apexpy.Apex

The Apex class is used for all the main functionality (converting between coordinate systems, field line mapping, and calculating base vectors).

class apexpy.Apex(date=None, refh=0, datafile=None)[source]

Performs coordinate conversions, field-line mapping and base vector calculations.

Parameters:
  • date (float (decimal year) or datetime.date or datetime.datetime, optional) – Determines which IGRF coefficients are used in conversions. Uses current date as default.
  • 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
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

Notes

The calculations use IGRF-12 with coefficients from 1900 to 2020 [1].

References

[1]Thébault, 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.
convert(lat, lon, source, dest, height=0, datetime=None, precision=1e-10, ssheight=318550)[source]

Converts between geodetic, modified apex, quasi-dipole and MLT.

Parameters:
  • lat (array_like) – Latitude
  • lon (array_like) – Longitude/MLT
  • source ({‘geo’, ‘apex’, ‘qd’, ‘mlt’}) – Input coordinate system
  • dest ({‘geo’, ‘apex’, ‘qd’, ‘mlt’}) – Output coordinate system
  • height (array_like, optional) – Altitude in km
  • datetime (datetime.datetime) – Date and time for MLT conversions (required for MLT conversions)
  • precision (float, optional) – Precision of output (degrees) when converting to geo. A negative value of this argument produces a low-precision calculation of geodetic lat/lon based only on their spherical harmonic representation. A positive value causes the underlying Fortran routine to iterate until feeding the output geo lat/lon into geo2qd (APXG2Q) reproduces the input QD lat/lon to within the specified precision (all coordinates being converted to geo are converted to QD first and passed through APXG2Q).
  • ssheight (float, optional) – Altitude in km to use for converting the subsolar point from geographic to magnetic coordinates. A high altitude is used to ensure the subsolar point is mapped to high latitudes, which prevents the South-Atlantic Anomaly (SAA) from influencing the MLT.
Returns:

  • lat (ndarray or float) – Converted latitude (if converting to MLT, output latitude is apex)
  • lat (ndarray or float) – Converted longitude/MLT

geo2apex(glat, glon, height)[source]

Converts geodetic to modified apex coordinates.

Parameters:
  • glat (array_like) – Geodetic latitude
  • glon (array_like) – Geodetic longitude
  • height (array_like) – Altitude in km
Returns:

  • alat (ndarray or float) – Modified apex latitude
  • alon (ndarray or float) – Modified apex longitude

apex2geo(alat, alon, height, precision=1e-10)[source]

Converts modified apex to geodetic coordinates.

Parameters:
  • alat (array_like) – Modified apex latitude
  • alon (array_like) – Modified apex longitude
  • height (array_like) – Altitude in km
  • precision (float, optional) – Precision of output (degrees). A negative value of this argument produces a low-precision calculation of geodetic lat/lon based only on their spherical harmonic representation. A positive value causes the underlying Fortran routine to iterate until feeding the output geo lat/lon into geo2qd (APXG2Q) reproduces the input QD lat/lon to within the specified precision.
Returns:

  • glat (ndarray or float) – Geodetic latitude
  • glon (ndarray or float) – Geodetic longitude
  • error (ndarray or float) – The angular difference (degrees) between the input QD coordinates and the qlat/qlon produced by feeding the output glat and glon into geo2qd (APXG2Q)

geo2qd(glat, glon, height)[source]

Converts geodetic to quasi-dipole coordinates.

Parameters:
  • glat (array_like) – Geodetic latitude
  • glon (array_like) – Geodetic longitude
  • height (array_like) – Altitude in km
Returns:

  • qlat (ndarray or float) – Quasi-dipole latitude
  • qlon (ndarray or float) – Quasi-dipole longitude

qd2geo(qlat, qlon, height, precision=1e-10)[source]

Converts quasi-dipole to geodetic coordinates.

Parameters:
  • qlat (array_like) – Quasi-dipole latitude
  • qlon (array_like) – Quasi-dipole longitude
  • height (array_like) – Altitude in km
  • precision (float, optional) – Precision of output (degrees). A negative value of this argument produces a low-precision calculation of geodetic lat/lon based only on their spherical harmonic representation. A positive value causes the underlying Fortran routine to iterate until feeding the output geo lat/lon into geo2qd (APXG2Q) reproduces the input QD lat/lon to within the specified precision.
Returns:

  • glat (ndarray or float) – Geodetic latitude
  • glon (ndarray or float) – Geodetic longitude
  • error (ndarray or float) – The angular difference (degrees) between the input QD coordinates and the qlat/qlon produced by feeding the output glat and glon into geo2qd (APXG2Q)

apex2qd(alat, alon, height)[source]

Converts modified apex to quasi-dipole coordinates.

