API References

The ChaosMagPy package consists of several modules, which contain classes and functions that are relevant in geomagnetic field modelling:

  • chaosmagpy.chaos: Everything related to loading specific geomagnetic field models, such as CHAOS, Cov-Obs, and other piecewise-polynomial spherical harmonic models (see Sect. Core Functionality).

  • chaosmagpy.coordinate_utils: Everything related to coordinate transformations and change of reference frames (see Sect. Coordinate Transformations).

  • chaosmagpy.model_utils: Everything related to evaluating geomagnetic field models, which includes functions for evaluating B-splines, Legendre polynomials and spherical harmonics (see Sect. Model Utilities)

  • chaosmagpy.plot_utils: Everything related to plotting geomagnetic field model outputs, i.e. plotting of timeseries, maps and spatial power spectra (see Sect. Plotting Utilities).

  • chaosmagpy.data_utils: Everything related to loading and saving datasets and model coefficients from and to files. This also includes functions for transforming datetime formats (see Sect. Data Utilities).

  • chaosmagpy.config_utils: Everything related to the configuration of ChaosMagPy, which includes setting parameters and paths to builtin data files (see Sect. Configuration Utilities).

Core Functionality

chaosmagpy.chaos provides classes and functions to read the CHAOS model and other geomagnetic field models.

Base(name[, breaks, order, coeffs, meta])

Piecewise polynomial base class.

BaseModel(name[, breaks, order, coeffs, ...])

Class for piecewise polynomial spherical harmonic models.

CHAOS(breaks[, order, coeffs_tdep, ...])

Class for the time-dependent geomagnetic field model CHAOS.

load_CHAOS_matfile(filepath[, name, satellites])

Load CHAOS model from MAT-file.

load_CHAOS_shcfile(filepath[, name, leap_year])

Load CHAOS model from SHC-file.

load_CovObs_txtfile(filepath[, name])

Load the ensemble mean of the internal model from the COV-OBS TXT-file in spline format.

load_gufm1_txtfile(filepath[, name])

Load model parameter file of the gufm1 model.

load_CALS7K_txtfile(filepath[, name])

Load the model parameter file of the CALS7K model.

load_IGRF_txtfile(filepath[, name])

Load the IGRF internal field model from the TXT-file with the piecewise-polynomial coefficients.

Coordinate Transformations

chaosmagpy.coordinate_utils provides functions related to coordinate transformations. Typical coordinate reference frames and corresponding abbreviations are listed in the following.


GEOGeographic coordinate system (orthogonal)

Geocentric coordinate system with the z-axis along Earth’s rotation axis, x-axis pointing to Greenwich and y-axis completing the right-handed system. This is also referred to as the ECEF (Earth-centered Earth-fixed) coordinate system.

GGGeodetic coordinate system (orthogonal).

Earth is approximated by a spheroid (ellipsoid of revolution) with equatorial radius a and polar radius b, b < a. The numerical values of these radii are defined by the World Geodetic System 1984 (WGS84).

USELocal Up-South-East frame defined on the sphere.

Axes directions are defined as Up-South-East at the point of interest on the sphere (e.g., B_radius, B_theta, B_phi, the spherical components of GEO).

GSMGeocentric Solar Magnetospheric coordinate system (orthogonal).

With x-axis pointing towards the sun, y-axis perpendicular to plane spanned by Earth-Sun line and the dipole axis, z-axis completes right-handed system.

SMSolar Magnetic coordinate system (orthogonal)

With z-axis along dipole axis pointing to the geomagnetic north pole, y-axis perpendicular to plane containing the dipole axis and the Earth-Sun line, x-axis completes the right-handed system.

MAGMagnetic coordinate system (centered dipole, orthogonal)

With z-axis pointing to the geomagnetic north pole, x-axis in the plane spanned by the dipole axis and Earth’s rotation axis, and y-axis completing the right-handed system.


Compute unit vector that is anti-parallel to the IGRF dipole.

