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 trace magnetic field lines and compute physically significant points along them. Starting from a given spacecraft position, you can locate the mirror point for a particle at a specified pitch angle, find where the field line crosses a target altitude (foot point), trace the complete field line geometry for visualization, identify the magnetic equator (Bmin point), and evaluate the magnetic field vector at any set of input positions.

​
FIND_MIRROR_POINT

FIND_MIRROR_POINT locates the magnitude and GEO Cartesian position of the mirror point along the field line threading a given location, for a particle with a specified local pitch angle.

​
Parameters

​
X
dict
required
Position and time dictionary with keys x1, x2, x3 (coordinates in sysaxes) and dateTime (ISO 8601 string, datetime.datetime, or pd.Timestamp).
​
maginput
dict
required
Magnetic field model driver inputs. See maginput.
​
alpha
float
required
Local pitch angle at the input position (degrees).

​
Outputs

​
blocal
float
Magnitude of the magnetic field at the input spacecraft position (nT).
​
bmin
float
Magnitude of the magnetic field at the mirror point (nT). This equals Bmirr for the given pitch angle.
​
POSIT
array of 3 floats
GEO Cartesian coordinates [x, y, z] of the mirror point (Re).

​
Calling sequences

from IRBEM import MagFields

model = MagFields()
LLA = {
    'x1': 651,
    'x2': 63,
    'x3': 20,
    'dateTime': '2015-02-02T06:12:43'
}
maginput = {'Kp': 40}
alpha = 90

result = model.find_mirror_point(LLA, maginput, alpha)
# result keys: 'blocal', 'bmin', 'POSIT'

​
FIND_FOOT_POINT

FIND_FOOT_POINT traces the field line from the input position to find where it crosses a specified altitude in a chosen magnetic hemisphere. This is commonly used to map spacecraft positions to ionospheric conjugate points.

​
Parameters

​
X
dict
required
Position and time dictionary. Keys: x1, x2, x3, dateTime.
​
maginput
dict
required
Magnetic field model driver inputs. See maginput.
​
stopAlt
float
required
Target altitude above Earth’s surface for the foot-point crossing (km).
​
hemiFlag
integer
required
Selects which magnetic hemisphere to trace into:
  • 0 — same magnetic hemisphere as the starting point
  • +1 — northern magnetic hemisphere
  • -1 — southern magnetic hemisphere
  • +2 — opposite magnetic hemisphere from the starting point

​
Outputs

​
XFOOT
array of 3 floats
GDZ coordinates [altitude (km), latitude (°), longitude (°)] of the field-line foot point.
​
BFOOT
array of 3 floats
Magnetic field vector at the foot point in GEO Cartesian coordinates (nT).
​
BFOOTMAG
float
Magnitude of the magnetic field at the foot point (nT).

​
Calling sequences

from IRBEM import MagFields

model = MagFields()
LLA = {
    'x1': 651,
    'x2': 63,
    'x3': 20,
    'dateTime': '2015-02-02T06:12:43'
}
maginput = {'Kp': 40}
stopAlt = 100    # km
hemiFlag = 0     # same hemisphere

result = model.find_foot_point(LLA, maginput, stopAlt, hemiFlag)
# result keys: 'XFOOT', 'BFOOT', 'BFOOTMAG'

​
TRACE_FIELD_LINE

TRACE_FIELD_LINE traces the complete field line passing through the input position, returning an array of GEO Cartesian positions from one end of the field line to the other, bounded by the reference surface at radius R0. In addition to the geometry, it returns the McIlwain L, Bmin, XJ, and local field magnitude at each traced point.

​
Parameters

​
X
dict
required
Position and time dictionary. Keys: x1, x2, x3, dateTime.
​
maginput
dict
required
Magnetic field model driver inputs. See maginput.
​
R0
float
default:"1"
Radius of the reference surface (Re) at which field-line tracing stops. Default is 1 Re (Earth’s surface). Use values less than 1 to trace into the drift loss cone.

​
Outputs

