gtsimulation package

Subpackages

Submodules

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

Bases: ABC

Description

Parameters:

Region (Global.regions.Regions) – The region of the in which the simulation is taken place. The parameter may have values as Global.Region.Magnetosphere, Global.Region.Heliosphere, Global.Region.Galaxy. See Global.regions. See also Global.regions._AbsRegion.set_params for additional energy losses. Example: one mau need to take into account the adiabatic energy losses in the heliosphere. In that case they call set_params(True).
Bfield (MagneticFields.magnetic_field.AbsBfield) – The magentic field object
Efield (None) – Electrical field. Similar to Bfield
Medium (Medium.general_medium.GTGeneralMedium) – The medium where particles may go into an interaction. See Medium.
Date (datetime.datetime) – Date that is used to initialize the fields
RadLosses (bool) – a bool flag that turns the calculations of radiation losses of the particles on.

# TODO add about the synchrotron emission

Parameters:

Particles (Particle.Flux) – The parameter is responsible for the initial particle flux generation. It defines the initial particle spectrum, distribution and chemical composition. See Particle.Generators.Spectrums and Particle.Generators.Distributions for available initial spectra and distributions respectively. For more information regarding flux also see Particle.Flux.
TrackParams (bool or dict) –
a ‘bool’ flag that turns the calculations of additional parameters in given region. If ‘True’ all the additional parameters will be calculated. If one needs to calculate specific parameter, he may pass a ‘dict’ instead of ‘bool’ with the names of a needed parts and the values of ‘True’. Example: {‘Invariants’: True, ‘GuidingCenter’: True}. See Global.regions._AbsRegion.SaveAdd for available parameters to a given region.

Note: to calculate some of the additional parameters others must be calculated as well.
ParticleOrigin (bool) – a ‘bool’ flag that turns the calculations of particle’s origin through the backtracing
IsFirstRun
ForwardTrck (1 or -1) – 1 refers to forward tracing, and -1 to the backtracing
Save (int or list) – The number of steps that are saved. If the value is 0, then only staring and finishing points are saved. The default parameters that are saved are Coordinates and Velocities. Other parameters that one needs to save as well, can be turned on by passing a list instead of int where the second element is a dict that’s key is the parameter name and value is True. Example [10, {“Clock”: True}]. To available parameters are listed in Global.codes.SaveCode.
Num (int) – The number of simulation steps
Step (float or dict) –
The time step of simulation in seconds. If dict one should pass:
1. UseAdaptiveStep: True/False — whether to use adaptive time step
2. InitialStep: float — The initial time step in seconds
3. MinLarmorRad: int — The minimal number of points during on the Larmor radius
4. MaxLarmorRad: int — The maximal number of points during on the Larmor radius
5. LarmorRad: int — The fixed number of points, in case when the user needs to update time step during each step
Nfiles (int or list) – Number of files if int, otherwise the list of file numbers (e.g. Nfiles = [5, 10, 20], then 3 files are numerated as 5, 10, 20). If Particles creates a flux of Nevents particles then the total number of particles that are going to be simulated is Nevents`x`Nfiles.
Output (str or None) – If None no files are saved. Otherwise, the name of the saved .npy file. If Nfiles is greater than 1. Then the names of the saved files will have the following form “Output”_i.npy
Verbose (int) – 0 - no output, 1 - short output, 2 - verbose output
BreakCondition (dict or list or None) – If None no break conditions are applied. In case of a dict with a key corresponding to the BreakCondition name and value corresponding to its value is passed. Example: {“Rmax”: 10}. In the example the maximal radius of the particle is 10 (in MagneticFields distance units). See the full list of break conditions Global.codes.BreakCode. If list, the first parameter is the dict, the second parameter describes the break condition center, i.e. A 3d array of point (in MagneticFields distance units). It represents the (0, 0, 0) relative to which Rmax/Rmin, Xmax/Xmin, Ymax/Ymin, Zmax/Zmin are calculated. Default np.array([0, 0, 0]).
UseDecay (bool) – If True the particles may decay. Otherwise, not.
InteractNUC

# TODO describe the InteractNUC parameter

