WaveProperties_mod: Cold and Warm Plasma Wave Theory

WaveProperties_mod translates the background environment (field strength, densities, frequencies) into the wave fields and wave numbers that drive particle dynamics. It implements both cold plasma theory and warm plasma corrections, and covers everything from the fundamental Stix parameters to the polarization components of the wave electric and magnetic fields.

import WPIT.WaveProperties_mod as wave

Cold Plasma Theory: Stix Parameters

The Stix representation of the cold magnetoplasma dielectric tensor (Stix, 1992) expresses plasma wave properties through five scalar parameters: R, L, P, S (= (R+L)/2), and D (= (R−L)/2).

`wave.stix_parameters(w, Ne, NH, NHe, NO, B0)`

Computes all five Stix parameters for a multi-species plasma (electrons + H⁺ + He⁺ + O⁺) at wave frequency w and background field B0:

import numpy as np
import WPIT.Environment_mod as env
import WPIT.WaveProperties_mod as wave

L     = 5.0
B     = env.Bmag_dipole(L, 0.0)
ne_eq, _, _ = env.density_equ_sheeley(L)
Ne = ne_eq * 1e6    # cm⁻³ → m⁻³

w  = 2 * np.pi * 2000.0   # 2 kHz in rad/s

S, D, P, R, L_stix = wave.stix_parameters(
    w_arg=w,
    Ne_arg=Ne,
    NH_arg=0.0,    # no H+ in this example
    NHe_arg=0.0,
    NO_arg=0.0,
    B0mag_arg=B
)
print(f"R={R:.4f}  L={L_stix:.4f}  P={P:.4f}  S={S:.4f}  D={D:.4f}")

Inputs: wave frequency w (rad/s), number densities for each species (m⁻³), background field B0mag (T)
Outputs: Sstix, Dstix, Pstix, Rstix, Lstix (dimensionless) Internally the function computes plasma and cyclotron frequencies for each ion species using env.const.

`wave.stix_parameters_warm(S_cold, D_cold, P_cold, Te, Ti, mu_warm, Ke, KH, KHe, KO)`

Warm-plasma corrected Stix parameters. Takes the cold-plasma S, D, P values (from wave.stix_parameters) plus electron temperature Te, ion temperature Ti, the warm-plasma parameter mu_warm, and the species thermal correction factors Ke, KH, KHe, KO. Returns the same five parameters with thermal corrections included in the off-diagonal dielectric tensor components.

`wave.cold_dielectric_tensor(w, wce, wpe, wcH, wpH, wcHe, wpHe, wcO, wpO)`

Assembles the full 3×3 cold-plasma dielectric tensor from the wave frequency and the electron and ion cyclotron/plasma frequencies. Internally computes the Stix R, L, P, S, D parameters and returns the tensor:

K = [ S   -iD   0 ]
    [ iD    S   0 ]
    [ 0     0   P ]

`wave.warm_dielectric_tensor(w, wce, wpe, wcH, wpH, wcHe, wpHe, wcO, wpO, psi)`

Assembles the warm-plasma dielectric tensor. Takes the same frequency parameters as the cold tensor plus the wave normal angle psi (rad) for the warm-plasma corrections.

Refractive Index

`wave.refr_index_appleton(w, wpe, wce, theta)`

Appleton-Hartree formula for an electron-only cold plasma (Appleton, 1932). Fast and widely used for whistler-mode calculations where ion contributions can be neglected:

wce = env.omega_cyclotron(B, env.const.qe, env.const.me)
wpe = env.omega_plasma(Ne, env.const.qe, env.const.me)
theta = np.deg2rad(30.0)    # wave normal angle

musq_plus, musq_minus, ref_ind, kappa, kappa_par, kappa_per = \
    wave.refr_index_appleton(w, wpe, wce, theta)

Outputs:

musq_plus — µ²₊ (plus root of the dispersion relation)
musq_minus — µ²₋ (minus root)
ref_ind — refractive index µ for the propagating (µ² > 0) root
kappa — wave number magnitude (rad/m)
kappa_par — parallel component κ‖ (rad/m)
kappa_per — perpendicular component κ⊥ (rad/m)

