physicskit 0.1.0__py3-none-any.whl

physicskit/chaos/tests/test_spectral.py

@@ -0,0 +1,48 @@
+import numpy as np
+import pytest
+
+from physicskit.chaos.utils.spectral import autocorrelation, power_spectrum
+
+
+def test_power_spectrum_of_pure_sine_peaks_at_its_frequency():
+    dt = 0.01
+    t = np.arange(0, 10, dt)
+    freq = 3.0
+    series = np.sin(2.0 * np.pi * freq * t)
+
+    frequencies, power = power_spectrum(series, dt=dt)
+    peak_freq = frequencies[np.argmax(power)]
+    assert peak_freq == pytest.approx(freq, abs=0.05)
+
+
+def test_power_spectrum_shapes_and_nonnegative():
+    series = np.random.default_rng(0).normal(size=200)
+    frequencies, power = power_spectrum(series, dt=1.0)
+    assert frequencies.shape == power.shape == (101,)
+    assert np.all(power >= 0.0)
+
+
+def test_autocorrelation_of_pure_sine_is_periodic():
+    dt = 0.01
+    t = np.arange(0, 20, dt)
+    freq = 2.0
+    series = np.sin(2.0 * np.pi * freq * t)
+
+    acf = autocorrelation(series, max_lag=len(series) - 1)
+    assert acf[0] == pytest.approx(1.0)
+    period_samples = round(1.0 / freq / dt)
+    assert acf[period_samples] == pytest.approx(1.0, abs=0.05)
+
+
+def test_autocorrelation_of_white_noise_decays_immediately():
+    rng = np.random.default_rng(0)
+    series = rng.normal(size=5000)
+    acf = autocorrelation(series, max_lag=50)
+    assert acf[0] == pytest.approx(1.0)
+    assert abs(acf[1]) < 0.1
+
+
+def test_autocorrelation_default_max_lag():
+    series = np.random.default_rng(0).normal(size=50)
+    acf = autocorrelation(series)
+    assert acf.shape == (50,)

physicskit/chaos/tests/test_streamlit_app.py

@@ -0,0 +1,45 @@
+"""Smoke tests for the Streamlit explorer app, run headlessly via
+``streamlit.testing.v1.AppTest`` (no browser or server needed)."""
+
+from pathlib import Path
+
+import pytest
+
+st_testing = pytest.importorskip("streamlit.testing.v1")
+
+APP_PATH = str(Path(__file__).resolve().parent.parent / "app" / "streamlit_app.py")
+
+
+def _run() -> "st_testing.AppTest":
+    at = st_testing.AppTest.from_file(APP_PATH)
+    at.run(timeout=120)
+    return at
+
+
+def test_app_loads_with_no_exceptions_in_default_state():
+    at = _run()
+    assert not at.exception
+
+
+@pytest.mark.parametrize("demo", ["Billiards", "Continuous systems", "Bifurcation diagrams", "Basins of attraction"])
+def test_each_demo_runs_with_no_exceptions(demo):
+    at = _run()
+    at.selectbox[0].set_value(demo).run(timeout=120)
+    assert not at.exception
+
+
+def test_every_billiard_shape_runs_with_no_exceptions():
+    at = _run()
+    for option in list(at.selectbox[1].options):
+        at.selectbox[1].set_value(option).run(timeout=120)
+        assert not at.exception, f"{option} raised: {list(at.exception)}"
+
+
+def test_every_map_and_sweep_parameter_runs_with_no_exceptions():
+    at = _run()
+    at.selectbox[0].set_value("Bifurcation diagrams").run(timeout=120)
+    for map_name in list(at.selectbox[1].options):
+        at.selectbox[1].set_value(map_name).run(timeout=120)
+        for param_name in list(at.selectbox[2].options):
+            at.selectbox[2].set_value(param_name).run(timeout=120)
+            assert not at.exception, f"{map_name}/{param_name} raised: {list(at.exception)}"

physicskit/chaos/tests/test_timeseries.py

