A wrapper for International Radiation Belt Environment Modeling (IRBEM) library

See the Documentation for more information.

Functions

Computing magnetic field coordinates

• make_lstar: Compute magnetic coordinates at a spacecraft position
• landi2lstar: Fast empirical L* for locally mirroring particles
• get_mlt: Get Magnetic Local Time from GEO position and date
• get_hemi: Get magnetic hemisphere of input location

Points of interest on the field line

• find_mirror_point: Find magnitude and location of mirror point along field line
• find_foot_point: Find footprint of field line in a given hemisphere
• find_magequator: Find coordinates of magnetic equator from field line tracing

Magnetic field computation

• get_field_multi: Compute GEO vector of magnetic field at input location
• get_bderivs: Compute the magnetic field and its 1st-order derivatives at each input location

Field tracing

• trace_field_line: Trace a full field line crossing the input position
• drift_shell: Trace a full drift shell for particles with mirror point at input location
• drift_bounce_orbit: Trace a full bounce orbit for particles with mirror point at input location

Coordinates transformations

• transform: Transform coordinates from one system to another

Library information

• get_igrf_version: Returns the version number of the IGRF model
• irbem_fortran_version: Provides the repository version number of the fortran source code
• irbem_fortran_release: Provides the repository release tag of the fortran source code

Outputs that IRBEM could not compute (its -1e31 fill value) are NaN. Only one IRBEM routine runs at a time: calls from multiple threads are serialized.

References

• IRBEM Documentation
• IRBEM GitHub
• spacepy.irbempy

External Magnetic Field Model

See IRBEM Documentation for more details.

Magnetic field inputs. Unset fields are -9999, which IRBEM treats as missing.

See IRBEM Documentation

1: Mead & Fairfield [1975], uses 0 ≤ Kp ≤ 9, valid for rGEO ≤17 Re

2: Tsyganenko short [1987], uses 0 ≤ Kp ≤ 9, valid for rGEO ≤30 Re

3: Tsyganenko long [1987], uses 0 ≤ Kp ≤ 9, valid for rGEO ≤70 Re

4: Tsyganenko [1989], uses 0 ≤ Kp ≤ 9, valid for rGEO ≤70 Re

5: Olson & Pfitzer quiet [1977], valid for rGEO ≤15 Re

6: Olson & Pfitzer dynamic [1988]

7: Tsyganenko [1996]

8: Ostapenko & Maltsev [1997]

9: Tsyganenko [2001], uses -50 ≤ Dst ≤ 20, 0.5 ≤ Pdyn ≤ 5, |By| ≤ 5, |Bz| ≤ 5, 0 ≤ G1 ≤ 10, 0 ≤ G2 ≤ 10, valid for xGSM ≥-15 Re

10: Tsyganenko [2001], storm time, uses Dst, Pdyn, By, Bz, G2, G3, valid for xGSM ≥-15 Re

11: Tsyganenko [2004], uses Dst, Pdyn, By, Bz, W1, W2, W3, W4, W5, W6, valid for xGSM ≥-15 Re

12: Alexeev [2000], also known as Paraboloid model, uses Dsw, Vsw, Dst, Bz, AL

13: Tsyganenko [2007]

14: Mead-Tsyganenko, uses Kp, onera model where the Tsyganenko 89 model is best fitted by a Mead model

Geodetic (altitude, latitude, east longitude - km, deg, deg)

Geocentric Geographic (Earth radii)

Geocentric Solar Magnetospheric (GSM)

X points sunward from Earth's center. The X-Z plane is defined to contain Earth's dipole axis (positive North).

Geocentric Solar Ecliptic (GSE) (Earth radii)

Solar Magnetic (SM)

Geocentric Equatorial Inertial (GEI), true of date (Earth radii)

Geomagnetic (MAG)

Spherical GEO (SPH) (radial distance, latitude, east longitude - Earth radii, deg, deg)

Geodetic (radial distance, latitude, East longitude - Earth radii, deg, deg)

A re-expression of GDZ coordinates using radial distance instead of altitude above the reference ellipsoid.

