physicskit 0.1.0__py3-none-any.whl

physicskit/chaos/tests/test_bifurcation.py

@@ -0,0 +1,132 @@
+import numpy as np
+import pytest
+
+from physicskit.chaos.systems.continuous import DrivenPendulum, Duffing
+from physicskit.chaos.systems.maps import LogisticMap
+from physicskit.chaos.visualizers.bifurcation import (
+    bifurcation_diagram,
+    map_bifurcation_sampler,
+    stroboscopic_bifurcation_sampler,
+)
+
+
+def test_bifurcation_diagram_flattens_and_repeats_params_correctly():
+    def sample_fn(param):
+        return np.array([param, param + 1.0])
+
+    params, samples = bifurcation_diagram([0.0, 10.0], sample_fn)
+    np.testing.assert_allclose(params, [0.0, 0.0, 10.0, 10.0])
+    np.testing.assert_allclose(samples, [0.0, 1.0, 10.0, 11.0])
+
+
+def test_bifurcation_diagram_with_multiple_threads_matches_sequential():
+    def sample_fn(param):
+        return np.array([param, param + 1.0])
+
+    param_values = np.linspace(0.0, 10.0, 15)
+    params_seq, samples_seq = bifurcation_diagram(param_values, sample_fn, n_jobs=1)
+    params_par, samples_par = bifurcation_diagram(param_values, sample_fn, n_jobs=4, show_progress=True)
+    np.testing.assert_allclose(params_par, params_seq)
+    np.testing.assert_allclose(samples_par, samples_seq)
+
+
+def test_map_bifurcation_sampler_shows_fixed_point_below_r3():
+    """Below r=3, the logistic map converges to a stable fixed point: every
+    surviving sample should be (nearly) identical."""
+    sampler = map_bifurcation_sampler(lambda r: LogisticMap(r=r), state0=np.array([0.5]), n_transient=200, n_keep=20)
+    samples = sampler(2.5)
+    assert np.ptp(samples) < 1e-6
+
+
+def test_map_bifurcation_sampler_shows_period_two_cycle_above_r3():
+    """Just above r=3, the logistic map settles into a period-2 cycle: the
+    surviving samples should cluster into exactly two distinct values."""
+    sampler = map_bifurcation_sampler(lambda r: LogisticMap(r=r), state0=np.array([0.5]), n_transient=500, n_keep=20)
+    samples = sampler(3.2)
+    unique_values = np.unique(np.round(samples, decimals=4))
+    assert unique_values.size == 2
+
+
+def test_map_bifurcation_sampler_shows_many_values_when_chaotic():
+    """At r=3.9 (chaotic), the surviving samples should spread over many
+    distinct values rather than clustering into a small cycle."""
+    sampler = map_bifurcation_sampler(lambda r: LogisticMap(r=r), state0=np.array([0.5]), n_transient=500, n_keep=50)
+    samples = sampler(3.9)
+    unique_values = np.unique(np.round(samples, decimals=3))
+    assert unique_values.size > 20
+
+
+def test_bifurcation_diagram_with_map_sampler_over_a_parameter_sweep():
+    sampler = map_bifurcation_sampler(lambda r: LogisticMap(r=r), state0=np.array([0.5]), n_transient=200, n_keep=10)
+    r_values = np.linspace(2.4, 4.0, 20)
+    params, samples = bifurcation_diagram(r_values, sampler)
+    # n_keep=10 plus the trajectory's initial state (row 0) surviving the
+    # transient slice, times 20 parameter values.
+    assert params.shape == samples.shape == (220,)
+    assert np.all(np.isfinite(samples))
+    assert np.all((samples >= 0.0) & (samples <= 1.0))
+
+
+def test_stroboscopic_bifurcation_sampler_on_duffing_is_finite_and_correct_shape():
+    omega = 1.2
+    period = 2.0 * np.pi / omega
+    sampler = stroboscopic_bifurcation_sampler(
+        lambda gamma: Duffing(delta=0.3, alpha=-1.0, beta=1.0, gamma=gamma, omega=omega),
+        state0=np.array([0.1, 0.0]),
+        sample_period=period,
+        n_transient_periods=20,
+        n_keep_periods=5,
+        component=0,
+        dt=0.05,
+    )
+    samples = sampler(0.3)
+    assert samples.shape == (5,)
+    assert np.all(np.isfinite(samples))
+
+
+def test_stroboscopic_bifurcation_sampler_shows_fixed_point_for_weak_forcing():
+    """With no forcing at all, the (linear, damped) oscillator settles to a
+    fixed point: every stroboscopic sample should be (nearly) identical."""
+    omega = 1.0
+    period = 2.0 * np.pi / omega
+    sampler = stroboscopic_bifurcation_sampler(
+        lambda gamma: Duffing(delta=0.3, alpha=1.0, beta=0.0, gamma=gamma, omega=omega),
+        state0=np.array([1.0, 0.0]),
+        sample_period=period,
+        n_transient_periods=30,
+        n_keep_periods=5,
+        component=0,
+        dt=0.05,
+    )
+    samples = sampler(0.0)
+    assert np.ptp(samples) < 1e-3
+
+
+@pytest.mark.slow
+def test_driven_pendulum_stroboscopic_sampler_shows_period_doubling_amplitude_dependence():
+    """The driven pendulum's forcing-amplitude sweep is the classic
+    period-doubling demo: a weak forcing amplitude should settle to a
+    single stroboscopic value (period-1 locked to the drive), while a
+    strong one (the module's default, deep in the chaotic regime) should
+    show many distinct surviving values."""
+    omega_d = 2.0 / 3.0
+    period = 2.0 * np.pi / omega_d
+
+    def make_system(A):
+        return DrivenPendulum(damping=0.5, g_over_l=1.0, A=A, omega_d=omega_d)
+
+    sampler = stroboscopic_bifurcation_sampler(
+        make_system,
+        state0=np.array([0.2, 0.0]),
+        sample_period=period,
+        n_transient_periods=50,
+        n_keep_periods=15,
+        component=0,
+        dt=0.02,
+    )
+    weak_samples = sampler(0.5)
+    assert np.ptp(weak_samples) < 1e-2
+
+    strong_samples = sampler(1.5)
+    unique_values = np.unique(np.round(strong_samples, decimals=2))
+    assert unique_values.size > 5

