aacgm2

These functions are available when you import aacgm2.

aacgm2.convert(lat, lon, alt, date=None, a2g=False, trace=False, allowtrace=False, badidea=False, geocentric=False)[source]

Converts to/from geomagnetic coordinates.

This is a user-friendly pythonic wrapper for the low-level C interface functions available in aacgm2._aacgmv2.

Parameters:
  • lat,lon,alt (array_like) – Input latitude(s), longitude(s) and altitude(s). They must be broadcastable to the same shape.
  • date (datetime.date/datetime.datetime, optional) – The date/time to use for the magnetic field model, default None (uses current time). Must be between 1900 and 2020.
  • a2g (bool, optional) – Convert from AACGM-v2 to geographic coordinates, default False (converts geographic to AACGM-v2).
  • trace (bool, optional) – Use field-line tracing, default False (uses coefficients). Tracing is more precise and needed at altitudes > 2000 km, but significantly slower.
  • allowtrace (bool, optional) – Automatically use field-line tracing above 2000 km, default False (raises an exception for these altitudes unless trace=True or badidea=True).
  • badidea (bool, optional) – Allow use of coefficients above 2000 km (bad idea!)
  • geocentric (bool, optional) – Assume inputs are geocentric with Earth radius 6371.2 km.
Returns:

  • lat_out (numpy.ndarray) – Converted latitude
  • lon_out (numpy.ndarray) – Converted longitude
  • alt_out (numpy.ndarray) – Converted altitude
Raises:
  • ValueError – if max(alt) > 2000 and neither of trace, allowtrace, or badidea is True
  • ValueError – if latitude is outside the range -90 to +90 degrees
  • RuntimeError – if there was a problem in the C extension

Notes

This function exclusively relies on the AACGM-v2 C library. Specifically, it calls the functions _aacgmv2.setDateTime() and _aacgmv2.aacgmConvert(), which are simple interfaces to the C library functions AACGM_v2_SetDateTime() and AACGM_v2_Convert(). Details of the techniques used to derive the AACGM-v2 coefficients are described by Shepherd, 2014 [1].

[1]Shepherd, S. G. (2014), Altitude-adjusted corrected geomagnetic coordinates: Definition and functional approximations, J. Geophys. Res. Space Physics, 119, 7501–7521, doi:10.1002/2014JA020264.
aacgm2.convert_mlt(arr, datetime, m2a=False)[source]

Converts between magnetic local time (MLT) and AACGM-v2 longitude.

Note

This function is not related to the AACGM-v2 C library, but is provided as a convenience in the hopes that it might be useful for some purposes.

Parameters:
  • arr (array_like or float) – Magnetic longitudes or MLTs to convert.
  • datetime (datetime.datetime) – Date and time for MLT conversion in Universal Time (UT).
  • m2a (bool) – Convert MLT to AACGM-v2 longitude (default is False, which implies conversion from AACGM-v2 longitude to MLT).
Returns:

out – Converted coordinates/MLT
Return type:

numpy.ndarray

Notes

The MLT conversion is not part of the AACGM-v2 C library and is instead based on Laundal et al., 2016 [1]. A brief summary of the method is provided below.

MLT is defined as

MLT = (magnetic longitude - magnetic noon meridian longitude) / 15 + 12

where the magnetic noon meridian longitude is the centered dipole longitude of the subsolar point.

There are two important reasons for using centered dipole instead of AACGM for this calculation. One reason is that the AACGM longitude of the subsolar point is often undefined (being at low latitudes). More importantly, if the subsolar point close to ground was used, the MLT at polar latitudes would be affected by non-dipole features at low latitudes, such as the South Atlantic Anomaly. This is not desirable; since the Sun-Earth interaction takes place at polar field lines, it is these field lines the MLT should describe.

In calculating the centered dipole longitude of the subsolar point, we use the first three IGRF Gauss coefficients, using linear interpolation between the model updates every five years.

Both input and output MLON are taken modulo 360 to ensure they are between 0 and 360 degrees. Similarly, input/output MLT are taken modulo 24. For implementation of the subsolar point calculation, see subsol().

[1]Laundal, K. M. and A. D. Richmond (2016), Magnetic Coordinate Systems, Space Sci. Rev., doi:10.1007/s11214-016-0275-y.
aacgm2.subsol(year, doy, ut)[source]

Finds subsolar geocentric longitude and latitude.

Helper function for convert_mlt().

Parameters:
  • year (int [1601, 2100]) – Calendar year
  • doy (int [1, 365/366]) – Day of year
  • ut (float) – Seconds since midnight on the specified day
Returns:

  • sbsllon (float) – Subsolar longitude for the given date/time
  • sbsllat (float) – Subsolar latitude for the given date/time

Notes

Based on formulas in Astronomical Almanac for the year 1996, p. C24. (U.S. Government Printing Office, 1994). Usable for years 1601-2100, inclusive. According to the Almanac, results are good to at least 0.01 degree latitude and 0.025 degrees longitude between years 1950 and 2050. Accuracy for other years has not been tested. Every day is assumed to have exactly 86400 seconds; thus leap seconds that sometimes occur on December 31 are ignored (their effect is below the accuracy threshold of the algorithm).

After Fortran code by A. D. Richmond, NCAR. Translated from IDL by K. Laundal.

aacgm2.set_coeff_path()[source]

Sets the environment variables AACGM_v2_DAT_PREFIX and IGRF_12_COEFFS (for the current process). These are required for the C library to function correctly. This function is automatically called when importing aacgm2. You may need to call this manually if you use multithreading or spawn child processes (untested).