physicskit 0.1.0__py3-none-any.whl

physicskit/chaos/tests/test_phase_space.py

@@ -0,0 +1,73 @@
+import numpy as np
+import pytest
+
+from physicskit.chaos.systems.billiards import BunimovichStadium, CircleBilliard, SinaiBilliard
+from physicskit.chaos.visualizers.phase_space import plot_billiard_trajectory, plot_poincare_section
+
+ALL_BILLIARDS = [
+    lambda: CircleBilliard(radius=1.0),
+    lambda: SinaiBilliard(cell_size=2.0, scatterer_radius=0.5),
+    lambda: BunimovichStadium(radius=1.0, straight_length=2.0),
+]
+
+
+@pytest.mark.parametrize("make_billiard", ALL_BILLIARDS)
+def test_simulate_many_rays_matches_per_ray_simulate(make_billiard):
+    """The parallel batch kernel must reproduce plain per-ray simulate() exactly."""
+    billiard = make_billiard()
+    pos = billiard.sample_interior_point()
+    angles = np.array([0.3, 1.1, 2.7, 4.0, 5.9])
+
+    batch = billiard.simulate_many_rays(pos, angles, n_bounces=30)
+
+    expected_s, expected_sin_phi = [], []
+    for angle in angles:
+        vel = np.array([np.cos(angle), np.sin(angle)])
+        result = billiard.simulate(pos, vel, n_bounces=30)
+        expected_s.append(result["s"])
+        expected_sin_phi.append(result["sin_phi"])
+
+    np.testing.assert_allclose(batch["s"], np.concatenate(expected_s))
+    np.testing.assert_allclose(batch["sin_phi"], np.concatenate(expected_sin_phi))
+
+
+def test_plot_poincare_section_returns_pooled_scatter_within_bounds():
+    billiard = SinaiBilliard(cell_size=2.0, scatterer_radius=0.5)
+    _, ax = plot_poincare_section(billiard, n_rays=8, n_bounces=20, seed=0)
+    collection = ax.collections[0]
+    offsets = collection.get_offsets()
+    assert offsets.shape == (8 * 20, 2)
+    s, sin_phi = offsets[:, 0], offsets[:, 1]
+    assert np.all(s >= 0.0) and np.all(s <= billiard.perimeter())
+    assert np.all(sin_phi >= -1.0) and np.all(sin_phi <= 1.0)
+
+
+def test_plot_billiard_trajectory_draws_boundary_and_path():
+    billiard = CircleBilliard(radius=1.0)
+    pos = billiard.sample_interior_point()
+    _, ax = plot_billiard_trajectory(billiard, pos, vel=(1.0, 0.3), n_bounces=15)
+    assert len(ax.lines) == 2
+
+
+def test_plot_poincare_section_defaults_to_billiards_own_interior_point():
+    """Rays launched from a circle's exact center (its default interior
+    point) all hit the boundary head-on, so every ray shares sin(phi) = 0 --
+    a documented degenerate case (see test below), not a bug in the default
+    itself: the default must still be ``sample_interior_point()``."""
+    billiard = CircleBilliard(radius=1.0)
+    _, ax = plot_poincare_section(billiard, n_rays=10, n_bounces=20, seed=0)
+    sin_phi = ax.collections[0].get_offsets()[:, 1]
+    assert np.allclose(sin_phi, 0.0, atol=1e-9)
+
+
+def test_plot_poincare_section_pos_override_avoids_circle_center_degeneracy():
+    """An off-center pos, unlike the default center, must produce a genuine
+    family of distinct invariant curves (one sin(phi) per ray, not all the
+    same value)."""
+    billiard = CircleBilliard(radius=1.0)
+    _, ax = plot_poincare_section(billiard, n_rays=10, n_bounces=20, pos=(0.3, 0.0), seed=0)
+    offsets = ax.collections[0].get_offsets()
+    sin_phi_per_ray = np.asarray(offsets[:, 1]).reshape(10, 20)
+    per_ray_values = sin_phi_per_ray[:, 0]
+    assert not np.allclose(sin_phi_per_ray, 0.0, atol=1e-9)
+    assert np.unique(np.round(per_ray_values, 6)).size == 10

physicskit/chaos/tests/test_properties.py