physicskit/chaos/tests/test_billiards.py

@@ -0,0 +1,115 @@
+import numpy as np
+import pytest
+
+from physicskit.chaos.systems.billiards import (
+    BunimovichStadium,
+    CircleBilliard,
+    EllipseBilliard,
+    RectangleBilliard,
+    SinaiBilliard,
+    TruncatedCircleBilliard,
+)
+
+ALL_BILLIARDS = [
+    lambda: CircleBilliard(radius=1.0),
+    lambda: RectangleBilliard(width=2.0, height=1.0),
+    lambda: SinaiBilliard(cell_size=2.0, scatterer_radius=0.5),
+    lambda: BunimovichStadium(radius=1.0, straight_length=2.0),
+    lambda: TruncatedCircleBilliard(radius=1.0, cut=0.3),
+    # Fewer segments than the default (2000) to keep the test suite fast; the
+    # polygon-approximation physics is exercised the same way either way.
+    lambda: EllipseBilliard(semi_major=1.5, semi_minor=1.0, n_segments=300),
+]
+
+
+@pytest.mark.parametrize("make_billiard", ALL_BILLIARDS)
+def test_speed_conserved_across_bounces(make_billiard):
+    """Specular reflection must preserve |v| = 1 at every bounce."""
+    billiard = make_billiard()
+    pos = billiard.sample_interior_point()
+    rng = np.random.default_rng(0)
+    for angle in rng.uniform(0, 2 * np.pi, size=10):
+        vel = np.array([np.cos(angle), np.sin(angle)])
+        result = billiard.simulate(pos, vel, n_bounces=200)
+        speeds = np.hypot(result["vx"], result["vy"])
+        np.testing.assert_allclose(speeds, 1.0, atol=1e-9)
+
+
+@pytest.mark.parametrize("make_billiard", ALL_BILLIARDS)
+def test_bounce_points_lie_within_perimeter_range(make_billiard):
+    """Boundary arclength coordinate s must stay within [0, perimeter)."""
+    billiard = make_billiard()
+    pos = billiard.sample_interior_point()
+    result = billiard.simulate(pos, np.array([1.0, 0.3]), n_bounces=200)
+    assert np.all(result["s"] >= -1e-6)
+    assert np.all(result["s"] <= billiard.perimeter() + 1e-6)
+
+
+@pytest.mark.parametrize("make_billiard", ALL_BILLIARDS)
+def test_sin_phi_within_unit_range(make_billiard):
+    billiard = make_billiard()
+    pos = billiard.sample_interior_point()
+    result = billiard.simulate(pos, np.array([0.7, 0.5]), n_bounces=200)
+    assert np.all(result["sin_phi"] >= -1.0 - 1e-9)
+    assert np.all(result["sin_phi"] <= 1.0 + 1e-9)
+
+
+@pytest.mark.parametrize("make_billiard", ALL_BILLIARDS)
+def test_bounce_points_on_or_inside_boundary(make_billiard):
+    """No bounce point should end up strictly outside the billiard's convex-ish
+    bounding region (a coarse sanity check against ray-tracing bugs)."""
+    billiard = make_billiard()
+    pos = billiard.sample_interior_point()
+    result = billiard.simulate(pos, np.array([0.4, 0.9]), n_bounces=100)
+    boundary = billiard.boundary_polyline()
+    margin = 1e-6
+    # boundary_polyline() separates disjoint closed components (e.g. Sinai's
+    # outer wall and inner scatterer) with a row of NaN; use nanmax/nanmin so
+    # that doesn't turn the bounding box into NaN.
+    assert result["x"].max() <= np.nanmax(boundary[:, 0]) + margin
+    assert result["x"].min() >= np.nanmin(boundary[:, 0]) - margin
+    assert result["y"].max() <= np.nanmax(boundary[:, 1]) + margin
+    assert result["y"].min() >= np.nanmin(boundary[:, 1]) - margin
+
+
+def test_circle_billiard_is_integrable_constant_sin_phi():
+    """In a circular billiard, sin(phi) is an exact invariant of the motion."""
+    billiard = CircleBilliard(radius=1.0)
+    result = billiard.simulate(np.array([0.3, 0.0]), np.array([0.2, 1.0]), n_bounces=100)
+    np.testing.assert_allclose(result["sin_phi"], result["sin_phi"][0], atol=1e-8)
+
+
+def test_sinai_billiard_rejects_scatterer_larger_than_cell():
+    with pytest.raises(ValueError):
+        SinaiBilliard(cell_size=2.0, scatterer_radius=1.5)
+
+
+def test_truncated_circle_rejects_invalid_cut():
+    with pytest.raises(ValueError):
+        TruncatedCircleBilliard(radius=1.0, cut=1.5)
+
+
+def test_ellipse_billiard_rejects_invalid_axes():
+    with pytest.raises(ValueError):
+        EllipseBilliard(semi_major=1.0, semi_minor=1.5)  # major must exceed minor
+    with pytest.raises(ValueError):
+        EllipseBilliard(semi_major=-1.0, semi_minor=0.5)
+    with pytest.raises(ValueError):
+        EllipseBilliard(semi_major=1.0, semi_minor=0.0)
+
+
+def test_ellipse_billiard_foci_at_known_positions():
+    billiard = EllipseBilliard(semi_major=1.5, semi_minor=1.0)
+    f1, f2 = billiard.foci()
+    c = np.sqrt(1.5**2 - 1.0**2)
+    np.testing.assert_allclose(f1, [c, 0.0])
+    np.testing.assert_allclose(f2, [-c, 0.0])
+
+
+def test_ellipse_billiard_sin_phi_stays_bounded_by_caustic():
+    """A single ellipse-billiard trajectory stays tangent to one confocal
+    caustic, so its sin(phi) values are confined to a bounded sub-range of
+    [-1, 1] rather than filling it (unlike a chaotic billiard)."""
+    billiard = EllipseBilliard(semi_major=1.5, semi_minor=1.0, n_segments=1000)
+    result = billiard.simulate(billiard.sample_interior_point(), np.array([0.3, 1.0]), n_bounces=300)
+    assert result["sin_phi"].max() - result["sin_phi"].min() < 1.0