Returns:: dict

A dictionary is saved. It has the following keys.

Track: The parameters that are saved along the trajectory. See Global.codes.SaveCode.
BC: The parameters regarding the simulation end.
2.1. WOut: The code of break. See Global.codes.BreakIndex
Particle: Information about the particle
3.1. PDG: Its PDG code

3.2. M: The mass in MeV

3.3. Z: The charge of the particle in e units.

3.4. T0: Its initial kinetic energy in MeV

3.5. Gen: Its generation
Additions: Additional parameters calculated in defined region. See Global.regions._AbsRegion.SaveAdd

4.1. In magnetosphere:

Invariants:
I1: First adiabatic invariant along the trajectory of a particle

I2: Second adiabatic invariant between each pair of reflections at mirror points

PitchAngles:
Pitch: Pitch angles along the trajectory of a particle

PitchEq: Equatorial pitch angles

MirrorPoints:
NumMirror: Indexes of trajectory where particle turns to be at a mirror point

NumEqPitch: Indexes of trajectory where particle crosses the magnetic equator

NumB0: An array of trajectory points with the minimum value of the magnetic field strength

Hmirr: The value of the magnetic field at the mirror points

Heq: The value of the magnetic field at the magnetic equator

L-shell:
L: L-shell calculated on the basis of second invariant and the field at the mirror point

Lgen: L-shell calculated at every magnetic equator point

LonTotal: the angle of rotation of the particle around the Earth

GuidingCenter:
LR: Larmor radius of a particle

LRNit:

Rline: Coordinates of the field line of the guiding centre of the particle

Bline: The value of the magnetic field of the field line of the guiding centre of the particle

Req: Coordinates of the guiding centre of the particle calculated from the field line

Beq: The value of the magnetic field at the magnetic equator calculated from the field line

BB0: The ratio of the value of the magnetic field at the position of the guiding center corresponding to the initial value of the coordinate and at the magnetic equator

L: L-shell calculated from the field line of the guiding centre

parReq: Coordinates of the guiding centre of the particle from the local field line

parBeq: The value of the magnetic field of the local field line of the particle

parBB0: The ratio of the value of the magnetic field at the position of

parL: L-shell calculated from the local field line

4.2. In heliosphere:

4.3. In galaxy:
Child: List of secondary particles. They have the same parameters.

static AdaptStep(q, m, B, V, T, M, dt, N1, N2)[source]

abstractmethod AlgoStep(T, M, q, Vm, r, H, E)[source]

CallOneFile()[source]

static CheckBreak(r, r0, center, TotPath, TotTime, full_revolutions, Brck)[source]

static RadLossStep(Vp, Vm, Yp, Ya, M, Q, UseRadLosses, Step, ForwardTracing, c, e)[source]

static SaveStep(r_old, V_norm, TotPathLen, TotPathDen, TotTime, Vm, r, T, E, B, PitchAngles, LarmorRadii, GuidingCenter, Saves, ColLen, RCode, VCode, ECode, BCode, ACode, PCode, DCode, CCode, TCode, PACode, LRCode, GCCode, SaveR, SaveV, SaveE, SaveB, SaveA, SaveP, SaveD, SaveC, SaveT, SavePA, SaveLR, SaveGC)[source]

static Update(PathLen, Step, TotPathLen, TotTime, Vm, r)[source]

gtsimulation.functions.CalcGuidingCenter(coo: ndarray, V: ndarray, H: ndarray, T: float, pitch_deg: float, M: float, Z: int) → ndarray[source]: Parameters

coo: ndarray [m], shape(m,3) V: ndarray, shape(m,3) H: ndarray [nT], shape(m,3) T: float pitch_deg: float M [MeV] Z [p+]

Returns

center [m]

gtsimulation.functions.CalcLarmorRadii(Hm: ndarray, T: float, pitchd: float, M: float, Z: int) → ndarray[source]: Parameters

Hm: ndarray of float [T], shape(N,) - module of magnetic induction Bm T: float [MeV] - kinetic energy pitchd: float [degree] - pitch angle M: float [MeV] - mass Z: int [p+] - charge

