Internal

using TestParticle imports the tracing setup and execution APIs, end-to-end VDF tracers, main result accessors, and plotting entry points. Diagnostics, conversions, sampling and distribution APIs, interpolation policies, and storage types are public but not exported. Access them through the module or an explicit import:

julia

using TestParticle
using TestParticle: get_energy, Maxwellian, ClampExtrap

# Alternatively, use TestParticle.get_energy, TestParticle.Maxwellian, etc.

Both exported and public-only names are supported API. If an unqualified name from an earlier release is no longer imported, qualify it with TestParticle. or add an explicit import; its implementation remains available.

Public APIs

TestParticle.AdaptiveHybrid Type

julia

AdaptiveHybrid{T, A}

Hybrid algorithm that switches between adaptive Boris (FO) and a guiding-center ODE solver gc_alg (defaulting to Vern7() when OrdinaryDiffEqVerner is loaded), used as solve(TraceProblem(u0, tspan, p), alg) with the full-orbit state u0.

Mode switching uses hysteresis with two adiabaticity thresholds to avoid rapid GC ↔ FO chattering near a single bound:

threshold_gc_to_fo (α): switch GC → FO when ε ≥ α.
threshold_fo_to_gc (β): switch FO → GC when ε < β.

With α ≥ β the band β ≤ ε < α forms a buffer where the current mode is retained, so a particle hovering near the boundary does not oscillate.

The adiabaticity parameter ε compared against the thresholds is selected by the adiabaticity field, which may be:

:curvature (default) → ε_curv = ρ_L / R_c (curvature drift; reproduces the legacy get_adiabaticity behavior exactly),
:gradB → ε_gradB = ρ_L / L_B, with L_B = |B| / |∇B|,
:both → OR of the two criteria: the solver switches to the full orbit whenever either ε_curv ≥ α or ε_gradB ≥ α (equivalently max(ε_curv, ε_gradB) ≥ α),
:jacobian → ε_jac = ρ_L · ‖JB‖_F / |B|, CHIMP's original all-in-one criterion (Bates & Fuentes, 2020), where JB is the Jacobian of B and ‖JB‖_F its Frobenius norm. It captures curvature, grad-B, torsion and shear at once, so it switches to full orbit in non-adiabatic regions that :curvature/:gradB miss (e.g. a field whose direction rotates in space while keeping constant magnitude).

Both modes adapt their step size to the local field. The full-orbit mode uses a Boris step dt = 2π * safety_fo / (|q/m| * |B|) clipped to [dtmin, dtmax] and recomputed after every accepted step; when the step changes, the staggered velocity is re-centered on the new step so that the leapfrog scheme stays time-reversible. The guiding-center mode steps with gc_alg, so its steps may span many gyroperiods.

Because a guiding-center step can be long compared with the scale on which ε varies, the adiabaticity check is triggered by whichever comes first: check_interval accepted steps, or check_dt in simulation time since the previous check. A step is also clipped so that it never crosses the next check deadline, which makes check_dt a hard bound on the simulated time a particle can travel between examinations rather than a bound that a long step could overshoot. check_dt defaults to 100 * dtmax: small enough to catch a transition that a long guiding-center step would otherwise jump over, and large enough that the clamp does not turn check_dt into a step-size cap that costs more than the monitoring saves. Lower it where ε changes on a shorter scale.

While the solver is in the full-orbit mode, check_margin_max > 1 lengthens both bounds by up to that factor in proportion to how far ε sits above threshold_fo_to_gc: ε changes by O(ε) over one curvature radius, so an ε that is a factor k above the exit threshold needs of order k such excursions before the mode can flip, and checking in between only costs time. The interval collapses back to its nominal value as ε approaches the threshold, and the guiding-center mode always uses the nominal interval, so a transition into a non-adiabatic region is detected as early as with a uniform interval.

It is off by default (check_margin_max = 1). Stretching reorders the mode history enough to matter: on the magnetic-bottle benchmark 4 makes the run about 40% faster but the RMS position error 50% larger, because the full-orbit excursions become fewer and longer and the full-orbit step is the coarser one. Raise it only where the full-orbit mode is cheap relative to the guiding-center mode.

On the switch to the guiding center, the state is refined by up to switch_correction fixed-point iterations of X = x - ρ(X) instead of the zeroth-order X = x - ρ(x) map, which removes the O(ε) jump that the switch would otherwise introduce. That map is the exact inverse of the reconstruction back to the full orbit, so the round trip through a switch returns the particle where it was. Set switch_correction = 0 for the legacy behavior.

Each check point records only the adiabaticity value used by the selected adiabaticity mode (a single scalar per check) together with the active mode in sol.stats.adiabaticity. This diagnostic is only saved when save_adiabaticity = true (the default); set it to false to skip the buffers and reduce memory/allocation overhead.

Term	Formula	Physics
`P_par`	`q v∥ (E⋅b̂)`	direct acceleration by `E∥`
`P_fermi`	`(m v∥²/B) (b̂×κ)⋅E`	work by `E` on the curvature drift
`P_grad`	`(μ/B) (b̂×∇B)⋅E`	convective part of the betatron channel, `μ v_E⋅∇B`
`P_betatron`	`μ ∂B/∂t`	local part of the betatron channel

Internal ​

Public APIs ​

Private types and methods ​

Internal

Public APIs

Private types and methods