physicskit/chaos/tests/test_continuous.py

@@ -0,0 +1,224 @@
+import numpy as np
+import pytest
+
+from physicskit.chaos.systems.continuous import (
+    Chua,
+    DoublePendulum,
+    DrivenPendulum,
+    Duffing,
+    MagneticPendulum,
+    RestrictedThreeBody,
+    Rossler,
+    effective_potential,
+    lagrange_points,
+)
+from physicskit.chaos.utils.metrics import energy_drift
+
+
+def test_rossler_attractor_trajectory_is_finite_and_matches_rhs():
+    system = Rossler(a=0.2, b=0.2, c=5.7)
+    assert system.initial_state().tolist() == [1.0, 1.0, 1.0]
+    t, states = system.trajectory(n_steps=2000, dt=0.01)
+    assert np.all(np.isfinite(states))
+    assert t.shape == (2001,)
+
+    deriv = system.rhs(states[0], t[0])
+    assert deriv.shape == (3,)
+    assert np.allclose(deriv, [-states[0, 1] - states[0, 2], states[0, 0] + 0.2 * states[0, 1], 0.2 + states[0, 2] * (states[0, 0] - 5.7)])
+
+
+def test_double_pendulum_and_magnetic_pendulum_rhs_match_trajectory():
+    dp = DoublePendulum()
+    state0 = dp.initial_state()
+    d = dp.rhs(state0, 0.0)
+    assert d.shape == state0.shape
+    assert np.all(np.isfinite(d))
+
+    mp = MagneticPendulum()
+    state0_mp = mp.initial_state()
+    d_mp = mp.rhs(state0_mp, 0.0)
+    assert d_mp.shape == state0_mp.shape
+    assert np.all(np.isfinite(d_mp))
+
+
+def test_duffing_initial_state_and_rhs():
+    system = Duffing(delta=0.3, alpha=-1.0, beta=1.0, gamma=0.3, omega=1.2)
+    state0 = system.initial_state()
+    assert state0.shape == (2,)
+    d = system.rhs(state0, 0.0)
+    assert d.shape == (2,)
+    assert np.all(np.isfinite(d))
+    _, states = system.trajectory(state0=state0, n_steps=100, dt=0.01)
+    assert np.all(np.isfinite(states))
+
+
+def test_chua_trajectory_is_finite_and_bounded():
+    """Chua's circuit is dissipative and settles onto a bounded attractor;
+    integrating it must never blow up to infinity/NaN."""
+    system = Chua()
+    _, states = system.trajectory(n_steps=5000, dt=0.01)
+    assert np.all(np.isfinite(states))
+    # The classic double-scroll attractor stays within a modest, known range
+    # of the parameters used here; a much looser bound just guards against
+    # numerical blow-up regressions.
+    assert np.all(np.abs(states) < 20.0)
+
+
+def test_chua_rhs_at_origin_is_zero():
+    """The origin is an equilibrium of Chua's circuit: h(0) = 0, so
+    rhs((0, 0, 0)) == (0, 0, 0)."""
+    system = Chua()
+    derivative = system.rhs(np.array([0.0, 0.0, 0.0]), 0.0)
+    np.testing.assert_allclose(derivative, [0.0, 0.0, 0.0], atol=1e-12)
+
+
+def test_chua_trajectory_is_dissipative():
+    """Chua's circuit is dissipative (its equilibria are unstable but phase
+    volume contracts on average): starting near, but not at, the origin, the
+    trajectory should not simply run away to the bounding box unboundedly."""
+    system = Chua()
+    _, states = system.trajectory(state0=np.array([0.1, 0.0, 0.0]), n_steps=5000, dt=0.01)
+    assert np.all(np.isfinite(states))
+    assert np.all(np.abs(states) < 20.0)
+
+
+def test_restricted_three_body_jacobi_constant_is_conserved():
+    """The Jacobi constant is an exact invariant of CR3BP motion; a good RK4
+    integration should conserve it to a tight tolerance."""
+    system = RestrictedThreeBody()
+    t, states = system.trajectory(dt=0.001, n_steps=5000)
+    drift = energy_drift(t, states, system.jacobi_constant)
+    assert np.max(np.abs(drift)) < 1e-4
+
+
+def test_restricted_three_body_arenstorf_orbit_is_approximately_periodic():
+    """The default initial condition is the classic Arenstorf periodic orbit:
+    integrating for exactly one period should return close to the start."""
+    system = RestrictedThreeBody()
+    state0 = system.initial_state()
+    period = 17.0652165601579625588917206249
+    dt = 0.0001
+    _, states = system.trajectory(dt=dt, n_steps=round(period / dt))
+    assert np.max(np.abs(states[-1] - state0)) < 0.01
+
+
+def test_restricted_three_body_rhs_matches_known_acceleration_at_a_point():
+    """Spot-check the CR3BP right-hand side at a simple point against a
+    hand-computed value, to catch sign/algebra errors in the Coriolis terms."""
+    system = RestrictedThreeBody(mu=0.1)
+    # On the x-axis with zero velocity, the Coriolis terms vanish and the
+    # y-acceleration is exactly zero by symmetry.
+    derivative = system.rhs(np.array([0.5, 0.0, 0.0, 0.0]), 0.0)
+    assert derivative[1] == 0.0  # dy/dt = vy = 0
+    assert derivative[3] == 0.0  # dvy/dt = 0 by symmetry on the x-axis
+
+
+def test_lagrange_points_collinear_points_are_ordered_and_at_equilibrium():
+    """L3 < -mu (primary) < L1 < 1-mu (secondary) < L2 on the x-axis, and
+    each collinear point must be a genuine root of the rotating-frame
+    x-acceleration (zero net force at rest)."""
+    mu = 0.012277471
+    points = lagrange_points(mu)
+    x_l1, x_l2, x_l3 = points[0, 0], points[1, 0], points[2, 0]
+    assert x_l3 < -mu < x_l1 < (1.0 - mu) < x_l2
+
+    system = RestrictedThreeBody(mu=mu)
+    for x in (x_l1, x_l2, x_l3):
+        derivative = system.rhs(np.array([x, 0.0, 0.0, 0.0]), 0.0)
+        assert abs(derivative[2]) < 1e-8  # zero net x-acceleration at rest
+
+
+def test_lagrange_points_l4_l5_form_equilateral_triangles_with_primaries():
+    """L4 and L5 are, by construction, equidistant from both primaries at
+    exactly the primary-primary separation (unit distance in these units)."""
+    mu = 0.012277471
+    points = lagrange_points(mu)
+    primary = np.array([-mu, 0.0])
+    secondary = np.array([1.0 - mu, 0.0])
+    for lx, ly in points[3:]:
+        p = np.array([lx, ly])
+        assert np.hypot(*(p - primary)) == pytest.approx(1.0, abs=1e-10)
+        assert np.hypot(*(p - secondary)) == pytest.approx(1.0, abs=1e-10)
+
+
+def test_effective_potential_matches_jacobi_constant_formula():
+    """RestrictedThreeBody.jacobi_constant is defined as
+    ``2*effective_potential(x, y, mu) - speed**2``; check the two stay
+    consistent (a regression guard against the two formulas drifting apart
+    if either is edited independently)."""
+    system = RestrictedThreeBody(mu=0.1)
+    state = np.array([0.3, 0.4, 0.1, -0.2])
+    x, y, vx, vy = state
+    expected = 2.0 * effective_potential(x, y, system.mu) - (vx * vx + vy * vy)
+    assert system.jacobi_constant(state) == pytest.approx(expected)
+
+
+def test_effective_potential_is_vectorized_over_a_grid():
+    """effective_potential must work directly on np.meshgrid output, since
+    that's how zero-velocity-curve plots use it."""
+    x = np.linspace(-1.5, 1.5, 5)
+    y = np.linspace(-1.5, 1.5, 5)
+    xx, yy = np.meshgrid(x, y)
+    omega = effective_potential(xx, yy, 0.012277471)
+    assert omega.shape == xx.shape
+    assert np.all(np.isfinite(omega))
+
+
+def test_effective_potential_is_minimized_at_lagrange_points_4_and_5():
+    """L4/L5 are the global minima of the effective potential; nearby points
+    (that aren't also Lagrange points) must have a strictly larger value."""
+    mu = 0.012277471
+    lx, ly = lagrange_points(mu)[3]
+    omega_l4 = effective_potential(lx, ly, mu)
+    for dx, dy in [(0.05, 0.0), (-0.05, 0.0), (0.0, 0.05), (0.0, -0.05)]:
+        assert effective_potential(lx + dx, ly + dy, mu) > omega_l4
+
+
+def test_driven_pendulum_rhs_matches_hand_derivation():
+    """Spot-check the driven-pendulum right-hand side at a simple point."""
+    system = DrivenPendulum(damping=0.5, g_over_l=1.0, A=1.5, omega_d=2.0 / 3.0)
+    derivative = system.rhs(np.array([0.0, 0.0]), 0.0)
+    # theta=0, omega=0, t=0: dtheta/dt=0, domega/dt = A*cos(0) = A
+    assert derivative[0] == 0.0
+    assert derivative[1] == pytest.approx(1.5)
+
+
+def test_driven_pendulum_trajectory_is_finite():
+    """The classic chaotic parameter set should integrate stably (bounded
+    omega; theta itself is allowed to wind arbitrarily as the pendulum
+    goes over the top, which happens for these parameters)."""
+    system = DrivenPendulum()
+    _, states = system.trajectory(n_steps=5000, dt=0.02)
+    assert np.all(np.isfinite(states))
+    assert np.all(np.abs(states[:, 1]) < 20.0)
+
+
+def test_magnetic_pendulum_settles_near_a_magnet():
+    """Starting the (damped) bob very close to one magnet should leave it
+    settled even closer to that same magnet."""
+    system = MagneticPendulum()
+    magnet = system.magnet_positions[0]
+    state0 = np.array([magnet[0] + 0.05, magnet[1], 0.0, 0.0])
+    _, states = system.trajectory(state0=state0, n_steps=5000, dt=0.02)
+    final_dist = np.hypot(*(states[-1, :2] - magnet))
+    initial_dist = np.hypot(*(state0[:2] - magnet))
+    assert final_dist < initial_dist
+
+
+def test_magnetic_pendulum_shows_sensitive_dependence_near_a_basin_boundary():
+    """Two very close starting points can settle near different magnets --
+    the hallmark of a fractal basin boundary."""
+    system = MagneticPendulum()
+    outcomes = set()
+    for x0 in np.linspace(-0.05, 0.05, 11):
+        _, states = system.trajectory(state0=np.array([x0, 0.0, 0.0, 0.0]), n_steps=5000, dt=0.02)
+        final = states[-1, :2]
+        dists = np.hypot(*(system.magnet_positions - final).T)
+        outcomes.add(int(np.argmin(dists)))
+    assert len(outcomes) > 1
+
+
+def test_magnetic_pendulum_trajectory_is_finite():
+    system = MagneticPendulum()
+    _, states = system.trajectory(n_steps=5000, dt=0.02)
+    assert np.all(np.isfinite(states))

