physicskit 0.1.0__py3-none-any.whl

physicskit/chaos/tests/test_dynamic_plots.py

@@ -0,0 +1,269 @@
+import matplotlib
+
+matplotlib.use("Agg")
+
+import numpy as np
+import pytest
+from matplotlib.animation import PillowWriter
+from matplotlib.collections import LineCollection
+
+from physicskit.chaos.systems.continuous import DrivenPendulum, Lorenz, MagneticPendulum, RestrictedThreeBody
+from physicskit.chaos.systems.maps import BakersMap
+from physicskit.chaos.visualizers.dynamic_plots import (
+    animate_bakers_map,
+    animate_driven_pendulum,
+    animate_multi_orbit_map,
+    animate_phase_volume_contraction,
+    animate_restricted_three_body,
+    plot_colored_trajectory,
+    plotly_3d_trajectory,
+)
+
+
+def test_plot_colored_trajectory_returns_figure_and_axes_with_line_collection():
+    x = np.linspace(0.0, 1.0, 50)
+    y = np.sin(x * 10.0)
+    values = np.arange(50, dtype=np.float64)
+
+    _fig, ax = plot_colored_trajectory(x, y, values)
+    collections = [c for c in ax.collections if isinstance(c, LineCollection)]
+    assert len(collections) == 1
+    # One fewer segment than points (each segment joins consecutive points).
+    assert collections[0].get_segments().__len__() == 49
+
+
+def test_plot_colored_trajectory_sets_axis_limits_to_data_range():
+    x = np.array([0.0, 5.0, 2.0])
+    y = np.array([0.0, 1.0, -3.0])
+    values = np.array([0.0, 1.0, 2.0])
+
+    _, ax = plot_colored_trajectory(x, y, values)
+    assert ax.get_xlim() == (0.0, 5.0)
+    assert ax.get_ylim() == (-3.0, 1.0)
+
+
+def test_plot_colored_trajectory_no_colorbar_when_disabled():
+    x = np.linspace(0.0, 1.0, 10)
+    y = np.linspace(0.0, 1.0, 10)
+    values = np.linspace(0.0, 1.0, 10)
+
+    fig, _ = plot_colored_trajectory(x, y, values, colorbar=False)
+    assert len(fig.axes) == 1  # just the main axes, no colorbar axes added
+
+
+def test_plotly_3d_trajectory_contains_all_points():
+    states = np.column_stack([np.linspace(0, 1, 20), np.linspace(0, 2, 20), np.linspace(0, 3, 20)])
+    fig = plotly_3d_trajectory(states)
+    trace = fig.data[0]
+    assert len(trace.x) == 20
+    np.testing.assert_allclose(trace.z, states[:, 2])
+
+
+def test_plotly_3d_trajectory_color_by_sets_marker_color_array():
+    states = np.random.default_rng(0).uniform(size=(15, 3))
+    color_values = np.arange(15, dtype=np.float64)
+    fig = plotly_3d_trajectory(states, color_by=color_values)
+    trace = fig.data[0]
+    np.testing.assert_allclose(trace.line.color, color_values)
+
+
+def test_animate_phase_volume_contraction_rejects_non_3d_system():
+    with pytest.raises(ValueError):
+        animate_phase_volume_contraction(MagneticPendulum())
+
+
+def test_animate_phase_volume_contraction_shrinks_the_cloud():
+    """The whole point of the animation: the point cloud's volume must shrink
+    over time for a dissipative system, since that is what phase-space
+    volume contraction means geometrically. Uses a small ball and a short
+    horizon, where the linear (Jacobian-trace) contraction that
+    :func:`~physicskit.chaos.utils.metrics.phase_volume_expansion` predicts still
+    dominates -- over a long horizon the cloud instead stretches into a
+    thin sheet *along* the attractor, and simple size statistics (spread
+    along one axis, a covariance-based volume estimate) stop decreasing
+    monotonically even though it is still, in the measure-theoretic sense,
+    contracting."""
+
+    def _cloud_volume(anim, frame):
+        anim._draw_frame(frame)
+        x, y, z = anim._fig.axes[0].collections[0]._offsets3d
+        cov = np.cov(np.column_stack([x, y, z]).T)
+        return float(np.sqrt(np.linalg.det(cov)))
+
+    system = Lorenz(sigma=10.0, rho=28.0, beta=8.0 / 3.0)
+    anim = animate_phase_volume_contraction(
+        system,
+        n_points=200,
+        ball_radius=0.3,
+        t_max=0.5,
+        dt=0.005,
+        n_frames=10,
+        warmup_steps=200,
+        seed=0,
+    )
+    volumes = [_cloud_volume(anim, i) for i in range(10)]
+    assert all(v2 < v1 for v1, v2 in zip(volumes, volumes[1:]))
+
+
+def test_animate_phase_volume_contraction_respects_explicit_center_state():
+    system = Lorenz(sigma=10.0, rho=28.0, beta=8.0 / 3.0)
+    center = np.array([1.0, 1.0, 1.0])
+    anim = animate_phase_volume_contraction(system, center_state=center, ball_radius=0.5, n_points=50, t_max=1.0, n_frames=5)
+    anim._draw_frame(0)
+    x, y, z = anim._fig.axes[0].collections[0]._offsets3d
+    points0 = np.column_stack([x, y, z])
+    assert np.allclose(points0.mean(axis=0), center, atol=0.5)
+
+
+def _n_points_drawn(anim):
+    return sum(len(line.get_xdata()) for line in anim._fig.axes[0].lines)
+
+
+def test_animate_multi_orbit_map_grows_every_orbit_together_not_one_at_a_time():
+    """Every orbit must gain points on (almost) every frame -- not have whole
+    orbits complete one at a time -- so the picture keeps visibly changing
+    for the whole animation instead of mostly settling within a few frames."""
+    rng = np.random.default_rng(0)
+    orbits = [rng.uniform(size=(50, 2)) for _ in range(5)]
+    anim = animate_multi_orbit_map(orbits, n_frames=20)
+
+    anim._draw_frame(0)
+    counts = [_n_points_drawn(anim)]
+    for i in range(1, 20):
+        anim._draw_frame(i)
+        counts.append(_n_points_drawn(anim))
+
+    # Points accumulate monotonically and every orbit has contributed to the
+    # very first frame already (all 5 lines non-empty), not just one.
+    assert all(c2 >= c1 for c1, c2 in zip(counts, counts[1:]))
+    anim._draw_frame(0)
+    non_empty_lines_at_frame_0 = sum(1 for line in anim._fig.axes[0].lines if len(line.get_xdata()) > 0)
+    assert non_empty_lines_at_frame_0 == 5
+
+
+def test_animate_multi_orbit_map_reaches_full_length_on_last_frame():
+    orbits = [np.column_stack([np.arange(30), np.arange(30)]) for _ in range(3)]
+    anim = animate_multi_orbit_map(orbits, n_frames=10)
+    anim._draw_frame(9)
+    assert _n_points_drawn(anim) == 30 * 3
+
+
+def test_animate_multi_orbit_map_handles_orbits_of_different_lengths():
+    orbits = [np.zeros((10, 2)), np.zeros((30, 2))]
+    anim = animate_multi_orbit_map(orbits, n_frames=5)
+    anim._draw_frame(4)
+    lengths = [len(line.get_xdata()) for line in anim._fig.axes[0].lines]
+    assert lengths == [10, 30]
+
+
+def _bakers_scatter(anim):
+    return anim._fig.axes[0].collections[0]
+
+
+def test_animate_bakers_map_colors_left_and_right_half_differently():
+    n_points = 100
+    seed = 0
+    system = BakersMap(alpha=0.5)
+    anim = animate_bakers_map(
+        system,
+        n_points=n_points,
+        n_iterations=1,
+        frames_per_iteration=6,
+        stripe_colors=("tab:blue", "tab:red"),
+        seed=seed,
+    )
+
+    # Reconstruct the same jittered starting grid `animate_bakers_map` builds
+    # internally, to know each marker's *original* x -- by frame 0 the
+    # stretch phase has already moved the markers, so their current offsets
+    # no longer reflect the left/right split the coloring is based on.
+    n_side = round(np.sqrt(n_points))
+    centers = (np.arange(n_side) + 0.5) / n_side
+    grid_x, _ = np.meshgrid(centers, centers)
+    rng = np.random.default_rng(seed)
+    jitter = rng.uniform(-0.15, 0.15, size=(2,) + grid_x.shape) / n_side
+    x0 = (grid_x + jitter[0]).ravel()
+
+    anim._draw_frame(0)
+    facecolors = _bakers_scatter(anim).get_facecolor()
+    unique_colors = {tuple(c) for c in facecolors}
+    assert len(unique_colors) == 2
+    # Color must actually track the left/right split, not just happen to
+    # take two values: every left-of-center point shares one color and every
+    # right-of-center point shares the other.
+    left_colors = {tuple(c) for c, x in zip(facecolors, x0) if x < 0.5}
+    right_colors = {tuple(c) for c, x in zip(facecolors, x0) if x >= 0.5}
+    assert len(left_colors) == 1
+    assert len(right_colors) == 1
+    assert left_colors != right_colors
+
+
+def test_animate_bakers_map_stretch_phase_extends_past_unit_square():
+    """During the stretch phase the cloud should spill out past x = 1, since
+    the right-hand branch is drawn stretched into its own, offset slot
+    rather than snapping straight to its final (folded-back) position."""
+    system = BakersMap(alpha=0.5)
+    anim = animate_bakers_map(system, n_points=400, n_iterations=1, frames_per_iteration=9)
+    for i in range(4):  # sequentially through frame 3 (mid-stretch, before the cut/pause frame)
+        anim._draw_frame(i)
+    x = _bakers_scatter(anim).get_offsets()[:, 0]
+    assert x.max() > 1.0
+
+
+def test_animate_bakers_map_returns_to_unit_square_after_full_iteration():
+    """At the last frame of an iteration, every point must land exactly on
+    the analytic baker's map image of its starting point, back inside the
+    unit square (no residual stretch/offset left over)."""
+    alpha = 0.5
+    system = BakersMap(alpha=alpha)
+    n_points = 100
+    seed = 0
+    anim = animate_bakers_map(system, n_points=n_points, n_iterations=1, frames_per_iteration=6, seed=seed)
+
+    # Reconstruct the same jittered starting grid `animate_bakers_map` builds
+    # internally (a perfectly regular grid sits at exact dyadic rationals,
+    # which this map's doubling action on `x` would otherwise degenerate
+    # within a handful of iterations).
+    n_side = round(np.sqrt(n_points))
+    centers = (np.arange(n_side) + 0.5) / n_side
+    grid_x, grid_y = np.meshgrid(centers, centers)
+    rng = np.random.default_rng(seed)
+    jitter = rng.uniform(-0.15, 0.15, size=(2,) + grid_x.shape) / n_side
+    x0 = np.clip(grid_x + jitter[0], 0.0, 1.0 - 1e-12).ravel()
+    y0 = np.clip(grid_y + jitter[1], 0.0, 1.0 - 1e-12).ravel()
+    left = x0 < alpha
+    x_expected = np.where(left, x0 / alpha, (x0 - alpha) / (1.0 - alpha))
+    y_expected = np.where(left, alpha * y0, alpha + (1.0 - alpha) * y0)
+
+    for i in range(6):  # sequentially through the last frame of the (only) iteration
+        anim._draw_frame(i)
+    offsets = _bakers_scatter(anim).get_offsets()
+    np.testing.assert_allclose(np.sort(offsets[:, 0]), np.sort(x_expected), atol=1e-10)
+    np.testing.assert_allclose(np.sort(offsets[:, 1]), np.sort(y_expected), atol=1e-10)
+
+
+def test_animate_bakers_map_uses_square_markers():
+    system = BakersMap(alpha=0.5)
+    anim = animate_bakers_map(system, n_points=100, n_iterations=1, frames_per_iteration=6)
+    paths = _bakers_scatter(anim).get_paths()
+    assert len(paths) == 1  # scatter shares one path (the marker shape) across all points
+    # A square marker path has 4 (or 5, if closed) vertices.
+    assert len(paths[0].vertices) in (4, 5)
+
+
+@pytest.mark.slow
+def test_animate_restricted_three_body_saves_gif(tmp_path):
+    system = RestrictedThreeBody()
+    anim = animate_restricted_three_body(system, dt=0.001, n_steps=800, skip=20)
+    out = tmp_path / "cr3bp.gif"
+    anim.save(out, writer=PillowWriter(fps=10))
+    assert out.exists() and out.stat().st_size > 0
+
+
+@pytest.mark.slow
+def test_animate_driven_pendulum_saves_gif(tmp_path):
+    system = DrivenPendulum()
+    anim = animate_driven_pendulum(system, dt=0.02, n_steps=60)
+    out = tmp_path / "driven_pendulum.gif"
+    anim.save(out, writer=PillowWriter(fps=10))
+    assert out.exists() and out.stat().st_size > 0

