Pulsar Simulation

class antenna
#include <antenna.hpp>

Digital twin model of a radio antenna.

The antenna class simulates how a real-world radio antenna would interact with incoming astronomical signals, particularly those from pulsars. It also includes the ability to inject noise representative of narrow-band and broad-band radio frequency interference (RFI), and to compute antenna output voltages and temperature.

Public Functions

antenna(payload &cargo, double sensitivity = 0.1, double prob_nbrfi = 1., double prob_bbrfi = 1.)

Constructs an antenna model initialized from a data payload.

Parameters:

  • cargo – The signal payload to initialize the antenna with (frequencies, data, rotation phases).

  • sensitivity – Antenna sensitivity level (default is 0.1).

  • prob_nbrfi – Probability of narrow-band RFI being injected (default is 1.0).

  • prob_bbrfi – Probability of broad-band RFI being injected (default is 1.0).

Eigen::MatrixXd calculate_antenna_output_voltage_matrix(const Eigen::MatrixXd &received_flux)

Calculates the output voltage matrix of the antenna given received flux data.

Parameters:

received_flux – The input flux matrix (e.g., from a pulsar or simulated environment).

Returns:

A matrix representing the antenna output voltage at each time-frequency point.

Eigen::MatrixXd gen_noise_NBRFI(double effected_freq_channel, double nbrfi_amplitude = 1.0, double spread_in_channels = 0.5)

Generates narrow-band RFI (NBRFI) noise centered on a specific frequency channel.

Parameters:

  • effected_freq_channel – The central frequency channel affected by NBRFI.

  • nbrfi_amplitude – Amplitude of the narrow-band RFI (default is 1.0).

  • spread_in_channels – Gaussian spread of RFI across adjacent channels (default is 0.5).

Returns:

A noise matrix with narrow-band RFI.

Eigen::MatrixXd gen_noise_BBRFI(double effected_rot_phase, double bbrfi_amplitude = 1.0, double spread_in_phase = 10.0)

Generates broad-band RFI (BBRFI) noise affecting a specific rotational phase.

Parameters:

  • effected_rot_phase – The rotational phase most affected by BBRFI.

  • bbrfi_amplitude – Amplitude of the broad-band RFI (default is 1.0).

  • spread_in_phase – Temporal spread (in rotational phase units) of the RFI (default is 10.0).

Returns:

A noise matrix with broad-band RFI.

double antenna_temperature(double received_flux)

Calculates the antenna temperature for a given received flux.

Parameters:

received_flux – A scalar flux value.

Returns:

Antenna temperature in arbitrary units.

Eigen::MatrixXd gen_terresterial_noise(double effected_freq_channel_by_nbrfi, double nbrfi_bandwidth, double effected_rot_phase_by_bbrfi, double bbrfi_duration, const std::vector<double> &noise_amplitude_range)

Generates terrestrial noise by combining both NBRFI and BBRFI components.

Parameters:

  • effected_freq_channel_by_nbrfi – Central frequency affected by NBRFI.

  • nbrfi_bandwidth – Bandwidth (spread) of NBRFI.

  • effected_rot_phase_by_bbrfi – Central rotational phase affected by BBRFI.

  • bbrfi_duration – Duration/spread of BBRFI in phase units.

  • noise_amplitude_range – Range of possible amplitudes for the noise [min, max].

Returns:

A matrix containing the combined terrestrial noise.

std::pair<Eigen::MatrixXd, Eigen::MatrixXd> randomize_antenna_output()

Randomizes the antenna’s output by optionally injecting noise events.

This method may add narrow-band or broad-band RFI based on predefined probabilities.

Returns:

A pair of matrices:

  • The randomized antenna output (flux + noise).

  • A matrix containing just the injected noise component.

void is_pulsar_present()

Checks if a pulsar is present in the current signal and updates counters accordingly.

Public Members

int nbrfi_count = 0
int bbrfi_count = 0
int pulsar_count = 0

Private Members

std::vector<double> freq_channels
std::vector<double> rot_phases
Eigen::MatrixXd dataframe
double sensitivity
double prob_nbrfi
double prob_bbrfi
class data_generator
#include <data_generator.hpp>

Class responsible for generating synthetic pulsar data using spark pattern models and noise injection.

The data_generator class is used to simulate observational data of pulsars, including spark patterns and various interferences, through the use of a pulsar_animator and antenna model. It supports realistic modeling of pulsar emissions, propagation effects, and instrumentation noise.

