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.
Most IRBEM routines accept an options parameter — a 5-element integer array that governs how the library performs its internal calculations. Selecting appropriate values for this array lets you trade off between computation speed and numerical precision, control how frequently the IGRF model is updated, and choose the internal magnetic field model.
Quick Reference
| Index | Controls | Default (0) |
|---|
options[0] | L* or Φ output mode | Do not compute L* or Φ |
options[1] | IGRF initialization frequency | Once per year at year.5 |
options[2] | Field line integration resolution | ~2% error at L=6 |
options[3] | Drift shell integration resolution | Sufficient for LEO |
options[4] | Internal magnetic field model | IGRF |
Fortran indexing: IRBEM’s Fortran source and some legacy documentation use 1-based indexing, so what this page calls options[0] is options(1) in Fortran and IDL. The Python wrapper uses 0-based Python indexing throughout.
options[0] — L* or Φ Computation Mode
Controls whether the adiabatic invariant L* (Roederer L) or the third invariant Φ is computed alongside other outputs.
| Value | Behavior |
|---|
0 | Do not compute L* or Φ — faster, safe when only field values or L-shell are needed |
1 | Compute Roederer L* |
2 | Compute Φ = 2π B₀ / L* (in units of nT Re²) |
options[0] = 0 significantly reduces runtime for routines like make_lstar when you only need Lm, blocal, or similar quantities that do not require a full drift-shell integration.
options[1] — IGRF Initialization Frequency
Controls how often the IGRF internal field coefficients are recomputed during a batch calculation.
| Value | Behavior |
|---|
0 | Initialize IGRF once per year (at year.5) |
n > 0 | Re-initialize every n days starting on January 1st of each year — e.g., n=15 updates on days 1, 15, 30, 45, … |
options[1] = 0 is adequate. For multi-year runs or high-accuracy work during years with rapid geomagnetic variation, setting a smaller n improves fidelity at the cost of additional initialization overhead.
options[2] — L* Field Line Resolution
Determines the integration step dθ along field lines when computing L*.
| Value | Integration step |
|---|
| 0 | dθ = π / (720 × 1) — recommended; ~2% error at L=6 |
| 1 | dθ = π / (720 × 2) |
| … | … |
| n | dθ = π / (720 × (n + 1)) |
0 provides a good balance between precision and computation time. Precision gains generally plateau around options[2] = 4; values beyond that increase runtime without meaningful accuracy improvements.
options[3] — L* Drift Shell Resolution
Determines the integration step dφ around the drift shell when computing L*.
| Value | Integration step |
|---|
| 0 | dφ = 2π / (25 × 1) — usually sufficient |
| 1 | dφ = 2π / (25 × 2) |
| … | … |
| n | dφ = 2π / (25 × (n + 1)) |
options[3] = 0 is typically sufficient because the drift shell varies little. For non-LEO orbits — particularly at high L-shells where the drift shell becomes asymmetric — increasing this value improves L* accuracy.
options[4] — Internal Magnetic Field Model
Selects the internal (main) field model. This overrides the default IGRF when a simpler or user-supplied model is needed.
| Value | Model |
|---|
0 | IGRF (default) |
1 | Eccentric tilted dipole |
2 | Jensen & Cain 1960 |
3 | GSFC 12/66 updated to 1970 |
4 | User-defined myOwnMagField(xGEO, Bxint) routine |
5 | Centered dipole |
Python Usage Example
from IRBEM import MagFields
# options[0]=1: compute L*
# options[1]=0: update IGRF once per year
# options[2]=0: default field line resolution (~2% at L=6)
# options[3]=0: default drift shell resolution (adequate for LEO)
# options[4]=0: use IGRF internal field
model = MagFields(options=[1, 0, 0, 0, 0], kext='OPQ77')
X = {
'dateTime': '2022-03-15T08:30:00',
'x1': 650.0, # altitude (km) in GDZ
'x2': 55.0, # latitude (deg)
'x3': 20.0, # East longitude (deg)
}
maginput = {'Kp': 20.0}
result = model.make_lstar(X, maginput)
print('L*:', result['Lstar'])
Fortran / IDL Usage
Pass options as a 5-element long-integer array (1-based in Fortran):
! Fortran example
INTEGER*4 options(5)
options(1) = 1 ! compute L*
options(2) = 0 ! yearly IGRF
options(3) = 0 ! default field line resolution
options(4) = 0 ! default drift shell resolution
options(5) = 0 ! IGRF internal field
; IDL example
options = [1, 0, 0, 0, 0]
An all-zeros options array is always valid and safe as a starting point. Set options[0] = 1 to enable L* computation, and only increase options[2] or options[3] if accuracy testing reveals significant errors at your orbit altitude.