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 resonance functions in WaveProperties_mod characterise the geometric and kinematic conditions under which energetic charged particles interact resonantly with electromagnetic waves in the magnetosphere. resonant_velocity solves the relativistic resonance condition for the parallel velocity and energy of a particle interacting with a wave at harmonic number m; res_angle finds the wave normal angle at which the refractive index surface has a conical singularity (resonance cone); and gendrin_angle identifies the wave normal angle that maximises the field-aligned component of the group velocity — a key quantity for chorus-wave duct tracing and Landau-damping studies. 
import WPIT.WaveProperties_mod as wave

​
resonant_velocity

Computes the relativistic cyclotron-resonance parallel velocity, perpendicular velocity, total velocity, resonant kinetic energy, and Lorentz factor for a particle interacting with an electromagnetic wave at resonance harmonic number m. The resonance condition is ω − k‖ v‖ − m ωc / γ = 0, which is solved relativistically for v‖ via the quadratic formula implemented in the source. Reference: Sousa, A. P. (2018). Global and Seasonal Effects of Lightning-Induced Electron Precipitation. Stanford University (PhD thesis). 
v_para, v_perp, v_tot, E_res, gamma = wave.resonant_velocity(
    m_res_arg, w_wave_arg, kz_arg, wce_arg, alpha_arg, m_arg
)

​
Parameters

​
m_res_arg
int
required
Resonance harmonic number m. Use m = 0 for Landau (transit-time) resonance, m = 1 for the fundamental cyclotron resonance, m = −1 for the anomalous cyclotron resonance, and |m| > 1 for higher harmonics.
​
w_wave_arg
float
required
Wave angular frequency [rad s⁻¹].
​
kz_arg
float
required
z-component of the wave number (field-aligned component) κ‖ [m⁻¹]. Obtain from refr_index_full, refr_index_appleton, or refr_index_warm as kappa_par.
​
wce_arg
float
required
Electron cyclotron angular frequency [rad s⁻¹]. For ion resonances, pass the appropriate ion cyclotron frequency.
​
alpha_arg
float
required
Local particle pitch angle α [rad]. The pitch angle defines the ratio v_perp / v = sin α and is used to project the total resonant velocity onto the field-aligned and perpendicular directions.
​
m_arg
float
required
Rest mass of the resonant particle [kg]. Use WPIT.Environment_mod.const.me for electrons or the appropriate ion mass constant.

​
Returns

​
v_para_res
float
Parallel (field-aligned) resonant velocity v‖ [m s⁻¹]. For Landau resonance (m = 0) the sign is set to oppose the wave phase velocity direction.
​
v_per_res
float
Perpendicular resonant velocity v_perp = v_tot × sin α [m s⁻¹].
​
v_tot_res
float
Total resonant velocity v = v‖ / cos α [m s⁻¹].
​
E_res
float
Resonant kinetic energy E = (γ − 1) m c² [J].
​
gamma_res
float
Relativistic Lorentz factor γ = 1 / sqrt(1 − v²/c²) (dimensionless). γ = 1 for a non-relativistic particle; γ greater than 1 for a relativistic particle.

​
Example

import WPIT.WaveProperties_mod as wave
from WPIT.Environment_mod import const
import numpy as np

# 5 kHz whistler, 20° wave normal angle
w      = 2 * np.pi * 5e3
B0     = 3e-5
S, D, P, R, L = wave.stix_parameters(w, 1e7, 0.9e7, 0.05e7, 0.05e7, B0)
theta  = np.deg2rad(20)
_, _, eta, kappa, kpar, kperp = wave.refr_index_full(theta, w, S, P, R, L)

wce    = const.qe * B0 / const.me
alpha  = np.deg2rad(60)            # 60° pitch angle

# Fundamental cyclotron resonance (m = 1)
v_par, v_perp, v_tot, E_res, gamma = wave.resonant_velocity(
    1, w, kpar, wce, alpha, const.me
)

E_keV = E_res / (1e3 * const.qe)   # convert J -> keV
print(f"v_para = {v_par/const.c_light:.4f} c")
print(f"Resonant energy = {E_keV:.2f} keV,  gamma = {gamma:.4f}")

# Landau resonance (m = 0)
v_par0, v_perp0, v_tot0, E_res0, gamma0 = wave.resonant_velocity(
    0, w, kpar, wce, alpha, const.me
)
print(f"Landau v_para = {v_par0/const.c_light:.4f} c")
For m_res_arg = 0 (Landau resonance) the function sets direction to −sign(k‖) so that the resonant particle moves in the same direction as the wave. For m not equal to 0 the direction is sign(k‖) × sign(m), correctly distinguishing co- and counter-streaming resonances. Ensure kz_arg carries the correct sign (positive = northward propagation).