@@ -0,0 +1,116 @@
+"""Property-based tests (Hypothesis) for invariants that should hold across
+the whole input space, not just the handful of fixed examples the other test
+files check -- exact physical/mathematical identities that must hold no
+matter what parameters or initial conditions are chosen.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from hypothesis import given, settings
+from hypothesis import strategies as st
+
+from physicskit.chaos.quantum.maps import QuantumBakersMap, QuantumKickedRotor
+from physicskit.chaos.systems.billiards import BunimovichStadium, CircleBilliard, SinaiBilliard
+from physicskit.chaos.systems.maps import HenonMap
+from physicskit.chaos.utils.metrics import numerical_jacobian_map
+from physicskit.chaos.utils.timeseries import delay_embed
+
+ALL_BILLIARDS = [
+    lambda: CircleBilliard(radius=1.0),
+    lambda: SinaiBilliard(cell_size=2.0, scatterer_radius=0.5),
+    lambda: BunimovichStadium(radius=1.0, straight_length=2.0),
+]
+
+angles = st.floats(min_value=0.0, max_value=2.0 * np.pi, exclude_max=True)
+
+
+@settings(deadline=None, max_examples=30)
+@given(billiard_idx=st.sampled_from(range(len(ALL_BILLIARDS))), angle=angles)
+def test_billiard_speed_is_conserved_for_any_launch_angle(billiard_idx, angle):
+    """Specular reflection is elastic: |v| = 1 must hold after every bounce,
+    for every billiard shape and every launch angle -- not just the sampled
+    angles the example-based tests happen to use."""
+    billiard = ALL_BILLIARDS[billiard_idx]()
+    pos = billiard.sample_interior_point()
+    vel = np.array([np.cos(angle), np.sin(angle)])
+    result = billiard.simulate(pos, vel, n_bounces=50)
+    speeds = np.hypot(result["vx"], result["vy"])
+    np.testing.assert_allclose(speeds, 1.0, atol=1e-8)
+
+
+@settings(deadline=None, max_examples=30)
+@given(billiard_idx=st.sampled_from(range(len(ALL_BILLIARDS))), angle=angles)
+def test_billiard_boundary_coordinate_s_stays_within_perimeter(billiard_idx, angle):
+    """The arclength coordinate s must always lie in [0, perimeter), for any
+    launch angle."""
+    billiard = ALL_BILLIARDS[billiard_idx]()
+    pos = billiard.sample_interior_point()
+    vel = np.array([np.cos(angle), np.sin(angle)])
+    result = billiard.simulate(pos, vel, n_bounces=50)
+    assert np.all(result["s"] >= 0.0)
+    assert np.all(result["s"] <= billiard.perimeter() + 1e-9)
+
+
+@settings(deadline=None, max_examples=50)
+@given(
+    a=st.floats(min_value=0.5, max_value=2.0),
+    b=st.floats(min_value=-0.9, max_value=0.9, allow_nan=False).filter(lambda v: abs(v) > 1e-3),
+    x=st.floats(min_value=-1.0, max_value=1.0),
+    y=st.floats(min_value=-1.0, max_value=1.0),
+)
+def test_henon_map_jacobian_matches_analytic_formula_everywhere(a, b, x, y):
+    """The Henon map's Jacobian is exactly [[-2*a*x, 1], [b, 0]] at every
+    point and every parameter choice, not just the one example the
+    fixed-value test checks."""
+    henon = HenonMap(a=a, b=b)
+    jac = numerical_jacobian_map(henon, np.array([x, y]))
+    expected = np.array([[-2.0 * a * x, 1.0], [b, 0.0]])
+    np.testing.assert_allclose(jac, expected, atol=1e-4, rtol=1e-4)
+
+
+@settings(deadline=None, max_examples=50)
+@given(
+    n=st.integers(min_value=5, max_value=200),
+    dim=st.integers(min_value=1, max_value=4),
+    tau=st.integers(min_value=1, max_value=5),
+)
+def test_delay_embed_shape_formula_holds_for_any_valid_dim_and_tau(n, dim, tau):
+    """delay_embed's output row count must always be n - (dim - 1) * tau,
+    for any series length, dimension, and delay for which that's positive."""
+    n_out = n - (dim - 1) * tau
+    if n_out <= 0:
+        return
+    series = np.arange(n, dtype=np.float64)
+    embedded = delay_embed(series, dim=dim, tau=tau)
+    assert embedded.shape == (n_out, dim)
+    # Each row must be an arithmetic progression with common difference tau,
+    # since the series itself is just np.arange(n).
+    if dim > 1:
+        diffs = np.diff(embedded, axis=1)
+        np.testing.assert_allclose(diffs, float(tau))
+
+
+@settings(deadline=None, max_examples=30)
+@given(k=st.floats(min_value=0.0, max_value=10.0), dim=st.integers(min_value=2, max_value=60))
+def test_quantum_kicked_rotor_floquet_operator_is_unitary_for_any_k_and_dim(k, dim):
+    """The Floquet operator's unitarity is an exact mathematical consequence of
+    being built from products of unitary (DFT and diagonal phase) matrices --
+    it must hold regardless of the kick strength or Hilbert space dimension."""
+    u = QuantumKickedRotor(k=k, dim=dim).floquet_operator()
+    np.testing.assert_allclose(u.conj().T @ u, np.eye(dim), atol=1e-8)
+
+
+@settings(deadline=None, max_examples=30)
+@given(
+    dim=st.integers(min_value=4, max_value=60),
+    alpha=st.floats(min_value=0.1, max_value=0.9, allow_nan=False),
+)
+def test_quantum_bakers_map_floquet_operator_is_unitary_for_any_dim_and_alpha(dim, alpha):
+    """Same unitarity guarantee as the kicked rotor, for any (dim, alpha) pair
+    that yields a valid two-block split."""
+    n1 = round(alpha * dim)
+    if n1 < 1 or n1 > dim - 1:
+        return
+    u = QuantumBakersMap(dim=dim, alpha=alpha).floquet_operator()
+    np.testing.assert_allclose(u.conj().T @ u, np.eye(dim), atol=1e-8)

