Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/stourgai/WPIT/llms.txt

Use this file to discover all available pages before exploring further.

The refractive-index functions in WaveProperties_mod convert plasma parameters and wave geometry into the electromagnetic phase and group velocities needed for ray tracing and wave–particle interaction calculations. Four approaches are available: the classic two-fluid Appleton-Hartree formula; the complete cold-plasma Stix formalism via refr_index_full; a warm-plasma cubic-root solver in refr_index_warm; and a parallel-propagation specialisation for EMIC waves in refr_index_parallel_EMIC. All functions except refr_index_parallel_EMIC return the refractive index η together with the full and component wave numbers κ, κ‖, and κ⊥. 
import WPIT.WaveProperties_mod as wave

​
refr_index_appleton

Implements the Appleton-Hartree dispersion formula for a two-component (electron + background ions) magnetised plasma. Returns both roots (plus and minus) of the quadratic dispersion equation; physically the two roots correspond to the ordinary (O) and extra-ordinary (X) modes for transverse propagation, or to the R and L modes for parallel propagation. Reference: Appleton, E. V. (1932). Wireless studies of the ionosphere. Proceedings of the Wireless Section of the IEE 7, 257–265. 
eta_sq_plus, eta_sq_minus, ref_ind, kappa, kappa_par, kappa_per = \
    wave.refr_index_appleton(w_arg, wpe_arg, wce_arg, theta_arg)

​
Parameters

​
w_arg
float
required
Wave angular frequency [rad s⁻¹].
​
wpe_arg
float
required
Electron plasma angular frequency [rad s⁻¹].
​
wce_arg
float
required
Electron cyclotron angular frequency [rad s⁻¹].
​
theta_arg
float
required
Wave normal angle θ with respect to the background magnetic field B₀ [rad]. 0 corresponds to parallel propagation; π/2 to perpendicular propagation.

​
Returns

​
eta_sq_plus
float
The plus root of the Appleton-Hartree equation. At θ = 0 this corresponds to the R-mode (right-hand circularly polarised).
​
eta_sq_minus
float
The minus root. At θ = 0 this corresponds to the L-mode (left-hand circularly polarised). At θ = π/2 the two roots map to the O and X modes.
​
ref_ind
float
Refractive index η = sqrt(eta_sq_plus) if eta_sq_plus is positive, else sqrt(eta_sq_minus). Selects the first positive-definite root (dimensionless).
​
kappa
float
Total wave number κ = η ω / c [m⁻¹].
​
kappa_par
float
Field-aligned (parallel) wave number κ‖ = κ cos θ [m⁻¹].
​
kappa_per
float
Perpendicular wave number κ⊥ = κ sin θ [m⁻¹].

​
Example

import WPIT.WaveProperties_mod as wave
import numpy as np

w     = 2 * np.pi * 5e3        # 5 kHz whistler
wpe   = 2 * np.pi * 1.0e5
wce   = 2 * np.pi * 1.4e6
theta = np.deg2rad(20)          # 20° wave normal angle

eta_p, eta_m, eta, kappa, kpar, kperp = \
    wave.refr_index_appleton(w, wpe, wce, theta)

print(f"eta^2+ = {eta_p:.2f},  eta^2- = {eta_m:.2f}")
print(f"eta = {eta:.4f},  kappa = {kappa:.4e} m^-1")
print(f"k_par = {kpar:.4e} m^-1,  k_perp = {kperp:.4e} m^-1")
The Appleton-Hartree formula assumes a single electron species against a stationary ion background and neglects ion dynamics entirely. For frequencies near or below the ion cyclotron frequency, use refr_index_full (multi-species Stix) or refr_index_parallel_EMIC instead.

​
refr_index_full

Computes the refractive index from the full cold-plasma Stix dispersion relation using precomputed S, P, R, and L parameters. This formulation correctly accounts for all four species (e⁻, H⁺, He⁺, O⁺) and is valid across the entire frequency range from DC to above the electron plasma frequency. The quadratic coefficients A, B, C in η⁴ involve the wave normal angle θ explicitly. Reference: Kimura, I. (1966). Effects of ions on whistler-mode ray tracing. Radio Science 1, 269–283. 
eta_sq_plus, eta_sq_minus, ref_ind, kappa, kappa_par, kappa_per = \
    wave.refr_index_full(theta_arg, w_wave_arg, S_arg, P_arg, R_arg, L_arg)

