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.
EMIC_ion_mod sub-module implements the relativistic equations of motion for a single ion (proton, helium, or oxygen) interacting with an obliquely propagating Electromagnetic Ion Cyclotron (EMIC) wave in a dipole magnetic field. All coupling is expressed through right-hand and left-hand polarised wave components decomposed via Bessel functions of the first kind. Compared with whistler_electron_mod, this module adds two unique evolution equations — dkpardt and dwcdt — that track the variation of the parallel wave number and the cyclotron frequency along the particle trajectory, which are needed for accurate nonlinear trapping analysis in an inhomogeneous field.
wpi_params
Computes derived wave–particle coupling parameters required by all time-derivative functions. Call this once per integration step before evaluating any d*/dt function. The function decomposes the transverse wave fields into right- and left-hand circularly polarised components and forms the corresponding reference momenta and frequencies.
Ion momentum component perpendicular to the background magnetic field B₀, in kg m s⁻¹.
Perpendicular component of the wave number vector, in rad m⁻¹.
Ion charge, in Coulombs. Use
WPIT.Environment_mod.const.qi for protons.Ion rest mass, in kg. Use
const.mH, const.mHe, or const.mO for proton, helium, or oxygen respectively.Magnitude of the background geomagnetic field, in T.
x-component of the wave electric field amplitude, in V m⁻¹.
y-component of the wave electric field amplitude, in V m⁻¹.
x-component of the wave magnetic field amplitude, in T.
y-component of the wave magnetic field amplitude, in T.
Relativistic Lorentz factor of the ion (dimensionless).
Bessel function argument
beta = -(kper * pper) / (qi * Bmag) (dimensionless).Right-hand circularly polarised wave magnetic field amplitude,
BwR = 0.5*(Bxw + Byw), in T.Left-hand circularly polarised wave magnetic field amplitude,
BwL = 0.5*(Bxw - Byw), in T.Right-hand circularly polarised wave electric field amplitude, in V m⁻¹.
Left-hand circularly polarised wave electric field amplitude, in V m⁻¹.
Right-hand reference momentum
pwR = gamma * mi * (EwR / BwR), in kg m s⁻¹.Left-hand reference momentum
pwL = gamma * mi * (EwL / BwL), in kg m s⁻¹.Right-hand effective cyclotron-like frequency
wR = (qi * BwR) / (gamma * mi), in rad s⁻¹.Left-hand effective cyclotron-like frequency
wL = (qi * BwL) / (gamma * mi), in rad s⁻¹.dzdt
Returns the time rate of change of the distance along the magnetic field line.
Ion momentum component parallel to B₀, in kg m s⁻¹.
Lorentz factor (dimensionless).
Ion rest mass, in kg.
Time derivative of the field-line distance
dz/dt = ppar / (mi * gamma), in m s⁻¹.dlamdadt
Returns the time rate of change of the magnetic latitude lambda along the field line, accounting for dipole geometry.
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, combining the wave-driven force (expressed via Bessel functions) with the adiabatic mirror force.
Perpendicular momentum, in kg m s⁻¹.
Wave–particle phase angle, in radians.
Lorentz factor (dimensionless).
Resonance harmonic order m (integer).
Ion charge, in Coulombs.
Ion rest mass, in kg.
Field-aligned (z) component of the wave electric field amplitude, in V m⁻¹.
Bessel argument beta from
wpi_params (dimensionless).Right-hand effective frequency from
wpi_params, in rad s⁻¹.Left-hand effective frequency from
wpi_params, in rad s⁻¹.Background magnetic field magnitude, in T.
Spatial gradient of the magnetic field magnitude along the field line, in T m⁻¹.
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 parallel momentum and the reference momenta pwR and pwL.
Perpendicular momentum, in kg m s⁻¹.
Parallel momentum, in kg m s⁻¹.
Wave–particle phase angle, in radians.
Lorentz factor (dimensionless).
Resonance harmonic order m.
Ion charge, in Coulombs.
Ion rest mass, in kg.
Right-hand reference momentum from
wpi_params, in kg m s⁻¹.Left-hand reference momentum from
wpi_params, in kg m s⁻¹.Bessel argument beta (dimensionless).
Right-hand effective frequency, in rad s⁻¹.
Left-hand effective frequency, in rad s⁻¹.
Background magnetic field magnitude, in T.
Spatial gradient of the magnetic field along the field line, in T m⁻¹.
Time derivative of the perpendicular momentum
dpper/dt, in kg m s⁻².dEkdt
Returns the time rate of change of the relativistic kinetic energy of the ion due to wave–particle interaction.
Perpendicular momentum, in kg m s⁻¹.
Parallel momentum, in kg m s⁻¹.
Wave–particle phase angle, in radians.
Lorentz factor (dimensionless).
Resonance harmonic order m.
Ion charge, in Coulombs.
Ion rest mass, in kg.
Field-aligned wave electric field component, in V m⁻¹.
Bessel argument beta (dimensionless).
Right-hand wave electric field amplitude, in V m⁻¹.
Left-hand wave electric field amplitude, in V m⁻¹.
Wave angular frequency, in rad s⁻¹.
Wave number magnitude, in rad m⁻¹.
Time derivative of the kinetic energy, in J s⁻¹.
dgammadt
Returns the time rate of change of the Lorentz factor due to the wave–particle interaction.
Perpendicular momentum, in kg m s⁻¹.
Parallel momentum, in kg m s⁻¹.
Wave–particle phase angle, in radians.
Lorentz factor (dimensionless).
Resonance harmonic order m.
Ion charge, in Coulombs.
Ion rest mass, in kg.
Field-aligned wave electric field component, in V m⁻¹.
Bessel argument beta (dimensionless).
Right-hand wave electric field amplitude, in V m⁻¹.
Left-hand wave electric field amplitude, in V m⁻¹.
Time derivative of the Lorentz factor, in s⁻¹.
dalphadt
Returns the time rate of change of the local pitch angle.
Perpendicular momentum, in kg m s⁻¹.
Parallel momentum, in kg m s⁻¹.
Wave–particle phase angle, in radians.
Field-aligned wave electric field component, in V m⁻¹.
Resonance harmonic order m.
Ion charge, in Coulombs.
Right-hand reference momentum from
wpi_params, in kg m s⁻¹.Left-hand reference momentum from
wpi_params, in kg m s⁻¹.Bessel argument beta (dimensionless).
Right-hand effective frequency, in rad s⁻¹.
Left-hand effective frequency, in rad s⁻¹.
Time derivative of the local pitch angle, in rad s⁻¹.
daeqdt
Returns the time rate of change of the equatorial pitch angle, combining wave forcing and the tan(aeq) geometric factor that maps local pitch angle changes to their equatorial equivalent.
Perpendicular momentum, in kg m s⁻¹.
Parallel momentum, in kg m s⁻¹.
Wave–particle phase angle, in radians.
Equatorial pitch angle, in radians.
Field-aligned wave electric field component, in V m⁻¹.
Lorentz factor (dimensionless).
Resonance harmonic order m.
Ion charge, in Coulombs.
Ion rest mass, in kg.
Right-hand reference momentum, in kg m s⁻¹.
Left-hand reference momentum, in kg m s⁻¹.
Bessel argument beta (dimensionless).
Right-hand effective frequency, in rad s⁻¹.
Left-hand effective frequency, in rad s⁻¹.
Time derivative of the equatorial pitch angle, in rad s⁻¹.
detadt
Returns the time rate of change of the wave–particle phase angle eta, which governs whether the particle is trapped or passing relative to the wave potential.
Parallel momentum, in kg m s⁻¹.
Resonance harmonic order m.
Ion cyclotron frequency magnitude, in rad s⁻¹.
Lorentz factor (dimensionless).
Parallel wave number component, in rad m⁻¹.
Ion rest mass, in kg.
Wave angular frequency, in rad s⁻¹.
Time derivative of the wave–particle phase:
deta/dt = (m*wc/gamma) + (kpar*ppar)/(gamma*mi) - w, in rad s⁻¹.dkpardt
Unique to this module. Returns the rate of change of the parallel wave number experienced by the ion as it moves along the magnetic field line. This is needed to compute the nonlinear parameter H accurately in an inhomogeneous field.
Parallel ion momentum, in kg m s⁻¹.
Ion rest mass, in kg.
Lorentz factor (dimensionless).
Wave–particle phase angle (used as the cosine projection factor), in radians.
Spatial gradient of the parallel wave number along the field line, in rad m⁻².
Time derivative of the parallel wave number:
dkpar/dt = (ppar / (m*gamma)) * dkdz * cos(psi), in rad m⁻¹ s⁻¹.dkpardt is defined in EMIC_ion_mod/dkpardt.py but is not re-exported through __init__.py. Import it directly with from WPIT.WPI_mod.EMIC_ion_mod.dkpardt import dkpardt. There is no equivalent in whistler_electron_mod; the EMIC ion interaction requires explicit tracking of parallel wave-number evolution because the EMIC dispersion surface varies significantly with field-line position and ion composition.dwcdt
Unique to this module. Returns the rate of change of the ion cyclotron frequency along the particle trajectory as it moves in the inhomogeneous dipole field.
Parallel ion momentum, in kg m s⁻¹.
Ion rest mass, in kg.
Lorentz factor (dimensionless).
Spatial gradient of the ion cyclotron frequency along the field line, in rad m⁻¹ s⁻¹.
Time derivative of the cyclotron frequency:
dwc/dt = (ppar / (m*gamma)) * dwcdz, in rad s⁻².Nonlinear trapping diagnostics
The four nonlinear functions compute the trapping-island Hamiltonian terms following the formalism of Omura et al. (2010) adapted for EMIC waves with Bessel-function corrections for oblique propagation.nonlinear_C0
Computes the inhomogeneity coefficient C0, the field-aligned component of the nonlinear force.
Parallel momentum, in kg m s⁻¹.
Parallel wave number, in rad m⁻¹.
Resonance harmonic order m.
Lorentz factor (dimensionless).
Ion charge, in Coulombs.
Ion rest mass, in kg.
Ion cyclotron frequency, in rad s⁻¹.
Field-aligned wave electric field amplitude, in V m⁻¹.
The C0 nonlinear coefficient (SI units).
nonlinear_C1m
Computes the left-hand coupling coefficient C1m for the nonlinear trapping force.
Perpendicular momentum, in kg m s⁻¹.
Parallel momentum, in kg m s⁻¹.
Parallel wave number, in rad m⁻¹.
Resonance harmonic order m.
Ion charge, in Coulombs.
Ion rest mass, in kg.
Lorentz factor (dimensionless).
Left-hand effective frequency from
wpi_params, in rad s⁻¹.Left-hand wave electric field amplitude, in V m⁻¹.
Ion cyclotron frequency, in rad s⁻¹.
The C1m left-hand nonlinear coupling coefficient (SI units).
nonlinear_C1p
Computes the right-hand coupling coefficient C1p for the nonlinear trapping force.
Perpendicular momentum, in kg m s⁻¹.
Parallel momentum, in kg m s⁻¹.
Parallel wave number, in rad m⁻¹.
Resonance harmonic order m.
Ion charge, in Coulombs.
Ion rest mass, in kg.
Lorentz factor (dimensionless).
Right-hand effective frequency from
wpi_params, in rad s⁻¹.Right-hand wave electric field amplitude, in V m⁻¹.
Ion cyclotron frequency, in rad s⁻¹.
The C1p right-hand nonlinear coupling coefficient (SI units).
nonlinear_H
Computes the nonlinear trapping Hamiltonian H, which measures the distance of a particle from exact resonance including field inhomogeneity corrections. When H/wtsq (the trapping parameter S) satisfies |S| < 1, the particle is phase-trapped.
Perpendicular momentum, in kg m s⁻¹.
Parallel momentum, in kg m s⁻¹.
Parallel wave number, in rad m⁻¹.
Lorentz factor (dimensionless).
Resonance harmonic order m.
Ion rest mass, in kg.
Ion cyclotron frequency, in rad s⁻¹.
Time derivative of the parallel wave number (from
dkpardt), in rad m⁻¹ s⁻¹.Spatial gradient of the cyclotron frequency along the field line, in rad m⁻¹ s⁻¹.
Time derivative of the wave frequency (typically zero for monochromatic waves), in rad s⁻².
The nonlinear Hamiltonian H. Pass to
nonlinear_S together with the trapping frequency squared.nonlinear_S
Computes the dimensionless trapping parameter S = H / omega_t_sq. Phase trapping occurs when |S| < 1.
The nonlinear Hamiltonian H from
nonlinear_H.The trapping frequency squared from
nonlinear_theta (in rad² s⁻²).Dimensionless nonlinear trapping parameter. |S| less than 1 indicates phase trapping; |S| greater than 1 indicates phase liberation.
nonlinear_theta
Computes the nonlinear coupling term theta and the trapping frequency squared, using Bessel functions evaluated at beta to account for the oblique propagation geometry.
Field-aligned coefficient from
nonlinear_C0.Right-hand coefficient from
nonlinear_C1p.Left-hand coefficient from
nonlinear_C1m.Resonance harmonic order m.
Bessel argument beta from
wpi_params (dimensionless).Combined nonlinear trapping coupling term (Bessel-weighted sum of C0, C1p, C1m).
Trapping frequency squared
|theta| (in rad² s⁻²), passed to nonlinear_S as wtsq_arg.