physicskit/chaos/tests/test_integrators.py

@@ -0,0 +1,96 @@
+import numpy as np
+from numba import njit
+
+from physicskit.chaos.core.integrators import leapfrog_integrate, rk4_integrate, yoshida4_integrate
+
+
+@njit
+def _harmonic_force(pos, t, params):
+    """Restoring force for a simple harmonic oscillator, for integrator tests."""
+    omega = params[0]
+    return -(omega**2) * pos
+
+
+@njit
+def _harmonic_rhs(state, t, params):
+    """RK4-form right-hand side for the same simple harmonic oscillator."""
+    omega = params[0]
+    out = np.empty(2)
+    out[0] = state[1]
+    out[1] = -(omega**2) * state[0]
+    return out
+
+
+def _harmonic_energy(pos, vel, omega):
+    return 0.5 * vel**2 + 0.5 * omega**2 * pos**2
+
+
+def test_yoshida4_conserves_energy_better_than_leapfrog():
+    """The 4th-order Yoshida integrator should have much smaller energy drift
+    than plain (2nd-order) leapfrog at the same step size, since it is built
+    from three leapfrog sub-steps composed to raise the order of accuracy."""
+    omega = 2.0
+    params = np.array([omega])
+    pos0, vel0 = np.array([1.0]), np.array([0.0])
+    dt, n_steps = 0.05, 5000
+
+    _, pos_lf, vel_lf = leapfrog_integrate(_harmonic_force, pos0, vel0, 0.0, dt, n_steps, params)
+    energy_lf = _harmonic_energy(pos_lf[:, 0], vel_lf[:, 0], omega)
+    drift_lf = np.max(np.abs(energy_lf - energy_lf[0]) / energy_lf[0])
+
+    _, pos_y4, vel_y4 = yoshida4_integrate(_harmonic_force, pos0, vel0, 0.0, dt, n_steps, params)
+    energy_y4 = _harmonic_energy(pos_y4[:, 0], vel_y4[:, 0], omega)
+    drift_y4 = np.max(np.abs(energy_y4 - energy_y4[0]) / energy_y4[0])
+
+    assert drift_y4 < drift_lf
+
+
+def test_yoshida4_energy_drift_does_not_grow_with_integration_time():
+    """Being symplectic, Yoshida4's energy drift should stay bounded as the
+    integration horizon grows, unlike RK4's secularly-growing drift."""
+    omega = 2.0
+    params = np.array([omega])
+    pos0, vel0 = np.array([1.0]), np.array([0.0])
+    dt = 0.05
+
+    drifts = []
+    for n_steps in (2000, 20000, 200000):
+        _, pos, vel = yoshida4_integrate(_harmonic_force, pos0, vel0, 0.0, dt, n_steps, params)
+        energy = _harmonic_energy(pos[:, 0], vel[:, 0], omega)
+        drifts.append(np.max(np.abs(energy - energy[0]) / energy[0]))
+
+    # All three drifts should be the same order of magnitude (bounded), not
+    # growing proportionally with the 100x increase in integration horizon.
+    assert max(drifts) / min(drifts) < 10.0
+
+
+def test_rk4_energy_drift_grows_with_integration_time():
+    """The non-symplectic RK4 integrator's energy drift grows with
+    integration horizon, in contrast to the symplectic integrators -- this is
+    exactly the failure mode the symplectic integrators exist to avoid."""
+    omega = 2.0
+    params = np.array([omega])
+    state0 = np.array([1.0, 0.0])
+    dt = 0.05
+
+    drifts = []
+    for n_steps in (2000, 200000):
+        _, states = rk4_integrate(_harmonic_rhs, state0, 0.0, dt, n_steps, params)
+        energy = _harmonic_energy(states[:, 0], states[:, 1], omega)
+        drifts.append(np.max(np.abs(energy - energy[0]) / energy[0]))
+
+    assert drifts[1] > 5.0 * drifts[0]
+
+
+def test_yoshida4_matches_leapfrog_for_a_single_leapfrog_substep_limit():
+    """Sanity check: with a tiny step size, both integrators should agree
+    closely on the trajectory of a simple, smooth system."""
+    omega = 1.0
+    params = np.array([omega])
+    pos0, vel0 = np.array([1.0]), np.array([0.0])
+    dt, n_steps = 1e-4, 100
+
+    _, pos_lf, _ = leapfrog_integrate(_harmonic_force, pos0, vel0, 0.0, dt, n_steps, params)
+    _, pos_y4, _ = yoshida4_integrate(_harmonic_force, pos0, vel0, 0.0, dt, n_steps, params)
+
+    np.testing.assert_allclose(pos_lf, pos_y4, atol=1e-8)

