harmonica.IGRF14

class harmonica.IGRF14(date, min_degree=1, max_degree=13, ellipsoid=Ellipsoid(name='WGS84', semimajor_axis=6378137, flattening=0.0033528106647474805, geocentric_grav_const=398600441800000.0, angular_velocity=7.292115e-05, long_name='World Geodetic System (1984)', reference='Hofmann-Wellenhof, B., & Moritz, H. (2006). Physical Geodesy (2nd, corr. ed. 2006 edition ed.). Wien; New York: Springer.', comments=None))

International Geomagnetic Reference Field (14th generation).

Calculate the three components of the magnetic field vector of the IGRF model in a geodetic (longitude, latitude, geometric height) system for any date between 1900 and 2030. Model coefficients are automatically downloaded and cached locally using pooch.

Note

The code is automatically parallelized (multithreaded shared-memory) with Numba. To evaluate the model on a regular grid, it’s at least 2x faster to use the grid method than the predict method since the former is able to avoid repeat computations.

Parameters:

datestr or datetime.datetime

The date and time at which to calculate the IGRF field. If it’s a string, should be an ISO 8601 formatted date and it will be converted into a Python datetime.datetime. Must be on or after 1900 and before 2030.

min_degreeint

The minimum degree used in the expansion. Default is 1 (magnetic fields don’t have the 0 degree term).

max_degreeint

The maximum degree used in the expansion. Default is 13.

ellipsoidboule.Ellipsoid

The ellipsoid used to convert geodetic to geocentric spherical coordinates and convert the magnetic field vector from a geocentric spherical to a geodetic system. Default is boule.WGS84.

Notes

The IGRF is a spherical harmonic model of the Earth’s internal magnetic field. Its time variation is represented by piecewise linear functions. In practice, the model Gauss coefficients are provided in 5-year epochs and can be linearly interpolated between two epochs. For years later than the last epoch, the coefficients can be extrapolated linearly using the provided estimates of secular variation for each Gauss coefficient.

The 3-component magnetic field vector in a geocentric spherical coordinate system (longitude, spherical colatitude, radius) system can be expressed in terms of spherical harmonics as:

\[B_e(r, \theta, \lambda) = -\dfrac{1}{\sin\theta} \sum\limits_{n=1}^{N}\sum\limits_{m=0}^{n} \left(\dfrac{R}{r}\right)^{n+2} [ -m g_n^m \sin m\lambda + m h_n^m \cos m\lambda ] P_n^m(\cos\theta)\]

\[B_n(r, \theta, \lambda) = \sum\limits_{n=1}^{N}\sum\limits_{m=0}^{n} \left(\dfrac{R}{r}\right)^{n+2} [ g_n^m \cos m\lambda + h_n^m \sin m\lambda ] \dfrac{\partial P_n^m(\cos\theta)}{\partial \theta}\]

\[B_r(r, \theta, \lambda) = \sum\limits_{n=1}^{N}\sum\limits_{m=0}^{n} (n + 1)\left(\dfrac{R}{r}\right)^{n+2} [ g_n^m \cos m\lambda + h_n^m \sin m\lambda ] P_n^m(\cos\theta)\]

in which \(B_e\) is the easting/longitudinal component, \(B_n\) is the northing/latitudinal component, \(B_r\) is the radial component, \(r\) is the radius coordinate, \(\theta\) is the colatitude, \(\lambda\) is the longitude, \(n\) is the degree, \(m\) is the order, \(P_n^m\) are associated Legendre functions, and \(g_n^m\) and \(h_n^m\) are the Gauss coefficients.

The vector is converted to a geodetic system (longitude, latitude, height/upward) using the following rotation:

\[B_{n}^{geodetic} = \cos(\varphi - \phi) B_n + \sin(\varphi - \phi) B_r\]

\[B_{u} = -\sin(\varphi - \phi) B_n + \cos(\varphi - \phi) B_r\]

in which \(\varphi\) is the spherical latitude and \(\phi\) is the geodetic latitude.

References

[Alken2021]

[IAGA2024]

Attributes:

doistr

The DOI used to download the coefficient file.

file_namestr

The name of the coefficient file in the online archive.

hashstr

The hash of the coefficient file, used to check download integrity.

reference_radiusfloat

The reference radius used in the spherical harmonic expansion in meters.

coefficientstuple = (g, h)

The g and h Gauss coefficients interpolated to the given date. Each coefficient is a 2d-array with shape (max_degree + 1, max_degree + 1). The degree n varies with rows and the order m varies with columns. The values where m > n are set to zero.

Methods

grid(region, height[, shape, spacing, adjust])	Generate a grid of the IGRF magnetic field vector.
predict(coordinates)	Calculate the IGRF magnetic field vector at the given coordinates.

IGRF14.grid(region, height, shape=None, spacing=None, adjust='spacing')

Generate a grid of the IGRF magnetic field vector.

Predict the magnetic field vector on a regular grid of geodetic coordinates. This is much faster than using predict to predict on the same points because we are able to reduce repeated calculations when we know the data are on a regular grid.

If neither a spacing nor a shape are given, will estimate the optimal grid spacing for the maximum degree used using the sampling theorem of [DriscollHealy1994].

Parameters:

regiontuple = (W, E, S, N)

The boundaries of the grid in geographic coordinates. Should have a lower and an upper boundary for each dimension of the coordinate system. If region is not given, will use the bounding region of the given coordinates. Units are degrees.

height2d-array or float

The geometric height above the reference ellipsoid where the magnetic field will be calculated. Units are meters.

shapetuple = (size_SN, size_WE) or None

The number of points in each direction of the given region, in reverse order. Must have one integer value per dimension of the region. The order of arguments is the opposite of the order of the region for compatibility with numpy’s .shape attribute. If None, spacing must be provided. Default is None.

spacingfloat, tuple = (space_SN, space_WE), or None

The grid spacing in each direction of the given region, in reverse order. A single value means that the spacing is equal in all directions. If a tuple, must have one value per dimension of the region. The order of arguments is the opposite of the order of the region for compatibility with shape. If None, shape must be provided. Default is None. Units are degrees.

adjuststr = “spacing” or “region”

Whether to adjust the spacing or the region if the spacing is not a multiple of the region. Ignored if shape is given instead of spacing. Default is "spacing".

Returns:

gridxarray.Dataset

A collection of the grids of the eastward (b_east), northward (b_north), and upward (b_up) components of the magnetic field. Each has dimensions of latitude and longitude and the height as a non-dimensional coordinate. Grid points are grid-line registered.

IGRF14.predict(coordinates)

Calculate the IGRF magnetic field vector at the given coordinates.

The field is evaluated using the given minimum and maximum degrees. The input coordinates are assumed to be in a geodetic coordinate system and are converted to geocentric spherical with the given ellipsoid. The output vector is rotated to the geodetic system with the horizontal components tangential to the ellipsoid and the upward component parallel to the ellipsoid normal.

Parameters:

coordinatestuple = (longitude, latitude, height)

Tuple of arrays with the longitude, latitude, and height coordinates of each point. Arrays can be Python lists or any numpy-compatible array type. Arrays can be of any shape but must all have the same shape. Longitude and latitude are in degrees and height in meters.

Returns:

be, bn, buarrays

The eastward, northward, and upward magnetic field vector components calculated at each point. The arrays will have the same shape as the coordinate arrays. All are in nT.

---