physicskit/chaos/tests/test_quantum_billiards.py

@@ -0,0 +1,94 @@
+import numpy as np
+import pytest
+
+from physicskit.chaos.quantum.billiards import QuantumBilliard, points_in_billiard
+from physicskit.chaos.systems.billiards import (
+    BunimovichStadium,
+    CircleBilliard,
+    RectangleBilliard,
+    SinaiBilliard,
+)
+
+
+def test_points_in_billiard_excludes_scatterer_hole():
+    """The Sinai billiard's boundary polyline has two components (outer square,
+    inner scatterer circle); a correct point-in-domain test must exclude the
+    scatterer's interior even though it is "inside" the outer square."""
+    billiard = SinaiBilliard(cell_size=2.0, scatterer_radius=0.5)
+    points = np.array(
+        [
+            [0.0, 0.0],  # scatterer center: outside the physical domain
+            [0.3, 0.0],  # inside the scatterer: outside the physical domain
+            [0.7, 0.0],  # outside the scatterer, inside the cell: inside
+            [0.9, 0.9],  # near a corner: inside
+            [1.5, 1.5],  # outside the cell entirely: outside
+        ]
+    )
+    expected = np.array([False, False, True, True, False])
+    assert np.array_equal(points_in_billiard(billiard, points), expected)
+
+
+def test_points_in_billiard_circle():
+    billiard = CircleBilliard(radius=1.0)
+    points = np.array([[0.0, 0.0], [0.5, 0.5], [0.99, 0.0], [1.01, 0.0], [2.0, 2.0]])
+    expected = np.array([True, True, True, False, False])
+    assert np.array_equal(points_in_billiard(billiard, points), expected)
+
+
+def test_quantum_billiard_rejects_low_resolution():
+    with pytest.raises(ValueError):
+        QuantumBilliard(CircleBilliard(radius=1.0), resolution=5)
+
+
+def test_quantum_billiard_eigenvalues_are_positive_and_ascending():
+    qb = QuantumBilliard(RectangleBilliard(width=2.0, height=1.0), resolution=80)
+    eigenvalues, eigenfunctions = qb.eigenstates(n_states=6)
+    assert eigenvalues.shape == (6,)
+    assert np.all(eigenvalues > 0.0)
+    assert np.all(np.diff(eigenvalues) >= 0.0)
+    assert eigenfunctions.shape == (6, *qb.grid()[0].shape)
+
+
+def test_quantum_billiard_eigenfunctions_vanish_outside_domain():
+    qb = QuantumBilliard(CircleBilliard(radius=1.0), resolution=80)
+    _, eigenfunctions = qb.eigenstates(n_states=3)
+    inside = qb._inside
+    assert np.all(np.isnan(eigenfunctions[:, ~inside]))
+    assert np.all(np.isfinite(eigenfunctions[:, inside]))
+
+
+def test_quantum_billiard_matches_analytic_rectangle_spectrum():
+    """The Dirichlet rectangle's eigenvalues are known exactly:
+    k^2_mn = pi^2 * (m^2/Lx^2 + n^2/Ly^2). The finite-difference solver should
+    match this to a few percent at a moderate grid resolution."""
+    lx, ly = 2.0, 1.0
+    qb = QuantumBilliard(RectangleBilliard(width=lx, height=ly), resolution=150)
+    eigenvalues, _ = qb.eigenstates(n_states=6)
+
+    exact = sorted(np.pi**2 * (m**2 / lx**2 + n**2 / ly**2) for m in range(1, 8) for n in range(1, 8))[:6]
+
+    rel_err = np.abs(eigenvalues - np.array(exact)) / np.array(exact)
+    assert np.all(rel_err < 0.05)
+
+
+def test_quantum_billiard_weyl_law_matches_actual_counts_reasonably():
+    """Weyl's law is an asymptotic average, not exact for any individual
+    eigenvalue, but the smooth counting function should sit close to the
+    actual staircase over a modest range of low-lying states."""
+    qb = QuantumBilliard(BunimovichStadium(radius=1.0, straight_length=2.0), resolution=110)
+    n_states = 20
+    wavenumbers = qb.wavenumbers(n_states)
+    actual_counts = np.arange(1, n_states + 1)
+    predicted_counts = qb.weyl_counting_function(wavenumbers)
+    assert np.mean(np.abs(actual_counts - predicted_counts)) < 3.0
+
+
+def test_quantum_billiard_wavenumbers_are_sqrt_of_eigenvalues():
+    qb = QuantumBilliard(CircleBilliard(radius=1.0), resolution=80)
+    eigenvalues, _ = qb.eigenstates(4)
+    assert np.allclose(qb.wavenumbers(4), np.sqrt(eigenvalues))
+
+
+def test_quantum_billiard_area_is_close_to_analytic_rectangle_area():
+    qb = QuantumBilliard(RectangleBilliard(width=2.0, height=1.5), resolution=150)
+    assert qb.area() == pytest.approx(2.0 * 1.5, rel=0.02)

