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.

Coordinate Transformations

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

Abbreviations

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

USECartesian coordinate system on spherical surface.

Axes directions are defined as Up-South-East at a point of interest on the spherical surface (e.g. B_radius, B_theta, B_phi in spherical geocentric coordinates).

GSMGeocentric Solar Magnetic 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.

igrf_dipole([epoch])

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.

sun_position(time)

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 to cartesian coordinates.

cartesian_to_spherical(x, y, z)

Convert geocentric cartesian to spherical coordinates.

basevectors_gsm(time[, dipole])

Compute the unit base vectors of the GSM coordinate system with respect to the standard geographic coordinate system (GEO).

basevectors_sm(time[, dipole])

Computes the unit base vectors of the SM coordinate system with respect to the standard geographic coordinate system (GEO).

basevectors_use(theta, phi)

Computes the unit base vectors of local orthogonal coordinate system USE (Up-South-East) on the spherical surface (theta, phi) with respect to the standard geographic coordinate system (GEO).

basevectors_mag([dipole])

Computes the unit base vectors of the central-dipole coordinate system (sometimes referred to as MAG) with respect to the standard geographic coordinate system (GEO).

geo_to_gg(radius, theta)

Compute geodetic colatitude and vertical height above the ellipsoid as defined by the World Geodetic System 1984 (WGS84) from geocentric radius and colatitude.

gg_to_geo(height, beta)

Compute geocentric colatitude and radius from geodetic colatitude and vertical height above the ellipsoid 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 spherical coordinates of a rotated geocentric coordinate system as given by three base vectors.

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

Compute matrices to trasnform vector components from USE frame at given spherical geographic coordinates into components with respect to a rotated geocentric coordinate system.

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

Transform spherical geographic coordinates (GEO) into spherical coordinates of a rotated geocentric coordinate system.

transform_vectors(theta, phi, B_theta, B_phi)

Transform vectors resolved into components in USE (Up-South-East) at given spherical geographic coordinates (GEO) to components in USE into components with respect to a rotated geocentric coordinate system.

center_azimuth(phi)

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

local_time(time, phi)

Compute local time from the azimuthal distance to 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.

nio_colormap()

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 hdf-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).

timestamp(time)

Convert modified Julian date to NumPy's datetime format.

is_leap_year(year)

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.

memory_usage(pandas_obj)

Compute memory usage of pandas object.

gauss_units([deriv])

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
    6371.2

Parameters

Value

Type

Description

‘params.r_surf’

float

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

‘params.r_cmb’

float

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

‘params.dipole’

list, ndarray, shape (3,)

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

‘params.ellipsoid’

list, ndarray shape (2,)

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

‘params.CHAOS_version’

str

Version of the CHAOS model that was constructed with the built-in RC-index, e.g. '7.1'.

‘params.cdf_to_mjd’

int

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

Files

Value

Type

Description

‘file.RC_index’

h5-file, txt-file

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

‘file.GSM_spectrum’

npz-file

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

‘file.SM_spectrum’

npz-file

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

‘file.Earth_conductivity’

txt-file

Conductivity model of a layered Earth (used for induced fields).

Plots

Value

Type

Description

‘plots.figure_width’

float

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

BasicConfig(*args, **kwargs)

Class for creating CHAOS configuration dictionary.