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.

These routines compute magnetic coordinates for a given set of spacecraft positions. Computed quantities include the McIlwain L parameter (Lm), Roederer L* (or the equivalent Φ = 2π B₀/L*), the magnetic field magnitude at the local point (Blocal) and at the magnetic equator (Bmin), the second adiabatic invariant I (XJ), and magnetic local time (MLT). A choice of internal and external magnetic field models can be selected via the kext and options parameters.

​
Lm / L* encoding

IRBEM output values of Lm and L* carry additional information about whether a particle at that location is trapped. Two special cases are encoded:
  • Drift shell intersects the atmosphere — if the drift shell passes through the atmosphere before completing a full circuit, the particle is precipitating. The output value is set to a large negative sentinel so it can be distinguished from a physical L value.
  • Drift shell is not closed — if the shell cannot close around the Earth (open field line, beyond the magnetopause, etc.), the output value is set to a different sentinel indicating a non-trapped state.
Only values in the physically meaningful range correspond to stably trapped particles. Consult the Lstar-coding figure in the IRBEM documentation and check for sentinel values (typically < -90) when interpreting outputs.

​
MAKE_LSTAR

MAKE_LSTAR computes magnetic coordinates at any spacecraft position for locally mirroring particles (local pitch angle = 90°). For arbitrary pitch angles, see MAKE_LSTAR_SHELL_SPLITTING. For a fast approximation valid only with the Olson-Pfitzer Quiet model, see LANDI2LSTAR.

​
Parameters

​
ntime
integer
required
Number of time points to process.
​
kext
integer
required
Key selecting the external magnetic field model. See Magnetic Field Models.
​
options
array of 5 integers
required
Array of five integers controlling library behaviour (e.g., L* vs Φ output, accuracy settings). See Options Parameters.
​
sysaxes
integer
required
Key for the input coordinate system. See Coordinate Systems.
​
iyear[ntime]
integer array
required
Year of each time point.
​
idoy[ntime]
integer array
required
Day of year for each time point (January 1 = 1).
​
UT[ntime]
double array
required
Time in seconds since midnight for each time point.
​
x1[ntime]
double array
required
First coordinate component at each time point, in the system given by sysaxes.
​
x2[ntime]
double array
required
Second coordinate component at each time point.
​
x3[ntime]
double array
required
Third coordinate component at each time point.
​
maginput[25, ntime]
double array
required
Magnetic field model driver inputs. See maginput for the full list of valid keys and expected values for each model.

​
Outputs

​
Lm[ntime]
double array
McIlwain L parameter at each location. Sentinel values indicate non-trapped particles; see Lm/L* encoding.
​
Lstar[ntime]
double array
Roederer L* or Φ = 2π B₀/L* (nT Re²), depending on the value of options[0]. Sentinel values indicate non-closed or atmosphere-intersecting drift shells.
​
Blocal[ntime]
double array
Magnitude of the magnetic field at the spacecraft position (nT).
​
Bmin[ntime]
double array
Magnitude of the magnetic field at the magnetic equator along the field line (nT).
​
XJ[ntime]
double array
Second adiabatic invariant I, related to the bounce motion (Re).
​
MLT[ntime]
double array
Magnetic local time at each position (hours, 0–24).

​
Calling sequences

call make_lstar1(ntime, kext, options, sysaxes, &
    iyear, idoy, ut, x1, x2, x3, maginput, &
    lm, lstar, blocal, bmin, xj, mlt)

​
MAKE_LSTAR_SHELL_SPLITTING

MAKE_LSTAR_SHELL_SPLITTING extends MAKE_LSTAR to compute magnetic coordinates at arbitrary pitch angles, not only for locally mirroring particles. Up to NALPHA_MAX = 25 pitch angles may be requested simultaneously.

​
Additional parameters (beyond MAKE_LSTAR)

​
npa
integer
required
Number of requested pitch angles (1 to NALPHA_MAX = 25).
​
alpha[npa]
double array
required
Local pitch angles at the spacecraft position (degrees).

​
Outputs

​
Lm[ntime, NALPHA_MAX]
double array
McIlwain L parameter for each time point and pitch angle.
​
Lstar[ntime, NALPHA_MAX]
double array
Roederer L* or Φ for each time point and pitch angle.
​
Bmirr[ntime, NALPHA_MAX]
double array
Magnetic field magnitude at the mirror point for each time point and pitch angle (nT).
​
XJ[ntime, NALPHA_MAX]
double array
Second adiabatic invariant I for each time point and pitch angle (Re).
​
Bmin[ntime]
double array
Magnetic field at the magnetic equator — one value per time point, shared across all pitch angles (nT).
​
MLT[ntime]
double array
Magnetic local time — one value per time point (hours).

​
Calling sequences

call make_lstar_shell_splitting1(ntime, Npa, kext, options, sysaxes, &
    iyear, idoy, ut, x1, x2, x3, alpha, maginput, &
    lm, lstar, bmirr, bmin, xj, mlt)

​
LANDI2LSTAR

LANDI2LSTAR provides a fast empirical approximation of L* by deriving it from Lm, I (the second adiabatic invariant), and the day of year. Because it bypasses the full drift-shell integration, it is substantially faster than MAKE_LSTAR, but is only valid for the IGRF + Olson-Pfitzer Quiet external field model (kext = 5). Errors in L* are less than 2%. This routine computes L* for locally mirroring particles. For arbitrary pitch angles with the same fast approach, use LANDI2LSTAR_SHELL_SPLITTING.
Python users should use make_lstar() directly. The LANDI2LSTAR routine is not separately wrapped in the Python interface.

​
Calling sequences

call landi2lstar1(ntime, kext, options, sysaxes, &
    iyear, idoy, ut, x1, x2, x3, maginput, &
    lm, lstar, blocal, bmin, xj, mlt)
Inputs and outputs are identical to those of MAKE_LSTAR. The kext parameter must be 5 (Olson-Pfitzer Quiet); other values are not supported by this routine.

Build docs developers (and LLMs) love

Get started for freeTalk to us