Public Functions

data_generator(pulsar_animator anim = pulsar_animator())

Constructs a data generator with an optional custom pulsar animator.

Parameters:

anim – An optional pulsar animator instance (defaults to a default-constructed one).

std::pair<Eigen::MatrixXd, Eigen::MatrixXd> generate_data_spark_pattern(const std::vector<double> &rot_phases, std::vector<double> freq_channel, std::string tag = "test", double signal_time_bin = 0.09166, const std::string &param_folder = "./params/runtime/", const std::string &payload_folder = "./params/payloads/", double antenna_sensitivity = 0.5, double prob_nbrfi = 0.5, double prob_bbrfi = 0.5, double scale_direction_randomness = 0.5, bool remove_drift_effect = true, bool randomize = true, const std::vector<shared_ptr<spark_pattern_generator::spark>> &init_spark_list = std::vector<shared_ptr<spark_pattern_generator::spark>>{})

Generates observational data from a pulsar using a spark pattern model.

This function simulates the entire signal pipeline, including pulsar signal generation, interstellar effects, antenna response, and noise injection.

Parameters:

  • rot_phases – Vector of rotational phases (time samples).

  • freq_channel – Frequency channels of observation.

  • tag – Optional label/tag for saving parameter and payload files (default: “test”).

  • signal_time_bin – Duration of each time bin in seconds (default: 0.09166).

  • param_folder – Path to the folder where runtime parameters will be saved.

  • payload_folder – Path to the folder where payload data will be saved.

  • antenna_sensitivity – Sensitivity of the antenna model (default: 0.5).

  • prob_nbrfi – Probability of injecting narrow-band RFI (default: 0.5).

  • prob_bbrfi – Probability of injecting broad-band RFI (default: 0.5).

  • scale_direction_randomness – Factor controlling direction vector randomness (default: 0.5).

  • remove_drift_effect – Whether to remove the drift effect in simulation (default: true).

  • randomize – Whether to randomize the output with noise (default: true).

  • init_spark_list – Optional list of initial spark objects to override default random spark generation.

Returns:

A pair of Eigen matrices: simulated signal matrix and corresponding noise matrix.

std::vector<shared_ptr<spark_pattern_generator::spark>> generate_random_spark_pattern(aggregated_payload &aggregate, int num_cones = 2, double avg_spark_dimension = 7.0, float avg_spark_per_cone_length = .05, double avg_spark_pattern_center_tilt = 45.0, double avg_drift_vel = 1.)

Randomly generates a list of sparks representing a pulsar’s emission pattern.

Parameters:

  • aggregate – Reference to the aggregated payload storing runtime parameters.

  • num_cones – Number of spark cones (default: 2).

  • avg_spark_dimension – Average angular width of individual sparks (default: 7.0).

  • avg_spark_per_cone_length – Average spark density per cone arc length (default: 0.05).

  • avg_spark_pattern_center_tilt – Average tilt of spark pattern in degrees (default: 45.0).

  • avg_drift_vel – Average angular drift velocity of sparks (default: 1.0).

Returns:

A vector of shared pointers to the generated sparks.

payload generate_payload_at_acquisition_frequency(const payload &payload_raw) const

Applies a simulated acquisition filter to a raw pulsar payload.

This models the transformation of the signal by an observational receiver operating at a specific acquisition frequency.

Parameters:

payload_raw – The raw input signal payload.

Returns:

A processed payload modified to represent signal as acquired by instrumentation.

interstellar_medium generate_random_ism_obj(aggregated_payload &aggregate)

Generates a randomized interstellar medium (ISM) object.

This function synthesizes ISM effects such as dispersion and scintillation to apply to the aggregated signal.

Parameters:

aggregate – Aggregated payload holding signal and runtime data.

Returns:

A randomized interstellar_medium object.

void randomize_existing_spark_pattern(aggregated_payload &aggregate)

Randomizes an existing spark pattern in a given aggregated payload.

This allows for modifying an existing configuration, useful for re-simulation or perturbation studies.

Parameters:

aggregate – Reference to the payload whose spark pattern will be randomized.

Public Members

pulsar_animator animator
std::vector<double> freq_channels
class interstellar_medium
#include <interstellar_medium.hpp>

Models the effect of the interstellar medium (ISM) on pulsar signals.

The interstellar_medium class simulates both deterministic and stochastic effects of the ISM, including dispersion and scintillation, which alter the received pulsar signal.

Public Functions