physicskit/chaos/tests/test_quantum_maps.py

@@ -0,0 +1,144 @@
+import numpy as np
+import pytest
+
+from physicskit.chaos.quantum.husimi import husimi_function
+from physicskit.chaos.quantum.maps import QuantumBakersMap, QuantumKickedRotor
+from physicskit.chaos.systems.maps import BakersMap, StandardMap
+
+
+def _is_unitary(u, atol=1e-10):
+    n = u.shape[0]
+    return np.allclose(u.conj().T @ u, np.eye(n), atol=atol)
+
+
+@pytest.mark.parametrize("dim", [8, 33, 64])
+def test_kicked_rotor_floquet_operator_is_unitary(dim):
+    qkr = QuantumKickedRotor(k=1.7, dim=dim)
+    assert _is_unitary(qkr.floquet_operator())
+
+
+def test_kicked_rotor_rejects_too_small_dim():
+    with pytest.raises(ValueError):
+        QuantumKickedRotor(dim=1)
+
+
+def test_kicked_rotor_default_hbar_matches_torus_quantization():
+    qkr = QuantumKickedRotor(dim=100)
+    assert qkr.hbar == pytest.approx(2.0 * np.pi / 100)
+
+
+def test_kicked_rotor_evolve_preserves_norm_and_dimension():
+    qkr = QuantumKickedRotor(k=2.0, dim=50)
+    psi0 = qkr.coherent_state(1.0, 2.0)
+    states = qkr.evolve(psi0, n_steps=10)
+    assert states.shape == (11, 50)
+    assert np.allclose(np.linalg.norm(states, axis=1), 1.0)
+
+
+def test_kicked_rotor_eigenphases_are_on_unit_circle():
+    qkr = QuantumKickedRotor(k=3.0, dim=40)
+    phases = qkr.eigenphases()
+    assert phases.shape == (40,)
+    assert np.all(phases >= -np.pi) and np.all(phases <= np.pi)
+    assert np.all(np.diff(phases) >= 0.0)
+
+
+def test_kicked_rotor_coherent_state_husimi_peaks_at_its_own_center():
+    qkr = QuantumKickedRotor(k=1.0, dim=300)
+    theta0, p0 = 2.3, 4.1
+    psi = qkr.coherent_state(theta0, p0)
+    theta_grid, p_grid, husimi = qkr.husimi(psi, resolution=150)
+    idx = np.unravel_index(np.argmax(husimi), husimi.shape)
+    assert theta_grid[idx] == pytest.approx(theta0, abs=0.1)
+    assert p_grid[idx] == pytest.approx(p0, abs=0.1)
+
+
+@pytest.mark.slow
+def test_kicked_rotor_husimi_peak_tracks_classical_orbit_at_weak_kick():
+    """At small k the classical map is near-integrable, so a narrow wavepacket's
+    Husimi peak should closely track the classical StandardMap orbit for a
+    handful of iterations, before it has a chance to spread appreciably."""
+    k = 0.3
+    dim = 200
+    theta0, p0 = 1.0, 1.0
+    qkr = QuantumKickedRotor(k=k, dim=dim)
+    psi = qkr.coherent_state(theta0, p0)
+    states = qkr.evolve(psi, n_steps=4)
+
+    classical = StandardMap(k=k).trajectory(np.array([theta0, p0]), n_iter=4)
+
+    for i in range(5):
+        theta_grid, p_grid, husimi = qkr.husimi(states[i], resolution=80)
+        idx = np.unravel_index(np.argmax(husimi), husimi.shape)
+        assert theta_grid[idx] == pytest.approx(classical[i, 0], abs=0.15)
+        assert p_grid[idx] == pytest.approx(classical[i, 1], abs=0.15)
+
+
+@pytest.mark.parametrize("dim", [8, 32, 100])
+def test_bakers_map_floquet_operator_is_unitary_symmetric(dim):
+    qbm = QuantumBakersMap(dim=dim, alpha=0.5)
+    assert _is_unitary(qbm.floquet_operator())
+
+
+@pytest.mark.parametrize("dim,alpha", [(10, 0.3), (100, 0.7), (99, 1.0 / 3.0)])
+def test_bakers_map_floquet_operator_is_unitary_asymmetric(dim, alpha):
+    qbm = QuantumBakersMap(dim=dim, alpha=alpha)
+    assert _is_unitary(qbm.floquet_operator())
+
+
+def test_bakers_map_rejects_invalid_alpha():
+    with pytest.raises(ValueError):
+        QuantumBakersMap(dim=10, alpha=0.0)
+    with pytest.raises(ValueError):
+        QuantumBakersMap(dim=10, alpha=1.0)
+
+
+def test_bakers_map_rejects_dim_alpha_combo_with_empty_block():
+    with pytest.raises(ValueError):
+        QuantumBakersMap(dim=10, alpha=0.02)
+
+
+def test_bakers_map_evolve_preserves_norm_and_dimension():
+    qbm = QuantumBakersMap(dim=48)
+    psi0 = qbm.coherent_state(0.2, 0.6)
+    states = qbm.evolve(psi0, n_steps=6)
+    assert states.shape == (7, 48)
+    assert np.allclose(np.linalg.norm(states, axis=1), 1.0)
+
+
+def test_bakers_map_coherent_state_husimi_peaks_at_its_own_center():
+    qbm = QuantumBakersMap(dim=250)
+    q0, p0 = 0.35, 0.72
+    psi = qbm.coherent_state(q0, p0)
+    q_grid, p_grid, husimi = qbm.husimi(psi, resolution=150)
+    idx = np.unravel_index(np.argmax(husimi), husimi.shape)
+    assert q_grid[idx] == pytest.approx(q0, abs=0.03)
+    assert p_grid[idx] == pytest.approx(p0, abs=0.03)
+
+
+def test_bakers_map_hbar_matches_classical_area_quantization():
+    qbm = QuantumBakersMap(dim=40)
+    assert qbm.hbar == pytest.approx(1.0 / 40)
+
+
+def test_bakers_map_eigenphases_shape_and_range():
+    qbm = QuantumBakersMap(dim=40)
+    phases = qbm.eigenphases()
+    assert phases.shape == (40,)
+    assert np.all(np.diff(phases) >= 0.0)
+
+
+def test_husimi_function_is_normalized_to_unit_peak():
+    n = 64
+    psi = np.zeros(n, dtype=complex)
+    psi[0] = 1.0
+    _, _, husimi = husimi_function(psi, hbar=2.0 * np.pi / n, q_period=2.0 * np.pi, resolution=40)
+    assert husimi.max() == pytest.approx(1.0)
+    assert husimi.min() >= 0.0
+
+
+def test_classical_bakers_map_default_alpha_matches_quantum_default():
+    """physicskit.chaos's classical BakersMap defaults to alpha=0.5; the quantum
+    version's default should match, so QuantumBakersMap(dim) quantizes
+    BakersMap() out of the box."""
+    assert BakersMap().alpha == QuantumBakersMap(dim=10).alpha

