System

HamiltonianSystem

Symbolic and compiled representation of the n-body Weber Hamiltonian.

Constructed once for a given (n_particles, dims) pair via HamiltonianSystem(n_particles, dims). The compiled equations of motion are reused across many HamiltonianProblem instances with different physical parameters. Construction involves symbolic differentiation and code generation via Symbolics.jl; expect a few seconds for the first call.

Fields

• n_particles::Int: Number of charged particles.
• dims::Int: Spatial dimension (1, 2, or 3).
• q_symbols::Vector{Num}: Symbolic coordinate variables [x1, y1, ..., xN, yN, ...].
• p_symbols::Vector{Num}: Symbolic momentum variables [px1, py1, ...].
• t_symbol::Num: Symbolic time variable. Reserved for time-dependent terms; the current Weber Hamiltonian is autonomous and does not use it.
• param_symbols: Symbolic parameter vector [m1…mN, q1…qN, c].
• kappa_symbols: Symbolic κ vector [κ12, κ13, …, κ_{N-1,N}], length N*(N-1)/2.
• hamiltonian_symbolic: Full symbolic Weber Hamiltonian expression.
• dq_dt_symbolic, dp_dt_symbolic: Symbolic Hamilton's equations.
• dq_dt_compiled(out, q, p, t, params, kappas), dp_dt_compiled(out, q, p, t, params, kappas): In-place compiled equations of motion. t is currently unused.
• hamiltonian_compiled(q, p, t, params, kappas): Compiled scalar Hamiltonian function.
• degrees_of_freedom::Int: Total DOF = n_particles × dims.
• terms::Vector{NamedTerm}: Named components of the Hamiltonian (e.g. :weber, :zollner) preserving the decomposition for per-term statistics and plotting. The generic constructor assigns a single :hamiltonian term by default; specialized constructors populate richer decompositions.

HamiltonianSystem(n_particles::Int, dims::Int) -> HamiltonianSystem

Convenience constructor for the default n-body Weber Hamiltonian in dims spatial dimensions. Equivalent to building weber_term(…) with all κ=1 symbols and passing it to the generic HamiltonianSystem(H, q, p; …) constructor.

Arguments

• n_particles: Number of particles (≥ 1).
• dims: Spatial dimension; must be 1, 2, or 3.

weber_term(q_vars, p_vars;
           masses, charges, c, kappas,
           n_particles, dims) -> Num

Build the symbolic Weber Hamiltonian (kinetic term plus κ-weighted pairwise velocity-dependent potential) from pre-constructed symbolic inputs.

Returns a Symbolics.Num expression usable with Symbolics.derivative and Symbolics.build_function. This is the symbolic builder at the heart of the default HamiltonianSystem(n_particles, dims) constructor; calling it directly lets a user compose a custom Hamiltonian, e.g. H = weber_term(q,p; …) + zollner_term(…).

Arguments

• q_vars, p_vars: Phase-space symbolic variables, each length n_particles*dims.

Keywords

• masses: Per-particle mass symbolic variables (length n_particles).
• charges: Per-particle charge symbolic variables (length n_particles).
• c: Speed-of-light symbolic variable.
• kappas: Per-pair κ coupling symbolic variables (length n_particles*(n_particles-1)/2, ordered by i<j and indexed via _pair_index).
• n_particles::Int, dims::Int: Problem shape.

zollner_term(q_vars, p_vars;
             masses, charges, c, kappas,
             n_particles, dims) -> Num

Build the symbolic Zöllner correction to the Weber Hamiltonian.

Returns Σ_{i<j} (kappas[pair_idx] - 1) · U_weber(i,j), where U_weber(i,j) is the standard Weber pair potential q_i q_j / r · (1 − ṙ² / (2c²)). This is the extra potential relative to the κ=1 (pure Weber) case, so

weber_term(…; kappas = κ)
== weber_term(…; kappas = ones) + zollner_term(…; kappas = κ)

up to Symbolics.jl expression rewriting. When all κ = 1 the correction is identically zero.

The physical Zöllner mismatch (κij = 1+a for unlike-sign pairs, 1 otherwise) is expressed by the concrete κ values injected via params at solve time; see `computezollnerkappas`.

Arguments

• q_vars, p_vars: Phase-space symbolic variables.

Keywords

• masses: Per-particle mass symbolic variables (enter through ṙ = r̂ · v, with v_i = p_i / m_i).
• charges: Per-particle charge symbolic variables.
• c: Speed-of-light symbolic variable.
• kappas: Per-pair κ coupling symbolic variables (length n_particles*(n_particles-1)/2, ordered by i<j and indexed via _pair_index).
• n_particles::Int, dims::Int: Problem shape.

NamedTerm(name, H_symbolic; pair_decomposition = nothing)

Named component of a composite Hamiltonian: a symbol that identifies the physical role (e.g. :weber, :zollner) and the symbolic expression contributing to the total H. Stored on HamiltonianSystem as terms::Vector{NamedTerm} so statistics and plotting can query individual contributions without re-deriving them from the compiled aggregate.

The optional pair_decomposition closure returns a per-pair decomposition of the term's contribution, evaluated on concrete (i, j, q, p, params) inputs. The shape of the returned tuple is term-specific; the Weber and Zöllner builders will attach compatible closures in Phase 4 when statistics migrate onto this interface.

Fields

• name::Symbol: Identifier used by get_term, has_term, term_names.
• H_symbolic: Symbolic expression contributing to the aggregate Hamiltonian.
• pair_decomposition::Union{Function,Nothing}: Optional closure (i, j, q, p, params) -> NamedTuple for per-pair statistics.

term_names(sys::HamiltonianSystem) -> Vector{Symbol}

Return the names of every NamedTerm on sys, in insertion order.

term_names(sys::HamiltonianSystem) -> Vector{Symbol}
has_term(sys::HamiltonianSystem, name::Symbol) -> Bool
get_term(sys::HamiltonianSystem, name::Symbol) -> NamedTerm

Query the named Hamiltonian components stored on sys.

has_term(sys::HamiltonianSystem, name::Symbol) -> Bool

Return true if sys carries a NamedTerm called name.

get_term(sys::HamiltonianSystem, name::Symbol) -> NamedTerm

Return the NamedTerm called name. Throws KeyError if absent.

n_particles(sys::HamiltonianSystem) -> Int
dims(sys::HamiltonianSystem) -> Int
degrees_of_freedom(sys::HamiltonianSystem) -> Int

Read-only accessors for the problem shape. Prefer these over direct field access so extensions stay stable across future Hamiltonian shapes.

n_particles(prob::HamiltonianProblem) -> Int
dims(prob::HamiltonianProblem) -> Int
masses(prob::HamiltonianProblem) -> AbstractVector{Float64}
charges(prob::HamiltonianProblem) -> AbstractVector{Float64}
speed_of_light(prob::HamiltonianProblem) -> Float64
kappas(prob::HamiltonianProblem) -> Vector{Float64}
params(prob::HamiltonianProblem) -> Vector{Float64}

Read-only accessors. masses and charges return views into the backing params vector (layout [m₁…mₙ, q₁…qₙ, c]); kappas returns the backing κ vector directly. All are O(1) and allocation-free but must be treated as read-only.