chaosmagpy.chaos.CHAOS

class chaosmagpy.chaos.CHAOS(breaks, order=None, *, coeffs_tdep=None, coeffs_static=None, coeffs_sm=None, coeffs_gsm=None, breaks_delta=None, coeffs_delta=None, breaks_euler=None, coeffs_euler=None, breaks_cal=None, coeffs_cal=None, coeffs_ion=None, refh_ion=None, name=None, meta=None)[source]

Bases: object

Class for the time-dependent geomagnetic field model CHAOS.

Parameters:
breaksndarray, shape (m+1,)

Break points for piecewise polynomial representation of the time-dependent internal (i.e. large-scale core) field in modified Julian date format.

orderint, positive

Order k of polynomial pieces (e.g. 4 = cubic) of the time-dependent internal field.

coeffs_tdepndarray, shape (k, m, n_tdep * (n_tdep + 2))

Coefficients of the time-dependent internal field as piecewise polynomial.

coeffs_staticndarray, shape (n_static * (n_static + 2),)

Coefficients of the static internal (i.e. small-scale crustal) field.

coeffs_smndarray, shape (n_sm * (n_sm + 2),)

Coefficients of the static external field in SM coordinates.

coeffs_gsmndarray, shape (n_gsm * (n_gsm + 2),)

Coefficients of the static external field in GSM coordinates.

breaks_deltadict with ndarrays, shape (\(m_q\) + 1,)

Breaks of baseline corrections of static external field in SM coordinates. The dictionary keys are 'q10', 'q11', 's11'.

coeffs_deltadict with ndarrays, shape (1, \(m_q\))

Coefficients of baseline corrections of static external field in SM coordinates. The dictionary keys are 'q10', 'q11', 's11'.

breaks_eulerdict with ndarrays, shape (\(m_e\) + 1,)

Dictionary containing satellite name as key and corresponding break vectors of Euler angles (keys are 'oersted', 'champ', 'sac_c', 'swarm_a', 'swarm_b', 'swarm_c', 'cryosat-2_1').

coeffs_eulerdict with ndarrays, shape (1, \(m_e\), 3)

Dictionary containing satellite name as key and arrays of the Euler angles alpha, beta and gamma as trailing dimension (keys are 'oersted', 'champ', 'sac_c', 'swarm_a', 'swarm_b', 'swarm_c', 'cryosat-2_1').

breaks_caldict with ndarrays, shape (\(m_c\) + 1,)

Dictionary containing satellite name as key and corresponding break vectors for the calibration parameters (keys are 'cryosat-2_1').

coeffs_caldict with ndarrays, shape (1, \(m_c\), 3)

Dictionary containing satellite name as key and arrays of the 9 basic calibration parameters (3 offsets, 3 sensitivities, 3 non-orthogonality angles) (keys are 'cryosat-2_1').

coeffs_ionndarray, shape (n_base, n_ion * (n_ion + 2))

Coefficients of the ionospheric field in QD/MLT coordinates.

refh_ion: float

Reference height of the sheet current in the ionospheric E-layer.

namestr, optional

User defined name of the model. Defaults to 'CHAOS'.

metadict, optional

Dictionary containing additional information about the model.

Attributes:
timestampstr

UTC timestamp at initialization.

model_tdepBaseModel instance

Time-dependent internal field model.

model_staticBaseModel instance

Static internal field model.

model_eulerdict of Base instances

Dictionary containing the satellite’s name as key and the Euler angles as Base class instance.

model_caldict of Base instances

Dictionary containing the satellite’s name as key and the calibration parameters as Base class instance.

n_smint, positive

Maximum spherical harmonic degree of external field in SM coordinates.

coeffs_smndarray, shape (n_sm * (n_sm + 2),)

Coefficients of static external field in SM coordinates.

n_gsmint, positive

Maximum spherical harmonic degree of external field in GSM coordinates.

coeffs_gsmndarray, shape (n_gsm * (n_gsm + 2),)

Coefficients of static external field in GSM coordinates.

breaks_deltadict with ndarrays, shape (\(m_q\) +1,)

Breaks of baseline corrections of static external field in SM coordinates. The dictionary keys are 'q10', 'q11', 's11'.

coeffs_deltadict with ndarrays, shape (1, \(m_q\))

