Statistics

TrajectoryData

Per-particle position trajectories extracted from a HamiltonianSolution.

Fields

• trajectories::Vector{Matrix{Float64}}: One (n_points, dims) matrix per particle, where rows are time steps and columns are spatial dimensions.
• initial_positions::Vector{Vector{Float64}}: Position of each particle at the first selected time step.
• final_positions::Vector{Vector{Float64}}: Position of each particle at the last selected time step.
• n_particles::Int: Number of particles.
• dims::Int: Spatial dimension.

compute_trajectory_data(sol, n_particles, dims; stride=1) -> TrajectoryData

Extract per-particle position trajectories from a HamiltonianSolution.

Arguments

• sol::HamiltonianSolution: Completed simulation result.
• n_particles::Int: Number of particles encoded in sol.
• dims::Int: Spatial dimension (must match dims(sol.prob)).

Keywords

• stride=1: Downsample factor; every stride-th timestep is included.

Returns

• TrajectoryData with one (n_points, dims) trajectory matrix per particle.

EnergyData

Complete energy timeseries and conservation statistics for an n-body simulation.

Fields

• t::Vector{Float64}: Time points.
• total_energy::Vector{Float64}: Total Hamiltonian H = KE + V at each time point.
• kinetic_energy::Vector{Float64}: Total kinetic energy.
• total_potential_energy::Vector{Float64}: Sum of all pair Weber potentials.
• total_zollner_residual::Vector{Float64}: Summed Zöllner extra potential (zero when Zöllner extension is disabled).
• pair_energies::Dict{Tuple{Int,Int},PairEnergyData}: Per-pair energy decomposition.
• statistics::EnergyStatistics: Energy conservation quality metrics.
• hamiltonian_validation_error::Vector{Float64}: |Hmanual − Hcompiled| at each time point, cross-checking the manual decomposition against the compiled Hamiltonian.
• n_particles::Int, n_pairs::Int: System size.

PairEnergyData

Energy decomposition timeseries for a single particle pair (i, j).

Fields

• pair::Tuple{Int,Int}: Particle indices (i < j).
• kappa::Float64: Zöllner coupling factor κ_ij (1.0 for standard Weber).
• coulomb_term::Vector{Float64}: κ·qᵢqⱼ/r — Coulomb part of the potential.
• velocity_term::Vector{Float64}: −κ·qᵢqⱼ/r·ṙ²/(2c²) — velocity correction.
• zollner_extra_potential::Vector{Float64}: (κ−1)·qᵢqⱼ/r·(...) — extra potential from the Zöllner mismatch (zero when Zöllner is disabled).
• total_pair_potential::Vector{Float64}: Sum of all pair potential contributions.
• radial_velocity::Vector{Float64}: Radial velocity ṙ = dr/dt.

EnergyStatistics

Summary statistics for energy conservation over a simulation.

Local error is the step-to-step absolute change |Et − E{t−1}|. Global error ratio is Et / Einitial (ideal value: 1.0). Global error percentage is |Et − Einitial| / |E_initial| × 100.

Fields

• local_error_max, local_error_min, local_error_avg::Float64: Maximum, minimum, and mean step-to-step energy change.
• global_error_ratio_max, global_error_ratio_min, global_error_ratio_avg::Float64: Maximum, minimum, and mean of Et / Einitial.
• global_error_percent_max, global_error_percent_min, global_error_percent_avg::Float64: Maximum, minimum, and mean global error as a percentage.

compute_energy_timeseries(sol; stride=1) -> EnergyData

Compute the full energy decomposition timeseries from a HamiltonianSolution.

Evaluates kinetic energy, per-pair Weber potentials, and the compiled Hamiltonian at each selected timestep. The hamiltonian_validation_error field cross-checks the manual decomposition against the Symbolics-compiled function.

Keywords

• stride=1: Downsample factor; every stride-th timestep is included.

Returns

• EnergyData with all energy components and conservation statistics.

PairForceData

