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, fortranlib=None)[source]¶ Performs coordinate conversions, field-line mapping and base vector calculations.
- Parameters
date (float,
dt.date
, ordt.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
- 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-13 with coefficients from 1900 to 2025 1.
The geodetic reference ellipsoid is WGS84.
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 timessheight (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 timessheight (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 ((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
f3, g1, g2, g3, d1, d2, d3, e1, e2, e3 ((3, N) or (3,) ndarray)
Notes
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,3,4,5)
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,3,4)
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
(lat, height=None)[source]¶ Calculate apex height
- Parameters
lat ((float)) – Latitude in degrees
height ((float or NoneType)) – Height above the surface of the earth in km or NoneType to use reference height (default=None)
- Returns
apex_height ((float)) – Height of the 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).
-
get_babs
(glat, glon, height)[source]¶ Returns the magnitude of the IGRF magnetic field in tesla.
- Parameters
glat (array_like) – Geodetic latitude
glon (array_like) – Geodetic longitude
height (array_like) – Altitude in km
- Returns
babs (ndarray or float) – Magnitude of the IGRF magnetic field
-
bvectors_apex
(lat, lon, height, coords='geo', precision=1e-10)[source]¶ Returns the magnetic field vectors in apex coordinates.
The apex magnetic field vectors described by Richmond [1995] 4 and Emmert et al. [2010] 5, specfically the Be3 and Bd3 components. The vector components are geodetic east, north, and up.
- 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
Be3 ((1, N) or (1,) ndarray)
e3 ((3, N) or (3,) ndarray)
Bd3 ((1, N) or (1,) ndarray)
d3 ((3, N) or (3,) ndarray)
Notes
Be3 is not equivalent to the magnitude of the IGRF magnitude, but is instead equal to the IGRF magnitude divided by a scaling factor, D. Similarly, Bd3 is the IGRF magnitude multiplied by D.
See Richmond, A. D. (1995) 4 equations 3.13 and 3.14
References