tardis.energy_input.gamma_ray_packet_source module

class tardis.energy_input.gamma_ray_packet_source.GammaRayPacketSource(cumulative_decays_df: DataFrame, isotope_decay_df: DataFrame, positronium_fraction: float, inner_velocities: ndarray, outer_velocities: ndarray, times: ndarray, effective_times: ndarray, **kwargs)

Bases: BasePacketSource

Initialize gamma ray packet source.

Initializes a gamma ray packet source for creating gamma ray packets from radioactive decay data, including support for positronium formation.

Parameters:

cumulative_decays_dfpd.DataFrame

DataFrame containing cumulative decay data with columns including radiation type, decay energies, and multi-level indices for isotope, shell_number, and time_index.

isotope_decay_dfpd.DataFrame

DataFrame containing isotope decay data with decay constants and other isotope-specific parameters.

positronium_fractionfloat

Fraction of positrons that form positronium (0.0 to 1.0). Used for modeling three-photon decay vs two-photon annihilation.

inner_velocitiesnp.ndarray

Array of inner shell velocities [cm/s] for each spatial shell.

outer_velocitiesnp.ndarray

Array of outer shell velocities [cm/s] for each spatial shell.

timesnp.ndarray

Array of time steps [s] used in the simulation.

effective_timesnp.ndarray

Array of effective time steps [s] accounting for simulation specifics.

**kwargs

Additional keyword arguments passed to the parent BasePacketSource class.

Notes

This packet source generates gamma ray packets from radioactive decay events, with proper handling of: - Spatial distribution within shells - Time-dependent decay processes - Positronium formation and decay modes - Doppler effects from moving material

create_packet_directions(no_of_packets: int, seed: int | None) → ndarray

Create random isotropic directions for packets.

Generates an array of random unit vectors representing isotropic directions for gamma ray packets.

Parameters:

no_of_packetsint

Number of packets to generate directions for.

seedint or None

Random seed for reproducible direction generation. If None, uses current random state.

Returns:

np.ndarray

Array of shape (3, no_of_packets) containing unit direction vectors. Each column represents a 3D unit vector [x, y, z].

Notes

Directions are sampled uniformly on the unit sphere to ensure isotropic distribution in 3D space.

create_packet_energies(no_of_packets: int, energy: float) → ndarray

Create uniform packet energies for gamma ray packets.

Generates an array of identical packet energies for a specified number of packets.

Parameters:

no_of_packetsint

Number of packets to create energies for.

energyfloat

Energy value [erg] to assign to each packet.

Returns:

np.ndarray

Array of packet energies [erg] with length no_of_packets, where each element equals the input energy value.

Notes

This method creates uniform energy packets, where each packet carries the same energy regardless of the specific gamma ray line that created it. The total energy is conserved through the packet weighting system.

create_packet_mus(no_of_packets: int, *args, **kwargs)

Create packet directional cosines.

Creates packet directional cosines by calling the parent class method. This method is inherited from BasePacketSource.

Parameters:

no_of_packetsint

Number of packets for which to create directional cosines.

*args

Variable length argument list passed to parent method.

**kwargs

Arbitrary keyword arguments passed to parent method.

Returns:

The return value from the parent class create_packet_mus method.

create_packet_nus(packets: DataFrame, positronium_fraction: float, number_of_packets: int) → ndarray

Create packet frequency-energies accounting for positronium formation.

Generates an array of packet frequency-energies (E = h * nu) considering positronium formation and its decay modes for positron annihilation lines.

Parameters:

packetspd.DataFrame

DataFrame containing packet information with ‘radiation_energy_keV’ column.

positronium_fractionfloat

Fraction of positrons that form positronium (0.0 to 1.0). Default is 0.0 for no positronium formation.

number_of_packetsint

Number of packets to generate frequency-energies for.

Returns:

np.ndarray

Array of sampled frequency-energies [keV] with length number_of_packets.

Notes

For positron annihilation lines (511 keV), this method: - Determines if positronium forms based on positronium_fraction - For ortho-positronium: samples from 3-photon decay spectrum - For para-positronium: uses the 511 keV line energy - For direct annihilation: uses the original 511 keV energy

The para/ortho ratio is set by PARA_TO_ORTHO_RATIO constant (0.25).

create_packet_times_uniform_energy(no_of_packets: ndarray, isotopes: Series, decay_time: ndarray) → ndarray

Sample decay times from isotope mean lifetimes using rejection sampling.

Generates decay times by sampling from exponential distributions based on isotope mean lifetimes, constrained to specific time intervals.

Parameters:

no_of_packetsnp.ndarray

Array indices for the packets (used for iteration).

isotopespd.Series

Series containing parent isotope names for each packet.

decay_timenp.ndarray

Array of time step indices indicating the time interval for each packet’s decay.

Returns:

np.ndarray

