gtsimulation.Interaction package

Submodules

gtsimulation.Interaction.G4functions.G4Decay(PDG, E)[source]

The function calls executable binary program that simulate decay of unstable particle and outputs information about products.

Parameters:

  • PDG (int) – Particle PDG code

  • E (float) – Kinetic energy of the particle [MeV]

Returns:

secondary

  • Name - Name

  • PDGcode - PDG encoding

  • Mass - Mass [MeV]

  • Charge - Charge

  • KineticEnergy - Kinetic energy of the particle [MeV]

  • MomentumDirection - Direction of the velocity of the particle [unit vector]

Return type:

structured ndarray

Examples

secondary = G4Decay(2112, 1)        # n -> p + e- + anti_nu_e

secondary = G4Decay(-2112, 1)       # anti_n -> anti_p + e+ + nu_e

secondary = G4Decay(211, 1)         # pi+ -> mu+ + nu_mu

secondary = G4Decay(13, 1)          # mu- -> e- + anti_nu_e + nu_mu

secondary = G4Decay(1000060140, 1)  # C14 -> N14 + e- + anti_nu_e

secondary = G4Decay(1000922380, 1)  # U238 -> Th234 + alpha

secondary = G4Decay(2212, 1)        # p is stable

gtsimulation.Interaction.G4functions.G4Interaction(PDG, E, m, rho, element_name, element_abundance)[source]

The function calls executable binary program that calculate interaction of the charge particle with matter at a given path length and outputs information about secondary particles.

For this we simulate a cylinder filled with matter with a density rho. Cylinder length is calculated as l = m / rho. The radius of the cylinder R is equal to its length l. The initial coordinate of the particle is (0, 0, 0). The initial velocity is directed along the cylinder axis, which coincides with the Z axis. The simulation stops when the primary particle has died or reached the boundary of the cylinder.

Parameters:

  • PDG (int) – Particle PDG code

  • E (float) – Kinetic energy of the particle [MeV]

  • m (float) – Path of a particle in [g/cm^2]

  • rho (float) – Density of medium [g/cm^3]

  • element_name (list) – List of chemical elements that make up the medium

  • element_abundance (array_like) – Medium composition, sum must be equal 1

Returns:

primary

  • Name - Name

  • PDGcode - PDG encoding

  • Mass - Mass [MeV]

  • Charge - Charge

  • KineticEnergy - Kinetic energy of the particle [MeV]

  • MomentumDirection - Direction of the velocity of the particle [unit vector]

  • Position - Coordinates of the primary particle [m]

  • LastProcess - Name of the last process in which the primary particle participated (usually ‘Transportation’ or ‘…Inelastic’)

Return type:

structured ndarray

gtsimulation.Interaction.G4functions.G4Shower(PDG, E, r, v, date)[source]

The function calls executable binary program that calculates interaction of the charged particle with the Earth’s atmosphere and outputs information about secondary (albedo) particles.

The program creates a spherical layer with a thickness of 80 + 0.5 km, which is divided into layers with a thickness of 1 km. The air density for each layer is assumed to be constant and is calculated using the atmospheric model NRLMSISE-00. All calculations are carried out in the GEO coordinate system.

Parameters:

  • PDG (int) – Particle PDG code

  • E (float) – Kinetic energy of the particle [MeV]

  • r (float array) – Coordinates of the primary particle in GEO [m]

  • v (float array) – Velocity of the primary particle in GEO [unit vector]

  • date (datetime) – Current datetime

Returns:

primary

  • Name - Name

  • PDGcode - PDG encoding

  • Mass - Mass [MeV]

  • Charge - Charge

  • PositionInteraction - Coordinates of the interaction of the primary particle [m]

  • LastProcess - Name of the last process in which the primary particle participated