Returns

larmor: ndarray of float [m], shape(N,) - larmor radius

Used formulas

p = np.sqrt((T+M)**2 - M**2) r = p * sin(pitch) / (q * B)

gtsimulation.functions.CalcPitchAngles(H: ndarray, V: ndarray) → ndarray[source]: Parameters

H: ndarray of float [nT], shape(3,) or (N, 3) - magnetic field vectors V: ndarray of float [m/s], shape(3,) or (N, 3) - velocity vectors

Returns

PitchAngles: ndarray [degrees], shape() or (N,) - pitch angles in degrees

gtsimulation.functions.GetLastPoints(RetArr_i, s)[source]

Module contents

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

Bases: ABC

Description

Parameters:

Region (Global.regions.Regions) – The region of the in which the simulation is taken place. The parameter may have values as Global.Region.Magnetosphere, Global.Region.Heliosphere, Global.Region.Galaxy. See Global.regions. See also Global.regions._AbsRegion.set_params for additional energy losses. Example: one mau need to take into account the adiabatic energy losses in the heliosphere. In that case they call set_params(True).
Bfield (MagneticFields.magnetic_field.AbsBfield) – The magentic field object
Efield (None) – Electrical field. Similar to Bfield
Medium (Medium.general_medium.GTGeneralMedium) – The medium where particles may go into an interaction. See Medium.
Date (datetime.datetime) – Date that is used to initialize the fields
RadLosses (bool) – a bool flag that turns the calculations of radiation losses of the particles on.

# TODO add about the synchrotron emission

Parameters:

Particles (Particle.Flux) – The parameter is responsible for the initial particle flux generation. It defines the initial particle spectrum, distribution and chemical composition. See Particle.Generators.Spectrums and Particle.Generators.Distributions for available initial spectra and distributions respectively. For more information regarding flux also see Particle.Flux.
TrackParams (bool or dict) –
a ‘bool’ flag that turns the calculations of additional parameters in given region. If ‘True’ all the additional parameters will be calculated. If one needs to calculate specific parameter, he may pass a ‘dict’ instead of ‘bool’ with the names of a needed parts and the values of ‘True’. Example: {‘Invariants’: True, ‘GuidingCenter’: True}. See Global.regions._AbsRegion.SaveAdd for available parameters to a given region.

Note: to calculate some of the additional parameters others must be calculated as well.
ParticleOrigin (bool) – a ‘bool’ flag that turns the calculations of particle’s origin through the backtracing
IsFirstRun
ForwardTrck (1 or -1) – 1 refers to forward tracing, and -1 to the backtracing
Save (int or list) – The number of steps that are saved. If the value is 0, then only staring and finishing points are saved. The default parameters that are saved are Coordinates and Velocities. Other parameters that one needs to save as well, can be turned on by passing a list instead of int where the second element is a dict that’s key is the parameter name and value is True. Example [10, {“Clock”: True}]. To available parameters are listed in Global.codes.SaveCode.
Num (int) – The number of simulation steps
Step (float or dict) –
The time step of simulation in seconds. If dict one should pass:
1. UseAdaptiveStep: True/False — whether to use adaptive time step
2. InitialStep: float — The initial time step in seconds
3. MinLarmorRad: int — The minimal number of points during on the Larmor radius
4. MaxLarmorRad: int — The maximal number of points during on the Larmor radius
5. LarmorRad: int — The fixed number of points, in case when the user needs to update time step during each step
Nfiles (int or list) – Number of files if int, otherwise the list of file numbers (e.g. Nfiles = [5, 10, 20], then 3 files are numerated as 5, 10, 20). If Particles creates a flux of Nevents particles then the total number of particles that are going to be simulated is Nevents`x`Nfiles.
Output (str or None) – If None no files are saved. Otherwise, the name of the saved .npy file. If Nfiles is greater than 1. Then the names of the saved files will have the following form “Output”_i.npy
Verbose (int) – 0 - no output, 1 - short output, 2 - verbose output
BreakCondition (dict or list or None) – If None no break conditions are applied. In case of a dict with a key corresponding to the BreakCondition name and value corresponding to its value is passed. Example: {“Rmax”: 10}. In the example the maximal radius of the particle is 10 (in MagneticFields distance units). See the full list of break conditions Global.codes.BreakCode. If list, the first parameter is the dict, the second parameter describes the break condition center, i.e. A 3d array of point (in MagneticFields distance units). It represents the (0, 0, 0) relative to which Rmax/Rmin, Xmax/Xmin, Ymax/Ymin, Zmax/Zmin are calculated. Default np.array([0, 0, 0]).
UseDecay (bool) – If True the particles may decay. Otherwise, not.
InteractNUC