Array of decay times [s] sampled from exponential distributions constrained to the appropriate time intervals.

Notes

This method uses rejection sampling to ensure decay times fall within the correct time bins. For each packet: 1. Determines the time interval [t_min, t_max] from decay_time index 2. Samples from exponential distribution: t = -tau * ln(random) 3. Rejects and resamples if t is outside the interval

Requires self.taus attribute containing isotope mean lifetimes.

create_packet_times_uniform_time(no_of_packets: int, start: float, end: float) → ndarray

Sample packet decay times uniformly within a time interval.

Generates decay times uniformly distributed between start and end times. This approach requires non-uniform packet energies to maintain energy conservation.

Parameters:

no_of_packetsint

Number of packets to generate decay times for.

startfloat

Start time [s] of the sampling interval.

endfloat

End time [s] of the sampling interval.

Returns:

np.ndarray

Array of decay times [s] with length no_of_packets, uniformly distributed between start and end.

Notes

This method samples decay times uniformly in time, which means the packet energies must be weighted according to the decay rate at each time to properly represent the physical decay process.

create_packet_velocities(sampled_packets_df: DataFrame) → ndarray

Initialize random radial velocities for packets within shells.

Generates random initial velocities for packets distributed within spherical shells using a uniform distribution in volume.

Parameters:

sampled_packets_dfpd.DataFrame

DataFrame where each row represents a packet, containing ‘inner_velocity’ and ‘outer_velocity’ columns for shell boundaries.

Returns:

np.ndarray

Array of initial velocities [cm/s] with length equal to the number of packets in sampled_packets_df.

Notes

Uses the cube root method to ensure uniform distribution in volume: r^3 = z * r_inner^3 + (1-z) * r_outer^3, where z is uniform random [0,1].

create_packets(cumulative_decays_df: DataFrame, number_of_packets: int, legacy_energy_per_packet: float | None = None) → GXPacketCollection

Initialize a collection of gamma ray packets for simulation.

Creates a collection of gamma ray packets from radioactive decay data, including proper spatial distribution, directional sampling, energy assignment, and Doppler corrections.

Parameters:

cumulative_decays_dfpd.DataFrame

DataFrame containing cumulative decay data with columns including ‘radiation’, ‘decay_energy_erg’, and multi-level index with ‘isotope’, ‘shell_number’, and ‘time_index’.

number_of_packetsint

Total number of gamma ray packets to create for the simulation.

legacy_energy_per_packetfloat, optional

Legacy energy per packet [erg] for backwards compatibility. If None, energy per packet is calculated from total gamma ray energy divided by number of packets. Default is None.

Returns:

GXPacketCollection

Collection of gamma ray packets with initialized properties: - locations: 3D positions in the simulation domain - directions: isotropic unit direction vectors - energies: rest frame and comoving frame energies - frequencies: rest frame and comoving frame frequencies - metadata: shell numbers, decay times, source isotopes

Notes

The packet creation process includes:

1. Energy calculation: Total gamma ray energy is divided equally among packets (uniform energy approach)

2. Spatial sampling: Packets are distributed within shells based on decay energy weighting

3. Temporal placement: Packets are positioned at decay times with appropriate radial expansion

4. Spectral sampling: Frequencies include positronium formation effects for 511 keV annihilation lines

5. Doppler corrections: Applied for relativistic motion between rest and comoving frames

The method ensures energy conservation while providing proper statistical sampling of the decay process.

tardis.energy_input.gamma_ray_packet_source.legacy_calculate_positron_fraction(isotope_decay_df: DataFrame, isotopes: ndarray, number_of_packets: int) → ndarray

Calculate positron kinetic energy fraction relative to gamma ray energy.

Computes the fraction of energy released as positron kinetic energy compared to gamma ray energy for each isotope associated with packets.

Parameters:

isotope_decay_dfpd.DataFrame

DataFrame containing isotope decay data with multi-level index including ‘isotope’ and ‘shell_number’, and columns including ‘radiation’, ‘energy_per_channel_keV’.

isotopesnp.ndarray

Array of isotope names as strings, where each isotope is associated with a packet.

number_of_packetsint

Total number of gamma ray packets in the simulation.

Returns:

np.ndarray

Array of positron energy fractions with length number_of_packets. Each element represents the ratio of positron kinetic energy to gamma ray energy for the corresponding packet’s source isotope.

Notes

This function:

1. Filters decay data for shell_number == 0 to avoid double counting

2. Separates gamma ray (‘g’) and beta plus (‘bp’) radiation channels

3. Sums energy per isotope for each radiation type

4. Calculates fraction = E_positron / E_gamma for each isotope

5. Maps isotope fractions to packet array

Isotopes not present in the decay DataFrame receive a fraction of 0.0. This is used for legacy compatibility and may be deprecated in favor of more sophisticated positron energy modeling.