`wave.refr_index_full(theta, w, S, P, R, L)`

Full cold-plasma refractive index from the Stix tensor, valid for oblique propagation and multi-species plasmas. Takes the wave normal angle theta (rad), wave frequency w (rad/s), and the four Stix parameters S, P, R, L. Solves the biquadratic dispersion relation.

`wave.refr_index_warm(K_e, K_H, K_He, K_O, psi, Te, Ti, K110, K220, K330, K120, w)`

Refractive index including warm-plasma corrections. Takes the species thermal correction tensors (K_e, K_H, K_He, K_O), wave normal angle psi, electron and ion temperatures, the off-diagonal tensor elements (K110, K220, K330, K120), and the wave frequency w.

`wave.refr_index_parallel_EMIC(w, wpe, wce, wpH, wcH, wpO, wcO, wpHe, wcHe)`

Refractive index for EMIC waves propagating strictly parallel to the background field. Requires the plasma and cyclotron frequencies for electrons and for each ion species (H⁺, O⁺, He⁺). Used internally by parallel_EMIC_mod.

Dispersion Relations

WPIT provides individual dispersion relation functions for the principal magnetoplasma modes. Each returns the squared refractive index µ²:

Function	Signature	Mode	Propagation
`wave.dispersion_R`	`(w, wpe, wce, wpH, wcH, wpHe, wcHe, wpO, wcO)`	R-mode (right-hand circularly polarized)	Parallel
`wave.dispersion_L`	`(w, wpe, wce, wpH, wcH, wpHe, wcHe, wpO, wcO)`	L-mode (left-hand circularly polarized)	Parallel
`wave.dispersion_O`	`(w, wpe, wpH, wpHe, wpO)`	O-mode (ordinary wave)	Perpendicular
`wave.dispersion_X`	`(w, wpe, wlh)`	X-mode (extraordinary wave)	Perpendicular
`wave.dispersion_light`	`(w, wpe, wce)`	Light wave in plasma	Any

All dispersion functions take plasma/cyclotron frequencies for each relevant species rather than pre-computed Stix parameters. Cutoff frequencies (where µ² → 0) are returned by wave.cutoff_R(wce, wpe) and wave.cutoff_L(wce, wpe).

Wave Amplitude Models

Given a wave normal angle and the wave magnetic field amplitude By (in Tesla), WPIT can compute all six polarization components (Bx, By, Bz, Ex, Ey, Ez) of the wave field using three different polarization models.

Bell (1984) Model — `wave.wave_amplitudes_bell(mu, P, D, S, Byw, theta)`

Computes the complete field vector using the cold-plasma eigenmode structure described in Bell (1984), which is the basis of the whistler_electron_mod equations of motion:

S, D, P, R, L_stix = wave.stix_parameters(w, Ne, 0, 0, 0, B)
_, _, mu, _, _, _ = wave.refr_index_appleton(w, wpe, wce, theta)

Byw = 65e-12   # By amplitude in Tesla (65 pT)

Bxw, Byw_out, Bzw, Exw, Eyw, Ezw = \
    wave.wave_amplitudes_bell(mu, P, D, S, Byw, theta)

Li Model — `wave.wave_amplitudes_li(mu, P, D, S, Byw, theta)`

Alternative polarization parameterization.

Jasna Model — `wave.wave_amplitudes_jasna(P, S, D, theta, ref, power)`

Alternative parameterization after Jasna et al. (1992). Instead of a prescribed By amplitude, it takes the wave Poynting flux power (mW/m²) and the refractive index ref, making it more convenient when wave intensity data are given in power units.

Wave Packet Shapes

Wave packets in WPIT are implemented as envelope functions that modulate the wave amplitude as a function of magnetic latitude along the field line. All three functions take the peak wave amplitude Bw0 (T) and the current magnetic latitude lamda (radians) and return the local amplitude Bwave:

