Magnetism Models

Earth magnetic field models and computations.

Magnetism models module.

This module provides implementations of geomagnetic field models including the World Magnetic Model (WMM), International Geomagnetic Reference Field (IGRF), and high-resolution models (EMM, WMMHR).

Examples

>>> from pytcl.magnetism import wmm, magnetic_declination
>>> import numpy as np

>>> # Magnetic field at a location
>>> result = wmm(np.radians(40), np.radians(-105), 1.0, 2026.0)
>>> print(f"Declination: {np.degrees(result.D):.2f}°")
Declination: 7.58°
>>> print(f"Total intensity: {result.F:.0f} nT")
Total intensity: 51207 nT

>>> # Just the declination
>>> D = magnetic_declination(np.radians(40), np.radians(-105))
>>> print(f"Declination: {np.degrees(D):.2f}°")
Declination: 7.67°

>>> # High-resolution models (require external coefficient files)
>>> from pytcl.magnetism import emm, wmmhr, create_emm_test_coefficients
>>> # Create test coefficients for demonstration
>>> coef = create_emm_test_coefficients(n_max=36)

World Magnetic Model (WMM)

World Magnetic Model implementation (WMM2020 epoch, valid 2020-2025).

World Magnetic Model (WMM) implementation.

The WMM is the standard model used by the U.S. Department of Defense, the U.K. Ministry of Defense, NATO, and the International Hydrographic Organization for navigation, attitude, and heading referencing.

References

Chulliat et al., “The US/UK World Magnetic Model for 2020-2025,” NOAA Technical Report, 2020.
https://www.ngdc.noaa.gov/geomag/WMM/

class pytcl.magnetism.wmm.MagneticResult(X, Y, Z, H, F, I, D)[source]

Bases: NamedTuple

Result of magnetic field computation.

Variables:

X (float) – Northward component (nT).
Y (float) – Eastward component (nT).
Z (float) – Downward component (nT).
H (float) – Horizontal intensity (nT).
F (float) – Total intensity (nT).
I (float) – Inclination (dip angle) in radians.
D (float) – Declination in radians.

X: float: Alias for field number 0

Y: float: Alias for field number 1

Z: float: Alias for field number 2

H: float: Alias for field number 3

F: float: Alias for field number 4

I: float: Alias for field number 5

D: float: Alias for field number 6

class pytcl.magnetism.wmm.MagneticCoefficients(g, h, g_dot, h_dot, epoch, n_max)[source]

Bases: NamedTuple

Spherical harmonic coefficients for magnetic model.

Variables:

g (ndarray) – Main field cosine coefficients (nT).
h (ndarray) – Main field sine coefficients (nT).
g_dot (ndarray) – Secular variation of g (nT/year).
h_dot (ndarray) – Secular variation of h (nT/year).
epoch (float) – Reference epoch (decimal year).
n_max (int) – Maximum degree.

g: ndarray[tuple[Any, ...], dtype[floating]]: Alias for field number 0

h: ndarray[tuple[Any, ...], dtype[floating]]: Alias for field number 1

g_dot: ndarray[tuple[Any, ...], dtype[floating]]: Alias for field number 2

h_dot: ndarray[tuple[Any, ...], dtype[floating]]: Alias for field number 3

epoch: float: Alias for field number 4

n_max: int: Alias for field number 5

pytcl.magnetism.wmm.create_wmm2020_coefficients()[source]

Create WMM2020 model coefficients.

Returns:: coeffs – WMM2020 spherical harmonic coefficients.
Return type:: MagneticCoefficients

Examples

>>> coeffs = create_wmm2020_coefficients()
>>> coeffs.epoch
2020.0
>>> coeffs.n_max
12

Notes

These are the official WMM2020 coefficients valid from 2020.0 to 2025.0, embedded verbatim from the NOAA/NCEI WMM.COF distribution file. For use beyond 2025, updated coefficients should be obtained from NOAA.

pytcl.magnetism.wmm.create_wmm2025_coefficients()[source]

Create WMM2025 model coefficients.

Returns:: coeffs – WMM2025 spherical harmonic coefficients.
Return type:: MagneticCoefficients

Examples

>>> coeffs = create_wmm2025_coefficients()
>>> coeffs.epoch
2025.0
>>> coeffs.n_max
12

Notes

These are the official WMM2025 coefficients valid from 2025.0 to 2030.0, embedded verbatim from the NOAA/NCEI WMM.COF distribution file.