synth_rotate_gauss(time, frequency, spectrum)

Compute time-dependent matrices that transform spherical harmonic expansion from the given Fourier coefficients.

rotate_gauss_fft(nmax, kmax, *[, qfunc, ...])

Compute Fourier coefficients of the timeseries of matrices that transform spherical harmonic expansions (degree kmax) from a time-dependent reference system (GSM, SM) to GEO (degree nmax).

rotate_gauss(nmax, kmax, base_1, base_2, base_3)

Compute matrices for the coordinate transformation of spherical harmonic expansions.

sh_analysis(func, nmax[, kmax])

Perform a spherical harmonic expansion of a function defined on a spherical surface.


Computes the sun's position in longitude and colatitude at a given time (mjd2000).

zenith_angle(time, theta, phi)

Compute the solar zenith angle.

spherical_to_cartesian(radius, theta, phi)

Convert spherical coordinates to cartesian coordinates.

cartesian_to_spherical(x, y, z)

Convert cartesian coordinates to spherical coordinates.

basevectors_gg(theta, beta)

Compute the geodetic basevectors of the WGS84.

basevectors_gsm(time[, dipole])

Compute the unit base vectors of the GSM coordinate system.

basevectors_sm(time[, dipole])

Compute the unit base vectors of the SM coordinate system.

basevectors_use(theta, phi)

Computes the unit base vectors of the local USE frame (spherical components).


Compute the unit base vectors of the centered dipole coordinate system (sometimes referred to as MAG).

geo_to_gg(radius, theta[, B_radius, B_theta])

Compute geodetic coordinates and components as defined by the World Geodetic System 1984 (WGS84) from spherical geographic coordinates and components.

gg_to_geo(height, beta[, X, Z])

Compute spherical geographic coordinates and components from geodetic coordinates and components as defined by the World Geodetic System 1984 (WGS84).

geo_to_base(theta, phi, base_1, base_2, base_3)

Transform spherical geographic coordinates into rotated spherical coordinates as given by three cartesian unit base vectors.

matrix_geo_to_base(theta, phi, base_1, ...)

Transform vector components in the local USE frame of GEO to components in the local USE frame of a rotated spherical coordinate system as given by three cartesian unit base vectors.

transform_points(theta, phi[, time, ...])

Transform spherical geographic coordinates into rotated spherical coordinates.

transform_vectors(theta, phi, B_theta, B_phi)

Transform vector components in the local USE frame of GEO to components in the local USE frame of a magnetic coordinate system.


Project azimuth angles in degrees to the semi-open interval \((-180^\circ, 180^\circ]\).

local_time(time, phi)

Compute local time in terms of the azimuthal distance to the prime meridian.

q_response(frequency, nmax)

Compute the Q-response for a given conductivity model of Earth.

q_response_1D(periods, sigma, radius, n[, kind])

Compute the response for a spherically layered conductor in an inducing external field of a single spherical harmonic degree.

Model Utilities

chaosmagpy.model_utils provides functions for analyzing and estimating geomagnetic field models in general, and the CHAOS geomagnetic field model in particular.

design_matrix(knots, order, n_tdep, time, ...)

Returns matrices that connect radial, colatitude and azimuthal field components on a grid with radius, theta (colatitude) and phi to the spherical harmonics expansion of a potential.

design_gauss(radius, theta, phi, nmax, *[, ...])

Computes matrices to connect the radial, colatitude and azimuthal field components to the magnetic potential field in terms of spherical harmonic coefficients (Schmidt quasi-normalized).

colloc_matrix(x, knots, order[, deriv])

Create collocation matrix of a univariate function on x in terms of a B-spline representation of order k.

augment_breaks(breaks, order)

Augment a vector of break points and return the knot vector for a B-spline representation of order k.

pp_from_bspline(coeffs, knots, order)

Return a piecewise polynomial from a BSpline representation.

synth_from_pp(breaks, order, coeffs, time, ...)

