pleiszenburg/pycrgi

pyCRGI is a Python package offering the IGRF-13 (International Geomagnetic Reference Field) model.

pyCRGI

pyCRGI is a cleaned-up and modernized fork of pyIGRF. Be aware that there are a number of small function and module name differences to the original pyIGRF package. The fork's main goals are verified results, tests, speed and ease of maintainability. This is work in progress.

• package structure cleanup, allowing proper testing and packaging
• type annotations
• doc strings completed and prepared for Sphinx autodoc
• debug mode via environment variable PYCGIR_DEBUG=1
• pure Python 3 implementation without dependency to numpy
• JIT-compiled implementation depending on numba and numpy, installation target jited
• array implementation depending on numba and numpy, installation target array
• unit tests via test makefile target
• verification of field's values against original Fortran implementation
• verification of field's annual/seasonal variation -> huge differences to original Fortran implementation
• benchmark
• clean up and add missing relevant coordinate system conversions

What is pyCRGI?

pyCRGI is a Python package offering the IGRF-13 (International Geomagnetic Reference Field) model. You can use it to calculate the magnetic field's intensity and to transform coordinates between GeoGraphical and GeoMagnetic. The package offers different implementations, pure Python and Python JIT-compiled via numba. The project's name is literally the French equivalent of pyIGRF, the project that pyCRGI was once forked from: Champ de Référence Géomagnétique International.

How to Install?

Use pip to install the latest development version from Github:

pip install git+https://github.com/pleiszenburg/pyCRGI.git@master

How to Use it?

First import the package, either as pure Python 3 or JIT-compiled via numba and numpy:

from pyCRGI.pure import get_value, get_variation # pure Python 3
# or
from pyCRGI.jited import get_value, get_variation # JIT-compiled via `numba` and `numpy`
# or
from pyCRGI.array import get_value, get_variation # array implementation via `numba` and `numpy`

As an alternative to pyCRGI.jited, there is also an experimental, structurally different JIT-compiled version named pyCRGI.jited2 available. In the latter implementation, the handling of coefficients differs from the original Fortran implementation that pyCRGI & pyIGRF are based on. It can serve as a foundation for a CUDA-based implementation.

You can calculate the magnetic field's intensity:

get_value(lat, lon, alt, year)

You can calculate the annual variation of the magnetic field's intensity:

get_variation(lat, lon, alt, year)

The return value is a tuple (or array) of seven floating point numbers representing the local magnetic field:

• D: declination (+ve east) [degree]
• I: inclination (+ve down) [degree]
• H: horizontal intensity [nT]
• X: north component [nT]
• Y: east component [nT]
• Z: vertical component (+ve down) [nT]
• F: total intensity [nT]

If you want to use the IGRF-13 model in a more flexible manner, you can use the functions geodetic2geocentric and get_syn. They are somewhat closer to the original Fortran implementation.

Another function, get_coeffs, can be used to get g[m][n] or h[m][n] corresponding to the IGRF's formula.

Alternatives

This project was originally forked from pyIGRF:

• original pyIGRF, Python

There are other, independent implementations named pyIGRF, not to be confused with the previously mentioned one:

• another recent independent pyIGRF, Python
• another older independent pyIGRF, Python & Fortran
• another small independent pyigrf, Python

The official IGRF implementations by IAGA are available via the NOAA website:

• IAGA IGRF, Fortran
• IAGA IGRF, Python

A good, modern and pure Python implementation:

• ppigrf, Python

Another Python implementation is part of the navtools package:

• navtools IGRF, Python

Another Python wrapper around a cleaned-up version of IAGA's Fortran code is maintained as part of the space physics project:

• space-physics IGRF, Python & Fortran

A more or less undocumented, pure Python implementation can be found here:

• ADCS_IGRF, Python

The IGRF is not to be confused with the World Magnetic Model (WMM). Recent implementations of the WMM accessible via Python are maintained as part of the space physics project:

• space-physics WMM2015, Python & C
• space-physics WMM2020, Python & C

References

• Model introduction and IGRF-13 coefficients file download at NOAA