Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/PRBEM/IRBEM/llms.txt

Use this file to discover all available pages before exploring further.

Drift shells describe the toroidal surface swept out by a charged particle as it simultaneously bounces between mirror points and drifts azimuthally around the Earth under gradient and curvature forces. These routines trace that surface, compute the resulting magnetic coordinates (Lm, L*, Bmin, XJ, MLT), and provide Python helpers for derived quantities such as the bounce period and mirror point altitude.

​
DRIFT_SHELL

DRIFT_SHELL traces a complete drift shell for locally mirroring particles (pitch angle = 90°) whose mirror point is at the input location. The routine samples 48 azimuths and returns up to 1000 field-line points per azimuth, providing full three-dimensional geometry of the shell for visualization or further analysis.
To retrieve only positions between the mirror points (the drift-bounce orbit), use DRIFT_BOUNCE_ORBIT, which samples 25 azimuths and supports arbitrary pitch angles.

​
Parameters

​
X
dict
required
Position and time dictionary with keys x1, x2, x3 (coordinates in sysaxes) and dateTime (ISO 8601 string, datetime.datetime, or pd.Timestamp). This is the starting mirror point.
​
maginput
dict
required
Magnetic field model driver inputs. See maginput.

​
Outputs

​
Lm
float
McIlwain L parameter for the drift shell.
​
lstar
float
Roederer L* or Φ = 2π B₀/L* (nT Re²), depending on options[0].
​
blocal
array of shape (48, 1000)
Magnetic field magnitude at each traced point along the shell (nT). Rows correspond to the 48 azimuthal field lines; unused trailing elements are set to NaN.
​
bmin
float
Minimum magnetic field magnitude along the drift shell (nT).
​
xj
float
Second adiabatic invariant I (Re).
​
POSIT
array of shape (48, 1000, 3)
GEO Cartesian coordinates [x, y, z] of each point on the drift shell (Re). Unused trailing points per field line are set to NaN.
​
Nposit
integer array of length 48
Number of valid field-line points for each of the 48 traced azimuths.

​
Calling sequences

from IRBEM import MagFields

model = MagFields()
LLA = {
    'x1': 651,
    'x2': 63,
    'x3': 20,
    'dateTime': '2015-02-02T06:12:43'
}
maginput = {'Kp': 40}

result = model.drift_shell(LLA, maginput)
# result keys: 'Lm', 'lstar', 'blocal', 'bmin', 'xj', 'POSIT', 'Nposit'

​
DRIFT_BOUNCE_ORBIT

DRIFT_BOUNCE_ORBIT traces the drift-bounce orbit — the portion of the drift shell between mirror points — for a particle with a specified pitch angle at the input location. Compared to DRIFT_SHELL, it samples 25 azimuths (rather than 48), returns only points between the mirror points, and provides additional outputs describing the minimum-altitude point along the drift path.

​
Parameters

​
X
dict
required
Position and time dictionary. Keys: x1, x2, x3, dateTime.
​
maginput
dict
required
Magnetic field model driver inputs. See maginput.
​
alpha
float
default:"90"
Local pitch angle at the input position (degrees). Default is 90° (locally mirroring).
​
R0
float
default:"1"
Minimum allowed radial distance along the drift path (Re). Use R0 = 1 for standard trapped particles. Set R0 < 1 when working in the drift loss cone.

​
Outputs

​
Lm
float
McIlwain L parameter.
​
lstar
float
Roederer L* or Φ, depending on options[0].
​
blocal
array of shape (25, 1000)
Magnetic field magnitude at each traced point (nT). Unused trailing elements per azimuth are set to NaN.
​
bmin
float
Minimum magnetic field magnitude along the orbit (nT).
​
bmirr
float
Magnetic field magnitude at the mirror point (nT).
​
xj
float
Second adiabatic invariant I (Re).
​
POSIT
array of shape (25, 1000, 3)
GEO Cartesian coordinates [x, y, z] of each point on the drift-bounce orbit (Re). Unused trailing points are set to NaN.
​
Nposit
integer array of length 25
Number of valid field-line points for each of the 25 traced azimuths.
​
hmin
float
Altitude (km, GDZ) of the minimum-altitude point along the drift path among all traced azimuths.
​
hmin_lon
float
Longitude (°, GDZ) of the minimum-altitude point.