Heliocentric Earth Ecliptic (HEE) (Earth radii)

Heliocentric Aries Ecliptic (HAE) (Earth radii)

Heliocentric Earth Equatorial (HEEQ) (Earth radii)

True of Date (TOD), same as GEI (Earth radii)

GEI at J2000: mean equator and mean equinox of J2000 (Earth radii)

True Equator Mean Equinox (TEME), the inertial system of SGP4 (Earth radii)

make_lstar(time, x, [coord="GDZ",] maginput=(; ); kext=KEXT[], options=OPTIONS[])
make_lstar(model::MagneticField, X::AbstractDict, maginput=(; ))

Compute magnetic coordinates at a spacecraft position. Returns a named tuple with fields Lm, Lstar, Blocal, Bmin, XJ, and MLT. Lstar is only computed when options[1] > 0 (NaN otherwise).

Arguments

Signature 1 (preferred):

• time: Date and time (DateTime, Vector{DateTime}, or String)
• x: Position as a 3-vector, a 3×n array, or a vector of 3-vectors (one per time). If x is a CoordinateVector (e.g. GDZ(...)) or a vector of them, omit coord.
• coord (optional): Coordinate system name, Symbol or type (default: "GDZ")
• kext (optional): External field model selection (default: KEXT[])
• options (optional): Model options (default: OPTIONS[])

Signature 2:

• model::MagneticField: The magnetic field model
• X: Dictionary with keys:
  • dateTime or Time: Date and time (DateTime or String)
  • x1, x2, x3: Position coordinates in the system specified by sysaxes

Common arguments:

• maginput: Named tuple, dictionary or MagInput with magnetic field model inputs (optional). Values are scalars (shared by all times) or vectors (one per time); unset inputs are missing (-9999).

Examples

julia> make_lstar("2015-02-02T06:12:43", GDZ(600.0, 60.0, 50.0), (; Kp = 40.0); kext = "T89")
(Lm = 3.5597242229067536, Lstar = NaN, Blocal = 42271.43059990003, Bmin = 626.2258295723121, XJ = 7.020585390925573, MLT = 10.170297893176182)

Reference: IRBEM API

landi2lstar(time, x, [coord="GDZ",] maginput=(; ); kext=KEXT[], options=OPTIONS[])
landi2lstar(model::MagneticField, X::AbstractDict, maginput=(; ))

Like make_lstar, but L* is deduced empirically from Lm, I and day of year, which is much faster. Errors in L* are below 2%. Valid for locally mirroring particles only. IRBEM forces IGRF + Olson-Pfitzer quiet (OPQ77), whatever kext and options[5] are.

Arguments

Signature 1 (preferred):

• time: Date and time (DateTime, Vector{DateTime}, or String)
• x: Position as a 3-vector, a 3×n array, or a vector of 3-vectors (one per time). If x is a CoordinateVector (e.g. GDZ(...)) or a vector of them, omit coord.
• coord (optional): Coordinate system name, Symbol or type (default: "GDZ")
• kext (optional): External field model selection (default: KEXT[])
• options (optional): Model options (default: OPTIONS[])

Signature 2:

• model::MagneticField: The magnetic field model
• X: Dictionary with keys:
  • dateTime or Time: Date and time (DateTime or String)
  • x1, x2, x3: Position coordinates in the system specified by sysaxes

Common arguments:

• maginput: Named tuple, dictionary or MagInput with magnetic field model inputs (optional). Values are scalars (shared by all times) or vectors (one per time); unset inputs are missing (-9999).

Reference: IRBEM API

get_mlt(𝐫, time)
get_mlt(time, 𝐫::AbstractVector)
get_mlt(x, y, z, time)
get_mlt(X::AbstractDict)

Get Magnetic Local Time (MLT) from a Cartesian GEO position 𝐫 and time. X is a dictionary with keys x1, x2, x3 (GEO position) and dateTime or Time.

get_hemi(time, x, [coord="GDZ",] maginput=(; ); kext=KEXT[], options=OPTIONS[])
get_hemi(model::MagneticField, X::AbstractDict, maginput=(; ))

