TheDocumentation 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.
whistler_electron_mod sub-module implements the relativistic equations of motion for a single electron interacting with an obliquely propagating whistler-mode wave in a dipole magnetic field. It follows the formulation of Bortnik’s thesis (equations 2.25a–h) and expresses all coupling through left- and right-hand polarised wave components. The time-derivative functions are designed to be called once per integrator step after wpi_params has pre-computed the resonance-order-dependent coupling terms.
wpi_params
Computes derived wave–particle coupling parameters needed by all time-derivative functions. Must be called once per integration step before evaluating any d*/dt function.
Resonance harmonic order m. Use
m = 1 for the fundamental cyclotron resonance, m = 0 for Landau resonance, negative integers for higher-order harmonics.Electron momentum component parallel to the background magnetic field B₀, in kg m s⁻¹.
Electron momentum component perpendicular to B₀, in kg m s⁻¹.
x-component of the wave magnetic field amplitude, in T.
y-component of the wave magnetic field amplitude, in T.
x-component of the wave electric field amplitude, in V m⁻¹.
y-component of the wave electric field amplitude, in V m⁻¹.
z-component (field-aligned) of the wave electric field amplitude, in V m⁻¹.
Parallel (field-aligned) wave number component, in rad m⁻¹.
Perpendicular wave number component, in rad m⁻¹.
Unsigned electron gyrofrequency |Ω_e|, in rad s⁻¹.
(gamma, w1, w2, wtau_sq, R1, R2, beta)
Relativistic Lorentz factor γ = √(1 + |p|² / (m_e c)²).
Right-hand trapping frequency amplitude ω₁ = (q_e / 2m_e)(B_xw + B_yw), in rad s⁻¹.
Left-hand trapping frequency amplitude ω₂ = (q_e / 2m_e)(B_xw − B_yw), in rad s⁻¹.
Squared trapping frequency ω²_τm for harmonic m (Bortnik eq. 2.25c), in rad² s⁻².
Polarisation ratio R₁ = (E_xw + E_yw) / (B_xw + B_yw), units V T⁻¹ (equivalent to m s⁻¹).
Polarisation ratio R₂ = (E_xw − E_yw) / (B_xw − B_yw), units m s⁻¹.
Perpendicular gyro-phase argument β = k_x p_⊥ / (m_e γ Ω_e), dimensionless. Used as the argument of Bessel functions J_n(β).
dzdt
Rate of change of the field-aligned particle position z.
Parallel momentum, in kg m s⁻¹.
Lorentz factor (from
wpi_params).Particle mass, in kg. For electrons use
WPIT.Environment_mod.const.me.dz/dt = p_∥ / (γ m), the field-aligned velocity component, in m s⁻¹.
dlamdadt
Rate of change of magnetic latitude λ along a dipole field line.
Parallel momentum, in kg m s⁻¹.
Current magnetic latitude λ, in radians.
Lorentz factor.
McIlwain L-shell parameter (dimensionless Earth radii).
dλ/dt in rad s⁻¹. The electron mass
const.me and Earth radius const.Re are used internally.dppardt
Rate of change of the parallel momentum component.
Perpendicular momentum, in kg m s⁻¹.
Wave–particle resonance phase angle η, in radians.
Squared trapping frequency ω²_τm (from
wpi_params), in rad² s⁻².Parallel wave number, in rad m⁻¹.
Lorentz factor.
Electron gyrofrequency, in rad s⁻¹.
Spatial gradient of the gyrofrequency along the field line dΩ_e/ds, in rad s⁻¹ m⁻¹.
dp_∥/dt in kg m s⁻². Contains a wave-interaction term proportional to sin(η) and an adiabatic mirror-force term.
dpperdt
Rate of change of the perpendicular momentum component.
Parallel momentum, in kg m s⁻¹.
Perpendicular momentum, in kg m s⁻¹.
Resonance phase angle, in radians.
Right-hand trapping amplitude ω₁ (from
wpi_params), in rad s⁻¹.Left-hand trapping amplitude ω₂ (from
wpi_params), in rad s⁻¹.Gyro-phase argument β (from
wpi_params), dimensionless.Lorentz factor.
Polarisation ratio R₁ (from
wpi_params).Polarisation ratio R₂ (from
wpi_params).Resonance harmonic order m.
Electron gyrofrequency, in rad s⁻¹.
Gradient of gyrofrequency along field line, in rad s⁻¹ m⁻¹.
dp_⊥/dt in kg m s⁻². Bessel functions J_(m±1)(β) appear explicitly.
dEkdt
Rate of change of the relativistic kinetic energy.
Perpendicular momentum, in kg m s⁻¹.
Parallel momentum, in kg m s⁻¹.
Resonance phase angle, in radians.
Resonance harmonic order m.
x-component of wave electric field, in V m⁻¹.
y-component of wave electric field, in V m⁻¹.
z-component of wave electric field, in V m⁻¹.
Gyro-phase argument β, dimensionless.
Lorentz factor.
dE_k/dt in J s⁻¹ (watts). Combines contributions from the field-aligned, left-hand, and right-hand electric field components weighted by Bessel functions J_m, J_(m+1), J_(m-1).
dgammadt
Rate of change of the relativistic Lorentz factor γ.
dEkdt. Internally the result equals dE_k/dt divided by m_e c².
Perpendicular momentum, in kg m s⁻¹.
Parallel momentum, in kg m s⁻¹.
Resonance phase angle, in radians.
Resonance harmonic order m.
x-component of wave electric field, in V m⁻¹.
y-component of wave electric field, in V m⁻¹.
z-component of wave electric field, in V m⁻¹.
Gyro-phase argument β, dimensionless.
Lorentz factor.
dγ/dt in s⁻¹.
dalphadt
Rate of change of the local pitch angle α.
Perpendicular momentum, in kg m s⁻¹.
Parallel momentum, in kg m s⁻¹.
Resonance phase angle, in radians.
Right-hand trapping amplitude ω₁, in rad s⁻¹.
Left-hand trapping amplitude ω₂, in rad s⁻¹.
Polarisation ratio R₁.
Polarisation ratio R₂.
Squared trapping frequency ω²_τm, in rad² s⁻².
Parallel wave number, in rad m⁻¹.
Gyro-phase argument β, dimensionless.
Resonance harmonic order m.
Lorentz factor.
Electron gyrofrequency, in rad s⁻¹.
Gradient of gyrofrequency along the field line dΩ_e/ds, in rad s⁻¹ m⁻¹.
dα/dt in rad s⁻¹. Derived from
dppardt and dpperdt using the chain rule on the pitch angle definition.daeqdt
Rate of change of the equatorial pitch angle α_eq.
Parallel momentum, in kg m s⁻¹.
Perpendicular momentum, in kg m s⁻¹.
Local pitch angle α, in radians.
Equatorial pitch angle α_eq, in radians.
Resonance phase angle η, in radians.
Right-hand trapping amplitude ω₁, in rad s⁻¹.
Polarisation ratio R₁.
Left-hand trapping amplitude ω₂, in rad s⁻¹.
Polarisation ratio R₂.
Lorentz factor.
Gyro-phase argument β, dimensionless.
Squared trapping frequency ω²_τm, in rad² s⁻².
Parallel wave number, in rad m⁻¹.
Resonance harmonic order m.
dα_eq/dt in rad s⁻¹. The equatorial pitch angle is related to the local pitch angle through the mirror ratio; this function encodes that mapping’s time derivative.
detadt
Rate of change of the wave–particle resonance phase angle η.
Parallel momentum, in kg m s⁻¹.
Resonance harmonic order m.
Electron gyrofrequency Ω_e, in rad s⁻¹.
Wave angular frequency ω, in rad s⁻¹.
Lorentz factor.
Parallel wave number k_z, in rad m⁻¹.
dη/dt = (m Ω_e / γ) − ω − k_z p_∥ / (m_e γ), in rad s⁻¹. When this quantity is zero the particle satisfies the resonance condition exactly.
nonlinear_C0
Computes the C₀ coefficient that appears in the phase-angle (θ) inhomogeneity equation for the field-aligned electric field component.
Parallel momentum, in kg m s⁻¹.
Resonance harmonic order m.
Electron gyrofrequency, in rad s⁻¹.
Parallel wave number, in rad m⁻¹.
Lorentz factor.
z-component of wave electric field, in V m⁻¹.
C₀ coefficient, in rad s⁻². Encodes the contribution of E_z to the inhomogeneity of the trapping potential.
nonlinear_C1m
Computes the C₁⁻ coefficient related to the right-hand circularly polarised electric field component E_wR.
Perpendicular momentum, in kg m s⁻¹.
Parallel momentum, in kg m s⁻¹.
Right-hand trapping amplitude ω₁, in rad s⁻¹.
x-component of wave electric field, in V m⁻¹.
y-component of wave electric field, in V m⁻¹.
Resonance harmonic order m.
Electron gyrofrequency, in rad s⁻¹.
Parallel wave number, in rad m⁻¹.
Lorentz factor.
C₁⁻ coefficient, in rad s⁻².
nonlinear_C1p
Computes the C₁⁺ coefficient related to the left-hand circularly polarised electric field component E_wL.
Perpendicular momentum, in kg m s⁻¹.
Parallel momentum, in kg m s⁻¹.
Left-hand trapping amplitude ω₂, in rad s⁻¹.
x-component of wave electric field, in V m⁻¹.
y-component of wave electric field, in V m⁻¹.
Resonance harmonic order m.
Electron gyrofrequency, in rad s⁻¹.
Parallel wave number, in rad m⁻¹.
Lorentz factor.
C₁⁺ coefficient, in rad s⁻².
nonlinear_H
Computes the nonlinear trapping potential inhomogeneity parameter H, which measures how quickly the resonance condition drifts due to changes in k_∥, Ω_e, and the wave frequency.
Perpendicular momentum, in kg m s⁻¹.
Parallel momentum, in kg m s⁻¹.
Parallel wave number k_∥, in rad m⁻¹.
Lorentz factor.
Resonance harmonic order m.
Particle mass, in kg.
Gyrofrequency Ω_e, in rad s⁻¹.
Time derivative of parallel wave number dk_∥/dt, in rad m⁻¹ s⁻¹.
Spatial gradient of gyrofrequency dΩ_e/dz, in rad s⁻¹ m⁻¹.
Time derivative of wave frequency dω/dt, in rad s⁻².
H parameter in rad s⁻². Used to form the nonlinear S parameter via S = H / ω²_τ.
nonlinear_S
Computes the dimensionless nonlinear S parameter (degree of nonlinearity). Values |S| ≪ 1 indicate the particle is deeply trapped; |S| > 1 indicates quasi-linear (untrapped) scattering.
Inhomogeneity parameter H (from
nonlinear_H), in rad s⁻².Squared trapping frequency ω²_τ, in rad² s⁻². Use the absolute value returned by
nonlinear_theta.S = H / ω²_τ, dimensionless.
nonlinear_theta
Computes the effective trapping frequency squared ω²_τ from the C coefficients and Bessel functions. Returns both the signed quantity θ and its absolute value.
C₀ coefficient (from
nonlinear_C0), in rad s⁻².C₁⁺ coefficient (from
nonlinear_C1p), in rad s⁻².C₁⁻ coefficient (from
nonlinear_C1m), in rad s⁻².Resonance harmonic order m.
Gyro-phase argument β (from
wpi_params), dimensionless.Signed trapping frequency squared θ = C₀ J_m(β) + C₁⁺ J_(m+1)(β) + C₁⁻ J_(m-1)(β), in rad s⁻².
|θ|, the absolute value used as ω²_τ in
nonlinear_S. In rad² s⁻².Complete simulation step example
The snippet below shows one full Runge–Kutta step for an electron at the first cyclotron resonance with a whistler wave.The
dkpar_dt argument of nonlinear_H represents the convective derivative of k_∥ along the ray path, not simply dk/dt. If ray-tracing is not performed simultaneously, this can be approximated as zero for a monochromatic CW wave.