Function	Signature	Shape
`wave.wave_packet_gauss`	`(Bw0, lamda, lamda_range)`	Symmetric Gaussian; `lamda_range` is the latitudinal half-width
`wave.wave_packet_one_sided`	`(Bw0, lamda, shape, location, direction)`	Hyperbolic-tangent step; `shape` controls edge sharpness, `location` sets the HWHM latitude, `direction` is `'north'` or `'south'`
`wave.wave_packet_two_sided`	`(Bw0, lamda, shape, location)`	Symmetric two-sided taper using opposing hyperbolic-tangent steps

Why different packet shapes?

Chorus wave elements observed by spacecraft often show asymmetric amplitude envelopes. The one-sided packet models a wave train that is switched on or off at a particular latitude (e.g., a chorus element growing away from the equator in one direction only). The two-sided packet is symmetric about the equator and is appropriate for standing-wave or monochromatic test-wave studies where the packet decays equally in both directions.

Resonance

Resonant Velocity — `wave.resonant_velocity(m_res, w_wave, kz, wce, alpha, m)`

Computes the parallel, perpendicular, and total resonant velocities, the resonant kinetic energy, and the resonant Lorentz factor γ for a particle with pitch angle alpha interacting at cyclotron harmonic m_res:

v_par, v_per, v_tot, E_res, gamma_res = wave.resonant_velocity(
    m_res_arg=-1,            # first harmonic cyclotron resonance
    w_wave_arg=w,
    kz_arg=kappa_par,
    wce_arg=wce,
    alpha_arg=np.deg2rad(68.0),
    m_arg=env.const.me
)
print(f"Resonant energy: {E_res / env.const.qe / 1e3:.1f} keV")

Resonance Angle — `wave.res_angle(P, S)`

The resonance (Storey) cone angle, which sets the maximum wave normal angle for propagation of whistler-mode waves. Takes the Stix P and S parameters (from wave.stix_parameters) and returns the resonance angle in radians: tan²θ_res = −P/S.

Gendrin Angle — `wave.gendrin_angle(w_wave, wlhr, wce)`

The Gendrin angle is the wave normal angle at which the group velocity of a whistler-mode wave is parallel to the background magnetic field (Bortnik et al., 2006):

theta_gen = wave.gendrin_angle(w, wlhr, wce)
print(f"Gendrin angle: {np.rad2deg(theta_gen):.2f}°")

Waves propagating near the Gendrin angle travel along field lines without diverging — a condition that maximises their interaction length with bouncing particles. The function returns nan for frequencies below the lower hybrid resonance, 90° at the lower hybrid resonance, the Gendrin formula for wlhr < w < wce/2, and 0° for wce/2 < w < wce.

The Gendrin angle is used internally by LandauDamp_mod to assess the propagation direction of the wave relative to the background field along the ray path.

Get Started

Concepts

Guides

WaveProperties_mod: Cold and Warm Plasma Wave Theory

Cold Plasma Theory: Stix Parameters

`wave.stix_parameters(w, Ne, NH, NHe, NO, B0)`

`wave.stix_parameters_warm(S_cold, D_cold, P_cold, Te, Ti, mu_warm, Ke, KH, KHe, KO)`

`wave.cold_dielectric_tensor(w, wce, wpe, wcH, wpH, wcHe, wpHe, wcO, wpO)`

`wave.warm_dielectric_tensor(w, wce, wpe, wcH, wpH, wcHe, wpHe, wcO, wpO, psi)`

Refractive Index

`wave.refr_index_appleton(w, wpe, wce, theta)`

`wave.refr_index_full(theta, w, S, P, R, L)`

`wave.refr_index_warm(K_e, K_H, K_He, K_O, psi, Te, Ti, K110, K220, K330, K120, w)`

`wave.refr_index_parallel_EMIC(w, wpe, wce, wpH, wcH, wpO, wcO, wpHe, wcHe)`

Dispersion Relations

Wave Amplitude Models

