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.
High Resolution
Starting in 2025, a high resolution model was released you can read more about it here: World Magnetic Model High Resolution (WMMHR)
From NOAA
The World Magnetic Model High Resolution (WMMHR) is an advanced geomagnetic field model that provides a more detailed, accurate depiction of the geomagnetic field than the World Magnetic Model (WMM). WMMHR2025 includes core field and secular variation coefficients for degrees n = 1 to 15. This model also covers the crustal field (from n=16 through n=133). As a result, it has more coefficients ((18,210 non-zero coefficients instead of 336) and more digits (4 instead of 1) in each coefficient.
Installation
Install using pip with:
pip install pygeomagExample
Calculate the geomagnetic declination at the Space Needle in Seattle, WA:
>>> from pygeomag import GeoMag
>>> geo_mag = GeoMag(coefficients_file="wmm/WMM_2025.COF")
>>> result = geo_mag.calculate(glat=47.6205, glon=-122.3493, alt=0, time=2025.25)
>>> print(result.d)
15.065629638512593And calculate it for the same spot 12 years previous:
>>> 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.25)
>>> print(result.d)
16.415602225952366And calculate it for the same spot using the high resolution model:
>>> from pygeomag import GeoMag
>>> geo_mag = GeoMag(coefficients_file='wmm/WMMHR_2025.COF', high_resolution=True)
>>> result = geo_mag.calculate(glat=47.6205, glon=-122.3493, alt=0, time=2025.00)
>>> print(result.d)
15.017316292177854Validation
All test values from the official NOAA WMM documentation are tested here for WMM-2025, WMMHR-2025, WMM-2020, WMM-2015v2, WMM-2015 and WMM-2010.
For the WMM-2025 and WMMHR-2025 the test data went from 1 decmial place to 6 for x, y, z, h and f. The code copied from the legacy C application uses a different formula and thus isn’t quite the same. I am looking at the newer code to see if it makes sense to re-port over.
Notes
This is a direct port from the Legacy C code provided by NOAA. It defaults to using the WMM-2025 Coefficient file (WMM.COF) valid for 2025.0 - 2030.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.
1 maintainer
Metadata
1 maintainer
Release files for pygeomag 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pygeomag-1.1.0.tar.gz | 237.6 kB | Without provenance | Details for pygeomag-1.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pygeomag-1.1.0-py3-none-any.whl | Python 3 | none | any | Details for pygeomag-1.1.0-py3-none-any.whl |
Total release size: 486.7 kB
Release files / pygeomag-1.1.0.tar.gz
| Download URL | pygeomag-1.1.0.tar.gz |
|---|---|
| Size | 237.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c38943c43f7e0e771e25f101b2b94077f00307436760bbf5e79b84c3a41569d7
|
|
BLAKE2b-256 checksum How to use checksums |
f4050479687afaf337f7e549b8d576a53de65c9b491ddd8e1e1a254f97c7aff8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.1.0 CPython/3.11.6
|
Release files / pygeomag-1.1.0-py3-none-any.whl
| Download URL | pygeomag-1.1.0-py3-none-any.whl |
|---|---|
| Size | 249.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b08fc5de7ca545721e511f62a342d415a4d76e695fec28ef9ef255e994e6727b
|
|
BLAKE2b-256 checksum How to use checksums |
65af4416ce7b7f2b924d32ae8834d6b76bde02980fca7619fbb26d171140c5b8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.1.0 CPython/3.11.6
|
Security for pygeomag 1.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