physicskit/chaos/tests/test_dimension.py

@@ -0,0 +1,69 @@
+import numpy as np
+import pytest
+
+from physicskit.chaos.systems.maps import HenonMap
+from physicskit.chaos.utils.dimension import box_counting_dimension, correlation_dimension
+
+
+def _cantor_set_points(n_iter=10):
+    """Midpoints of the intervals surviving `n_iter` steps of the middle-thirds
+    Cantor set construction; its exact box-counting/correlation dimension is
+    log(2)/log(3), giving a ground-truth target for both estimators."""
+    intervals = [(0.0, 1.0)]
+    for _ in range(n_iter):
+        new_intervals = []
+        for a, b in intervals:
+            third = (b - a) / 3.0
+            new_intervals.append((a, a + third))
+            new_intervals.append((b - third, b))
+        intervals = new_intervals
+    return np.array([[(a + b) / 2.0] for a, b in intervals])
+
+
+CANTOR_DIMENSION = np.log(2) / np.log(3)
+
+
+def test_box_counting_dimension_matches_cantor_set_exact_value():
+    points = _cantor_set_points(n_iter=10)
+    d0, epsilons, counts = box_counting_dimension(points, n_scales=15, eps_min=3.0**-8, eps_max=3.0**-2)
+    assert d0 == pytest.approx(CANTOR_DIMENSION, abs=0.05)
+    assert epsilons.shape == (15,)
+    assert counts.shape == (15,)
+    assert np.all(counts >= 1.0)
+
+
+def test_correlation_dimension_matches_cantor_set_exact_value():
+    points = _cantor_set_points(n_iter=10)
+    d2, _, correlation_sums = correlation_dimension(points, n_scales=15, eps_min=3.0**-8, eps_max=3.0**-2)
+    assert d2 == pytest.approx(CANTOR_DIMENSION, abs=0.05)
+    assert np.all((correlation_sums >= 0.0) & (correlation_sums <= 1.0))
+
+
+def test_box_counting_dimension_of_a_line_segment_is_about_one():
+    rng = np.random.default_rng(0)
+    points = np.column_stack([rng.uniform(size=5000), np.zeros(5000)])
+    d0, _, _ = box_counting_dimension(points)
+    assert d0 == pytest.approx(1.0, abs=0.15)
+
+
+def test_box_counting_dimension_of_a_filled_square_approaches_two():
+    """With enough points to avoid box-counting's finite-sample saturation,
+    a uniformly-filled 2D region should have dimension close to 2."""
+    rng = np.random.default_rng(0)
+    points = rng.uniform(size=(100000, 2))
+    d0, _, _ = box_counting_dimension(points)
+    assert d0 == pytest.approx(2.0, abs=0.15)
+
+
+def test_henon_attractor_dimension_matches_known_literature_value():
+    """The classic Henon attractor (a=1.4, b=0.3) has a well-documented
+    fractal dimension of approximately 1.2-1.3."""
+    system = HenonMap(a=1.4, b=0.3)
+    traj = system.trajectory(np.array([0.0, 0.0]), n_iter=8000)
+    traj = traj[500:]  # discard transient
+
+    d0, _, _ = box_counting_dimension(traj)
+    assert 1.1 < d0 < 1.4
+
+    d2, _, _ = correlation_dimension(traj)
+    assert 1.0 < d2 < 1.4