Parameters:
  • alat (array_like) – Modified apex latitude
  • alon (array_like) – Modified apex longitude
  • height (array_like) – Altitude in km
Returns:

  • qlat (ndarray or float) – Quasi-dipole latitude
  • qlon (ndarray or float) – Quasi-dipole longitude

Raises:

ApexHeightError – if height > apex height

qd2apex(qlat, qlon, height)[source]

Converts quasi-dipole to modified apex coordinates.

Parameters:
  • qlat (array_like) – Quasi-dipole latitude
  • qlon (array_like) – Quasi-dipole longitude
  • height (array_like) – Altitude in km
Returns:

  • alat (ndarray or float) – Modified apex latitude
  • alon (ndarray or float) – Modified apex longitude

Raises:

ApexHeightError – if apex height < reference height

mlon2mlt(mlon, datetime, ssheight=318550)[source]

Computes the magnetic local time at the specified magnetic longitude and UT.

Parameters:
  • mlon (array_like) – Magnetic longitude (apex and quasi-dipole longitude are always equal)
  • datetime (datetime.datetime) – Date and time
  • ssheight (float, optional) – Altitude in km to use for converting the subsolar point from geographic to magnetic coordinates. A high altitude is used to ensure the subsolar point is mapped to high latitudes, which prevents the South-Atlantic Anomaly (SAA) from influencing the MLT.
Returns:

mlt (ndarray or float) – Magnetic local time [0, 24)

Notes

To compute the MLT, we find the apex longitude of the subsolar point at the given time. Then the MLT of the given point will be computed from the separation in magnetic longitude from this point (1 hour = 15 degrees).

mlt2mlon(mlt, datetime, ssheight=318550)[source]

Computes the magnetic longitude at the specified magnetic local time and UT.

Parameters:
  • mlt (array_like) – Magnetic local time
  • datetime (datetime.datetime) – Date and time
  • ssheight (float, optional) – Altitude in km to use for converting the subsolar point from geographic to magnetic coordinates. A high altitude is used to ensure the subsolar point is mapped to high latitudes, which prevents the South-Atlantic Anomaly (SAA) from influencing the MLT.
Returns:

mlon (ndarray or float) – Magnetic longitude [0, 360) (apex and quasi-dipole longitude are always equal)

Notes

To compute the magnetic longitude, we find the apex longitude of the subsolar point at the given time. Then the magnetic longitude of the given point will be computed from the separation in magnetic local time from this point (1 hour = 15 degrees).

map_to_height(glat, glon, height, newheight, conjugate=False, precision=1e-10)[source]

Performs mapping of points along the magnetic field to the closest or conjugate hemisphere.

Parameters:
  • glat (array_like) – Geodetic latitude
  • glon (array_like) – Geodetic longitude
  • height (array_like) – Source altitude in km
  • newheight (array_like) – Destination altitude in km
  • conjugate (bool, optional) – Map to newheight in the conjugate hemisphere instead of the closest hemisphere
  • precision (float, optional) – Precision of output (degrees). A negative value of this argument produces a low-precision calculation of geodetic lat/lon based only on their spherical harmonic representation. A positive value causes the underlying Fortran routine to iterate until feeding the output geo lat/lon into geo2qd (APXG2Q) reproduces the input QD lat/lon to within the specified precision.
Returns:

  • newglat (ndarray or float) – Geodetic latitude of mapped point
  • newglon (ndarray or float) – Geodetic longitude of mapped point
  • error (ndarray or float) – The angular difference (degrees) between the input QD coordinates and the qlat/qlon produced by feeding the output glat and glon into geo2qd (APXG2Q)

Notes

The mapping is done by converting glat/glon/height to modified apex lat/lon, and converting back to geographic using newheight (if conjugate, use negative apex latitude when converting back)

map_E_to_height(alat, alon, height, newheight, E)[source]

Performs mapping of electric field along the magnetic field.

It is assumed that the electric field is perpendicular to B.

Parameters:
  • alat ((N,) array_like or float) – Modified apex latitude
  • alon ((N,) array_like or float) – Modified apex longitude
  • height ((N,) array_like or float) – Source altitude in km
  • newheight ((N,) array_like or float) – Destination altitude in km
  • E ((3,) or (3, N) array_like) – Electric field (at alat, alon, height) in geodetic east, north, and up components
Returns:

E ((3, N) or (3,) ndarray) – The electric field at newheight (geodetic east, north, and up components)

map_V_to_height(alat, alon, height, newheight, V)[source]

Performs mapping of electric drift velocity along the magnetic field.

It is assumed that the electric field is perpendicular to B.

