Regularization

Regularization is an optional, advanced feature. The core integrator runs unregularized by default; pass regularization = RegularizationOptions(enabled = true) to opt in.

When to use it

The Weber potential contains a Coulomb singularity at zero separation. For most simulations with well-separated particles this is not an issue. Enable regularization when:

• Two or more particles are expected to have close encounters (separation approaching zero).
• You observe energy drift or NaN values near close passages without it.

Regularization handles the Coulomb/Kepler singularity only. Weber's velocity-dependent correction is not regularized — the LC and KS transforms apply to the conservative part of the force.

Enabling regularization

prob = WeberProblem(
    sys, tspan, q0, p0;
    masses  = [1.0, 1.0],
    charges = [1.0, -1.0],
    c       = 10.0,
    dt      = 0.01,
    regularization = RegularizationOptions(enabled = true),   # opt in
)

Backends

For 3D problems, :lifted_pair automatically falls back to :adaptive_cartesian (with an optional warning controlled by warn_on_fallback).

# Explicit 3D choice
prob = WeberProblem(sys, tspan, q0, p0; ...
    regularization = RegularizationOptions(
        enabled = true,
        backend = :adaptive_cartesian,
    ),
)

Activation hysteresis

Regularization switches on when any pair separation drops below r_on and switches off once all separations in the active component exceed r_off. The thresholds are computed from the initial minimum separation by default:

r_on  = r_on_factor  × min_initial_separation   (default factor: 0.15)
r_off = r_off_factor × min_initial_separation   (default factor: 0.25)

You can override them directly:

prob = WeberProblem(sys, tspan, q0, p0; ...
    regularization = RegularizationOptions(
        enabled = true,
        r_on    = 0.05,
        r_off   = 0.10,
    ),
)

Chain mode

When three or more particles form a connected close-encounter cluster, regularization falls back to chain mode (adaptive Cartesian substeps for the whole cluster). Chain mode is enabled by default; disable with RegularizationOptions(chain_enabled = false).

Collision bounce

For head-on (ℓ = 0) collisions between like-charge pairs, a reflection boundary can be applied before each macro-step. This avoids the non-regularizable ℓ ≠ 0 singularity (where particles reach r = 0 at infinite speed).

prob = WeberProblem(sys, tspan, q0, p0; ...
    regularization = RegularizationOptions(collision_bounce_radius = 0.02),  # reflect at r < 0.02
)

Collision bounce works best without Levi-Civita regularization (the unregularized symplectic integrator keeps energy bounded across the bounce). See CollisionBounceRegularization for details.

Diagnostics

Every WeberSolution carries a regularization::RegularizationDiagnostics field with step counts, backend used, minimum encounter distance, and more.

sol = solve(prob, SymmetricProjectionIntegrator())
d = sol.regularization
println("Backend used: ", d.used_backend)
println("Activation count: ", d.activation_count)
println("Min encounter distance: ", d.min_encounter_distance)

Key fields and what they mean:

API reference

RegularizationOptions(; kwargs...)

RegularizationDiagnostics