physicskit/chaos/tests/test_recurrence.py

@@ -0,0 +1,51 @@
+import numpy as np
+import pytest
+
+from physicskit.chaos.systems.maps import HenonMap
+from physicskit.chaos.utils.recurrence import kac_lemma_estimate, recurrence_matrix, recurrence_times
+
+
+def test_recurrence_matrix_is_symmetric_with_true_diagonal():
+    rng = np.random.default_rng(0)
+    states = rng.uniform(size=(50, 2))
+    matrix = recurrence_matrix(states, epsilon=0.3)
+    assert matrix.shape == (50, 50)
+    assert matrix.dtype == np.bool_
+    np.testing.assert_array_equal(matrix, matrix.T)
+    assert np.all(np.diag(matrix))  # every point recurs to itself at distance 0
+
+
+def test_recurrence_matrix_epsilon_zero_is_only_the_diagonal():
+    rng = np.random.default_rng(0)
+    states = rng.uniform(size=(20, 2))
+    matrix = recurrence_matrix(states, epsilon=1e-12)
+    np.testing.assert_array_equal(matrix, np.eye(20, dtype=bool))
+
+
+def test_recurrence_times_detects_a_simple_periodic_orbit():
+    """A trajectory that revisits the same three points in a cycle should
+    show a recurrence time of exactly the period (3 steps) every time."""
+    states = np.tile(np.array([[0.0, 0.0], [1.0, 0.0], [2.0, 0.0]]), (10, 1))
+    times = recurrence_times(states, epsilon=0.01, reference_idx=0, dt=1.0)
+    assert times.size > 0
+    np.testing.assert_allclose(times, 3.0)
+
+
+def test_recurrence_times_scales_with_dt():
+    states = np.tile(np.array([[0.0, 0.0], [1.0, 0.0], [2.0, 0.0]]), (10, 1))
+    times_dt1 = recurrence_times(states, epsilon=0.01, dt=1.0)
+    times_dt2 = recurrence_times(states, epsilon=0.01, dt=0.5)
+    np.testing.assert_allclose(times_dt2, times_dt1 * 0.5)
+
+
+def test_kac_lemma_holds_for_a_long_henon_trajectory():
+    """Kac's lemma predicts mean_recurrence_time * measure(epsilon-ball) ~= 1
+    for an ergodic, measure-preserving trajectory sampled long enough."""
+    system = HenonMap(a=1.4, b=0.3)
+    traj = system.trajectory(np.array([0.1, 0.1]), n_iter=100000)
+    traj = traj[500:]  # discard transient
+
+    mean_time, measure, kac_product = kac_lemma_estimate(traj, epsilon=0.05, reference_idx=0)
+    assert mean_time > 0.0
+    assert 0.0 < measure < 1.0
+    assert kac_product == pytest.approx(1.0, abs=0.1)

