Solver

solve(prob::HamiltonianProblem, alg::HamiltonianAlgorithm = SymmetricProjectionIntegrator()) -> HamiltonianSolution

Initialise and run the integrator in a single call.

Convenience wrapper equivalent to solve!(init(prob, alg)).

Returns

• HamiltonianSolution with retcode ∈ {:Success, :Failure}.

init(prob::HamiltonianProblem,
     alg::HamiltonianAlgorithm = SymmetricProjectionIntegrator();
     callbacks = ()) -> HamiltonianIntegrator

Initialise a step-by-step integrator without running any steps.

Pre-allocates all workspace buffers and history arrays sized to hold the full trajectory. Use the returned integrator with step! for fine-grained control, or pass it directly to solve!.

Keyword arguments

• callbacks: a single HamiltonianCallback or an iterable of them. Invoked pre-/post-step around each macro-step.

If alg is a RegularizedIntegrator with collision_bounce_radius > 0 and no CollisionBounce is present in callbacks, a matching one is synthesised automatically so the legacy kwarg keeps working.

Returns

• HamiltonianIntegrator at t = prob.tspan[1] with step_count = 0.

step!(integrator::HamiltonianIntegrator) -> Bool

Advance the integrator by one macro time step prob.dt.

Dispatches to the regularized or plain Cartesian integration path based on the algorithm type (RegularizedIntegrator vs SymmetricProjectionIntegrator) and current particle separations. The final step is automatically shortened to land exactly on prob.tspan[2].

Returns

• true if more steps remain, false when integration is complete.

solve!(integrator::HamiltonianIntegrator) -> HamiltonianSolution

Run the integrator to completion and return the full solution.

Repeatedly calls step! until t ≥ t_end. If the fixed-point projection fails to converge, retcode is set to :Failure rather than throwing.

Returns

• HamiltonianSolution containing the full time series and regularization diagnostics.

HamiltonianIntegrator

Mutable step-by-step integrator returned by init.

Use step!(integrator) to advance one macro-step, or solve!(integrator) to run to completion. The current state is accessible via integrator.q, integrator.p, and integrator.t.

Fields

• prob::HamiltonianProblem: Problem definition.
• alg::SymmetricProjectionIntegrator: Algorithm parameters.
• t::Float64: Current time.
• t_end::Float64: Final time (prob.tspan[2]).
• q::Vector{Float64}: Current flattened positions.
• p::Vector{Float64}: Current flattened momenta.
• step_count::Int: Number of macro-steps completed so far.
• buffers::SymmetricProjectionBuffers: Pre-allocated workspace (internal).
• callbacks::Tuple: Per-step callbacks (pre-/post-step hooks).
• diagnostics::RegularizationDiagnostics: Live regularization statistics.
• t_history::Vector{Float64}: Pre-allocated time history array.
• q_history::Vector{Vector{Float64}}: Pre-allocated position history.
• p_history::Vector{Vector{Float64}}: Pre-allocated momentum history.

HamiltonianSolution

Result returned by solve or solve!.

Supports Julia iteration (for (t, q, p) in sol), integer indexing (sol[i]), and length(sol). Each index returns a (t, q, p) tuple.

Fields

• t::Vector{Float64}: Time points.
• q::Vector{Vector{Float64}}: Flattened position snapshots, one per time point.
• p::Vector{Vector{Float64}}: Flattened momentum snapshots, one per time point.
• prob::HamiltonianProblem: The originating problem definition.
• retcode::Symbol: :Success on normal completion, :Failure if the projection fixed-point failed to converge.
• regularization::RegularizationDiagnostics: Regularization usage statistics.

SymmetricProjectionIntegrator(; relaxation=0.25)

Symplectic integrator based on Strang-splitting with symmetric projection in extended phase space.

Implements the method of Jayawardana & Ohsawa (2021) for Weber's velocity-dependent Hamiltonian. The projection step solves a fixed-point iteration whose convergence is controlled by relaxation.

Keywords

• relaxation=0.25: Fixed-point relaxation factor ω ∈ (0, 1]. Smaller values slow convergence but improve stability near close encounters.

Fields

• relaxation::Float64: Stored relaxation factor.

RegularizedIntegrator{A}(base_alg::A; kwargs...)

Algorithm wrapper that activates Levi-Civita / KS regularization on top of a base Hamiltonian algorithm. kwargs mirror RegularizationOptions and are forwarded verbatim; enabled is set to true implicitly.

This is the user-facing entry point for regularized integration:

alg = RegularizedIntegrator(SymmetricProjectionIntegrator();
                            r_on_factor = 0.15, backend = :lifted_pair)
sol = solve(prob, alg)

The base algorithm's settings (e.g. relaxation) are preserved.