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