Parameters:
  • alat ((N,) array_like or float) – Modified apex latitude
  • alon ((N,) array_like or float) – Modified apex longitude
  • height ((N,) array_like or float) – Source altitude in km
  • newheight ((N,) array_like or float) – Destination altitude in km
  • V ((3,) or (3, N) array_like) – Electric drift velocity (at alat, alon, height) in geodetic east, north, and up components
Returns:

V ((3, N) or (3,) ndarray) – The electric drift velocity at newheight (geodetic east, north, and up components)

basevectors_qd(lat, lon, height, coords='geo', precision=1e-10)[source]

Returns quasi-dipole base vectors f1 and f2 at the specified coordinates.

The vectors are described by Richmond [1995] [2] and Emmert et al. [2010] [3]. The vector components are geodetic east and north.

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’, ‘qd’}, optional) – Input coordinate system
  • precision (float, optional) – Precision of output (degrees) when converting to geo. A negative value of this argument produces a low-precision calculation of geodetic lat/lon based only on their spherical harmonic representation. A positive value causes the underlying Fortran routine to iterate until feeding the output geo lat/lon into geo2qd (APXG2Q) reproduces the input QD lat/lon to within the specified precision (all coordinates being converted to geo are converted to QD first and passed through APXG2Q).
Returns:

  • f1 ((2, N) or (2,) ndarray)
  • f2 ((2, N) or (2,) ndarray)

References

[2]Richmond, A. D. (1995), Ionospheric Electrodynamics Using Magnetic Apex Coordinates, Journal of geomagnetism and geoelectricity, 47(2), 191–212, doi:10.5636/jgg.47.191.
[3]Emmert, J. T., A. D. Richmond, and D. P. Drob (2010), A computationally compact representation of Magnetic-Apex and Quasi-Dipole coordinates with smooth base vectors, J. Geophys. Res., 115(A8), A08322, doi:10.1029/2010JA015326.
basevectors_apex(lat, lon, height, coords='geo', precision=1e-10)[source]

Returns base vectors in quasi-dipole and apex coordinates.

The vectors are described by Richmond [1995] [4] and Emmert et al. [2010] [5]. The vector components are geodetic east, north, and up (only east and north for f1 and f2).

Parameters:
  • lat, lon ((N,) array_like or float) – Latitude
  • lat ((N,) array_like or float) – Longitude
  • height ((N,) array_like or float) – Altitude in km
  • coords ({‘geo’, ‘apex’, ‘qd’}, optional) – Input coordinate system
  • return_all (bool, optional) – Will also return f3, g1, g2, and g3, and f1 and f2 have 3 components (the last component is zero). Requires lat, lon, and height to be broadcast to 1D (at least one of the parameters must be 1D and the other two parameters must be 1D or 0D).
  • precision (float, optional) – Precision of output (degrees) when converting to geo. A negative value of this argument produces a low-precision calculation of geodetic lat/lon based only on their spherical harmonic representation. A positive value causes the underlying Fortran routine to iterate until feeding the output geo lat/lon into geo2qd (APXG2Q) reproduces the input QD lat/lon to within the specified precision (all coordinates being converted to geo are converted to QD first and passed through APXG2Q).
Returns:

  • f1, f2 ((2, N) or (2,) ndarray)
  • f3, g1, g2, g3, d1, d2, d3, e1, e2, e3 ((3, N) or (3,) ndarray)

Note

f3, g1, g2, and g3 are not part of the Fortran code by Emmert et al. [2010] [5]. They are calculated by this Python library according to the following equations in Richmond [1995] [4]:

  • g1: Eqn. 6.3
  • g2: Eqn. 6.4
  • g3: Eqn. 6.5
  • f3: Eqn. 6.8

References

[4](1, 2) Richmond, A. D. (1995), Ionospheric Electrodynamics Using Magnetic Apex Coordinates, Journal of geomagnetism and geoelectricity, 47(2), 191–212, doi:10.5636/jgg.47.191.
[5](1, 2) Emmert, J. T., A. D. Richmond, and D. P. Drob (2010), A computationally compact representation of Magnetic-Apex and Quasi-Dipole coordinates with smooth base vectors, J. Geophys. Res., 115(A8), A08322, doi:10.1029/2010JA015326.
get_apex(alat)[source]

Computes the field line apex for a given modified apex latitude.

Parameters:alat (array_like) – Modified apex latitude
Returns:apex (ndarray or float) – Field line apex in km
set_epoch(year)[source]

Updates the epoch for all subsequent conversions.

Parameters:year (float) – Decimal year
set_refh(refh)[source]

Updates the apex reference height for all subsequent conversions.

Parameters:refh (float) – Apex reference height in km

Notes

The reference height is the height to which field lines will be mapped, and is only relevant for conversions involving apex (not quasi-dipole).