API

GeoMag

exception pygeomag.BlackoutZoneException

Horizontal intensity is in a Blackout Zone.

The Blackout Zones are defined as regions around the north and south magnetic poles where the horizontal intensity of Earth’s magnetic field (H) is less than 2000 nT. In these zones WMM declination values are inaccurate and compasses are unreliable.

exception pygeomag.CautionZoneException

Horizontal intensity is in a Caution Zone.

A Caution Zone is an areas around a Blackout Zone where caution must be exercised while using a compass. It is defined where Earth’s magnetic field (H) is between 2000 and 6000 nT. Compass accuracy may be degraded in this region.

class pygeomag.GeoMag(coefficients_file: str | None = None, coefficients_data: Tuple | None = None, base_year: str | datetime | None = None, high_resolution: bool = False)

Python port of the Legacy C code provided by NOAA for the World Magnetic Model (WMM).

It defaults to using the WMM-2025 Coefficient file (WMM.COF) valid for 2025.0 - 2030.0.

Included are the following coefficient files, if you have the need to calculate past values:

File	Model	Life Span	Creation
WMM.COF	WMM-2025	2025.0 - 2030.0	11/13/2024
WMM_2025.COF	WMM-2025	2025.0 - 2030.0	11/13/2024
WMM_2020.COF	WMM-2020	2020.0 - 2025.0	12/10/2019
WMM_2015v2.COF	WMM-2015v2	2015.0 - 2020.0	09/18/2018
WMM_2015.COF	WMM-2015	2015.0 - 2020.0	12/15/2014
WMM_2010.COF	WMM-2010	2010.0 - 2015.0	11/20/2009

__init__(coefficients_file: str | None = None, coefficients_data: Tuple | None = None, base_year: str | datetime | None = None, high_resolution: bool = False) → None

Create a GeoMag instance.

There are 4 methods of initialization:

>>> from pygeomag import GeoMag
>>> from pygeomag.wmm.wmm_2025 import WMM_2025
>>>
>>> # Have it default to the latest coefficients file:
>>> geo_mag = GeoMag()
>>>
>>> # Specify a coefficients file:
>>> geo_mag = GeoMag(coefficients_file="wmm/WMM_2025.COF")
>>>
>>> # Specify coefficients data:
>>> geo_mag = GeoMag(coefficients_data=WMM_2025)
>>>
>>> # Specify either a base year as a int/float:
>>> geo_mag = GeoMag(base_year=2025)
>>> # or pass in an object that has a year property:
>>> geo_mag = GeoMag(base_year=datetime.datetime.now())

Leaving all values as None will load the packages default coefficients file, supplying multiple will raise.

Parameters:

coefficients_file (str) – Full or relative path to a coefficients file supplied by this package or WMM
coefficients_data (Tuple) – coefficients data from a python module
base_year (Union[str, datetime.datetime]) – a year you want to use to auto select the correct coefficients data
high_resolution (bool) – use the high resolution dataset

calculate(glat: float, glon: float, alt: float, time: float, allow_date_outside_lifespan: bool = False, raise_in_warning_zone: bool = False) → GeoMagResult

Calculate the Magnetic Components from a latitude, longitude, altitude and date.

Parameters:

glat (float) – Geodetic Latitude, -90.00 to +90.00 degrees (North positive, South negative)
glon (float) – Geodetic Longitude, -180.00 to +180.00 degrees (East positive, West negative)
alt (float) – Altitude, -1 to 850km referenced to the WGS 84 ellipsoid OR the Mean Sea Level (MSL)
time (float) – Time (in decimal year)
allow_date_outside_lifespan (bool) – True, if you want an estimation outside the 5-year life span
raise_in_warning_zone (bool) – True if you want to raise a BlackoutZoneException or CautionZoneException exception when the horizontal intensity is < 6000

Returns:

A GeoMagResult object

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.065629638512593

And 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.415602225952366

property life_span: Tuple[float, float]: Return the life span for the selected coefficient file.

property model: str: Return the model name for the selected coefficient file.

property release_date: str: Return the release date for the selected coefficient file.

class pygeomag.GeoMagResult(time: float, alt: float, glat: float, glon: float)

The Magnetic Components values from GeoMag.calculate().

glat: float: Geodetic Latitude, -90.00 to +90.00 degrees (North positive, South negative).

glon: float: Geodetic Longitude, -180.00 to +180.00 degrees (East positive, West negative).

alt: float: Altitude, -1 to 850km referenced to the WGS 84 ellipsoid OR the Mean Sea Level (MSL).

time: float: Time (in decimal year).

f: float: Total Intensity.

property ti: float: Total Intensity.

property total_intensity: float: Total Intensity.

h: float: Horizontal Intensity.

x: float: North Component.

y: float: East Component.

z: float: Vertical Component.

i: float: Geomagnetic Inclination.

property dip: float: Geomagnetic Inclination.

property inclination: float: Geomagnetic Inclination.

d: float: Geomagnetic Declination (Magnetic Variation).

property dec: float: Geomagnetic Declination (Magnetic Variation).

gv: float: Magnetic grid variation if the current geodetic position is in the arctic or antarctic.

in_blackout_zone: bool: Horizontal intensity is in a Blackout Zone.

in_caution_zone: bool: Horizontal intensity is in a Caution Zone.

