Lifetime models due to chorus waves

The chorus provides lifetime models due to interaction with chorus waves.

Models:

  • Gu et al., (2012) - Parameterized polynomial model

  • Wang et al., (2024) - Lookup table model

G2012(mlt, L, en, kp)

Calculates electron lifetime due to chorus waves following Gu et al. [2012] model, including correction [Gu et al., 2012].

W2024(L, en, kp, mlt[, method, data_file, ...])

Calculates electron lifetime due to chorus waves following Wang et al. [2024] model.

Functions

rbamlib.models.tau.chorus.G2012(mlt, L, en, kp)

Calculates electron lifetime due to chorus waves following Gu et al. [2012] model, including correction [Gu et al., 2012].

Parameters:

  • mlt (float or ndarray) – Magnetic local time in hours. Dayside is assumed for \(6 \le \mathrm{MLT} < 18\), nightside otherwise.

  • L (float or ndarray) – L-shell (McIlwain L), dimensionless. Valid: \(3 \le L \le 10\).

  • en (float or ndarray) – Kinetic energy (MeV). Energy range: 1 keV–2 MeV

  • kp (float or ndarray) – Kp index (dimensionless). Scaling is applied for \(Kp \in [0,6]\).

Returns:

Electron lifetime in seconds. Returns NaN if outside a parameterized bin (e.g., nightside energies above 0.1 MeV).

Return type:

float or ndarray

Notes

Parameterization. Lifetimes are expressed as polynomials in \(L\) and energy with coefficients \(a_1,\ldots,a_{10}\) (Table S1), and equations from the Gu et al. (2012)

  • Dayside: 1–10 keV (Eq. 1), 10–100 keV (Eq. 2), 0.1–0.4 MeV (Eq. 3), 0.4–2.0 MeV (Eq. 4).

  • Nightside: 1–10 keV (Eq. 5), 10–100 keV (Eq. 6, corrected).

Kp scaling and MLT coverage. The final lifetime includes Kp‑dependent wave‑amplitude scaling and a factor of 4 to account for 25% MLT coverage (drift‑averaged presence of chorus):

\[\begin{split}\tau(kp) = 4 \cdot \tau \cdot \left( \frac{B_w}{B_w(kp)} \right)^2 = \begin{cases} 4\,\tau \left[2*10^\sqrt{0.73 + 0.91 kp}/{57.6}\right]^{-2}, & Kp \le 2+ \\ 4\,\tau \left[2*10^\sqrt{2.50 + 0.18 kp}/{57.6}\right]^{-2}, & 2+ < Kp \le 6 \end{cases}\end{split}\]
rbamlib.models.tau.chorus.W2024(L, en, kp, mlt, method='albert', data_file=None, data_folder=None, auto_download=False)

Calculates electron lifetime due to chorus waves following Wang et al. [2024] model.

This model uses nearest neighbor lookup from a precomputed lifetime database as a function of L-shell, energy, Kp, and MLT.

Parameters:

  • L (float or ndarray) – L-shell (McIlwain L), dimensionless. Valid range: 3 ≤ L ≤ 7.

  • en (float or ndarray) – Kinetic energy (MeV). Valid range: 0.001 ≤ en ≤ 2.0.

  • kp (float or ndarray) –

    Kp index (dimensionless). Valid range: 1 ≤ Kp ≤ 6.

    Warning: Model is valid only for Kp ≤ 6. Use caution for Kp > 6.

  • mlt (float or ndarray) – Magnetic local time in hours (0-24).

  • method (str, optional) –

    Lifetime calculation method:

    • albert (default): Albert & Shprits (2009)

    • lc: Loss cone method (Shprits et al., 2006)

  • data_file (str, optional) –

    Path to data file (absolute, relative, or filename).

    Default: life_time_all_Kp_MLT_calculated_from_matrix.mat

  • data_folder (str, optional) – Folder to search for data file. Default: current working directory.

  • auto_download (bool, default=False) – If True, automatically download the data file from GFZ Data Services if data file not found.

Returns:

Electron lifetime in seconds.

Return type:

float or ndarray

Notes

Data File Requirements:

This model requires: life_time_all_Kp_MLT_calculated_from_matrix.mat (~35 MB)

Download from:

Note

The original paper references data files at DOI 10.5880/GFZ.2.7.2022.002, but the auto_download feature uses an updated version of the dataset hosted on GFZ Nextcloud with filename life_time_all_Kp_MLT_calculated_from_matrix.mat.

File search order:

  1. If data_file provided → try opening

  2. If not found → search in data_folder (default: current directory)

  3. If auto_download=True → download and extract to data_folder

Examples

>>> from rbamlib.models.tau.chorus import W2024
>>> tau = W2024(L=5.0, en=1.0, kp=3.0, mlt=12.0, auto_download=True)
>>> print(f"Lifetime: {tau:.2e} seconds")

>>> # Using manually downloaded file
>>> tau = W2024(L=5.0, en=1.0, kp=3.0, mlt=12.0, data_file='path/to/file.mat')

>>> # Array inputs
>>> import numpy as np
>>> L = np.array([4.0, 5.0, 6.0])
>>> tau = W2024(L, en=1.0, kp=3.0, mlt=12.0)