@@ -0,0 +1,131 @@
+import numpy as np
+import pytest
+
+from physicskit.chaos.systems.continuous import Lorenz
+from physicskit.chaos.utils.timeseries import (
+    average_log_divergence,
+    delay_embed,
+    iaaft_surrogate,
+    rosenstein_lyapunov,
+    surrogate_test,
+)
+
+
+def test_delay_embed_shape_and_values():
+    series = np.arange(10.0)
+    embedded = delay_embed(series, dim=3, tau=2)
+    assert embedded.shape == (6, 3)
+    np.testing.assert_allclose(embedded[0], [0.0, 2.0, 4.0])
+    np.testing.assert_allclose(embedded[-1], [5.0, 7.0, 9.0])
+
+
+def test_delay_embed_rejects_series_too_short():
+    with pytest.raises(ValueError):
+        delay_embed(np.arange(5.0), dim=10, tau=1)
+
+
+def test_average_log_divergence_returns_matching_shapes():
+    rng = np.random.default_rng(0)
+    series = rng.normal(size=500)
+    steps, log_div = average_log_divergence(series, dim=3, tau=1, max_iter=20)
+    assert steps.shape == log_div.shape
+    assert steps.size > 0
+
+
+def test_average_log_divergence_stops_early_once_no_pairs_remain_in_range():
+    """With max_iter set far beyond what the series length can support, the
+    forward-evolution loop must break out early (rather than index out of
+    bounds) once every candidate pair's forward offset runs past the end of
+    the series."""
+    series = np.sin(np.linspace(0, 20, 60))
+    steps, log_div = average_log_divergence(series, dim=2, tau=1, max_iter=1000)
+    assert steps.shape == log_div.shape
+    assert steps.size > 0
+    assert steps[-1] < 1000 - 1
+
+
+def test_average_log_divergence_skips_steps_with_only_exact_zero_distances():
+    """A constant series makes every embedded point identical, so its
+    nearest-neighbor distance is exactly zero at every forward step; those
+    steps must be skipped (not averaged as log(0) = -inf), leaving no valid
+    steps at all here."""
+    series = np.full(50, 3.0)
+    steps, log_div = average_log_divergence(series, dim=2, tau=1, max_iter=5)
+    assert steps.shape == (0,)
+    assert log_div.shape == (0,)
+
+
+@pytest.mark.slow
+def test_rosenstein_lyapunov_matches_known_lorenz_exponent():
+    """The Lorenz system's largest Lyapunov exponent is well known to be
+    approximately 0.905; estimating it from a raw x(t) time series (no
+    equations used) with Rosenstein's algorithm should get reasonably close."""
+    system = Lorenz()
+    dt = 0.01
+    _, states = system.trajectory(n_steps=12000, dt=dt)
+    x = states[1000:, 0]
+
+    lam = rosenstein_lyapunov(x, dim=5, tau=10, dt=dt, fit_fraction=0.3)
+    assert 0.5 < lam < 1.3
+
+
+def test_rosenstein_lyapunov_rejects_too_short_series():
+    with pytest.raises(ValueError):
+        rosenstein_lyapunov(np.arange(5.0), dim=3, tau=1)
+
+
+def test_iaaft_surrogate_preserves_mean_and_std():
+    rng = np.random.default_rng(0)
+    series = rng.normal(loc=3.0, scale=2.0, size=1000)
+    surrogate = iaaft_surrogate(series, n_iter=50, seed=1)
+    assert surrogate.mean() == pytest.approx(series.mean(), abs=1e-9)
+    assert surrogate.std() == pytest.approx(series.std(), abs=1e-9)
+
+
+def test_iaaft_surrogate_preserves_power_spectrum_closely():
+    system = Lorenz()
+    _, states = system.trajectory(n_steps=4000, dt=0.01)
+    x = states[500:, 0]
+
+    surrogate = iaaft_surrogate(x, n_iter=100, seed=0)
+    original_spectrum = np.abs(np.fft.rfft(x))
+    surrogate_spectrum = np.abs(np.fft.rfft(surrogate))
+    relative_error = np.max(np.abs(original_spectrum - surrogate_spectrum)) / np.max(original_spectrum)
+    assert relative_error < 0.05
+
+
+@pytest.mark.slow
+def test_surrogate_test_detects_nonlinear_structure_in_lorenz():
+    """Lorenz x(t) has genuine deterministic/nonlinear structure that IAAFT
+    surrogates (linear stochastic realizations with the same spectrum) lack,
+    so the observed statistic should be many surrogate-std-devs away from the
+    surrogate distribution."""
+    system = Lorenz()
+    dt = 0.01
+    _, states = system.trajectory(n_steps=6000, dt=dt)
+    x = states[1000:, 0]
+
+    def statistic(series):
+        return rosenstein_lyapunov(series, dim=5, tau=10, dt=dt, fit_fraction=0.3)
+
+    _observed, surrogate_values, significance = surrogate_test(x, statistic, n_surrogates=6, n_iter=15, seed=0)
+    assert surrogate_values.shape == (6,)
+    assert significance > 2.0
+
+
+def test_surrogate_test_finds_no_structure_in_pure_noise():
+    """White noise has no structure beyond its (flat) spectrum and
+    distribution, so a nonlinear statistic (here, the same Rosenstein
+    exponent used to detect Lorenz's structure) should come out statistically
+    indistinguishable between the noise and its own surrogates (low
+    significance) -- unlike a trivially IAAFT-invariant statistic such as the
+    standard deviation, which every surrogate reproduces exactly by
+    construction and would give a meaningless zero-variance comparison."""
+    rng = np.random.default_rng(0)
+    noise = rng.normal(size=2000)
+
+    def statistic(series):
+        return rosenstein_lyapunov(series, dim=5, tau=1, fit_fraction=0.3)
+
+    _observed, _surrogate_values, significance = surrogate_test(noise, statistic, n_surrogates=9, n_iter=20, seed=1)
+    assert significance < 2.0