calculate_uncertainty() → GeoMagUncertaintyResult

Calculate the uncertainty values for this GeoMagResult.

Uncertainty estimates provided by the WMM2015, WMM2020, and WMM2025 error model for the various field components. H is expressed in nT in the formula providing the error in D.

These values can currently only be computed for GeoMagResult between 2015.0 and 2030.0 and using a value outside this will raise an Exception

Returns:: A GeoMagUncertaintyResult object

>>> from pygeomag import GeoMag
>>> geo_mag = GeoMag(coefficients_file="wmm/WMM_2020.COF")
>>> result = geo_mag.calculate(glat=47.6205, glon=-122.3493, alt=0, time=2023.75)
>>> uncertainty = result.calculate_uncertainty()
>>> print(uncertainty.d)
0.3935273117953904

class pygeomag.GeoMagUncertaintyResult(result: GeoMagResult)

The uncertainty values of a GeoMagResult.

f: float: Uncertainty of the Total Intensity in nT.

h: float: Uncertainty of the Horizontal Intensity in nT.

x: float: Uncertainty of the North Component in nT.

y: float: Uncertainty of the East Component in nT.

z: float: Uncertainty of the Vertical Component in nT.

i: float: Uncertainty of the Geomagnetic Inclination in degrees.

d: float: Uncertainty of the Geomagnetic Declination (Magnetic Variation) in degrees.

Time utils

There are methods for converting both a time.struct_time, datetime.date and datetime.datetime object to a decimal year:

pygeomag.time.calculate_decimal_year(date)

Calculate the decimal year (2022.5) from a value (i.e. ‘datetime.datetime’ or ‘time.struct_time’).

If you know using either date format will work in your version of Python, you can use this wrapper method.

>>> import datetime
>>> from pygeomag import calculate_decimal_year
>>> calculate_decimal_year(datetime.datetime(2020, 7, 2))
2020.5

pygeomag.time.decimal_year_from_date(date)

Calculate the decimal year (2022.5) from a ‘datetime.date’ or ‘datetime.datetime’.

>>> import datetime
>>> from pygeomag import decimal_year_from_date
>>> value = datetime.datetime(2020, 7, 2)
>>> decimal_year_from_date(value)
2020.5

pygeomag.time.decimal_year_from_struct_time(date)

Calculate the decimal year (2022.5) from a ‘time.struct_time’.

>>> import time
>>> from pygeomag import decimal_year_from_struct_time
>>> value = time.struct_time((2020, 7, 2, 0, 0, 0, 0, 0, 0))
>>> decimal_year_from_struct_time(value)
2020.5

Formatting utils

There are methods from going between decimal degrees and degrees minutes and seconds:

pygeomag.format.decimal_degrees_to_degrees_minutes(decimal_degrees)

Convert decimal degrees to degrees and minutes.

>>> from pygeomag import decimal_degrees_to_degrees_minutes
>>> decimal_degrees_to_degrees_minutes(45.7625)
(45, 45.75)

pygeomag.format.decimal_degrees_to_degrees_minutes_seconds(decimal_degrees)

Convert decimal degrees to degrees, minutes and seconds.

>>> from pygeomag import decimal_degrees_to_degrees_minutes_seconds
>>> decimal_degrees_to_degrees_minutes_seconds(45.7625)
(45, 45, 45.0)

pygeomag.format.degrees_minutes_seconds_to_decimal_degrees(degrees, minutes, seconds)

Convert degrees, minutes and seconds to decimal degrees.

>>> from pygeomag import degrees_minutes_seconds_to_decimal_degrees
>>> degrees_minutes_seconds_to_decimal_degrees(45, 45, 45)
45.7625

pygeomag.format.degrees_minutes_to_decimal_degrees(degrees, minutes)

Convert degrees and minutes to decimal degrees (45.7625).

>>> from pygeomag import degrees_minutes_to_decimal_degrees
>>> degrees_minutes_to_decimal_degrees(45, 45.75)
45.7625

pygeomag.format.pretty_print_degrees(decimal_degrees, is_latitude, show_seconds=False, full_words=False, number_of_digits=0)

Format decimal degrees into a human-readable string.

Parameters:

decimal_degrees (float, int) – Decimal degrees you want converted
is_latitude (bool) – True for latitude, False for longitude
show_seconds (bool) – True to show seconds, False for just degrees and minutes
full_words (bool) – True to use full words like “North”, False for single characters like “N”
number_of_digits (int) – The amount of digits to round the last value to

Returns:

Human-readable string

>>> from pygeomag import pretty_print_degrees
>>> pretty_print_degrees(decimal_degrees=45.7625, is_latitude=True)
"45° 46' N"
>>> pretty_print_degrees(decimal_degrees=45.7625, is_latitude=True, number_of_digits=2)
"45° 45.75' N"
>>> pretty_print_degrees(decimal_degrees=45.7625, is_latitude=True, full_words=True, number_of_digits=2)
'45 Degrees 45.75 Minutes North'

pygeomag.format.round_to_digits(number, number_of_digits=0)

Round to number of digits, removing all if 0 and not Pythons round to even number strategy.

>>> from pygeomag import round_to_digits
>>> round_to_digits(45.7625, 0)
46
>>> round_to_digits(45.7625, 1)
45.8
>>> round_to_digits(45.7625, 2)
45.76