physicskit/chaos/tests/test_io.py

@@ -0,0 +1,41 @@
+import numpy as np
+
+from physicskit.chaos.systems.billiards import SinaiBilliard
+from physicskit.chaos.systems.continuous import Lorenz
+from physicskit.chaos.utils.io import load_arrays, load_system_config, save_arrays, save_system_config
+
+
+def test_save_and_load_system_config_roundtrips_scalar_params(tmp_path):
+    system = Lorenz(sigma=11.0, rho=27.5, beta=8.0 / 3.0)
+    path = tmp_path / "lorenz.json"
+    save_system_config(system, path)
+    restored = load_system_config(path)
+
+    assert type(restored) is Lorenz
+    assert restored.sigma == system.sigma
+    assert restored.rho == system.rho
+    assert restored.beta == system.beta
+
+
+def test_save_and_load_system_config_roundtrips_billiard_params(tmp_path):
+    billiard = SinaiBilliard(cell_size=2.5, scatterer_radius=0.7)
+    path = tmp_path / "sinai.json"
+    save_system_config(billiard, path)
+    restored = load_system_config(path)
+
+    assert type(restored) is SinaiBilliard
+    assert restored.cell_size == billiard.cell_size
+    assert restored.scatterer_radius == billiard.scatterer_radius
+
+
+def test_save_and_load_arrays_roundtrips_exactly(tmp_path):
+    t = np.linspace(0.0, 10.0, 50)
+    states = np.random.default_rng(0).normal(size=(50, 3))
+    path = tmp_path / "run.npz"
+
+    save_arrays(path, t=t, states=states)
+    loaded = load_arrays(path)
+
+    assert set(loaded.keys()) == {"t", "states"}
+    np.testing.assert_array_equal(loaded["t"], t)
+    np.testing.assert_array_equal(loaded["states"], states)

