aacgmv2

These functions are available when you import aacgmv2.

Conversion functions between geo-graphic/detic and AACGM-V2 magnetic coords.

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)

aacgmv2.wrapper

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]

Convert 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 (dt.datetime) – Datetime for magnetic field

  • method_code (str or int) –

    Bit code or string denoting which type(s) of conversion to perform (default=”G2A”)

    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

  • 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]

Convert between geomagnetic coordinates and AACGM coordinates.

Parameters
  • in_lat (np.ndarray, 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 (dt.datetime) – Single datetime object for magnetic field

  • method_code (int or str) –

    Bit code or string denoting which type(s) of conversion to perform (default=”G2A”)

    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

  • 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 dt.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:

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 (dt.datetime) – Date and time to calculate magnetic location

  • method (str) –

    The type(s) of conversion to perform (default=”ALLOWTRACE”)

    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

  • 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 (dt.datetime) – Date and time to calculate magnetic location

  • method (str) –

    The type(s) of conversion to perform (default=”ALLOWTRACE”)

    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

  • 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]

Set 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

bool

Notes

Appropriate altitude ranges for the different methods are explored in Shepherd (2014). Summarized, they are: 1. Coefficients: 0-2000 km 2. 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 (any) – 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

aacgmv2.utils

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, same type as input gc_lat

Return type

array-like or float

aacgmv2.utils.igrf_dipole_axis(date)[source]

Get Cartesian unit vector pointing at dipole pole in the north (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]

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