tsdynamics 2.1.1__tar.gz → 2.2.0__tar.gz

{tsdynamics-2.1.1 → tsdynamics-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tsdynamics
-Version: 2.1.1
+Version: 2.2.0
 Summary: Compiled ODE/DDE integration, discrete maps, and chaos analysis for dynamical systems.
 Project-URL: Source, https://github.com/El3ssar/TSDynamics
 Project-URL: Documentation, https://el3ssar.github.io/TSDynamics/

{tsdynamics-2.1.1 → tsdynamics-2.2.0}/src/tsdynamics/__init__.py

@@ -48,7 +48,7 @@ from .systems import continuous as _continuous
 from .systems import discrete as _discrete
 
 # Single source of truth for the package version; rewritten by python-semantic-release.
-__version__ = "2.1.1"
+__version__ = "2.2.0"
 
 # Re-export every system class at the top level so ``from tsdynamics import Lorenz``
 # works without users having to remember which submodule a system lives in.

{tsdynamics-2.1.1 → tsdynamics-2.2.0}/src/tsdynamics/base/ode_base.py

@@ -718,11 +718,14 @@ class ContinuousSystem(SystemBase, ABC):
             ``tsit45`` / ``bdf`` / ``tr_bdf2`` / ``esdirk34``.
         rtol, atol : float
             Solver tolerances (default 1e-6 / 1e-9).
-        backend : {"jitcode", "diffsol"}
-            ``"jitcode"`` (default) compiles via C; ``"diffsol"`` is the
-            experimental Rust solver suite
-            (``pip install tsdynamics[diffsol]``,
-            see :mod:`tsdynamics.backends.diffsol`).
+        backend : {"jitcode", "diffsol", "auto"}
+            ``"jitcode"`` (default) compiles the RHS to C; ``"diffsol"`` uses
+            the Rust solver suite via LLVM JIT — no C compiler, prebuilt
+            wheels (``pip install tsdynamics[diffsol]``), ~10× faster on small
+            chaotic systems, and validated against JiTCODE across the whole
+            ODE catalogue (see :mod:`tsdynamics.backends.diffsol`).  ``"auto"``
+            picks ``"diffsol"`` when it is installed, else ``"jitcode"`` —
+            the recommended zero-compiler fast path.
         **integrator_kwargs
             Forwarded to ``jitcode.set_integrator`` (e.g. ``max_step``).
 
@@ -731,6 +734,15 @@ class ContinuousSystem(SystemBase, ABC):
         Trajectory
             Supports tuple-unpacking: ``t, y = sys.integrate(...)``.
         """
+        if backend == "auto":
+            # Prefer the zero-compiler Rust path when its optional dependency
+            # is installed; otherwise fall back to the always-available
+            # JiTCODE path. Lets `tsdynamics[diffsol]` users get the fast
+            # backend without naming it, with no surprise for everyone else.
+            from tsdynamics.backends import diffsol as _diffsol
+
+            backend = "diffsol" if _diffsol.available() else "jitcode"
+
         if backend == "diffsol":
             from tsdynamics.backends import diffsol as _diffsol
 
@@ -754,7 +766,7 @@ class ContinuousSystem(SystemBase, ABC):
                 ),
             )
         if backend != "jitcode":
-            raise ValueError(f"Unknown backend {backend!r}; use 'jitcode' or 'diffsol'.")
+            raise ValueError(f"Unknown backend {backend!r}; use 'jitcode', 'diffsol', or 'auto'.")
 
         method = method or self._default_method
         integ_name = _INTEGRATOR_MAP.get(method, method)

tsdynamics-2.2.0/tests/test_diffsol_backend.py

@@ -0,0 +1,169 @@
+"""
+Cross-validation of the experimental diffsol backend against JiTCODE.
+
+Skipped entirely when the ``tsdynamics[diffsol]`` extra is not installed.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+pytest.importorskip("pydiffsol")
+
+import tsdynamics as ts
+from tsdynamics.backends import diffsol as dsl
+
+# ---------------------------------------------------------------------------
+# Translator (fast)
+# ---------------------------------------------------------------------------
+
+
+def test_to_diffsl_lorenz_structure() -> None:
+    code, control = dsl.to_diffsl(ts.Lorenz())
+    assert control == ["sigma", "rho", "beta"]
+    assert "in_i {" in code and "u_i {" in code and "F_i {" in code
+    assert "ic0" in code and "ic2" in code
+
+
+def test_unknown_backend_rejected() -> None:
+    with pytest.raises(ValueError, match="Unknown backend"):
+        ts.Lorenz().integrate(final_time=1.0, dt=0.1, backend="quantum")
+
+
+def test_auto_backend_uses_diffsol_when_available() -> None:
+    """With pydiffsol installed, backend='auto' routes to diffsol."""
+    traj = ts.Lorenz().integrate(final_time=1.0, dt=0.1, ic=[1.0, 1.0, 1.0], backend="auto")
+    assert traj.meta["backend"] == "diffsol"
+
+
+# ---------------------------------------------------------------------------
+# Solving + cross-validation (no C compiler needed — pure LLVM JIT)
+# ---------------------------------------------------------------------------
+
+
+def test_lorenz_diffsol_short_integration() -> None:
+    traj = ts.Lorenz().integrate(
+        final_time=2.0, dt=0.01, ic=[1.0, 1.0, 1.0], backend="diffsol", rtol=1e-9, atol=1e-11
+    )
+    assert traj.y.shape == (201, 3)  # grid includes the endpoint
+    assert np.all(np.isfinite(traj.y))
+    assert traj.meta["backend"] == "diffsol"
+
+
+def test_param_change_reuses_compiled_module() -> None:
+    a = ts.Lorenz().integrate(final_time=1.0, dt=0.1, ic=[1.0, 1.0, 1.0], backend="diffsol")
+    before = dict(dsl._ODE_CACHE)
+    b = ts.Lorenz(params={"rho": 35.0}).integrate(
+        final_time=1.0, dt=0.1, ic=[1.0, 1.0, 1.0], backend="diffsol"
+    )
+    assert dict(dsl._ODE_CACHE) == before  # no recompilation
+    assert not np.allclose(a.y[-1], b.y[-1])  # but different dynamics
+
+
+@pytest.mark.slow
+@pytest.mark.parametrize("name,ic", [("Lorenz", [1.0, 1.0, 1.0]), ("Rossler", [1.0, 0.0, 0.0])])
+def test_cross_validation_against_jitcode(name: str, ic: list) -> None:
+    """Both backends must agree to tight tolerance over a short window."""
+    sys_a = getattr(ts, name)()
+    sys_b = getattr(ts, name)()
+    kw = dict(final_time=5.0, dt=0.01, ic=ic, rtol=1e-10, atol=1e-12)
+    ref = sys_a.integrate(method="dop853", **kw)
+    alt = sys_b.integrate(backend="diffsol", **kw)
+    np.testing.assert_allclose(alt.y, ref.y, rtol=1e-5, atol=1e-6)
+
+
+@pytest.mark.slow
+def test_cross_validation_over_sample() -> None:
+    """
+    diffsol (BDF) reproduces JiTCODE (dop853) across the curated ODE sample.
+
+    Short horizon + tight tolerances keep chaotic sensitivity from masking a
+    real translator/solver discrepancy; max abs deviation must stay < 1e-3.
+    """
+    import sys
+    from pathlib import Path
+
+    sys.path.insert(0, str(Path(__file__).parent))
+    from _sampling import INTEGRATION_SAMPLE
+
+    from tsdynamics import registry
+
+    bad = []
+    for name in INTEGRATION_SAMPLE:
+        cls = registry.get(name).cls
+        ic = cls().resolve_ic(None)
+        yj = (
+            cls()
+            .integrate(ic=ic, final_time=1.5, dt=0.03, method="dop853", rtol=1e-10, atol=1e-12)
+            .y
+        )
+        yd = (
+            cls()
+            .integrate(
+                ic=ic,
+                final_time=1.5,
+                dt=0.03,
+                backend="diffsol",
+                method="LSODA",
+                rtol=1e-10,
+                atol=1e-12,
+            )
+            .y
+        )
+        n = min(len(yj), len(yd))
+        dev = float(np.max(np.abs(yj[:n] - yd[:n])))
+        if dev >= 1e-3:
+            bad.append((name, dev))
+    assert not bad, f"diffsol disagrees with jitcode on: {bad}"
+
+
+@pytest.mark.slow
+def test_stiff_solver_path() -> None:
+    """The BDF mapping handles a stiff-ish problem."""
+    traj = ts.Lorenz().integrate(
+        final_time=2.0, dt=0.01, ic=[1.0, 1.0, 1.0], backend="diffsol", method="LSODA"
+    )
+    assert np.all(np.isfinite(traj.y))
+
+
+@pytest.mark.full
+def test_cross_validation_full_catalogue() -> None:
+    """
+    The gate for flipping the default backend to diffsol: *every* built-in ODE
+    must integrate on diffsol (BDF) and agree with JiTCODE (dop853) to <1e-3
+    over a short window.  Runs nightly (``-m full``) with the diffsol extra.
+    """
+    from tsdynamics import registry
+
+    bad = []
+    for e in registry.all_systems(family="ode"):
+        cls = e.cls
+        try:
+            ic = cls().resolve_ic(None)
+            yj = (
+                cls()
+                .integrate(ic=ic, final_time=1.0, dt=0.02, method="dop853", rtol=1e-10, atol=1e-12)
+                .y
+            )
+            yd = (
+                cls()
+                .integrate(
+                    ic=ic,
+                    final_time=1.0,
+                    dt=0.02,
+                    backend="diffsol",
+                    method="LSODA",
+                    rtol=1e-10,
+                    atol=1e-12,
+                )
+                .y
+            )
+        except Exception as exc:  # noqa: BLE001 — record which system & why
+            bad.append((e.name, f"error: {str(exc).splitlines()[-1][:50]}"))
+            continue
+        n = min(len(yj), len(yd))
+        dev = float(np.max(np.abs(yj[:n] - yd[:n])))
+        if dev >= 1e-3:
+            bad.append((e.name, round(dev, 5)))
+    assert not bad, f"{len(bad)}/118 ODEs disagree or error on diffsol: {bad}"

tsdynamics-2.2.0/tests/test_diffsol_translation.py

@@ -0,0 +1,42 @@
+"""
+Diffsol *translator* coverage — runs without the pydiffsol extra.
+
+``to_diffsl`` only needs SymEngine + the jitcode symbols, so this guards the
+SymEngine→DiffSL translation for the whole ODE catalogue on every CI run,
+independently of whether the Rust solver itself is installed.  The numeric
+cross-validation against JiTCODE lives in ``test_diffsol_backend.py`` (which
+needs pydiffsol and is therefore skipped when the extra is absent).
+"""
+
+from __future__ import annotations
+
+from tsdynamics import registry
+from tsdynamics.backends.diffsol import DiffSLTranslationError, to_diffsl
+
+
+def test_every_ode_translates_to_diffsl(ode_entry) -> None:
+    """Every built-in ODE must translate to a well-formed DiffSL module."""
+    try:
+        code, control_names = to_diffsl(ode_entry.cls())
+    except DiffSLTranslationError as exc:
+        # A genuine "DiffSL can't express this" is allowed but must be visible:
+        # fail loudly so the coverage number can't silently regress unnoticed.
+        raise AssertionError(f"{ode_entry.name}: no longer translates to DiffSL — {exc}") from exc
+    assert "in_i {" in code and "u_i {" in code and "F_i {" in code
+    # control inputs = the non-structural params (structural ones, e.g.
+    # Lorenz96's N, are baked into the generated module, not solve-time inputs).
+    cls = ode_entry.cls
+    structural = getattr(cls, "_structural_params", frozenset())
+    expected = [k for k in cls().params if k not in structural]
+    assert list(control_names) == expected
+
+
+def test_translation_coverage_is_total() -> None:
+    """The whole ODE catalogue translates — the headline Phase-2 coverage fact."""
+    failed = []
+    for e in registry.all_systems(family="ode"):
+        try:
+            to_diffsl(e.cls())
+        except Exception as exc:  # noqa: BLE001 — record, don't abort
+            failed.append((e.name, str(exc).splitlines()[0][:60]))
+    assert not failed, f"{len(failed)} ODE systems no longer translate: {failed}"

tsdynamics-2.1.1/tests/test_diffsol_backend.py

@@ -1,76 +0,0 @@
-"""
-Cross-validation of the experimental diffsol backend against JiTCODE.
-
-Skipped entirely when the ``tsdynamics[diffsol]`` extra is not installed.
-"""
-
-from __future__ import annotations
-
-import numpy as np
-import pytest
-
-pytest.importorskip("pydiffsol")
-
-import tsdynamics as ts
-from tsdynamics.backends import diffsol as dsl
-
-# ---------------------------------------------------------------------------
-# Translator (fast)
-# ---------------------------------------------------------------------------
-
-
-def test_to_diffsl_lorenz_structure() -> None:
-    code, control = dsl.to_diffsl(ts.Lorenz())
-    assert control == ["sigma", "rho", "beta"]
-    assert "in_i {" in code and "u_i {" in code and "F_i {" in code
-    assert "ic0" in code and "ic2" in code
-
-
-def test_unknown_backend_rejected() -> None:
-    with pytest.raises(ValueError, match="Unknown backend"):
-        ts.Lorenz().integrate(final_time=1.0, dt=0.1, backend="quantum")
-
-
-# ---------------------------------------------------------------------------
-# Solving + cross-validation (no C compiler needed — pure LLVM JIT)
-# ---------------------------------------------------------------------------
-
-
-def test_lorenz_diffsol_short_integration() -> None:
-    traj = ts.Lorenz().integrate(
-        final_time=2.0, dt=0.01, ic=[1.0, 1.0, 1.0], backend="diffsol", rtol=1e-9, atol=1e-11
-    )
-    assert traj.y.shape == (201, 3)  # grid includes the endpoint
-    assert np.all(np.isfinite(traj.y))
-    assert traj.meta["backend"] == "diffsol"
-
-
-def test_param_change_reuses_compiled_module() -> None:
-    a = ts.Lorenz().integrate(final_time=1.0, dt=0.1, ic=[1.0, 1.0, 1.0], backend="diffsol")
-    before = dict(dsl._ODE_CACHE)
-    b = ts.Lorenz(params={"rho": 35.0}).integrate(
-        final_time=1.0, dt=0.1, ic=[1.0, 1.0, 1.0], backend="diffsol"
-    )
-    assert dict(dsl._ODE_CACHE) == before  # no recompilation
-    assert not np.allclose(a.y[-1], b.y[-1])  # but different dynamics
-
-
-@pytest.mark.slow
-@pytest.mark.parametrize("name,ic", [("Lorenz", [1.0, 1.0, 1.0]), ("Rossler", [1.0, 0.0, 0.0])])
-def test_cross_validation_against_jitcode(name: str, ic: list) -> None:
-    """Both backends must agree to tight tolerance over a short window."""
-    sys_a = getattr(ts, name)()
-    sys_b = getattr(ts, name)()
-    kw = dict(final_time=5.0, dt=0.01, ic=ic, rtol=1e-10, atol=1e-12)
-    ref = sys_a.integrate(method="dop853", **kw)
-    alt = sys_b.integrate(backend="diffsol", **kw)
-    np.testing.assert_allclose(alt.y, ref.y, rtol=1e-5, atol=1e-6)
-
-
-@pytest.mark.slow
-def test_stiff_solver_path() -> None:
-    """The BDF mapping handles a stiff-ish problem."""
-    traj = ts.Lorenz().integrate(
-        final_time=2.0, dt=0.01, ic=[1.0, 1.0, 1.0], backend="diffsol", method="LSODA"
-    )
-    assert np.all(np.isfinite(traj.y))