# API References¶

## Core Functionality¶

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¶

This module provides functions related to coordinate transformations. Typical coordinate reference frames and corresponding abbbreviations 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 Eart-Sun line and dipole axis and z-axis completing 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, and x-axis completing 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) 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. 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¶

This module provide functions for building the CHAOS model and geomagnetic field models in general.

 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, source]) Compute the spatial power spectrum. degree_correlation(coeffs_1, coeffs_2) Correlation per spherical harmonic degree between two models 1 and 2.

## Plotting Utilities¶

This module provides functions for plotting model outputs.

 plot_timeseries(time, *args, **kwargs) Returns a line plot showing the timeseries of the input arguments. plot_maps(theta_grid, phi_grid, *args, **kwargs) Returns a global map showing the input arguments. plot_power_spectrum(spectrum, **kwargs) Plot spherical harmonic spectrum. Define custom-built colormap 'nio' and register.

## Data Utilities¶

The module provides functions for loading and writing data and models. It also offers functions to do simple 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¶

Parameters and options in ChaosMagPy are stored in a dictionary and can be modified as desired. The following list gives an overview of the possible keywords.

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

Current version of the CHAOS model, 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

‘files.RC_index’

h5-file, txt-file

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

‘files.GSM_spectrum’

npz-file

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

‘files.SM_spectrum’

npz-file

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

‘files.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.