Package Maintenance

Updating IGRF

The International Geomagnetic Reference Field is regularly updated to reflect the most recent changes to the Terrestrial magnetic field. AACGMV2 currently uses IRGF-14 coefficients, which are provided in the aacgmv2/aacgmv2/igrf14coeff.txt file and a combined magnetic model that uses coefficients provided in aacgmv2/aacgmv2/magmodel_1590-2025.txt. To change or update the magnetic field coefficients used by AACGMV2, you need to obtain the new IGRF coefficients, magnetic model coefficients, and the AACGMV2 coefficients, and update the Python and C code. If substantial changes have been made to the C code, it may be necessary to update the functions in aacgmv2/aacgmv2/aacgmv2module.c, as this is what allows Python to interface with the AACGMV2 source code. Updates to the AACGMV2 coefficients and code may be obtained from the website hosted by Dartmouth. The C tarball contains the IGRF and magnetic model coefficient files.

Assuming no changes were made to the way coefficients are handled or the C code is called, the updating process is simple:

  1. Clone the repository or update your fork of the repository (see Contributing).

  2. Replace the AACGMV2 coefficients in aacgmv2/aacgmv2/aacgm_coeffs.

  3. Replace the IGRF coefficient file in aacgmv2/aacgmv2/.

  4. Update the aacgmv2/__init__.py global variables AACGM_v2_DAT_PREFIX and IGRF_COEFFFS

  5. If the C code has been updated, update the c_aacgmv2/README.txt, c_aacgmv2/release_notes.txt, and LISCENCE-AstAlg.txt files for the new version.

  6. If the C code has been updated, update the header files in c_aacgmv2/include. Check to see if any files have been removed. If c_aacgmv2/include/astalg.h ends up removing the M_PI definition, add it back in (needed for Windows).

  7. If the C code has been updated, update the source files in c_aacgmv2/src. Check to see if any files have been removed; remove them from the list of aacgmv2/setup.py sources. If the NAN and isfinite definitions are removed from mlt_v2.c and the EINVAL definition and setenv function are removed from rtime.c, add these and the header info back in (needed for Windows). Also, fix the commenting style in test_aacgm.c to reduce compiler warnings.

  8. Rebuild and install AACGMV2 following the instructions in Installation.

  9. Update the unit tests in the aacgmv2/aacgmv2/tests/ directory so that they check the functions are working correctly with dates after the IGRF epoch update. You will have to update the hard-coded confirmation values used by these tests, but the values should not change by more than a hundredth of a degree. Tests that may need to be updated include:

    1. test_c_aacgmv2.py::TestCAACGMV2.test_convert

    2. test_cmd_aacgmv2.py::TestCmdAACGMV2::test_convert_stdin_stdout

    3. test_cmd_aacgmv2.py::TestCmdAACGMV2::test_convert_mlt_stdin_stdout

    4. test_struct_aacgmv2.py::TestTopVariables::test_top_parameters

    5. test_utils_aacgmv2.py::TestUtilsAACGMV2::test_igrf_dipole_axis

    6. environ/test_environ_aacgmv2.py::TestPyEnviron

  10. Commit all changes and create a pull request on GitHub to integrate your branch with updated IGRF into the main repository.

Modifying the C Source

When modifying the C source code, it can be helpful to run a preliminary validation of the C output independent of the Python wrapper. This should be done within the aacgmv2/c_aacgmv2 directory.

  1. Build the test_aacgm binary by following the instructions in aacgmv2/c_aacgmv2/README.txt. You will have to alter the compilation command to preface each .c file with src and also add -Iinclude.

  1. Execute the test_aacgm binary.

  2. Confirm the output printed to the screen matches the test output shown in the comment block provided in the aacgmv2/c_aacgmv2/README.txt.

  3. If the modifications involved adding or removing C source files, modify the list of extension sources in setup.py.

  4. Rebuild and install AACGMV2 following the instructions in Installation.