pytcl.magnetism.wmm.magnetic_field_spherical(lat, lon, r, year, coeffs=(array([[0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-2.93518e+04, -1.41080e+03, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-2.55660e+03, 2.95110e+03, 1.64930e+03, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [1.36100e+03, -2.40410e+03, 1.24380e+03, 4.53600e+02, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [8.95000e+02, 7.99500e+02, 5.57000e+01, -2.81100e+02, 1.21000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-2.33200e+02, 3.68900e+02, 1.87200e+02, -1.38700e+02, -1.42000e+02, 2.09000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [6.44000e+01, 6.38000e+01, 7.69000e+01, -1.15700e+02, -4.09000e+01, 1.49000e+01, -6.07000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [7.95000e+01, -7.70000e+01, -8.80000e+00, 5.93000e+01, 1.58000e+01, 2.50000e+00, -1.11000e+01, 1.42000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [2.32000e+01, 1.08000e+01, -1.75000e+01, 2.00000e+00, -2.17000e+01, 1.69000e+01, 1.50000e+01, -1.68000e+01, 9.00000e-01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [4.60000e+00, 7.80000e+00, 3.00000e+00, -2.00000e-01, -2.50000e+00, -1.31000e+01, 2.40000e+00, 8.60000e+00, -8.70000e+00, -1.29000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-1.30000e+00, -6.40000e+00, 2.00000e-01, 2.00000e+00, -1.00000e+00, -6.00000e-01, -9.00000e-01, 1.50000e+00, 9.00000e-01, -2.70000e+00, -3.90000e+00, 0.00000e+00, 0.00000e+00], [2.90000e+00, -1.50000e+00, -2.50000e+00, 2.40000e+00, -6.00000e-01, -1.00000e-01, -6.00000e-01, -1.00000e-01, 1.10000e+00, -1.00000e+00, -2.00000e-01, 2.60000e+00, 0.00000e+00], [-2.00000e+00, -2.00000e-01, 3.00000e-01, 1.20000e+00, -1.30000e+00, 6.00000e-01, 6.00000e-01, 5.00000e-01, -1.00000e-01, -4.00000e-01, -2.00000e-01, -1.30000e+00, -7.00000e-01]]), array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5454e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -3.1336e+03, -8.1510e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -5.6600e+01, 2.3750e+02, -5.4950e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 2.7860e+02, -1.3390e+02, 2.1200e+02, -3.7560e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5400e+01, 2.2020e+02, -1.2290e+02, 4.3000e+01, 1.0610e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.8400e+01, 1.6800e+01, 4.8800e+01, -5.9800e+01, 1.0900e+01, 7.2700e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -4.8900e+01, -1.4400e+01, -1.0000e+00, 2.3400e+01, -7.4000e+00, -2.5100e+01, -2.3000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 7.1000e+00, -1.2600e+01, 1.1400e+01, -9.7000e+00, 1.2700e+01, 7.0000e-01, -5.2000e+00, 3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -2.4800e+01, 1.2200e+01, 8.3000e+00, -3.3000e+00, -5.2000e+00, 7.2000e+00, -6.0000e-01, 8.0000e-01, 1.0000e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 3.3000e+00, 0.0000e+00, 2.4000e+00, 5.3000e+00, -9.1000e+00, 4.0000e-01, -4.2000e+00, -3.8000e+00, 9.0000e-01, -9.1000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 0.0000e+00, 2.9000e+00, -6.0000e-01, 2.0000e-01, 5.0000e-01, -3.0000e-01, -1.2000e+00, -1.7000e+00, -2.9000e+00, -1.8000e+00, -2.3000e+00, 0.0000e+00], [0.0000e+00, -1.3000e+00, 7.0000e-01, 1.0000e+00, -1.4000e+00, -0.0000e+00, 6.0000e-01, -1.0000e-01, 8.0000e-01, 1.0000e-01, -1.0000e+00, 1.0000e-01, 2.0000e-01]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [12., 9.7, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-11.6, -5.2, -8., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.3, -4.2, 0.4, -15.6, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.6, -2.4, -6., 5.6, -7., 0., 0., 0., 0., 0., 0., 0., 0.], [0.6, 1.4, 0., 0.6, 2.2, 0.9, 0., 0., 0., 0., 0., 0., 0.], [-0.2, -0.4, 0.9, 1.2, -0.9, 0.3, 0.9, 0., 0., 0., 0., 0., 0.], [-0., -0.1, -0.1, 0.5, -0.1, -0.8, -0.8, 0.8, 0., 0., 0., 0., 0.], [-0.1, 0.2, 0., 0.5, -0.1, 0.3, 0.2, -0., 0.2, 0., 0., 0., 0.], [-0., -0.1, 0.1, 0.3, -0.3, 0., 0.3, -0.1, 0.1, -0.1, 0., 0., 0.], [0.1, 0., 0.1, 0.1, -0., -0.3, 0., -0.1, -0.1, -0., -0., 0., 0.], [0., -0., 0., 0., 0., -0.1, 0., -0., -0.1, -0.1, -0.1, -0.1, 0.], [0., 0., -0., -0., -0., -0., 0.1, -0., 0., 0., -0.1, -0., -0.1]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -21.5, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -27.7, -12.1, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 4., -0.3, -4.1, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -1.1, 4.1, 1.6, -4.4, 0., 0., 0., 0., 0., 0., 0., 0.], [0., -0.5, 2.2, 0.4, 1.7, 1.9, 0., 0., 0., 0., 0., 0., 0.], [0., 0.3, -1.6, -0.4, 0.9, 0.7, 0.9, 0., 0., 0., 0., 0., 0.], [0., 0.6, 0.5, -0.8, 0., -1., 0.6, -0.2, 0., 0., 0., 0., 0.], [0., -0.2, 0.5, -0.4, 0.4, -0.5, -0.6, 0.3, 0.2, 0., 0., 0., 0.], [0., -0.3, 0.3, -0.3, 0.3, 0.2, -0.1, -0.2, 0.4, 0.1, 0., 0., 0.], [0., 0., -0., -0.2, 0.1, -0.1, 0.1, 0., -0.1, 0.2, -0., 0., 0.], [0., -0., 0.1, -0., 0.1, -0., -0., 0.1, -0., 0., 0., 0., 0.], [0., -0., 0., -0.1, 0.1, -0., -0., -0., 0., -0., -0., 0., -0.1]]), 2025.0, 12), use_cache=True)[source]

Compute magnetic field in spherical coordinates.

Parameters:

lat (float) – Geocentric latitude in radians.
lon (float) – Longitude in radians.
r (float) – Radial distance from Earth’s center in km.
year (float) – Decimal year (e.g., 2023.5 for mid-2023).
coeffs (MagneticCoefficients, optional) – Model coefficients. Default WMM2025.
use_cache (bool, optional) – Whether to use LRU caching for repeated queries. Default True. Set to False for single-use queries or when memory is constrained.

Returns:

B_r (float) – Radial component (positive outward) in nT.
B_theta (float) – Colatitude component (positive southward) in nT.
B_phi (float) – Longitude component (positive eastward) in nT.

Return type:

Tuple[float, float, float]

Notes

Results are cached by default using LRU caching. Inputs are quantized to a configurable precision before caching to improve hit rates for nearby queries. Use get_magnetic_cache_info() to check cache statistics and clear_magnetic_cache() to free memory.

Examples

>>> import numpy as np
>>> from pytcl.magnetism import magnetic_field_spherical
>>> # Compute at Earth's surface (40°N, 105°W, sea level)
>>> lat = np.radians(40)
>>> lon = np.radians(-105)
>>> r = 6371.2  # Earth mean radius in km
>>> B_r, B_theta, B_phi = magnetic_field_spherical(lat, lon, r, 2023.0)
>>> # All components should be on order of tens to tens of thousands of nT
>>> bool(20000 < (B_r**2 + B_theta**2 + B_phi**2)**0.5 < 70000)
True

pytcl.magnetism.wmm.wmm(lat, lon, h=0.0, year=2025.0, coeffs=(array([[0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-2.93518e+04, -1.41080e+03, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-2.55660e+03, 2.95110e+03, 1.64930e+03, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [1.36100e+03, -2.40410e+03, 1.24380e+03, 4.53600e+02, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [8.95000e+02, 7.99500e+02, 5.57000e+01, -2.81100e+02, 1.21000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-2.33200e+02, 3.68900e+02, 1.87200e+02, -1.38700e+02, -1.42000e+02, 2.09000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [6.44000e+01, 6.38000e+01, 7.69000e+01, -1.15700e+02, -4.09000e+01, 1.49000e+01, -6.07000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [7.95000e+01, -7.70000e+01, -8.80000e+00, 5.93000e+01, 1.58000e+01, 2.50000e+00, -1.11000e+01, 1.42000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [2.32000e+01, 1.08000e+01, -1.75000e+01, 2.00000e+00, -2.17000e+01, 1.69000e+01, 1.50000e+01, -1.68000e+01, 9.00000e-01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [4.60000e+00, 7.80000e+00, 3.00000e+00, -2.00000e-01, -2.50000e+00, -1.31000e+01, 2.40000e+00, 8.60000e+00, -8.70000e+00, -1.29000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-1.30000e+00, -6.40000e+00, 2.00000e-01, 2.00000e+00, -1.00000e+00, -6.00000e-01, -9.00000e-01, 1.50000e+00, 9.00000e-01, -2.70000e+00, -3.90000e+00, 0.00000e+00, 0.00000e+00], [2.90000e+00, -1.50000e+00, -2.50000e+00, 2.40000e+00, -6.00000e-01, -1.00000e-01, -6.00000e-01, -1.00000e-01, 1.10000e+00, -1.00000e+00, -2.00000e-01, 2.60000e+00, 0.00000e+00], [-2.00000e+00, -2.00000e-01, 3.00000e-01, 1.20000e+00, -1.30000e+00, 6.00000e-01, 6.00000e-01, 5.00000e-01, -1.00000e-01, -4.00000e-01, -2.00000e-01, -1.30000e+00, -7.00000e-01]]), array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5454e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -3.1336e+03, -8.1510e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -5.6600e+01, 2.3750e+02, -5.4950e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 2.7860e+02, -1.3390e+02, 2.1200e+02, -3.7560e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5400e+01, 2.2020e+02, -1.2290e+02, 4.3000e+01, 1.0610e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.8400e+01, 1.6800e+01, 4.8800e+01, -5.9800e+01, 1.0900e+01, 7.2700e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -4.8900e+01, -1.4400e+01, -1.0000e+00, 2.3400e+01, -7.4000e+00, -2.5100e+01, -2.3000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 7.1000e+00, -1.2600e+01, 1.1400e+01, -9.7000e+00, 1.2700e+01, 7.0000e-01, -5.2000e+00, 3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -2.4800e+01, 1.2200e+01, 8.3000e+00, -3.3000e+00, -5.2000e+00, 7.2000e+00, -6.0000e-01, 8.0000e-01, 1.0000e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 3.3000e+00, 0.0000e+00, 2.4000e+00, 5.3000e+00, -9.1000e+00, 4.0000e-01, -4.2000e+00, -3.8000e+00, 9.0000e-01, -9.1000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 0.0000e+00, 2.9000e+00, -6.0000e-01, 2.0000e-01, 5.0000e-01, -3.0000e-01, -1.2000e+00, -1.7000e+00, -2.9000e+00, -1.8000e+00, -2.3000e+00, 0.0000e+00], [0.0000e+00, -1.3000e+00, 7.0000e-01, 1.0000e+00, -1.4000e+00, -0.0000e+00, 6.0000e-01, -1.0000e-01, 8.0000e-01, 1.0000e-01, -1.0000e+00, 1.0000e-01, 2.0000e-01]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [12., 9.7, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-11.6, -5.2, -8., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.3, -4.2, 0.4, -15.6, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.6, -2.4, -6., 5.6, -7., 0., 0., 0., 0., 0., 0., 0., 0.], [0.6, 1.4, 0., 0.6, 2.2, 0.9, 0., 0., 0., 0., 0., 0., 0.], [-0.2, -0.4, 0.9, 1.2, -0.9, 0.3, 0.9, 0., 0., 0., 0., 0., 0.], [-0., -0.1, -0.1, 0.5, -0.1, -0.8, -0.8, 0.8, 0., 0., 0., 0., 0.], [-0.1, 0.2, 0., 0.5, -0.1, 0.3, 0.2, -0., 0.2, 0., 0., 0., 0.], [-0., -0.1, 0.1, 0.3, -0.3, 0., 0.3, -0.1, 0.1, -0.1, 0., 0., 0.], [0.1, 0., 0.1, 0.1, -0., -0.3, 0., -0.1, -0.1, -0., -0., 0., 0.], [0., -0., 0., 0., 0., -0.1, 0., -0., -0.1, -0.1, -0.1, -0.1, 0.], [0., 0., -0., -0., -0., -0., 0.1, -0., 0., 0., -0.1, -0., -0.1]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -21.5, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -27.7, -12.1, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 4., -0.3, -4.1, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -1.1, 4.1, 1.6, -4.4, 0., 0., 0., 0., 0., 0., 0., 0.], [0., -0.5, 2.2, 0.4, 1.7, 1.9, 0., 0., 0., 0., 0., 0., 0.], [0., 0.3, -1.6, -0.4, 0.9, 0.7, 0.9, 0., 0., 0., 0., 0., 0.], [0., 0.6, 0.5, -0.8, 0., -1., 0.6, -0.2, 0., 0., 0., 0., 0.], [0., -0.2, 0.5, -0.4, 0.4, -0.5, -0.6, 0.3, 0.2, 0., 0., 0., 0.], [0., -0.3, 0.3, -0.3, 0.3, 0.2, -0.1, -0.2, 0.4, 0.1, 0., 0., 0.], [0., 0., -0., -0.2, 0.1, -0.1, 0.1, 0., -0.1, 0.2, -0., 0., 0.], [0., -0., 0.1, -0., 0.1, -0., -0., 0.1, -0., 0., 0., 0., 0.], [0., -0., 0., -0.1, 0.1, -0., -0., -0., 0., -0., -0., 0., -0.1]]), 2025.0, 12))[source]

Compute magnetic field using World Magnetic Model.

Parameters:

lat (float) – Geodetic latitude in radians.
lon (float) – Longitude in radians.
h (float, optional) – Height above WGS84 ellipsoid in km. Default 0.
year (float, optional) – Decimal year. Default 2025.0.
coeffs (MagneticCoefficients, optional) – Model coefficients. Default WMM2025.

Returns:

result – Magnetic field components and derived quantities.

Return type:

MagneticResult

Warns:

UserWarning – If year falls outside coeffs’s five-year validity window (epoch to epoch + 5.0); the secular-variation terms are being extrapolated and the result is not an official WMM value.

Examples

>>> import numpy as np
>>> result = wmm(np.radians(40), np.radians(-105), 1.0, 2026.0)
>>> print(f"Declination: {np.degrees(result.D):.2f}°")
Declination: 7.58°
>>> print(f"Inclination: {np.degrees(result.I):.2f}°")
Inclination: 66.08°
>>> print(f"Total intensity: {result.F:.0f} nT")
Total intensity: 51207 nT

pytcl.magnetism.wmm.magnetic_declination(lat, lon, h=0.0, year=2025.0, coeffs=(array([[0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-2.93518e+04, -1.41080e+03, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-2.55660e+03, 2.95110e+03, 1.64930e+03, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [1.36100e+03, -2.40410e+03, 1.24380e+03, 4.53600e+02, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [8.95000e+02, 7.99500e+02, 5.57000e+01, -2.81100e+02, 1.21000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-2.33200e+02, 3.68900e+02, 1.87200e+02, -1.38700e+02, -1.42000e+02, 2.09000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [6.44000e+01, 6.38000e+01, 7.69000e+01, -1.15700e+02, -4.09000e+01, 1.49000e+01, -6.07000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [7.95000e+01, -7.70000e+01, -8.80000e+00, 5.93000e+01, 1.58000e+01, 2.50000e+00, -1.11000e+01, 1.42000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [2.32000e+01, 1.08000e+01, -1.75000e+01, 2.00000e+00, -2.17000e+01, 1.69000e+01, 1.50000e+01, -1.68000e+01, 9.00000e-01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [4.60000e+00, 7.80000e+00, 3.00000e+00, -2.00000e-01, -2.50000e+00, -1.31000e+01, 2.40000e+00, 8.60000e+00, -8.70000e+00, -1.29000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-1.30000e+00, -6.40000e+00, 2.00000e-01, 2.00000e+00, -1.00000e+00, -6.00000e-01, -9.00000e-01, 1.50000e+00, 9.00000e-01, -2.70000e+00, -3.90000e+00, 0.00000e+00, 0.00000e+00], [2.90000e+00, -1.50000e+00, -2.50000e+00, 2.40000e+00, -6.00000e-01, -1.00000e-01, -6.00000e-01, -1.00000e-01, 1.10000e+00, -1.00000e+00, -2.00000e-01, 2.60000e+00, 0.00000e+00], [-2.00000e+00, -2.00000e-01, 3.00000e-01, 1.20000e+00, -1.30000e+00, 6.00000e-01, 6.00000e-01, 5.00000e-01, -1.00000e-01, -4.00000e-01, -2.00000e-01, -1.30000e+00, -7.00000e-01]]), array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5454e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -3.1336e+03, -8.1510e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -5.6600e+01, 2.3750e+02, -5.4950e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 2.7860e+02, -1.3390e+02, 2.1200e+02, -3.7560e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5400e+01, 2.2020e+02, -1.2290e+02, 4.3000e+01, 1.0610e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.8400e+01, 1.6800e+01, 4.8800e+01, -5.9800e+01, 1.0900e+01, 7.2700e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -4.8900e+01, -1.4400e+01, -1.0000e+00, 2.3400e+01, -7.4000e+00, -2.5100e+01, -2.3000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 7.1000e+00, -1.2600e+01, 1.1400e+01, -9.7000e+00, 1.2700e+01, 7.0000e-01, -5.2000e+00, 3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -2.4800e+01, 1.2200e+01, 8.3000e+00, -3.3000e+00, -5.2000e+00, 7.2000e+00, -6.0000e-01, 8.0000e-01, 1.0000e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 3.3000e+00, 0.0000e+00, 2.4000e+00, 5.3000e+00, -9.1000e+00, 4.0000e-01, -4.2000e+00, -3.8000e+00, 9.0000e-01, -9.1000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 0.0000e+00, 2.9000e+00, -6.0000e-01, 2.0000e-01, 5.0000e-01, -3.0000e-01, -1.2000e+00, -1.7000e+00, -2.9000e+00, -1.8000e+00, -2.3000e+00, 0.0000e+00], [0.0000e+00, -1.3000e+00, 7.0000e-01, 1.0000e+00, -1.4000e+00, -0.0000e+00, 6.0000e-01, -1.0000e-01, 8.0000e-01, 1.0000e-01, -1.0000e+00, 1.0000e-01, 2.0000e-01]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [12., 9.7, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-11.6, -5.2, -8., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.3, -4.2, 0.4, -15.6, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.6, -2.4, -6., 5.6, -7., 0., 0., 0., 0., 0., 0., 0., 0.], [0.6, 1.4, 0., 0.6, 2.2, 0.9, 0., 0., 0., 0., 0., 0., 0.], [-0.2, -0.4, 0.9, 1.2, -0.9, 0.3, 0.9, 0., 0., 0., 0., 0., 0.], [-0., -0.1, -0.1, 0.5, -0.1, -0.8, -0.8, 0.8, 0., 0., 0., 0., 0.], [-0.1, 0.2, 0., 0.5, -0.1, 0.3, 0.2, -0., 0.2, 0., 0., 0., 0.], [-0., -0.1, 0.1, 0.3, -0.3, 0., 0.3, -0.1, 0.1, -0.1, 0., 0., 0.], [0.1, 0., 0.1, 0.1, -0., -0.3, 0., -0.1, -0.1, -0., -0., 0., 0.], [0., -0., 0., 0., 0., -0.1, 0., -0., -0.1, -0.1, -0.1, -0.1, 0.], [0., 0., -0., -0., -0., -0., 0.1, -0., 0., 0., -0.1, -0., -0.1]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -21.5, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -27.7, -12.1, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 4., -0.3, -4.1, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -1.1, 4.1, 1.6, -4.4, 0., 0., 0., 0., 0., 0., 0., 0.], [0., -0.5, 2.2, 0.4, 1.7, 1.9, 0., 0., 0., 0., 0., 0., 0.], [0., 0.3, -1.6, -0.4, 0.9, 0.7, 0.9, 0., 0., 0., 0., 0., 0.], [0., 0.6, 0.5, -0.8, 0., -1., 0.6, -0.2, 0., 0., 0., 0., 0.], [0., -0.2, 0.5, -0.4, 0.4, -0.5, -0.6, 0.3, 0.2, 0., 0., 0., 0.], [0., -0.3, 0.3, -0.3, 0.3, 0.2, -0.1, -0.2, 0.4, 0.1, 0., 0., 0.], [0., 0., -0., -0.2, 0.1, -0.1, 0.1, 0., -0.1, 0.2, -0., 0., 0.], [0., -0., 0.1, -0., 0.1, -0., -0., 0.1, -0., 0., 0., 0., 0.], [0., -0., 0., -0.1, 0.1, -0., -0., -0., 0., -0., -0., 0., -0.1]]), 2025.0, 12))[source]

Compute magnetic declination (variation).

Parameters:

lat (float) – Geodetic latitude in radians.
lon (float) – Longitude in radians.
h (float, optional) – Height above ellipsoid in km. Default 0.
year (float, optional) – Decimal year. Default 2025.0.
coeffs (MagneticCoefficients, optional) – Model coefficients.

Returns:

D – Magnetic declination in radians. Positive = east of true north. Negative = west of true north.

Return type:

float

Examples

>>> import numpy as np
>>> # Declination in Denver, CO (easterly, i.e. positive)
>>> D = magnetic_declination(np.radians(39.7), np.radians(-105.0))
>>> print(f"Declination: {np.degrees(D):.1f}°")
Declination: 7.6°

pytcl.magnetism.wmm.magnetic_inclination(lat, lon, h=0.0, year=2025.0, coeffs=(array([[0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-2.93518e+04, -1.41080e+03, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-2.55660e+03, 2.95110e+03, 1.64930e+03, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [1.36100e+03, -2.40410e+03, 1.24380e+03, 4.53600e+02, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [8.95000e+02, 7.99500e+02, 5.57000e+01, -2.81100e+02, 1.21000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-2.33200e+02, 3.68900e+02, 1.87200e+02, -1.38700e+02, -1.42000e+02, 2.09000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [6.44000e+01, 6.38000e+01, 7.69000e+01, -1.15700e+02, -4.09000e+01, 1.49000e+01, -6.07000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [7.95000e+01, -7.70000e+01, -8.80000e+00, 5.93000e+01, 1.58000e+01, 2.50000e+00, -1.11000e+01, 1.42000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [2.32000e+01, 1.08000e+01, -1.75000e+01, 2.00000e+00, -2.17000e+01, 1.69000e+01, 1.50000e+01, -1.68000e+01, 9.00000e-01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [4.60000e+00, 7.80000e+00, 3.00000e+00, -2.00000e-01, -2.50000e+00, -1.31000e+01, 2.40000e+00, 8.60000e+00, -8.70000e+00, -1.29000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-1.30000e+00, -6.40000e+00, 2.00000e-01, 2.00000e+00, -1.00000e+00, -6.00000e-01, -9.00000e-01, 1.50000e+00, 9.00000e-01, -2.70000e+00, -3.90000e+00, 0.00000e+00, 0.00000e+00], [2.90000e+00, -1.50000e+00, -2.50000e+00, 2.40000e+00, -6.00000e-01, -1.00000e-01, -6.00000e-01, -1.00000e-01, 1.10000e+00, -1.00000e+00, -2.00000e-01, 2.60000e+00, 0.00000e+00], [-2.00000e+00, -2.00000e-01, 3.00000e-01, 1.20000e+00, -1.30000e+00, 6.00000e-01, 6.00000e-01, 5.00000e-01, -1.00000e-01, -4.00000e-01, -2.00000e-01, -1.30000e+00, -7.00000e-01]]), array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5454e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -3.1336e+03, -8.1510e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -5.6600e+01, 2.3750e+02, -5.4950e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 2.7860e+02, -1.3390e+02, 2.1200e+02, -3.7560e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5400e+01, 2.2020e+02, -1.2290e+02, 4.3000e+01, 1.0610e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.8400e+01, 1.6800e+01, 4.8800e+01, -5.9800e+01, 1.0900e+01, 7.2700e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -4.8900e+01, -1.4400e+01, -1.0000e+00, 2.3400e+01, -7.4000e+00, -2.5100e+01, -2.3000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 7.1000e+00, -1.2600e+01, 1.1400e+01, -9.7000e+00, 1.2700e+01, 7.0000e-01, -5.2000e+00, 3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -2.4800e+01, 1.2200e+01, 8.3000e+00, -3.3000e+00, -5.2000e+00, 7.2000e+00, -6.0000e-01, 8.0000e-01, 1.0000e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 3.3000e+00, 0.0000e+00, 2.4000e+00, 5.3000e+00, -9.1000e+00, 4.0000e-01, -4.2000e+00, -3.8000e+00, 9.0000e-01, -9.1000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 0.0000e+00, 2.9000e+00, -6.0000e-01, 2.0000e-01, 5.0000e-01, -3.0000e-01, -1.2000e+00, -1.7000e+00, -2.9000e+00, -1.8000e+00, -2.3000e+00, 0.0000e+00], [0.0000e+00, -1.3000e+00, 7.0000e-01, 1.0000e+00, -1.4000e+00, -0.0000e+00, 6.0000e-01, -1.0000e-01, 8.0000e-01, 1.0000e-01, -1.0000e+00, 1.0000e-01, 2.0000e-01]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [12., 9.7, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-11.6, -5.2, -8., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.3, -4.2, 0.4, -15.6, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.6, -2.4, -6., 5.6, -7., 0., 0., 0., 0., 0., 0., 0., 0.], [0.6, 1.4, 0., 0.6, 2.2, 0.9, 0., 0., 0., 0., 0., 0., 0.], [-0.2, -0.4, 0.9, 1.2, -0.9, 0.3, 0.9, 0., 0., 0., 0., 0., 0.], [-0., -0.1, -0.1, 0.5, -0.1, -0.8, -0.8, 0.8, 0., 0., 0., 0., 0.], [-0.1, 0.2, 0., 0.5, -0.1, 0.3, 0.2, -0., 0.2, 0., 0., 0., 0.], [-0., -0.1, 0.1, 0.3, -0.3, 0., 0.3, -0.1, 0.1, -0.1, 0., 0., 0.], [0.1, 0., 0.1, 0.1, -0., -0.3, 0., -0.1, -0.1, -0., -0., 0., 0.], [0., -0., 0., 0., 0., -0.1, 0., -0., -0.1, -0.1, -0.1, -0.1, 0.], [0., 0., -0., -0., -0., -0., 0.1, -0., 0., 0., -0.1, -0., -0.1]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -21.5, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -27.7, -12.1, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 4., -0.3, -4.1, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -1.1, 4.1, 1.6, -4.4, 0., 0., 0., 0., 0., 0., 0., 0.], [0., -0.5, 2.2, 0.4, 1.7, 1.9, 0., 0., 0., 0., 0., 0., 0.], [0., 0.3, -1.6, -0.4, 0.9, 0.7, 0.9, 0., 0., 0., 0., 0., 0.], [0., 0.6, 0.5, -0.8, 0., -1., 0.6, -0.2, 0., 0., 0., 0., 0.], [0., -0.2, 0.5, -0.4, 0.4, -0.5, -0.6, 0.3, 0.2, 0., 0., 0., 0.], [0., -0.3, 0.3, -0.3, 0.3, 0.2, -0.1, -0.2, 0.4, 0.1, 0., 0., 0.], [0., 0., -0., -0.2, 0.1, -0.1, 0.1, 0., -0.1, 0.2, -0., 0., 0.], [0., -0., 0.1, -0., 0.1, -0., -0., 0.1, -0., 0., 0., 0., 0.], [0., -0., 0., -0.1, 0.1, -0., -0., -0., 0., -0., -0., 0., -0.1]]), 2025.0, 12))[source]

Compute magnetic inclination (dip angle).

Parameters:

lat (float) – Geodetic latitude in radians.
lon (float) – Longitude in radians.
h (float, optional) – Height above ellipsoid in km. Default 0.
year (float, optional) – Decimal year. Default 2025.0.
coeffs (MagneticCoefficients, optional) – Model coefficients.

Returns:

I – Magnetic inclination in radians. Positive = field points into Earth (Northern hemisphere). Negative = field points out of Earth (Southern hemisphere).

Return type:

float

Examples

>>> import numpy as np
>>> from pytcl.magnetism import magnetic_inclination
>>> # Inclination at 40°N, 105°W (Denver)
>>> lat = np.radians(40)
>>> lon = np.radians(-105)
>>> I = magnetic_inclination(lat, lon, 1.6, 2026.0)
>>> # Northern hemisphere: inclination should be positive
>>> bool(I > 0)
True
>>> # Typical values in US are 50-70 degrees
>>> bool(0.8 < I < 1.3)  # ~46-74 degrees
True

pytcl.magnetism.wmm.magnetic_field_intensity(lat, lon, h=0.0, year=2025.0, coeffs=(array([[0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-2.93518e+04, -1.41080e+03, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-2.55660e+03, 2.95110e+03, 1.64930e+03, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [1.36100e+03, -2.40410e+03, 1.24380e+03, 4.53600e+02, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [8.95000e+02, 7.99500e+02, 5.57000e+01, -2.81100e+02, 1.21000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-2.33200e+02, 3.68900e+02, 1.87200e+02, -1.38700e+02, -1.42000e+02, 2.09000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [6.44000e+01, 6.38000e+01, 7.69000e+01, -1.15700e+02, -4.09000e+01, 1.49000e+01, -6.07000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [7.95000e+01, -7.70000e+01, -8.80000e+00, 5.93000e+01, 1.58000e+01, 2.50000e+00, -1.11000e+01, 1.42000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [2.32000e+01, 1.08000e+01, -1.75000e+01, 2.00000e+00, -2.17000e+01, 1.69000e+01, 1.50000e+01, -1.68000e+01, 9.00000e-01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [4.60000e+00, 7.80000e+00, 3.00000e+00, -2.00000e-01, -2.50000e+00, -1.31000e+01, 2.40000e+00, 8.60000e+00, -8.70000e+00, -1.29000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-1.30000e+00, -6.40000e+00, 2.00000e-01, 2.00000e+00, -1.00000e+00, -6.00000e-01, -9.00000e-01, 1.50000e+00, 9.00000e-01, -2.70000e+00, -3.90000e+00, 0.00000e+00, 0.00000e+00], [2.90000e+00, -1.50000e+00, -2.50000e+00, 2.40000e+00, -6.00000e-01, -1.00000e-01, -6.00000e-01, -1.00000e-01, 1.10000e+00, -1.00000e+00, -2.00000e-01, 2.60000e+00, 0.00000e+00], [-2.00000e+00, -2.00000e-01, 3.00000e-01, 1.20000e+00, -1.30000e+00, 6.00000e-01, 6.00000e-01, 5.00000e-01, -1.00000e-01, -4.00000e-01, -2.00000e-01, -1.30000e+00, -7.00000e-01]]), array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5454e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -3.1336e+03, -8.1510e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -5.6600e+01, 2.3750e+02, -5.4950e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 2.7860e+02, -1.3390e+02, 2.1200e+02, -3.7560e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5400e+01, 2.2020e+02, -1.2290e+02, 4.3000e+01, 1.0610e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.8400e+01, 1.6800e+01, 4.8800e+01, -5.9800e+01, 1.0900e+01, 7.2700e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -4.8900e+01, -1.4400e+01, -1.0000e+00, 2.3400e+01, -7.4000e+00, -2.5100e+01, -2.3000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 7.1000e+00, -1.2600e+01, 1.1400e+01, -9.7000e+00, 1.2700e+01, 7.0000e-01, -5.2000e+00, 3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -2.4800e+01, 1.2200e+01, 8.3000e+00, -3.3000e+00, -5.2000e+00, 7.2000e+00, -6.0000e-01, 8.0000e-01, 1.0000e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 3.3000e+00, 0.0000e+00, 2.4000e+00, 5.3000e+00, -9.1000e+00, 4.0000e-01, -4.2000e+00, -3.8000e+00, 9.0000e-01, -9.1000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 0.0000e+00, 2.9000e+00, -6.0000e-01, 2.0000e-01, 5.0000e-01, -3.0000e-01, -1.2000e+00, -1.7000e+00, -2.9000e+00, -1.8000e+00, -2.3000e+00, 0.0000e+00], [0.0000e+00, -1.3000e+00, 7.0000e-01, 1.0000e+00, -1.4000e+00, -0.0000e+00, 6.0000e-01, -1.0000e-01, 8.0000e-01, 1.0000e-01, -1.0000e+00, 1.0000e-01, 2.0000e-01]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [12., 9.7, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-11.6, -5.2, -8., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.3, -4.2, 0.4, -15.6, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.6, -2.4, -6., 5.6, -7., 0., 0., 0., 0., 0., 0., 0., 0.], [0.6, 1.4, 0., 0.6, 2.2, 0.9, 0., 0., 0., 0., 0., 0., 0.], [-0.2, -0.4, 0.9, 1.2, -0.9, 0.3, 0.9, 0., 0., 0., 0., 0., 0.], [-0., -0.1, -0.1, 0.5, -0.1, -0.8, -0.8, 0.8, 0., 0., 0., 0., 0.], [-0.1, 0.2, 0., 0.5, -0.1, 0.3, 0.2, -0., 0.2, 0., 0., 0., 0.], [-0., -0.1, 0.1, 0.3, -0.3, 0., 0.3, -0.1, 0.1, -0.1, 0., 0., 0.], [0.1, 0., 0.1, 0.1, -0., -0.3, 0., -0.1, -0.1, -0., -0., 0., 0.], [0., -0., 0., 0., 0., -0.1, 0., -0., -0.1, -0.1, -0.1, -0.1, 0.], [0., 0., -0., -0., -0., -0., 0.1, -0., 0., 0., -0.1, -0., -0.1]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -21.5, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -27.7, -12.1, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 4., -0.3, -4.1, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -1.1, 4.1, 1.6, -4.4, 0., 0., 0., 0., 0., 0., 0., 0.], [0., -0.5, 2.2, 0.4, 1.7, 1.9, 0., 0., 0., 0., 0., 0., 0.], [0., 0.3, -1.6, -0.4, 0.9, 0.7, 0.9, 0., 0., 0., 0., 0., 0.], [0., 0.6, 0.5, -0.8, 0., -1., 0.6, -0.2, 0., 0., 0., 0., 0.], [0., -0.2, 0.5, -0.4, 0.4, -0.5, -0.6, 0.3, 0.2, 0., 0., 0., 0.], [0., -0.3, 0.3, -0.3, 0.3, 0.2, -0.1, -0.2, 0.4, 0.1, 0., 0., 0.], [0., 0., -0., -0.2, 0.1, -0.1, 0.1, 0., -0.1, 0.2, -0., 0., 0.], [0., -0., 0.1, -0., 0.1, -0., -0., 0.1, -0., 0., 0., 0., 0.], [0., -0., 0., -0.1, 0.1, -0., -0., -0., 0., -0., -0., 0., -0.1]]), 2025.0, 12))[source]

Compute total magnetic field intensity.

Parameters:

lat (float) – Geodetic latitude in radians.
lon (float) – Longitude in radians.
h (float, optional) – Height above ellipsoid in km. Default 0.
year (float, optional) – Decimal year. Default 2025.0.
coeffs (MagneticCoefficients, optional) – Model coefficients.

Returns:

F – Total magnetic field intensity in nT.

Return type:

float

Examples

>>> import numpy as np
>>> from pytcl.magnetism import magnetic_field_intensity
>>> # Field intensity at magnetic equator vs pole
>>> F_eq = magnetic_field_intensity(0, 0, 0, 2026.0)  # Equator
>>> F_pole = magnetic_field_intensity(np.radians(80), 0, 0, 2026.0)  # Near pole
>>> # Field is stronger at poles
>>> bool(F_pole > F_eq)
True
>>> # Typical Earth field is 25,000 to 65,000 nT
>>> bool(25000 < F_eq < 35000)  # Equatorial field is weaker
True
>>> bool(55000 < F_pole < 65000)  # Polar field is stronger
True

pytcl.magnetism.wmm.get_magnetic_cache_info()[source]

Get information about the magnetic field computation cache.

Returns:: info – Dictionary containing cache statistics: - hits: Number of cache hits - misses: Number of cache misses - maxsize: Maximum cache size - currsize: Current number of cached entries - hit_rate: Ratio of hits to total calls (0-1)
Return type:: dict

Examples

>>> from pytcl.magnetism import get_magnetic_cache_info
>>> info = get_magnetic_cache_info()
>>> 0.0 <= info['hit_rate'] <= 1.0
True

pytcl.magnetism.wmm.clear_magnetic_cache()[source]

Clear the magnetic field computation cache.

This can be useful when memory is constrained or when switching between different coefficient sets.

Examples

>>> from pytcl.magnetism import clear_magnetic_cache
>>> clear_magnetic_cache()  # Free cached computations

pytcl.magnetism.wmm.configure_magnetic_cache(maxsize=None, precision=None)[source]

Configure the magnetic field computation cache.

Parameters:

maxsize (int, optional) – Maximum number of entries in the cache. If None, keeps current. Set to 0 to disable caching.
precision (dict, optional) – Dictionary with keys ‘lat’, ‘lon’, ‘r’, ‘year’ specifying decimal places for rounding. Higher values = more precision but fewer cache hits.

Notes

Changing cache configuration clears the existing cache.

Examples

>>> from pytcl.magnetism import configure_magnetic_cache
>>> # Increase cache size for batch processing
>>> configure_magnetic_cache(maxsize=4096)
>>> # Reduce precision for more cache hits
>>> configure_magnetic_cache(precision={'lat': 4, 'lon': 4, 'r': 2, 'year': 1})
>>> # Restore the default precision
>>> configure_magnetic_cache(precision={'lat': 6, 'lon': 6, 'r': 3, 'year': 2})

IGRF Model

International Geomagnetic Reference Field implementation: IGRF-14 (the default, with the full 1900.0-2025.0 epoch tables and 2025-30 secular variation) plus the superseded IGRF-13 for reproducibility.

International Geomagnetic Reference Field (IGRF) implementation.

The IGRF is a standard mathematical description of the Earth’s main magnetic field, used widely in studies of the Earth’s interior, its ionosphere and magnetosphere, and in various applications.

References

Alken et al., “International Geomagnetic Reference Field: the thirteenth generation,” Earth, Planets and Space, 2021.
https://www.ngdc.noaa.gov/IAGA/vmod/igrf.html

class pytcl.magnetism.igrf.IGRFModel(epoch, coeffs, valid_from, valid_to)[source]

Bases: NamedTuple

IGRF model for a specific epoch.

Variables:

epoch (float) – Reference epoch year.
coeffs (MagneticCoefficients) – Spherical harmonic coefficients.
valid_from (float) – Start of validity period.
valid_to (float) – End of validity period.

epoch: float: Alias for field number 0

coeffs: MagneticCoefficients: Alias for field number 1

valid_from: float: Alias for field number 2

valid_to: float: Alias for field number 3

pytcl.magnetism.igrf.create_igrf13_coefficients()[source]

Create IGRF-13 model coefficients for epoch 2020.

Returns:: coeffs – IGRF-13 spherical harmonic coefficients (epoch 2020.0, with 2020-2025 secular variation), embedded verbatim from the official IAGA igrf13coeffs.txt distribution.
Return type:: MagneticCoefficients

Examples

>>> coeffs = create_igrf13_coefficients()
>>> coeffs.epoch
2020.0
>>> coeffs.n_max
13

Notes

IGRF-13 is valid from 1900.0 to 2025.0. This function returns the coefficients for the 2020.0 epoch; for earlier epochs the historical tables should be interpolated.

IGRF-13’s validity window ends 2025.0 and it is superseded by create_igrf14_coefficients() / IGRF14, the default for igrf() since v2.8.0. IGRF-13 is retained for reproducibility of results computed against it. Calls with year beyond 2025.0 extrapolate the 2020-2025 secular variation (g_dot/h_dot) linearly past the model’s official range – treat results for year > 2025.0 as an unofficial extrapolation, not IGRF-13 output.

pytcl.magnetism.igrf.create_igrf14_coefficients(year=None)[source]

Create IGRF-14 model coefficients for a given decimal year.

Parameters:: year (float, optional) – Decimal year selecting the coefficient epoch. Default is the IGRF-14 reference epoch, 2025.0.
Returns:: coeffs – Spherical harmonic coefficients whose linear time term reproduces the IGRF-14 field at year. At or after 2025.0 this is the reference-epoch main field with the published 2025-2030 secular variation as g_dot/h_dot. Within 1900.0-2025.0 it is the main field of the five-year epoch at or below year, with the slope of the bracketing interval as the time term, so a field evaluation at year linearly interpolates the two neighboring epochs. Before 1900.0 the 1900-1905 slope extrapolates backwards, with a warning.
Return type:: MagneticCoefficients

Examples

>>> coeffs = create_igrf14_coefficients()
>>> coeffs.epoch
2025.0
>>> coeffs.g[1, 0]
-29350.0
>>> create_igrf14_coefficients(2012.5).epoch
2010.0

Notes

Port of getIGRFCoeffs.m from the MATLAB library (epoch selection and interpolation; the Schmidt semi-normalized coefficients are kept in nT for pytcl.magnetism.wmm.wmm()-style evaluation rather than fully normalized in Tesla).

Deviation from the MATLAB original: a warning is emitted for years beyond 2030.0, the end of the published secular-variation window. getIGRFCoeffs.m extrapolates forward silently; the IGRF-13 model embedded in this library previously did the same past 2025.0, and that silence is exactly how it went stale unnoticed.

pytcl.magnetism.igrf.igrf(lat, lon, h=0.0, year=2025.0, coeffs=None)[source]

Compute magnetic field using IGRF model.

Parameters:

lat (float) – Geodetic latitude in radians.
lon (float) – Longitude in radians.
h (float, optional) – Height above WGS84 ellipsoid in km. Default 0.
year (float, optional) – Decimal year. Default 2025.0, the IGRF-14 reference epoch.
coeffs (MagneticCoefficients, optional) – Model coefficients. Default: IGRF-14 coefficients selected for year by create_igrf14_coefficients(), interpolating the 1900.0-2025.0 epoch tables and warning outside the model’s validity window.

Returns:

result – Magnetic field components and derived quantities.

Return type:

MagneticResult

Examples

>>> import numpy as np
>>> result = igrf(np.radians(45), np.radians(-75), 0, 2023.0)
>>> print(f"Total field: {result.F:.0f} nT")
Total field: 53341 nT

pytcl.magnetism.igrf.igrf_declination(lat, lon, h=0.0, year=2025.0)[source]

Compute magnetic declination using IGRF.

Parameters:

lat (float) – Geodetic latitude in radians.
lon (float) – Longitude in radians.
h (float, optional) – Height in km. Default 0.
year (float, optional) – Decimal year. Default 2025.0.

Returns:

D – Declination in radians.

Return type:

float

Examples

>>> import numpy as np
>>> from pytcl.magnetism import igrf_declination
>>> # Declination at Denver (40°N, 105°W)
>>> lat = np.radians(40)
>>> lon = np.radians(-105)
>>> D = igrf_declination(lat, lon, 1.6, 2023.0)
>>> # Denver lies west of the agonic line: easterly declination (~8° E)
>>> print(f"Declination: {np.degrees(D):.1f}°")
Declination: 7.8°
>>> bool(0 < D < 0.35)  # East is positive
True

pytcl.magnetism.igrf.igrf_inclination(lat, lon, h=0.0, year=2025.0)[source]

Compute magnetic inclination using IGRF.

Parameters:

lat (float) – Geodetic latitude in radians.
lon (float) – Longitude in radians.
h (float, optional) – Height in km. Default 0.
year (float, optional) – Decimal year. Default 2025.0.

Returns:

I – Inclination in radians.

Return type:

float

Examples

>>> import numpy as np
>>> from pytcl.magnetism import igrf_inclination
>>> # Inclination comparison: equator vs pole
>>> I_eq = igrf_inclination(0, 0, 0, 2023.0)  # Equator
>>> I_pole = igrf_inclination(np.radians(85), 0, 0, 2023.0)  # Near pole
>>> # The dip equator is offset from the geographic equator; at (0°N, 0°E)
>>> # in the Gulf of Guinea the inclination is moderately negative (~-30°)
>>> bool(-0.6 < I_eq < 0)
True
>>> bool(abs(I_pole) > 1.4)  # ~80+ degrees near the pole
True

pytcl.magnetism.igrf.dipole_moment(coeffs=(array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.9350e+04, -1.4103e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.5562e+03, 2.9509e+03, 1.6487e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [1.3609e+03, -2.4042e+03, 1.2438e+03, 4.5340e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [8.9470e+02, 7.9960e+02, 5.5800e+01, -2.8110e+02, 1.2000e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.3290e+02, 3.6900e+02, 1.8720e+02, -1.3870e+02, -1.4190e+02, 2.0900e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [6.4300e+01, 6.3800e+01, 7.6700e+01, -1.1570e+02, -4.0900e+01, 1.4900e+01, -6.0800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [7.9600e+01, -7.6900e+01, -8.8000e+00, 5.9300e+01, 1.5800e+01, 2.5000e+00, -1.1200e+01, 1.4300e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [2.3100e+01, 1.0900e+01, -1.7500e+01, 2.0000e+00, -2.1800e+01, 1.6900e+01, 1.4900e+01, -1.6800e+01, 1.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [4.7000e+00, 8.0000e+00, 3.0000e+00, -2.0000e-01, -2.5000e+00, -1.3100e+01, 2.4000e+00, 8.6000e+00, -8.7000e+00, -1.2800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-1.3000e+00, -6.4000e+00, 2.0000e-01, 2.0000e+00, -1.0000e+00, -5.0000e-01, -9.0000e-01, 1.5000e+00, 9.0000e-01, -2.6000e+00, -3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [3.0000e+00, -1.4000e+00, -2.5000e+00, 2.4000e+00, -6.0000e-01, 0.0000e+00, -6.0000e-01, -1.0000e-01, 1.1000e+00, -1.0000e+00, -1.0000e-01, 2.6000e+00, 0.0000e+00, 0.0000e+00], [-2.0000e+00, -1.0000e-01, 4.0000e-01, 1.2000e+00, -1.2000e+00, 6.0000e-01, 5.0000e-01, 5.0000e-01, -1.0000e-01, -5.0000e-01, -2.0000e-01, -1.2000e+00, -7.0000e-01, 0.0000e+00], [2.0000e-01, -9.0000e-01, 6.0000e-01, 7.0000e-01, -2.0000e-01, 5.0000e-01, 1.0000e-01, 7.0000e-01, 0.0000e+00, 3.0000e-01, 2.0000e-01, 4.0000e-01, -5.0000e-01, -4.0000e-01]]), array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5455e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -3.1336e+03, -8.1420e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -5.6900e+01, 2.3760e+02, -5.4960e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 2.7860e+02, -1.3400e+02, 2.1200e+02, -3.7540e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5300e+01, 2.2000e+02, -1.2290e+02, 4.2900e+01, 1.0620e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.8400e+01, 1.6800e+01, 4.8900e+01, -5.9800e+01, 1.0900e+01, 7.2800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -4.8900e+01, -1.4400e+01, -1.0000e+00, 2.3500e+01, -7.4000e+00, -2.5100e+01, -2.2000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 7.2000e+00, -1.2600e+01, 1.1500e+01, -9.7000e+00, 1.2700e+01, 7.0000e-01, -5.2000e+00, 3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -2.4800e+01, 1.2100e+01, 8.3000e+00, -3.4000e+00, -5.3000e+00, 7.2000e+00, -6.0000e-01, 8.0000e-01, 9.8000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 3.3000e+00, 1.0000e-01, 2.5000e+00, 5.4000e+00, -9.0000e+00, 4.0000e-01, -4.2000e+00, -3.8000e+00, 9.0000e-01, -9.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 0.0000e+00, 2.8000e+00, -6.0000e-01, 1.0000e-01, 5.0000e-01, -3.0000e-01, -1.2000e+00, -1.7000e+00, -2.9000e+00, -1.8000e+00, -2.3000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.2000e+00, 6.0000e-01, 1.0000e+00, -1.5000e+00, 0.0000e+00, 6.0000e-01, -2.0000e-01, 8.0000e-01, 1.0000e-01, -9.0000e-01, 1.0000e-01, 2.0000e-01, 0.0000e+00], [0.0000e+00, -9.0000e-01, 7.0000e-01, 1.2000e+00, -3.0000e-01, -1.3000e+00, -1.0000e-01, 2.0000e-01, -2.0000e-01, 5.0000e-01, 6.0000e-01, -6.0000e-01, -3.0000e-01, -5.0000e-01]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [12.6, 10., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-11.2, -5.3, -8.3, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.5, -4.4, 0.4, -15.6, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.7, -2.3, -5.8, 5.4, -6.8, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0.6, 1.3, 0., 0.7, 2.3, 1., 0., 0., 0., 0., 0., 0., 0., 0.], [-0.2, -0.3, 0.8, 1.2, -0.8, 0.4, 0.9, 0., 0., 0., 0., 0., 0., 0.], [-0.1, -0.1, -0.1, 0.5, -0.1, -0.8, -0.8, 0.9, 0., 0., 0., 0., 0., 0.], [-0.1, 0.2, 0., 0.4, -0.1, 0.3, 0.1, 0., 0.3, 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -21.5, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -27.3, -11.1, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 3.8, -0.2, -3.9, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -1.3, 4.1, 1.6, -4.1, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -0.5, 2.1, 0.5, 1.7, 1.9, 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0.3, -1.6, -0.4, 0.8, 0.7, 0.9, 0., 0., 0., 0., 0., 0., 0.], [0., 0.6, 0.5, -0.7, 0., -0.9, 0.5, -0.3, 0., 0., 0., 0., 0., 0.], [0., -0.3, 0.4, -0.3, 0.4, -0.5, -0.6, 0.3, 0.2, 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]), 2025.0, 13))[source]

Compute the centered dipole moment.

Parameters:: coeffs (MagneticCoefficients, optional) – Model coefficients. Default IGRF14.
Returns:: M – Dipole moment in nT * km^3.
Return type:: float

Notes

The dipole moment is computed from the n=1 Gauss coefficients: M = a^3 * sqrt(g10^2 + g11^2 + h11^2)

Examples

>>> from pytcl.magnetism import dipole_moment, IGRF14
>>> # Compute Earth's dipole moment from IGRF-14
>>> M = dipole_moment(IGRF14)
>>> # Earth's dipole moment is approximately 7.9 × 10^22 A·m²
>>> # In nT·km³ units, this is about 7.9 × 10^15
>>> 7e15 < M < 8.5e15
True

pytcl.magnetism.igrf.dipole_axis(coeffs=(array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.9350e+04, -1.4103e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.5562e+03, 2.9509e+03, 1.6487e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [1.3609e+03, -2.4042e+03, 1.2438e+03, 4.5340e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [8.9470e+02, 7.9960e+02, 5.5800e+01, -2.8110e+02, 1.2000e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.3290e+02, 3.6900e+02, 1.8720e+02, -1.3870e+02, -1.4190e+02, 2.0900e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [6.4300e+01, 6.3800e+01, 7.6700e+01, -1.1570e+02, -4.0900e+01, 1.4900e+01, -6.0800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [7.9600e+01, -7.6900e+01, -8.8000e+00, 5.9300e+01, 1.5800e+01, 2.5000e+00, -1.1200e+01, 1.4300e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [2.3100e+01, 1.0900e+01, -1.7500e+01, 2.0000e+00, -2.1800e+01, 1.6900e+01, 1.4900e+01, -1.6800e+01, 1.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [4.7000e+00, 8.0000e+00, 3.0000e+00, -2.0000e-01, -2.5000e+00, -1.3100e+01, 2.4000e+00, 8.6000e+00, -8.7000e+00, -1.2800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-1.3000e+00, -6.4000e+00, 2.0000e-01, 2.0000e+00, -1.0000e+00, -5.0000e-01, -9.0000e-01, 1.5000e+00, 9.0000e-01, -2.6000e+00, -3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [3.0000e+00, -1.4000e+00, -2.5000e+00, 2.4000e+00, -6.0000e-01, 0.0000e+00, -6.0000e-01, -1.0000e-01, 1.1000e+00, -1.0000e+00, -1.0000e-01, 2.6000e+00, 0.0000e+00, 0.0000e+00], [-2.0000e+00, -1.0000e-01, 4.0000e-01, 1.2000e+00, -1.2000e+00, 6.0000e-01, 5.0000e-01, 5.0000e-01, -1.0000e-01, -5.0000e-01, -2.0000e-01, -1.2000e+00, -7.0000e-01, 0.0000e+00], [2.0000e-01, -9.0000e-01, 6.0000e-01, 7.0000e-01, -2.0000e-01, 5.0000e-01, 1.0000e-01, 7.0000e-01, 0.0000e+00, 3.0000e-01, 2.0000e-01, 4.0000e-01, -5.0000e-01, -4.0000e-01]]), array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5455e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -3.1336e+03, -8.1420e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -5.6900e+01, 2.3760e+02, -5.4960e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 2.7860e+02, -1.3400e+02, 2.1200e+02, -3.7540e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5300e+01, 2.2000e+02, -1.2290e+02, 4.2900e+01, 1.0620e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.8400e+01, 1.6800e+01, 4.8900e+01, -5.9800e+01, 1.0900e+01, 7.2800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -4.8900e+01, -1.4400e+01, -1.0000e+00, 2.3500e+01, -7.4000e+00, -2.5100e+01, -2.2000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 7.2000e+00, -1.2600e+01, 1.1500e+01, -9.7000e+00, 1.2700e+01, 7.0000e-01, -5.2000e+00, 3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -2.4800e+01, 1.2100e+01, 8.3000e+00, -3.4000e+00, -5.3000e+00, 7.2000e+00, -6.0000e-01, 8.0000e-01, 9.8000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 3.3000e+00, 1.0000e-01, 2.5000e+00, 5.4000e+00, -9.0000e+00, 4.0000e-01, -4.2000e+00, -3.8000e+00, 9.0000e-01, -9.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 0.0000e+00, 2.8000e+00, -6.0000e-01, 1.0000e-01, 5.0000e-01, -3.0000e-01, -1.2000e+00, -1.7000e+00, -2.9000e+00, -1.8000e+00, -2.3000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.2000e+00, 6.0000e-01, 1.0000e+00, -1.5000e+00, 0.0000e+00, 6.0000e-01, -2.0000e-01, 8.0000e-01, 1.0000e-01, -9.0000e-01, 1.0000e-01, 2.0000e-01, 0.0000e+00], [0.0000e+00, -9.0000e-01, 7.0000e-01, 1.2000e+00, -3.0000e-01, -1.3000e+00, -1.0000e-01, 2.0000e-01, -2.0000e-01, 5.0000e-01, 6.0000e-01, -6.0000e-01, -3.0000e-01, -5.0000e-01]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [12.6, 10., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-11.2, -5.3, -8.3, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.5, -4.4, 0.4, -15.6, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.7, -2.3, -5.8, 5.4, -6.8, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0.6, 1.3, 0., 0.7, 2.3, 1., 0., 0., 0., 0., 0., 0., 0., 0.], [-0.2, -0.3, 0.8, 1.2, -0.8, 0.4, 0.9, 0., 0., 0., 0., 0., 0., 0.], [-0.1, -0.1, -0.1, 0.5, -0.1, -0.8, -0.8, 0.9, 0., 0., 0., 0., 0., 0.], [-0.1, 0.2, 0., 0.4, -0.1, 0.3, 0.1, 0., 0.3, 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -21.5, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -27.3, -11.1, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 3.8, -0.2, -3.9, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -1.3, 4.1, 1.6, -4.1, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -0.5, 2.1, 0.5, 1.7, 1.9, 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0.3, -1.6, -0.4, 0.8, 0.7, 0.9, 0., 0., 0., 0., 0., 0., 0.], [0., 0.6, 0.5, -0.7, 0., -0.9, 0.5, -0.3, 0., 0., 0., 0., 0., 0.], [0., -0.3, 0.4, -0.3, 0.4, -0.5, -0.6, 0.3, 0.2, 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]), 2025.0, 13))[source]

Compute the geocentric dipole axis direction.

Parameters:

coeffs (MagneticCoefficients, optional) – Model coefficients. Default IGRF14.

Returns:

lat (float) – Latitude of the north geomagnetic pole in radians.
lon (float) – Longitude of the north geomagnetic pole in radians.

Return type:

tuple[float, float]

Notes

The geomagnetic pole is where the centered dipole axis intersects the Earth’s surface.

Examples

>>> import numpy as np
>>> from pytcl.magnetism import dipole_axis, IGRF14
>>> # Compute geomagnetic pole location
>>> lat, lon = dipole_axis(IGRF14)
>>> # Geomagnetic north pole is around 80.7°N, 72.5°W (epoch 2025)
>>> print(f"{np.degrees(lat):.2f}°N, {np.degrees(lon):.2f}°E")
80.79°N, -72.76°E
>>> bool(70 < np.degrees(lat) < 85)
True
>>> bool(-100 < np.degrees(lon) < -60)
True

pytcl.magnetism.igrf.magnetic_north_pole(year=2025.0, coeffs=None)[source]

Compute the location of the magnetic north pole.

The magnetic north pole is where the field is vertical (inclination = 90°). This differs from the geomagnetic pole due to non-dipole field contributions.

Parameters:

year (float, optional) – Decimal year. Default 2025.0.
coeffs (MagneticCoefficients, optional) – Model coefficients. Default: IGRF-14 coefficients selected for year by create_igrf14_coefficients().

Returns:

lat (float) – Latitude of magnetic north pole in radians.
lon (float) – Longitude of magnetic north pole in radians.

Return type:

tuple[float, float]

Notes

This uses an iterative search starting from the dipole pole. The magnetic pole moves over time.

Examples

>>> import numpy as np
>>> from pytcl.magnetism import magnetic_north_pole, dipole_axis
>>> # Magnetic north pole location (2023)
>>> lat, lon = magnetic_north_pole(2023.0)
>>> # The pole has drifted past 86°N toward the Siberian side of
>>> # the Arctic (east longitude), around 86°N, 146°E in 2023
>>> bool(75 < np.degrees(lat) < 90)
True
>>> bool(130 < np.degrees(lon) < 180)
True
>>> # Compare with geomagnetic pole
>>> geo_lat, geo_lon = dipole_axis()
>>> # Magnetic pole differs from geomagnetic pole
>>> bool(abs(lat - geo_lat) > 0.01)  # Different locations
True

Enhanced Magnetic Model (EMM) and WMMHR2025

High-resolution magnetic field models: EMM2017 (degree 790) and WMMHR2025 (degree 133). Both support scalar and array inputs for lat/lon/height.

Enhanced Magnetic Model (EMM) and World Magnetic Model High Resolution (WMMHR).

This module provides support for high-degree magnetic field models: - EMM2017: Degree 790, resolves anomalies down to 51 km wavelength - WMMHR2025: Degree 133, resolves anomalies down to ~300 km wavelength

These models provide higher spatial resolution than the standard WMM (degree 12) by including crustal magnetic field contributions.

References

Maus, S., et al. “EMAG2: A 2-arc min resolution Earth Magnetic Anomaly Grid compiled from satellite, airborne, and marine magnetic measurements.” Geochemistry, Geophysics, Geosystems 10.8 (2009).
NOAA National Centers for Environmental Information, “Enhanced Magnetic Model (EMM).” https://www.ncei.noaa.gov/products/enhanced-magnetic-model
NOAA National Centers for Environmental Information, “World Magnetic Model High Resolution (WMMHR).” https://www.ncei.noaa.gov/products/world-magnetic-model-high-resolution

class pytcl.magnetism.emm.HighResCoefficients(g, h, g_dot, h_dot, epoch, n_max, n_max_sv, model_name)[source]

Bases: NamedTuple

High-resolution magnetic model coefficients.

Extends MagneticCoefficients with additional metadata for high-degree models like EMM and WMMHR.

Variables:

g (ndarray) – Main field cosine coefficients (nT), shape (n_max+1, n_max+1).
h (ndarray) – Main field sine coefficients (nT), shape (n_max+1, n_max+1).
g_dot (ndarray) – Secular variation of g (nT/year), shape (n_max_sv+1, n_max_sv+1).
h_dot (ndarray) – Secular variation of h (nT/year), shape (n_max_sv+1, n_max_sv+1).
epoch (float) – Reference epoch (decimal year).
n_max (int) – Maximum degree for main field.
n_max_sv (int) – Maximum degree for secular variation (may be < n_max).
model_name (str) – Model identifier (“EMM2017” or “WMMHR2025”).

g: ndarray[tuple[Any, ...], dtype[floating]]: Alias for field number 0

h: ndarray[tuple[Any, ...], dtype[floating]]: Alias for field number 1

g_dot: ndarray[tuple[Any, ...], dtype[floating]]: Alias for field number 2

h_dot: ndarray[tuple[Any, ...], dtype[floating]]: Alias for field number 3

epoch: float: Alias for field number 4

n_max: int: Alias for field number 5

n_max_sv: int: Alias for field number 6

model_name: str: Alias for field number 7

pytcl.magnetism.emm.get_data_dir()[source]

Get the pytcl data directory for external data files.

The data directory is located at ~/.pytcl/data/ by default. Can be overridden by setting the PYTCL_DATA_DIR environment variable.

Returns:: Path to the data directory.
Return type:: Path

pytcl.magnetism.emm.parse_emm_file(filepath, n_max=None)[source]

Parse an EMM/WMMHR coefficient file.

The file format is similar to WMM but with more coefficients:: n m g_nm h_nm g_dot_nm h_dot_nm

Parameters:

filepath (Path) – Path to the coefficient file.
n_max (int, optional) – Maximum degree to load. If None, loads all coefficients.

Returns:

g (ndarray) – Cosine coefficients.
h (ndarray) – Sine coefficients.
g_dot (ndarray) – Secular variation of g.
h_dot (ndarray) – Secular variation of h.
epoch (float) – Model epoch.
actual_n_max (int) – Maximum degree loaded.

Return type:

tuple[ndarray[tuple[Any, …], dtype[floating]], ndarray[tuple[Any, …], dtype[floating]], ndarray[tuple[Any, …], dtype[floating]], ndarray[tuple[Any, …], dtype[floating]], float, int]

pytcl.magnetism.emm.create_test_coefficients(n_max=36)[source]

Create test coefficients for low-degree testing.

Creates a simplified set of coefficients for testing purposes, using the same low-degree terms as WMM2020 extended with synthetic crustal field terms.

Parameters:: n_max (int) – Maximum degree (default 36).
Returns:: Test coefficient set.
Return type:: HighResCoefficients

pytcl.magnetism.emm.load_emm_coefficients(model='EMM2017', n_max=None)[source]

Load high-resolution magnetic model coefficients.

Parameters:

model (str) – Model name, either “EMM2017” or “WMMHR2025”.
n_max (int, optional) – Maximum degree to load. If None, loads the full model.

Returns:

Loaded coefficient structure.

Return type:

HighResCoefficients

Raises:

FileNotFoundError – If the coefficient file is not found.
ValueError – If an unknown model is specified.

Examples

>>> coef = load_emm_coefficients("WMMHR2025", n_max=50)
>>> coef.n_max
50

pytcl.magnetism.emm.emm(lat, lon, h=0.0, year=2020.0, model='EMM2017', n_max=None, coefficients=None)[source]

Compute magnetic field using Enhanced Magnetic Model.

The EMM provides higher spatial resolution than WMM by including crustal magnetic field contributions up to degree 790.

Parameters:

lat (float) – Geodetic latitude in radians.
lon (float) – Longitude in radians.
h (float, optional) – Height above WGS84 ellipsoid in km. Default 0.
year (float, optional) – Decimal year. Default 2020.0.
model (str, optional) – Model name (“EMM2017” or “WMMHR2025”). Default “EMM2017”.
n_max (int, optional) – Maximum degree to evaluate. Default uses full model.
coefficients (HighResCoefficients, optional) – Pre-loaded coefficients. If None, loads from file.

Returns:

result – Magnetic field components and derived quantities.

Return type:

MagneticResult

Warns:

UserWarning – If year falls outside model’s declared validity window (EMM_PARAMETERS[model][“valid_start”] to [“valid_end”]); the secular-variation terms are being extrapolated and the result is not an official model value.

Examples

>>> import numpy as np
>>> # Use test coefficients for demonstration
>>> coef = create_test_coefficients(n_max=36)
>>> result = emm(np.radians(40), np.radians(-105), 1.0, 2020.0, coefficients=coef)
>>> bool(np.isfinite(result.D) and np.isfinite(result.F))
True

pytcl.magnetism.emm.wmmhr(lat, lon, h=0.0, year=2025.0, n_max=None, coefficients=None)[source]

Compute magnetic field using World Magnetic Model High Resolution.

WMMHR2025 extends WMM to degree 133, providing higher spatial resolution for applications requiring more accurate local field values.

Parameters:

lat (float) – Geodetic latitude in radians.
lon (float) – Longitude in radians.
h (float, optional) – Height above WGS84 ellipsoid in km. Default 0.
year (float, optional) – Decimal year. Default 2025.0.
n_max (int, optional) – Maximum degree to evaluate. Default uses full model (133).
coefficients (HighResCoefficients, optional) – Pre-loaded coefficients. If None, loads from file.

Returns:

result – Magnetic field components and derived quantities.

Return type:

MagneticResult

Warns:

UserWarning – If year falls outside WMMHR2025’s 2025.0-2030.0 validity window; see emm.

Notes

WMMHR2025 is valid for 2025.0 - 2030.0. For dates outside this range, results are extrapolated (see Warns).

Secular variation is only computed for degrees 1-15. Higher degree terms represent static crustal field.

pytcl.magnetism.emm.emm_declination(lat, lon, h=0.0, year=2020.0, model='EMM2017', n_max=None, coefficients=None)[source]

Compute magnetic declination using EMM/WMMHR.

Parameters:

lat (float or ndarray) – Geodetic latitude in radians.
lon (float or ndarray) – Longitude in radians.
h (float or ndarray, optional) – Height above WGS84 ellipsoid in km.
year (float, optional) – Decimal year.
model (str, optional) – Model name.
n_max (int, optional) – Maximum degree to evaluate.
coefficients (HighResCoefficients, optional) – Pre-loaded coefficients.

Returns:

Magnetic declination in radians.

Return type:

float or ndarray

pytcl.magnetism.emm.emm_inclination(lat, lon, h=0.0, year=2020.0, model='EMM2017', n_max=None, coefficients=None)[source]

Compute magnetic inclination using EMM/WMMHR.

Parameters:

lat (float or ndarray) – Geodetic latitude in radians.
lon (float or ndarray) – Longitude in radians.
h (float or ndarray, optional) – Height above WGS84 ellipsoid in km.
year (float, optional) – Decimal year.
model (str, optional) – Model name.
n_max (int, optional) – Maximum degree to evaluate.
coefficients (HighResCoefficients, optional) – Pre-loaded coefficients.

Returns:

Magnetic inclination (dip) in radians.

Return type:

float or ndarray

pytcl.magnetism.emm.emm_intensity(lat, lon, h=0.0, year=2020.0, model='EMM2017', n_max=None, coefficients=None)[source]

Compute total magnetic field intensity using EMM/WMMHR.

Parameters:

lat (float or ndarray) – Geodetic latitude in radians.
lon (float or ndarray) – Longitude in radians.
h (float or ndarray, optional) – Height above WGS84 ellipsoid in km.
year (float, optional) – Decimal year.
model (str, optional) – Model name.
n_max (int, optional) – Maximum degree to evaluate.
coefficients (HighResCoefficients, optional) – Pre-loaded coefficients.

Returns:

Total magnetic field intensity in nT.

Return type:

float or ndarray

Package-level Aliases

pytcl.magnetism re-exports two EMM helpers under names that make their scope explicit at the package level.

pytcl.magnetism.create_emm_test_coefficients(n_max=36)

Create test coefficients for low-degree testing.

Creates a simplified set of coefficients for testing purposes, using the same low-degree terms as WMM2020 extended with synthetic crustal field terms.

Parameters:: n_max (int) – Maximum degree (default 36).
Returns:: Test coefficient set.
Return type:: HighResCoefficients

pytcl.magnetism.get_emm_data_dir()

Get the pytcl data directory for external data files.

The data directory is located at ~/.pytcl/data/ by default. Can be overridden by setting the PYTCL_DATA_DIR environment variable.

Returns:: Path to the data directory.
Return type:: Path

Magnetic Coordinate Systems

Centered-dipole transforms, magnetic/geographic heading conversions, and apex/quasi-dipole coordinates by field-line tracing.

Magnetic coordinate systems.

Ports of the MATLAB TCL’s Magnetism coordinate half: centered dipole (CD) transforms, magnetic apex and quasi-dipole (QD) coordinates via field-line tracing, and magnetic/geographic heading conversions.

The field-line tracer integrates along the normalized magnetic flux direction until the ellipsoidal height stops increasing, then locates the apex by root-finding on the level condition – algorithmically the MATLAB implementation, with SciPy’s adaptive RK45 and event root-finding in place of the hand-rolled adaptive step and fminbnd (a documented swap; the fixtures pin agreement).

Positions are ITRS/ECEF Cartesian in meters unless stated otherwise.

References

A. D. Richmond, “Ionospheric electrodynamics using magnetic apex coordinates,” Journal of Geomagnetism and Geoelectricity, vol. 47, no. 2, pp. 191-212, 1995.
J. T. Emmert, A. D. Richmond, and D. P. Drob, “A computationally compact representation of magnetic-apex and quasi-dipole coordinates with smooth base vectors,” Journal of Geophysical Research, vol. 115, no. A8, 2010.

pytcl.magnetism.coordinates.cd_rotation_matrix(g10=None, g11=None, h11=None, coeffs=(array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.9350e+04, -1.4103e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.5562e+03, 2.9509e+03, 1.6487e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [1.3609e+03, -2.4042e+03, 1.2438e+03, 4.5340e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [8.9470e+02, 7.9960e+02, 5.5800e+01, -2.8110e+02, 1.2000e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.3290e+02, 3.6900e+02, 1.8720e+02, -1.3870e+02, -1.4190e+02, 2.0900e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [6.4300e+01, 6.3800e+01, 7.6700e+01, -1.1570e+02, -4.0900e+01, 1.4900e+01, -6.0800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [7.9600e+01, -7.6900e+01, -8.8000e+00, 5.9300e+01, 1.5800e+01, 2.5000e+00, -1.1200e+01, 1.4300e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [2.3100e+01, 1.0900e+01, -1.7500e+01, 2.0000e+00, -2.1800e+01, 1.6900e+01, 1.4900e+01, -1.6800e+01, 1.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [4.7000e+00, 8.0000e+00, 3.0000e+00, -2.0000e-01, -2.5000e+00, -1.3100e+01, 2.4000e+00, 8.6000e+00, -8.7000e+00, -1.2800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-1.3000e+00, -6.4000e+00, 2.0000e-01, 2.0000e+00, -1.0000e+00, -5.0000e-01, -9.0000e-01, 1.5000e+00, 9.0000e-01, -2.6000e+00, -3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [3.0000e+00, -1.4000e+00, -2.5000e+00, 2.4000e+00, -6.0000e-01, 0.0000e+00, -6.0000e-01, -1.0000e-01, 1.1000e+00, -1.0000e+00, -1.0000e-01, 2.6000e+00, 0.0000e+00, 0.0000e+00], [-2.0000e+00, -1.0000e-01, 4.0000e-01, 1.2000e+00, -1.2000e+00, 6.0000e-01, 5.0000e-01, 5.0000e-01, -1.0000e-01, -5.0000e-01, -2.0000e-01, -1.2000e+00, -7.0000e-01, 0.0000e+00], [2.0000e-01, -9.0000e-01, 6.0000e-01, 7.0000e-01, -2.0000e-01, 5.0000e-01, 1.0000e-01, 7.0000e-01, 0.0000e+00, 3.0000e-01, 2.0000e-01, 4.0000e-01, -5.0000e-01, -4.0000e-01]]), array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5455e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -3.1336e+03, -8.1420e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -5.6900e+01, 2.3760e+02, -5.4960e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 2.7860e+02, -1.3400e+02, 2.1200e+02, -3.7540e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5300e+01, 2.2000e+02, -1.2290e+02, 4.2900e+01, 1.0620e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.8400e+01, 1.6800e+01, 4.8900e+01, -5.9800e+01, 1.0900e+01, 7.2800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -4.8900e+01, -1.4400e+01, -1.0000e+00, 2.3500e+01, -7.4000e+00, -2.5100e+01, -2.2000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 7.2000e+00, -1.2600e+01, 1.1500e+01, -9.7000e+00, 1.2700e+01, 7.0000e-01, -5.2000e+00, 3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -2.4800e+01, 1.2100e+01, 8.3000e+00, -3.4000e+00, -5.3000e+00, 7.2000e+00, -6.0000e-01, 8.0000e-01, 9.8000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 3.3000e+00, 1.0000e-01, 2.5000e+00, 5.4000e+00, -9.0000e+00, 4.0000e-01, -4.2000e+00, -3.8000e+00, 9.0000e-01, -9.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 0.0000e+00, 2.8000e+00, -6.0000e-01, 1.0000e-01, 5.0000e-01, -3.0000e-01, -1.2000e+00, -1.7000e+00, -2.9000e+00, -1.8000e+00, -2.3000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.2000e+00, 6.0000e-01, 1.0000e+00, -1.5000e+00, 0.0000e+00, 6.0000e-01, -2.0000e-01, 8.0000e-01, 1.0000e-01, -9.0000e-01, 1.0000e-01, 2.0000e-01, 0.0000e+00], [0.0000e+00, -9.0000e-01, 7.0000e-01, 1.2000e+00, -3.0000e-01, -1.3000e+00, -1.0000e-01, 2.0000e-01, -2.0000e-01, 5.0000e-01, 6.0000e-01, -6.0000e-01, -3.0000e-01, -5.0000e-01]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [12.6, 10., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-11.2, -5.3, -8.3, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.5, -4.4, 0.4, -15.6, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.7, -2.3, -5.8, 5.4, -6.8, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0.6, 1.3, 0., 0.7, 2.3, 1., 0., 0., 0., 0., 0., 0., 0., 0.], [-0.2, -0.3, 0.8, 1.2, -0.8, 0.4, 0.9, 0., 0., 0., 0., 0., 0., 0.], [-0.1, -0.1, -0.1, 0.5, -0.1, -0.8, -0.8, 0.9, 0., 0., 0., 0., 0., 0.], [-0.1, 0.2, 0., 0.4, -0.1, 0.3, 0.1, 0., 0.3, 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -21.5, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -27.3, -11.1, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 3.8, -0.2, -3.9, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -1.3, 4.1, 1.6, -4.1, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -0.5, 2.1, 0.5, 1.7, 1.9, 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0.3, -1.6, -0.4, 0.8, 0.7, 0.9, 0., 0., 0., 0., 0., 0., 0.], [0., 0.6, 0.5, -0.7, 0., -0.9, 0.5, -0.3, 0., 0., 0., 0., 0., 0.], [0., -0.3, 0.4, -0.3, 0.4, -0.5, -0.6, 0.3, 0.2, 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]), 2025.0, 13), year=None)[source]

Rotation taking ITRS vectors into centered-dipole coordinates.

The CD +z axis points along the dipole axis toward the northern magnetic pole, derived from the degree-1 Gauss coefficients (either given directly or taken from coeffs at year).

Shared core of the MATLAB ITRS2CartCD/CartCD2ITRS pair.

Parameters:

g10 (float, optional) – Degree-1 Gauss coefficients. Either give all three or none.
g11 (float, optional) – Degree-1 Gauss coefficients. Either give all three or none.
h11 (float, optional) – Degree-1 Gauss coefficients. Either give all three or none.
coeffs (MagneticCoefficients, optional) – Model supplying the coefficients when not given directly. Default IGRF14.
year (float, optional) – Decimal year for secular variation. Default: the model epoch.

Returns:

R – (3, 3) rotation matrix; R @ v_itrs is in CD coordinates.

Return type:

ndarray

Notes

coeffs is not checked against any validity window here. Unlike pytcl.magnetism.wmm.wmm(), this function (and the rest of this module) does not warn when year (or coeffs.epoch, used when year is not given) falls outside the coefficient set’s declared validity range – silent extrapolation is possible. A caller who wants that check should call wmm() directly, or compare year against the coefficient set’s own documented window before calling in here.

Examples

>>> R = cd_rotation_matrix()
>>> R.shape
(3, 3)

pytcl.magnetism.coordinates.itrs2cart_cd(z_cart, g10=None, g11=None, h11=None, coeffs=(array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.9350e+04, -1.4103e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.5562e+03, 2.9509e+03, 1.6487e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [1.3609e+03, -2.4042e+03, 1.2438e+03, 4.5340e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [8.9470e+02, 7.9960e+02, 5.5800e+01, -2.8110e+02, 1.2000e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.3290e+02, 3.6900e+02, 1.8720e+02, -1.3870e+02, -1.4190e+02, 2.0900e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [6.4300e+01, 6.3800e+01, 7.6700e+01, -1.1570e+02, -4.0900e+01, 1.4900e+01, -6.0800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [7.9600e+01, -7.6900e+01, -8.8000e+00, 5.9300e+01, 1.5800e+01, 2.5000e+00, -1.1200e+01, 1.4300e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [2.3100e+01, 1.0900e+01, -1.7500e+01, 2.0000e+00, -2.1800e+01, 1.6900e+01, 1.4900e+01, -1.6800e+01, 1.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [4.7000e+00, 8.0000e+00, 3.0000e+00, -2.0000e-01, -2.5000e+00, -1.3100e+01, 2.4000e+00, 8.6000e+00, -8.7000e+00, -1.2800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-1.3000e+00, -6.4000e+00, 2.0000e-01, 2.0000e+00, -1.0000e+00, -5.0000e-01, -9.0000e-01, 1.5000e+00, 9.0000e-01, -2.6000e+00, -3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [3.0000e+00, -1.4000e+00, -2.5000e+00, 2.4000e+00, -6.0000e-01, 0.0000e+00, -6.0000e-01, -1.0000e-01, 1.1000e+00, -1.0000e+00, -1.0000e-01, 2.6000e+00, 0.0000e+00, 0.0000e+00], [-2.0000e+00, -1.0000e-01, 4.0000e-01, 1.2000e+00, -1.2000e+00, 6.0000e-01, 5.0000e-01, 5.0000e-01, -1.0000e-01, -5.0000e-01, -2.0000e-01, -1.2000e+00, -7.0000e-01, 0.0000e+00], [2.0000e-01, -9.0000e-01, 6.0000e-01, 7.0000e-01, -2.0000e-01, 5.0000e-01, 1.0000e-01, 7.0000e-01, 0.0000e+00, 3.0000e-01, 2.0000e-01, 4.0000e-01, -5.0000e-01, -4.0000e-01]]), array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5455e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -3.1336e+03, -8.1420e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -5.6900e+01, 2.3760e+02, -5.4960e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 2.7860e+02, -1.3400e+02, 2.1200e+02, -3.7540e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5300e+01, 2.2000e+02, -1.2290e+02, 4.2900e+01, 1.0620e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.8400e+01, 1.6800e+01, 4.8900e+01, -5.9800e+01, 1.0900e+01, 7.2800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -4.8900e+01, -1.4400e+01, -1.0000e+00, 2.3500e+01, -7.4000e+00, -2.5100e+01, -2.2000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 7.2000e+00, -1.2600e+01, 1.1500e+01, -9.7000e+00, 1.2700e+01, 7.0000e-01, -5.2000e+00, 3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -2.4800e+01, 1.2100e+01, 8.3000e+00, -3.4000e+00, -5.3000e+00, 7.2000e+00, -6.0000e-01, 8.0000e-01, 9.8000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 3.3000e+00, 1.0000e-01, 2.5000e+00, 5.4000e+00, -9.0000e+00, 4.0000e-01, -4.2000e+00, -3.8000e+00, 9.0000e-01, -9.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 0.0000e+00, 2.8000e+00, -6.0000e-01, 1.0000e-01, 5.0000e-01, -3.0000e-01, -1.2000e+00, -1.7000e+00, -2.9000e+00, -1.8000e+00, -2.3000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.2000e+00, 6.0000e-01, 1.0000e+00, -1.5000e+00, 0.0000e+00, 6.0000e-01, -2.0000e-01, 8.0000e-01, 1.0000e-01, -9.0000e-01, 1.0000e-01, 2.0000e-01, 0.0000e+00], [0.0000e+00, -9.0000e-01, 7.0000e-01, 1.2000e+00, -3.0000e-01, -1.3000e+00, -1.0000e-01, 2.0000e-01, -2.0000e-01, 5.0000e-01, 6.0000e-01, -6.0000e-01, -3.0000e-01, -5.0000e-01]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [12.6, 10., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-11.2, -5.3, -8.3, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.5, -4.4, 0.4, -15.6, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.7, -2.3, -5.8, 5.4, -6.8, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0.6, 1.3, 0., 0.7, 2.3, 1., 0., 0., 0., 0., 0., 0., 0., 0.], [-0.2, -0.3, 0.8, 1.2, -0.8, 0.4, 0.9, 0., 0., 0., 0., 0., 0., 0.], [-0.1, -0.1, -0.1, 0.5, -0.1, -0.8, -0.8, 0.9, 0., 0., 0., 0., 0., 0.], [-0.1, 0.2, 0., 0.4, -0.1, 0.3, 0.1, 0., 0.3, 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -21.5, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -27.3, -11.1, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 3.8, -0.2, -3.9, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -1.3, 4.1, 1.6, -4.1, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -0.5, 2.1, 0.5, 1.7, 1.9, 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0.3, -1.6, -0.4, 0.8, 0.7, 0.9, 0., 0., 0., 0., 0., 0., 0.], [0., 0.6, 0.5, -0.7, 0., -0.9, 0.5, -0.3, 0., 0., 0., 0., 0., 0.], [0., -0.3, 0.4, -0.3, 0.4, -0.5, -0.6, 0.3, 0.2, 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]), 2025.0, 13), year=None)[source]

Rotate Cartesian ITRS positions into centered-dipole coordinates.

Port of ITRS2CartCD.

Parameters:

z_cart (array_like) – (3,) or (3, N) ITRS positions.
g10 (float | None) – As in cd_rotation_matrix().
g11 (float | None) – As in cd_rotation_matrix().
h11 (float | None) – As in cd_rotation_matrix().
coeffs (MagneticCoefficients) – As in cd_rotation_matrix().
year (float | None) – As in cd_rotation_matrix().

Returns:

z_cd – The positions in CD coordinates, same shape.

Return type:

ndarray

Notes

coeffs is not checked against any validity window; see cd_rotation_matrix()’s Notes.

Examples

>>> z = itrs2cart_cd([6378137.0, 0.0, 0.0])
>>> z.shape
(3,)

pytcl.magnetism.coordinates.cart_cd2itrs(z_cd, g10=None, g11=None, h11=None, coeffs=(array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.9350e+04, -1.4103e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.5562e+03, 2.9509e+03, 1.6487e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [1.3609e+03, -2.4042e+03, 1.2438e+03, 4.5340e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [8.9470e+02, 7.9960e+02, 5.5800e+01, -2.8110e+02, 1.2000e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.3290e+02, 3.6900e+02, 1.8720e+02, -1.3870e+02, -1.4190e+02, 2.0900e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [6.4300e+01, 6.3800e+01, 7.6700e+01, -1.1570e+02, -4.0900e+01, 1.4900e+01, -6.0800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [7.9600e+01, -7.6900e+01, -8.8000e+00, 5.9300e+01, 1.5800e+01, 2.5000e+00, -1.1200e+01, 1.4300e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [2.3100e+01, 1.0900e+01, -1.7500e+01, 2.0000e+00, -2.1800e+01, 1.6900e+01, 1.4900e+01, -1.6800e+01, 1.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [4.7000e+00, 8.0000e+00, 3.0000e+00, -2.0000e-01, -2.5000e+00, -1.3100e+01, 2.4000e+00, 8.6000e+00, -8.7000e+00, -1.2800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-1.3000e+00, -6.4000e+00, 2.0000e-01, 2.0000e+00, -1.0000e+00, -5.0000e-01, -9.0000e-01, 1.5000e+00, 9.0000e-01, -2.6000e+00, -3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [3.0000e+00, -1.4000e+00, -2.5000e+00, 2.4000e+00, -6.0000e-01, 0.0000e+00, -6.0000e-01, -1.0000e-01, 1.1000e+00, -1.0000e+00, -1.0000e-01, 2.6000e+00, 0.0000e+00, 0.0000e+00], [-2.0000e+00, -1.0000e-01, 4.0000e-01, 1.2000e+00, -1.2000e+00, 6.0000e-01, 5.0000e-01, 5.0000e-01, -1.0000e-01, -5.0000e-01, -2.0000e-01, -1.2000e+00, -7.0000e-01, 0.0000e+00], [2.0000e-01, -9.0000e-01, 6.0000e-01, 7.0000e-01, -2.0000e-01, 5.0000e-01, 1.0000e-01, 7.0000e-01, 0.0000e+00, 3.0000e-01, 2.0000e-01, 4.0000e-01, -5.0000e-01, -4.0000e-01]]), array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5455e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -3.1336e+03, -8.1420e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -5.6900e+01, 2.3760e+02, -5.4960e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 2.7860e+02, -1.3400e+02, 2.1200e+02, -3.7540e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5300e+01, 2.2000e+02, -1.2290e+02, 4.2900e+01, 1.0620e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.8400e+01, 1.6800e+01, 4.8900e+01, -5.9800e+01, 1.0900e+01, 7.2800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -4.8900e+01, -1.4400e+01, -1.0000e+00, 2.3500e+01, -7.4000e+00, -2.5100e+01, -2.2000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 7.2000e+00, -1.2600e+01, 1.1500e+01, -9.7000e+00, 1.2700e+01, 7.0000e-01, -5.2000e+00, 3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -2.4800e+01, 1.2100e+01, 8.3000e+00, -3.4000e+00, -5.3000e+00, 7.2000e+00, -6.0000e-01, 8.0000e-01, 9.8000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 3.3000e+00, 1.0000e-01, 2.5000e+00, 5.4000e+00, -9.0000e+00, 4.0000e-01, -4.2000e+00, -3.8000e+00, 9.0000e-01, -9.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 0.0000e+00, 2.8000e+00, -6.0000e-01, 1.0000e-01, 5.0000e-01, -3.0000e-01, -1.2000e+00, -1.7000e+00, -2.9000e+00, -1.8000e+00, -2.3000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.2000e+00, 6.0000e-01, 1.0000e+00, -1.5000e+00, 0.0000e+00, 6.0000e-01, -2.0000e-01, 8.0000e-01, 1.0000e-01, -9.0000e-01, 1.0000e-01, 2.0000e-01, 0.0000e+00], [0.0000e+00, -9.0000e-01, 7.0000e-01, 1.2000e+00, -3.0000e-01, -1.3000e+00, -1.0000e-01, 2.0000e-01, -2.0000e-01, 5.0000e-01, 6.0000e-01, -6.0000e-01, -3.0000e-01, -5.0000e-01]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [12.6, 10., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-11.2, -5.3, -8.3, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.5, -4.4, 0.4, -15.6, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.7, -2.3, -5.8, 5.4, -6.8, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0.6, 1.3, 0., 0.7, 2.3, 1., 0., 0., 0., 0., 0., 0., 0., 0.], [-0.2, -0.3, 0.8, 1.2, -0.8, 0.4, 0.9, 0., 0., 0., 0., 0., 0., 0.], [-0.1, -0.1, -0.1, 0.5, -0.1, -0.8, -0.8, 0.9, 0., 0., 0., 0., 0., 0.], [-0.1, 0.2, 0., 0.4, -0.1, 0.3, 0.1, 0., 0.3, 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -21.5, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -27.3, -11.1, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 3.8, -0.2, -3.9, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -1.3, 4.1, 1.6, -4.1, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -0.5, 2.1, 0.5, 1.7, 1.9, 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0.3, -1.6, -0.4, 0.8, 0.7, 0.9, 0., 0., 0., 0., 0., 0., 0.], [0., 0.6, 0.5, -0.7, 0., -0.9, 0.5, -0.3, 0., 0., 0., 0., 0., 0.], [0., -0.3, 0.4, -0.3, 0.4, -0.5, -0.6, 0.3, 0.2, 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]), 2025.0, 13), year=None)[source]

Rotate centered-dipole Cartesian positions back into the ITRS.

Port of CartCD2ITRS.

Parameters:

z_cd (array_like) – (3,) or (3, N) CD positions.
g10 (float | None) – As in cd_rotation_matrix().
g11 (float | None) – As in cd_rotation_matrix().
h11 (float | None) – As in cd_rotation_matrix().
coeffs (MagneticCoefficients) – As in cd_rotation_matrix().
year (float | None) – As in cd_rotation_matrix().

Returns:

z_itrs – The positions in the ITRS, same shape.

Return type:

ndarray

Notes

coeffs is not checked against any validity window; see cd_rotation_matrix()’s Notes.

Examples

>>> import numpy as np
>>> z = np.array([6378137.0, 0.0, 0.0])
>>> back = cart_cd2itrs(itrs2cart_cd(z))
>>> bool(np.allclose(back, z))
True

pytcl.magnetism.coordinates.spher_itrs2spher_cd(z_spher, g10=None, g11=None, h11=None, coeffs=(array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.9350e+04, -1.4103e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.5562e+03, 2.9509e+03, 1.6487e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [1.3609e+03, -2.4042e+03, 1.2438e+03, 4.5340e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [8.9470e+02, 7.9960e+02, 5.5800e+01, -2.8110e+02, 1.2000e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.3290e+02, 3.6900e+02, 1.8720e+02, -1.3870e+02, -1.4190e+02, 2.0900e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [6.4300e+01, 6.3800e+01, 7.6700e+01, -1.1570e+02, -4.0900e+01, 1.4900e+01, -6.0800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [7.9600e+01, -7.6900e+01, -8.8000e+00, 5.9300e+01, 1.5800e+01, 2.5000e+00, -1.1200e+01, 1.4300e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [2.3100e+01, 1.0900e+01, -1.7500e+01, 2.0000e+00, -2.1800e+01, 1.6900e+01, 1.4900e+01, -1.6800e+01, 1.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [4.7000e+00, 8.0000e+00, 3.0000e+00, -2.0000e-01, -2.5000e+00, -1.3100e+01, 2.4000e+00, 8.6000e+00, -8.7000e+00, -1.2800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-1.3000e+00, -6.4000e+00, 2.0000e-01, 2.0000e+00, -1.0000e+00, -5.0000e-01, -9.0000e-01, 1.5000e+00, 9.0000e-01, -2.6000e+00, -3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [3.0000e+00, -1.4000e+00, -2.5000e+00, 2.4000e+00, -6.0000e-01, 0.0000e+00, -6.0000e-01, -1.0000e-01, 1.1000e+00, -1.0000e+00, -1.0000e-01, 2.6000e+00, 0.0000e+00, 0.0000e+00], [-2.0000e+00, -1.0000e-01, 4.0000e-01, 1.2000e+00, -1.2000e+00, 6.0000e-01, 5.0000e-01, 5.0000e-01, -1.0000e-01, -5.0000e-01, -2.0000e-01, -1.2000e+00, -7.0000e-01, 0.0000e+00], [2.0000e-01, -9.0000e-01, 6.0000e-01, 7.0000e-01, -2.0000e-01, 5.0000e-01, 1.0000e-01, 7.0000e-01, 0.0000e+00, 3.0000e-01, 2.0000e-01, 4.0000e-01, -5.0000e-01, -4.0000e-01]]), array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5455e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -3.1336e+03, -8.1420e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -5.6900e+01, 2.3760e+02, -5.4960e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 2.7860e+02, -1.3400e+02, 2.1200e+02, -3.7540e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5300e+01, 2.2000e+02, -1.2290e+02, 4.2900e+01, 1.0620e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.8400e+01, 1.6800e+01, 4.8900e+01, -5.9800e+01, 1.0900e+01, 7.2800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -4.8900e+01, -1.4400e+01, -1.0000e+00, 2.3500e+01, -7.4000e+00, -2.5100e+01, -2.2000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 7.2000e+00, -1.2600e+01, 1.1500e+01, -9.7000e+00, 1.2700e+01, 7.0000e-01, -5.2000e+00, 3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -2.4800e+01, 1.2100e+01, 8.3000e+00, -3.4000e+00, -5.3000e+00, 7.2000e+00, -6.0000e-01, 8.0000e-01, 9.8000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 3.3000e+00, 1.0000e-01, 2.5000e+00, 5.4000e+00, -9.0000e+00, 4.0000e-01, -4.2000e+00, -3.8000e+00, 9.0000e-01, -9.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 0.0000e+00, 2.8000e+00, -6.0000e-01, 1.0000e-01, 5.0000e-01, -3.0000e-01, -1.2000e+00, -1.7000e+00, -2.9000e+00, -1.8000e+00, -2.3000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.2000e+00, 6.0000e-01, 1.0000e+00, -1.5000e+00, 0.0000e+00, 6.0000e-01, -2.0000e-01, 8.0000e-01, 1.0000e-01, -9.0000e-01, 1.0000e-01, 2.0000e-01, 0.0000e+00], [0.0000e+00, -9.0000e-01, 7.0000e-01, 1.2000e+00, -3.0000e-01, -1.3000e+00, -1.0000e-01, 2.0000e-01, -2.0000e-01, 5.0000e-01, 6.0000e-01, -6.0000e-01, -3.0000e-01, -5.0000e-01]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [12.6, 10., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-11.2, -5.3, -8.3, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.5, -4.4, 0.4, -15.6, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.7, -2.3, -5.8, 5.4, -6.8, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0.6, 1.3, 0., 0.7, 2.3, 1., 0., 0., 0., 0., 0., 0., 0., 0.], [-0.2, -0.3, 0.8, 1.2, -0.8, 0.4, 0.9, 0., 0., 0., 0., 0., 0., 0.], [-0.1, -0.1, -0.1, 0.5, -0.1, -0.8, -0.8, 0.9, 0., 0., 0., 0., 0., 0.], [-0.1, 0.2, 0., 0.4, -0.1, 0.3, 0.1, 0., 0.3, 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -21.5, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -27.3, -11.1, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 3.8, -0.2, -3.9, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -1.3, 4.1, 1.6, -4.1, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -0.5, 2.1, 0.5, 1.7, 1.9, 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0.3, -1.6, -0.4, 0.8, 0.7, 0.9, 0., 0., 0., 0., 0., 0., 0.], [0., 0.6, 0.5, -0.7, 0., -0.9, 0.5, -0.3, 0., 0., 0., 0., 0., 0.], [0., -0.3, 0.4, -0.3, 0.4, -0.5, -0.6, 0.3, 0.2, 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]), 2025.0, 13), year=None)[source]

Convert spherical ITRS coordinates to spherical CD coordinates.

Port of spherITRS2SpherCD.

Parameters:

z_spher (array_like) – (3,) [r, azimuth, elevation] or (2,) [azimuth, elevation] (angles in radians; unit radius assumed for the 2-element form).
g10 (float | None) – As in cd_rotation_matrix().
g11 (float | None) – As in cd_rotation_matrix().
h11 (float | None) – As in cd_rotation_matrix().
coeffs (MagneticCoefficients) – As in cd_rotation_matrix().
year (float | None) – As in cd_rotation_matrix().

Returns:

z_cd – The spherical CD coordinates, same number of elements.

Return type:

ndarray

Notes

coeffs is not checked against any validity window; see cd_rotation_matrix()’s Notes.

Examples

>>> z = spher_itrs2spher_cd([6.4e6, 0.5, 0.2])
>>> z.shape
(3,)

pytcl.magnetism.coordinates.spher_cd2spher_itrs(z_cd, g10=None, g11=None, h11=None, coeffs=(array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.9350e+04, -1.4103e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.5562e+03, 2.9509e+03, 1.6487e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [1.3609e+03, -2.4042e+03, 1.2438e+03, 4.5340e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [8.9470e+02, 7.9960e+02, 5.5800e+01, -2.8110e+02, 1.2000e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.3290e+02, 3.6900e+02, 1.8720e+02, -1.3870e+02, -1.4190e+02, 2.0900e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [6.4300e+01, 6.3800e+01, 7.6700e+01, -1.1570e+02, -4.0900e+01, 1.4900e+01, -6.0800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [7.9600e+01, -7.6900e+01, -8.8000e+00, 5.9300e+01, 1.5800e+01, 2.5000e+00, -1.1200e+01, 1.4300e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [2.3100e+01, 1.0900e+01, -1.7500e+01, 2.0000e+00, -2.1800e+01, 1.6900e+01, 1.4900e+01, -1.6800e+01, 1.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [4.7000e+00, 8.0000e+00, 3.0000e+00, -2.0000e-01, -2.5000e+00, -1.3100e+01, 2.4000e+00, 8.6000e+00, -8.7000e+00, -1.2800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-1.3000e+00, -6.4000e+00, 2.0000e-01, 2.0000e+00, -1.0000e+00, -5.0000e-01, -9.0000e-01, 1.5000e+00, 9.0000e-01, -2.6000e+00, -3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [3.0000e+00, -1.4000e+00, -2.5000e+00, 2.4000e+00, -6.0000e-01, 0.0000e+00, -6.0000e-01, -1.0000e-01, 1.1000e+00, -1.0000e+00, -1.0000e-01, 2.6000e+00, 0.0000e+00, 0.0000e+00], [-2.0000e+00, -1.0000e-01, 4.0000e-01, 1.2000e+00, -1.2000e+00, 6.0000e-01, 5.0000e-01, 5.0000e-01, -1.0000e-01, -5.0000e-01, -2.0000e-01, -1.2000e+00, -7.0000e-01, 0.0000e+00], [2.0000e-01, -9.0000e-01, 6.0000e-01, 7.0000e-01, -2.0000e-01, 5.0000e-01, 1.0000e-01, 7.0000e-01, 0.0000e+00, 3.0000e-01, 2.0000e-01, 4.0000e-01, -5.0000e-01, -4.0000e-01]]), array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5455e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -3.1336e+03, -8.1420e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -5.6900e+01, 2.3760e+02, -5.4960e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 2.7860e+02, -1.3400e+02, 2.1200e+02, -3.7540e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5300e+01, 2.2000e+02, -1.2290e+02, 4.2900e+01, 1.0620e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.8400e+01, 1.6800e+01, 4.8900e+01, -5.9800e+01, 1.0900e+01, 7.2800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -4.8900e+01, -1.4400e+01, -1.0000e+00, 2.3500e+01, -7.4000e+00, -2.5100e+01, -2.2000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 7.2000e+00, -1.2600e+01, 1.1500e+01, -9.7000e+00, 1.2700e+01, 7.0000e-01, -5.2000e+00, 3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -2.4800e+01, 1.2100e+01, 8.3000e+00, -3.4000e+00, -5.3000e+00, 7.2000e+00, -6.0000e-01, 8.0000e-01, 9.8000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 3.3000e+00, 1.0000e-01, 2.5000e+00, 5.4000e+00, -9.0000e+00, 4.0000e-01, -4.2000e+00, -3.8000e+00, 9.0000e-01, -9.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 0.0000e+00, 2.8000e+00, -6.0000e-01, 1.0000e-01, 5.0000e-01, -3.0000e-01, -1.2000e+00, -1.7000e+00, -2.9000e+00, -1.8000e+00, -2.3000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.2000e+00, 6.0000e-01, 1.0000e+00, -1.5000e+00, 0.0000e+00, 6.0000e-01, -2.0000e-01, 8.0000e-01, 1.0000e-01, -9.0000e-01, 1.0000e-01, 2.0000e-01, 0.0000e+00], [0.0000e+00, -9.0000e-01, 7.0000e-01, 1.2000e+00, -3.0000e-01, -1.3000e+00, -1.0000e-01, 2.0000e-01, -2.0000e-01, 5.0000e-01, 6.0000e-01, -6.0000e-01, -3.0000e-01, -5.0000e-01]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [12.6, 10., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-11.2, -5.3, -8.3, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.5, -4.4, 0.4, -15.6, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.7, -2.3, -5.8, 5.4, -6.8, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0.6, 1.3, 0., 0.7, 2.3, 1., 0., 0., 0., 0., 0., 0., 0., 0.], [-0.2, -0.3, 0.8, 1.2, -0.8, 0.4, 0.9, 0., 0., 0., 0., 0., 0., 0.], [-0.1, -0.1, -0.1, 0.5, -0.1, -0.8, -0.8, 0.9, 0., 0., 0., 0., 0., 0.], [-0.1, 0.2, 0., 0.4, -0.1, 0.3, 0.1, 0., 0.3, 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -21.5, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -27.3, -11.1, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 3.8, -0.2, -3.9, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -1.3, 4.1, 1.6, -4.1, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -0.5, 2.1, 0.5, 1.7, 1.9, 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0.3, -1.6, -0.4, 0.8, 0.7, 0.9, 0., 0., 0., 0., 0., 0., 0.], [0., 0.6, 0.5, -0.7, 0., -0.9, 0.5, -0.3, 0., 0., 0., 0., 0., 0.], [0., -0.3, 0.4, -0.3, 0.4, -0.5, -0.6, 0.3, 0.2, 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]), 2025.0, 13), year=None)[source]

Convert spherical CD coordinates back to spherical ITRS.

Port of spherCD2SpherITRS.

Parameters:

z_cd (array_like) – (3,) [r, azimuth, elevation] or (2,) [azimuth, elevation].
g10 (float | None) – As in cd_rotation_matrix().
g11 (float | None) – As in cd_rotation_matrix().
h11 (float | None) – As in cd_rotation_matrix().
coeffs (MagneticCoefficients) – As in cd_rotation_matrix().
year (float | None) – As in cd_rotation_matrix().

Returns:

z_spher – The spherical ITRS coordinates, same number of elements.

Return type:

ndarray

Notes

coeffs is not checked against any validity window; see cd_rotation_matrix()’s Notes.

Examples

>>> import numpy as np
>>> z = np.array([6.4e6, 0.5, 0.2])
>>> back = spher_cd2spher_itrs(spher_itrs2spher_cd(z))
>>> bool(np.allclose(back, z))
True

pytcl.magnetism.coordinates.geog_heading2mag(point_lla, heading, coeffs=(array([[0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-2.93518e+04, -1.41080e+03, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-2.55660e+03, 2.95110e+03, 1.64930e+03, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [1.36100e+03, -2.40410e+03, 1.24380e+03, 4.53600e+02, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [8.95000e+02, 7.99500e+02, 5.57000e+01, -2.81100e+02, 1.21000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-2.33200e+02, 3.68900e+02, 1.87200e+02, -1.38700e+02, -1.42000e+02, 2.09000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [6.44000e+01, 6.38000e+01, 7.69000e+01, -1.15700e+02, -4.09000e+01, 1.49000e+01, -6.07000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [7.95000e+01, -7.70000e+01, -8.80000e+00, 5.93000e+01, 1.58000e+01, 2.50000e+00, -1.11000e+01, 1.42000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [2.32000e+01, 1.08000e+01, -1.75000e+01, 2.00000e+00, -2.17000e+01, 1.69000e+01, 1.50000e+01, -1.68000e+01, 9.00000e-01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [4.60000e+00, 7.80000e+00, 3.00000e+00, -2.00000e-01, -2.50000e+00, -1.31000e+01, 2.40000e+00, 8.60000e+00, -8.70000e+00, -1.29000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-1.30000e+00, -6.40000e+00, 2.00000e-01, 2.00000e+00, -1.00000e+00, -6.00000e-01, -9.00000e-01, 1.50000e+00, 9.00000e-01, -2.70000e+00, -3.90000e+00, 0.00000e+00, 0.00000e+00], [2.90000e+00, -1.50000e+00, -2.50000e+00, 2.40000e+00, -6.00000e-01, -1.00000e-01, -6.00000e-01, -1.00000e-01, 1.10000e+00, -1.00000e+00, -2.00000e-01, 2.60000e+00, 0.00000e+00], [-2.00000e+00, -2.00000e-01, 3.00000e-01, 1.20000e+00, -1.30000e+00, 6.00000e-01, 6.00000e-01, 5.00000e-01, -1.00000e-01, -4.00000e-01, -2.00000e-01, -1.30000e+00, -7.00000e-01]]), array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5454e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -3.1336e+03, -8.1510e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -5.6600e+01, 2.3750e+02, -5.4950e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 2.7860e+02, -1.3390e+02, 2.1200e+02, -3.7560e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5400e+01, 2.2020e+02, -1.2290e+02, 4.3000e+01, 1.0610e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.8400e+01, 1.6800e+01, 4.8800e+01, -5.9800e+01, 1.0900e+01, 7.2700e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -4.8900e+01, -1.4400e+01, -1.0000e+00, 2.3400e+01, -7.4000e+00, -2.5100e+01, -2.3000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 7.1000e+00, -1.2600e+01, 1.1400e+01, -9.7000e+00, 1.2700e+01, 7.0000e-01, -5.2000e+00, 3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -2.4800e+01, 1.2200e+01, 8.3000e+00, -3.3000e+00, -5.2000e+00, 7.2000e+00, -6.0000e-01, 8.0000e-01, 1.0000e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 3.3000e+00, 0.0000e+00, 2.4000e+00, 5.3000e+00, -9.1000e+00, 4.0000e-01, -4.2000e+00, -3.8000e+00, 9.0000e-01, -9.1000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 0.0000e+00, 2.9000e+00, -6.0000e-01, 2.0000e-01, 5.0000e-01, -3.0000e-01, -1.2000e+00, -1.7000e+00, -2.9000e+00, -1.8000e+00, -2.3000e+00, 0.0000e+00], [0.0000e+00, -1.3000e+00, 7.0000e-01, 1.0000e+00, -1.4000e+00, -0.0000e+00, 6.0000e-01, -1.0000e-01, 8.0000e-01, 1.0000e-01, -1.0000e+00, 1.0000e-01, 2.0000e-01]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [12., 9.7, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-11.6, -5.2, -8., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.3, -4.2, 0.4, -15.6, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.6, -2.4, -6., 5.6, -7., 0., 0., 0., 0., 0., 0., 0., 0.], [0.6, 1.4, 0., 0.6, 2.2, 0.9, 0., 0., 0., 0., 0., 0., 0.], [-0.2, -0.4, 0.9, 1.2, -0.9, 0.3, 0.9, 0., 0., 0., 0., 0., 0.], [-0., -0.1, -0.1, 0.5, -0.1, -0.8, -0.8, 0.8, 0., 0., 0., 0., 0.], [-0.1, 0.2, 0., 0.5, -0.1, 0.3, 0.2, -0., 0.2, 0., 0., 0., 0.], [-0., -0.1, 0.1, 0.3, -0.3, 0., 0.3, -0.1, 0.1, -0.1, 0., 0., 0.], [0.1, 0., 0.1, 0.1, -0., -0.3, 0., -0.1, -0.1, -0., -0., 0., 0.], [0., -0., 0., 0., 0., -0.1, 0., -0., -0.1, -0.1, -0.1, -0.1, 0.], [0., 0., -0., -0., -0., -0., 0.1, -0., 0., 0., -0.1, -0., -0.1]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -21.5, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -27.7, -12.1, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 4., -0.3, -4.1, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -1.1, 4.1, 1.6, -4.4, 0., 0., 0., 0., 0., 0., 0., 0.], [0., -0.5, 2.2, 0.4, 1.7, 1.9, 0., 0., 0., 0., 0., 0., 0.], [0., 0.3, -1.6, -0.4, 0.9, 0.7, 0.9, 0., 0., 0., 0., 0., 0.], [0., 0.6, 0.5, -0.8, 0., -1., 0.6, -0.2, 0., 0., 0., 0., 0.], [0., -0.2, 0.5, -0.4, 0.4, -0.5, -0.6, 0.3, 0.2, 0., 0., 0., 0.], [0., -0.3, 0.3, -0.3, 0.3, 0.2, -0.1, -0.2, 0.4, 0.1, 0., 0., 0.], [0., 0., -0., -0.2, 0.1, -0.1, 0.1, 0., -0.1, 0.2, -0., 0., 0.], [0., -0., 0.1, -0., 0.1, -0., -0., 0.1, -0., 0., 0., 0., 0.], [0., -0., 0., -0.1, 0.1, -0., -0., -0., 0., -0., -0., 0., -0.1]]), 2025.0, 12), year=None)[source]

Convert a geographic heading to a magnetic heading.

The magnetic heading is the geographic heading minus the local magnetic declination (the direction of the horizontal magnetic flux, east of geographic north).

Port of geogHeading2Mag, evaluated through pytcl’s validated field models.

Parameters:

point_lla (array_like) – (3,) geodetic [latitude, longitude, height] in radians and meters (WGS-84).
heading (float) – Geographic heading in radians east of north.
coeffs (MagneticCoefficients, optional) – Field model. Default WMM2025 (the MATLAB default is the WMM).
year (float, optional) – Decimal year. Default: the model epoch.

Returns:

heading_mag – Heading in radians east of magnetic north.

Return type:

float

Notes

coeffs is not checked against any validity window; see cd_rotation_matrix()’s Notes. This applies regardless of which coefficient set is passed – WMM2025, IGRF14, or anything else.

Examples

>>> h = geog_heading2mag([0.7, -1.2, 0.0], 0.5)
>>> isinstance(h, float)
True

pytcl.magnetism.coordinates.mag_heading2geog(point_lla, heading_mag, coeffs=(array([[0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-2.93518e+04, -1.41080e+03, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-2.55660e+03, 2.95110e+03, 1.64930e+03, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [1.36100e+03, -2.40410e+03, 1.24380e+03, 4.53600e+02, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [8.95000e+02, 7.99500e+02, 5.57000e+01, -2.81100e+02, 1.21000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-2.33200e+02, 3.68900e+02, 1.87200e+02, -1.38700e+02, -1.42000e+02, 2.09000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [6.44000e+01, 6.38000e+01, 7.69000e+01, -1.15700e+02, -4.09000e+01, 1.49000e+01, -6.07000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [7.95000e+01, -7.70000e+01, -8.80000e+00, 5.93000e+01, 1.58000e+01, 2.50000e+00, -1.11000e+01, 1.42000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [2.32000e+01, 1.08000e+01, -1.75000e+01, 2.00000e+00, -2.17000e+01, 1.69000e+01, 1.50000e+01, -1.68000e+01, 9.00000e-01, 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00], [4.60000e+00, 7.80000e+00, 3.00000e+00, -2.00000e-01, -2.50000e+00, -1.31000e+01, 2.40000e+00, 8.60000e+00, -8.70000e+00, -1.29000e+01, 0.00000e+00, 0.00000e+00, 0.00000e+00], [-1.30000e+00, -6.40000e+00, 2.00000e-01, 2.00000e+00, -1.00000e+00, -6.00000e-01, -9.00000e-01, 1.50000e+00, 9.00000e-01, -2.70000e+00, -3.90000e+00, 0.00000e+00, 0.00000e+00], [2.90000e+00, -1.50000e+00, -2.50000e+00, 2.40000e+00, -6.00000e-01, -1.00000e-01, -6.00000e-01, -1.00000e-01, 1.10000e+00, -1.00000e+00, -2.00000e-01, 2.60000e+00, 0.00000e+00], [-2.00000e+00, -2.00000e-01, 3.00000e-01, 1.20000e+00, -1.30000e+00, 6.00000e-01, 6.00000e-01, 5.00000e-01, -1.00000e-01, -4.00000e-01, -2.00000e-01, -1.30000e+00, -7.00000e-01]]), array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5454e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -3.1336e+03, -8.1510e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -5.6600e+01, 2.3750e+02, -5.4950e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 2.7860e+02, -1.3390e+02, 2.1200e+02, -3.7560e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5400e+01, 2.2020e+02, -1.2290e+02, 4.3000e+01, 1.0610e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.8400e+01, 1.6800e+01, 4.8800e+01, -5.9800e+01, 1.0900e+01, 7.2700e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -4.8900e+01, -1.4400e+01, -1.0000e+00, 2.3400e+01, -7.4000e+00, -2.5100e+01, -2.3000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 7.1000e+00, -1.2600e+01, 1.1400e+01, -9.7000e+00, 1.2700e+01, 7.0000e-01, -5.2000e+00, 3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -2.4800e+01, 1.2200e+01, 8.3000e+00, -3.3000e+00, -5.2000e+00, 7.2000e+00, -6.0000e-01, 8.0000e-01, 1.0000e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 3.3000e+00, 0.0000e+00, 2.4000e+00, 5.3000e+00, -9.1000e+00, 4.0000e-01, -4.2000e+00, -3.8000e+00, 9.0000e-01, -9.1000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 0.0000e+00, 2.9000e+00, -6.0000e-01, 2.0000e-01, 5.0000e-01, -3.0000e-01, -1.2000e+00, -1.7000e+00, -2.9000e+00, -1.8000e+00, -2.3000e+00, 0.0000e+00], [0.0000e+00, -1.3000e+00, 7.0000e-01, 1.0000e+00, -1.4000e+00, -0.0000e+00, 6.0000e-01, -1.0000e-01, 8.0000e-01, 1.0000e-01, -1.0000e+00, 1.0000e-01, 2.0000e-01]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [12., 9.7, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-11.6, -5.2, -8., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.3, -4.2, 0.4, -15.6, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.6, -2.4, -6., 5.6, -7., 0., 0., 0., 0., 0., 0., 0., 0.], [0.6, 1.4, 0., 0.6, 2.2, 0.9, 0., 0., 0., 0., 0., 0., 0.], [-0.2, -0.4, 0.9, 1.2, -0.9, 0.3, 0.9, 0., 0., 0., 0., 0., 0.], [-0., -0.1, -0.1, 0.5, -0.1, -0.8, -0.8, 0.8, 0., 0., 0., 0., 0.], [-0.1, 0.2, 0., 0.5, -0.1, 0.3, 0.2, -0., 0.2, 0., 0., 0., 0.], [-0., -0.1, 0.1, 0.3, -0.3, 0., 0.3, -0.1, 0.1, -0.1, 0., 0., 0.], [0.1, 0., 0.1, 0.1, -0., -0.3, 0., -0.1, -0.1, -0., -0., 0., 0.], [0., -0., 0., 0., 0., -0.1, 0., -0., -0.1, -0.1, -0.1, -0.1, 0.], [0., 0., -0., -0., -0., -0., 0.1, -0., 0., 0., -0.1, -0., -0.1]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -21.5, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -27.7, -12.1, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 4., -0.3, -4.1, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -1.1, 4.1, 1.6, -4.4, 0., 0., 0., 0., 0., 0., 0., 0.], [0., -0.5, 2.2, 0.4, 1.7, 1.9, 0., 0., 0., 0., 0., 0., 0.], [0., 0.3, -1.6, -0.4, 0.9, 0.7, 0.9, 0., 0., 0., 0., 0., 0.], [0., 0.6, 0.5, -0.8, 0., -1., 0.6, -0.2, 0., 0., 0., 0., 0.], [0., -0.2, 0.5, -0.4, 0.4, -0.5, -0.6, 0.3, 0.2, 0., 0., 0., 0.], [0., -0.3, 0.3, -0.3, 0.3, 0.2, -0.1, -0.2, 0.4, 0.1, 0., 0., 0.], [0., 0., -0., -0.2, 0.1, -0.1, 0.1, 0., -0.1, 0.2, -0., 0., 0.], [0., -0., 0.1, -0., 0.1, -0., -0., 0.1, -0., 0., 0., 0., 0.], [0., -0., 0., -0.1, 0.1, -0., -0., -0., 0., -0., -0., 0., -0.1]]), 2025.0, 12), year=None)[source]

Convert a magnetic heading to a geographic heading.

Port of magHeading2Geog.

Parameters:

point_lla (array_like) – (3,) geodetic [latitude, longitude, height] in radians and meters (WGS-84).
heading_mag (float) – Heading in radians east of magnetic north.
coeffs (MagneticCoefficients) – As in geog_heading2mag().
year (float | None) – As in geog_heading2mag().

Returns:

heading_geo – Heading in radians east of geographic north.

Return type:

float

Notes

coeffs is not checked against any validity window; see cd_rotation_matrix()’s Notes.

Examples

>>> p = [0.7, -1.2, 0.0]
>>> round(mag_heading2geog(p, geog_heading2mag(p, 0.5)), 12)
0.5

pytcl.magnetism.coordinates.trace2earth_mag_apex(z_cart, coeffs=(array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.9350e+04, -1.4103e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.5562e+03, 2.9509e+03, 1.6487e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [1.3609e+03, -2.4042e+03, 1.2438e+03, 4.5340e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [8.9470e+02, 7.9960e+02, 5.5800e+01, -2.8110e+02, 1.2000e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.3290e+02, 3.6900e+02, 1.8720e+02, -1.3870e+02, -1.4190e+02, 2.0900e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [6.4300e+01, 6.3800e+01, 7.6700e+01, -1.1570e+02, -4.0900e+01, 1.4900e+01, -6.0800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [7.9600e+01, -7.6900e+01, -8.8000e+00, 5.9300e+01, 1.5800e+01, 2.5000e+00, -1.1200e+01, 1.4300e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [2.3100e+01, 1.0900e+01, -1.7500e+01, 2.0000e+00, -2.1800e+01, 1.6900e+01, 1.4900e+01, -1.6800e+01, 1.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [4.7000e+00, 8.0000e+00, 3.0000e+00, -2.0000e-01, -2.5000e+00, -1.3100e+01, 2.4000e+00, 8.6000e+00, -8.7000e+00, -1.2800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-1.3000e+00, -6.4000e+00, 2.0000e-01, 2.0000e+00, -1.0000e+00, -5.0000e-01, -9.0000e-01, 1.5000e+00, 9.0000e-01, -2.6000e+00, -3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [3.0000e+00, -1.4000e+00, -2.5000e+00, 2.4000e+00, -6.0000e-01, 0.0000e+00, -6.0000e-01, -1.0000e-01, 1.1000e+00, -1.0000e+00, -1.0000e-01, 2.6000e+00, 0.0000e+00, 0.0000e+00], [-2.0000e+00, -1.0000e-01, 4.0000e-01, 1.2000e+00, -1.2000e+00, 6.0000e-01, 5.0000e-01, 5.0000e-01, -1.0000e-01, -5.0000e-01, -2.0000e-01, -1.2000e+00, -7.0000e-01, 0.0000e+00], [2.0000e-01, -9.0000e-01, 6.0000e-01, 7.0000e-01, -2.0000e-01, 5.0000e-01, 1.0000e-01, 7.0000e-01, 0.0000e+00, 3.0000e-01, 2.0000e-01, 4.0000e-01, -5.0000e-01, -4.0000e-01]]), array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5455e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -3.1336e+03, -8.1420e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -5.6900e+01, 2.3760e+02, -5.4960e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 2.7860e+02, -1.3400e+02, 2.1200e+02, -3.7540e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5300e+01, 2.2000e+02, -1.2290e+02, 4.2900e+01, 1.0620e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.8400e+01, 1.6800e+01, 4.8900e+01, -5.9800e+01, 1.0900e+01, 7.2800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -4.8900e+01, -1.4400e+01, -1.0000e+00, 2.3500e+01, -7.4000e+00, -2.5100e+01, -2.2000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 7.2000e+00, -1.2600e+01, 1.1500e+01, -9.7000e+00, 1.2700e+01, 7.0000e-01, -5.2000e+00, 3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -2.4800e+01, 1.2100e+01, 8.3000e+00, -3.4000e+00, -5.3000e+00, 7.2000e+00, -6.0000e-01, 8.0000e-01, 9.8000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 3.3000e+00, 1.0000e-01, 2.5000e+00, 5.4000e+00, -9.0000e+00, 4.0000e-01, -4.2000e+00, -3.8000e+00, 9.0000e-01, -9.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 0.0000e+00, 2.8000e+00, -6.0000e-01, 1.0000e-01, 5.0000e-01, -3.0000e-01, -1.2000e+00, -1.7000e+00, -2.9000e+00, -1.8000e+00, -2.3000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.2000e+00, 6.0000e-01, 1.0000e+00, -1.5000e+00, 0.0000e+00, 6.0000e-01, -2.0000e-01, 8.0000e-01, 1.0000e-01, -9.0000e-01, 1.0000e-01, 2.0000e-01, 0.0000e+00], [0.0000e+00, -9.0000e-01, 7.0000e-01, 1.2000e+00, -3.0000e-01, -1.3000e+00, -1.0000e-01, 2.0000e-01, -2.0000e-01, 5.0000e-01, 6.0000e-01, -6.0000e-01, -3.0000e-01, -5.0000e-01]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [12.6, 10., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-11.2, -5.3, -8.3, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.5, -4.4, 0.4, -15.6, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.7, -2.3, -5.8, 5.4, -6.8, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0.6, 1.3, 0., 0.7, 2.3, 1., 0., 0., 0., 0., 0., 0., 0., 0.], [-0.2, -0.3, 0.8, 1.2, -0.8, 0.4, 0.9, 0., 0., 0., 0., 0., 0., 0.], [-0.1, -0.1, -0.1, 0.5, -0.1, -0.8, -0.8, 0.9, 0., 0., 0., 0., 0., 0.], [-0.1, 0.2, 0., 0.4, -0.1, 0.3, 0.1, 0., 0.3, 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -21.5, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -27.3, -11.1, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 3.8, -0.2, -3.9, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -1.3, 4.1, 1.6, -4.1, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -0.5, 2.1, 0.5, 1.7, 1.9, 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0.3, -1.6, -0.4, 0.8, 0.7, 0.9, 0., 0., 0., 0., 0., 0., 0.], [0., 0.6, 0.5, -0.7, 0., -0.9, 0.5, -0.3, 0., 0., 0., 0., 0., 0.], [0., -0.3, 0.4, -0.3, 0.4, -0.5, -0.6, 0.3, 0.2, 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]), 2025.0, 13), year=None, rel_tol=1e-06, abs_tol=1e-09)[source]

Trace the magnetic field line through a point to its apex.

Integration follows the normalized flux direction toward increasing ellipsoidal height until the height peaks; the apex is located by root-finding on the level condition. A field line that climbs beyond 1e37 m (near the magnetic poles) is declared to reach infinity, as in the reference.

Port of trace2EarthMagApex (SciPy RK45 with event root-finding in place of the hand-rolled adaptive step).

Parameters:

z_cart (array_like) – (3,) ITRS position in meters.
coeffs (MagneticCoefficients, optional) – Field model. Default IGRF14.
year (float, optional) – Decimal year. Default: the model epoch.
rel_tol (float, optional) – Integration tolerances. Defaults 1e-6 and 1e-9, the MATLAB defaults.
abs_tol (float, optional) – Integration tolerances. Defaults 1e-6 and 1e-9, the MATLAB defaults.

Returns:

apex_point (ndarray) – (3,) ITRS position of the apex in meters (infinite entries for a polar-escaping line).
sign_val (float) – +1 when the field at the start points toward increasing height (magnetically southern side), -1 otherwise.

Return type:

tuple[ndarray[tuple[Any, …], dtype[float64]], float]

Notes

coeffs is not checked against any validity window; see cd_rotation_matrix()’s Notes.

Examples

>>> apex, sign = trace2earth_mag_apex([6.4e6, 1e5, 2e6])
>>> apex.shape
(3,)

pytcl.magnetism.coordinates.itrs2magnetic_apex(z_cart, h_r=0.0, coeffs=(array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.9350e+04, -1.4103e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.5562e+03, 2.9509e+03, 1.6487e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [1.3609e+03, -2.4042e+03, 1.2438e+03, 4.5340e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [8.9470e+02, 7.9960e+02, 5.5800e+01, -2.8110e+02, 1.2000e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.3290e+02, 3.6900e+02, 1.8720e+02, -1.3870e+02, -1.4190e+02, 2.0900e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [6.4300e+01, 6.3800e+01, 7.6700e+01, -1.1570e+02, -4.0900e+01, 1.4900e+01, -6.0800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [7.9600e+01, -7.6900e+01, -8.8000e+00, 5.9300e+01, 1.5800e+01, 2.5000e+00, -1.1200e+01, 1.4300e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [2.3100e+01, 1.0900e+01, -1.7500e+01, 2.0000e+00, -2.1800e+01, 1.6900e+01, 1.4900e+01, -1.6800e+01, 1.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [4.7000e+00, 8.0000e+00, 3.0000e+00, -2.0000e-01, -2.5000e+00, -1.3100e+01, 2.4000e+00, 8.6000e+00, -8.7000e+00, -1.2800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-1.3000e+00, -6.4000e+00, 2.0000e-01, 2.0000e+00, -1.0000e+00, -5.0000e-01, -9.0000e-01, 1.5000e+00, 9.0000e-01, -2.6000e+00, -3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [3.0000e+00, -1.4000e+00, -2.5000e+00, 2.4000e+00, -6.0000e-01, 0.0000e+00, -6.0000e-01, -1.0000e-01, 1.1000e+00, -1.0000e+00, -1.0000e-01, 2.6000e+00, 0.0000e+00, 0.0000e+00], [-2.0000e+00, -1.0000e-01, 4.0000e-01, 1.2000e+00, -1.2000e+00, 6.0000e-01, 5.0000e-01, 5.0000e-01, -1.0000e-01, -5.0000e-01, -2.0000e-01, -1.2000e+00, -7.0000e-01, 0.0000e+00], [2.0000e-01, -9.0000e-01, 6.0000e-01, 7.0000e-01, -2.0000e-01, 5.0000e-01, 1.0000e-01, 7.0000e-01, 0.0000e+00, 3.0000e-01, 2.0000e-01, 4.0000e-01, -5.0000e-01, -4.0000e-01]]), array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5455e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -3.1336e+03, -8.1420e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -5.6900e+01, 2.3760e+02, -5.4960e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 2.7860e+02, -1.3400e+02, 2.1200e+02, -3.7540e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5300e+01, 2.2000e+02, -1.2290e+02, 4.2900e+01, 1.0620e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.8400e+01, 1.6800e+01, 4.8900e+01, -5.9800e+01, 1.0900e+01, 7.2800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -4.8900e+01, -1.4400e+01, -1.0000e+00, 2.3500e+01, -7.4000e+00, -2.5100e+01, -2.2000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 7.2000e+00, -1.2600e+01, 1.1500e+01, -9.7000e+00, 1.2700e+01, 7.0000e-01, -5.2000e+00, 3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -2.4800e+01, 1.2100e+01, 8.3000e+00, -3.4000e+00, -5.3000e+00, 7.2000e+00, -6.0000e-01, 8.0000e-01, 9.8000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 3.3000e+00, 1.0000e-01, 2.5000e+00, 5.4000e+00, -9.0000e+00, 4.0000e-01, -4.2000e+00, -3.8000e+00, 9.0000e-01, -9.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 0.0000e+00, 2.8000e+00, -6.0000e-01, 1.0000e-01, 5.0000e-01, -3.0000e-01, -1.2000e+00, -1.7000e+00, -2.9000e+00, -1.8000e+00, -2.3000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.2000e+00, 6.0000e-01, 1.0000e+00, -1.5000e+00, 0.0000e+00, 6.0000e-01, -2.0000e-01, 8.0000e-01, 1.0000e-01, -9.0000e-01, 1.0000e-01, 2.0000e-01, 0.0000e+00], [0.0000e+00, -9.0000e-01, 7.0000e-01, 1.2000e+00, -3.0000e-01, -1.3000e+00, -1.0000e-01, 2.0000e-01, -2.0000e-01, 5.0000e-01, 6.0000e-01, -6.0000e-01, -3.0000e-01, -5.0000e-01]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [12.6, 10., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-11.2, -5.3, -8.3, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.5, -4.4, 0.4, -15.6, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.7, -2.3, -5.8, 5.4, -6.8, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0.6, 1.3, 0., 0.7, 2.3, 1., 0., 0., 0., 0., 0., 0., 0., 0.], [-0.2, -0.3, 0.8, 1.2, -0.8, 0.4, 0.9, 0., 0., 0., 0., 0., 0., 0.], [-0.1, -0.1, -0.1, 0.5, -0.1, -0.8, -0.8, 0.9, 0., 0., 0., 0., 0., 0.], [-0.1, 0.2, 0., 0.4, -0.1, 0.3, 0.1, 0., 0.3, 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -21.5, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -27.3, -11.1, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 3.8, -0.2, -3.9, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -1.3, 4.1, 1.6, -4.1, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -0.5, 2.1, 0.5, 1.7, 1.9, 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0.3, -1.6, -0.4, 0.8, 0.7, 0.9, 0., 0., 0., 0., 0., 0., 0.], [0., 0.6, 0.5, -0.7, 0., -0.9, 0.5, -0.3, 0., 0., 0., 0., 0., 0.], [0., -0.3, 0.4, -0.3, 0.4, -0.5, -0.6, 0.3, 0.2, 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]), 2025.0, 13), year=None, rel_tol=1e-06, abs_tol=1e-09)[source]

Convert an ITRS position to (modified) magnetic apex coordinates.

The apex latitude follows Richmond’s definition from the apex height of the field line through the point; the longitude is the centered-dipole longitude of the apex; the third coordinate is the signed magnetic scalar potential at the point.

Port of ITRS2MagneticApex.

Parameters:

z_cart (array_like) – (3,) ITRS position in meters.
h_r (float, optional) – Reference height in meters for modified apex coordinates. Default 0 (standard apex coordinates).
coeffs (MagneticCoefficients) – As in trace2earth_mag_apex().
year (float | None) – As in trace2earth_mag_apex().
rel_tol (float) – As in trace2earth_mag_apex().
abs_tol (float) – As in trace2earth_mag_apex().

Returns:

z_apex (ndarray) – (3,) [apex latitude (rad), apex longitude (rad), potential (T m)]. The latitude is NaN when the field line’s apex sits below h_r (the modified-apex definition leaves it undefined there); the longitude is NaN for a polar-escaping line.
apex_point (ndarray) – (3,) the traced apex position in the ITRS (meters).

Return type:

tuple[ndarray[tuple[Any, …], dtype[float64]], ndarray[tuple[Any, …], dtype[float64]]]

Notes

coeffs is not checked against any validity window; see cd_rotation_matrix()’s Notes.

Examples

>>> z, apex = itrs2magnetic_apex([6.4e6, 1e5, 2e6])
>>> z.shape
(3,)

pytcl.magnetism.coordinates.itrs2qd(z_cart, coeffs=(array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.9350e+04, -1.4103e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.5562e+03, 2.9509e+03, 1.6487e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [1.3609e+03, -2.4042e+03, 1.2438e+03, 4.5340e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [8.9470e+02, 7.9960e+02, 5.5800e+01, -2.8110e+02, 1.2000e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-2.3290e+02, 3.6900e+02, 1.8720e+02, -1.3870e+02, -1.4190e+02, 2.0900e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [6.4300e+01, 6.3800e+01, 7.6700e+01, -1.1570e+02, -4.0900e+01, 1.4900e+01, -6.0800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [7.9600e+01, -7.6900e+01, -8.8000e+00, 5.9300e+01, 1.5800e+01, 2.5000e+00, -1.1200e+01, 1.4300e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [2.3100e+01, 1.0900e+01, -1.7500e+01, 2.0000e+00, -2.1800e+01, 1.6900e+01, 1.4900e+01, -1.6800e+01, 1.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [4.7000e+00, 8.0000e+00, 3.0000e+00, -2.0000e-01, -2.5000e+00, -1.3100e+01, 2.4000e+00, 8.6000e+00, -8.7000e+00, -1.2800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [-1.3000e+00, -6.4000e+00, 2.0000e-01, 2.0000e+00, -1.0000e+00, -5.0000e-01, -9.0000e-01, 1.5000e+00, 9.0000e-01, -2.6000e+00, -3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [3.0000e+00, -1.4000e+00, -2.5000e+00, 2.4000e+00, -6.0000e-01, 0.0000e+00, -6.0000e-01, -1.0000e-01, 1.1000e+00, -1.0000e+00, -1.0000e-01, 2.6000e+00, 0.0000e+00, 0.0000e+00], [-2.0000e+00, -1.0000e-01, 4.0000e-01, 1.2000e+00, -1.2000e+00, 6.0000e-01, 5.0000e-01, 5.0000e-01, -1.0000e-01, -5.0000e-01, -2.0000e-01, -1.2000e+00, -7.0000e-01, 0.0000e+00], [2.0000e-01, -9.0000e-01, 6.0000e-01, 7.0000e-01, -2.0000e-01, 5.0000e-01, 1.0000e-01, 7.0000e-01, 0.0000e+00, 3.0000e-01, 2.0000e-01, 4.0000e-01, -5.0000e-01, -4.0000e-01]]), array([[0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5455e+03, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -3.1336e+03, -8.1420e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -5.6900e+01, 2.3760e+02, -5.4960e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 2.7860e+02, -1.3400e+02, 2.1200e+02, -3.7540e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 4.5300e+01, 2.2000e+02, -1.2290e+02, 4.2900e+01, 1.0620e+02, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.8400e+01, 1.6800e+01, 4.8900e+01, -5.9800e+01, 1.0900e+01, 7.2800e+01, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -4.8900e+01, -1.4400e+01, -1.0000e+00, 2.3500e+01, -7.4000e+00, -2.5100e+01, -2.2000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 7.2000e+00, -1.2600e+01, 1.1500e+01, -9.7000e+00, 1.2700e+01, 7.0000e-01, -5.2000e+00, 3.9000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -2.4800e+01, 1.2100e+01, 8.3000e+00, -3.4000e+00, -5.3000e+00, 7.2000e+00, -6.0000e-01, 8.0000e-01, 9.8000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 3.3000e+00, 1.0000e-01, 2.5000e+00, 5.4000e+00, -9.0000e+00, 4.0000e-01, -4.2000e+00, -3.8000e+00, 9.0000e-01, -9.0000e+00, 0.0000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, 0.0000e+00, 2.8000e+00, -6.0000e-01, 1.0000e-01, 5.0000e-01, -3.0000e-01, -1.2000e+00, -1.7000e+00, -2.9000e+00, -1.8000e+00, -2.3000e+00, 0.0000e+00, 0.0000e+00], [0.0000e+00, -1.2000e+00, 6.0000e-01, 1.0000e+00, -1.5000e+00, 0.0000e+00, 6.0000e-01, -2.0000e-01, 8.0000e-01, 1.0000e-01, -9.0000e-01, 1.0000e-01, 2.0000e-01, 0.0000e+00], [0.0000e+00, -9.0000e-01, 7.0000e-01, 1.2000e+00, -3.0000e-01, -1.3000e+00, -1.0000e-01, 2.0000e-01, -2.0000e-01, 5.0000e-01, 6.0000e-01, -6.0000e-01, -3.0000e-01, -5.0000e-01]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [12.6, 10., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-11.2, -5.3, -8.3, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.5, -4.4, 0.4, -15.6, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [-1.7, -2.3, -5.8, 5.4, -6.8, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0.6, 1.3, 0., 0.7, 2.3, 1., 0., 0., 0., 0., 0., 0., 0., 0.], [-0.2, -0.3, 0.8, 1.2, -0.8, 0.4, 0.9, 0., 0., 0., 0., 0., 0., 0.], [-0.1, -0.1, -0.1, 0.5, -0.1, -0.8, -0.8, 0.9, 0., 0., 0., 0., 0., 0.], [-0.1, 0.2, 0., 0.4, -0.1, 0.3, 0.1, 0., 0.3, 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]), array([[0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -21.5, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -27.3, -11.1, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 3.8, -0.2, -3.9, 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -1.3, 4.1, 1.6, -4.1, 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., -0.5, 2.1, 0.5, 1.7, 1.9, 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0.3, -1.6, -0.4, 0.8, 0.7, 0.9, 0., 0., 0., 0., 0., 0., 0.], [0., 0.6, 0.5, -0.7, 0., -0.9, 0.5, -0.3, 0., 0., 0., 0., 0., 0.], [0., -0.3, 0.4, -0.3, 0.4, -0.5, -0.6, 0.3, 0.2, 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]), 2025.0, 13), year=None, rel_tol=1e-06, abs_tol=1e-09)[source]

Convert an ITRS position to quasi-dipole coordinates.

The QD latitude uses the point’s own ellipsoidal height against the apex height; the longitude is the centered-dipole longitude of the apex.

Port of ITRS2QD.

Parameters:

z_cart (array_like) – (3,) ITRS position in meters.
coeffs (MagneticCoefficients) – As in trace2earth_mag_apex().
year (float | None) – As in trace2earth_mag_apex().
rel_tol (float) – As in trace2earth_mag_apex().
abs_tol (float) – As in trace2earth_mag_apex().

Returns:

z_qd (ndarray) – (3,) [QD latitude (rad), QD longitude (rad), ellipsoidal height (m)]. The longitude is NaN for a polar-escaping line.
apex_point (ndarray) – (3,) the traced apex position in the ITRS (meters).

Return type:

tuple[ndarray[tuple[Any, …], dtype[float64]], ndarray[tuple[Any, …], dtype[float64]]]

Notes

coeffs is not checked against any validity window; see cd_rotation_matrix()’s Notes.

Examples

>>> z, apex = itrs2qd([6.4e6, 1e5, 2e6])
>>> z.shape
(3,)