VelocityDistributionFunctions

Abstract type for velocity distributions.

Abstract type for velocity probability distribution functions, extending MultivariateDistribution.

BiKappaPDF(vth_perp, vth_para, κ, b0=[0, 0, 1])
BiKappaPDF(T_perp::Temperature, T_para::Temperature, κ, b0=[0, 0, 1]; mass = me)

Modified BiKappa velocity distribution with kappa index κ, assuming κ-independent temperatures $T_{∥,⟂}$, with magnetic field direction b0.

The distribution can also be parameterized by kappa thermal speeds $v_{th,∥}$ and $v_{th,⟂}$.

\[\begin{aligned} f_κ(𝐯) & ∝ \left[1 + \frac{v_∥^2}{κ v_{\mathrm{th}, ∥}^2} + \frac{v_⟂^2}{κ v_{\mathrm{th}, ⟂}^2}\right]^{- κ - 1} \\ & = \left[1+\frac{m}{k_B (2 κ-3)} \left(\frac{v_∥^2}{T_∥}+\frac{v_⟂^2}{T_⟂}\right) \right]^{-κ-1} \end{aligned}\]

where the normalization constant is

\[\begin{aligned} A_κ &= \left(\frac{1}{π κ}\right)^{3/2} \frac{1}{v_{th,∥} v_{th,⟂}^2} \frac{Γ[κ+1]}{Γ[κ-1/2]} \\ &= \left[\frac{m}{π k_B(2 κ-3)}\right]^{3 / 2} \frac{1}{T_⟂ \sqrt{T_∥}} \frac{Γ[κ+1]}{Γ[κ-1/2]} \end{aligned}\]

See also Kappa, kappa_thermal_speed

BiMaxwellian(vth_perp, vth_para, b0=[0, 0, 1])
BiMaxwellian(T_perp::Temperature, T_para::Temperature, b0=[0, 0, 1]; mass = me)

BiMaxwellian velocity distribution with different thermal velocities in perpendicular vth_perp and parallel vth_para directions and magnetic field direction b0.

\[f(𝐯) ∝ \exp[-\frac{𝐯_⟂^2}{v_{\mathrm{th}, ⟂}^2}] \exp[-\frac{𝐯_∥^2}{v_{\mathrm{th}, ∥}^2}]\]

where the normalization constant is $A = √π^{-3} / (v_{th,∥} v_{th,⟂}^2)$.

A Kappa distribution has a nearly Maxwellian core at low energies, and highenergy tails decreasing as suprathermal power laws that can be significantly broader than exponential tails.

See also Pierrard et al. [1] and Pierrard and Lazar [2].

KappaPDF(vth, κ)
KappaPDF(T::Temperature, κ; mass = me)

Kappa velocity distribution with index κ and thermal velocity vth.

\[f(𝐯) ∝ [1 + |𝐯|²/(κ·vₜₕ²)]^{-(κ+1)}\]

where the normalization constant is $A_3 = Γ(κ + 1) / Γ(κ - 1/2) / (π κ v_{th}^2)^{3/2}$.

Notes

Kappa index must be > 1.5 for finite variance. For large κ, the distribution approaches a Maxwellian. Smaller κ values produce stronger high-energy tails.

See also kappa_thermal_speed.

Maxwellian(vth)
Maxwellian(T::Temperature; mass = me)

Isotropic Maxwellian velocity distribution with thermal velocity vth / temperature T.

ShiftedPDF(base, u0)

Velocity distribution with a drift velocity u0 applied to a base distribution.

VelocityDistribution(n, pdf)

Physical velocity distribution combining number density n with a velocity probability distribution pdf.

Normalized PDF for the parallel velocity

\[f(v) = 1 / (√π vₜₕ) · exp[-(v/vₜₕ)²]\]

ustrip(d::VelocityDistribution)

Strip units from all fields of a velocity distribution, returning a new distribution with unitless values.

BiKappa(args...; u0=nothing, kw...)
BiKappa(n, args...; u0=nothing, kw...)

Construct a BiKappaPDF velocity distribution.

If n is provided, returns VelocityDistribution with n and the distribution BiKappaPDF(args...; kw...). If u0 is provided, returns ShiftedPDF with the distribution BiKappaPDF(args...; kw...) and u0.

BiMaxwellian(args...; u0=nothing, kw...)
BiMaxwellian(n, args...; u0=nothing, kw...)

Construct a BiMaxwellianPDF velocity distribution.

