Getting Started
===============

Welcome to Pulsar Digital Twin :pulsardt:`PulsarDT++`! python package Version. This package in its current form provides a digital twin/animation of a Pulsar. Using this package a user can design a pulsar source with a customized radio emission pattern or sparks. In addition specific physics such as spectral emission profile associated with each sparks can also be modelled. The sparks can also have their own drift velocity. At its present form a method is provided to make sparks arranged in nested cone pattern. A pipeline is also provided to generate random frequency-time graphs containing Pulsar+NBRFI+BBRFI dataframes which will be used to train neural network models to detect pulsars from radio data streams generated from radio-telescopes like MeerKAT.

Installation
------------

You can install PulsarDT from the Git repository as:

.. code-block:: bash

   git clone https://gitlab.dzastro.de/punch/ml-ppa/pulsardtpp.git
   cd pulsardtpp
   python -m venv .venv
   source .venv/bin/activate
   pip install uv
   uv pip install .


Example Hello World
-------------------

Here is how to use **PulsarDT** in a simple script:

.. code-block:: python

   import numpy as np
   import pulsardtpp.defines as defines
   from pulsardtpp import PulsarAnimator 
   from pulsardtpp import create_pulsar_animation

   pulsar_animator = PulsarAnimator(rot_axis=[0,0,1],mag_axis_tilt=45)
   create_pulsar_animation(
                        pulsar_animator=pulsar_animator,
                        animation_folder_path='./output/anims/',
                        tag='test_spark',
                        telescope_direction=(1,0,1),
                        rot_phases=np.arange(0, 360, 30),
                        res=60
                        ) 

The following GIF shows an example animation created by stacking the frames generated by the above code:

.. image:: /static/state_vector_multi_perspective_new.gif
   :alt: PulsarDT Demo
   :width: 600px