Magnetic field related models

The mag provides magnetic field related models. Note, dipole field related functions are in the module dip.

Models:

  • Tsyganenko & Sitnov (2005) W and S coefficients

TS2005_S(Nsw, Vsw, Bz[, fillval])

Compute the Tsyganenko & Sitnov (2005) [2005] source functions \(S_k\), per Eq.

TS2005_W(time, S[, storm_onsets, fill_value])

Compute Tsyganenko & Sitnov (2005) [2005] \(W_k(t_i)\), per Eq.

Functions

rbamlib.models.mag.TS2005_S(Nsw, Vsw, Bz, fillval=None)

Compute the Tsyganenko & Sitnov (2005) [2005] source functions \(S_k\), per Eq. (8):

\[S_k = \left(\frac{N_{\mathrm{sw}}}{5}\right)^{\lambda_k} \left(\frac{V_{\mathrm{sw}}}{400}\right)^{\beta_k} \left(\frac{B_s}{5}\right)^{\gamma_k},\]

where \(B_s = -B_z\) if \(B_z < 0\) else 0, and \((\lambda_k, \beta_k, \gamma_k)\) are from the Tsyganenko & Sitnov (2005) model tables.

Parameters:

  • Nsw (1D ndarray) – Solar wind density array.

  • Vsw (1D ndarray) – Solar wind velocity array.

  • Bz (1D ndarray) – IMF Bz array.

  • fillval (float, optional) – Fill values of S if is computed as np.nan (due to invalid input)

Returns:

S – 6 different \(S_k(t)\) time series (one column per k).

Return type:

2D ndarray, shape (N, 6)

rbamlib.models.mag.TS2005_W(time, S, storm_onsets=None, fill_value=nan)

Compute Tsyganenko & Sitnov (2005) [2005] \(W_k(t_i)\), per Eq. (7) with optional “storm-by-storm” resets.

Parameters:

  • time (1D array-like of datetime.datetime) – Strictly increasing times. Must match the length of the second dimension of S.

  • S (2D ndarray, shape (N, 6)) – The source function \(S_k(t_i)\) (from eq. (8)). 6 columns for k=1..6, N rows for times 0..N-1.

  • storm_onsets (list or 1D array of int, default=None) – Indices of time that mark the beginning of each storm. If provided, then for i in [onsets[m]..onsets[m+1]-1], we sum from onsets[m]. Times before the first onset or after the last are filled with fill_value. If None (default), we sum from i=0 (the earliest time). Add 0 to storm_onsets array to include the calculation of coefficients before the storm.

  • fill_value (float, default=np.nan) – Value for W outside any identified storms. Default is NaN.

Returns:

W – 6 different \(W_k(t_i)\) for each k (and i).

Return type:

2D ndarray, shape (N, 6)

Notes

Equation (7) in Tsyganenko & Sitnov (2005) can be written (for each k):

\[W_k(t_i) = \frac{r_k}{12} \sum_{j = j_{\mathrm{start}}}^{i} \bigl[ S_k(t_j)\,\exp\bigl(r_k \times (t_j - t_i)\times 24 \bigr)\bigr],\]
Here:

  • \((t_j - t_i)\) is in days,

  • \(r_k\) is provided in \(\mathrm{hr}^{-1}\),

  • The factor \(\times 24\) converts days to hours.

  • \(j_{\mathrm{start}}\) = 0 if summing from the very first sample, or the index of the most recent storm onset (if storm_onsets is provided).