Magnetic hemisphere of the input location: +1 northern, -1 southern, 0 invalid magnetic field.

Arguments

Signature 1 (preferred):

• time: Date and time (DateTime, Vector{DateTime}, or String)
• x: Position as a 3-vector, a 3×n array, or a vector of 3-vectors (one per time). If x is a CoordinateVector (e.g. GDZ(...)) or a vector of them, omit coord.
• coord (optional): Coordinate system name, Symbol or type (default: "GDZ")
• kext (optional): External field model selection (default: KEXT[])
• options (optional): Model options (default: OPTIONS[])

Signature 2:

• model::MagneticField: The magnetic field model
• X: Dictionary with keys:
  • dateTime or Time: Date and time (DateTime or String)
  • x1, x2, x3: Position coordinates in the system specified by sysaxes

Common arguments:

• maginput: Named tuple, dictionary or MagInput with magnetic field model inputs (optional). Values are scalars (shared by all times) or vectors (one per time); unset inputs are missing (-9999).

Reference: IRBEM API

find_mirror_point(time, x, alpha, [coord="GDZ",] maginput=(; ); kext=KEXT[], options=OPTIONS[])
find_mirror_point(model::MagneticField, X, alpha, maginput=(; ))

Find the magnitude and location of the mirror point along a field line traced from any given location and local pitch-angle.

Arguments

Signature 1 (preferred):

• time: Date and time (DateTime, Vector{DateTime}, or String)
• x: Position as a 3-vector, a 3×n array, or a vector of 3-vectors (one per time). If x is a CoordinateVector (e.g. GDZ(...)) or a vector of them, omit coord.
• coord (optional): Coordinate system name, Symbol or type (default: "GDZ")
• kext (optional): External field model selection (default: KEXT[])
• options (optional): Model options (default: OPTIONS[])

Signature 2:

• model::MagneticField: The magnetic field model
• X: Dictionary with keys:
  • dateTime or Time: Date and time (DateTime or String)
  • x1, x2, x3: Position coordinates in the system specified by sysaxes

Common arguments:

• maginput: Named tuple, dictionary or MagInput with magnetic field model inputs (optional). Values are scalars (shared by all times) or vectors (one per time); unset inputs are missing (-9999).

• alpha: Local pitch angle in degrees

Outputs

• Blocal: magnitude of magnetic field at point (nT)
• Bmirr: magnitude of the magnetic field at the mirror point (nT)
• posit (array of 3 double): GEO coordinates of the mirror point (Re)

References: IRBEM API

find_magequator(time, x, [coord="GDZ",] maginput=(; ); kext=KEXT[], options=OPTIONS[])
find_magequator(model::MagneticField, X::AbstractDict, maginput=(; ))

Find the coordinates of the magnetic equator from tracing the magnetic field line from the input location. Returns a named tuple with fields Bmin and XGEO (location of magnetic equator).

Arguments

Signature 1 (preferred):

• time: Date and time (DateTime, Vector{DateTime}, or String)
• x: Position as a 3-vector, a 3×n array, or a vector of 3-vectors (one per time). If x is a CoordinateVector (e.g. GDZ(...)) or a vector of them, omit coord.
• coord (optional): Coordinate system name, Symbol or type (default: "GDZ")
• kext (optional): External field model selection (default: KEXT[])
• options (optional): Model options (default: OPTIONS[])

Signature 2:

• model::MagneticField: The magnetic field model
• X: Dictionary with keys:
  • dateTime or Time: Date and time (DateTime or String)
  • x1, x2, x3: Position coordinates in the system specified by sysaxes

Common arguments:

• maginput: Named tuple, dictionary or MagInput with magnetic field model inputs (optional). Values are scalars (shared by all times) or vectors (one per time); unset inputs are missing (-9999).

find_foot_point(time, x, stop_alt, hemi_flag, [coord="GDZ",] maginput=(; ); kext=KEXT[], options=OPTIONS[])
find_foot_point(model::MagneticField, X, stop_alt, hemi_flag, maginput=(; ))

Find the footprint of a field line that passes through location X in a given hemisphere.

Arguments