​
Calling sequences

from IRBEM import MagFields

model = MagFields()
LLA = {
    'x1': 651,
    'x2': 63,
    'x3': 20,
    'dateTime': '2015-02-02T06:12:43'
}
maginput = {'Kp': 40}

result = model.drift_bounce_orbit(LLA, maginput, alpha=90, R0=1)
# result keys: 'Lm', 'lstar', 'blocal', 'bmin', 'bmirr',
#              'xj', 'POSIT', 'Nposit', 'hmin', 'hmin_lon'

​
MagFields.bounce_period (Python only)

bounce_period computes the bounce period of a particle travelling along a magnetic field line in the configured field model. It traces the field line with trace_field_line, interpolates the field profile, and numerically integrates ds / v‖ between the two mirror points to obtain the period. The default particle type is electrons; change Erest for other species.
This is a Python-only helper method. It is not part of the underlying Fortran IRBEM library and has no FORTRAN, MATLAB, or IDL equivalent.

​
Parameters

​
X
dict
required
Position and time dictionary. Keys: x1, x2, x3, dateTime.
​
maginput
dict
required
Magnetic field model driver inputs. See maginput.
​
E
float, list, or np.ndarray
required
Particle kinetic energy (keV). A single value returns a scalar period; an array returns an array of periods.
​
Erest
float
default:"511"
Particle rest-mass energy (keV). Default is 511 keV for electrons. Use 938272 keV for protons, etc.
​
R0
float
default:"1"
Reference surface radius (Re) at which field-line tracing stops.
​
alpha
float
default:"90"
Local pitch angle at the input position (degrees).
​
interpNum
int
default:"100000"
Number of interpolation samples along the field line used in the numerical integration. Higher values improve accuracy at the cost of speed; 100,000 is a good balance.

​
Outputs

​
Tb
float or np.ndarray
Bounce period(s) in seconds. Shape matches the input E.

​
Example

from IRBEM import MagFields
import numpy as np

model = MagFields()
LLA = {
    'x1': 651,
    'x2': 63,
    'x3': 20,
    'dateTime': '2015-02-02T06:12:43'
}
maginput = {'Kp': 40}

# Single energy
Tb = model.bounce_period(LLA, maginput, E=1000)

# Multiple energies
energies = np.array([100, 500, 1000, 5000])  # keV
Tb_array = model.bounce_period(LLA, maginput, E=energies)

​
MagFields.mirror_point_altitude (Python only)

mirror_point_altitude calculates the altitude of the mirror point in the opposite hemisphere for a locally mirroring particle. It traces the field line and identifies the mirror point on the far side by locating the intersection of the interpolated field profile with the mirror-field value.
This is a Python-only helper method with no Fortran, MATLAB, or IDL equivalent. For the mirror point in the same or an arbitrary hemisphere, use find_mirror_point() instead.

​
Parameters

​
X
dict
required
Position and time dictionary. Keys: x1, x2, x3, dateTime.
​
maginput
dict
required
Magnetic field model driver inputs. See maginput.
​
R0
float
default:"1"
Reference surface radius (Re) used during field-line tracing.

​
Outputs

​
mirrorAlt
float
Altitude of the mirror point in the opposite magnetic hemisphere (km above Earth’s surface).

​
Example

from IRBEM import MagFields

model = MagFields()
LLA = {
    'x1': 651,
    'x2': 63,
    'x3': 20,
    'dateTime': '2015-02-02T06:12:43'
}
maginput = {'Kp': 40}

alt_km = model.mirror_point_altitude(LLA, maginput, R0=1)
print(f"Conjugate mirror point altitude: {alt_km:.1f} km")
If the mirror point lies below the reference surface R0, both bounce_period and mirror_point_altitude will raise a ValueError: Mirror point below R0. Lower R0 to extend the tracing into the loss cone, or verify that the chosen position and pitch angle correspond to a trapped particle.

Build docs developers (and LLMs) love

Get started for freeTalk to us