tsdynamics 3.0.2__tar.gz → 3.0.4__tar.gz

{tsdynamics-3.0.2 → tsdynamics-3.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tsdynamics
-Version: 3.0.2
+Version: 3.0.4
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent

{tsdynamics-3.0.2 → tsdynamics-3.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "tsdynamics"
-version = "3.0.2"
+version = "3.0.4"
 description = "Zero-warmup Rust-engine ODE/DDE/SDE integration, discrete maps, and chaos analysis for dynamical systems."
 readme = "README.md"
 requires-python = ">=3.12,<4.0"
@@ -62,6 +62,7 @@ lz = ["lzcomplexity>=0.9"]
 dev = [
   "pytest>=8.0",
   "pytest-cov>=5.0",
+  "pytest-xdist>=3.6",
   "ruff>=0.6",
   "mypy>=1.10",
   "pre-commit>=3.8",

{tsdynamics-3.0.2 → tsdynamics-3.0.4}/src/tsdynamics/__init__.py

@@ -124,7 +124,7 @@ from .families import (
 )
 
 # Single source of truth for the package version; rewritten by python-semantic-release.
-__version__ = "3.0.2"
+__version__ = "3.0.4"
 
 # Built-in system classes are NOT bound into this namespace — that would bury the
 # submodules (``analysis``, ``data``, ``systems``, …) under ~149 model names in

{tsdynamics-3.0.2 → tsdynamics-3.0.4}/src/tsdynamics/analysis/orbits/orbit_diagram.py

@@ -164,6 +164,47 @@ def _count_branches(col: np.ndarray, rtol: float) -> int:
     return 1 + int(np.count_nonzero(np.diff(s) > rtol * span))
 
 
+def _record_via_iterate(
+    current: Any, start: Any, transient: int, n: int, idx: list[int]
+) -> tuple[np.ndarray, np.ndarray]:
+    """Record one parameter value on the Rust engine, in a single ``iterate`` call.
+
+    Resolve the initial condition explicitly and iterate ``transient + n`` steps
+    in one FFI round-trip, then slice off the transient.  ``max_retries=1`` with an
+    explicit ``ic`` makes a divergent value raise ``RuntimeError`` (no random-IC
+    retry) — the caller turns that into an empty record set, exactly as the
+    per-step path does.  Returns the recorded points and the final state (the
+    carry-over initial condition for the next value).
+    """
+    ic_resolved = current.resolve_ic(start)
+    traj = current.iterate(steps=transient + n, ic=ic_resolved, max_retries=1)
+    y = traj.y
+    rec = np.asarray(y[transient : transient + n][:, idx], dtype=float)
+    # A zero-length run (``transient + n == 0``) yields no rows; the carry-over
+    # final state is then just the resolved initial condition — matching the old
+    # step-loop's ``current.state()`` after taking no steps.
+    last = y[-1].copy() if y.shape[0] else np.asarray(ic_resolved, dtype=float).reshape(current.dim)
+    return rec, last
+
+
+def _record_via_step(
+    current: Any, start: Any, transient: int, n: int, idx: list[int]
+) -> tuple[np.ndarray, np.ndarray]:
+    """Record one parameter value via the per-step protocol path (a ``step()`` loop).
+
+    The fallback for flow wrappers (``PoincareMap`` / ``StroboscopicMap``), maps
+    whose ``_step`` will not lower to the engine IR, and wheel-free environments.
+    Returns the recorded points and the final state.
+    """
+    current.reinit(start)
+    for _ in range(transient):
+        current.step()
+    rec = np.empty((n, len(idx)))
+    for i in range(n):
+        rec[i] = current.step()[idx]
+    return rec, current.state()
+
+
 def orbit_diagram(
     sys: Any,
     param: str,
@@ -241,21 +282,44 @@ def orbit_diagram(
 
     import warnings
 
+    from tsdynamics.engine.compile import TapeCompileError
+    from tsdynamics.engine.run import EngineNotAvailableError
+    from tsdynamics.families import DiscreteMap
+
     values_arr = np.asarray(list(values), dtype=float)
     points: list[np.ndarray] = []
     state: np.ndarray | None = None
 
+    # A genuine DiscreteMap iterates on the Rust engine: the whole transient +
+    # record run for one parameter value becomes a single engine call (one FFI
+    # round-trip) rather than ``transient + n`` Python ``step()`` calls — the
+    # per-value bottleneck this stream removes (Logistic 600×120: ~9× faster).
+    # Flow wrappers (PoincareMap / StroboscopicMap) have no ``iterate`` and keep
+    # the per-step protocol path; a map whose ``_step`` will not lower to the IR,
+    # or a wheel-free environment with no compiled engine, falls back to it too
+    # (the decision is taken once and latched for the rest of the sweep).  Both
+    # paths iterate the *same* lowered ``_step``, so a periodic window converges to
+    # the identical cycle and — where the engine and NumPy agree bit-for-bit (e.g.
+    # the logistic map) — the whole diagram is byte-identical; a chaotic window
+    # records the same attractor (the engine ``iterate`` being the canonical map
+    # runner).
+    use_engine = isinstance(sys, DiscreteMap)
+
     for v in values_arr:
         current = sys.with_params(**{param: v})
         start = state if (carry_state and state is not None) else ic
         try:
-            current.reinit(start)
-            for _ in range(transient):
-                current.step()
-            rec = np.empty((n, len(idx)))
-            for i in range(n):
-                u = current.step()
-                rec[i] = u[idx]
+            if use_engine:
+                try:
+                    rec, last = _record_via_iterate(current, start, transient, n, idx)
+                except (TapeCompileError, EngineNotAvailableError):
+                    # This map cannot run on the engine (a non-lowerable step, or
+                    # no compiled wheel): fall back to the protocol path for this
+                    # value and the rest of the sweep.
+                    use_engine = False
+                    rec, last = _record_via_step(current, start, transient, n, idx)
+            else:
+                rec, last = _record_via_step(current, start, transient, n, idx)
         except RuntimeError as exc:
             # One divergent value must not discard the whole sweep: record an
             # empty point set and restart the next value from `ic`.
@@ -270,7 +334,7 @@ def orbit_diagram(
             continue
         points.append(rec)
         if carry_state:
-            state = current.state()
+            state = last
 
     meta = {
         "system": type(sys).__name__,

{tsdynamics-3.0.2 → tsdynamics-3.0.4}/src/tsdynamics/engine/run.py

@@ -526,7 +526,15 @@ def _run_continuous(
 
     eng = _engine()
     y = _engine_integrate_dense(
-        eng, problem, t_eval, method=method, rtol=rtol, atol=atol, jit=(backend == "jit")
+        eng,
+        _primary_tape(problem).to_arrays(),
+        problem.ic,
+        problem.params_vec(),
+        t_eval,
+        method=method,
+        rtol=rtol,
+        atol=atol,
+        jit=(backend == "jit"),
     )
     y = np.asarray(y, dtype=np.float64)
     if not np.all(np.isfinite(y)):
@@ -537,6 +545,74 @@ def _run_continuous(
     return y
 
 
+def _step_continuous(
+    tape_arrays: tuple,
+    ic: np.ndarray,
+    params_vec: np.ndarray,
+    t_eval: np.ndarray,
+    *,
+    method: str,
+    rtol: float,
+    atol: float,
+    jit: bool,
+    name: str,
+) -> np.ndarray:
+    """Integrate one dense ODE span from pre-marshalled tape arrays — the per-step seam.
+
+    The lean inner core of
+    :meth:`~tsdynamics.families.continuous.ContinuousSystem.step`: it performs
+    exactly the engine call and finiteness guard :func:`_run_continuous` does for an
+    ODE on the compiled engine, but takes the already-marshalled tape wire arrays
+    (cached once at ``reinit`` — they are loop-invariant) plus the live parameter
+    vector, skipping the per-call tape re-marshalling, ``Problem`` construction and
+    output-grid build that the full :func:`integrate` entry point pays.  It is
+    therefore **answer-identical** to :func:`_run_continuous` over the same inputs
+    (stream WS-INVHOIST); it serves only the constant-/small-``dt`` stepping loops
+    (Poincaré refinement, basins over flows, the streaming protocol), never a
+    user-facing :class:`~tsdynamics.families.Trajectory` (which keeps its
+    provenance via :func:`integrate`).
+
+    Parameters
+    ----------
+    tape_arrays : tuple
+        The RHS tape's engine wire arrays (:meth:`Tape.to_arrays`), marshalled once
+        by the caller and reused across the loop.
+    ic : ndarray, shape (dim,)
+        The state to start this span from.
+    params_vec : ndarray
+        Live control-parameter values, read per step so a mid-loop parameter change
+        still takes effect — identical to the pre-hoist path.
+    t_eval : ndarray
+        The (two-node) output grid for this span.
+    method, rtol, atol, jit : str, float, float, bool
+        Solver configuration, resolved once by ``reinit``.
+    name : str
+        System name, for the divergence error message.
+
+    Returns
+    -------
+    ndarray, shape (len(t_eval), dim)
+
+    Raises
+    ------
+    RuntimeError
+        If the integration diverged or the step collapsed (non-finite output) —
+        the same loud-divergence contract as :func:`_run_continuous`.
+    """
+    eng = _engine()
+    y = np.asarray(
+        _engine_integrate_dense(
+            eng, tape_arrays, ic, params_vec, t_eval, method=method, rtol=rtol, atol=atol, jit=jit
+        ),
+        dtype=np.float64,
+    )
+    if not np.isfinite(y).all():
+        raise RuntimeError(
+            f"{name}: integration diverged or the step collapsed before reaching the final time."
+        )
+    return y
+
+
 def _run_dde(
     problem: DDEProblem,
     t_eval: np.ndarray,
@@ -917,7 +993,9 @@ def sde_ensemble_final(
 
 def _engine_integrate_dense(
     eng: Any,
-    problem: Problem,
+    tape_arrays: tuple,
+    ic: np.ndarray,
+    params_vec: np.ndarray,
     t_eval: np.ndarray,
     *,
     method: str,
@@ -925,11 +1003,19 @@ def _engine_integrate_dense(
     atol: float,
     jit: bool,
 ) -> np.ndarray:
-    """Dispatch a dense single-trajectory integration to the engine."""
+    """Dispatch a dense single-trajectory integration to the engine.
+
+    ``tape_arrays`` is the RHS tape's wire tuple (:meth:`Tape.to_arrays` — the
+    drift tape for an SDE).  Taking the marshalled arrays as an argument rather than
+    deriving them here lets a hot stepping loop pass arrays it marshalled once
+    (:func:`_step_continuous`) instead of rebuilding the tuple per step (stream
+    WS-INVHOIST), while the single-shot :func:`integrate` path marshals them inline
+    at the call site.
+    """
     return eng.integrate_dense(
-        *_primary_tape(problem).to_arrays(),
-        np.ascontiguousarray(problem.ic, dtype=np.float64),
-        problem.params_vec(),
+        *tape_arrays,
+        np.ascontiguousarray(ic, dtype=np.float64),
+        params_vec,
         np.ascontiguousarray(t_eval, dtype=np.float64),
         method,
         float(rtol),

{tsdynamics-3.0.2 → tsdynamics-3.0.4}/src/tsdynamics/families/continuous.py

@@ -165,8 +165,11 @@ class ContinuousSystem(SystemBase, ABC):
     # Per-step integration context cached by ``reinit`` so a repeated constant-``dt``
     # stepping loop pays the fixed per-call overhead (solver-registry resolve,
     # Jacobian decision, output-grid build, provenance, Trajectory wrap) once at
-    # reinit instead of on every ``step`` (stream WS-STEPBUF).
+    # reinit instead of on every ``step`` (stream WS-STEPBUF).  ``_step_tape_arrays``
+    # caches the engine wire arrays of the (loop-invariant) tape so the per-``dt``
+    # loop reuses them rather than re-marshalling the tuple each call (WS-INVHOIST).
     _step_method_canonical: str | None = None
+    _step_tape_arrays: Any = None
 
     # ------------------------------------------------------------------ #
     # Subclass interface
@@ -304,7 +307,16 @@ class ContinuousSystem(SystemBase, ABC):
         # Cache the canonical kernel name (``"RK45"`` → ``"rk45"``) so the per-step
         # loop hits the engine core directly without re-resolving every call.
         self._step_method_canonical = resolution.name
-        self._engine_problem = ode_problem(self, ic=ic_arr, t0=t0, **resolution.build_kwargs)
+        prob = ode_problem(self, ic=ic_arr, t0=t0, **resolution.build_kwargs)
+        # Marshal the (loop-invariant) tape to its engine wire arrays once here so the
+        # per-``dt`` ``step`` loop reuses them instead of rebuilding the tuple on every
+        # call (stream WS-INVHOIST).  Re-derived on each ``reinit`` (a sweep reinits
+        # per parameter value), so a re-lowered tape is always picked up.  Marshal before
+        # publishing the problem so a (theoretical) marshalling failure can't leave a new
+        # ``_engine_problem`` paired with a stale ``_step_tape_arrays``.
+        step_arrays = prob.tape.to_arrays()
+        self._engine_problem = prob
+        self._step_tape_arrays = step_arrays
         self._step_rtol = float(rtol)
         self._step_atol = float(atol)
         self._state_now = ic_arr.copy()
@@ -323,14 +335,18 @@ class ContinuousSystem(SystemBase, ABC):
         Each call integrates **exactly one** ``dt`` from the live ``(state, t)``,
         returning byte-for-byte the trajectory the released per-``dt`` path
         produced — there is no batching, so the numbers are unchanged for every
-        method, adaptive or fixed-step (stream WS-STEPBUF).  The speedup comes
-        only from skipping fixed per-call overhead: ``step`` reuses the tape and
-        canonical kernel name cached by :meth:`reinit` and calls the engine's lean
-        dense-output core (:func:`~tsdynamics.engine.run._run_continuous`)
-        directly, so a constant-``dt`` stepping loop (Poincaré refinement, basins
+        method, adaptive or fixed-step (streams WS-STEPBUF, WS-INVHOIST).  The
+        speedup comes only from hoisting fixed per-call overhead out of the loop:
+        ``step`` reuses the tape, its canonical kernel name and its marshalled
+        engine wire arrays — all cached by :meth:`reinit` — and calls the engine's
+        lean dense-output core (:func:`~tsdynamics.engine.run._step_continuous`)
+        directly.  So a constant-``dt`` stepping loop (Poincaré refinement, basins
         over flows) skips the solver-registry resolve, the implicit-Jacobian
-        decision, provenance assembly and the :class:`Trajectory` wrap that the
-        full :meth:`integrate` entry point pays on every call.
+        decision, the tape re-marshalling, the output-grid ``arange``/append,
+        provenance assembly and the :class:`Trajectory` wrap that the full
+        :meth:`integrate` entry point pays on every call.  The control-parameter
+        vector is still read live each step, so the live-stepper semantics are
+        unchanged.
 
         A batch-ahead variant that integrated a whole chunk in one engine call was
         rejected: a chunked adaptive integration is *not* equal to N single-``dt``
@@ -339,31 +355,50 @@ class ContinuousSystem(SystemBase, ABC):
         ``max_lyapunov``.  The durable amortisation is the resumable engine stepper
         (WS-STEPPER), which advances without re-seeding and stays answer-exact.
         """
-        from tsdynamics.engine.problem import ODEProblem
-        from tsdynamics.engine.run import _run_continuous
-        from tsdynamics.utils.grids import make_output_grid
+        from tsdynamics.engine.run import _step_continuous
 
         if self._engine_problem is None:
             self.reinit()
         dt = float(n_or_dt) if n_or_dt is not None else self._default_step_dt
 
         t0 = self._t_now
-        # The same two-node output grid the full ``integrate`` would build for a
-        # single ``dt`` span — so ``step`` is bit-identical to a per-``dt``
-        # ``integrate`` from the live state.
-        t_eval = make_output_grid(t0, t0 + dt, dt)
-        prob = ODEProblem(tape=self._engine_problem.tape, ic=self._state_now, t0=t0, system=self)
-        y = _run_continuous(
-            prob,
+        tf = t0 + dt
+        # The two-node grid ``make_output_grid(t0, tf, dt)`` builds for a single ``dt``
+        # span, assembled directly to skip its ``arange``/append (WS-INVHOIST).  When the
+        # span clears ``1e-9`` the helper is byte-for-byte exactly ``[t0, tf]``: that sits
+        # a thousandfold above its ``1e-12`` append tolerance (``t_arr[-1] < tf - 1e-12``)
+        # and above the float-subtraction rounding even at large ``t0``, and a single
+        # ``dt`` span never yields more than two nodes — so the shortcut is identical
+        # there (the regime of every real step; verified bit-for-bit over a wide
+        # ``t0``/``dt`` fuzz).  The rare remainder — a sub-``1e-9`` step (whose helper grid
+        # may degenerate to a single un-advanced node) or a non-forward / non-positive
+        # ``dt`` (which must raise the canonical
+        # :class:`~tsdynamics.errors.InvalidParameterError`) — defers to the helper so
+        # ``step`` stays byte-identical to the pre-hoist path for *every* input.
+        if tf - t0 > 1e-9:
+            t_eval = np.array([t0, tf], dtype=np.float64)
+        else:
+            from tsdynamics.utils.grids import make_output_grid
+
+            t_eval = make_output_grid(t0, tf, dt)
+        y = _step_continuous(
+            self._step_tape_arrays,
+            self._state_now,
+            self._engine_problem.params_vec(),
             t_eval,
             method=self._step_method_canonical,
             rtol=self._step_rtol,
             atol=self._step_atol,
-            backend=self._step_backend,
+            jit=self._step_backend == "jit",
+            name=type(self).__name__,
         )
         state = np.asarray(y[-1], dtype=float)
-        self._t_now = t0 + dt
-        self._state_now = state.copy()
+        # The state/time advance writes private framework attributes that always pass
+        # straight through ``SystemBase.__setattr__`` (underscore-prefixed) — go direct
+        # to ``object.__setattr__`` so the hot loop skips the param-typo guard's
+        # ``params`` membership check on every step (WS-INVHOIST).
+        object.__setattr__(self, "_t_now", tf)
+        object.__setattr__(self, "_state_now", state.copy())
         return state.copy()
 
     def state(self) -> np.ndarray: