physicskit 0.1.0__py3-none-any.whl

physicskit/classical/tests/test_base_system.py

@@ -0,0 +1,113 @@
+"""Tests for the DynamicalSystem/ODESystem/HamiltonianSystem base-class
+machinery in physicskit.classical.core.base_system that every concrete system
+uses but that no single concrete system exercises end to end:
+``reset()`` (never called by any real system or example), the
+``force()``/``derivatives()`` defensive defaults for a non-separable
+Hamiltonian system with no ``_deriv_njit`` of its own (every real
+HamiltonianSystem subclass in this package is separable and never hits
+them), and both base classes' "unknown integration method" guard.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from physicskit.classical.core.base_system import HamiltonianSystem
+from physicskit.classical.systems.newtonian import FoucaultPendulum, ProjectileMotion
+
+
+class _MinimalNonSeparableHamiltonian(HamiltonianSystem):
+    """Smallest possible non-separable HamiltonianSystem subclass. Every
+    real system in this package is separable and provides its own
+    ``_force_njit``/``_deriv_njit``, so the base class's defensive
+    defaults for the non-separable, nothing-provided case are otherwise
+    dead code."""
+
+    separable = False
+
+    def __init__(self):
+        super().__init__([0.0], [0.0])
+
+    def kinetic_energy(self, p):
+        return 0.5 * p[0] ** 2
+
+    def potential_energy(self, q):
+        return 0.0
+
+
+def test_hamiltonian_system_reset_updates_state_and_time():
+    system = ProjectileMotion(q0=[0.0, 0.0], p0=[1.0, 1.0])
+    new_state = system.reset(state0=[5.0, 5.0, 2.0, 2.0], t0=3.0)
+    np.testing.assert_allclose(new_state, [5.0, 5.0, 2.0, 2.0])
+    assert system.t == 3.0
+    assert system.state is new_state
+
+
+def test_reset_with_no_state0_keeps_current_state_but_updates_time():
+    system = ProjectileMotion(q0=[1.0, 2.0], p0=[3.0, 4.0])
+    original_state = system.state
+    returned = system.reset(t0=7.0)
+    np.testing.assert_allclose(returned, original_state)
+    assert system.t == 7.0
+
+
+def test_hamiltonian_system_force_raises_for_non_separable_system_without_force():
+    system = _MinimalNonSeparableHamiltonian()
+    with pytest.raises(NotImplementedError):
+        system.force(system.q, 0.0)
+
+
+def test_hamiltonian_system_derivatives_raises_for_non_separable_system_without_deriv():
+    system = _MinimalNonSeparableHamiltonian()
+    with pytest.raises(NotImplementedError):
+        system.derivatives(0.0, system.state)
+
+
+def test_hamiltonian_system_integrate_rejects_symplectic_method_for_non_separable_system():
+    system = _MinimalNonSeparableHamiltonian()
+    with pytest.raises(ValueError):
+        system.integrate((0.0, 1.0), dt=0.1, method="verlet")
+
+
+def test_hamiltonian_system_integrate_rejects_unknown_method():
+    system = ProjectileMotion(q0=[0.0, 0.0], p0=[1.0, 1.0])
+    with pytest.raises(ValueError):
+        system.integrate((0.0, 1.0), dt=0.1, method="bogus")
+
+
+def test_hamiltonian_system_force_matches_gravity_for_separable_system():
+    system = ProjectileMotion(q0=[0.0, 10.0], p0=[1.0, 0.0])
+    fx, fy = system.force(system.q, 0.0)
+    assert fx == pytest.approx(0.0)
+    assert fy == pytest.approx(-system.m * system.g)
+
+
+def test_hamiltonian_system_derivatives_matches_auto_built_separable_deriv():
+    """ProjectileMotion without drag never sets self._deriv_njit itself,
+    so .derivatives() must fall back to auto-building it from force()
+    (HamiltonianSystem._ensure_deriv_njit's separable branch)."""
+    system = ProjectileMotion(q0=[0.0, 10.0], p0=[1.0, 0.0])
+    d = system.derivatives(0.0, system.state)
+    assert d.shape == (4,)
+    vx, vy, fx, fy = d
+    assert vx == pytest.approx(system.p[0] * system.mass_inv)
+    assert vy == pytest.approx(system.p[1] * system.mass_inv)
+    assert fx == pytest.approx(0.0)
+    assert fy == pytest.approx(-system.m * system.g)
+
+
+def test_ode_system_derivatives_matches_foucault_equations_by_hand():
+    system = FoucaultPendulum(q0=[1.0, 0.0], v0=[0.5, -0.2])
+    d = system.derivatives(0.0, system.state)
+    x, y, vx, vy = system.state
+    assert d[0] == pytest.approx(vx)
+    assert d[1] == pytest.approx(vy)
+    assert d[2] == pytest.approx(-(system.omega0**2) * x + 2 * system.omega_z * vy)
+    assert d[3] == pytest.approx(-(system.omega0**2) * y - 2 * system.omega_z * vx)
+
+
+def test_ode_system_integrate_rejects_unknown_method():
+    system = FoucaultPendulum(q0=[1.0, 0.0], v0=[0.0, 0.0])
+    with pytest.raises(ValueError):
+        system.integrate((0.0, 1.0), dt=0.1, method="bogus")

physicskit/classical/tests/test_chains.py

@@ -0,0 +1,84 @@
+"""Targeted checks for physicskit.classical.systems.chains.SineGordonChain.kink beyond
+energy conservation (covered in test_conservation.py): this exists
+because of two real bugs found while building the examples gallery --
+the original boost formula had a sign error, and using the default
+width (2.0, arbitrary) rather than sqrt(k/m) (1.0, for the default
+m=1, k=1) gave a profile that isn't actually a valid soliton and
+visibly relaxes/radiates instead of propagating cleanly.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from physicskit.classical.systems.chains import SineGordonChain
+
+
+def _front_position(q: np.ndarray) -> float:
+    """Interpolated lattice site where q crosses pi (the kink's center)."""
+    return float(np.interp(np.pi, q, np.arange(len(q))))
+
+
+def test_sine_gordon_chain_defaults_to_zero_state_when_q0_p0_omitted():
+    system = SineGordonChain(n=10)
+    np.testing.assert_allclose(system.q, np.zeros(10))
+    np.testing.assert_allclose(system.p, np.zeros(10))
+
+
+def test_kink_moves_in_the_requested_direction():
+    n = 200
+    q_right, p_right = SineGordonChain.kink(n, center=80, width=1.0, velocity=0.4, polarity=1)
+    q_left, p_left = SineGordonChain.kink(n, center=80, width=1.0, velocity=-0.4, polarity=1)
+
+    right_mover = SineGordonChain(n=n, q0=q_right, p0=p_right)
+    left_mover = SineGordonChain(n=n, q0=q_left, p0=p_left)
+
+    res_right = right_mover.integrate((0, 50), dt=0.005, method="yoshida4")
+    res_left = left_mover.integrate((0, 50), dt=0.005, method="yoshida4")
+
+    assert _front_position(res_right.q[-1]) > _front_position(res_right.q[0])
+    assert _front_position(res_left.q[-1]) < _front_position(res_left.q[0])
+
+
+def test_kink_with_matched_width_keeps_its_shape():
+    """width = sqrt(k/m) = 1 (the default) is the only width for which
+    the profile is a genuine static/moving solution; its steepness
+    should stay essentially constant as it propagates."""
+    n = 200
+    q0, p0 = SineGordonChain.kink(n, center=60, width=1.0, velocity=0.3, polarity=1)
+    system = SineGordonChain(n=n, q0=q0, p0=p0)
+    result = system.integrate((0, 150), dt=0.005, method="yoshida4")
+
+    def measured_width(q):
+        return 2.0 / np.max(np.abs(np.diff(q)))
+
+    w0 = measured_width(result.q[0])
+    wf = measured_width(result.q[-1])
+    assert abs(wf - w0) / w0 < 0.15
+
+
+def test_kink_with_mismatched_width_visibly_relaxes():
+    """A width that does NOT match sqrt(k/m) is not a genuine soliton
+    solution; its steepness should visibly change (relax toward the
+    natural width) as the system evolves -- the behavior the width=1.0
+    fix above avoids."""
+    n = 200
+    q0, p0 = SineGordonChain.kink(n, center=100, width=3.0, velocity=0.0, polarity=1)
+    system = SineGordonChain(n=n, q0=q0, p0=p0)
+    result = system.integrate((0, 100), dt=0.005, method="yoshida4")
+
+    def measured_width(q):
+        return 2.0 / np.max(np.abs(np.diff(q)))
+
+    w0 = measured_width(result.q[0])
+    wf = measured_width(result.q[-1])
+    assert abs(wf - w0) / w0 > 0.15
+
+
+def test_kink_rejects_superluminal_velocity():
+    import pytest
+
+    with pytest.raises(ValueError):
+        SineGordonChain.kink(100, center=50, width=1.0, velocity=1.0)
+    with pytest.raises(ValueError):
+        SineGordonChain.kink(100, center=50, width=1.0, velocity=-1.5)

physicskit/classical/tests/test_conservation.py

@@ -0,0 +1,244 @@
+"""Verify |H(t) - H(0)| / |H(0)| < 1e-6 over 10**5 integration steps for
+every conservative system in physicskit.classical, using each system's default
+symplectic integrator (Yoshida4 for separable Hamiltonians,
+implicit-midpoint for non-separable Lagrangian/rigid-body systems).
+
+Each system's timestep below was chosen (see the module-level
+``N_STEPS``/tolerance) so that the discretization error -- which for a
+2nd/4th-order symplectic method scales as a fixed power of dt -- comfortably
+clears the 1e-6 relative-drift bar over exactly 10**5 steps; see
+individual test docstrings for the physical timescale each dt resolves.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from physicskit.classical.systems.chains import FPUTChain, HarmonicChain, SineGordonChain
+from physicskit.classical.systems.hamiltonian import HenonHeilesSystem, PendulumSwarm
+from physicskit.classical.systems.lagrangian import BeadOnRotatingHoop, CoupledOscillators, DoublePendulum, ElasticPendulum
+from physicskit.classical.systems.newtonian import FoucaultPendulum, KeplerSystem, ProjectileMotion
+from physicskit.classical.systems.rotations import EulerTop, HeavySymmetricTop
+from physicskit.classical.utils.conservation import lrl_drift, relative_energy_drift
+
+N_STEPS = 100_000
+TOL = 1e-6
+
+
+def _assert_conserved(system, dt, method, n_steps=N_STEPS, tol=TOL):
+    result = system.integrate((0.0, n_steps * dt), dt=dt, method=method)
+    assert len(result.t) - 1 == n_steps
+    drift = relative_energy_drift(result.energy)
+    assert np.max(drift) < tol, f"energy drift {np.max(drift):.3e} exceeds tolerance {tol:.1e}"
+    return result
+
+
+def test_projectile_motion_conserves_energy():
+    """Free fall with an oblique launch velocity (the "cannonball"
+    problem), unconstrained over 1e5 steps (~100s of flight, well past
+    where a real cannonball would have hit the ground -- gravity alone
+    is still exactly conservative for arbitrarily long unconstrained
+    free fall)."""
+    system = ProjectileMotion.from_launch(speed=20.0, angle_deg=45.0, g=9.81)
+    _assert_conserved(system, dt=1e-3, method="yoshida4")
+
+
+def test_projectile_motion_matches_analytic_parabola():
+    """Over the ~2s a real cannonball is actually airborne, a constant
+    force is exactly separable, so the symplectic integrator should
+    reproduce Galileo's closed-form parabola to floating-point
+    precision, not merely to some small tolerance."""
+    system = ProjectileMotion.from_launch(speed=20.0, angle_deg=45.0, g=9.81)
+    result = system.integrate((0.0, 2.0), dt=1e-3, method="yoshida4")
+    x_analytic, y_analytic = ProjectileMotion.analytic_trajectory(20.0, 45.0, 9.81, result.t)
+    assert np.max(np.abs(result.q[:, 0] - x_analytic)) < 1e-9
+    assert np.max(np.abs(result.q[:, 1] - y_analytic)) < 1e-9
+
+
+def test_projectile_motion_with_drag_dissipates_energy_and_rejects_symplectic_methods():
+    """Quadratic air drag makes the system genuinely non-conservative:
+    energy must decrease monotonically, and requesting a symplectic
+    method that can't see the (velocity-dependent) drag force must be
+    refused rather than silently ignoring it."""
+    system = ProjectileMotion.from_launch(speed=20.0, angle_deg=45.0, g=9.81, drag_coeff=0.05)
+    with pytest.raises(ValueError):
+        system.integrate((0.0, 1.0), dt=1e-3, method="yoshida4")
+    result = system.integrate((0.0, 2.0), dt=1e-3, method="rk4")
+    assert np.all(np.diff(result.energy) <= 1e-9)
+    assert result.energy[-1] < result.energy[0]
+
+
+def test_kepler_pure_conserves_energy_and_lrl():
+    """Pure 1/r Kepler orbit: energy AND the LRL vector should both be
+    conserved (no precession without a perturbation)."""
+    system = KeplerSystem.from_orbital_elements(a=1.0, e=0.5, k=1.0, mu=1.0)
+    lrl0 = system.lrl_vector()
+    result = _assert_conserved(system, dt=1e-3, method="yoshida4")
+    drift = lrl_drift(system, result.q, result.p)
+    assert np.max(drift) / np.linalg.norm(lrl0) < 1e-4
+
+
+def test_kepler_perturbed_conserves_energy():
+    """With the post-Newtonian 1/r**3 correction switched on, the orbit
+    precesses (LRL direction rotates) but total energy remains conserved."""
+    system = KeplerSystem.from_orbital_elements(a=1.0, e=0.3, k=1.0, mu=1.0, c_pn=0.01)
+    _assert_conserved(system, dt=1e-3, method="yoshida4")
+
+
+def test_foucault_pendulum_conserves_energy():
+    """The Coriolis term is velocity-perpendicular and does no work, so
+    energy is exactly conserved even as the swing plane precesses;
+    implicit midpoint preserves this quadratic invariant to machine
+    precision for this linear system."""
+    system = FoucaultPendulum.from_deflection(amplitude=1.0, latitude_deg=48.85)
+    _assert_conserved(system, dt=1e-3, method="implicit_midpoint")
+
+
+def test_foucault_pendulum_matches_analytic_precession():
+    """Compare the numerical trajectory against the closed-form
+    small-oscillation solution, and check the swing plane is unwound
+    (stays near y=0) in the frame corotating at ``omega_z``."""
+    system = FoucaultPendulum.from_deflection(amplitude=1.0, latitude_deg=48.85)
+    result = system.integrate((0.0, 200.0), dt=1e-3, method="implicit_midpoint")
+    x_analytic, y_analytic = FoucaultPendulum.analytic_solution([1.0, 0.0], [0.0, 0.0], system.omega0, system.omega_z, result.t)
+    assert np.max(np.abs(result.y[:, 0] - x_analytic)) < 1e-5
+    assert np.max(np.abs(result.y[:, 1] - y_analytic)) < 1e-5
+
+    x_rot, y_rot = FoucaultPendulum.to_corotating_frame(result.y[:, 0], result.y[:, 1], result.t, system.omega_z)
+    assert np.max(np.abs(y_rot)) < 1e-3
+
+
+@pytest.mark.slow
+def test_double_pendulum_conserves_energy():
+    """Chaotic, non-separable system; validated via the implicit-midpoint
+    symplectic integrator on the Legendre-transformed Hamiltonian."""
+    system = DoublePendulum([2.0, 1.0], [0.5, -0.3])
+    _assert_conserved(system, dt=3e-5, method="implicit_midpoint", n_steps=10_000)
+
+
+@pytest.mark.slow
+def test_bead_on_rotating_hoop_conserves_energy():
+    system = BeadOnRotatingHoop(0.3, 0.0, omega=3.0)
+    _assert_conserved(system, dt=2.2e-5, method="implicit_midpoint", n_steps=10_000)
+
+
+@pytest.mark.slow
+def test_coupled_oscillators_conserve_energy():
+    system = CoupledOscillators([0.1, -0.2, 0.15], [0.0, 0.0, 0.0], n=3)
+    _assert_conserved(system, dt=1e-4, method="implicit_midpoint", n_steps=10_000)
+
+
+def test_henon_heiles_conserves_energy():
+    system = HenonHeilesSystem(np.array([0.0, 0.3]), np.array([0.3, 0.0]))
+    _assert_conserved(system, dt=5e-3, method="yoshida4")
+
+
+@pytest.mark.slow
+def test_elastic_pendulum_conserves_energy():
+    """2-DOF nonlinear (stretch, swing) Lagrangian system; validated via
+    implicit midpoint on the Legendre-transformed Hamiltonian, same as
+    DoublePendulum."""
+    system = ElasticPendulum([0.1, 0.05], [0.0, 0.0])
+    _assert_conserved(system, dt=2e-5, method="implicit_midpoint", n_steps=10_000)
+
+
+@pytest.mark.slow
+def test_pendulum_swarm_conserves_energy_and_liouville_area():
+    """Every particle in the swarm independently conserves energy over
+    a 1e4-step run, and -- checked separately over a shorter
+    window, before the patch shears into a filament thin enough that a
+    convex-hull area estimate starts overstating it -- the occupied
+    phase-space area (a proxy for Liouville's theorem) is preserved."""
+    system = PendulumSwarm.from_box(1.0, 0.0, 0.05, 0.05, n=200, seed=1)
+    _assert_conserved(system, dt=1e-3, method="yoshida4", n_steps=10_000)
+
+    system2 = PendulumSwarm.from_box(1.0, 0.0, 0.05, 0.05, n=200, seed=1)
+    area0 = system2.phase_space_area()
+    system2.integrate((0.0, 5.0), dt=1e-3, method="yoshida4")
+    area1 = system2.phase_space_area()
+    assert abs(area1 - area0) / area0 < 0.05
+
+
+def test_harmonic_chain_conserves_energy():
+    rng = np.random.default_rng(0)
+    n = 16
+    system = HarmonicChain(rng.normal(0, 0.1, n), np.zeros(n), k=1.0)
+    _assert_conserved(system, dt=1e-2, method="yoshida4")
+
+
+def test_fput_chain_conserves_energy():
+    """N=32 Fermi-Pasta-Ulam-Tsingou beta-lattice."""
+    system = FPUTChain(n=32, beta=0.7, mode=1, amplitude=0.5)
+    _assert_conserved(system, dt=5e-2, method="yoshida4")
+
+
+def test_fput_chain_shows_mode_recurrence():
+    """The energy initially placed in the first normal mode should
+    remain the dominant mode throughout (the FPUT non-ergodicity
+    signature), not spread evenly across all 32 modes."""
+    system = FPUTChain(n=32, beta=0.7, mode=1, amplitude=0.5)
+    e0 = system.energy()
+    result = system.integrate((0.0, 5000.0), dt=5e-2, method="yoshida4")
+    energies = system.modal_energies(result.q[-1], result.p[-1])
+    assert energies[0] / e0 > 0.5
+
+
+def test_sine_gordon_chain_conserves_energy():
+    q0, p0 = SineGordonChain.kink(100, center=50, width=1.0, velocity=0.2)
+    system = SineGordonChain(n=100, q0=q0, p0=p0)
+    _assert_conserved(system, dt=1e-2, method="yoshida4")
+
+
+def test_euler_top_conserves_energy_and_angular_momentum():
+    """Torque-free asymmetric top: both energy and |L|^2 are quadratic
+    invariants exactly preserved by implicit midpoint."""
+    system = EulerTop([0.01, 1.0, 0.01], I1=1.0, I2=2.0, I3=3.0)
+    L0 = system.angular_momentum_squared()
+    _assert_conserved(system, dt=1e-3, method="implicit_midpoint")
+    L1 = system.angular_momentum_squared()
+    assert abs(L1 - L0) / L0 < 1e-6
+
+
+def test_euler_top_intermediate_axis_instability():
+    """Spinning (almost) exactly about the intermediate-inertia axis
+    (I1 < I2 < I3) must show the tumbling instability: the other two
+    body-frame components grow far beyond their tiny initial values."""
+    system = EulerTop([0.01, 1.0, 0.01], I1=1.0, I2=2.0, I3=3.0)
+    result = system.integrate((0.0, 100.0), dt=1e-3, method="implicit_midpoint")
+    assert np.max(np.abs(result.y[:, 0])) > 0.5  # w1 tumbles far above its 0.01 start
+
+
+def test_euler_top_stable_axis_no_tumbling():
+    """Spinning about the smallest-inertia axis is stable: the small
+    transverse perturbations stay small for the whole integration."""
+    system = EulerTop([1.0, 0.01, 0.01], I1=1.0, I2=2.0, I3=3.0)
+    result = system.integrate((0.0, 100.0), dt=1e-3, method="implicit_midpoint")
+    assert np.max(np.abs(result.y[:, 1])) < 0.1
+    assert np.max(np.abs(result.y[:, 2])) < 0.1
+
+
+@pytest.mark.slow
+def test_heavy_symmetric_top_conserves_energy():
+    system = HeavySymmetricTop([0.0, 0.5, 0.0], [0.0, 0.0, 20.0], I1=1.0, I3=0.5, M=1.0, l=1.0, g=9.81)
+    _assert_conserved(system, dt=5e-5, method="implicit_midpoint", n_steps=10_000)
+
+
+@pytest.mark.parametrize(
+    "system_factory,dt",
+    [
+        (lambda: KeplerSystem.from_orbital_elements(a=1.0, e=0.5), 1e-3),
+        (lambda: HenonHeilesSystem(np.array([0.0, 0.3]), np.array([0.3, 0.0])), 5e-3),
+    ],
+)
+def test_verlet_and_yoshida4_agree_to_leading_order(system_factory, dt):
+    """Sanity check that the 2nd-order Verlet and 4th-order Yoshida4
+    backends integrate the same separable system to consistent, small
+    energy drift (Yoshida4 should be at least as good as Verlet)."""
+    sys_v = system_factory()
+    sys_y = system_factory()
+    res_v = sys_v.integrate((0.0, 2000 * dt), dt=dt, method="verlet")
+    res_y = sys_y.integrate((0.0, 2000 * dt), dt=dt, method="yoshida4")
+    drift_v = np.max(relative_energy_drift(res_v.energy))
+    drift_y = np.max(relative_energy_drift(res_y.energy))
+    assert drift_y <= drift_v * 10  # Yoshida4 is not meaningfully worse than Verlet

physicskit/classical/tests/test_conservation_utils.py

@@ -0,0 +1,47 @@
+"""Direct tests for the standalone helpers in
+physicskit.classical.utils.conservation that test_conservation.py's
+end-to-end energy-drift checks never call: energy_drift() (only its
+relative sibling is used there), angular_momentum_2d()/
+angular_momentum_drift() (no test currently checks angular momentum at
+all), and relative_energy_drift()'s zero-initial-energy edge case."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from physicskit.classical.utils.conservation import (
+    angular_momentum_2d,
+    angular_momentum_drift,
+    energy_drift,
+    relative_energy_drift,
+)
+
+
+def test_energy_drift_is_absolute_deviation_from_initial_value():
+    energy = np.array([10.0, 10.5, 9.5, 10.0])
+    drift = energy_drift(energy)
+    np.testing.assert_allclose(drift, [0.0, 0.5, 0.5, 0.0])
+
+
+def test_relative_energy_drift_is_infinite_when_initial_energy_is_zero():
+    energy = np.array([0.0, 1.0, -1.0])
+    drift = relative_energy_drift(energy)
+    assert np.all(np.isinf(drift))
+
+
+def test_angular_momentum_2d_matches_cross_product_formula():
+    q = np.array([[1.0, 0.0], [0.0, 2.0]])
+    p = np.array([[0.0, 1.0], [3.0, 0.0]])
+    L = angular_momentum_2d(q, p)
+    np.testing.assert_allclose(L, [1.0 * 1.0 - 0.0 * 0.0, 0.0 * 0.0 - 2.0 * 3.0])
+
+
+def test_angular_momentum_drift_is_zero_for_a_conserved_circular_orbit():
+    """A particle moving on a circle at constant angular speed has
+    exactly conserved angular momentum, so drift should be exactly
+    zero at every sample."""
+    theta = np.linspace(0.0, 2.0 * np.pi, 50, endpoint=False)
+    q = np.column_stack([np.cos(theta), np.sin(theta)])
+    p = np.column_stack([-np.sin(theta), np.cos(theta)])
+    drift = angular_momentum_drift(q, p)
+    np.testing.assert_allclose(drift, 0.0, atol=1e-12)

physicskit/classical/tests/test_hamiltonian.py

@@ -0,0 +1,44 @@
+"""Tests for physicskit.classical.systems.hamiltonian's action-angle helper and
+PendulumSwarm.per_particle_energy(), neither of which any other test in
+the suite calls (test_conservation.py only checks PendulumSwarm's total
+energy/Liouville area, and pendulum_action_angle isn't used anywhere)."""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from physicskit.classical.systems.hamiltonian import PendulumSwarm, pendulum_action_angle
+
+
+def test_pendulum_action_angle_small_oscillation_limit_matches_harmonic_period():
+    """As E -> -g/l (the bottom of the well), a pendulum's period should
+    approach the small-oscillation harmonic result T = 2*pi/sqrt(g/l)."""
+    g_over_l = 2.0
+    _, period = pendulum_action_angle(-g_over_l + 1e-6, g_over_l)
+    assert period == pytest.approx(2.0 * np.pi / np.sqrt(g_over_l), rel=1e-3)
+
+
+def test_pendulum_action_angle_rejects_energy_outside_librating_range():
+    g_over_l = 1.0
+    with pytest.raises(ValueError):
+        pendulum_action_angle(g_over_l, g_over_l)
+    with pytest.raises(ValueError):
+        pendulum_action_angle(-g_over_l, g_over_l)
+    with pytest.raises(ValueError):
+        pendulum_action_angle(2.0 * g_over_l, g_over_l)
+
+
+def test_pendulum_swarm_per_particle_energy_sums_to_the_total_energy():
+    swarm = PendulumSwarm([0.1, 0.2, 0.3], [0.05, -0.05, 0.0], g_over_l=1.5)
+    per_particle = swarm.per_particle_energy()
+    assert per_particle.shape == (3,)
+    assert np.sum(per_particle) == pytest.approx(swarm.energy())
+
+
+def test_pendulum_swarm_per_particle_energy_accepts_explicit_state_override():
+    swarm = PendulumSwarm([0.1, 0.2, 0.3], [0.05, -0.05, 0.0], g_over_l=1.5)
+    default = swarm.per_particle_energy()
+    overridden = swarm.per_particle_energy(q=np.zeros(3), p=np.zeros(3))
+    np.testing.assert_allclose(overridden, -1.5)
+    assert not np.allclose(default, overridden)

physicskit/classical/tests/test_integrators.py

@@ -0,0 +1,123 @@
+"""Direct unit tests for physicskit.classical.core.integrators, independent of any
+physicskit.classical.systems class. These exercise the four integrators (and the
+make_separable_derivatives helper) against a plain harmonic oscillator
+and a simple exponential-decay ODE with known analytic solutions, so a
+regression here is caught at the numerical-core level rather than only
+showing up as a mysterious failure in some system built on top of it.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numba import njit
+
+from physicskit.classical.core.integrators import (
+    implicit_midpoint_integrate,
+    implicit_midpoint_step,
+    make_separable_derivatives,
+    rk4_integrate,
+    velocity_verlet_integrate,
+    yoshida4_integrate,
+)
+
+
+@njit(cache=False)
+def _sho_force(q, t):
+    return -q  # harmonic oscillator, k = m = 1
+
+
+@njit(cache=False)
+def _exp_decay_deriv(t, y):
+    return -y
+
+
+def _sho_energy(q, p):
+    return 0.5 * q**2 + 0.5 * p**2
+
+
+def test_rk4_matches_analytic_exponential_decay():
+    y0 = np.array([1.0])
+    dt = 1e-3
+    n_steps = 1000
+    ts, ys = rk4_integrate(_exp_decay_deriv, y0, 0.0, n_steps, dt)
+    analytic = np.exp(-ts)
+    assert np.max(np.abs(ys[:, 0] - analytic)) < 1e-9
+
+
+def test_verlet_and_yoshida4_conserve_harmonic_oscillator_energy():
+    q0, p0 = np.array([1.0]), np.array([0.0])
+    dt, n_steps = 0.01, 50_000
+    mass_inv = 1.0
+
+    ts, qs, ps = velocity_verlet_integrate(_sho_force, mass_inv, q0, p0, 0.0, n_steps, dt)
+    E = _sho_energy(qs[:, 0], ps[:, 0])
+    assert np.max(np.abs(E - E[0])) / E[0] < 1e-3  # 2nd order, bounded oscillation
+
+    ts, qs, ps = yoshida4_integrate(_sho_force, mass_inv, q0, p0, 0.0, n_steps, dt)
+    E4 = _sho_energy(qs[:, 0], ps[:, 0])
+    assert np.max(np.abs(E4 - E4[0])) / E4[0] < 1e-8  # 4th order: much tighter at the same dt
+
+
+def test_yoshida4_more_accurate_than_verlet_at_fixed_dt():
+    """4th order should beat 2nd order by several orders of magnitude
+    at a dt small enough for both to be in their asymptotic regime."""
+    q0, p0 = np.array([1.0]), np.array([0.0])
+    dt, n_steps = 0.02, 5_000
+    mass_inv = 1.0
+
+    _, qs_v, ps_v = velocity_verlet_integrate(_sho_force, mass_inv, q0, p0, 0.0, n_steps, dt)
+    _, qs_y, ps_y = yoshida4_integrate(_sho_force, mass_inv, q0, p0, 0.0, n_steps, dt)
+
+    drift_v = np.max(np.abs(_sho_energy(qs_v[:, 0], ps_v[:, 0]) - 0.5))
+    drift_y = np.max(np.abs(_sho_energy(qs_y[:, 0], ps_y[:, 0]) - 0.5))
+    assert drift_y < drift_v * 1e-3
+
+
+def test_implicit_midpoint_conserves_harmonic_oscillator_energy():
+    y0 = np.array([1.0, 0.0])
+
+    @njit(cache=False)
+    def deriv(t, y):
+        out = np.empty(2)
+        out[0] = y[1]
+        out[1] = -y[0]
+        return out
+
+    dt, n_steps = 0.01, 50_000
+    ts, ys = implicit_midpoint_integrate(deriv, y0, 0.0, n_steps, dt)
+    E = _sho_energy(ys[:, 0], ys[:, 1])
+    assert np.max(np.abs(E - E[0])) / E[0] < 1e-10
+
+
+def test_implicit_midpoint_step_exactly_preserves_norm_for_a_rotation_generator():
+    """For dy/dt = A y with A skew-symmetric (a pure rotation vector
+    field), |y|^2 is a quadratic invariant; a single implicit-midpoint
+    step -- solved via the Cayley transform of A, not the matrix
+    exponential -- should still preserve |y| exactly (to machine
+    precision) even though it does not reproduce the exact rotation
+    angle. This is a direct check of the step formula itself, distinct
+    from the aggregate energy-conservation checks elsewhere."""
+
+    @njit(cache=False)
+    def deriv(t, y):
+        out = np.empty(2)
+        out[0] = -y[1]
+        out[1] = y[0]
+        return out
+
+    y0 = np.array([1.0, 0.0])
+    dt = 0.1
+    y1 = implicit_midpoint_step(deriv, 0.0, y0, dt)
+
+    assert abs(np.linalg.norm(y1) - np.linalg.norm(y0)) < 1e-12
+    assert y1[1] > 0  # rotated counter-clockwise, matching the sign of the generator
+
+
+def test_make_separable_derivatives_matches_verlet_force():
+    mass_inv = 1.0
+    ndof = 1
+    deriv = make_separable_derivatives(_sho_force, mass_inv, ndof)
+    y = np.array([0.5, -0.3])
+    dy = deriv(0.0, y)
+    # dq/dt = p/m, dp/dt = force(q) = -q
+    assert np.allclose(dy, [-0.3, -0.5])