​
POSIT
array of shape (Nposit, 3)
GEO Cartesian coordinates [x, y, z] of each point along the field line (Re). Array is trimmed to the Nposit valid points.
​
Nposit
integer
Number of valid points returned in POSIT. Maximum is 3000.
​
lm
float
McIlwain L shell value for the traced field line.
​
blocal
array of Nposit floats
Magnetic field magnitude at each point along the field line (nT).
​
bmin
float
Minimum magnetic field magnitude along the field line, located at the magnetic equator (nT).
​
xj
float
Second adiabatic invariant I (Re).

​
Calling sequences

from IRBEM import MagFields

model = MagFields()
LLA = {
    'x1': 651,
    'x2': 63,
    'x3': 20,
    'dateTime': '2015-02-02T06:12:43'
}
maginput = {'Kp': 40}

result = model.trace_field_line(LLA, maginput, R0=1)
# result keys: 'POSIT', 'Nposit', 'lm', 'blocal', 'bmin', 'xj'

​
FIND_MAGEQUATOR

FIND_MAGEQUATOR traces the magnetic field line from the input position to locate the magnetic equator — the point of minimum field strength (Bmin) along the field line. It returns both Bmin and the GEO Cartesian coordinates of that equatorial crossing.

​
Parameters

​
X
dict
required
Position and time dictionary. Keys: x1, x2, x3, dateTime.
​
maginput
dict
required
Magnetic field model driver inputs. See maginput.

​
Outputs

​
bmin
float
Magnetic field magnitude at the magnetic equator (nT).
​
XGEO
array of 3 floats
GEO Cartesian coordinates [x, y, z] of the magnetic equator along the field line (Re).

​
Calling sequences

from IRBEM import MagFields

model = MagFields()
LLA = {
    'x1': 651,
    'x2': 63,
    'x3': 20,
    'dateTime': '2015-02-02T06:12:43'
}
maginput = {'Kp': 40}

result = model.find_magequator(LLA, maginput)
# result keys: 'bmin', 'XGEO'

​
GET_FIELD_MULTI

GET_FIELD_MULTI computes the magnetic field vector (in GEO Cartesian coordinates) and its magnitude at each of the input positions, using the selected internal and external field models. This is the primary routine for evaluating the raw field at arbitrary points.

​
Parameters

​
X
dict
required
Position and time dictionary with array-valued x1, x2, x3, and dateTime. Multiple time points are supported.
​
maginput
dict
required
Magnetic field model driver inputs. See maginput.

​
Outputs

​
BxGEO
array
X component of the magnetic field vector in GEO coordinates (nT).
​
ByGEO
array
Y component of the magnetic field vector in GEO coordinates (nT).
​
BzGEO
array
Z component of the magnetic field vector in GEO coordinates (nT).
​
Bl
array
Total magnetic field magnitude at each input position (nT).

​
Calling sequences

from IRBEM import MagFields

model = MagFields(options=[0, 0, 0, 0, 0], verbose=True)
LLA = {
    'x1': 651,
    'x2': 63.97,
    'x3': 15.9,
    'dateTime': '2015-02-02T06:12:43'
}
maginput = {'Kp': 40.0}

result = model.get_field_multi(LLA, maginput)
# result keys: 'BxGEO', 'ByGEO', 'BzGEO', 'Bl'

​
GET_MLT

GET_MLT computes the magnetic local time (MLT) from a position in GEO Cartesian coordinates and a date. It uses only the IGRF internal field model — no external field model or maginput is required.

​
Parameters

​
X
dict
required
Position and time dictionary in GEO Cartesian coordinates. Keys: x1 (Xgeo, Re), x2 (Ygeo, Re), x3 (Zgeo, Re), and dateTime.

​
Outputs

​
MLT
float
Magnetic local time at the input position (hours, 0–24).

​
Calling sequences

from IRBEM import MagFields

model = MagFields()
# X must be in GEO Cartesian coordinates
X = {
    'x1': 0.5,   # Xgeo (Re)
    'x2': 0.3,   # Ygeo (Re)
    'x3': 0.8,   # Zgeo (Re)
    'dateTime': '2015-02-02T06:12:43'
}

mlt = model.get_mlt(X)
# returns a float: MLT in hours
GET_MLT accepts a single position and time (scalar inputs), unlike the multi-point routines. In Python, get_mlt() returns a scalar float rather than a dictionary.

Build docs developers (and LLMs) love

Get started for freeTalk to us