Coefficients of baseline corrections of static external field in SM coordinates. The dictionary keys are 'q10', 'q11', 's11'.

coeffs_ionndarray, shape (n_base, n_ion * (n_ion + 2))

Coefficients of the ionospheric field in QD/MLT coordinates.

n_ionint, positive

Maximum spherical harmonic degree in QD/MLT coordinates of the ionospheric E-layer field.

refh_ion: float

Reference height of the sheet current in the ionospheric E-layer.

namestr, optional

User defined name of the model.

metadict, optional

Dictionary containing additional information about the model.

Methods

__call__(time, radius, theta, phi[, rc_e, ...])

Calculate the magnetic field of all sources from the CHAOS model.

from_mat(filepath[, name, satellites])

Alternative constructor for creating a CHAOS class instance.

from_shc(filepath, *[, name, leap_year])

Alternative constructor for creating a CHAOS class instance.

plot_maps_external(time, radius, *[, nmax, ...])

Plot a global map of the magnetospheric field in the CHAOS model.

plot_maps_static(radius, *[, nmax])

Plot global map of the static internal field from the CHAOS model.

plot_maps_tdep(time, radius, *[, nmax, deriv])

Plot global map of the time-dependent internal field from the CHAOS model.

plot_timeseries_tdep(radius, theta, phi, ...)

Plot the time series of the time-dependent internal field from the CHAOS model at a given location.

save_matfile(filepath)

Save CHAOS model to a MAT-file.

save_shcfile(filepath, *[, model, leap_year])

Save spherical harmonic coefficients to a file in shc-format.

synth_coeffs_gsm(time, *[, nmax, source])

Compute the spherical harmonic coefficients of the far-magnetospheric magnetic field from the CHAOS model.

synth_coeffs_sm(time, *[, nmax, source, rc])

Compute the spherical harmonic coefficients of the near-magnetospheric magnetic field from the CHAOS model.

synth_coeffs_static(*[, nmax])

Compute the spherical harmonic coefficients of the static internal magnetic field from the CHAOS model.

synth_coeffs_tdep(time, *[, nmax])

Compute the spherical harmonic coefficients of the time-dependent internal magnetic field from the CHAOS model.

synth_euler_angles(time, satellite, *[, ...])

Extract Euler angles for specified satellite.

synth_values_gsm(time, radius, theta, phi, *)

Compute the vector components of the far-magnetospheric magnetic field from the CHAOS model.

synth_values_ion(time, radius, theta, phi, ...)

Compute the vector components of the ionospheric E-layer field from the CHAOS model.

synth_values_sm(time, radius, theta, phi, *)

Compute the vector components of the near-magnetospheric magnetic field from the CHAOS model.

synth_values_static(radius, theta, phi, *[, ...])

Compute the vector components of the static internal magnetic field from the CHAOS model.

synth_values_tdep(time, radius, theta, phi, *)

Compute the vector components of the time-dependent internal magnetic field from the CHAOS model.

Examples

Load for example the MAT-file CHAOS-6-x7.mat in the current working directory like this:

>>> import chaosmagpy as cp
>>> model = cp.CHAOS.from_mat('CHAOS-6-x7.mat')
>>> print(model)

For more examples, see the documentation of the methods below.

__call__(time, radius, theta, phi, rc_e=None, rc_i=None, imf_y=None, imf_z=None, v=None, f107=None, source_list=None, nmax_static=None, verbose=None)[source]

Calculate the magnetic field of all sources from the CHAOS model.

All sources means the time-dependent and static internal fields, the external magnetospheric (SM/GSM) fields including their induced parts, and the ionospheric E-layer field.

Parameters:
timendarray, shape (…) or float

Array containing the time in modified Julian dates.

radiusndarray, shape (…) or float

Radius of station in kilometers.

thetandarray, shape (…) or float

Colatitude in degrees \([0^\circ, 180^\circ]\).

phindarray, shape (…) or float

Longitude in degrees.

rc_endarray, shape (…), optional

External part of the RC-index (defaults to linearly interpolating the hourly values given by the built-in RC-index file).

rc_indarray, shape (…), optional

Internal part of the RC-index (defaults to linearly interpolating the hourly values given by the built-in RC-index file).

imf_yndarray, shape (…),

Y-component of the IMF in the GSM frame (nT). This is a required input when computing the ionospheric E-layer field, i.e. if 'ion' is in source_list.