physicskit/chaos/tests/test_maps.py

@@ -0,0 +1,110 @@
+import numpy as np
+import pytest
+
+from physicskit.chaos.systems.maps import BakersMap, LogisticMap
+
+
+def test_bakers_map_state_stays_in_unit_square():
+    """Every iterate of the (area-preserving) baker's map must stay in [0, 1) x [0, 1)."""
+    system = BakersMap(alpha=0.5)
+    traj = system.trajectory(np.array([0.123, 0.456]), n_iter=1000)
+    assert np.all(traj >= 0.0)
+    assert np.all(traj < 1.0)
+
+
+@pytest.mark.parametrize("alpha", [0.2, 0.5, 0.7])
+def test_bakers_map_state_stays_in_unit_square_asymmetric(alpha):
+    system = BakersMap(alpha=alpha)
+    traj = system.trajectory(np.array([0.37, 0.81]), n_iter=1000)
+    assert np.all(traj >= 0.0)
+    assert np.all(traj < 1.0)
+
+
+def test_bakers_map_symmetric_lyapunov_exponents_are_log2():
+    """For alpha=0.5, the analytic Lyapunov exponents are exactly +-ln(2)."""
+    system = BakersMap(alpha=0.5)
+    lam_plus, lam_minus = system.lyapunov_exponents()
+    assert lam_plus == pytest.approx(np.log(2.0))
+    assert lam_minus == pytest.approx(-np.log(2.0))
+
+
+def test_bakers_map_lyapunov_exponents_are_symmetric_and_positive():
+    system = BakersMap(alpha=0.3)
+    lam_plus, lam_minus = system.lyapunov_exponents()
+    assert lam_plus > 0.0
+    assert lam_minus == pytest.approx(-lam_plus)
+
+
+def test_bakers_map_symmetric_case_doubles_x_separation_each_step():
+    """For alpha=0.5, two points starting in the same branch have their
+    x-separation exactly double at every step, until a branch-crossing wraps
+    one of them -- the literal "stretch" half of "stretch, cut, and stack"."""
+    system = BakersMap(alpha=0.5)
+    state_a = np.array([0.1, 0.2])
+    state_b = np.array([0.1 + 1e-6, 0.2])
+    for _ in range(10):
+        dx_before = abs(state_b[0] - state_a[0])
+        same_branch = (state_a[0] < 0.5) == (state_b[0] < 0.5)
+        state_a = system.step(state_a)
+        state_b = system.step(state_b)
+        if same_branch:
+            dx_after = abs(state_b[0] - state_a[0])
+            assert dx_after == pytest.approx(2.0 * dx_before, rel=1e-6)
+
+
+def test_bakers_map_rejects_invalid_alpha():
+    with pytest.raises(ValueError):
+        BakersMap(alpha=0.0)
+    with pytest.raises(ValueError):
+        BakersMap(alpha=1.0)
+    with pytest.raises(ValueError):
+        BakersMap(alpha=1.5)
+
+
+def test_logistic_map_step_matches_trajectory_first_iteration():
+    """LogisticMap.trajectory() uses a fast, standalone numba loop rather
+    than calling .step() itself; check .step() directly gives the same
+    first iteration as trajectory() does, so the two paths can't diverge."""
+    system = LogisticMap(r=3.9)
+    state0 = np.array([0.37])
+    stepped = system.step(state0)
+    traj = system.trajectory(state0, n_iter=1)
+    assert stepped.shape == (1,)
+    np.testing.assert_allclose(stepped, traj[1])
+
+
+def test_logistic_map_state_stays_in_unit_interval():
+    system = LogisticMap(r=3.9)
+    traj = system.trajectory(np.array([0.37]), n_iter=2000)
+    assert traj.shape == (2001, 1)
+    assert np.all(traj >= 0.0)
+    assert np.all(traj <= 1.0)
+
+
+def test_logistic_map_converges_to_known_fixed_point_below_r3():
+    """For 1 < r < 3, every trajectory converges to the stable fixed point x* = 1 - 1/r."""
+    r = 2.5
+    system = LogisticMap(r=r)
+    traj = system.trajectory(np.array([0.1]), n_iter=500)
+    x_star = 1.0 - 1.0 / r
+    assert traj[-1, 0] == pytest.approx(x_star, abs=1e-6)
+
+
+def test_logistic_map_period_two_cycle_just_above_r3():
+    """Just above the first period-doubling bifurcation at r=3, orbits settle
+    into a period-2 cycle: x(n+2) == x(n) but x(n+1) != x(n)."""
+    system = LogisticMap(r=3.2)
+    traj = system.trajectory(np.array([0.1]), n_iter=2000)
+    tail = traj[-4:, 0]
+    assert tail[0] == pytest.approx(tail[2], abs=1e-6)
+    assert tail[1] == pytest.approx(tail[3], abs=1e-6)
+    assert abs(tail[0] - tail[1]) > 1e-3
+
+
+def test_logistic_map_sensitive_dependence_at_chaotic_r():
+    """At r=4 (fully chaotic), two nearby trajectories must diverge noticeably
+    within a modest number of iterations."""
+    system = LogisticMap(r=4.0)
+    traj_a = system.trajectory(np.array([0.4]), n_iter=40)
+    traj_b = system.trajectory(np.array([0.4 + 1e-10]), n_iter=40)
+    assert abs(traj_a[-1, 0] - traj_b[-1, 0]) > 1e-3

