gtsimulation.interaction.nuclear_interaction#
Functions
|
Run a single Geant4 atmosphere event. |
|
Convert C++ Geant4 atmosphere result object to structured NumPy arrays. |
|
Convert C++ Geant4 result object to structured NumPy arrays. |
|
Geant4 worker process loop. |
Classes
|
Geant4-backed nuclear interaction simulator with optional process restarts. |
- class gtsimulation.interaction.nuclear_interaction.NuclearInteraction(max_generations: int = 1, grammage_threshold: float = 10.0, seed: int = None, restart_limit: int = 20, atmosphere_height: float = 80000.0)[source]#
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_DTYPEandSECONDARY_DTYPE.The class also simulates air showers in the Earth’s atmosphere (
run_atmosphere). Each shower is computed in a separate short-lived process, since Geant4 can be initialized only once per process.- 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
Seed of the random generator that provides seeds for the Geant4 worker processes.
- restart_limitint, default=20
Number of runs after which the worker process is restarted automatically.
- atmosphere_heightfloat, default=80e3
Height of the atmosphere [m] simulated by
run_atmosphere. Must be a positive multiple of 1 km (thickness of one atmospheric layer).
- run_atmosphere(pdg: int, energy: float, r: ndarray, v: ndarray, date: datetime)[source]#
Simulate an air shower produced by a particle in the Earth’s atmosphere.
The atmosphere is a spherical layer of height
atmosphere_heightabove the local Earth radius, divided into 1 km layers. The density and composition of each layer are calculated with the NRLMSISE-00 model at the position of the particle. Under the atmosphere there is a 0.5 km layer of soil. All calculations are carried out in the GEO coordinate system.- Parameters:
- pdgint
PDG code of the primary particle.
- energyfloat
Primary particle kinetic energy in MeV.
- rnumpy.ndarray
Coordinates of the primary particle in GEO [m].
- vnumpy.ndarray
Direction of the primary particle velocity in GEO.
- datedatetime
Current date and time.
- Returns:
- primarynumpy.ndarray
Structured NumPy array with dtype
PRIMARY_DTYPE(final state of the primary particle, seerun_matter_layer).- secondarynumpy.ndarray
Structured NumPy array with dtype
ATMOSPHERE_SECONDARY_DTYPEand shape(N,), whereNis the number of secondary particles with kinetic energy above 1 MeV leaving the atmosphere upwards or the soil downwards (may be 0). Fields:Name: strPDGcode: intMass: float, MeVCharge: intPosition: (3,) float, m, GEOMomentumDirection: (3,) float, unit vector, GEOKineticEnergy: float, MeVVertexPosition: (3,) float, m, GEOVertexMomentumDirection: (3,) float, unit vector, GEOVertexKineticEnergy: float, MeV
- 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 of the elements, one per entry of
element_name; the sum must be 1.
- Returns:
- primarynumpy.ndarray
Structured NumPy array of shape
(1,)with dtypePRIMARY_DTYPE. Fields:Name: strPDGcode: intMass: float, MeVCharge: intKineticEnergy: float, MeVMomentumDirection: (3,) float, unit vectorPosition: (3,) float, mLastProcess: str
- secondarynumpy.ndarray
Structured NumPy array with dtype
SECONDARY_DTYPEand shape(N,), whereNis the number of secondary particles (may be 0). Fields:Name: strPDGcode: intMass: float, MeVCharge: intKineticEnergy: float, MeVMomentumDirection: (3,) float, unit vector
- Raises:
- ValueError
If
element_nameandelement_abundancediffer in length, or the abundances do not sum to 1.
- gtsimulation.interaction.nuclear_interaction.atmosphere_worker(params)[source]#
Run a single Geant4 atmosphere event.
Geant4 can be initialized only once per process, so this function must be executed in a fresh process for every call.
- Parameters:
- paramsdict
Keyword arguments for
atmosphere.run.
- Returns:
- primary, secondarynumpy.ndarray
Result converted by
convert_atmosphere_to_numpy.
Notes
Internal worker function for
NuclearInteraction. Not intended for direct use.
- gtsimulation.interaction.nuclear_interaction.convert_atmosphere_to_numpy(run_result)[source]#
Convert C++ Geant4 atmosphere result object to structured NumPy arrays.
- Parameters:
- run_resultatmosphere.RunResult
C++ result object returned by
atmosphere.run.
- Returns:
- primarynumpy.ndarray
Structured array with dtype
PRIMARY_DTYPEcontaining the final state of the primary particle.- secondarynumpy.ndarray
Structured array of shape
(N,)with dtypeATMOSPHERE_SECONDARY_DTYPEcontaining secondary particles leaving the atmosphere (empty ifN=0).
- 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 dtypePRIMARY_DTYPEcontaining the final state of the primary particle.- secondarynumpy.ndarray
Structured array of shape
(N,)with dtypeSECONDARY_DTYPEcontaining secondary particles produced during the interaction (empty ifN=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.Simulatorinstance. Receives simulation parameters viainput_queue, executes events, and returns results viaoutput_queue. Automatically terminates when receivingNone.- 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), or the exception raised by the simulator.- 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.