imf_zndarray, shape (…)

Z-component of the IMF in the GSM frame (nT). This is a required input when computing the ionospheric E-layer field, i.e. if 'ion' is in source_list.

vndarray, shape (…)

X-component of the solar wind in the GSM/GSE frame (km/s). This is a required input when computing the ionospheric E-layer field, i.e. if 'ion' is in source_list.

f107ndarray, shape(…)

Solar radio flux (sfu). This is a required input when computing the ionospheric E-layer field, i.e. if 'ion' is in source_list.

source_listlist, [‘tdep’, ‘static’, ‘gsm’, ‘sm’, ‘ion’] or str, {‘internal’, ‘external’}

Specify sources in any order. Default is all sources. Instead of a list, pass source_list='internal' which is equivalent to source_list=['tdep', 'static'] (internal sources) or source_list='external' which is the same as source_list=['gsm', 'sm', 'ion'] (external sources including Earth-induced parts).

nmax_staticint, optional

Maximum spherical harmonic degree of the static internal magnetic field (defaults to 85).

verbose{False, True}, optional

Print messages (defaults to False).

Returns:
B_radius, B_theta, B_phindarray, shape (…)

Radial, colatitude and azimuthal field components.

Notes

Please find more details on computing the ionospheric E-layer field using the interplanetary magnetic field, the solar wind speed and the solar radio flux in the notes for chaosmagpy.chaos.CHAOS.synth_values_ion().

Examples

>>> import chaosmagpy as cp
>>> model = cp.CHAOS.from_mat('CHAOS-6-x7.mat')
>>> Br, Bt, Bp = model(0., 6371.2, 45., 0., source_list=['tdep', 'static'])  # only internal sources
>>> Br
array(-40418.23217586)
classmethod from_mat(filepath, name=None, satellites=None)[source]

Alternative constructor for creating a CHAOS class instance.

Parameters:
filepathstr

Path to MAT-file containing the CHAOS model.

namestr, optional

User defined name of the model. Defaults to the filename without the file extension.

satelliteslist of strings, optional

List of satellite names whose Euler angles are stored in the MAT-file. This is needed for correct referencing as this information is not given in the standard CHAOS MAT-file format (defaults to ['oersted', 'champ', 'sac_c', 'swarm_a', 'swarm_b', 'swarm_c', 'cryosat-2_1', 'cryosat-2_2', 'cryosat-2_3'].)

Returns:
modelCHAOS instance

Fully initialized model.

See also

load_CHAOS_matfile

Examples

Load for example the MAT-file CHAOS-6-x7.mat in the current working directory like this:

>>> from chaosmagpy import CHAOS
>>> model = CHAOS.from_mat('CHAOS-6-x7.mat')
>>> print(model)
classmethod from_shc(filepath, *, name=None, leap_year=None)[source]

Alternative constructor for creating a CHAOS class instance.

Parameters:
filepathstr

Path to SHC-file.

namestr, optional

User defined name of the model. Defaults to 'CHAOS-<version>', where <version> is the default in basicConfig['params.version'].

leap_year{False, True}, optional

Take leap year in time conversion into account. By default set to False, so that a conversion factor of 365.25 days per year is used.

Returns:
modelCHAOS instance

Class instance with either the time-dependent or static internal part initialized.

See also

load_CHAOS_shcfile

Examples

Load for example the SHC-file CHAOS-6-x7_tdep.shc in the current working directory, containing the coefficients of time-dependent internal part of the CHAOS-6-x7 model.

>>> import chaosmagpy as cp
>>> model = cp.CHAOS.from_shc('CHAOS-6-x7_tdep.shc')
>>> print(model)
plot_maps_external(time, radius, *, nmax=None, reference=None, source=None, rc_e=None, rc_i=None)[source]

Plot a global map of the magnetospheric field in the CHAOS model.

Parameters:
timendarray, shape (), (1,) or float

Time given as MJD2000 (modified Julian date).

radiusndarray, shape (), (1,) or float

Radius in kilometers.

nmaxint, positive, optional

Maximum degree harmonic expansion (default is given by the model coefficients, but can also be smaller, if specified).

reference{‘all’, ‘GSM’, ‘SM’}, optional

Choose contribution either from GSM, SM or the sum of both (default).

