Before calling any IRBEM routine, it is important to understand the shared conventions that govern data types, array sizing, and the common input parameters accepted by most routines. This page consolidates that reference material so that the individual routine pages can focus on routine-specific behavior.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.
Data types
Unless specified otherwise in a routine’s documentation, IRBEM routines use the following types throughout:- Integers: 32-bit signed integers (referred to as
longintegers in IDL). - Floats: 64-bit double-precision floating-point numbers.
- Array ordering: all multi-dimensional arrays use column-major (Fortran) ordering.
Array size limits
Some IRBEM routines operate on arrays of multiple time points, energies, or pitch angles. For a subset of these routines, the array dimensions are bounded by library-wide constants.| Constant | Value | Description |
|---|---|---|
NTIME_MAX | variable | Maximum number of time points in input/output arrays for routines that use fixed-size time arrays. Retrieve at runtime using GET_IRBEM_NTIME_MAX. |
NENE_MAX | 25 | Maximum number of energy bins. |
NALPHA_MAX | 25 | Maximum number of pitch angles. |
Newer routines use variable-length arrays where the time dimension is the first axis of the array. For these routines, any value of
ntime is supported as long as the array is allocated with at least that many elements. Routines that still require NTIME_MAX-sized arrays explicitly note this in their documentation.Error sentinel value
When an IRBEM routine cannot compute a valid output (for example, because the requested point is outside the valid domain of the field model), the corresponding output element is set to −1×10³¹. In the Python wrapper, this sentinel is converted to −9999 for convenience.kext — External magnetic field model
Most IRBEM routines accept a kext integer parameter that selects the external magnetic field model. The following table lists all supported values.
| Key | Magnetic field model | Comments |
|---|---|---|
| 0 | No external field | — |
| 1 | Mead & Fairfield [1975] | Uses 0 ≤ Kp ≤ 9 — valid for r_GEO ≤ 17 Re |
| 2 | Tsyganenko short [1987] | Uses 0 ≤ Kp ≤ 9 — valid for r_GEO ≤ 30 Re |
| 3 | Tsyganenko long [1987] | Uses 0 ≤ Kp ≤ 9 — valid for r_GEO ≤ 70 Re |
| 4 | Tsyganenko [1989c] | Uses 0 ≤ Kp ≤ 9 — valid for r_GEO ≤ 70 Re |
| 5 | Olson & Pfitzer quiet [1977] | Valid for r_GEO ≤ 15 Re |
| 6 | Olson & Pfitzer dynamic [1988] | Uses 5 ≤ Dsw ≤ 50, 300 ≤ Vsw ≤ 500, −100 ≤ Dst ≤ 20 — valid for r_GEO ≤ 60 Re |
| 7 | Tsyganenko [1996] | Uses −100 ≤ Dst ≤ 20, 0.5 ≤ Pdyn ≤ 10, |By| ≤ 10, |Bz| ≤ 10 — valid for r_GEO ≤ 40 Re |
| 8 | Ostapenko & Maltsev [1997] | Uses Dst, Pdyn, Bz, Kp |
| 9 | Tsyganenko [2001] | Uses −50 ≤ Dst ≤ 20, 0.5 ≤ Pdyn ≤ 5, |By| ≤ 5, |Bz| ≤ 5, 0 ≤ G1 ≤ 10, 0 ≤ G2 ≤ 10 — valid for x_GSM ≥ −15 Re |
| 10 | Tsyganenko [2001] storm | Uses Dst, Pdyn, By, Bz, G2, G3 — no upper/lower limit on inputs — valid for x_GSM ≥ −15 Re |
| 11 | Tsyganenko [2004] storm | Uses Dst, Pdyn, By, Bz, W1–W6 — no upper/lower limit on inputs — valid for x_GSM ≥ −15 Re |
| 12 | Alexeev [2000] (Paraboloid model) | Uses Dsw, Vsw, Dst, Bz, AL |
| 13 | Tsyganenko [2007] | — |
| 14 | Mead-Tsyganenko | Uses Kp — ONERA model where Tsyganenko 89 is best-fitted by a Mead model |
In addition to the external field model, the internal magnetic field model used by IRBEM can be selected via the fifth element of the
options array. See the Options array section below.options — Options array
Many IRBEM routines accept an options parameter, which is a 5-element integer array that controls runtime behavior. The table below summarises each element. For full documentation see the Options Parameters concept page.
| Index | Quantity | Values |
|---|---|---|
| 1 | L* or Φ computation | 0 = do not compute L* or Φ; 1 = compute L*; 2 = compute Φ |
| 2 | IGRF update frequency | 0 = initialize once per year at year.5; n = update every n days from January 1 |
| 3 | L* field line resolution | 0–9; 0 is recommended (∼2 % error at L = 6); higher values improve precision at the cost of computation time |
| 4 | L* drift shell resolution | 0–9; 0 is usually sufficient except on LEO orbits where higher values are recommended |
| 5 | Internal magnetic field model | 0 = IGRF (default); 1 = eccentric tilted dipole; 2 = Jensen & Cain 1960; 3 = GSFC 12/66 updated to 1970; 4 = user-supplied myOwnMagField; 5 = centered dipole |
sysaxes — Coordinate system keys
Routines that accept or return position vectors use a sysaxes integer to identify the coordinate system. The following table lists all 15 supported systems.
| Key | Name | Description |
|---|---|---|
| 0 | GDZ | Geodetic — altitude (km), latitude (deg), East longitude (deg). Uses the WGS84 reference ellipsoid. |
| 1 | GEO | Geocentric geographic (Cartesian, Re). Earth-centered, Earth-fixed; X toward the Prime Meridian, Z toward True North. |
| 2 | GSM | Geocentric Solar Magnetospheric (Cartesian, Re). X sunward; X-Z plane contains Earth’s dipole axis. |
| 3 | GSE | Geocentric Solar Ecliptic (Cartesian, Re). X sunward; Y in the ecliptic plane pointing anti-orbit; Z toward ecliptic north. |
| 4 | SM | Solar Magnetic (Cartesian, Re). Z aligned with the centered dipole axis; a rotation about Y from GSM. |
| 5 | GEI | Geocentric Equatorial Inertial (Cartesian, Re). X toward the equinox of date; Z parallel to Earth’s instantaneous rotation axis. |
| 6 | MAG | Geomagnetic (Cartesian, Re). Z parallel to the centered dipole axis; Y is the intersection of the equator and the meridian 90° east of the dipole meridian. |
| 7 | SPH | GEO in spherical — radial distance (Re), latitude (deg), East longitude (deg). |
| 8 | RLL | Geodetic spherical — radial distance (Re), geodetic latitude (deg), East longitude (deg). Not interchangeable with SPH. |
| 9 | HEE | Heliocentric Earth Ecliptic (Cartesian, Re). Origin at solar center; X toward Earth; Z perpendicular to Earth’s orbital plane (north). |
| 10 | HAE | Heliocentric Aries Ecliptic (Cartesian, Re). Origin at solar center; Z perpendicular to Earth’s orbital plane; X toward the equinox of date. |
| 11 | HEEQ | Heliocentric Earth Equatorial (Cartesian, Re). Origin at solar center; Z parallel to the Sun’s rotation axis; X toward the intersection of the solar equator and solar central meridian as seen from Earth. |
| 12 | TOD | True of Date — same as GEI (Cartesian, Re). Included for legacy support; uses the true equator and equinox of date. |
| 13 | J2000 | GEI at J2000 (Cartesian, Re). X toward the mean equinox at J2000; Z perpendicular to the mean equator at J2000. Corrects for precession but not nutation. |
| 14 | TEME | True Equator Mean Equinox (Cartesian, Re). The inertial system used by the SGP4 orbit propagator. |
IRBEM defines the geophysical coordinate systems (GSE, GSM, SM, etc.) relative to TOD (GEI). Some missions define these systems relative to a different inertial frame (usually MOD). For details of the approximations used, see Russel (1971) and Hapgood (1992).
maginput — Magnetic field inputs
Routines that drive external magnetic field models require a maginput array of 25 double-precision elements containing geophysical parameters. The table below describes each index.
| Index | Name | Description |
|---|---|---|
| 1 | Kp | Kp index as in OMNI2 files (double, not integer); equals Kp × 10, range 0–90. |
| 2 | Dst | Dst index (nT). |
| 3 | Dsw | Solar wind density (cm⁻³). |
| 4 | Vsw | Solar wind velocity (km s⁻¹). |
| 5 | Pdyn | Solar wind dynamic pressure (nPa). |
| 6 | By | GSM y component of the interplanetary magnetic field (nT). |
| 7 | Bz | GSM z component of the interplanetary magnetic field (nT). |
| 8 | G1 | ⟨Vsw (Bperp/40)² / (1 + Bperp/40) sin³(θ/2)⟩ — 1-hour average; Bperp is the transverse IMF magnitude (GSM) and θ its clock angle. |
| 9 | G2 | ⟨a Vsw Bs⟩ — 1-hour average; Bs = |IMF Bz| when Bz < 0, else 0; a = 0.005. |
| 10 | G3 | ⟨Vsw Dsw Bs / 2000⟩ — 1-hour average. |
| 11–16 | W1–W6 | See definitions in Tsyganenko et al. (2005), doi:10.1029/2004JA010798. |
| 17 | AL | Auroral index. |
| 18–25 | — | Reserved for future use. |
Solar wind inputs (Dsw, Vsw, Pdyn, By, Bz, G1–G3) must be measured near the dayside magnetopause — not at the L1 Lagrange point. The hourly NASA OMNI2 dataset is a suitable source.