aacgmv2

These functions are available when you import aacgmv2.

Functions to convert between geographic/geodetic and AACGM-V2 magnetic coordinates

aacgmv2.logger

Logger handle

Type:(logger)
aacgmv2.high_alt_coeff

Upper altitude limit for using coefficients in km

Type:(float)
aacgmv2.high_alt_trace

Upper altitude limit for using field-line tracing in km

Type:(float)
aacgmv2.AACGM_V2_DAT_PREFIX

Location of AACGM-V2 coefficient files with the file prefix

Type:(str)
aacgmv2.IGRF_COEFFS

Filename, with directory, of IGRF coefficients

Type:(str)

Pythonic wrappers for AACGM-V2 C functions.

aacgmv2.wrapper.convert_bool_to_bit(a2g=False, trace=False, allowtrace=False, badidea=False, geocentric=False)[source]

convert boolian flags to bit code specification

Parameters:
  • a2g ((bool)) – True for AACGM-v2 to geographic (geodetic), False otherwise (default=False)
  • trace ((bool)) – If True, use field-line tracing, not coefficients (default=False)
  • allowtrace ((bool)) – If True, use trace only above 2000 km (default=False)
  • badidea ((bool)) – If True, use coefficients above 2000 km (default=False)
  • geocentric ((bool)) – True for geodetic, False for geocentric w/RE=6371.2 (default=False)
Returns:

bit_code – code specification in bits

Return type:

(int)

aacgmv2.wrapper.convert_latlon(in_lat, in_lon, height, dtime, method_code='G2A')[source]

Converts between geomagnetic coordinates and AACGM coordinates

Parameters:
  • in_lat ((float)) – Input latitude in degrees N (code specifies type of latitude)
  • in_lon ((float)) – Input longitude in degrees E (code specifies type of longitude)
  • height ((float)) – Altitude above the surface of the earth in km
  • dtime ((datetime)) – Datetime for magnetic field
  • method_code ((str or int)) – Bit code or string denoting which type(s) of conversion to perform G2A - geographic (geodetic) to AACGM-v2 A2G - AACGM-v2 to geographic (geodetic) TRACE - use field-line tracing, not coefficients ALLOWTRACE - use trace only above 2000 km BADIDEA - use coefficients above 2000 km GEOCENTRIC - assume inputs are geocentric w/ RE=6371.2 (default is “G2A”)
Returns:

  • out_lat ((float)) – Output latitude in degrees N
  • out_lon ((float)) – Output longitude in degrees E
  • out_r ((float)) – Geocentric radial distance (R_Earth) or altitude above the surface of the Earth (km)

Raises:
  • ValueError if input is incorrect
  • RuntimeError if unable to set AACGMV2 datetime
aacgmv2.wrapper.convert_latlon_arr(in_lat, in_lon, height, dtime, method_code='G2A')[source]

Converts between geomagnetic coordinates and AACGM coordinates.

Parameters:
  • in_lat ((np.ndarray or list or float)) – Input latitude in degrees N (method_code specifies type of latitude)
  • in_lon ((np.ndarray or list or float)) – Input longitude in degrees E (method_code specifies type of longitude)
  • height ((np.ndarray or list or float)) – Altitude above the surface of the earth in km
  • dtime ((datetime)) – Single datetime object for magnetic field
  • method_code ((int or str)) – Bit code or string denoting which type(s) of conversion to perform G2A - geographic (geodetic) to AACGM-v2 A2G - AACGM-v2 to geographic (geodetic) TRACE - use field-line tracing, not coefficients ALLOWTRACE - use trace only above 2000 km BADIDEA - use coefficients above 2000 km GEOCENTRIC - assume inputs are geocentric w/ RE=6371.2 (default = “G2A”)
Returns:

  • out_lat ((np.ndarray)) – Output latitudes in degrees N
  • out_lon ((np.ndarray)) – Output longitudes in degrees E
  • out_r ((np.ndarray)) – Geocentric radial distance (R_Earth) or altitude above the surface of the Earth (km)

Raises:
  • ValueError if input is incorrect
  • RuntimeError if unable to set AACGMV2 datetime

Notes

At least one of in_lat, in_lon, and height must be a list or array.

If errors are encountered, NaN or Inf will be included in the input so that all successful calculations are returned. To select only good values use a function like np.isfinite.

Multi-dimensional arrays are not allowed.

aacgmv2.wrapper.convert_mlt(arr, dtime, m2a=False)[source]

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

Parameters:
  • arr ((array-like or float)) – Magnetic longitudes (degrees E) or MLTs (hours) to convert
  • dtime ((array-like or datetime.datetime)) – Date and time for MLT conversion in Universal Time (UT).
  • m2a ((bool)) – Convert MLT to AACGM-v2 longitude (True) or magnetic longitude to MLT (False). (default=False)
Returns:

out – Converted coordinates/MLT in degrees E or hours (as appropriate)

Return type:

(np.ndarray)

Notes

This routine previously based on Laundal et al. 2016, but now uses the improved calculation available in AACGM-V2.4.

aacgmv2.wrapper.convert_str_to_bit(method_code)[source]

convert string code specification to bit code specification

Parameters:method_code ((str)) – Bitwise code for passing options into converter (default=0) G2A - geographic (geodetic) to AACGM-v2 A2G - AACGM-v2 to geographic (geodetic) TRACE - use field-line tracing, not coefficients ALLOWTRACE - use trace only above 2000 km BADIDEA - use coefficients above 2000 km GEOCENTRIC - assume inputs are geocentric w/ RE=6371.2
Returns:bit_code – Method code specification in bits
Return type:(int)