Bell (1984) Model — `wave.wave_amplitudes_bell(mu, P, D, S, Byw, theta)`

Li Model — `wave.wave_amplitudes_li(mu, P, D, S, Byw, theta)`

Jasna Model — `wave.wave_amplitudes_jasna(P, S, D, theta, ref, power)`

Wave Packet Shapes

Resonance

Resonant Velocity — `wave.resonant_velocity(m_res, w_wave, kz, wce, alpha, m)`

Resonance Angle — `wave.res_angle(P, S)`

Gendrin Angle — `wave.gendrin_angle(w_wave, wlhr, wce)`

Build docs developers (and LLMs) love

Get Started

Concepts

Guides

Documentation Index

​Cold Plasma Theory: Stix Parameters

​wave.stix_parameters(w, Ne, NH, NHe, NO, B0)

​wave.stix_parameters_warm(S_cold, D_cold, P_cold, Te, Ti, mu_warm, Ke, KH, KHe, KO)

​wave.cold_dielectric_tensor(w, wce, wpe, wcH, wpH, wcHe, wpHe, wcO, wpO)

​wave.warm_dielectric_tensor(w, wce, wpe, wcH, wpH, wcHe, wpHe, wcO, wpO, psi)

​Refractive Index

​wave.refr_index_appleton(w, wpe, wce, theta)

​wave.refr_index_full(theta, w, S, P, R, L)

​wave.refr_index_warm(K_e, K_H, K_He, K_O, psi, Te, Ti, K110, K220, K330, K120, w)

​wave.refr_index_parallel_EMIC(w, wpe, wce, wpH, wcH, wpO, wcO, wpHe, wcHe)

​Dispersion Relations

​Wave Amplitude Models

​Bell (1984) Model — wave.wave_amplitudes_bell(mu, P, D, S, Byw, theta)

​Li Model — wave.wave_amplitudes_li(mu, P, D, S, Byw, theta)

​Jasna Model — wave.wave_amplitudes_jasna(P, S, D, theta, ref, power)

​Wave Packet Shapes

​Resonance

​Resonant Velocity — wave.resonant_velocity(m_res, w_wave, kz, wce, alpha, m)

​Resonance Angle — wave.res_angle(P, S)

​Gendrin Angle — wave.gendrin_angle(w_wave, wlhr, wce)

Build docs developers (and LLMs) love

Cold Plasma Theory: Stix Parameters

`wave.stix_parameters(w, Ne, NH, NHe, NO, B0)`

`wave.stix_parameters_warm(S_cold, D_cold, P_cold, Te, Ti, mu_warm, Ke, KH, KHe, KO)`

`wave.cold_dielectric_tensor(w, wce, wpe, wcH, wpH, wcHe, wpHe, wcO, wpO)`

`wave.warm_dielectric_tensor(w, wce, wpe, wcH, wpH, wcHe, wpHe, wcO, wpO, psi)`

Refractive Index

`wave.refr_index_appleton(w, wpe, wce, theta)`

`wave.refr_index_full(theta, w, S, P, R, L)`

`wave.refr_index_warm(K_e, K_H, K_He, K_O, psi, Te, Ti, K110, K220, K330, K120, w)`

`wave.refr_index_parallel_EMIC(w, wpe, wce, wpH, wcH, wpO, wcO, wpHe, wcHe)`

Dispersion Relations

Wave Amplitude Models

Bell (1984) Model — `wave.wave_amplitudes_bell(mu, P, D, S, Byw, theta)`

Li Model — `wave.wave_amplitudes_li(mu, P, D, S, Byw, theta)`

Jasna Model — `wave.wave_amplitudes_jasna(P, S, D, theta, ref, power)`

Wave Packet Shapes

Resonance

Resonant Velocity — `wave.resonant_velocity(m_res, w_wave, kz, wce, alpha, m)`

Resonance Angle — `wave.res_angle(P, S)`

Gendrin Angle — `wave.gendrin_angle(w_wave, wlhr, wce)`