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.

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 | list | 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:
ParticlesFlux

Particle flux generator defining initial spectrum, distribution and composition. See gtsimulation.particle.

Numint

Maximum number of simulation steps.

Stepfloat 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).

BfieldAbsBfield or None, optional

Magnetic field model object. If None, no magnetic field is applied. Default is None.

EfieldGeneralFieldE or None, optional

Electric field model object. If None, no electric field is applied. Default is None.

MediumGTGeneralMedium 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.

RegionRegions, optional

Simulation region specifying the physical environment. Available options: Magnetosphere, Heliosphere, Galaxy. See gtsimulation.common.regions. Default is Regions.Undefined.

BreakConditiondict 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.

Important

In the magnetosphere, TrackParams and ParticleOrigin require Rmin >= Units.RE. Missing or smaller values are replaced with Units.RE.

UseDecaybool, optional

Enable particle decay processes. Default is False.

InteractNUCNuclearInteraction or None, optional

Nuclear interaction module. Requires Medium to be set. Default is None.

RadLossesbool 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.

Datedatetime.datetime, optional

Date for field model initialization. Default is datetime.datetime(2008, 1, 1).

Saveint 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.

Nfilesint or list, optional

Number of output files. If int: create N files. If list: create files with specified indices. Default is 1.

Outputstr, list or None, optional

Output file name. The extension selects the format: .npy for NumPy or .h5/.hdf5 for HDF5. The extension is required when an output file is specified. HDF5 options can be passed as [name, {"Compression": None}]. Compression can be "gzip" or "lzf". If None, results are not saved to disk. Default is None.

Verboseint, 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.

TrackParamsbool 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.

ParticleOriginbool, optional

Enable particle origin calculation through backtracing. Default is False.

IsFirstRunbool, optional

Flag indicating first simulation run. Affects logging and some calculations. Default is True.

Returns:
resultlist or None

Results of simulation.

  • If Output is None:

    Returns a list of lists. Each outer element corresponds to one file, and each inner list contains one result dictionary per simulated particle. With Nfiles = 1, the outer list still contains one inner list.

  • If Output is not None:

    Results are saved to disk (NumPy or HDF5 files) and the method returns None.

See also

gtsimulation.particle.Flux

Particle flux generation

gtsimulation.common.codes.SaveCode

Available save parameters

gtsimulation.common.codes.BreakCode

Available break conditions

gtsimulation.magnetic_field

Magnetic field module

gtsimulation.medium

Medium module

Notes

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

abstractmethod AlgoStep(T, M, Q, Vm, r, H, E)[source]#
CallOneFile(output_writer=None)[source]#

Modules

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.

output

particle

Particle definitions and initial conditions.

pusher

Particle trajectory pushers.