​
Parameters

​
theta_arg
float
required
Wave normal angle θ with respect to B₀ [rad].
​
w_wave_arg
float
required
Wave angular frequency [rad s⁻¹].
​
S_arg
float
required
Stix S parameter (from stix_parameters or stix_parameters_warm).
​
P_arg
float
required
Stix P parameter.
​
R_arg
float
required
Stix R parameter.
​
L_arg
float
required
Stix L parameter.

​
Returns

​
eta_sq_plus
float
Larger root — (B + F) / (2A) of the Stix biquadratic, where F = sqrt(B² − 4AC) and A, B, C are angle-dependent coefficients built from S, P, R, L.
​
eta_sq_minus
float
Smaller root — (B − F) / (2A). For whistler-mode waves this is typically the physical root (slow mode); the larger root corresponds to the fast/light branch.
​
ref_ind
float
Refractive index η = sqrt(eta_sq_minus) (always uses the minus root). Dimensionless.
​
kappa
float
Total wave number κ [m⁻¹].
​
kappa_par
float
Field-aligned wave number κ‖ = κ cos θ [m⁻¹].
​
kappa_per
float
Perpendicular wave number κ⊥ = κ sin θ [m⁻¹].

​
Example

import WPIT.WaveProperties_mod as wave
import numpy as np

w     = 2 * np.pi * 5e3
Ne    = 1e7
B0    = 3e-5

S, D, P, R, L = wave.stix_parameters(w, Ne, 0.9e7, 0.05e7, 0.05e7, B0)

theta = np.deg2rad(30)
eta_p, eta_m, eta, kappa, kpar, kperp = \
    wave.refr_index_full(theta, w, S, P, R, L)

print(f"Full cold-plasma: eta = {eta:.4f},  kappa_par = {kpar:.4e} m^-1")
The minus root is hardcoded in refr_index_full to select the whistler/slow branch. If you need the fast branch, extract it directly from the eta_sq_plus return value.

​
refr_index_warm

Solves the warm-plasma dispersion relation — a cubic polynomial in η² — for the physical (positive, real) root. Warm corrections introduce finite-temperature effects via the dimensionless thermal ratio τₛ = (k_B Tₛ) / (mₛ c²) × η² for each species. The cubic is assembled from cold tensor components K110, K220, K330, K120 and the warm correction arrays returned by warm_dielectric_tensor. Reference: Kulkarni, P., Gołkowski, M., Inan, U., and Bell, T. (2015). JGR: Space Physics 120, 581–591. 
ref_ind, kappa, kappa_par, kappa_per = wave.refr_index_warm(
    K_e, K_H, K_He, K_O, psi_arg, Te, Ti, K110, K220, K330, K120, w_wave_arg
)

​
Parameters

​
K_e
list[complex]
required
9-element list of electron warm dielectric tensor components (from warm_dielectric_tensor).
​
K_H
list[complex]
required
9-element list of H⁺ warm dielectric tensor components.
​
K_He
list[complex]
required
9-element list of He⁺ warm dielectric tensor components.
​
K_O
list[complex]
required
9-element list of O⁺ warm dielectric tensor components.
​
psi_arg
float
required
Wave normal angle ψ with respect to B₀ [rad].
​
Te
float
required
Electron temperature [eV].
​
Ti
float
required
Ion temperature [eV] (applied uniformly to all ion species).
​
K110
complex
required
K11 component of the cold dielectric tensor (from cold_dielectric_tensor).
​
K220
complex
required
K22 component of the cold dielectric tensor. Equal to K11 for a cold plasma.
​
K330
complex
required
K33 component of the cold dielectric tensor.
​
K120
complex
required
K12 component of the cold dielectric tensor (purely imaginary).
​
w_wave_arg
float
required
Wave angular frequency [rad s⁻¹].

​
Returns

​
ref_ind
float
Warm-plasma refractive index η (real part of the positive root) (dimensionless).
​
kappa
float
Total wave number κ = η ω / c [m⁻¹].
​
kappa_par
float
Field-aligned wave number κ‖ = κ cos ψ [m⁻¹].
​
kappa_per
float
Perpendicular wave number κ⊥ = κ sin ψ [m⁻¹].

​
Example

