Geomagnetic Field

IGRF 14

Geomagnetic Model: International Geomagnetic Reference Field (IGRF) v14.

Attributes

Functions:

get_geocentric_igrf

Python

get_geocentric_igrf(coordinates: NDArray[floating], date: datetime, min_degree: int = 1, max_degree: int = 13) -> npt.NDArray[np.floating]

Evaluate the IGRF magnetic field in geocentric coordinates.

Parameters:

Name	Type	Description	Default
`coordinates`	`NDArray[floating]`	geocentric coordinates with shape (N, 3) or (3,), where 3 corresponds to `radius [km]`, `colatitude [degrees]` and `longitude [degrees]`	required
`date`	`datetime`	the date of the evaluation	required
`min_degree`	`int`	lowest spherical harmonic degree, by default 1	`1`
`max_degree`	`int`	highest spherical harmonic degree, by default 13	`13`

Returns:

Type	Description
`NDArray[floating]`	magnetic field components [nT] at the given coordinates with shape (N, 3) or (3,), where 3 corresponds to `Br (radial)`, `B_theta (southward)` and `B_phi (eastward)`

get_geodetic_igrf

Python

get_geodetic_igrf(coordinates: NDArray[floating], date: datetime, min_degree: int = 1, max_degree: int = 13) -> npt.NDArray[np.floating]

Evaluate the IGRF magnetic field in geodetic coordinates.

Geodetic coordinates account for the ellipsoidal shape of the Earth using WGS84 model. The northward component is tangential to the ellipsoid, and the upward component is perpendicular to it.

Parameters:

Name	Type	Description	Default
`coordinates`	`NDArray[floating]`	geodetic coordinates with shape (N, 3) or (3,), where 3 corresponds to `longitude [degrees]`, `latitude [degrees]` and `height [km above WGS84 ellipsoid]`	required
`date`	`datetime`	the date of the evaluation	required
`min_degree`	`int`	lowest spherical harmonic degree, by default 1	`1`
`max_degree`	`int`	highest spherical harmonic degree, by default 13	`13`

Returns:

Type	Description
`NDArray[floating]`	magnetic field components [nT] at the given coordinates with shape (N, 3) or (3,), where 3 corresponds to `Be (eastward)`, `Bn (northward, tangential to the ellipsoid)` and `Bu (upward, perpendicular to the ellipsoid)`

get_geocentric_igrf_potential

Python

get_geocentric_igrf_potential(coordinates: NDArray[floating], date: datetime, min_degree: int = 1, max_degree: int = 13) -> float | npt.NDArray[np.floating]

Evaluate the IGRF magnetic potential in geocentric coordinates.

The magnetic potential \(V\) satisfies \(\mathbf{B} = -\nabla V\) and is expanded in spherical harmonics up to degree 13.

Parameters:

Name	Type	Description	Default
`coordinates`	`NDArray[floating]`	geocentric coordinates with shape (N, 3) or (3,), where 3 corresponds to `radius [km]`, `colatitude [degrees]` and `longitude [degrees]`	required
`date`	`datetime`	the date of the evaluation	required
`min_degree`	`int`	lowest spherical harmonic degree, by default 1	`1`
`max_degree`	`int`	highest spherical harmonic degree, by default 13	`13`

Returns:

Type	Description
`float \| NDArray[floating]`	magnetic potential [nT km], with shape (N,) or scalar

Utilities

IGRF: utilities functions.

Functions:

get_legendre

Python

get_legendre(theta: NDArray[floating], keys: list[tuple[int, int]]) -> tuple[npt.NDArray[np.floating], npt.NDArray[np.floating]]

Calculate Schmidt semi-normalized associated Legendre functions.

Calculations based on recursive algorithm referring to "Spacecraft attitude determination and control" by Wertz, James R., 1978, https://doi.org/10.1007/978-94-009-9907-7

Parameters:

Name	Type	Description	Default
`theta`	`NDArray[floating]`	colatitudes in degrees, with shape (N,)	required
`keys`	`list[tuple[int, int]]`	list of spherical harmonic degree[0] and order[1], tuple (n, m) for each term in the expansion	required

Returns:

Type	Description
`NDArray[floating]`	Legendre functions (P), with shape (N, len(keys))
`NDArray[floating]`	dP/d_theta, with shape (N, len(keys))

get_magnetic_inclination

Python

get_magnetic_inclination(geodetic_magnetic_field: NDArray[floating], degrees: bool = True) -> npt.NDArray[np.floating]

Compute the magnetic inclination angles of the IGRF from magnetic field components in geodetic coordinates.

Inclination angle is defined as the angle between the magnetic field vector and the horizontal plane:

\[ I = \arctan \left(\frac{-B_u}{\sqrt{B_e^2 + B_n^2}}\right) \]

Parameters:

Name	Type	Description	Default
`geodetic_magnetic_field`	`NDArray[floating]`	magnetic field components [nT] with shape (N, 3) or (3,), where 3 corresponds to `Be (eastward)`, `Bn (northward, tangential to the ellipsoid)` and `Bu (upward, perpendicular to the ellipsoid)`	required
`degrees`	`bool`	flag to return the angles in degrees, by default True	`True`

Returns:

Type	Description
`NDArray[floating]`	inclination angle of the IGRF magnetic vector [degrees] or [radians], with shape (N,) or scalar

get_magnetic_declination

Python

get_magnetic_declination(geodetic_magnetic_field: NDArray[floating], degrees: bool = True) -> npt.NDArray[np.floating]

Compute the magnetic declination angles of the IGRF from magnetic field components in geodetic coordinates.

Declination angle is defined as the azimuth of the projection of the magnetic field vector onto the horizontal plane (starting from the northing direction, positive to the east and negative to the west):

\[ D = \arctan2\left(B_e, B_n\right) \]

Parameters:

Name	Type	Description	Default
`geodetic_magnetic_field`	`NDArray[floating]`	magnetic field components [nT] with shape (N, 3) or (3,), where 3 corresponds to `Be (eastward)`, `Bn (northward, tangential to the ellipsoid)` and `Bu (upward, perpendicular to the ellipsoid)`	required
`degrees`	`bool`	flag to return the angles in degrees, by default True	`True`

Returns:

Type	Description
`NDArray[floating]`	declination angle of the IGRF magnetic vector [degrees] or [radians], with shape (N,) or scalar