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.

This guide walks you through two of IRBEM’s most common operations: computing L* (the Roederer drift-shell parameter) for a spacecraft location, and transforming a position vector between geographic and magnetospheric coordinate systems. Both examples use the Python wrapper that ships with IRBEM. By the end you will have confirmed your installation is working and produced physically meaningful output.
1

Install IRBEM

Follow the Installation guide for your platform. You need:
  1. A compiled IRBEM shared library (libirbem.so, libirbem.dll, or the macOS equivalent) produced by running make OS=<platform> ENV=gfortran64 all and make OS=<platform> ENV=gfortran64 install.
  2. The Python wrapper installed from the python/ directory: 
    cd python
python3 -m pip install -e .
Confirm the library is importable before continuing:
python3 -c "from IRBEM import MagFields; print('IRBEM loaded OK')"
2

Compute L* with MagFields

The MagFields class wraps IRBEM’s magnetic coordinate routines. Instantiate it once with your chosen external field model and input coordinate system, then call make_lstar with a position dictionary and magnetic field driver inputs.
from IRBEM import MagFields

# kext='OPQ77' selects the Olson-Pfitzer Quiet (1977) external field model.
# sysaxes=0 means input coordinates are GDZ: (altitude km, latitude °, longitude °).
model = MagFields(kext='OPQ77', sysaxes=0)

# Spacecraft position: 651 km altitude, 63° latitude, 20° longitude
# on 2015-02-02 at 06:12:43 UTC.
LLA = {
    'x1': 651,            # altitude (km)  — GDZ first coordinate
    'x2': 63,             # latitude (deg) — GDZ second coordinate
    'x3': 20,             # longitude (deg)— GDZ third coordinate
    'dateTime': '2015-02-02T06:12:43',
}

# Magnetic field driver input.
# Kp index is required by OPQ77. Kp=40 corresponds to Kp = 4.0 in tenths.
maginput = {'Kp': 40}

result = model.make_lstar(LLA, maginput)
print(result)
# {'Lm': [...], 'Lstar': [...], 'blocal': [...], 'bmin': [...], 'xj': [...], 'MLT': [...]}
The kext string 'OPQ77' maps to integer 5 in IRBEM’s external model table. Other commonly used models are 'T89' (kext=4), 'T96' (kext=7), and 'T01' (kext=9). Each model requires different entries in maginput; see the general information reference for the full maginput key table.
3

Interpret the make_lstar output

make_lstar returns a dictionary with six keys. Each value is a list with one entry per input time point:
KeyUnitsDescription
Lm—McIlwain L parameter. Encodes whether the particle is trapped, in the drift loss cone, or outside a closed shell.
Lstar—Roederer L* (or Φ = 2π B₀/L* in nT Re² if options[0]=2). The primary adiabatic drift-shell invariant.
blocalnTMagnetic field magnitude at the input spacecraft position.
bminnTMagnetic field magnitude at the magnetic equator along the field line (equatorial mirror field).
xjReSecond adiabatic invariant I, related to the bounce motion of trapped particles.
MLThoursMagnetic Local Time (0–24 h), indicating the magnetic longitude relative to the Sun.
IRBEM uses fill value −9999 (Python wrapper) or −1×10³¹ (Fortran) to flag invalid or unphysical results — for example, when a position is outside a closed drift shell. Always check your output for fill values before using the data.
4

Transform coordinates with Coords

The Coords class wraps IRBEM’s coord_trans_vec1 Fortran routine. Pass a datetime object (or list of them), a position (or array of positions), and the source and destination coordinate system names.
from IRBEM import Coords
import datetime
import numpy as np

c = Coords()

# Single point: GEO Cartesian (Re) → GSM Cartesian (Re)
t = datetime.datetime(2015, 2, 2, 6, 12, 43)
pos_geo = [0.5, 0.3, 0.8]          # [X, Y, Z] in GEO (Re)

pos_gsm = c.transform(t, pos_geo, 'GEO', 'GSM')
print('GEO:', pos_geo)
print('GSM:', pos_gsm)

# Multiple points: pass lists of datetimes and an (N×3) array
times = [
    datetime.datetime(2015, 2, 2, 6, 0, 0),
    datetime.datetime(2015, 2, 2, 7, 0, 0),
    datetime.datetime(2015, 2, 2, 8, 0, 0),
]
positions_geo = np.array([
    [0.5, 0.3, 0.8],
    [0.6, 0.2, 0.9],
    [0.7, 0.1, 1.0],
])

positions_gsm = c.transform(times, positions_geo, 'GEO', 'GSM')
print(positions_gsm)   # shape (3, 3)
The transform method accepts coordinate system names as either three-letter strings ('GEO', 'GSM', 'GSE', 'SM', 'GEI', 'MAG', 'GDZ', 'RLL') or as the corresponding integer keys (0–8). In Fortran, pass the integer key directly.Available coordinate systems:
KeyNameUnits
0GDZaltitude (km), latitude (°), East longitude (°)
1GEOCartesian geographic (Re)
2GSMGeocentric Solar Magnetospheric Cartesian (Re)
3GSEGeocentric Solar Ecliptic Cartesian (Re)
4SMSolar Magnetic Cartesian (Re)
5GEIGeocentric Equatorial Inertial Cartesian (Re)
6MAGGeomagnetic Cartesian (Re)
7SPHSpherical geographic (Re, °, °)
8RLLRadial-Lat-Long (Re, °, °) — preferred over SPH

​
Next Steps

Drift Shell Tracing

Use MagFields.drift_shell() to trace a complete drift shell and obtain the full set of field-line positions in GEO coordinates — useful for visualisation and drift-averaged quantities.

Field-Line Tracing

Use MagFields.trace_field_line() to trace the field line through a spacecraft position and recover its GEO coordinates as a (3 × 3000) array.

Mirror Point & Footpoint

find_mirror_point() returns the GEO position and field magnitude of the conjugate mirror point; find_foot_point() maps to the ionospheric footprint at a specified altitude.

Radiation Models

Call FLY_IN_NASA_AEAP (via the Fortran or IDL/MATLAB interface) to fly a spacecraft trajectory through the AE8/AP8 electron and proton flux models and retrieve differential or integral fluxes.
For interactive exploration, all MagFields method outputs are stored as instance attributes after each call — e.g., model.make_lstar_output — so you can inspect them in a Python REPL without capturing the return value.
For deeper coverage of each language interface, refer to the full IRBEM documentation at https://prbem.github.io/IRBEM/ and the bundled test scripts in python/IRBEM/.

Build docs developers (and LLMs) love

Get started for freeTalk to us