geomaglib 1.2.4

The core library for building geomag model.

geomaglib

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 [e-mail], submit issue or pull request at https://github.com/CIRES-Geomagnetism/geomaglib.