Compute radial, colatitude and azimuthal field components from the magnetic potential in terms of a spherical harmonic expansion in form of a piecewise polynomial.

synth_values(coeffs, radius, theta, phi, *)

Computes radial, colatitude and azimuthal field components from the magnetic potential field in terms of spherical harmonic coefficients.

legendre_poly(nmax, theta)

Returns associated Legendre polynomials \(P_n^m(\cos\theta)\) (Schmidt quasi-normalized) and the derivative \(dP_n^m(\cos\theta)/d\theta\) evaluated at \(\theta\).

power_spectrum(coeffs[, radius, nmax, ...])

Compute the spatial power spectrum.

degree_correlation(coeffs_1, coeffs_2)

Correlation per spherical harmonic degree between two models 1 and 2.

sensitivity(coeffs, coeffs_true)

Sensitivity (degree normalized error) of the input coefficients with respect to the target/true coefficients.

Plotting Utilities

chaosmagpy.plot_utils provides functions for plotting model outputs.

plot_timeseries(time, *args, **kwargs)

Creates line plots for the timeseries of the input arguments.

plot_maps(theta_grid, phi_grid, *args, **kwargs)

Plots global maps of the input arguments.

plot_power_spectrum(spectrum, **kwargs)

Plot the spherical harmonic spectrum.


Define custom-built colormap 'nio' and register.

Data Utilities

chaosmagpy.data_utils provides functions for loading and writing data and geomagnetic field models. It also offers functions to do common time conversions.

load_matfile(filepath[, variable_names])

Load MAT-file and return dictionary.

load_RC_datfile([filepath, parse_dates])

Load RC-index data file into pandas data frame.

save_RC_h5file(filepath[, read_from])

Return HDF5-file of the RC index.

load_shcfile(filepath[, leap_year, comment])

Load SHC-file and return coefficient arrays.

save_shcfile(time, coeffs[, order, ...])

Save Gauss coefficients as SHC-file.

mjd2000(year[, month, day, hour, minute, ...])

Computes the modified Julian date as floating point number (epoch 2000).


Convert modified Julian date to NumPy's datetime format.


Determine if input year is a leap year.

dyear_to_mjd(time[, leap_year])

Convert time from decimal years to modified Julian date 2000.

mjd_to_dyear(time[, leap_year])

Convert time from modified Julian date 2000 to decimal years.


Compute memory usage of pandas object.


Return string of the magnetic field units given the derivative with time.

Configuration Utilities

chaosmagpy.config_utils contains functions and classes to manipulate the configuration dictionary, which contains parameters and options in ChaosMagPy. The following list gives an overview of the possible keywords. The keywords can be accessed after importing chaosmagpy through:

>>> import chaosmagpy as cp
>>> cp.basicConfig['params.r_surf']  # get Earth's mean radius in km







Reference radius in kilometers (defaults to Earth’s surface radius of 6371.2 km).



Core-mantle boundary radius in kilometers (defaults to 3485.0 km).


list, ndarray, shape (3,)

Coefficients of the dipole (used for GSM/SM coordinate transformations) in units of nanotesla.


list, ndarray shape (2,)

Equatorial (index 0) and polar radius (index 1) of the spheroid describing Earth (WGS84) in units of kilometers.



Version of the CHAOS model that was constructed with the built-in RC-index.



Number of days on Jan 01, 2000 since Jan 01, 0000 (CDF start epoch)






HDF5-file, TXT-file

RC-index file (used for external field computation). See also data_utils.save_RC_h5file().



GSM transformation coefficients. See also coordinate_utils.rotate_gauss_fft().



SM transformation coefficients. See also coordinate_utils.rotate_gauss_fft().



Conductivity model of a layered Earth (deprecated).


SHP-file, ZIP-file

Coastline shapefile (default file provided by Natural Earth).







Plot width in inches (defaults to 6.3 inches or 16 cm)

BasicConfig(*args, **kwargs)

Class for creating CHAOS configuration dictionary.