Reference

API description for marppy functions.

class marppy.Marp(*args: Any, **kwargs: Any)

Performs coordinate conversions and base vector calculations. Inherets apexpy.Apex class.

Parameters:

• date (float, dt.date, or dt.datetime, optional) – Determines which IGRF coefficients are used in conversions. Uses current date as default. If float, use decimal year.

• refh (float, optional) – Reference height in km for apex coordinates (the field lines are mapped to this height)

• datafile (str, optional) – Path to custom coefficient file

• pole (list, optional) – Location of the new northern pole in Apex or geodetic coordinates plus the rotation angle around that pole (all in degrees)

• null (list, optional) – Location of the new null island ((0,0) point) in Apex or geodetic coordinates plus the bearing angle of new north (all in degrees)

• alt (float, optional) – Altitude of MARP origin location if it is specified in geodetic coordinates (defaults to the refence height)

• coords (str, optional) – Coordinate system MARP origin is specified in

Variables:

• year (float) – Decimal year used for the IGRF model

• refh (float) – Reference height in km for apex coordinates

• datafile (str) – Path to coefficient file

• lam0 (float) – Apex latitude of the MARP north pole

• phi0 (float) – Apex longitude of the MARP north pole

• tau0 (float) – Final rotation about MARP north pole

• R ((3,3) ndarray) – Rotation matrix to transform from Apex to MARP

Notes

The calculations use IGRF-13 with coefficients from 1900 to 2025 [1]. The geodetic reference ellipsoid is WGS84.

References

[1]

Thebault, E. et al. (2015), International Geomagnetic Reference Field: the 12th generation, Earth, Planets and Space, 67(1), 79, doi:10.1186/s40623-015-0228-9.

null2pole(null)

Calculate pole location from null location. This makes use of the Haversine formulation and Law of Spherical Cosines.

Parameters:

null (list) – Location of the null island ((0,0) point) in Apex coordinates plus the bearing angle of north (all in degrees)

Returns:

pole (list) – Location of the northern pole in Apex coordinates plus the rotation angle around that pole (all in degrees)

rotation_matrix(lam0, phi0, tau0)

Calculate the Rotation Matrix.

Parameters:

• lam0 (float) – Apex latitude of the MARP north pole

• phi0 (float) – Apex longitude of the MARP north pole

• tau0 (float) – Final rotation about MARP north pole

Returns:

R ((3,3) ndarray) – Rotation matrix to transform from Apex to MARP

apex2marp(alat, alon)

Converts Apex to MARP coordinates.

Parameters:

• alat (array_like) – Apex latitude

• alon (array_like) – Apex longitude

Returns:

• mlat (ndarray or float) – MARP latitude

• mlon (ndarray or float) – MARP longitude

marp2apex(mlat, mlon)

Converts MARP to Apex coordinates.

Parameters:

• mlat (ndarray or float) – MARP latitude

• mlon (ndarray or float) – MARP longitude

Returns:

• alat (array_like) – Apex latitude

• alon (array_like) – Apex longitude

geo2marp(glat, glon, height)

Converts Geodetic to MARP coordinates.

Parameters:

• glat (ndarray or float) – Geodetic latitude

• glon (ndarray or float) – Geodetic longitude

• height (array_like) – Altitude in km

Returns:

• mlat (ndarray or float) – MARP latitude

• mlon (ndarray or float) – MARP longitude

marp2geo(mlat, mlon, height)

Converts MARP to Geodetic coordinates.

Parameters:

• mlat (ndarray or float) – MARP latitude

• mlon (ndarray or float) – MARP longitude

• height (array_like) – Altitude in km

Returns:

• glat (ndarray or float) – Geodetic latitude

• glon (ndarray or float) – Geodetic longitude

• err (ndarray or float) – Error returned by apexpy.Apex.apex2geo

basevectors_marp(lat, lon, height, coords='geo')

Get MARP base vectors d1, d2, d3 and e1, e2, e3 at the specified coordinates.

Parameters:

• lat ((N,) array_like or float) – Latitude

• lon ((N,) array_like or float) – Longitude

• height ((N,) array_like or float) – Altitude in km

• coords ({‘geo’, ‘apex’}, optional) – Input coordinate system

Returns:

• d1 ((3, N) or (3,) ndarray) – MARP base vector normal to contours of constant PhiM

• d2 ((3, N) or (3,) ndarray) – MARP base vector normal to contours of constant LamM

• d3 ((3, N) or (3,) ndarray) – MARP base vector normal to contours of constant V0

• e1 ((3, N) or (3,) ndarray) – MARP base vector tangent to contours of constant LamM

• e2 ((3, N) or (3,) ndarray) – MARP base vector tangent to contours of constant PhiM

• e3 ((3, N) or (3,) ndarray) – MARP base vector tangent to magnetic field