Welcome to pyGeoMag's documentation!

What is declination?

Declination is the angle that adjusts a compass reading from Magnetic North to True North. Many maps will show it in the legend, so you can adjust your compass (either physically or mentally).

Why do you need this?

In Washington State, the declination angle is between 14° and 16° West depending on your location. Meaning if I just pull out my compass and head North, I'm really heading at about 15°. And now if I walk 500 feet on that course, I'll be about 130 feet to the East of where I wanted to be.

Now say I'm building a device that includes a magnetometer. I get it all calibrated to point to Magnetic North, show this value on the device and now the user is pointing in the wrong direction. And of course, the values change yearly. In the last 10 years, it's dropped just over a full degree in the Greater Seattle area. Here is where pyGeoMag comes in.

To help see how much the magnetic field changes as you travel across the globe, here is projection for 2020 from NOAA:

To see how much the value changes per year (The contour interval is 2 arcminutes/year):

If you want to look up these values, you can use NOAA's Magnetic Field Caculators in a browser or install their CrowdMag app on your Android or iOS device.

pyGeoMag is an implementation written in Python of the World Magnetic Model (WMM), specifically to be used in lightweight versions (like MicroPython and CircuitPython).

From NOAA

The World Magnetic Model (WMM) is the standard model for navigation, attitude, and heading referencing systems using the geomagnetic field. Additional WMM uses include civilian applications, including navigation and heading systems.

The model is a joint product of the United States' National Geospatial-Intelligence Agency (NGA) and the United Kingdom's Defence Geographic Centre (DGC). NCEI and the British Geological Survey (BGS) jointly developed the WMM. The U.S. Department of Defense, the U.K. Ministry of Defence, the North Atlantic Treaty Organization (NATO), and the International Hydrographic Organization (IHO) use the WMM.

Installation

Install using pip with:

pip install pygeomag

Example

Calculate the geomagnetic declination at the Space Needle in Seattle, WA:

>>> from pygeomag import GeoMag
>>> geo_mag = GeoMag()
>>> result = geo_mag.calculate(glat=47.6205, glon=-122.3493, alt=0, time=2023.75)
>>> print(result.d)
15.25942260585284

And calculate it for the same spot 10 years ago:

>>> from pygeomag import GeoMag
>>> geo_mag = GeoMag(coefficients_file='wmm/WMM_2010.COF')
>>> result = geo_mag.calculate(glat=47.6205, glon=-122.3493, alt=0, time=2013.75)
>>> print(result.d)
16.32554283003356

Validation

All test values from the official NOAA WMM documentation are tested here for WMM-2020, WMM-2015v2, WMM-2015 and WMM-2010.

Notes

This is a direct port from the Legacy C code provided by NOAA. It defaults to using the WMM-2020 Coefficient file (WMM.COF) valid for 2020.0 - 2025.0. The code is specifically not 100% pythonic in order to make adding updates simple (for example uppercase variable names).

At this point Annual change also known as Secular Variation is not in this package the Legacy C version does a direct year+1.value - year2.value and both the test values and other existing code bases do something different.

Documentation

More documentation and examples can be found at Read the Docs.