import WPIT.WaveProperties_mod as wave
import numpy as np

w     = 2 * np.pi * 5e3
psi   = np.deg2rad(20)
Te, Ti = 1.0, 0.5               # eV

# Compute cold tensor first
K11, K12, K13, K21, K22, K23, K31, K32, K33 = wave.cold_dielectric_tensor(
    w, wce, wpe, wcH, wpH, wcHe, wpHe, wcO, wpO
)
# Compute warm tensor corrections
K_e, K_H, K_He, K_O = wave.warm_dielectric_tensor(
    w, wce, wpe, wcH, wpH, wcHe, wpHe, wcO, wpO, psi
)

eta_w, kappa_w, kpar_w, kperp_w = wave.refr_index_warm(
    K_e, K_H, K_He, K_O, psi, Te, Ti, K11, K22, K33, K12, w
)
print(f"Warm eta = {eta_w:.4f}")
The solver uses numpy.roots on the cubic and returns the first positive-real root. In strongly anisotropic conditions near a resonance there may be multiple positive roots; inspect eta_sq_plus / eta_sq_minus from refr_index_full to verify the physical branch.

​
refr_index_parallel_EMIC

Computes the squared refractive index for parallel-propagating electromagnetic ion cyclotron (EMIC) waves in a multi-species cold plasma. The function evaluates the L-mode dispersion relation relevant for EMIC wave propagation studies, where the wave is left-hand polarised at the frequency of the ions. Returns η² directly (not η). Reference: Summers, D. and Thorne, R. M. (2003). Relativistic electron pitch-angle scattering by electromagnetic ion cyclotron waves during geomagnetic storms. JGR: Space Physics 108. 
eta_sq = wave.refr_index_parallel_EMIC(
    wmega_wave, wpe, wce, wpH, wcH, wpO, wcO, wpHe, wcHe
)

​
Parameters

​
wmega_wave
float
required
Wave angular frequency [rad s⁻¹].
​
wpe
float
required
Electron plasma angular frequency [rad s⁻¹].
​
wce
float
required
Electron cyclotron angular frequency [rad s⁻¹].
​
wpH
float
required
H⁺ plasma angular frequency [rad s⁻¹].
​
wcH
float
required
H⁺ cyclotron angular frequency [rad s⁻¹].
​
wpO
float
required
O⁺ plasma angular frequency [rad s⁻¹]. Pass 0 to exclude O⁺.
​
wcO
float
required
O⁺ cyclotron angular frequency [rad s⁻¹]. Pass 0 to exclude O⁺.
​
wpHe
float
required
He⁺ plasma angular frequency [rad s⁻¹]. Pass 0 to exclude He⁺.
​
wcHe
float
required
He⁺ cyclotron angular frequency [rad s⁻¹]. Pass 0 to exclude He⁺.

​
Returns

​
R_tmp
float
Squared refractive index η² for the parallel L-mode EMIC wave (dimensionless). A positive value indicates propagation; a negative value indicates evanescence between the L-cutoff and an ion cyclotron frequency.

​
Example

import WPIT.WaveProperties_mod as wave
import numpy as np

# Parameters for H+ EMIC wave below H+ cyclotron frequency
B0  = 4e-8                          # 40 nT
wcH = 1.609e-19 * B0 / 1.673e-27   # H+ cyclotron frequency
wcHe = wcH / 4.0
wcO  = wcH / 16.0
wce  = 1.609e-19 * B0 / 9.109e-31  # electron cyclotron frequency

Ne   = 1e6                          # m^-3
eps0 = 8.854e-12
wpe  = np.sqrt(Ne * (1.609e-19)**2 / (9.109e-31 * eps0))
wpH  = wpe / np.sqrt(1836.0)

w_emic = 0.8 * wcH                  # 80% of H+ cyclotron freq

eta_sq = wave.refr_index_parallel_EMIC(
    w_emic, wpe, wce, wpH, wcH, 0, 0, 0, 0
)
print(f"EMIC parallel eta^2 = {eta_sq:.2f}")
This function returns η² (not η). The EMIC L-mode branch becomes evanescent when the wave frequency approaches wcH, wcHe, or wcO from below — the denominator factors change sign, making η² negative. Guard against this with a frequency range check before calling the function.

Build docs developers (and LLMs) love

Get started for freeTalk to us