​
res_angle

Computes the resonance cone angle — the wave normal angle at which the refractive index surface of a cold plasma diverges (η² → ∞). At this angle wave energy is deposited at the plasma resonance. For whistler-mode waves, the resonance cone limits the obliqueness of propagation paths. Reference: Stix, T. H. (1992). Waves in Plasmas. Springer Science & Business Media. 
theta_res = wave.res_angle(P_arg, S_arg)

​
Parameters

​
P_arg
float
required
Stix P parameter (from stix_parameters). P encodes the field-parallel dielectric response and equals 1 − Σ ωₚₛ²/ω².
​
S_arg
float
required
Stix S parameter. S = (R + L)/2 encodes the average transverse response.

​
Returns

​
thetares
float
Resonance cone half-angle [rad]. Defined by tan²(θ_res) = −P / S. Valid only when P/S is negative (i.e., P and S have opposite signs), which is the condition for the existence of a resonance cone in the cold-plasma model.

​
Example

import WPIT.WaveProperties_mod as wave
import numpy as np

w  = 2 * np.pi * 5e3
S, D, P, R, L = wave.stix_parameters(w, 1e7, 0.9e7, 0.05e7, 0.05e7, 3e-5)

theta_res = wave.res_angle(P, S)
print(f"Resonance cone angle = {np.rad2deg(theta_res):.2f} degrees")
The expression tan²(θ_res) = −P/S requires −P/S to be positive, i.e., P and S must have opposite signs. At frequencies below the lower hybrid resonance, P is negative and S is positive for whistler-mode waves, so the resonance cone is well-defined. If P/S is non-negative the function will raise a ValueError from np.sqrt of a negative number; check the sign of P and S before calling.

​
gendrin_angle

Computes the Gendrin angle — the wave normal angle at which the group velocity vector is directed exactly along the background magnetic field B₀. At this angle the wave energy propagates purely field-aligned regardless of the wave normal direction, making it a natural duct for chorus wave generation and propagation. The Gendrin angle exists only in the frequency band wlhr less than ω less than wce/2. Reference: Bortnik, J., Inan, U. S., and Bell, T. F. (2006). Landau damping and resultant unidirectional propagation of chorus waves. Geophysical Research Letters 33. 
theta_gendrin = wave.gendrin_angle(w_wave_arg, wlhr_arg, wce_arg)

​
Parameters

​
w_wave_arg
float
required
Wave angular frequency [rad s⁻¹].
​
wlhr_arg
float
required
Lower hybrid resonance angular frequency [rad s⁻¹]. Approximately sqrt(wce × wcH) for an electron–proton plasma.
​
wce_arg
float
required
Electron cyclotron angular frequency [rad s⁻¹].

​
Returns

​
th_gen
float
Gendrin angle [rad]. In the valid range (wlhr less than ω less than 0.5 × wce) the formula is arccos(2 * (ω² − ω_lhr²) / (ω × ωce)). Outside the valid range the function returns:
  • np.nan if ω is less than wlhr (wave below lower hybrid; no Gendrin angle exists)
  • π/2 (90°) if ω equals wlhr
  • 0 if 0.5 × wce is less than ω less than wce

​
Example

import WPIT.WaveProperties_mod as wave
import numpy as np

B0  = 3e-5
wce = 1.609e-19 * B0 / 9.109e-31      # electron cyclotron frequency
wcH = wce / 1836.0                     # H+ cyclotron
wlh = np.sqrt(wce * wcH)              # lower hybrid resonance

# Sweep frequency from wlh to wce/2
freqs = np.linspace(wlh * 1.01, 0.49 * wce, 300)

gendrin_angles_deg = np.array([
    np.rad2deg(wave.gendrin_angle(w, wlh, wce))
    for w in freqs
])

import matplotlib.pyplot as plt
plt.plot(freqs / wce, gendrin_angles_deg)
plt.xlabel("ω / ωce")
plt.ylabel("Gendrin angle (°)")
plt.title("Gendrin angle vs normalised wave frequency")
plt.show()
The Gendrin angle is a key parameter in chorus-wave formation models. Below the lower hybrid frequency, EMIC waves do not have a Gendrin angle and this function returns np.nan. Code that iterates over a frequency array should guard against np.nan values before plotting or using the result in further calculations.

Build docs developers (and LLMs) love

Get started for freeTalk to us