physicskit/chaos/tests/test_viewer3d.py

@@ -0,0 +1,41 @@
+import numpy as np
+import pytest
+
+pv_module = pytest.importorskip("pyvista")
+
+from physicskit.chaos.systems.continuous import Lorenz
+from physicskit.chaos.visualizers.viewer3d import pyvista_trajectory
+
+
+def test_pyvista_trajectory_returns_plotter_with_expected_point_count():
+    system = Lorenz()
+    _, states = system.trajectory(n_steps=200, dt=0.01)
+    plotter = pyvista_trajectory(states, off_screen=True)
+    try:
+        assert isinstance(plotter, pv_module.Plotter)
+        image = plotter.screenshot()
+        assert image.ndim == 3 and image.shape[2] == 3
+    finally:
+        plotter.close()
+
+
+def test_pyvista_trajectory_color_by_speed_runs_without_error():
+    system = Lorenz()
+    _, states = system.trajectory(n_steps=200, dt=0.01)
+    plotter = pyvista_trajectory(states, color_by="speed", off_screen=True)
+    try:
+        plotter.screenshot()
+    finally:
+        plotter.close()
+
+
+def test_pyvista_trajectory_uses_selected_components():
+    states = np.column_stack([np.linspace(0, 1, 20), np.linspace(0, 2, 20), np.linspace(0, 3, 20), np.linspace(0, 4, 20)])
+    plotter = pyvista_trajectory(states, components=(1, 2, 3), off_screen=True)
+    try:
+        mesh = plotter.meshes[0]
+        np.testing.assert_allclose(mesh.points[:, 0], states[:, 1])
+        np.testing.assert_allclose(mesh.points[:, 1], states[:, 2])
+        np.testing.assert_allclose(mesh.points[:, 2], states[:, 3])
+    finally:
+        plotter.close()

physicskit/chaos/utils/__init__.py

@@ -0,0 +1,46 @@
+from physicskit.chaos.utils.dimension import box_counting_dimension, correlation_dimension
+from physicskit.chaos.utils.io import load_arrays, load_system_config, save_arrays, save_system_config
+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,
+)
+from physicskit.chaos.utils.recurrence import kac_lemma_estimate, recurrence_matrix, recurrence_times
+from physicskit.chaos.utils.spectral import autocorrelation, power_spectrum
+from physicskit.chaos.utils.timeseries import (
+    average_log_divergence,
+    delay_embed,
+    iaaft_surrogate,
+    rosenstein_lyapunov,
+    surrogate_test,
+)
+
+__all__ = [
+    "autocorrelation",
+    "average_log_divergence",
+    "benettin_lyapunov_spectrum",
+    "box_counting_dimension",
+    "correlation_dimension",
+    "delay_embed",
+    "energy_drift",
+    "iaaft_surrogate",
+    "kac_lemma_estimate",
+    "load_arrays",
+    "load_system_config",
+    "lyapunov_exponent_from_divergence",
+    "map_lyapunov_spectrum",
+    "numerical_jacobian",
+    "numerical_jacobian_map",
+    "phase_volume_expansion",
+    "power_spectrum",
+    "recurrence_matrix",
+    "recurrence_times",
+    "rosenstein_lyapunov",
+    "save_arrays",
+    "save_system_config",
+    "surrogate_test",
+]

physicskit/chaos/utils/dimension.py