physicskit/chaos/tests/test_metrics.py

@@ -0,0 +1,115 @@
+import numpy as np
+import pytest
+
+from physicskit.chaos.systems.continuous import DoublePendulum, Lorenz
+from physicskit.chaos.systems.maps import HenonMap, StandardMap
+from physicskit.chaos.utils.metrics import (
+    benettin_lyapunov_spectrum,
+    energy_drift,
+    lyapunov_exponent_from_divergence,
+    map_lyapunov_spectrum,
+    numerical_jacobian,
+    numerical_jacobian_map,
+    phase_volume_expansion,
+)
+
+
+def test_numerical_jacobian_matches_known_linear_system():
+    """For dx/dt = A x, the Jacobian is exactly A everywhere."""
+
+    class Linear:
+        dim = 2
+
+        def rhs(self, state, t):
+            a = np.array([[0.0, 1.0], [-2.0, -3.0]])
+            return a @ state
+
+    jac = numerical_jacobian(Linear(), np.array([1.0, 2.0]), t=0.0)
+    np.testing.assert_allclose(jac, [[0.0, 1.0], [-2.0, -3.0]], atol=1e-6)
+
+
+def test_numerical_jacobian_map_matches_known_henon_jacobian():
+    """The Henon map's Jacobian at (x, y) is exactly [[-2*a*x, 1], [b, 0]]."""
+    henon = HenonMap(a=1.4, b=0.3)
+    x, y = 0.3, 0.1
+    jac = numerical_jacobian_map(henon, np.array([x, y]))
+    expected = np.array([[-2.0 * 1.4 * x, 1.0], [0.3, 0.0]])
+    np.testing.assert_allclose(jac, expected, atol=1e-5)
+
+
+def test_lyapunov_exponent_from_divergence_recovers_known_exponential_rate():
+    t = np.linspace(0.0, 10.0, 200)
+    true_rate = 0.7
+    delta = 1e-6 * np.exp(true_rate * t)
+    estimate = lyapunov_exponent_from_divergence(t, delta)
+    assert estimate == pytest.approx(true_rate, rel=1e-3)
+
+
+def test_benettin_lyapunov_spectrum_matches_known_lorenz_values():
+    """The classic Lorenz parameters have well-documented Lyapunov exponents
+    of approximately (0.906, 0, -14.57)."""
+    system = Lorenz()
+    spectrum = benettin_lyapunov_spectrum(system, system.initial_state(), dt=0.005, n_steps=10000, n_transient=2000)
+    assert spectrum[0] == pytest.approx(0.906, abs=0.15)
+    assert abs(spectrum[1]) < 0.1
+    assert spectrum[2] == pytest.approx(-14.57, abs=1.5)
+
+
+def test_benettin_lyapunov_spectrum_sum_matches_exact_lorenz_divergence():
+    """The Lorenz system's phase-space divergence (trace of the Jacobian) is
+    exactly -(sigma + 1 + beta) everywhere, so the sum of the Lyapunov
+    spectrum -- estimated with no knowledge of that identity -- should match
+    it closely, regardless of how accurately the individual exponents (which
+    are harder to pin down individually) are estimated."""
+    system = Lorenz(sigma=10.0, rho=28.0, beta=8.0 / 3.0)
+    spectrum = benettin_lyapunov_spectrum(system, system.initial_state(), dt=0.005, n_steps=10000, n_transient=2000)
+    expected_sum = -(system.sigma + 1.0 + system.beta)
+    assert spectrum.sum() == pytest.approx(expected_sum, abs=0.05)
+
+
+def test_map_lyapunov_spectrum_sum_matches_exact_henon_jacobian_determinant():
+    """The Henon map's Jacobian determinant is exactly -b everywhere, so the
+    sum of its Lyapunov exponents must equal ln|b| to high precision --
+    regardless of how well the individual exponents are estimated."""
+    henon = HenonMap(a=1.4, b=0.3)
+    spectrum = map_lyapunov_spectrum(henon, henon.initial_state(), n_iter=10000, n_transient=1000)
+    assert spectrum.sum() == pytest.approx(np.log(0.3), abs=1e-4)
+    assert spectrum[0] > 0.0 > spectrum[1]
+
+
+def test_map_lyapunov_spectrum_sums_to_zero_for_area_preserving_map():
+    """The standard map is exactly area-preserving, so its Lyapunov spectrum
+    must sum to zero."""
+    system = StandardMap(k=2.0)
+    spectrum = map_lyapunov_spectrum(system, system.initial_state(), n_iter=10000, n_transient=1000)
+    assert spectrum.sum() == pytest.approx(0.0, abs=1e-4)
+
+
+def test_energy_drift_is_zero_at_t0():
+    system = DoublePendulum()
+    t, states = system.trajectory(n_steps=500, dt=0.005)
+    drift = energy_drift(t, states, system.energy)
+    assert drift[0] == pytest.approx(0.0)
+
+
+def test_energy_drift_stays_small_for_a_good_integration():
+    system = DoublePendulum()
+    t, states = system.trajectory(n_steps=2000, dt=0.005)
+    drift = energy_drift(t, states, system.energy)
+    assert np.max(np.abs(drift)) < 1e-3
+
+
+def test_phase_volume_expansion_starts_at_zero():
+    system = Lorenz()
+    t, states = system.trajectory(n_steps=500, dt=0.01)
+    log_volume = phase_volume_expansion(system, t, states)
+    assert log_volume[0] == pytest.approx(0.0)
+
+
+def test_phase_volume_expansion_is_dissipative_for_lorenz():
+    """Lorenz phase-space volume must contract (log volume strictly
+    decreasing on average) since the system is dissipative."""
+    system = Lorenz(sigma=10.0, rho=28.0, beta=8.0 / 3.0)
+    t, states = system.trajectory(n_steps=1000, dt=0.01)
+    log_volume = phase_volume_expansion(system, t, states)
+    assert log_volume[-1] < 0.0