Signature 1 (preferred):

• time: Date and time (DateTime, Vector{DateTime}, or String)
• x: Position as a 3-vector, a 3×n array, or a vector of 3-vectors (one per time). If x is a CoordinateVector (e.g. GDZ(...)) or a vector of them, omit coord.
• coord (optional): Coordinate system name, Symbol or type (default: "GDZ")
• kext (optional): External field model selection (default: KEXT[])
• options (optional): Model options (default: OPTIONS[])

Signature 2:

• model::MagneticField: The magnetic field model
• X: Dictionary with keys:
  • dateTime or Time: Date and time (DateTime or String)
  • x1, x2, x3: Position coordinates in the system specified by sysaxes

Common arguments:

• maginput: Named tuple, dictionary or MagInput with magnetic field model inputs (optional). Values are scalars (shared by all times) or vectors (one per time); unset inputs are missing (-9999).

• stop_alt: Altitude in km where to stop field line tracing

• hemi_flag: Hemisphere flag (0: same as SM z, +1: northern, -1: southern)

Outputs

• XFOOT: GDZ coordinates of the foot point (km, deg, deg)
• BFOOT: magnetic field vector (GEO) at the foot point (nT)
• BFOOTMAG: magnitude of the magnetic field at the foot point (nT)

References: IRBEM API

get_field_multi(time, x, [coord="GDZ",] maginput=(; ); kext=KEXT[], options=OPTIONS[])
get_field_multi(model::MagneticField, X::AbstractDict, maginput=(; ))

Compute the GEO vector of the magnetic field at input location for a set of internal/external magnetic field.

Arguments

Signature 1 (preferred):

• time: Date and time (DateTime, Vector{DateTime}, or String)
• x: Position as a 3-vector, a 3×n array, or a vector of 3-vectors (one per time). If x is a CoordinateVector (e.g. GDZ(...)) or a vector of them, omit coord.
• coord (optional): Coordinate system name, Symbol or type (default: "GDZ")
• kext (optional): External field model selection (default: KEXT[])
• options (optional): Model options (default: OPTIONS[])

Signature 2:

• model::MagneticField: The magnetic field model
• X: Dictionary with keys:
  • dateTime or Time: Date and time (DateTime or String)
  • x1, x2, x3: Position coordinates in the system specified by sysaxes

Common arguments:

• maginput: Named tuple, dictionary or MagInput with magnetic field model inputs (optional). Values are scalars (shared by all times) or vectors (one per time); unset inputs are missing (-9999).

Returns

• NamedTuple: Contains fields Bgeo (GEO components of B field) and Bmag (magnitude of B field)

get_bderivs(time, x, [coord="GDZ",] maginput=(; ); kext=KEXT[], options=OPTIONS[])
get_bderivs(model::MagneticField, X::AbstractDict, maginput=(; ))

Compute the magnetic field and its 1st-order derivatives at each input location.

Arguments

Signature 1 (preferred):

• time: Date and time (DateTime, Vector{DateTime}, or String)
• x: Position as a 3-vector, a 3×n array, or a vector of 3-vectors (one per time). If x is a CoordinateVector (e.g. GDZ(...)) or a vector of them, omit coord.
• coord (optional): Coordinate system name, Symbol or type (default: "GDZ")
• kext (optional): External field model selection (default: KEXT[])
• options (optional): Model options (default: OPTIONS[])

Signature 2:

• model::MagneticField: The magnetic field model
• X: Dictionary with keys:
  • dateTime or Time: Date and time (DateTime or String)
  • x1, x2, x3: Position coordinates in the system specified by sysaxes

Common arguments:

• maginput: Named tuple, dictionary or MagInput with magnetic field model inputs (optional). Values are scalars (shared by all times) or vectors (one per time); unset inputs are missing (-9999).

• dX: step size (Re) for the finite differences, placed right after the position

Returns

• NamedTuple: Contains fields Bgeo (GEO components of B field), Bmag (magnitude of B field), gradBmag (gradients of Bmag in GEO), and diffB (derivatives of the magnetic field vector).

Examples