source{‘all’, ‘external’, ‘internal’}, optional

Choose source to be external (inducing), internal (induced) or the sum of both (default).

rc_endarray, shape (…), optional

External part of the RC-index (defaults to linearly interpolating the hourly values given by the built-in RC-index file). This is only used in the near-magnetospheric field (SM) part of the model.

rc_indarray, shape (…), optional

Internal part of the RC-index (defaults to linearly interpolating the hourly values given by the built-in RC-index file). This is only used in the near-magnetospheric field (SM) part of the model.

Notes

You may need to call matplotlib plt.show() to actually show the plot. For more customization get access to the figure and axes handles through matplotlib by using fig = plt.gcf() and axes = fig.axes right after the call to this plotting method.

plot_maps_static(radius, *, nmax=None, **kwargs)[source]

Plot global map of the static internal field from the CHAOS model.

Parameters:
radiusndarray, shape (), (1,) or float

Array containing the radius in kilometers.

nmaxint, positive, optional

Maximum degree harmonic expansion (default is given by the model coefficients, but can also be smaller, if specified).

**kwargskeywords

Other options are passed to BaseModel.plot_maps() method.

Notes

You may need to call matplotlib plt.show() to actually show the plot. For more customization get access to the figure and axes handles through matplotlib by using fig = plt.gcf() and axes = fig.axes right after the call to this plotting method.

plot_maps_tdep(time, radius, *, nmax=None, deriv=None, **kwargs)[source]

Plot global map of the time-dependent internal field from the CHAOS model.

Parameters:
timendarray, shape (), (1,) or float

Time given as MJD2000 (modified Julian date).

radiusndarray, shape (), (1,) or float

Array containing the radius in kilometers.

nmaxint, positive, optional

Maximum degree harmonic expansion (default is given by the model coefficients, but can also be smaller, if specified).

derivint, positive, optional

Derivative in time (default is 0). For secular variation, choose deriv=1.

**kwargskeywords

Other options are passed to BaseModel.plot_maps() method.

Notes

You may need to call matplotlib plt.show() to actually show the plot. For more customization get access to the figure and axes handles through matplotlib by using fig = plt.gcf() and axes = fig.axes right after the call to this plotting method.

plot_timeseries_tdep(radius, theta, phi, **kwargs)[source]

Plot the time series of the time-dependent internal field from the CHAOS model at a given location.

Parameters:
radiusndarray, shape (), (1,) or float

Radius of station in kilometers.

thetandarray, shape (), (1,) or float

Colatitude in degrees \([0^\circ, 180^\circ]\).

phindarray, shape (), (1,) or float

Longitude in degrees.

nmaxint, positive, optional

Maximum degree harmonic expansion (default is given by the model coefficients, but can also be smaller, if specified).

derivint, positive, optional

Derivative in time (default is 0). For secular variation, choose deriv=1.

**kwargskeywords

Other options to pass to BaseModel.plot_timeseries() method.

Notes

You may need to call matplotlib plt.show() to actually show the plot. For more customization get access to the figure and axes handles through matplotlib by using fig = plt.gcf() and axes = fig.axes right after the call to this plotting method.

save_matfile(filepath)[source]

Save CHAOS model to a MAT-file.

The model must be fully specified as is the case if originally loaded from a MAT-file.

Parameters:
filepathstr

Path and name of MAT-file that is to be saved.

save_shcfile(filepath, *, model=None, leap_year=None)[source]

Save spherical harmonic coefficients to a file in shc-format.

Parameters:
filepathstr

Path and name of output file *.shc.

model{‘tdep’, ‘static’}, optional

Choose part of the model to save (default is ‘tdep’).

leap_year{False, True}, optional

Take leap year in time conversion into account. By default set to False, so that a conversion factor of 365.25 days per year is used.

synth_coeffs_gsm(time, *, nmax=None, source=None)[source]

Compute the spherical harmonic coefficients of the far-magnetospheric magnetic field from the CHAOS model.

Parameters:
timendarray, shape (…) or float

Array containing the time in days.

nmaxint, positive, optional

Maximum degree harmonic expansion (default is given by the model coefficients, but can also be smaller, if specified).

source{‘external’, ‘internal’}, optional

Choose source either external or internal (default is ‘external’).

Returns:
coeffsndarray, shape (…, nmax * (nmax + 2))