Notes

Multiple codes should be seperated by pipes ‘|’. Invalid parts of the code are ignored and no code defaults to ‘G2A’.

aacgmv2.wrapper.get_aacgm_coord(glat, glon, height, dtime, method='ALLOWTRACE')[source]

Get AACGM latitude, longitude, and magnetic local time

Parameters:
  • glat ((float)) – Geodetic latitude in degrees N
  • glon ((float)) – Geodetic longitude in degrees E
  • height ((float)) – Altitude above the surface of the earth in km
  • dtime ((datetime)) – Date and time to calculate magnetic location
  • method ((str)) – String denoting which type(s) of conversion to perform TRACE - use field-line tracing, not coefficients ALLOWTRACE - use trace only above 2000 km BADIDEA - use coefficients above 2000 km GEOCENTRIC - assume inputs are geocentric w/ RE=6371.2 (default = “TRACE”)
Returns:

  • mlat ((float)) – magnetic latitude in degrees N
  • mlon ((float)) – magnetic longitude in degrees E
  • mlt ((float)) – magnetic local time in hours

aacgmv2.wrapper.get_aacgm_coord_arr(glat, glon, height, dtime, method='ALLOWTRACE')[source]

Get AACGM latitude, longitude, and magnetic local time

Parameters:
  • glat ((np.array or list)) – Geodetic latitude in degrees N
  • glon ((np.array or list)) – Geodetic longitude in degrees E
  • height ((np.array or list)) – Altitude above the surface of the earth in km
  • dtime ((datetime)) – Date and time to calculate magnetic location
  • method ((str)) – String denoting which type(s) of conversion to perform TRACE - use field-line tracing, not coefficients ALLOWTRACE - use trace only above 2000 km BADIDEA - use coefficients above 2000 km GEOCENTRIC - assume inputs are geocentric w/ RE=6371.2 (default = “TRACE”) (default = “TRACE”)
Returns:

  • mlat ((float)) – magnetic latitude in degrees N
  • mlon ((float)) – magnetic longitude in degrees E
  • mlt ((float)) – magnetic local time in hours

aacgmv2.wrapper.set_coeff_path(igrf_file=False, coeff_prefix=False)[source]

Sets the IGRF_COEFF and AACGMV_V2_DAT_PREFIX environment variables.

Parameters:
  • igrf_file ((str or bool)) – Full filename of IGRF coefficient file, True to use aacgmv2.IGRF_COEFFS, or False to leave as is. (default=False)
  • coeff_prefix ((str or bool)) – Location and file prefix for aacgm coefficient files, True to use aacgmv2.AACGM_V2_DAT_PREFIX, or False to leave as is. (default=False)
aacgmv2.wrapper.test_height(height, bit_code)[source]

Test the input height and ensure it is appropriate for the method

Parameters:
  • height ((float)) – Height to test in km
  • bit_code ((int)) – Code string denoting method to use
Returns:

good_height – True if height and method are appropriate, False if not

Return type:

(boolean)

Notes

Appropriate altitude ranges for the different methods are explored in Shepherd (2014). Summarized, they are: Coefficients: 0-2000 km Tracing: 0-1 Earth Radius

Altitudes below zero will work, but will not provide a good representation of the magnetic field because it goes beyond the intended scope of these coordiantes.

If you use the ‘BADIDEA’ code, you can bypass all constraints, but it is a Bad Idea! If you include a high enough altiutde, the code may hang.

aacgmv2.wrapper.test_time(dtime)[source]

Test the time input and ensure it is a dt.datetime object

Parameters:dtime ((unknown)) – Time input in an untested format
Returns:dtime – Time as a datetime object
Return type:(dt.datetime)
Raises:ValueError if time is not a dt.date or dt.datetime object

utilities that support the AACGM-V2 C functions.

References

Laundal, K. M. and A. D. Richmond (2016), Magnetic Coordinate Systems, Space
Sci. Rev., doi:10.1007/s11214-016-0275-y.
aacgmv2.utils.gc2gd_lat(gc_lat)[source]

Convert geocentric latitude to geodetic latitude using WGS84.

Parameters:gc_lat ((array_like or float)) – Geocentric latitude in degrees N
Returns:gd_lat – Geodetic latitude in degrees N
Return type:(same as input)
aacgmv2.utils.igrf_dipole_axis(date)[source]

Get Cartesian unit vector pointing at dipole pole in the north, according to IGRF

Parameters:date ((dt.datetime)) – Date and time
Returns:m_0 – Cartesian 3 element unit vector pointing at dipole pole in the north (geocentric coords)
Return type:(np.ndarray)

Notes

IGRF coefficients are read from the igrf12coeffs.txt file. It should also work after IGRF updates. The dipole coefficients are interpolated to the date, or extrapolated if date > latest IGRF model

aacgmv2.utils.subsol(year, doy, utime)[source]

Finds subsolar geocentric longitude and latitude.

Parameters:
  • year ((int)) – Calendar year between 1601 and 2100
  • doy ((int)) – Day of year between 1-365/366
  • utime ((float)) – Seconds since midnight on the specified day
Returns:

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

Raises:

ValueError if year is out of range

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).

References

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