If n is provided, returns VelocityDistribution with n and the distribution BiMaxwellianPDF(args...; kw...). If u0 is provided, returns ShiftedPDF with the distribution BiMaxwellianPDF(args...; kw...) and u0.

Kappa(args...; u0=nothing, kw...)
Kappa(n, args...; u0=nothing, kw...)

Construct a KappaPDF velocity distribution.

If n is provided, returns VelocityDistribution with n and the distribution KappaPDF(args...; kw...). If u0 is provided, returns ShiftedPDF with the distribution KappaPDF(args...; kw...) and u0.

Maxwellian(args...; u0=nothing, kw...)
Maxwellian(n, args...; u0=nothing, kw...)

Construct a MaxwellianPDF velocity distribution.

If n is provided, returns VelocityDistribution with n and the distribution MaxwellianPDF(args...; kw...). If u0 is provided, returns ShiftedPDF with the distribution MaxwellianPDF(args...; kw...) and u0.

Returns (coefficient, energy_exponent) such that: out = data * c * E^p

Conversion chain: df_cm ↔ df_km ↔ flux ↔ eflux

• f [s³/cm⁶] — phase space density (CGS)
• f [s³/km⁶] — phase space density (SI-ish)
• F [#/(cm²·s·sr·eV)] — differential number flux, F = 2E/m² · f
• j [eV/(cm²·s·sr·eV)] — differential energy flux, j = E · F

_rand!(rng::AbstractRNG, d::Kappa, x)

Generates a random velocity vector sampled from the 3D Kappa distribution.

Algorithm: The Kappa distribution is generated using a compound probability method (decomposition into a Maxwellian with a Chi-squared distributed temperature variance).

1. Sample from Chi-squared: ξ ~ ChiSq(2κ - 1)
2. Sample from Isotropic Normal: Z ~ Normal(0, I)
3. $𝐯 = vₜₕ * √(κ / ξ) * Z$

References

• https://www.wikiwand.com/en/articles/Student%27s_t-distribution
• Multivariate t-distribution

compute_field_aligned(ttens, t3evec, velocity, magf)

Field-aligned temperature decomposition and symmetry analysis.

Rotates the temperature tensor into a field-aligned coordinate system where $\hat{z}' \parallel \mathbf{B}$:

\[\mathbf{T}' = R^{-1}\, \mathbf{T}\, R\]

The rotation matrix $R$ has columns $(\hat{x}', \hat{y}', \hat{z}')$ where $\hat{z}' = \hat{B}$, $\hat{y}' = \hat{B} \times \mathbf{V} / |\hat{B} \times \mathbf{V}|$, and $\hat{x}'$ completes the right-handed triad.

The symmetry axis is the eigenvector closest to $\mathbf{B}$ (with sign chosen so the dot product is positive), and the symmetry angle is:

\[\alpha = \arccos|\hat{B} \cdot \hat{e}_\parallel|\]

Returns (; magt3, symm, symm_theta, symm_phi, symm_ang).

compute_temperature(ptens, density, mass) -> NamedTuple

Temperature quantities from the pressure tensor.

Eigenvalue decomposition of $\mathbf{T}$ yields three temperature eigenvalues $(T_1, T_2, T_3)$ sorted by the SPEDAS heuristic: the eigenvalue whose removal makes the remaining two most similar is assigned to slot 3.

Returns (; ttens, avgtemp, vthermal, t3, t3evec).

directional_energy_spectra(spec_data, time_var, pitch_angles, loss_cone; para_tol=22.25, anti_tol=22.25)

Process 3D spectral data (pitchangle × energy × time) to extract directional flux spectra. This implements the same logic as pyspedas epdl2_Espectra function.

kappa_thermal_speed(T, κ, m)

Return the most probable speed of a (modified) kappa distribution with κ-Independent temperature T.

\[V_{th} = \sqrt{\frac{κ - 3/2}{κ} \frac{2 k_B T}{m}}\]

omega_weights(theta, phi, dtheta, dphi)

Compute solid-angle integration weights for moments calculation.

Angles are in radians.

The 10 weight channels are:

Follows the IDL/PySPEDAS moments_3d_omega_weights convention (latitude angles).

pitch_angle_distribution(vdf, B, φ, θ; bins=nothing, method=:mean) -> (; data, pitch_angles)

Compute pitch-angle distributions from particle vdf and magnetic field B measurements, given azimuthal φ and polar θ angles.

Returns a named tuple with fields:

• data: Pitch-angle distribution array (nbins,) for 2-D input vdf or (nbins, energy) for 3-D input vdf
• pitch_angles: Bin center angles in degrees

Notes

• vdf can be either 2-D (φ, θ) or 3-D (φ, θ, energy)
• bins is used for pitch angle binning. It can be an Integer for uniform bin count, or a Vector of bin edges.
• method is used for aggregation. It can be :mean (default) or :sum.

plasma_moments(dist, sc_pot=0, magf=nothing; mass, charge, edim)

Compute all plasma moments from a single distribution on a spherical energy-angle grid.

Handles unit conversion, species mass/charge lookup, and coordinate transforms internally.

Arguments

• dist: Distribution struct with fields data, energy, theta, phi, mass, charge.
• sc_pot: Spacecraft potential [V]. Positive potential repels ions.
• magf: Magnetic field vector for field-aligned decomposition. If nothing (default), field-aligned quantities are omitted.

Keyword Arguments

• species: Species symbol (:H, :He, :O, :e). Determines mass, charge, and the A parameter for unit conversion. Defaults to :H.
• edim: Energy axis index in data (default 1). When edim ≠ 1, a permutedims moves energy to the first axis internally.
• units: Input unit system (:eflux, :flux, :df_km, :df_cm). Default :eflux (no conversion).

Returns

A NamedTuple of plasma moments.

Assumptions

The input distribution must have the following fields:

• data: Distribution values in energy flux units [eV/(cm²·s·sr·eV)]
• energy and denergy: Energy bin centers and widths [eV] (denergy is optional; estimated from energy if absent)
• theta and dtheta: Latitude angle bin centers and widths [deg] (dtheta/dphi optional; estimated from centres if absent)
• phi and dphi: Azimuthal angle bin centers and widths [deg]
• mass: Particle mass [eV/(cm/s)²]
• charge: Particle charge [elementary charges, signed] (optional; defaults to 1)

data may be either 2D (n_energy, n_angles) (reformed/flattened) or 3D (n_energy, n_phi, n_theta) (unreformed).

Energy arrays (energy, denergy) may be supplied as:

• a full array matching the shape of data, when energy bins vary across angles, or
• a 1D vector of length n_energy, when energy bins are the same for every angle.

Angle arrays (theta, dtheta, phi, dphi) may be supplied as:

• an array matching the angle-only dimensions of data (i.e. shape (n_angles,) or (n_phi, n_theta)).
• a 1D vector of length n_theta for theta, and n_phi for phi, when data is 3D.

Angular convention (SPEDAS-compatible)

• theta: latitude / elevation angle (−90° to 90°), not colatitude
• phi: azimuth (0° to 360°)

sort_flux_by_pitch_angle(flux, pitch_angle)

Sort flux by pitch angle into ascending order. Set sort_on_reverse to true to sort only if the pitch angle is in reverse order.

tmoments(data, theta, phi, energy, sc_pot, magf; tdim, edim, kw...)

Compute plasma moments for every timestep in a multi-time raw distribution array.

Loops over the time dimension tdim, calling plasma_moments for each slice, and returns a StructArray.

Keyword Arguments

• tdim: Which axis of data is time (required).

Returns

A StructArray of moment NamedTuples, one per timestep.

Example

tmoments(data, theta, phi, energy; species=:H, tdim=1, edim=4)

tmoments(dists::AbstractVector, sc_pots; kw...)
tmoments(dists::AbstractVector, sc_pots, magfs; kw...)

Batch-compute plasma moments for a vector of pre-processed distributions, returning a StructArray.

tpitch_angle_distribution(vdf, B, φ, θ; bins=nothing, method=:mean)

Compute pitch-angle distributions ***time series*** from particle vdf and magnetic field B measurements, given azimuthal φ and polar θ angles.

Returns a named tuple with fields:

• data: Pitch-angle distribution array, (nbins, time) for 3-D or (nbins, energy, time) for 4-D input vdf
• pitch_angles: Bin center angles in degrees

Notes

• vdf: can be either 3-D (φ, θ, time) or 4-D (φ, θ, energy, time). B should match the time dimension of vdf
• φ and θ can be either 1-D (n,) or time-varying 2-D (n, time)
• bins is used for pitch angle binning. It can be an Integer for uniform bin count, or a Vector of bin edges.
• method is used for aggregation. It can be :mean (default) or :sum.