interstellar_medium(double std_dm = 0.02, double std_scintillation_index = 100, double scintillation_index_homogeneous = 1., double dm_homogeneous = 2.643)

Constructs an interstellar_medium object with optional parameters.

Parameters:

  • std_dm – Standard deviation of dispersion measure variations (default: 0.02).

  • std_scintillation_index – Standard deviation of scintillation index variations (default: 100).

  • scintillation_index_homogeneous – Baseline scintillation index (default: 1.0).

  • dm_homogeneous – Baseline dispersion measure in pc/cm³ (default: 2.643).

double calc_disperse_phase_shift(double freq, double freq_ref = 1., double signal_time_bin = 1.) const

Calculates the dispersion-induced phase shift for a given frequency.

This models the frequency-dependent delay in arrival time caused by the ISM dispersion.

Parameters:

  • freq – Observing frequency in GHz.

  • freq_ref – Reference frequency in GHz (default: 1.0).

  • signal_time_bin – Time resolution of the signal in seconds (default: 1.0).

Returns:

Phase shift (in number of bins) due to dispersion.

void randomize_props()

Randomizes the dispersion and scintillation properties using the defined standard deviations.

This introduces stochastic behavior in dispersion and scintillation to simulate temporal variability.

payload propagate_through(payload payload, double signal_time_bin, bool average_over_period = true)

Simulates the propagation of a pulsar signal through the interstellar medium.

This function modifies the input payload by applying dispersion and scintillation effects.

Parameters:

  • payload – The input signal payload.

  • signal_time_bin – Time resolution of the signal in seconds.

  • average_over_period – Whether to average over the pulsar period during propagation (default: true).

Returns:

A modified payload containing the signal after ISM propagation.

Public Members

double std_dm
double std_scintillation_index
double scintillation_index_homogeneous
double dm_homogeneous
class pulsar_animator
#include <pulsar_animator.hpp>

Animates a pulsar rotator as observed from Earth.

This class models the rotation of a pulsar in the Earth’s celestial coordinate system. It manages pulsar rotation axis, magnetic axis tilt, and spark emission patterns, allowing simulation of radio signal generation as a function of pulsar rotation phase.

Public Functions

pulsar_animator(const Eigen::Vector3d &rot_axis = {0, 0, 1}, double mag_axis_tilt = 45.)

Constructs a pulsar_animator object.

Parameters:

  • rot_axis – Initial rotation axis vector (default is unit vector along z-axis).

  • mag_axis_tilt – Magnetic axis tilt angle in degrees (default is 45°).

void add_spark(std::vector<shared_ptr<spark_pattern_generator::spark>> spark_gen)

Adds spark generators to the pulsar animator.

Parameters:

spark_gen – Vector of shared pointers to spark generators to be added.

std::vector<Eigen::Vector3d> operator()(double rot_phase)

Computes the pulsar state vectors for a given rotation phase.

Parameters:

rot_phase – Rotation phase (in radians or degrees, as per implementation).

Returns:

Vector of Eigen::Vector3d representing pulsar frame basis at the given phase.

void update_pulsar_state_vectors(double rot_phase)

Updates internal pulsar state vectors based on the current rotation phase.

Parameters:

rot_phase – Current rotation phase.

std::pair<std::vector<double>, std::vector<double>> generate_radio_packet(double rot_phase, const Eigen::Vector3d &direction)

Generates a radio signal packet based on rotation phase and direction.

Parameters:

  • rot_phase – Rotation phase of the pulsar.

  • direction – Direction vector in which the radio signal is observed.

Returns:

Pair of vectors containing frequency channels and corresponding flux values.

payload generate_radio_packet_stream(const std::vector<double> &rot_phases, aggregated_payload &aggregate, const double &scale_direction_randomness = 0.5)

Generates a stream of radio packets across multiple rotation phases.

Parameters:

  • rot_phases – Vector of rotation phases to simulate.

  • aggregate – Aggregated payload object to store the generated data.

  • scale_direction_randomness – Scaling factor for randomness in direction (default 0.5).

Returns:

Payload object containing the generated radio packet stream.

Public Members

Eigen::Vector3d __rot_axis
double __mag_axis_tilt
std::vector<Eigen::Vector3d> mag_frame_basis_att0
std::vector<Eigen::Vector3d> rot_frame_basis
std::vector<Eigen::Vector3d> mag_frame_basis
std::vector<shared_ptr<spark_pattern_generator::spark>> spark_genlist
std::vector<spark_pattern_generator::spark_spectral_model> spark_spectrum_model_list