Spherical harmonic coefficients of the far-magnetospheric magnetic field with respect to geographic coordinates (GEO).

Examples

>>> import chaosmagpy as cp
>>> model = cp.CHAOS.from_mat('CHAOS-6-x7.mat')
>>> model.synth_coeffs_gsm(0.0)
array([11.63982782, -4.9276483 , -2.36281582,  0.46063709, -0.37934517,
       -0.18234297,  0.06281656,  0.07757099])
synth_coeffs_sm(time, *, nmax=None, source=None, rc=None)[source]

Compute the spherical harmonic coefficients of the near-magnetospheric magnetic field from the CHAOS model.

Parameters:
timendarray, shape (…) or float

Array containing the time in days.

nmaxint, positive, optional

Maximum degree harmonic expansion (default is given by the model coefficients, but can also be smaller, if specified).

source{‘external’, ‘internal’}, optional

Choose source either external or internal (default is ‘external’).

rcndarray, shape (…), optional

External (internal) part of the RC-index (defaults to linearly interpolating the hourly values given by the built-in RC-index file). Use the external part of the RC-index for source='external' (default) and the internal part for source='internal'. See also the notes section below for more information on the RC-index file.

Returns:
coeffsndarray, shape (…, nmax * (nmax + 2))

Spherical harmonic coefficients of the near-magnetospheric magnetic field with respect to geographic coordinates (GEO).

See also

CHAOS.synth_values_sm

Notes

The computation of the near-magnetospheric field coefficients requires the RC-index. If the values of the RC-index are not supplied directly via the rc input argument, a built-in RC-index file is loaded. This file goes with a specific version of the CHAOS model, which can be inspected by running print(chaosmagpy.basicConfig['params.CHAOS_version']) in a Python session. It is recommended to use this version of the CHAOS model together with the built-in RC-index.

For the latest CHAOS model, if necessary, a suitable RC-index file can be downloaded at https://www.spacecenter.dk/files/magnetic-models/RC/. Overwrite the use of the built-in RC-index file by either providing interpolated values from the downloaded file via the rc input argument, or by replacing the path in ChaosMagPy’s configuration dictionary chaosmagpy.basicParams['file.RC_index'] with the path to the downloaded file (for more details, see Sect. Change RC index file).

Examples

>>> import chaosmagpy as cp
>>> model = cp.CHAOS.from_mat('CHAOS-6-x7.mat')
>>> model.synth_coeffs_sm(0.)
array([53.20309271,  3.79138724, -8.59458138, -0.62818711,  1.45506171,
       -0.57977672, -0.31660638, -0.43888236])
synth_coeffs_static(*, nmax=None, **kwargs)[source]

Compute the spherical harmonic coefficients of the static internal magnetic field from the CHAOS model.

Parameters:
nmaxint, positive, optional

Maximum degree harmonic expansion (default is given by the model coefficients, but can also be smaller, if specified).

**kwargskeywords

Other options are passed to BaseModel.synth_coeffs() method.

Returns:
coeffsndarray, shape (nmax * (nmax + 2),)

Coefficients of the static internal field.

Examples

>>> import chaosmagpy as cp
>>> model = cp.CHAOS.from_mat('CHAOS-6-x7.mat')
>>> model.synth_coeffs_static(nmax=50)
array([ 0.     , 0.     ,  0.     , ...,  0.01655, -0.06339,  0.00715])
synth_coeffs_tdep(time, *, nmax=None, **kwargs)[source]

Compute the spherical harmonic coefficients of the time-dependent internal magnetic field from the CHAOS model.

Parameters:
timendarray, shape (…) or float

Array containing the time in modified Julian dates.

nmaxint, positive, optional

Maximum degree harmonic expansion (default is given by the model coefficients, but can also be smaller, if specified).

**kwargskeywords

Other options to pass to BaseModel.synth_coeffs() method.

Returns:
coeffsndarray, shape (…, nmax * (nmax + 2))

Coefficients of the time-dependent internal field.

Examples

>>> import chaosmagpy as cp
>>> model = cp.CHAOS.from_mat('CHAOS-6-x7.mat')
>>> time = np.array([0., 10.])

>>> model.synth_coeffs_tdep(time, nmax=1)  # dipole coefficients
array([[-29614.72797782,  -1728.47079907,   5185.50518939],
       [-29614.33800306,  -1728.13680075,   5184.89196286]])