julia> get_bderivs("2015-02-02T06:12:43", GDZ(600.0, 60.0, 50.0), 0.1, (; Kp = 40.0); kext = "T89") |> pprint
(Bgeo = [-21079.764883133903, -21504.21460705096, -29666.24532305791],
 Bmag = 42271.43059990003,
 gradBmag = [-49644.37271032293, -46030.37495428827, -83024.03530787815],
 diffB =
     [-13530.079906431165 31460.805163291334 53890.73134176735; 30427.464243221693 -16715.08632269888 50326.93737340687; 62620.43884602288 59981.93936448166 44395.53254933224])

trace_field_line(time, x, [coord="GDZ",] maginput=(; ); kext=KEXT[], options=OPTIONS[], R0=1.0)
trace_field_line(model::MagneticField, X::AbstractDict, maginput=(; ); R0=1.0)

Trace a full field line which crosses the input position until radial distance R0=1.0 (Re).

Outputs

• Lm: L McIlwain
• Blocal (array of Nposit double): magnitude of magnetic field at point (nT)
• Bmin: magnitude of magnetic field at equator (nT)
• XJ: I, related to second adiabatic invariant (Re)
• posit (array of (3, Nposit) double): Cartesian coordinates in GEO along the field line
• Nposit: number of points in posit

Reference: IRBEM API

drift_shell(time, x, [coord="GDZ",] maginput=(; ); kext=KEXT[], options=OPTIONS[])
drift_shell(model::MagneticField, X::AbstractDict, maginput=(; ))

Trace a full drift shell for particles that have their mirror point at the input location.

Outputs

• Lm: L McIlwain
• Lstar: L Roederer or Φ=2π Bo/L* (nT Re2), depending on the options value
• Blocal (array of (1000, 48)): magnitude of magnetic field at point (nT)
• Bmin: magnitude of magnetic field at equator (nT)
• XJ: I, related to second adiabatic invariant (Re)
• posit (array of (3, 1000, 48)): Cartesian coordinates in GEO along the drift shell
• Nposit (array of 48 integer): number of points in posit along each traced field line

Entries of posit and Blocal beyond Nposit are NaN.

Reference: IRBEM API

drift_bounce_orbit(time, x, [coord="GDZ",] maginput=(; ); kext=KEXT[], options=OPTIONS[], alpha=90, R0=1)
drift_bounce_orbit(model::MagneticField, X::AbstractDict, maginput=(; ); alpha=90, R0=1)

Trace a full drift-bounce orbit for particles with a specified pitch angle alpha=90 at the input location until radial distance R0=1.0 (Re). Returns only positions between mirror points, with 25 azimuths.

Outputs:

• Lm: L McIlwain
• Lstar: L Roederer or Φ=2π Bo/L* (nT Re2), depending on the options value
• Blocal (array of (1000, 25) double): magnitude of magnetic field at point (nT)
• Bmin: magnitude of magnetic field at equator (nT)
• Bmirr: magnitude of magnetic field at mirror point (nT)
• XJ: I, related to second adiabatic invariant (Re)
• posit (array of (3, 1000, 25) double): Cartesian coordinates in GEO along the drift shell
• Nposit (array of 25 integer): number of points in posit along each traced field line
• hmin, hmin_lon: GDZ altitude (km) and longitude (deg) of the lowest point of the drift shell, among all traced points

Entries of posit and Blocal beyond Nposit are NaN.

Reference: IRBEM API

transform(time, pos, in, out)
transform(time, pos, in => out)
transform(time, pos, "in2out")

Transform coordinates from in coordinate system to out coordinate system.

pos is of shape (3,) for a single point or (3, n) for n points, with one time per point.

Example

using Dates
using IRBEM

time = DateTime(2020, 1, 1)
pos = [6.90274, -1.63624, 1.91669]

GSM(time, GEO(pos))
transform(time, pos, "GEO", "GSM")
transform(time, pos, "GEO" => "GSM")
transform(time, pos, "geo2gsm")

Returns the version number of the IGRF model.

Provides the repository version number of the fortran source code.

Provides the repository release tag of the fortran source code.