A Python wrapper for AACGM-v2 magnetic coordinates

## Project description

This is a Python wrapper for the AACGM-v2 C library, which allows converting between geographic and magnetic coordinates. The currently included version of the C library is 2.4. The package is free software (MIT license). When referencing this package, please cite both the package DOI and the AACGM-v2 journal article:

Shepherd, S. G. (2014), Altitude‐adjusted corrected geomagnetic coordinates: Definition and functional approximations, Journal of Geophysical Research: Space Physics, 119, 7501–7521, doi:10.1002/2014JA020264.

## Quick start

Install (requires NumPy and logging):

```pip install aacgmv2
```

Convert between AACGM and geographic coordinates:

```>>> import aacgmv2
>>> import datetime as dt
>>> import numpy as np
>>> np.set_printoptions(formatter={'float_kind': lambda x:'{:.4f}'.format(x)})
>>> # geo to AACGM, single numbers
>>> dtime = dt.datetime(2013, 11, 3)
>>> np.array(aacgmv2.get_aacgm_coord(60, 15, 300, dtime))
array([57.4698, 93.6300, 1.4822])
>>> # AACGM to geo, mix arrays/numbers
>>> aacgmv2.convert_latlon_arr([90, -90], 0, 0, dtime, code="A2G")
(array([82.9666, -74.3385]), array([-84.6652, 125.8401]), array([14.1244, 12.8771]))
```

Convert between AACGM and MLT:

```>>> import aacgmv2
>>> import datetime as dt
>>> import numpy as np
>>> np.set_printoptions(formatter={'float_kind': lambda x:'{:.4f}'.format(x)})
>>> # MLT to AACGM
>>> dtime = dt.datetime(2013, 11, 3, 0, 0, 0)
>>> aacgmv2.convert_mlt([1.4822189, 12], dtime, m2a=True)
array([93.6300, -108.6033])
```

If you don’t know or use Python, you can also use the command line. See details in the full documentation.

## Changelog

### 2.4.2 (2018-05-21)

• Fixed bug in convert_mlt that caused all time inputs to occur at 00:00:00 UT
• Fixed year of last two updates in changelog

### 2.4.1 (2018-04-04)

• Fix bug in installation that caused files to be placed in the wrong directory

### 2.4.0 (2018-03-21)

• Update to use AACGM-v2.4, which includes changes to the inverse MLT and dipole tilt functions and some minor bug fixes
• Updated file structure
• Updated methods, retaining old methods in deprecated module
• Added testing for python 3.6
• Updated dependencies, removing support for python 3.3
• Tested on Mac OSX
• Updated comments to include units for input and output

### 2.0.0 (2016-11-03)

• Change method of calculating MLT, see documentation of convert_mlt for details

### 1.0.13 (2015-10-30)

• Correctly convert output of subsol() to geodetic coordinates (the error in MLT/mlon conversion was not large, typically two decimal places and below)

### 1.0.12 (2015-10-26)

• Return nan in forbidden region instead of throwing exception

### 1.0.11 (2015-10-26)

• Fix bug in subsolar/MLT conversion

### 1.0.10 (2015-10-08)

• No code changes, debugged automatic build/upload process and needed new version numbers along the way

### 1.0.0 (2015-10-07)

• Initial release