physicskit/chaos/tests/test_repr_and_api_consistency.py

@@ -0,0 +1,134 @@
+import numpy as np
+import pytest
+
+from physicskit.chaos.core.base_system import DiscreteMap, DynamicalSystem, get_init_params
+from physicskit.chaos.exceptions import ChaoskitError, InvalidParameterError
+from physicskit.chaos.quantum.billiards import QuantumBilliard
+from physicskit.chaos.quantum.maps import QuantumBakersMap, QuantumKickedRotor
+from physicskit.chaos.systems.billiards import CircleBilliard, EllipseBilliard, SinaiBilliard
+from physicskit.chaos.systems.continuous import Lorenz, MagneticPendulum
+from physicskit.chaos.systems.maps import BakersMap, HenonMap, LogisticMap, StandardMap
+
+
+@pytest.mark.parametrize(
+    "obj, expected_substrings",
+    [
+        (Lorenz(sigma=10.0, rho=28.0), ["Lorenz(", "sigma=10.0", "rho=28.0"]),
+        (HenonMap(a=1.4, b=0.3), ["HenonMap(", "a=1.4", "b=0.3"]),
+        (SinaiBilliard(cell_size=2.0), ["SinaiBilliard(", "cell_size=2.0"]),
+        (MagneticPendulum(friction=0.3), ["MagneticPendulum(", "friction=0.3"]),
+        (QuantumKickedRotor(k=2.0, dim=32), ["QuantumKickedRotor(", "k=2.0", "dim=32"]),
+        (QuantumBakersMap(dim=40, alpha=0.5), ["QuantumBakersMap(", "dim=40", "alpha=0.5"]),
+        (
+            QuantumBilliard(CircleBilliard(radius=1.0), resolution=50),
+            ["QuantumBilliard(", "resolution=50"],
+        ),
+    ],
+)
+def test_repr_includes_class_name_and_init_params(obj, expected_substrings):
+    text = repr(obj)
+    for substring in expected_substrings:
+        assert substring in text
+
+
+def test_repr_round_trips_through_eval_for_simple_scalar_params():
+    """For classes whose __init__ params are all simple scalars, repr()
+    should produce a string that reconstructs an equivalent object."""
+    original = HenonMap(a=1.4, b=0.3)
+    reconstructed = eval(repr(original), {"HenonMap": HenonMap})
+    assert reconstructed.a == original.a
+    assert reconstructed.b == original.b
+
+
+@pytest.mark.parametrize(
+    "make_map",
+    [lambda: StandardMap(), lambda: HenonMap(), lambda: BakersMap(), lambda: LogisticMap()],
+)
+def test_discrete_map_trajectory_defaults_state0_like_dynamical_system(make_map):
+    """DiscreteMap.trajectory() should default state0 via initial_state(),
+    exactly like DynamicalSystem.trajectory() already does -- not require it
+    positionally."""
+    system = make_map()
+    traj = system.trajectory(n_iter=5)
+    assert traj.shape == (6, system.dim)
+
+
+def test_invalid_parameter_error_is_both_chaos_and_value_error():
+    with pytest.raises(ChaoskitError):
+        EllipseBilliard(semi_major=1.0, semi_minor=1.5)
+    with pytest.raises(ValueError):
+        EllipseBilliard(semi_major=1.0, semi_minor=1.5)
+    with pytest.raises(InvalidParameterError):
+        EllipseBilliard(semi_major=1.0, semi_minor=1.5)
+
+
+class _MinimalDynamicalSystem(DynamicalSystem):
+    """The smallest possible concrete subclass: overrides only the
+    abstract ``rhs``, so calling ``initial_state()`` exercises
+    DynamicalSystem's own default (every real system in this package
+    overrides it instead, per module docstring)."""
+
+    dim = 2
+
+    def rhs(self, state, t):
+        return -state
+
+
+class _MinimalDiscreteMap(DiscreteMap):
+    """The smallest possible concrete subclass: overrides only the
+    abstract ``step``, so calling ``initial_state()``/``trajectory()``
+    exercises DiscreteMap's own defaults (every real map in this package
+    overrides both, per module docstring)."""
+
+    dim = 1
+
+    def step(self, state):
+        return state + 1.0
+
+
+def test_dynamical_system_initial_state_default_raises_not_implemented():
+    with pytest.raises(NotImplementedError):
+        _MinimalDynamicalSystem().initial_state()
+
+
+def test_discrete_map_initial_state_default_raises_not_implemented():
+    with pytest.raises(NotImplementedError):
+        _MinimalDiscreteMap().initial_state()
+
+
+def test_discrete_map_trajectory_default_implementation_iterates_step():
+    system = _MinimalDiscreteMap()
+    traj = system.trajectory(state0=np.array([0.0]), n_iter=3)
+    np.testing.assert_allclose(traj, [[0.0], [1.0], [2.0], [3.0]])
+
+
+def test_get_init_params_skips_unreadable_signature_and_missing_attributes():
+    """get_init_params must degrade gracefully both when the constructor's
+    signature can't be introspected (returns {}) and when a constructor
+    parameter isn't stored under its own name on the instance (that one
+    param is skipped, not raised)."""
+
+    class Skippy:
+        def __init__(self, a, b=1):
+            self.a = a
+            # b intentionally not stored as self.b
+
+    obj = Skippy(a=1, b=2)
+    assert get_init_params(obj) == {"a": 1}
+
+    class Unreadable:
+        def __init__(self, a=1):
+            self.a = a
+
+    unreadable_obj = Unreadable(a=5)
+    Unreadable.__init__ = 5  # no longer a real callable/function
+    assert get_init_params(unreadable_obj) == {}
+
+
+def test_billiard_boundary_arrays_matches_build_boundary_output():
+    billiard = CircleBilliard(radius=2.0)
+    segments, arcs, arc_full = billiard.boundary_arrays()
+    assert segments.shape == (0, 4)
+    assert arcs.shape == (1, 5)
+    assert arc_full.tolist() == [True]
+    np.testing.assert_allclose(arcs[0][:3], [0.0, 0.0, 2.0])

