Magnetic field#
The magnetic field is implemented through a dedicated Magnetic Field Module.
The core of this module is the abstract base class gtsimulation.magnetic_field.AbsBfield.
Any custom magnetic field model must be defined as a concrete subclass of this class, which requires the explicit
implementation of a calc_field() method. This method returns the
magnetic field vector at a given point.
The module comes with a library of pre-implemented models ready for immediate use:
General: A uniform magnetic field.
Magnetosphere: Dipole field, IGRF, Tsyganenko (89, 96, 15), CHAOS (7, 8), CM6, COV-OBS.x2, LCS-1, SIFM, DIFI-6.
Heliosphere: The Parker spiral model.
Galaxy: The Jansson & Farrar (JF12) and Unger & Farrar (UF23) models.
The specific classes that implement these field models can be found within the gtsimulation.magnetic_field
module and its submodules. These models support dynamic fields that can evolve in time during particle tracing.
The abstract architecture enables users to seamlessly integrate their own field models by subclassing the base class
and implementing the required interface.
Magnetic fields can be combined with the + operator. The resulting field is the vector sum of the individual
fields:
from datetime import datetime
from gtsimulation.magnetic_field.magnetosphere import Gauss, Tsyganenko
date = datetime(2008, 1, 1)
b_field = Gauss(date=date, model="IGRF", model_type="core", version=13) + Tsyganenko(date=date, ModCode="96")
Custom magnetic field#
A custom magnetic field model is a subclass of AbsBfield that implements two
methods:
calc_field()takes the coordinates in the native length unit of the model and returns the field components in nT. The native unit is set by the class attributeto_meters, the length of the unit in metres (for example,Units.km). The default value1corresponds to metres.update_state()updates the model for a new date. A model that does not depend on time implements it as a no-op.
The example below shows how to implement a custom magnetic field model: a magnetic bottle. The field magnitude on the \(z\) axis grows quadratically, \(B_z = B_0 \left(1 + z^2 / L^2\right)\), and the radial components \(B_x = -B_0 x z / L^2\) and \(B_y = -B_0 y z / L^2\) keep \(\nabla \cdot \mathbf{B} = 0\). Coordinates are taken in kilometres.
from gtsimulation.common import Units
from gtsimulation.magnetic_field import AbsBfield
class MagneticBottle(AbsBfield):
to_meters = Units.km # calc_field takes coordinates in km
def __init__(self, B0, L):
super().__init__()
self.ModelName = "MagneticBottle"
self.B0 = B0 # field at z = 0, nT
self.L = L / self.to_meters # length scale, km
def calc_field(self, x, y, z):
Bx = -self.B0 * x * z / self.L ** 2
By = -self.B0 * y * z / self.L ** 2
Bz = self.B0 * (1 + (z / self.L) ** 2)
return Bx, By, Bz
def update_state(self, new_date):
pass # the field does not depend on time
def __str__(self):
return (
f"{self.ModelName}\n"
f"\tB0: {self.B0} nT\n"
f"\tL: {self.L} km"
)
A custom model is used in the same way as the built-in ones:
import gtsimulation as gt
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-6,
Num=20000,
Bfield=MagneticBottle(B0=1 * Units.mT, L=2 * Units.km),
)
result = simulator()