tsdynamics 2.4.0__tar.gz → 2.4.1__tar.gz

{tsdynamics-2.4.0 → tsdynamics-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tsdynamics
-Version: 2.4.0
+Version: 2.4.1
 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.4.0 → tsdynamics-2.4.1}/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.4.0"
+__version__ = "2.4.1"
 
 # 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.4.0 → tsdynamics-2.4.1}/src/tsdynamics/base/ode_base.py

@@ -153,6 +153,14 @@ class ContinuousSystem(SystemBase, ABC):
 
     _default_method: ClassVar[str] = "RK45"
 
+    #: Whether JiTCODE should run SymEngine's ``simplify(ratio=1)`` on each RHS
+    #: expression before emitting C.  ``None`` keeps JiTCODE's own default
+    #: (enabled for ``dim <= 10``).  Set ``False`` on systems whose RHS is a
+    #: large rational expression: the simplify pass is super-linear and can
+    #: effectively hang at compile time, while the C compiler optimises the
+    #: unsimplified code just as well (see ``BlinkingRotlet``).
+    _compile_simplify: ClassVar[bool | None] = None
+
     #: Parameters whose values affect the symbolic *structure* of _equations
     #: (e.g. integer loop bounds). These are baked in at compile time.
     _structural_params: ClassVar[frozenset[str]] = frozenset()
@@ -390,7 +398,7 @@ class ContinuousSystem(SystemBase, ABC):
         ode = cls_jitc(
             f_sym, n=self.dim, control_pars=control_par_list, verbose=False, **lyap_kwargs
         )
-        ode.generate_f_C()
+        ode.generate_f_C(simplify=type(self)._compile_simplify)
         so = pathlib.Path(ode.save_compiled(destination=str(dest), overwrite=True))
 
         if for_lyap:

{tsdynamics-2.4.0 → tsdynamics-2.4.1}/src/tsdynamics/systems/continuous/climate_geophysics.py

@@ -75,6 +75,28 @@ class DoubleGyre(ContinuousSystem):
 
 
 class BlinkingRotlet(ContinuousSystem):
+    r"""Blinking-rotlet flow — a model of chaotic advection in Stokes mixing.
+
+    A passive tracer in a circular cell stirred by two off-centre rotlets at
+    radius ``+b`` and ``-b`` that alternate being active with period ``tau``,
+    the switch being a steep ``tanh`` ramp.  The periodic blinking folds and
+    stretches material lines, producing chaotic advection (Aref-type *blinking*
+    flow).  State is ``(r, theta, t)`` in polar coordinates with an explicit
+    clock; ``dtheta`` carries a ``1/r`` factor singular at the cell centre, so
+    ``default_ic`` sits on a bounded orbit away from ``r = 0``.
+
+    Compile note
+    ------------
+    The rotlet velocity field is a large rational expression.  JiTCODE's
+    default ``simplify(ratio=1)`` codegen pass is super-linear in expression
+    size and effectively hangs while *compiling* this RHS — which is what made
+    the system look un-integrable.  ``_compile_simplify = False`` skips that
+    pass (the C compiler optimises the unsimplified code), after which the flow
+    integrates in well under a millisecond at every tolerance, even at the
+    original steep ``tanh`` switch.
+    """
+
+    reference = "Meleshko & Aref (1996), Phys. Fluids 8, 3215-3217"
     params = {
         "a": 1.0,
         "b": 0.5298833894399929,
@@ -83,6 +105,15 @@ class BlinkingRotlet(ContinuousSystem):
         "tau": 3.0,
     }
     dim = 3
+    variables = ("r", "theta", "t")
+    #: On a bounded orbit (``r`` stays in ``[0.8, 0.91]``) away from the
+    #: ``r = 0`` angular singularity, so default sweeps stay bounded.
+    default_ic = [0.8, 4.887, 0.0]
+
+    # The rotlet RHS is a large rational expression; JiTCODE's default
+    # simplify(ratio=1) pass is super-linear on it and effectively hangs the
+    # compile.  Skip it — the C compiler optimises the unsimplified code.
+    _compile_simplify = False
 
     @staticmethod
     def _rotlet(r, theta, a, b, bc):

{tsdynamics-2.4.0 → tsdynamics-2.4.1}/src/tsdynamics/systems/continuous/physical_systems.py

@@ -140,13 +140,52 @@ class JerkCircuit(ContinuousSystem):
 
 
 class WindmiReduced(ContinuousSystem):
+    r"""Reduced WINDMI model of the solar-wind–magnetosphere–ionosphere coupling.
+
+    Three-variable reduction (field-aligned current ``i``, voltage ``v``,
+    pressure ``p``) of the WINDMI energy-conserving model.  The pressure-loss
+    term carries a fractional power ``p**(5/4)`` gated by a steep
+    ``tanh(d1*(i-1))`` switch (``d1 = 2200`` makes it a near-step at ``i = 1``,
+    the substorm-onset threshold).
+
+    Numerical guards (no change to the dynamics)
+    --------------------------------------------
+    Two robustness guards let every backend reproduce the same orbit that
+    JiTCODE's explicit dopri5 already handles:
+
+    * ``abs(p)`` under the fractional power.  On the attractor ``p >= 0``, but
+      adaptive and implicit solvers probe trial states with ``p < 0`` where the
+      real ``p**(5/4)`` is complex.  ``abs(p)`` is identical to ``p`` on the
+      physical trajectory and real, ``C^1`` everywhere.
+
+    * The ``tanh`` argument is clamped to ``[-_TANH_CLAMP, _TANH_CLAMP]``.
+      ``tanh`` saturates to ``±1`` to machine precision past ``|arg| ≈ 20``, so
+      clamping leaves the switch value unchanged, but it stops the diffsol Rust
+      kernels' automatic differentiation from overflowing on ``exp`` of an
+      enormous ``d1*(i-1)`` (≈ ±1500 on the orbit) — the actual cause of their
+      Newton/error-test failures.  The clamp uses ``abs`` only, which both the
+      JiTCODE and DiffSL paths support.
+    """
+
+    reference = "Horton, Weigel & Sprott (2001), Phys. Plasmas 8, 2946-2952"
     params = {"a1": 0.247, "b1": 10.8, "b2": 0.0752, "b3": 1.06, "d1": 2200, "vsw": 5}
     dim = 3
