geomaglib

PyPI - Version PyPI - Python Version PyPI - License

geomaglib Python API includes the core functions for building geomag model like WMM, WMMHR, HDGM-crust, HDGM-core and IGRF. The API is developed by the Cooperative Institute For Research in Environmental Sciences (CIRES), University of Colorado.

Installation

Install the geomaglib deployed to PyPI

Install the geomaglib from PyPI

pip install geomaglib

Install the Public Git repository to your virtual environment

1. Install specific branch

pip install git+https://github.com/CIRES-Geomagnetism/geomaglib.git@<branch_name>

2. Install specific tag

pip install git+https://github.com/CIRES-Geomagnetism/geomaglib.git@<tag_number>

Quick Start

Example 1: Compute the associated Legendre polynomials up to degree 12

from geomaglib import legendre

nmax = 12
colats = [30.0]  # colatitudes in degrees
Pnm, dPnm = legendre.Flattened_Chaos_Legendre1(nmax, colats)

Example 2: Calculate dipole magnetic latitude and longitude

from geomaglib.dipole import Dipole                                                                                                                                                                                             

dp = Dipole(2024.1)                                                                                                                                                                                                             
mlat, mlon = dp.coords(40.0, -105.0)                                                                                                                                                                                            
gclat, gclon = dp.coords(mlat, mlon, inverse=True)

For spherical harmonic models, load coefficients with geomaglib.sh_loader and compute fields with geomaglib.magmath.

API Reference

geomaglib.legendre

Compute the Legendre polynomials

See the detail of functions

Flattened_Chaos_Legendre1(): Outputs a 2 dimensional numpy array which contains the associated legendre polynomials (Pnm) and the respective derivatives (dPnm).

get_index(): Get the index of Flattened_Chaos_Legendre1

geomaglib.magmath

Compute the Geomagnetic elements in geodetic: Bx, By, Bz, Bh(horizontal), Bf(total intensity), declination, inclination and the delta Bx, By, Bz, Bh(horizontal), Bf(total intensity), declination, inclination
Radius and degree conversion
Convert magnetic vector from spherical to geodetic

See the detail of functions

rad2deg(): Convert radius to degree

deg2rad(): Convert degree to radius

calc_Bp_Pole(): Calculate the B_phi magnetic elements at pole

mag_SPH_summation(): Compute the spherical magnetic vectors (B_theta, B_phi, B_radius)

rotate_magvec(): Convert magnetic vector from spherical to geodetic

GeomagElements(): The Python class for computing magnetic elements in geodetic coordinates

Get all of the magnetic elements: get_all()
Get the specific magnetic element:
- get_Bx()
- get_By()
- get_Bz()
- get_Bh()
- get_Bf()
- get_Bdec()
- get_Binc()
- get_dBx()
- get_dBy()
- get_dBz()
- get_dBh()
- get_dBf()
- get_dBdec()
- get_dBinc()

geomaglib.util

Compute decimal year
Converting the coordinates based on geodetic to geocentric
Converting the mean sea level altitude to ellipsoid height

See the detail of functions

geod_to_geoc_lat(): Conversion of locations in geodetic (geodetic latitude, altitude in kilometers) to geocentric (radius in kilometers , geocentric latitude)

alt_to_ellipsoid_height(): This function converts mean sea level (MSL) altitude in kilometers to ellipsoid height in kilometers

calc_dec_year(): Takes year, month, and day and calculates the decimal year from those inputs

calc_dec_year_array():Takes the array of year, month, and day and outputs the decimal year from those inputs

decimalYearToDateTime(): Convert the decimal year to year, month, day, hour and minute

geomaglib.sh_vars

Computes Spherical Variable

See the detail of functions

comp_sh_vars(): Computes spherical variable and put the results in a dictionary variable computed are (a/r) ^ (n+2), cos_m(lon), and sin_m(lon)

geomaglib.sh_loader

Estimate the total elements from end degree of the model coefficients
Functions for loading WMM2025.COF, IGRF14.COF
Compute time change the model coefficients from the base year of the model (epoch) using secular variation coefficients.

See the detail of functions

calc_sh_degrees_to_num_elems(): Gives you the number of elements from the number of spherical harmonic degree

calc_num_elems_to_sh_degrees(): Gives you the number of spherical harmonic degrees from the total number of elements

load_wmm_coef()

load_igrf_coef()

timely_modify_magnetic_model_wmm()

timely_modify_magnetic_model_HDGM()

geomaglib.dipole

Geomagnetic dipole location for a set of geomagnetic main field coefficients (default is IGRF14)
Geomagnetic dipole to geocentric spherical coordinate (and back) coordinate rotation
Follows approach of Laundal & Richmond

See details of functions

geomaglib.dipole.Dipole

Class representing geomagnetic dipole location for a particular epoch (decimal year)
- Example: dp=Dipole(2024.1)
Method coords, transform from geomagnetic dipole coordinates (lat,lon) to geocentric spherical coordinates (lat,lon)
- Input and output types: scalar float or list of float
- Geocentric to dipole: mlat,mlon = dp.coords(gclat,glon)
- Dipole to geocentric: gclat,glon = dp.coords(mlat,mlon,inverse=True)

Development / Testing

For local development, create a virtual environment, install in editable mode, and run tests: python -m pip install -e . and python -m pytest.

Contacts and contributing to geomaglib:

If you have any questions, please email geomag.models@noaa.gov, submit issue or pull request at https://github.com/CIRES-Geomagnetism/geomaglib.

Metadata

Release files for geomaglib 1.2.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for geomaglib 1.2.4
File	Size	Uploaded
geomaglib-1.2.4.tar.gz	3.1 MB	Apr 15, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for geomaglib 1.2.4
File	Interpreter	ABI	Platform	Reset
geomaglib-1.2.4-py3-none-any.whl 3.2 MB Apr 15, 2026	Python 3	none	any	Details

Total release size: 6.3 MB

Release files / geomaglib-1.2.4.tar.gz

Download URL	geomaglib-1.2.4.tar.gz
Size	3.1 MB
Tags	Source
SHA-256 checksum How to use checksums	`be528794b1f7dabd8d68102b06a9017a68fab9b254d7c50ba78ce7b734c224a1`
BLAKE2b-256 checksum How to use checksums	`e4218e4a53fce54413acd86dc77fa3add7e1eec795c972d35f2a9ccb79e40245`
Upload date	Apr 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.13`

Release files / geomaglib-1.2.4-py3-none-any.whl

Download URL	geomaglib-1.2.4-py3-none-any.whl
Size	3.2 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`5e850aff345d0f991487db75061d9ca3c3c0de03b82dcd9f56045678bc98f4e0`
BLAKE2b-256 checksum How to use checksums	`d668fb689f2bf775276e4a318ef548c291e9da179d66b36f5aa0c66b840bbacb`
Upload date	Apr 15, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.13`