Medium#
The propagation medium is defined through the Medium Module. At the heart of this module lies the abstract base
class gtsimulation.medium.GTGeneralMedium. To create a custom medium model, users must implement a concrete
subclass and define several core methods. The primary method, calculate_model(),
updates the model’s internal state for given coordinates. At each step of the trajectory, the simulator calls it with
the particle coordinates in metres. The subclass must also implement
get_density() (returns the mass density in kg/m³),
get_element_list() (returns the list of chemical elements), and
get_element_abundance() (returns their mass fractions in the same order,
summing to 1).
The module provides several pre-configured models for common environments:
General: A homogeneous medium.
Magnetosphere: The NRLMSIS-00, 2.0, 2.1 atmosphere model.
Galaxy: A model for interstellar gas based on the work of Jóhannesson et al.
The concrete classes for these models are located within the gtsimulation.medium module and its submodules.
This module is optional and is only required when simulating physical processes that depend on the medium, such as
nuclear interactions. During trajectory calculation, it tracks the accumulated grammage (g/cm²), which is essential
for calculating interaction probabilities. The modular design allows for straightforward integration of user-defined
medium models by subclassing the base class.
Custom medium#
The example below shows how to implement a custom medium model: a hydrogen-helium gas whose density grows quadratically along the \(z\) axis, \(\rho = \rho_0 \left(1 + z^2 / L^2\right)\). The composition is constant: 75 % hydrogen and 25 % helium by mass.
import numpy as np
from gtsimulation.medium import GTGeneralMedium
class QuadraticMedium(GTGeneralMedium):
def __init__(self, rho0, L):
super().__init__()
self.model = "QuadraticMedium"
self.rho0 = rho0 # density at z = 0, kg/m3
self.L = L # length scale, m
self.element_list = ["H", "He"]
self.element_abundance = np.array([0.75, 0.25]) # mass fractions
self.density = rho0
def calculate_model(self, x, y, z):
self.density = self.rho0 * (1 + (z / self.L) ** 2)
def get_density(self):
return self.density
def get_element_list(self):
return self.element_list
def get_element_abundance(self):
return self.element_abundance
def __str__(self):
return (
f"{self.model}\n"
f"\trho0: {self.rho0} kg/m3\n"
f"\tL: {self.L} m"
)
The medium is passed to the simulator with the Medium parameter. To save the accumulated grammage along the
trajectory, enable Density in Save:
import gtsimulation as gt
from gtsimulation.common import Units
from gtsimulation.particle import generator
particle = gt.particle.Flux(
Distribution=generator.distribution.UserInput(R0=[0, 0, 0], V0=[1, 0, 1]),
Spectrum=generator.spectrum.UserInput(energy=1 * Units.keV),
Names="proton",
Nevents=1,
)
simulator = gt.pusher.BunemanBorisSimulator(
Particles=particle,
Step=1e-3,
Num=2000,
Bfield=gt.magnetic_field.Uniform(B=[0, 0, 100]),
Medium=QuadraticMedium(rho0=1e-12, L=1000 * Units.km),
Save=[1, {"Density": True}],
)
result = simulator()
grammage = result[0][0]["Track"]["Density"] # g/cm²