+    variables = ("i", "v", "p")
+
+    #: Bound on the ``tanh`` switch argument; ``tanh(±20)`` already equals ``±1``
+    #: to ~1e-18, so clamping is dynamically invisible but autodiff-safe.
+    _TANH_CLAMP = 25.0
 
     @staticmethod
     def _equations(Y, t, *, a1, b1, b2, b3, d1, vsw):
         i, v, p = Y(0), Y(1), Y(2)
+        # Clamp d1*(i-1) to [-C, C] via the abs identity
+        # clamp(z, -C, C) = (|z + C| - |z - C|) / 2 — smooth-enough (abs only)
+        # and translatable by both the JiTCODE and DiffSL backends.
+        c = WindmiReduced._TANH_CLAMP
+        z = d1 * (i - 1)
+        z_clamped = (abs(z + c) - abs(z - c)) / 2
         idot = a1 * (vsw - v)
         vdot = b1 * i - b2 * p**1 / 2 - b3 * v
-        pdot = vsw**2 - p ** (5 / 4) * vsw ** (1 / 2) * (1 + tanh(d1 * (i - 1))) / 2
+        pdot = vsw**2 - abs(p) ** (5 / 4) * vsw ** (1 / 2) * (1 + tanh(z_clamped)) / 2
         return idot, vdot, pdot

{tsdynamics-2.4.0 → tsdynamics-2.4.1}/tests/_sampling.py

@@ -56,25 +56,20 @@ INTEGRATION_SAMPLE: list[str] = [
 ]
 
 # --- ODE systems excluded from the exhaustive integration sweeps ------------
-# These cannot be integrated by adaptive solvers in bounded time, so they
-# would hang the nightly full sweep rather than fail it.
-HARD_TO_INTEGRATE: dict[str, str] = {
-    "BlinkingRotlet": (
-        "near-discontinuous blinking protocol (tanh of a steep sine) makes every "
-        "adaptive solver take vanishingly small steps and stall at any tolerance; "
-        "needs a dedicated integration recipe — tracked separately"
-    ),
-}
+# Systems that cannot be integrated by adaptive solvers in bounded time would
+# hang the nightly full sweep rather than fail it, so they are skipped here.
+# Currently empty: ``BlinkingRotlet`` (the former entry) only *looked*
+# un-integrable because JiTCODE's simplify(ratio=1) codegen pass hangs on its
+# large rational RHS — fixed with ``_compile_simplify = False`` on the class.
+HARD_TO_INTEGRATE: dict[str, str] = {}
 
 # Systems the diffsol backend specifically can't integrate (the default JiTCODE
 # backend handles them fine). Excluded from the diffsol full-catalogue sweep.
-DIFFSOL_SKIP: dict[str, str] = {
-    "WindmiReduced": (
-        "RHS has a near-discontinuous tanh(2200*(i-1)) switch and fractional "
-        "powers p**(5/4) that go complex when the solver probes p<0; diffsol's "
-        "Rust solvers fail to converge while JiTCODE's dopri5 tolerates it"
-    ),
-}
+# Currently empty: ``WindmiReduced`` (the former entry) now integrates on every
+# diffsol solver after guarding the fractional power with ``abs(p)`` and
+# clamping the steep ``tanh`` argument (autodiff-safe) — both no-ops on the
+# physical trajectory.
+DIFFSOL_SKIP: dict[str, str] = {}
 
 # --- Maps excluded from Lyapunov-spectrum shape tests -----------------------
 MAP_LYAPUNOV_EXCLUDE: dict[str, str] = {

{tsdynamics-2.4.0 → tsdynamics-2.4.1}/tests/test_diffsol_backend.py

@@ -135,10 +135,10 @@ def test_diffsol_integrates_full_catalogue() -> None:
     (``-m full``) with the diffsol extra.
 
     Numeric agreement with JiTCODE is checked separately on the curated sample
-    (``test_cross_validation_over_sample``).  We deliberately do NOT cross-check
-    the JiTCODE reference here for the whole catalogue: a couple of systems
-    (see ``HARD_TO_INTEGRATE``) stall every adaptive solver and can't produce a
-    bounded reference, which would hang the sweep rather than measure diffsol.
+    (``test_cross_validation_over_sample``); here we only assert each diffsol
+    trajectory is finite.  ``HARD_TO_INTEGRATE | DIFFSOL_SKIP`` is honoured as
+    an escape hatch for systems that genuinely cannot be integrated, but both
+    sets are currently empty — the whole ODE catalogue integrates on diffsol.
     """
     import sys
     import zlib