Comprehensive Weber force timeseries for a single particle pair (i, j).

Forces are decomposed into a vector form (3 velocity/acceleration correction terms) and a radial form (2 terms), both sharing the same κ-scaled Coulomb base.

Fields

• t::Vector{Float64}: Time points.
• dims::Int: Spatial dimension.
• pair::Tuple{Int,Int}: Particle indices (i, j).
• kappa::Float64: Zöllner coupling factor κ_ij (1.0 = standard Weber).
• charge_product::Float64: k = qᵢqⱼ; sign determines repulsion/attraction.
• force::Vector{Vector{Float64}}: Total force vector at each time point.
• magnitude::Vector{Float64}: |F| at each time point.
• stats::ForceStatistics: Min/max/mean/range of |F|.
• coulomb::Vector{Vector{Float64}}: κ-scaled Coulomb base force vector.
• vector_term_vv, vector_term_ra, vector_term_rv2: Three correction terms in the vector form decomposition.
• radial_term_rdot2, radial_term_rddot: Two correction terms in the radial form decomposition.
• zollner_extra_magnitude::Vector{Float64}: |(κ−1)·F_Coulomb| (zero for standard Weber without Zöllner).
• phase_space::PhaseSpaceData: Pair phase-space portrait (r, ṙ, θ, L).

ForceStatistics

Summary statistics over a force magnitude timeseries.

Fields

• min::Float64: Minimum force magnitude.
• max::Float64: Maximum force magnitude.
• mean::Float64: Mean force magnitude.
• range::Float64: max − min.

PhaseSpaceData

Pair (r, ṙ) phase-space timeseries extracted alongside force data.

Fields

• t::Vector{Float64}: Time points.
• separation_distance::Vector{Float64}: Interparticle separation r(t).
• radial_velocity::Vector{Float64}: Radial velocity ṙ(t) = dr/dt.
• theta::Union{Vector{Float64},Nothing}: Polar angle θ for 2D/3D; nothing in 1D.
• angular_momentum::Union{Vector{Float64},Nothing}: Angular momentum magnitude; nothing in 1D.

compute_pair_force_timeseries(sol, pair, n_particles, dims, masses, charges, c; stride=1) -> PairForceData

Compute the Weber force decomposition for one particle pair over a simulation.

Both the vector form and the radial form of the Weber force are evaluated, together with phase-space data (r, ṙ, θ, L).

Arguments

• sol::HamiltonianSolution: Completed simulation.
• pair::Tuple{Int,Int}: Particle pair indices (order does not matter; i ≠ j).
• n_particles::Int, dims::Int: System geometry.
• masses, charges::Vector{Float64}: Physical parameters.
• c::Float64: Speed of light.

Keywords

• stride=1: Downsample factor; every stride-th timestep is included.

Returns

• PairForceData with force vectors, decompositions, statistics, and phase-space data.

MomentumData

Total linear and angular momentum timeseries from a simulation.

Momentum conservation (constant |P| and |L|) is the primary quality indicator for simulations without external forces.

Fields

• t::Vector{Float64}: Time points.
• linear_momentum::Vector{Vector{Float64}}: Total momentum vector P(t).
• linear_momentum_components::Matrix{Float64}: (n_points, dims) matrix of individual momentum components.
• linear_momentum_magnitude::Vector{Float64}: |P(t)|.
• angular_momentum: nothing (1D), scalar Vector{Float64} (2D Lz values), or Vector{Vector{Float64}} (3D, full L vector per timestep).
• angular_momentum_magnitude::Union{Nothing,Vector{Float64}}: |L(t)|; nothing in 1D.
• n_particles::Int, dims::Int: System geometry.

compute_momentum_timeseries(solution; stride=1) -> MomentumData

Compute total linear and angular momentum timeseries from a HamiltonianSolution.

Keywords

• stride=1: Downsample factor; every stride-th timestep is included.

Returns

• MomentumData with linear and angular momentum at each selected timestep.