physicskit/chaos/tests/test_divergence.py

@@ -0,0 +1,90 @@
+import numpy as np
+import pytest
+
+from physicskit.chaos.systems.billiards import CircleBilliard, TruncatedCircleBilliard
+from physicskit.chaos.systems.continuous import Lorenz
+from physicskit.chaos.visualizers.divergence import (
+    billiard_trajectory_divergence,
+    plot_billiard_divergence,
+    plot_trajectory_ensemble,
+    trajectory_ensemble,
+)
+from physicskit.chaos.visualizers.dynamic_plots import animate_billiard_divergence
+
+
+def test_circle_billiard_separation_is_exactly_conserved():
+    """The circle is integrable (sin(phi) is an exact invariant), so two
+    nearby rays' separation should stay essentially unchanged forever --
+    no exponential growth, because there is no chaos to be sensitive to."""
+    billiard = CircleBilliard(radius=1.0)
+    delta_0 = 1e-8
+    _, separation = billiard_trajectory_divergence(
+        billiard,
+        pos=billiard.sample_interior_point(),
+        vel=(0.2, 1.0),
+        delta_0=delta_0,
+        n_bounces=100,
+    )
+    assert np.allclose(separation, delta_0, rtol=1e-6)
+
+
+@pytest.mark.parametrize("cut", [0.3, 0.05, 0.02])
+def test_truncated_circle_billiard_diverges_for_any_cut(cut):
+    """Even a tiny truncation destroys integrability: separation must grow
+    by many orders of magnitude over enough bounces, for any cut depth."""
+    billiard = TruncatedCircleBilliard(radius=1.0, cut=cut)
+    delta_0 = 1e-8
+    _, separation = billiard_trajectory_divergence(
+        billiard,
+        pos=billiard.sample_interior_point(),
+        vel=(0.2, 1.0),
+        delta_0=delta_0,
+        n_bounces=300,
+    )
+    assert separation.max() > 1e-3
+
+
+def test_billiard_trajectory_divergence_shapes():
+    billiard = TruncatedCircleBilliard(radius=1.0, cut=0.05)
+    bounce, separation = billiard_trajectory_divergence(billiard, pos=billiard.sample_interior_point(), vel=(0.2, 1.0), n_bounces=50)
+    assert bounce.shape == (50,)
+    assert separation.shape == (50,)
+    assert np.array_equal(bounce, np.arange(1, 51))
+
+
+def test_plot_billiard_divergence_estimates_positive_exponent_for_chaotic_billiard():
+    billiard = TruncatedCircleBilliard(radius=1.0, cut=0.05)
+    _, ax, lam = plot_billiard_divergence(billiard, pos=billiard.sample_interior_point(), vel=(0.2, 1.0), n_bounces=100)
+    assert lam > 0.0
+    assert ax.get_xlabel() == "bounce number k"
+
+
+def test_animate_billiard_divergence_runs():
+    billiard = TruncatedCircleBilliard(radius=1.0, cut=0.05)
+    anim = animate_billiard_divergence(billiard, pos=billiard.sample_interior_point(), vel=(0.2, 1.0), n_bounces=30, trail=10)
+    anim._draw_frame(20)
+
+
+def test_trajectory_ensemble_shape_and_zero_spread_members_share_the_reference():
+    """With spread=0, every ensemble member is launched from exactly the
+    same state as the reference, so all members' trajectories must be
+    identical to each other."""
+    system = Lorenz()
+    all_states = trajectory_ensemble(system, n_members=5, spread=0.0, dt=0.01, n_steps=50, seed=0)
+    assert all_states.shape == (5, 51, system.dim)
+    for member in all_states[1:]:
+        np.testing.assert_allclose(member, all_states[0])
+
+
+def test_trajectory_ensemble_members_start_within_the_requested_spread():
+    system = Lorenz()
+    state0 = system.initial_state()
+    all_states = trajectory_ensemble(system, state0=state0, n_members=10, spread=1e-3, dt=0.01, n_steps=10, seed=0)
+    offsets = np.linalg.norm(all_states[:, 0, :] - state0, axis=1)
+    assert np.all(offsets < 1e-3 + 1e-12)
+
+
+def test_plot_trajectory_ensemble_draws_one_line_per_member():
+    system = Lorenz()
+    _, ax = plot_trajectory_ensemble(system, n_members=6, spread=1e-4, dt=0.01, n_steps=20, seed=0)
+    assert len(ax.get_lines()) == 6