Public Static Functions

static std::pair<Eigen::Vector3d, Eigen::Vector3d> find_perpendicular_basis_vectors(const Eigen::Vector3d &vector)

Finds two perpendicular basis vectors orthogonal to a given vector.

Parameters:

vector – Input vector to which the returned basis vectors are perpendicular.

Returns:

A pair of Eigen::Vector3d vectors forming an orthonormal basis perpendicular to the input vector.

static std::pair<std::vector<double>, std::vector<double>> calculate_radio_packet_at_direction(std::vector<shared_ptr<spark_pattern_generator::spark>> &spark_patterns, const Eigen::Vector3d &direction, const std::vector<Eigen::Vector3d> &pulsar_rot_frame_basis, double rot_phase)

Calculates a radio packet at a specific direction given spark patterns and pulsar rotation basis.

Parameters:

  • spark_patterns – Vector of shared pointers to spark pattern objects.

  • direction – Direction vector of observation.

  • pulsar_rot_frame_basis – Pulsar rotation frame basis vectors.

  • rot_phase – Current rotation phase.

Returns:

Pair of vectors with frequency channels and corresponding flux.

Private Functions

std::vector<Eigen::Vector3d> rotate_reference_frame(const std::vector<Eigen::Vector3d> &frame_0_basis, const Eigen::Vector3d &axis_of_rotation, double rotation_angle)

Rotates a reference frame basis by a given rotation angle about an axis.

Parameters:

  • frame_0_basis – Initial basis vectors of the frame to rotate.

  • axis_of_rotation – Axis about which to rotate.

  • rotation_angle – Angle of rotation (radians or degrees).

Returns:

Rotated basis vectors as a vector of Eigen::Vector3d.

class spark_pattern_generator
#include <spark_pattern_generator.hpp>

Generates and manages spark emission patterns for pulsar simulations.

This class provides tools to create spark objects representing emission regions on pulsars, model their spectral characteristics, and build structured spark patterns.

Public Static Functions

static vector<shared_ptr<spark_pattern_generator::spark>> create_patterned_spark_pattern(const vector<int> &num_sparks, const vector<double> &conal_latitudes, const Eigen::Vector2d &spark_rotation_axis_polar_att0 = {45, 0}, const double drift_vel = (-10 / 360), const double spark_dimension = 0.3, const vector<double> &spark_mid_freqs = {}, const vector<double> &spark_flux_powers = {})

Creates a patterned spark pattern according to input parameters.

Generates a vector of shared pointers to spark objects arranged according to specified number of sparks, conal latitudes, rotation axes, drift velocity, dimension, mid frequencies, and flux powers.

Parameters:

  • num_sparks – Vector specifying number of sparks per cone.

  • conal_latitudes – Vector of latitudes defining cones.

  • spark_rotation_axis_polar_att0 – Polar coordinates for spark rotation axis (default {45,0}).

  • drift_vel – Drift velocity for sparks (default -10/360).

  • spark_dimension – Dimension of each spark (default 0.3).

  • spark_mid_freqs – Vector of mid frequencies for sparks.

  • spark_flux_powers – Vector of flux powers for sparks.

Returns:

Vector of shared pointers to created spark objects.

class spark
#include <spark_pattern_generator.hpp>

Represents an individual spark emission region on a pulsar.

A spark is characterized by spatial properties (position, size, rotation axis), drift velocity, emission frequency, and flux power. It includes methods to calculate its position and emission properties based on pulsar rotation phase and frame.

Public Functions

spark(int spark_id, int spark_cone_id, double spark_dimension, Eigen::Vector2d spark_center, Eigen::Vector2d spark_rotation_axis_polar_att0, double drift_vel, double drift_phase, double mid_freq, double flux_power)

Constructs a spark object with specified parameters.

Parameters:

  • spark_id – Unique spark identifier.

  • spark_cone_id – Cone ID this spark belongs to.

  • spark_dimension – Size of the spark.

  • spark_center – 2D polar coordinates of spark center.

  • spark_rotation_axis_polar_att0 – Polar coordinates of spark rotation axis.

  • drift_vel – Drift velocity (phase per unit time).

  • drift_phase – Current drift phase.

  • mid_freq – Central emission frequency.

  • flux_power – Emission flux power.

inline double get_spark_dimension() const
Returns:

The dimension (size) of the spark.