# TODO describe the InteractNUC parameter

Returns:: dict

A dictionary is saved. It has the following keys.

Track: The parameters that are saved along the trajectory. See Global.codes.SaveCode.
BC: The parameters regarding the simulation end.
2.1. WOut: The code of break. See Global.codes.BreakIndex
Particle: Information about the particle
3.1. PDG: Its PDG code

3.2. M: The mass in MeV

3.3. Z: The charge of the particle in e units.

3.4. T0: Its initial kinetic energy in MeV

3.5. Gen: Its generation
Additions: Additional parameters calculated in defined region. See Global.regions._AbsRegion.SaveAdd

4.1. In magnetosphere:

Invariants:
I1: First adiabatic invariant along the trajectory of a particle

I2: Second adiabatic invariant between each pair of reflections at mirror points

PitchAngles:
Pitch: Pitch angles along the trajectory of a particle

PitchEq: Equatorial pitch angles

MirrorPoints:
NumMirror: Indexes of trajectory where particle turns to be at a mirror point

NumEqPitch: Indexes of trajectory where particle crosses the magnetic equator

NumB0: An array of trajectory points with the minimum value of the magnetic field strength

Hmirr: The value of the magnetic field at the mirror points

Heq: The value of the magnetic field at the magnetic equator

L-shell:
L: L-shell calculated on the basis of second invariant and the field at the mirror point

Lgen: L-shell calculated at every magnetic equator point

LonTotal: the angle of rotation of the particle around the Earth

GuidingCenter:
LR: Larmor radius of a particle

LRNit:

Rline: Coordinates of the field line of the guiding centre of the particle

Bline: The value of the magnetic field of the field line of the guiding centre of the particle

Req: Coordinates of the guiding centre of the particle calculated from the field line

Beq: The value of the magnetic field at the magnetic equator calculated from the field line

BB0: The ratio of the value of the magnetic field at the position of the guiding center corresponding to the initial value of the coordinate and at the magnetic equator

L: L-shell calculated from the field line of the guiding centre

parReq: Coordinates of the guiding centre of the particle from the local field line

parBeq: The value of the magnetic field of the local field line of the particle

parBB0: The ratio of the value of the magnetic field at the position of

parL: L-shell calculated from the local field line

4.2. In heliosphere:

4.3. In galaxy:
Child: List of secondary particles. They have the same parameters.

static AdaptStep(q, m, B, V, T, M, dt, N1, N2)[source]

abstractmethod AlgoStep(T, M, q, Vm, r, H, E)[source]

CallOneFile()[source]

static CheckBreak(r, r0, center, TotPath, TotTime, full_revolutions, Brck)[source]

static RadLossStep(Vp, Vm, Yp, Ya, M, Q, UseRadLosses, Step, ForwardTracing, c, e)[source]

static SaveStep(r_old, V_norm, TotPathLen, TotPathDen, TotTime, Vm, r, T, E, B, PitchAngles, LarmorRadii, GuidingCenter, Saves, ColLen, RCode, VCode, ECode, BCode, ACode, PCode, DCode, CCode, TCode, PACode, LRCode, GCCode, SaveR, SaveV, SaveE, SaveB, SaveA, SaveP, SaveD, SaveC, SaveT, SavePA, SaveLR, SaveGC)[source]

static Update(PathLen, Step, TotPathLen, TotTime, Vm, r)[source]

gtsimulation package

Subpackages

Submodules

Parameters

Returns

Parameters

Returns

Used formulas

Parameters

Returns

Module contents