@@ -0,0 +1,139 @@
+"""Fractal dimension estimators: box-counting (capacity) and correlation dimension.
+
+Both estimators quantify how the "size" of a point cloud (typically a sampled
+strange attractor) scales as the measuring resolution ``epsilon`` shrinks,
+and both reduce to the ordinary embedding dimension for a non-fractal set
+(e.g. a filled disk in 2D gives dimension ~2, a line segment gives dimension
+~1) but return a *non-integer* value for a genuine fractal attractor.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+from scipy.spatial.distance import pdist
+
+
+def box_counting_dimension(
+    points: ArrayLike,
+    n_scales: int = 20,
+    eps_min: float | None = None,
+    eps_max: float | None = None,
+) -> tuple[float, NDArray[np.float64], NDArray[np.float64]]:
+    """Estimate the box-counting (capacity) dimension ``D0`` of a point cloud.
+
+    Covers the bounding box of `points` with a grid of boxes of side
+    `epsilon`, counts the number of occupied boxes ``N(epsilon)`` over a
+    range of `epsilon`, and estimates ``D0`` as the slope of
+    ``log(N(epsilon))`` vs. ``log(1/epsilon)`` (via ordinary least squares).
+
+    Parameters
+    ----------
+    points : array_like of float, shape (n, dim)
+        Point cloud to measure (e.g. a sampled attractor trajectory).
+    n_scales : int, default 20
+        Number of `epsilon` values to evaluate, log-spaced between `eps_min`
+        and `eps_max`.
+    eps_min : float, optional
+        Smallest box size; defaults to ``1/200`` of the point cloud's extent.
+    eps_max : float, optional
+        Largest box size; defaults to ``1/2`` of the point cloud's extent.
+
+    Returns
+    -------
+    D0 : float
+        Estimated box-counting dimension.
+    epsilons : ndarray of float, shape (n_scales,)
+        The box sizes evaluated.
+    counts : ndarray of float, shape (n_scales,)
+        The number of occupied boxes ``N(epsilon)`` at each box size.
+
+    Notes
+    -----
+    Once `epsilon` is small enough that most occupied boxes contain only a
+    single point, ``N(epsilon)`` stops scaling like the true fractal measure
+    and instead approaches the point count itself, biasing ``D0`` low. If the
+    estimate looks suspiciously low (e.g. well under 2 for a point cloud that
+    should densely fill a 2D region), either supply a larger `eps_min` or use
+    more sample points so the default (finer) `eps_min` stays in the regime
+    where boxes still contain multiple points on average.
+    """
+    points = np.atleast_2d(np.asarray(points, dtype=np.float64))
+    mins = points.min(axis=0)
+    extent = float(np.max(points.max(axis=0) - mins))
+    if eps_max is None:
+        eps_max = extent / 2.0
+    if eps_min is None:
+        eps_min = extent / 200.0
+
+    epsilons = np.geomspace(eps_max, eps_min, n_scales)
+    counts = np.empty(n_scales)
+    for i, eps in enumerate(epsilons):
+        box_idx = np.floor((points - mins) / eps).astype(np.int64)
+        counts[i] = np.unique(box_idx, axis=0).shape[0]
+
+    slope, _ = np.polyfit(np.log(1.0 / epsilons), np.log(counts), 1)
+    return float(slope), epsilons, counts
+
+
+def correlation_dimension(
+    points: ArrayLike,
+    n_scales: int = 20,
+    eps_min: float | None = None,
+    eps_max: float | None = None,
+) -> tuple[float, NDArray[np.float64], NDArray[np.float64]]:
+    """Estimate the correlation dimension ``D2`` via the Grassberger-Procaccia algorithm.
+
+    Computes the correlation sum ``C(epsilon)`` -- the fraction of all point
+    pairs closer together than `epsilon` -- over a range of `epsilon`, and
+    estimates ``D2`` as the slope of ``log(C(epsilon))`` vs. ``log(epsilon)``
+    (via ordinary least squares). ``D2`` is generally a slightly tighter
+    (never larger) estimate of an attractor's fractal dimension than the
+    box-counting ``D0``, and converges faster with the number of sample
+    points since it uses pairwise distances directly rather than a fixed grid.
+
+    Parameters
+    ----------
+    points : array_like of float, shape (n, dim)
+        Point cloud to measure (e.g. a sampled attractor trajectory). Keep
+        `points` to at most a few thousand rows: this computes all
+        :math:`O(n^2)` pairwise distances.
+    n_scales : int, default 20
+        Number of `epsilon` values to evaluate, log-spaced between `eps_min`
+        and `eps_max`.
+    eps_min : float, optional
+        Smallest neighborhood radius; defaults to the 5th percentile of the
+        pairwise distances. The very smallest pairwise distances are
+        dominated by finite-sample discreteness rather than the attractor's
+        true fractal scaling, so a percentile well above the minimum gives a
+        more reliable default than the minimum itself.
+    eps_max : float, optional
+        Largest neighborhood radius; defaults to the 50th percentile (median)
+        of the pairwise distances. The largest distances are dominated by
+        ``C(epsilon)`` saturating toward 1 (once `epsilon` exceeds the
+        attractor's overall diameter), which likewise biases a naive default.
+
+    Returns
+    -------
+    D2 : float
+        Estimated correlation dimension.
+    epsilons : ndarray of float, shape (n_scales,)
+        The neighborhood radii evaluated.
+    correlation_sums : ndarray of float, shape (n_scales,)
+        The correlation sum ``C(epsilon)`` at each radius.
+    """
+    points = np.atleast_2d(np.asarray(points, dtype=np.float64))
+    pair_dists = pdist(points)
+
+    if eps_max is None:
+        eps_max = float(np.percentile(pair_dists, 50))
+    if eps_min is None:
+        eps_min = float(np.percentile(pair_dists[pair_dists > 0], 5))
+
+    epsilons = np.geomspace(eps_max, eps_min, n_scales)
+    n_pairs = pair_dists.shape[0]
+    correlation_sums = np.array([np.count_nonzero(pair_dists < eps) / n_pairs for eps in epsilons])
+
+    mask = correlation_sums > 0
+    slope, _ = np.polyfit(np.log(epsilons[mask]), np.log(correlation_sums[mask]), 1)
+    return float(slope), epsilons, correlation_sums

physicskit/chaos/utils/io.py

@@ -0,0 +1,95 @@
+"""Save and load system configurations and array results (trajectories,
+basin grids, Poincare sections, ...) to disk.
+
+A system's configuration is recovered generically from its ``__init__``
+signature (see :func:`physicskit.chaos.core.base_system.get_init_params`), the same
+introspection that already powers every system's ``__repr__`` -- so
+:func:`save_system_config` / :func:`load_system_config` work for any
+concrete system in physicskit.chaos without a per-class serializer. Array results
+are saved as plain ``.npz`` archives via :func:`save_arrays` /
+:func:`load_arrays`.
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from physicskit.chaos.core.base_system import get_init_params
+
+
+def save_system_config(obj: object, path: str | Path) -> None:
+    """Save a system's class and constructor parameters as JSON.
+
+    Parameters
+    ----------
+    obj : object
+        A physicskit.chaos system instance (or any object whose ``__init__``
+        parameters are stored under same-named attributes).
+    path : str or pathlib.Path
+        Destination ``.json`` file.
+    """
+    params = {name: value.tolist() if isinstance(value, np.ndarray) else value for name, value in get_init_params(obj).items()}
+    config = {
+        "module": type(obj).__module__,
+        "class": type(obj).__qualname__,
+        "params": params,
+    }
+    Path(path).write_text(json.dumps(config, indent=2))
+
+
+def load_system_config(path: str | Path) -> Any:
+    """Reconstruct a system instance saved by :func:`save_system_config`.
+
+    Parameters
+    ----------
+    path : str or pathlib.Path
+        Source ``.json`` file.
+
+    Returns
+    -------
+    object
+        A new instance of the saved class, constructed from its saved
+        parameters.
+    """
+    config = json.loads(Path(path).read_text())
+    module = importlib.import_module(config["module"])
+    cls = getattr(module, config["class"])
+    return cls(**config["params"])
+
+
+def save_arrays(path: str | Path, **arrays: NDArray[Any]) -> None:
+    """Save named arrays (trajectories, grids, Poincare sections, ...) to a ``.npz`` archive.
+
+    Parameters
+    ----------
+    path : str or pathlib.Path
+        Destination ``.npz`` file.
+    **arrays
+        Arrays to save, keyed by name (e.g. ``save_arrays("run.npz", t=t,
+        states=states)``).
+    """
+    np.savez(path, **arrays)  # type: ignore[arg-type]  # numpy stubs mistype **kwds here
+
+
+def load_arrays(path: str | Path) -> dict[str, NDArray[Any]]:
+    """Load a ``.npz`` archive saved by :func:`save_arrays`.
+
+    Parameters
+    ----------
+    path : str or pathlib.Path
+        Source ``.npz`` file.
+
+    Returns
+    -------
+    dict
+        Mapping of array name to array, matching the keyword arguments
+        `save_arrays` was called with.
+    """
+    with np.load(path) as data:
+        return {key: data[key] for key in data.files}