inline Eigen::Vector2d get_spark_center() const
Returns:

The center of the spark in polar coordinates.

inline void set_spark_center(double val, int idx)

Sets a component of the spark center.

Parameters:

  • val – New value to set.

  • idx – Index of the component (0 or 1).

inline Eigen::Vector2d get_spark_rotation_axis_polar_att0() const
Returns:

Spark rotation axis in polar coordinates.

inline void set_spark_rotation_axis_polar_att0(double theta, double phi)

Sets the spark rotation axis polar angles.

Parameters:

  • theta – Polar angle theta.

  • phi – Polar angle phi.

inline double get_drift_vel() const
Returns:

Current drift velocity of the spark.

inline void set_drift_vel(double new_drift_value)

Sets the drift velocity of the spark.

Parameters:

new_drift_value – New drift velocity value.

inline double get_mid_frequency() const
Returns:

Mid-frequency of the spark emission.

inline double get_flux_power() const
Returns:

Flux power of the spark.

inline double get_id() const
Returns:

Unique ID of the spark.

double apply_physics_model(const std::vector<Eigen::Vector3d> &pulsar_rot_frame_basis, double pulsar_rot_phase, const Eigen::Vector3d &position)

Applies a physics model to compute spark flux at a given position and rotation phase.

Parameters:

  • pulsar_rot_frame_basis – Basis vectors of pulsar rotation frame.

  • pulsar_rot_phase – Current rotation phase of the pulsar.

  • position – 3D position vector to evaluate.

Returns:

Computed flux or intensity value.

Eigen::Vector3d calculate_spark_center_att(const std::vector<Eigen::Vector3d> &pulsar_rot_frame_basis, double pulsar_rot_phase)

Calculates the spark center position in the pulsar rotation frame at a given phase.

Parameters:

  • pulsar_rot_frame_basis – Pulsar rotation frame basis vectors.

  • pulsar_rot_phase – Rotation phase.

Returns:

3D vector representing spark center position.

std::vector<Eigen::Vector3d> calculate_magframe_basis_att(const std::vector<Eigen::Vector3d> &pulsar_rot_frame_basis, double pulsar_rot_phase)

Calculates magnetic frame basis vectors at a given rotation phase.

Parameters:

  • pulsar_rot_frame_basis – Pulsar rotation frame basis vectors.

  • pulsar_rot_phase – Rotation phase.

Returns:

Vector of 3D basis vectors in magnetic frame.

Public Members

double SPARK_RADIUS_THRESH_FACTOR = 5.0
int spark_id
int spark_cone_id = 0
double _spark_dimension = 0.1
Eigen::Vector2d _spark_center = {10., 0.}
Eigen::Vector2d _spark_rotation_axis_polar_att0 = {45., 0.}
double _drift_vel = -10. / 360.
double _drift_phase = 0.
double _mid_freq = 125
double _flux_power = 1.

Public Static Functions

static Eigen::Vector3d ortho_vector_parametric(double a, double b, double c, double parameter)

Computes a parametric vector orthogonal to a given plane defined by a, b, c.

Parameters:

  • a – Coefficient for x component.

  • b – Coefficient for y component.

  • c – Coefficient for z component.

  • parameter – Parameter along the parametric vector.

Returns:

Eigen::Vector3d Orthogonal vector computed.

static std::pair<Eigen::Vector3d, Eigen::Vector3d> find_perpendicular_basis_vectors(const Eigen::Vector3d &vector)

Finds two perpendicular basis vectors orthogonal to the input vector.

Parameters:

vector – Input 3D vector.

Returns:

Pair of orthonormal vectors perpendicular to input.

class spark_spectral_model
#include <spark_pattern_generator.hpp>

Models the spectral energy distribution of a spark.

This class computes the frequency-dependent emission intensity of a spark based on a spectral model defined by parameters like spectral index and curvature.

Public Functions

inline explicit spark_spectral_model(int model = 0)

Constructs a spark_spectral_model with the specified model type.

Parameters:

model – Model type identifier (default 0).

Eigen::VectorXd operator()(const double center_freq, const std::vector<double> frequencies) const

Calculates spectral intensity for a given center frequency over multiple frequencies.

Parameters:

  • center_freq – Central frequency around which model is calculated.

  • frequencies – Vector of frequencies to evaluate.

Returns:

Vector of spectral intensity values corresponding to input frequencies.

Public Members

int model
double spectral_index = -0.47
double b = 0.21
double curvature_parameter = 0.