physicskit/chaos/tests/test_section.py

@@ -0,0 +1,49 @@
+import numpy as np
+
+from physicskit.chaos.systems.continuous import RestrictedThreeBody
+from physicskit.chaos.visualizers.section import plot_poincare_map, poincare_crossings
+
+
+def test_poincare_crossings_only_keeps_the_requested_direction():
+    """Every returned crossing must have the section coordinate increasing
+    through `value` when direction=1.0 (and decreasing for direction=-1.0)."""
+    system = RestrictedThreeBody()
+    state0 = system.initial_state()
+
+    up = poincare_crossings(system, state0, coord=1, value=0.0, direction=1.0, t_max=2.0 * 17.0652165601579625588917206249, dt=1e-4)
+    down = poincare_crossings(system, state0, coord=1, value=0.0, direction=-1.0, t_max=2.0 * 17.0652165601579625588917206249, dt=1e-4)
+
+    assert up.shape[0] > 0
+    assert down.shape[0] > 0
+    # Interpolated crossings should sit essentially exactly on the surface.
+    np.testing.assert_allclose(up[:, 1], 0.0, atol=1e-6)
+    np.testing.assert_allclose(down[:, 1], 0.0, atol=1e-6)
+
+
+def test_poincare_crossings_returns_empty_array_for_a_surface_never_reached():
+    system = RestrictedThreeBody()
+    state0 = system.initial_state()
+    crossings = poincare_crossings(system, state0, coord=1, value=100.0, t_max=1.0, dt=1e-3)
+    assert crossings.shape == (0, system.dim)
+
+
+def test_plot_poincare_map_draws_one_scatter_series_per_initial_state():
+    system = RestrictedThreeBody()
+    state0 = system.initial_state()
+    state0_perturbed = state0.copy()
+    state0_perturbed[3] *= 1.001
+
+    _, ax = plot_poincare_map(
+        system,
+        [state0, state0_perturbed],
+        coord=1,
+        value=0.0,
+        direction=1.0,
+        t_max=2.0 * 17.0652165601579625588917206249,
+        dt=1e-4,
+        labels=["reference", "perturbed"],
+    )
+    assert len(ax.collections) == 2
+    legend = ax.get_legend()
+    assert legend is not None
+    assert [text.get_text() for text in legend.get_texts()] == ["reference", "perturbed"]