>>> model.synth_coeffs_tdep(time, nmax=1, deriv=1)  # SV coefficients
array([[ 14.25577646,  12.20214856, -22.43412895],
       [ 14.2317297 ,  12.19625726, -22.36146885]])
synth_euler_angles(time, satellite, *, dim=None, deriv=None, extrapolate=None)[source]

Extract Euler angles for specified satellite.

Parameters:
timefloat or ndarray, shape (…)

Time given as MJD2000 (modified Julian date).

satellitestr

Satellite from which to get the euler angles.

dimint, positive, optional

Maximum dimension (default is 3, for the three angles alpha, beta, gamma).

derivint, positive, optional

Derivative in time (default is 0).

extrapolate{‘linear’, ‘spline’, ‘constant’, ‘off’}, optional

Extrapolate to times outside of the model bounds. Defaults to 'linear'.

Returns:
anglesndarray, shape (…, 3)

Euler angles alpha, beta and gamma in degrees, stored in trailing dimension.

Examples

>>> import chaosmagpy as cp
>>> import numpy as np
>>> model = cp.CHAOS.from_mat('CHAOS-6-x7.mat')
>>> time = np.array([500., 600.])
>>> list(model.model_euler.keys())  # get list of satellite names
('oersted', 'champ', 'sac_c', 'swarm_a', 'swarm_b', 'swarm_c')

>>> model.synth_euler_angles(time, 'champ')
array([[-0.05521985, -1.5763316 ,  0.48787601],
       [-0.05440427, -1.57966925,  0.49043057]])
synth_values_gsm(time, radius, theta, phi, *, nmax=None, source=None, grid=None)[source]

Compute the vector components of the far-magnetospheric magnetic field from the CHAOS model.

Parameters:
timefloat or ndarray, shape (…)

Time given as MJD2000 (modified Julian date).

radiusfloat or ndarray, shape (…)

Array containing the radius in kilometers.

thetafloat or ndarray, shape (…)

Array containing the colatitude in degrees \([0^\circ,180^\circ]\).

phifloat or ndarray, shape (…)

Array containing the longitude in degrees.

nmaxint, positive, optional

Maximum degree harmonic expansion (default is given by the model coefficients, but can also be smaller, if specified).

source{‘all’, ‘external’, ‘internal’}, optional

Choose source to be external (inducing), internal (induced) or both added (default to ‘all’).

gridbool, optional

If True, field components are computed on a regular grid, which is created from theta and phi as their outer product (defaults to False).

Returns:
B_radius, B_theta, B_phindarray, shape (…)

Radial, colatitude and azimuthal field components.

Examples

>>> import chaosmagpy as cp
>>> model = cp.CHAOS.from_mat('CHAOS-6-x7.mat')
>>> time = np.array([0., 10.])
>>> Br, Bt, Bp = model.synth_values_gsm(time, 6371.2, 45., 0.)
>>> Br
array([-8.18751916, -8.25661729])
synth_values_ion(time, radius, theta, phi, imf_y, imf_z, v, f107, *, nmax=None, datafile=None, fortranlib=None)[source]

Compute the vector components of the ionospheric E-layer field from the CHAOS model.

Parameters:
timefloat or ndarray, shape (…)

Time given as MJD2000 (modified Julian date).

radiusfloat or ndarray, shape (…)

Array containing the radius in kilometers.

thetafloat or ndarray, shape (…)

Array containing the colatitude in degrees \([0^\circ,180^\circ]\).

phifloat or ndarray, shape (…)

Array containing the longitude in degrees.

imf_yndarray, shape (…)

Y-component of the interplanetary magnetic field in the GSM frame (nT).

imf_zndarray, shape (…)

Z-component of the interplanetary magnetic field in the GSM frame (nT).

vndarray, shape (…)

X-component of the solar wind velocity in the GSM/GSE frame (km/s).

f107ndarray, shape(…)

Solar radio flux (sfu).

nmaxint, positive, optional

Maximum spherical harmonic degree (defaults is given by the model coefficients).

datafilestr, optional

Path to custom coefficient file (defaults to apexsh.dat file in apexpy).

fortranlibstr, optional