secondary

  • Name - Name

  • PDGcode - PDG encoding

  • Mass - Mass [MeV]

  • Charge - Charge

  • Position - Coordinates of the secondary (albedo) particle in GEO [m]

  • MomentumDirection - Direction of the velocity of the particle in GEO [unit vector]

  • KineticEnergy - Kinetic energy of the particle [MeV]

  • VertexPosition - Coordinates of the secondary (albedo) particle in GEO at the birth point [m]

  • VertexMomentumDirection - Direction of the velocity of the particle in GEO at the birth point [unit vector]

  • VertexKineticEnergy - Kinetic energy of the particle at the birth point [MeV]

Rtype primary:

structured ndarray

Rtype secondary:

structured ndarray

Examples:

primary, secondary = G4Shower(2212, 10e3, [6378137 + 80000, 0, 0], [-1, 0, 1], datetime(2020, 1, 1)

primary, secondary = G4Shower(1000020040, 20e3, [0, 0, 6356752 + 60000], [0, 1, -2], datetime(2014, 1, 1)

class gtsimulation.Interaction.GenSynchCounter.SynchCounter[source]

Bases: object

add_iteration(T, B, V, dt)[source]
get_averages()[source]
print()[source]
reset()[source]
gtsimulation.Interaction.GenSynchCounter.get_alpha(B, V)[source]
gtsimulation.Interaction.GenSynchCounter.get_norm_B_perp(B, V)[source]
gtsimulation.Interaction.RadLossStep.MakeRadLossStep(Vp, Vm, Yp, Ya, M, Q, rm, dt, frwdTracing, sync_params, particle, Gen, Constants, synch_record: SynchCounter)[source]

11.10.2024 Функция SynchrotronEmission выполняет расчет энергий фотонов, испускаемых заряженной частицей (T_e_MeV, m, Z) за временной промежуток delta_t, движущейся в магнитном поле B под углом alpha. Фотоны испускаются вдоль направления движения частицы. INPUT

delta_t - sec - временной промежуток, за который частица испускает излучение T_e_MeV - MeV - кинетическая энергия частицы B - Tesla - средняя индукция магнитного поля, в котором находится частица за delta_t alpha - radians - средний угол между магнитным полем и скоростью частицы за delta_t m - kg - масса частицы Z - units - зарядовое число частицы

OUTPUT

E_keV_photons - keV - ndarray - массив энергий испускаемых фотонов

gtsimulation.Interaction.SynchrotronEmission.MakeSynchrotronEmission(delta_t, T_MeV, Bsina, M, Z)[source]
gtsimulation.Interaction.SynchrotronEmission.get_N_avg(B_perp, delta_t, M, Z)[source]

Geant4 Matter Layer Simulator

class gtsimulation.Interaction.matter_layer.ParticleData

Bases: pybind11_object

property charge
property kineticEnergy
property lastProcess
property mass
property momentumDirection
property name
property pdgCode
property position
class gtsimulation.Interaction.matter_layer.RunResult

Bases: pybind11_object

property primary
property secondaries
class gtsimulation.Interaction.matter_layer.Simulator

Bases: pybind11_object

property material_count
run(self: gtsimulation.Interaction.matter_layer.Simulator, pdg: SupportsInt, energy: SupportsFloat, mass: SupportsFloat, density: SupportsFloat, element_name: collections.abc.Sequence[str], element_abundance: collections.abc.Sequence[SupportsFloat]) → gtsimulation.Interaction.matter_layer.RunResult

Run one event with given parameters

class gtsimulation.Interaction.nuclear_interaction.NuclearInteraction(max_generations: int = 1, grammage_threshold: float = 10.0, seed: int = None, restart_limit: int = 20)[source]

Bases: object

Geant4-backed nuclear interaction simulator with optional process restarts.

This class wraps a Geant4 simulation that propagates a single charged particle through a homogeneous material layer and returns the final primary particle state and the list of produced secondary particles.

The simulation is executed in an isolated multiprocessing.Process. This makes it possible to fully reset Geant4 state by restarting the worker process when needed.

Performance note: restarting the worker is mainly useful when the medium is frequently updated (e.g., many unique material compositions/densities over time). In that scenario, Geant4 internal tables may grow and recalculations for previously used (now irrelevant) materials can slow down subsequent runs, so periodic restarts can keep performance stable.

If you keep using the same material configuration for many runs, restarts are usually unnecessary; the worker can stay alive and repeated calls are significantly faster.

The target geometry is a cylinder filled with a user-defined material mixture:

  • Cylinder length is computed as thickness = mass / density / 1e2 [m].

  • Cylinder radius equals its length.

  • The primary particle starts at (0, 0, 0) and travels along the +Z axis.

  • Tracking stops when the primary particle dies or reaches the cylinder boundary.

Internally, the C++ result object is converted to structured NumPy arrays with the dtypes PRIMARY_DTYPE and SECONDARY_DTYPE.

Parameters

max_generationsint, default=1

Maximum number of secondary particle generations to model in the simulation.

grammage_thresholdfloat, default=10.

Grammage threshold [g/cm²] above which the Geant4 subroutine is triggered. Should be set as a fraction of the expected nuclear interaction length in the material.

seedint

Random seed used to initialize the Geant4 simulator inside the worker process.

restart_limitint, default=20

Number of runs after which the worker process is restarted automatically.

run_matter_layer(pdg: int, energy: float, mass: float, density: float, element_name: list[str], element_abundance: list[float])[source]

Simulate interaction of a charged particle with a homogeneous material layer.

Parameters

pdgint

PDG code of the primary particle.

energyfloat

Primary particle kinetic energy in MeV.

massfloat

Traversed mass thickness in g/cm^2.

densityfloat

Medium density in g/cm^3.

element_namelist of str

Chemical element symbols (e.g. ["N", "O"]) forming the medium.

element_abundancelist of float

Mass fractions (or the fractions expected by your Geant4 material definition); the sum should be 1.

Returns

primarynumpy.ndarray

Structured NumPy array of shape (1,) with dtype PRIMARY_DTYPE. Fields:

  • Name : str

  • PDGcode : int

  • Mass : float, MeV

  • Charge : int

  • KineticEnergy : float, MeV

  • MomentumDirection : (3,) float, unit vector

  • Position : (3,) float, m

  • LastProcess : str

secondarynumpy.ndarray

Structured NumPy array with dtype SECONDARY_DTYPE and shape (N,), where N is the number of secondary particles (may be 0). Fields:

  • Name : str

  • PDGcode : int

  • Mass : float, MeV

  • Charge : int

  • KineticEnergy : float, MeV

  • MomentumDirection : (3,) float, unit vector

gtsimulation.Interaction.nuclear_interaction.convert_to_numpy(run_result)[source]

Convert C++ Geant4 result object to structured NumPy arrays.

Parameters

run_resultmatter_layer.RunResult

C++ result object returned by the Geant4 simulator.

Returns

primarynumpy.ndarray

Structured array of shape (1,) with dtype PRIMARY_DTYPE containing the final state of the primary particle.

secondarynumpy.ndarray

Structured array of shape (N,) with dtype SECONDARY_DTYPE containing secondary particles produced during the interaction (empty if N=0).

Notes

This is an internal utility function used by the multiprocessing worker to ensure efficient serialization of complex C++ objects across process boundaries.

gtsimulation.Interaction.nuclear_interaction.sim_worker(input_queue, output_queue, seed)[source]

Geant4 worker process loop.

Runs in an isolated process and owns a single matter_layer.Simulator instance. Receives simulation parameters via input_queue, executes events, and returns results via output_queue. Automatically terminates when receiving None.

Parameters

input_queuemultiprocessing.Queue

Input queue containing parameter tuples: (pdg, energy, mass, density, el_names, el_fracs).

output_queuemultiprocessing.Queue

Output queue for results: (primary_array, secondary_array, material_count).

seedint

Random seed passed to the Geant4 simulator constructor.

Notes

Internal worker function for NuclearInteraction. Not intended for direct use. The worker process is restarted periodically to control Geant4 memory growth.

Module contents