gtsimulation#

Particle transport simulation framework.

This package provides tools for simulating charged particle propagation in physical environments, including trajectory integration, electromagnetic fields, particle interactions, and medium descriptions.

Classes

GTSimulator(Particles, Num, Step[, Bfield, ...])

Main simulation class for particle trajectory calculation in various space environments.

class gtsimulation.GTSimulator(Particles: Flux, Num: int, Step: float, Bfield: AbsBfield | None = None, Efield: GeneralFieldE | None = None, Medium: GTGeneralMedium | None = None, Region: Regions = Regions.Undefined, BreakCondition: dict | list | None = None, UseDecay: bool = False, InteractNUC: NuclearInteraction | None = None, RadLosses: bool | list = False, Date: datetime = datetime.datetime(2008, 1, 1, 0, 0), Save: int | list = 1, Nfiles: int | list = 1, Output: str | None = None, Verbose: int = 1, ForwardTrck=None, TrackParams=False, ParticleOrigin=False, IsFirstRun=True)[source]#

Main simulation class for particle trajectory calculation in various space environments.

This abstract base class provides the core functionality for simulating particle trajectories, taking into account electromagnetic fields, particle interactions, and various physical processes.

Parameters:

Particles (Flux) – Particle flux generator defining initial spectrum, distribution and composition. See gtsimulation.particle.
Num (int) – Maximum number of simulation steps.
Step (float or dict) –
Time step configuration. If float: fixed time step in seconds. If dict: adaptive step configuration with keys:
- UseAdaptiveStep: bool – Enable adaptive stepping (default: False).
- InitialStep: float – Initial time step in seconds (used only if adaptive).
- MinLarmorRad: int – Minimum number of Larmor radii per step.
- MaxLarmorRad: int – The minimal number of points per Larmor radius.
- LarmorRad: int – The fixed number of points per Larmor radius (used when a fixed resolution is desired).
Bfield (AbsBfield or None, optional) – Magnetic field model object. If None, no magnetic field is applied. Default is None.
Efield (GeneralFieldE or None, optional) – Electric field model object. If None, no electric field is applied. Default is None.
Medium (GTGeneralMedium or None, optional) – Propagation medium for particles. Defines density and composition of the environment through which particles travel. Required when nuclear interactions are enabled (via InteractNUC parameter), but optional for simulations without interactions. See gtsimulation.medium. Default is None.
Region (Regions, optional) – Simulation region specifying the physical environment. Available options: Magnetosphere, Heliosphere, Galaxy. See gtsimulation.common.regions. Default is Regions.Undefined.
BreakCondition (dict or list or None, optional) – Simulation termination conditions. If dict: {condition: value}. If list format: [conditions_dict, center_point_array]. Available conditions: see BreakCode. Default is None.
UseDecay (bool, optional) – Enable particle decay processes. Default is False.
InteractNUC (NuclearInteraction or None, optional) – Nuclear interaction module. Requires Medium to be set. Default is None.
RadLosses (bool or list, optional) – Radiation losses configuration. If False, radiation losses are disabled. If list format: [True, {“Photons”: True/False, “MinE”: float, “MaxE”: float}]. Default is False.
Date (datetime.datetime, optional) – Date for field model initialization. Default is datetime.datetime(2008, 1, 1).
Save (int or list, optional) – Save interval configuration. If int N, save every N steps. If list format: [N, {“Clock”: True, …}] to save additional parameters. See SaveCode. Default is 1.
Nfiles (int or list, optional) – Number of output files. If int: create N files. If list: create files with specified indices. Default is 1.
Output (str or None, optional) – Output file base name. If None, results are not saved to disk. Default is None.
Verbose (int, optional) – Verbosity level: 0 (no output), 1 (short output), 2 (verbose output). Default is 1.
ForwardTrck ({1, -1} or None, optional) – Tracing direction: 1 for forward, -1 for backward. If None, determined from Particles. Default is None.
TrackParams (bool or dict, optional) – Additional parameter tracking. If True, all available parameters are tracked. If dict, specify which parameters to track: {‘Invariants’: True, ‘GuidingCenter’: True, etc.}. See SaveAdd. Default is False.
ParticleOrigin (bool, optional) – Enable particle origin calculation through backtracing. Default is False.
IsFirstRun (bool, optional) – Flag indicating first simulation run. Affects logging and some calculations. Default is True.

Returns:

result – Results of simulation.

If Output is None:
Returns a list of simulation results. The structure depends on Nfiles:
- Nfiles = 1 — a flat list of dictionaries, one per simulated particle (the number of particles is determined by the Particles argument).
- Nfiles > 1 — a list of lists. Each inner list corresponds to one output file and contains dictionaries for the particles processed in that file.
If Output is not None:
Results are saved to disk (NumPy binary files) and the method returns None.

Return type:

list or None

Notes

For detailed information about the structure of the particle data dictionaries, see the Simulation output section in the online documentation.

`common`	Common utilities and definitions used throughout the gtsimulation package.
`electric_field`	Electric field models.
`functions`
`interaction`	Particle interaction models.
`magnetic_field`	Magnetic field models.
`medium`	Medium models.
`particle`	Particle definitions and initial conditions.
`pusher`	Particle trajectory pushers.