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.
parallel_EMIC_mod sub-module implements the relativistic equations of motion for a single ion interacting with a parallel-propagating Electromagnetic Ion Cyclotron (EMIC) wave, where the wave normal angle is exactly zero. Because the wave propagates purely along the background magnetic field B₀, there is no perpendicular wave vector component, the Bessel function argument beta vanishes identically, and the coupling reduces to a simpler form involving only the wave magnetic field amplitude and a phase velocity term. This makes the module computationally lighter than EMIC_ion_mod and appropriate for simulations that assume field-aligned propagation. The nonlinear trapping functions in this module also use a different formulation for nonlinear_theta — one that directly involves Bw rather than Bessel-weighted electric field components — reflecting the simplified dispersion geometry.
Unlike
EMIC_ion_mod, this module does not export wpi_params, dkpardt, or dwcdt, and it does not export nonlinear_C0, nonlinear_C1m, or nonlinear_C1p. The parallel geometry removes the need for Bessel-based coupling coefficients. nonlinear_theta uses a different signature here — it takes Bw, kappa, momenta, and particle properties rather than precomputed C coefficients.dzdt
Returns the time rate of change of the field-line distance coordinate.
Ion momentum component parallel to B₀, in kg m s⁻¹.
Relativistic Lorentz factor (dimensionless).
Ion rest mass, in kg.
Time derivative of the field-line coordinate
dz/dt = ppar / (gamma * mi), in m s⁻¹.dlamdadt
Returns the time rate of change of the magnetic latitude, accounting for dipole-field geometry via the sqrt(1 + 3*sin^2(lambda)) * cos(lambda) metric factor.
Parallel ion momentum, in kg m s⁻¹.
Magnetic latitude lambda, in radians.
Lorentz factor (dimensionless).
Ion rest mass, in kg.
Magnetic L-shell value (dimensionless).
Time derivative of the magnetic latitude, in rad s⁻¹.
dppardt
Returns the time rate of change of the parallel momentum. For parallel propagation the wave coupling enters through the wave magnetic field Bw directly rather than through decomposed left/right components.
Perpendicular momentum, in kg m s⁻¹.
Wave–particle phase angle, in radians.
Ion cyclotron frequency, in rad s⁻¹.
Wave magnetic field amplitude, in T.
Lorentz factor (dimensionless).
Spatial derivative of the cyclotron frequency along the field line, in rad m⁻¹ s⁻¹.
Ion charge, in Coulombs.
Ion rest mass, in kg.
Time derivative of the parallel momentum
dppar/dt, in kg m s⁻².dpperdt
Returns the time rate of change of the perpendicular momentum. The wave term involves the difference between the particle’s parallel velocity and the wave phase velocity w/k.
Parallel momentum, in kg m s⁻¹.
Perpendicular momentum, in kg m s⁻¹.
Wave–particle phase angle, in radians.
Wave magnetic field amplitude, in T.
Lorentz factor (dimensionless).
Wave angular frequency, in rad s⁻¹.
Parallel wave number, in rad m⁻¹.
Ion cyclotron frequency, in rad s⁻¹.
Spatial derivative of the cyclotron frequency along the field line, in rad m⁻¹ s⁻¹.
Ion charge, in Coulombs.
Ion rest mass, in kg.
Time derivative of the perpendicular momentum
dpper/dt, in kg m s⁻².dEkdt
Returns the time rate of change of the relativistic kinetic energy. For parallel EMIC waves the energy exchange rate depends on the phase velocity w/kappa and the perpendicular momentum.
Perpendicular momentum, in kg m s⁻¹.
Wave–particle phase angle, in radians.
Lorentz factor (dimensionless).
Wave magnetic field amplitude, in T.
Parallel wave number, in rad m⁻¹.
Wave angular frequency, in rad s⁻¹.
Ion charge, in Coulombs.
Ion rest mass, in kg.
Time derivative of kinetic energy:
dEk/dt = (1/(gamma*m)) * q * pper * Bw * (w/kappa) * sin(eta), in J s⁻¹.dgammadt
Returns the time rate of change of the Lorentz factor.
Perpendicular momentum, in kg m s⁻¹.
Wave–particle phase angle, in radians.
Lorentz factor (dimensionless).
Wave magnetic field amplitude, in T.
Parallel wave number, in rad m⁻¹.
Wave angular frequency, in rad s⁻¹.
Ion charge, in Coulombs.
Ion rest mass, in kg.
Time derivative of the Lorentz factor, in s⁻¹.
dalphadt
Returns the time rate of change of the local pitch angle, including both the wave-driven term and the adiabatic drift term due to the field gradient.
Parallel momentum, in kg m s⁻¹.
Perpendicular momentum, in kg m s⁻¹.
Wave–particle phase angle, in radians.
Lorentz factor (dimensionless).
Ion cyclotron frequency, in rad s⁻¹.
Spatial derivative of the cyclotron frequency along the field line, in rad m⁻¹ s⁻¹.
Wave angular frequency, in rad s⁻¹.
Parallel wave number, in rad m⁻¹.
Wave magnetic field amplitude, in T.
Ion rest mass, in kg.
Ion charge, in Coulombs.
Time derivative of the local pitch angle, in rad s⁻¹.
daeqdt
Returns the time rate of change of the equatorial pitch angle for a parallel EMIC wave. The mapping from local to equatorial pitch angle change uses the ratio tan(aeq)/tan(alpha).
Parallel momentum, in kg m s⁻¹.
Perpendicular momentum, in kg m s⁻¹.
Wave–particle phase angle, in radians.
Lorentz factor (dimensionless).
Wave angular frequency, in rad s⁻¹.
Parallel wave number, in rad m⁻¹.
Wave magnetic field amplitude, in T.
Equatorial pitch angle, in radians.
Local pitch angle, in radians.
Ion rest mass, in kg.
Ion charge, in Coulombs.
Time derivative of the equatorial pitch angle, in rad s⁻¹.
detadt
Returns the time rate of change of the wave–particle phase angle eta. Accepts a species flag s to switch the sign of the cyclotron term between ions and electrons.
Parallel momentum, in kg m s⁻¹.
Perpendicular momentum, in kg m s⁻¹.
Wave–particle phase angle, in radians.
Wave magnetic field amplitude, in T.
Wave angular frequency, in rad s⁻¹.
Parallel wave number, in rad m⁻¹.
Ion cyclotron frequency, in rad s⁻¹.
Lorentz factor (dimensionless).
Ion charge, in Coulombs.
Ion rest mass, in kg.
Species selector. Use
'ion' for proton/helium/oxygen (cyclotron term sign +1) or 'electron' (cyclotron term sign -1).Time derivative of the wave–particle phase, in rad s⁻¹.
Nonlinear trapping diagnostics
The three nonlinear functions compute the phase-trapping diagnostics for parallel EMIC waves. Thenonlinear_theta function has a different signature from the oblique module: it directly computes the trapping frequency squared from the wave amplitude and momentum, without the Bessel-function decomposition used in EMIC_ion_mod.
nonlinear_H
Computes the nonlinear Hamiltonian H, which captures the departure from exact resonance due to field and wave inhomogeneity.
Perpendicular momentum, in kg m s⁻¹.
Parallel momentum, in kg m s⁻¹.
Parallel wave number, in rad m⁻¹.
Lorentz factor (dimensionless).
Ion rest mass, in kg.
Ion cyclotron frequency, in rad s⁻¹.
Time derivative of the parallel wave number, in rad m⁻¹ s⁻¹.
Spatial gradient of the cyclotron frequency along the field line, in rad m⁻¹ s⁻¹.
Time derivative of the wave frequency (zero for monochromatic wave), in rad s⁻².
Nonlinear trapping Hamiltonian H. Pass together with
wtsq to nonlinear_S.Compared with
EMIC_ion_mod.nonlinear_H, the sign on the cyclotron inhomogeneity term is negated: fac1 = -(1/gamma) * dwc_dt, reflecting the ion-resonance convention for parallel propagation.nonlinear_S
Computes the dimensionless trapping parameter S.
The nonlinear Hamiltonian H from
nonlinear_H.The trapping frequency squared from
nonlinear_theta (in rad² s⁻²).Dimensionless trapping parameter
S = H / wtsq. Phase trapping is indicated by |S| less than 1.nonlinear_theta
Computes the nonlinear trapping coupling term and trapping frequency squared directly from the wave amplitude and particle momentum. No Bessel functions are required for parallel propagation.
Perpendicular momentum, in kg m s⁻¹.
Parallel momentum, in kg m s⁻¹.
Wave magnetic field amplitude, in T.
Parallel wave number, in rad m⁻¹.
Lorentz factor (dimensionless).
Ion rest mass, in kg.
Ion charge, in Coulombs.
Ion cyclotron frequency, in rad s⁻¹.
Wave angular frequency, in rad s⁻¹.
Nonlinear coupling term theta (SI units). Combines the wave-magnetic force and relativistic correction.
Trapping frequency squared
|theta| (in rad² s⁻²), for use as wtsq_arg in nonlinear_S.Comparison with oblique EMIC_ion_mod
The table below summarises the key differences between the two EMIC sub-modules.| Feature | parallel_EMIC_mod | EMIC_ion_mod |
|---|---|---|
| Wave normal angle | Zero (field-aligned) | Arbitrary oblique angle |
| Bessel functions | Not needed | Jm, Jm±1 via beta |
wpi_params | Not available | Required per step |
| Coupling params | Direct Bw, w/k terms | C0, C1p, C1m coefficients |
dkpardt | Not available | Available |
dwcdt | Not available | Available |
detadt species flag | s='ion' or 'electron' | Not present |