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.

The maginput array is a 25-element array of double-precision values that supplies geophysical driving parameters — such as solar wind conditions and geomagnetic indices — to IRBEM’s external field models. Different models read different elements of this array; unused elements should be set to 0 (or to the sentinel value −9999 in the Python wrapper, which handles this automatically).

​
Parameter Table

The table below lists all named maginput elements. Indices follow Fortran 1-based convention (matching the IRBEM documentation); in Python’s 0-based arrays these are shifted by one. Elements 18–25 are reserved for future use.
Index (1-based)Python keyDescriptionUsed by
1KpKp index × 10 as in OMNI2 (range 0–90, so Kp=4 → 40)MF75, TS87, TL87, T89, MT
2DstDst index (nT)OPD88, T96, OM97, T01, T01S, T04, A00
3densSolar wind density (cm⁻³)
4veloSolar wind velocity (km/s)OPD88, A00
5PdynSolar wind dynamic pressure (nPa)T96, OM97, T01, T01S, T04
6ByIMFIMF By in GSM (nT)T96, T01, T01S, T04
7BzIMFIMF Bz in GSM (nT)T96, T01, T01S, T04, A00, OPD88
8G1Coupling parameter G1 = ⟨Vsw (Bperp/40)² / (1 + Bperp/40) sin³(θ/2)⟩ — 1-hour averageT01
9G2Coupling parameter G2 = ⟨a Vsw Bs⟩ where Bs = |IMF Bz| when Bz < 0 else 0, a = 0.005 — 1-hour averageT01, T01S
10G3Coupling parameter G3 = ⟨Vsw dens Bs / 2000⟩ — 1-hour averageT01S
11W1T04 storm-time coupling parameter W1 (see Tsyganenko et al., 2005)T04
12W2T04 storm-time coupling parameter W2T04
13W3T04 storm-time coupling parameter W3T04
14W4T04 storm-time coupling parameter W4T04
15W5T04 storm-time coupling parameter W5T04
16W6T04 storm-time coupling parameter W6T04
17ALAuroral AL index (nT)A00
18–25—Reserved for future use—
Kp encoding: Kp is stored as Kp × 10 consistent with the NASA OMNI2 data format. A Kp value of 4 should be passed as 40.0, Kp = 3.3 as 33.0, and so on. Valid range is 0–90.

​
Python Dictionary Interface

The Python MagFields wrapper accepts maginput as a plain dictionary. You only need to supply keys for the parameters actually required by your chosen model; the wrapper fills all other slots with the sentinel value −9999. 
from IRBEM import MagFields

# T96 model (kext=7) requires Dst, Pdyn, ByIMF, BzIMF
model = MagFields(kext='T96', options=[1, 0, 0, 0, 0])

X = {
    'dateTime': '2015-03-17T06:00:00',
    'x1': 20000.0,   # altitude (km) — GDZ
    'x2': 0.0,       # latitude (deg)
    'x3': 0.0,       # East longitude (deg)
}
maginput = {
    'Kp':    0.0,
    'Dst':  -30.0,   # nT
    'Pdyn':  2.0,    # nPa
    'ByIMF': 3.0,    # nT
    'BzIMF': -5.0,   # nT
}

result = model.make_lstar(X, maginput)
The Python key names come from the orderedKeys list in IRBEM.py: 
orderedKeys = ['Kp', 'Dst', 'dens', 'velo', 'Pdyn', 'ByIMF',
               'BzIMF', 'G1', 'G2', 'G3',
               'W1', 'W2', 'W3', 'W4', 'W5', 'W6', 'AL']

​
Per-Model Parameter Requirements

The table below summarises which maginput parameters each external model actually reads. Parameters not listed for a given model are ignored.
Model (kext)Required maginput keys
0 — No external field(none)
1 — MF75Kp
2 — TS87Kp
3 — TL87Kp
4 — T89Kp
5 — OPQ77(none)
6 — OPD88dens, velo, Dst
7 — T96Dst, Pdyn, ByIMF, BzIMF
8 — OM97Dst, Pdyn, BzIMF, Kp
9 — T01Dst, Pdyn, ByIMF, BzIMF, G1, G2
10 — T01SDst, Pdyn, ByIMF, BzIMF, G2, G3
11 — T04Dst, Pdyn, ByIMF, BzIMF, W1–W6
12 — A00dens, velo, Dst, BzIMF, AL
13 — T07(see T07 documentation)
14 — MTKp

​
MATLAB Helper

IRBEM’s MATLAB interface provides a convenience function that assembles the maginput array in the correct order: 
maginput = onera_desp_lib_maginputs(Kp, Dst, Nsw, Vsw, Psw, ...
               ByGSM, BzGSM, G1, G2, G3, W1, W2, W3, W4, W5, W6, AL);
Pass 0 for any parameter not used by the model you have selected.

​
Fortran Interface

In Fortran, maginput is a DOUBLE PRECISION array with dimensions (25, ntime) stored in column-major order: 
DOUBLE PRECISION maginput(25, ntime_max)
! Zero out unused slots
maginput = 0.0D0
! Example: set Kp=40 (i.e. Kp×10=40), Dst=-30 nT
maginput(1, 1) = 40.0D0   ! Kp (×10)
maginput(2, 1) = -30.0D0  ! Dst (nT)
Providing incorrect or missing driving parameters for a model will not cause IRBEM to raise an error — it will simply compute silently with wrong magnetic field values. For example, running T96 without supplying Dst and Pdyn will produce meaningless L* values. Always verify that your maginput dictionary contains all parameters listed for your chosen model.
Solar wind inputs (density, velocity, pressure, IMF) must be measured near the dayside magnetopause, not at the L1 Lagrange point. The hourly NASA OMNI2 dataset, which propagates solar wind observations to the nose of the magnetosphere, is a standard source for these values.

Build docs developers (and LLMs) love

Get started for freeTalk to us