Path to Fortran Apex CPython library (defaults to the linked library file in apexpy.

Returns:
B_radius, B_theta, B_phindarray, shape (…)

Radial, colatitude and azimuthal field components.

Warning

Predictions of the ionospheric magnetic field below the reference height (110 km), including at the Earth’s surface, are only approximate because contributions from the associated Earth-induced magnetic field are not taken into account.

The CHAOS-8 ionospheric field is estimated from data at satellite altitude and represents the combined fields from the E-layer currents and associated Earth-induced currents. Because these two contributions are not separated in the model, the total ionospheric field cannot be directly downward-continued to the Earth’s surface. However, since the induced counterpart is expected to be small at satellite altitude, the dominant E-layer field can be approximated at ground level, assuming the E-layer currents flow in a horizontal sheet at the reference height. This function implements the above approximation to estimate the dominant E-layer field below the reference height.

See also

chaosmagpy.coordinate_utils.clock_angle
chaosmagpy.coordinate_utils.coupling_Newell
chaosmagpy.coordinate_utils.dipole_tilt

Notes

Time series of the interplanetary magnetic field (imf_y, imf_z), solar wind speed (v) and the observed solar radio flux (f107) are available for download as CDF-files on the CHAOS-8 website (reading these files requires a reader such as cdflib). The time series can then be linearly interpolated at the desired time points using:

>>> import numpy
>>> import cdflib

>>> time = numpy.array([0., 10.])  # desired time series in MJD2000
>>> file = cdflib.CDF('F107_1day_19960101T120000_20250609T120000.cdf')
>>> f107 = numpy.interp(time, file.varget('Time'), file.varget('F107'))

for f107 and, similarly, for imf_y, imf_z, and v:

>>> file = cdflib.CDF('IMFV_1min_199701_202508.cdf')
>>> imf_y = numpy.interp(time, file.varget('Time'), file.varget('IMF_Y'))
>>> imf_z = numpy.interp(time, file.varget('Time'), file.varget('IMF_Z'))
>>> v = numpy.interp(time, file.varget('Time'), file.varget('V_X'))

Alternatively, interplanetary magnetic field (By and Bz in GSM) and solar wind speed (v) data at 1-minute resolution can be downloaded at OMNIWeb. The time series should be smoothed using a backward-looking 20-minute rolling mean before they are linearly interpolated.

The observed solar radio flux f107 is available at daily resolution from the LASP Interactive Solar Irradiance Datacenter, which can be linearly interpolated at the desired time points. Here, no smoothing is needed.

Examples

>>> import chaosmagpy as cp
>>> import numpy as np

>>> model = cp.CHAOS.from_mat('CHAOS-8.3.mat')

>>> time, r, theta, phi = np.array([0., 10.]), 6800., 45., 0.  # at satellite altitude
>>> imf_y, imf_z, v, f107 = (2., -4., 350., 100.)
>>> Br, Bt, Bp = model.synth_values_ion(time, r, theta, phi, imf_y, imf_z, v, f107)
>>> Br
array([0.92402341, 0.85912358])
synth_values_sm(time, radius, theta, phi, *, rc_e=None, rc_i=None, nmax=None, source=None, grid=None)[source]

Compute the vector components of the near-magnetospheric magnetic field from the CHAOS model.

Parameters:
timefloat or ndarray, shape (…)

Time given as MJD2000 (modified Julian date).

radiusfloat or ndarray, shape (…)

Array containing the radius in kilometers.

thetafloat or ndarray, shape (…)

Array containing the colatitude in degrees \([0^\circ,180^\circ]\).

phifloat or ndarray, shape (…)

Array containing the longitude in degrees.

nmaxint, positive, optional

Maximum degree harmonic expansion (default is given by the model coefficients, but can also be smaller, if specified).

source{‘all’, ‘external’, ‘internal’}, optional

Choose source to be external (inducing), internal (induced) or both added (defaults to ‘all’).

gridbool, optional

If True, field components are computed on a regular grid, which is created from theta and phi as their outer product (defaults to False).

rc_endarray, shape (…), optional

External part of the RC-index (defaults to linearly interpolating the hourly values given by the built-in RC-index file).

rc_indarray, shape (…), optional

Internal part of the RC-index (defaults to linearly interpolating the hourly values given by the built-in RC-index file).

Returns:
B_radius, B_theta, B_phindarray, shape (…)

Radial, colatitude and azimuthal field components.

See also

CHAOS.synth_values_sm

Notes

The computation of the near-magnetospheric field coefficients requires the RC-index. If the values of the RC-index are not supplied directly via the rc input argument, a built-in RC-index file is loaded. This file goes with a specific version of the CHAOS model, which can be inspected by running print(chaosmagpy.basicConfig['params.CHAOS_version']) in a Python session. It is recommended to use this version of the CHAOS model together with the built-in RC-index.

For the latest CHAOS model, if necessary, a suitable RC-index file can be downloaded at https://www.spacecenter.dk/files/magnetic-models/RC/. Overwrite the use of the built-in RC-index file by either providing interpolated values from the downloaded file via the rc input argument, or by replacing the path in ChaosMagPy’s configuration dictionary chaosmagpy.basicParams['file.RC_index'] with the path to the downloaded file (for more details, see Sect. Change RC index file).

Examples

>>> import chaosmagpy as cp
>>> model = cp.CHAOS.from_mat('CHAOS-6-x7.mat')
>>> time = np.array([0., 10.])
>>> Br, Bt, Bp = model.synth_values_sm(time, 6371.2, 45., 0.)
>>> Br
array([-18.85890361, -13.99893523])
synth_values_static(radius, theta, phi, *, nmax=None, **kwargs)[source]

Compute the vector components of the static internal magnetic field from the CHAOS model.

Parameters:
radiusndarray, shape (…) or float

Radius of station in kilometers.

thetandarray, shape (…) or float

Colatitude in degrees \([0^\circ, 180^\circ]\).

phindarray, shape (…) or float

Longitude in degrees.

nmaxint, positive, optional

Maximum degree harmonic expansion (default is given by the model coefficients, but can also be smaller, if specified).

**kwargskeywords

Other options are passed to BaseModel.synth_values() method.

Returns:
B_radius, B_theta, B_phindarray, shape (…)

Radial, colatitude and azimuthal field components.

Examples

>>> import chaosmagpy as cp
>>> model = cp.CHAOS.from_mat('CHAOS-6-x7.mat')
>>> Br, Bt, Bp = model.synth_values_static(6371.2, 45., 0., nmax=50)
>>> Br
array(-7.5608993)
synth_values_tdep(time, radius, theta, phi, *, nmax=None, deriv=None, grid=None, extrapolate=None)[source]

Compute the vector components of the time-dependent internal magnetic field from the CHAOS model.

Parameters:
timendarray, shape (…) or float

Array containing the time in modified Julian dates.

radiusndarray, shape (…) or float

Radius of station in kilometers.

thetandarray, shape (…) or float

Colatitude in degrees \([0^\circ, 180^\circ]\).

phindarray, shape (…) or float

Longitude in degrees.

nmaxint, positive, optional

Maximum degree harmonic expansion (default is given by the model coefficients, but can also be smaller, if specified).

derivint, positive, optional

Derivative in time (None defaults to 0). For secular variation, choose deriv=1.

gridbool, optional

If True, field components are computed on a regular grid. Arrays theta and phi must have one dimension less than the output grid since the grid will be created as their outer product.

extrapolate{‘linear’, ‘quadratic’, ‘cubic’, ‘spline’, ‘constant’, ‘off’} or int, optional

Extrapolate to times outside of the model bounds. Specify polynomial degree as string or any order as integer. Defaults to 'linear' (equiv. to order 2 polynomials).

Returns:
B_radius, B_theta, B_phindarray, shape (…)

Radial, colatitude and azimuthal field components.

Examples

>>> import chaosmagpy as cp
>>> model = cp.CHAOS.from_mat('CHAOS-6-x7.mat')
>>> time = np.array([0., 10.])

Compute magnetic field components at specific location.

>>> Br, Bt, Bp = model.synth_values_tdep(time, 6371.2, 45., 0.)
>>> Br
array([-40422.44815265, -40423.15091334])

Only dipole contribution:

>>> Br, Bt, Bp = model.synth_values_tdep(time, 6371.2, 45., 0., nmax=1)
>>> Br
array([-44325.97679843, -44324.95294588])

Secular variation:

>>> Br, Bt, Bp = model.synth_values_tdep(time, 6371.2, 45., 0., deriv=1)
>>> Br
array([-25.64604374, -25.69002078])