tsdynamics 5.2.4__tar.gz → 5.2.5__tar.gz

{tsdynamics-5.2.4 → tsdynamics-5.2.5}/PKG-INFO

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

tsdynamics-5.2.5/crates/tsdyn-core/src/bridge/lyapunov.rs

@@ -0,0 +1,162 @@
+//! ODE Lyapunov-spectrum entry point (stream `perf/ode-lyapunov-engine`).
+//!
+//! Thin bridge over the engine's [`tsdyn_engine::lyapunov`] kernel: build the
+//! evaluator (interpreter or JIT) over the **extended** variational tape + resolve
+//! the solver here (the cranelift edge lives in this crate, not the engine), then
+//! run the whole burn-in + averaging Benettin loop in one call. The per-`dt`
+//! integration is byte-for-byte the released `TangentSystem` ODE numerics, so
+//! `interp == jit` and the spectrum matches the Python path to floating-point
+//! tolerance.
+//!
+//! Shared plumbing (evaluator/solver builders, the `EngineError` enum) lives in
+//! [`super::marshal`]; the renormalisation loop and the QR live in
+//! [`tsdyn_engine::lyapunov`].
+
+use tsdyn_engine::lyapunov::{lyapunov_spectrum_ode, LyapunovError, LyapunovOutcome};
+use tsdyn_ir::Tape;
+use tsdyn_solvers::Solver;
+
+use super::marshal::{
+    build_evaluator, build_solver, require_jacobian_if_needed, resolve_solver, EngineError,
+};
+
+/// Map a [`LyapunovError`] (a kernel-side shape / divergence failure) to the
+/// bridge's [`EngineError`] so the binding routes it to the matching Python
+/// exception (`ValueError` / `RuntimeError`).
+fn to_engine_err(e: LyapunovError) -> EngineError {
+    match e {
+        LyapunovError::BadShape(m) => EngineError::BadShape(m),
+        LyapunovError::Diverged(m) => EngineError::Diverged(m),
+    }
+}
+
+/// Run the burn-in + averaging Benettin Lyapunov-spectrum loop over an
+/// **extended variational** ODE tape.
+///
+/// The `tape` is the `dim*(k+1)`-wide extended variational system (base RHS ⊕ the
+/// `k` tangent-vector RHS blocks) built by the Python
+/// `tsdynamics.derived._variational.build_variational_tape`. `method` resolves
+/// through the solver registry; an implicit kernel needs a Jacobian-carrying tape
+/// (the extended tape carries one — rejected up front exactly as the integrate
+/// path does, for the defence-in-depth message). `dt` is the renormalisation
+/// interval, `burn_in` / `final_time` the two window lengths. `p` is the live
+/// control-parameter vector. Returns the spectrum plus the final extended state.
+#[allow(clippy::too_many_arguments)]
+pub fn lyapunov_spectrum_ode_bridge(
+    tape: Tape,
+    p: &[f64],
+    method: &str,
+    rtol: f64,
+    atol: f64,
+    dim: usize,
+    k: usize,
+    z0: &[f64],
+    t0: f64,
+    dt: f64,
+    burn_in: f64,
+    final_time: f64,
+    jit: bool,
+) -> Result<LyapunovOutcome, EngineError> {
+    // The extended tape is `n_state == ev.dim()` (a plain ODE-shaped tape over the
+    // stacked state), validated by the kernel against `dim*(k+1)`. Resolve the
+    // method + the Jacobian guard exactly like the integrate / basin paths.
+    let name = resolve_solver(method)?;
+    require_jacobian_if_needed(&tape, name)?;
+    let ev = build_evaluator(tape, jit)?;
+    // A fresh kernel per `dt` chunk (mirrors `OdeStepper::advance` / the basin
+    // march); the name is a registry name, so `build_solver` always succeeds.
+    let factory = move || -> Box<dyn Solver> { build_solver(name, rtol, atol) };
+    lyapunov_spectrum_ode(&*ev, factory, p, dim, k, z0, t0, dt, burn_in, final_time)
+        .map_err(to_engine_err)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tsdyn_ir::TapeBuilder;
+
+    /// Extended variational tape of `dx = a x, dy = b y` with `k` tangents (the
+    /// Jacobian is the constant `diag(a, b)`). Spectrum is `[max(a,b), min(a,b)]`.
+    fn linear_extended(a: f64, b: f64, k: usize) -> Tape {
+        let dim = 2;
+        let mut bld = TapeBuilder::new();
+        let x = bld.state(0);
+        let y = bld.state(1);
+        let ac = bld.constant(a);
+        let bc = bld.constant(b);
+        let dx = bld.mul(ac, x);
+        let dy = bld.mul(bc, y);
+        let mut outs = vec![dx, dy];
+        for i in 0..k {
+            let base = dim + i * dim;
+            let w0 = bld.state(base);
+            let w1 = bld.state(base + 1);
+            let dw0 = bld.mul(ac, w0);
+            let dw1 = bld.mul(bc, w1);
+            outs.push(dw0);
+            outs.push(dw1);
+        }
+        let n = dim * (k + 1);
+        bld.finish(&outs, &[], n, 0).unwrap()
+    }
+
+    #[test]
+    fn bridge_spectrum_matches_analytic_and_interp_equals_jit() {
+        let (a, b, k) = (0.5, -2.0, 2);
+        let z0 = vec![1.0, 1.0, 1.0, 0.0, 0.0, 1.0];
+        let run = |jit| {
+            lyapunov_spectrum_ode_bridge(
+                linear_extended(a, b, k),
+                &[],
+                "rk45",
+                1e-9,
+                1e-11,
+                2,
+                k,
+                &z0,
+                0.0,
+                0.1,
+                5.0,
+                50.0,
+                jit,
+            )
+            .unwrap()
+        };
+        let interp = run(false);
+        let jit = run(true);
+        // interp == jit bit-for-bit (both drive the same &dyn Evaluator).
+        assert_eq!(interp.spectrum.len(), jit.spectrum.len());
+        for (i, (x, y)) in interp.spectrum.iter().zip(jit.spectrum.iter()).enumerate() {
+            assert_eq!(
+                x.to_bits(),
+                y.to_bits(),
+                "exponent {i}: jit {y} != interp {x}"
+            );
+        }
+        // and matches the analytic spectrum.
+        assert!((interp.spectrum[0] - 0.5).abs() < 1e-4);
+        assert!((interp.spectrum[1] - (-2.0)).abs() < 1e-4);
+    }
+
+    #[test]
+    fn bridge_rejects_unknown_method() {
+        let z0 = vec![1.0, 1.0, 1.0, 0.0, 0.0, 1.0];
+        let err = lyapunov_spectrum_ode_bridge(
+            linear_extended(0.5, -2.0, 2),
+            &[],
+            "no-such",
+            1e-6,
+            1e-9,
+            2,
+            2,
+            &z0,
+            0.0,
+            0.1,
+            1.0,
+            1.0,
+            false,
+        )
+        .unwrap_err();
+        assert!(matches!(err, EngineError::UnknownMethod(_)), "got {err:?}");
+    }
+}

{tsdynamics-5.2.4 → tsdynamics-5.2.5}/crates/tsdyn-core/src/bridge/map.rs

@@ -5,7 +5,10 @@
 //! iteration loop, shape contract and divergence behaviour are unchanged. Shared
 //! plumbing lives in [`super::marshal`].
 
-use tsdyn_engine::{iterate_dense, iterate_ensemble_final as engine_iterate_ensemble};
+use tsdyn_engine::{
+    iterate_dense, iterate_ensemble_final as engine_iterate_ensemble, map_orbit_sweep, SweepError,
+    SweepOutcome,
+};
 use tsdyn_ir::Tape;
 
 use super::marshal::{build_evaluator, map_diverge_msg, EngineError};
@@ -126,3 +129,88 @@ pub fn map_ensemble_final(
     let result = engine_iterate_ensemble(&*ev, ics, &[], steps);
     Ok(result.states)
 }
+
+/// Map a [`SweepError`] (a kernel-side shape failure) to the bridge's
+/// [`EngineError`] so the binding routes it to the same Python `ValueError` the
+/// other entry points use.
+fn sweep_to_engine_err(e: SweepError) -> EngineError {
+    match e {
+        SweepError::BadShape(m) => EngineError::BadShape(m),
+    }
+}
+
+/// Run the whole map orbit-diagram parameter sweep in one call (stream
+/// `perf/param-sweep-kernel`).
+///
+/// Unlike [`iterate_map`], the tape here keeps the **swept** parameter as its
+/// single runtime `Param` input (`n_param == 1`) — the Python wiring lowers the
+/// map once with the other parameters folded in, so a 1000-value sweep is one FFI
+/// call instead of ~1000 `iterate_map` round-trips. For each value the kernel sets
+/// `p[sweep_index] = value`, runs `transient + n` iterations (carrying the final
+/// state across values when `carry_state`), and records the last `n` asymptotic
+/// states' selected `components`.
+///
+/// Returns `(points, status)`: `points` is the flat row-major
+/// `(n_values * n, n_components)` recorded buffer, and `status[k]` is `0` for a
+/// value that ran finitely / `1` for a value that diverged (whose block is zero —
+/// the binding drops it to an empty set and warns, mirroring the per-value path).
+/// The per-iterate numerics are byte-for-byte the [`iterate_map`] path (a `Param`
+/// leaf reads the same `f64` a folded `Const` would).
+///
+/// `jit` selects the evaluator (Cranelift native code vs the interpreter); both
+/// are bit-for-bit identical on `eval`, so the swept diagram is numerically
+/// identical either way.
+#[allow(clippy::too_many_arguments)]
+pub fn map_param_sweep(
+    tape: Tape,
+    base_params: &[f64],
+    sweep_index: usize,
+    values: &[f64],
+    ic: &[f64],
+    components: &[usize],
+    transient: usize,
+    n_record: usize,
+    carry_state: bool,
+    jit: bool,
+) -> Result<(Vec<f64>, Vec<i64>), EngineError> {
+    // The sweep tape's next-state dimension equals its state dimension, and it
+    // carries exactly the swept parameter as a runtime input. Reject a tape whose
+    // shape disagrees (reachable only via a hand-built tape) so a mismatch is a
+    // clean error rather than a release-mode out-of-bounds inside the eval loop.
+    let dim = tape.dim();
+    if tape.n_state() != dim {
+        return Err(EngineError::BadShape(format!(
+            "map sweep expects n_state == dim (state and next-state share a \
+             dimension); got n_state = {} != dim = {dim}",
+            tape.n_state()
+        )));
+    }
+    if tape.n_param() != base_params.len() {
+        return Err(EngineError::BadShape(format!(
+            "map sweep base-parameter vector has length {}, but the tape declares \
+             n_param = {}",
+            base_params.len(),
+            tape.n_param()
+        )));
+    }
+    let ev = build_evaluator(tape, jit)?;
+    let SweepOutcome { points, status, .. } = map_orbit_sweep(
+        &*ev,
+        base_params,
+        sweep_index,
+        values,
+        ic,
+        components,
+        transient,
+        n_record,
+        carry_state,
+    )
+    .map_err(sweep_to_engine_err)?;
+    // Flatten the per-value fate to a plain i64 code (0 = ok, 1 = diverged) the
+    // FFI returns alongside the points buffer.
+    let status: Vec<i64> = status
+        .into_iter()
+        .map(|s| if s.is_ok() { 0 } else { 1 })
+        .collect();
+    Ok((points, status))
+}

tsdynamics-5.2.5/crates/tsdyn-core/src/bridge/map_lyapunov.rs

@@ -0,0 +1,142 @@
+//! Discrete-map Lyapunov-spectrum entry point (stream `perf/map-lyapunov-kernel`).
+//!
+//! Thin bridge over the engine's [`tsdyn_engine::map_lyapunov`] kernel: build the
+//! evaluator (interpreter or JIT) here (the cranelift edge lives in this crate, not
+//! the engine), then run the whole QR tangent-map iteration in one call. The map
+//! tape must carry its Jacobian (`with_jacobian=True`) — the tangent map needs
+//! `∂f/∂u`; a Jacobian-less tape is rejected as the engine error
+//! [`MapLyapunovError::NoJacobian`].
+//!
+//! Driven over the same lowered IR tape, the interpreter and JIT agree bit-for-bit;
+//! against the released Python `TangentSystem._accumulate_map` the result differs
+//! only by the lowered-IR vs pure-Python `_step`/`_jacobian` float order (the
+//! WS-MAPITER caveat) — the same attractor, the same spectrum to tolerance.
+
+use tsdyn_engine::map_lyapunov::{map_lyapunov, MapLyapunovError, MapLyapunovOutcome};
+use tsdyn_ir::Tape;
+
+use super::marshal::{build_evaluator, EngineError};
+
+/// Map a [`MapLyapunovError`] (a kernel-side shape / Jacobian / divergence failure)
+/// to the bridge's [`EngineError`] so the binding layer routes it to the same
+/// Python exception the other entry points use (`ValueError` / `RuntimeError`). The
+/// Jacobian-less case carries the actionable "recompile with a Jacobian" message.
+fn to_engine_err(e: MapLyapunovError) -> EngineError {
+    match e {
+        MapLyapunovError::BadShape(m) => EngineError::BadShape(m),
+        MapLyapunovError::NoJacobian => EngineError::BadShape(
+            "map Lyapunov needs the step Jacobian, but the map tape was compiled without one \
+             (with_jacobian=False). Recompile the map problem with a Jacobian."
+                .to_string(),
+        ),
+        MapLyapunovError::Diverged(m) => EngineError::Diverged(m),
+    }
+}
+
+/// Run the discrete-map QR tangent-map Lyapunov spectrum over a **map** tape.
+///
+/// Builds the evaluator over `tape` (which must carry its step Jacobian), seeds the
+/// deviation frame to the leading `k` identity columns, iterates `steps` map steps
+/// propagating the frame through `J(x_n)` (pre-image convention) with a QR
+/// reorthonormalisation every `reortho_interval` steps, and returns the `k`
+/// time-averaged exponents (largest first) plus the completed-interval count. The
+/// map tape folds its parameters in, so `p` is empty. `jit` selects the Cranelift
+/// evaluator (numerically identical to the interpreter).
+#[allow(clippy::too_many_arguments)]
+pub fn map_lyapunov_bridge(
+    tape: Tape,
+    p: &[f64],
+    ic: &[f64],
+    steps: usize,
+    k: usize,
+    reortho_interval: usize,
+    jit: bool,
+) -> Result<MapLyapunovOutcome, EngineError> {
+    let ev = build_evaluator(tape, jit)?;
+    map_lyapunov(&*ev, p, ic, steps, k, reortho_interval).map_err(to_engine_err)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tsdyn_ir::TapeBuilder;
+
+    /// Hénon `(x, y) ← (1 - a x² + y, b x)` carrying its analytic Jacobian.
+    fn henon_jac(a: f64, bcoef: f64) -> Tape {
+        let mut b = TapeBuilder::new();
+        let x = b.state(0);
+        let y = b.state(1);
+        let one = b.constant(1.0);
+        let ac = b.constant(a);
+        let bc = b.constant(bcoef);
+        let xx = b.mul(x, x);
+        let axx = b.mul(ac, xx);
+        let omaxx = b.sub(one, axx);
+        let nx = b.add(omaxx, y);
+        let ny = b.mul(bc, x);
+        let two = b.constant(2.0);
+        let twoa = b.mul(two, ac);
+        let twoax = b.mul(twoa, x);
+        let neg_twoax = b.neg(twoax);
+        let zero = b.constant(0.0);
+        b.finish(&[nx, ny], &[neg_twoax, one, bc, zero], 2, 0)
+            .unwrap()
+    }
+
+    /// A Jacobian-less map tape (the rejected case).
+    fn henon_no_jac(a: f64, bcoef: f64) -> Tape {
+        let mut b = TapeBuilder::new();
+        let x = b.state(0);
+        let y = b.state(1);
+        let one = b.constant(1.0);
+        let ac = b.constant(a);
+        let bc = b.constant(bcoef);
+        let xx = b.mul(x, x);
+        let axx = b.mul(ac, xx);
+        let omaxx = b.sub(one, axx);
+        let nx = b.add(omaxx, y);
+        let ny = b.mul(bc, x);
+        b.finish(&[nx, ny], &[], 2, 0).unwrap()
+    }
+
+    #[test]
+    fn bridge_interp_equals_jit_bit_for_bit() {
+        // The bridge drives both evaluators over the same lowered tape; the
+        // iteration is deterministic and eval/eval_jac are bit-identical between
+        // interpreter and JIT, so the exponents agree to the last bit.
+        let run = |jit| {
+            map_lyapunov_bridge(henon_jac(1.4, 0.3), &[], &[0.1, 0.1], 5000, 2, 1, jit)
+                .unwrap()
+                .exponents
+        };
+        let interp = run(false);
+        let jit = run(true);
+        assert_eq!(interp.len(), jit.len());
+        for (a, b) in interp.iter().zip(jit.iter()) {
+            assert_eq!(a.to_bits(), b.to_bits(), "interp {a} != jit {b}");
+        }
+    }
+
+    #[test]
+    fn bridge_reproduces_henon_literature() {
+        let out = map_lyapunov_bridge(henon_jac(1.4, 0.3), &[], &[0.1, 0.1], 10_000, 2, 1, false)
+            .unwrap();
+        assert!(
+            (out.exponents[0] - 0.419).abs() < 0.05,
+            "{:?}",
+            out.exponents
+        );
+        assert!(
+            (out.exponents[1] - (-1.623)).abs() < 0.05,
+            "{:?}",
+            out.exponents
+        );
+    }
+
+    #[test]
+    fn bridge_rejects_jacobianless_tape() {
+        let err = map_lyapunov_bridge(henon_no_jac(1.4, 0.3), &[], &[0.1, 0.1], 100, 2, 1, false)
+            .unwrap_err();
+        assert!(matches!(err, EngineError::BadShape(_)), "got {err:?}");
+    }
+}

{tsdynamics-5.2.4 → tsdynamics-5.2.5}/crates/tsdyn-core/src/bridge/mod.rs

@@ -33,7 +33,9 @@
 pub mod basin;
 pub mod dde;
 pub mod events;
+pub mod lyapunov;
 pub mod map;
+pub mod map_lyapunov;
 pub mod marshal;
 pub mod ode;
 pub mod sde;
@@ -46,7 +48,9 @@ pub mod stepper;
 pub use basin::{basin_march_flow_bridge, basin_march_map_bridge};
 pub use dde::integrate_dde_dense;
 pub use events::integrate_events_dense;
-pub use map::{iterate_map, map_ensemble_final};
+pub use lyapunov::lyapunov_spectrum_ode_bridge;
+pub use map::{iterate_map, map_ensemble_final, map_param_sweep};
+pub use map_lyapunov::map_lyapunov_bridge;
 #[cfg(test)]
 pub use marshal::build_tape;
 pub use marshal::EngineError;

{tsdynamics-5.2.4 → tsdynamics-5.2.5}/crates/tsdyn-core/src/lib.rs

@@ -281,6 +281,79 @@ fn iterate_ensemble_final<'py>(
     PyArray1::from_vec(py, flat).reshape([n_ic, dim])
 }
 
+/// Run a whole map orbit-diagram parameter sweep in one call (stream
+/// `perf/param-sweep-kernel`), returning the recorded asymptotic states and each
+/// value's fate.
+///
+/// The leading tape arrays describe the lowered map with the **swept** parameter
+/// kept as its single runtime `Param` input (`n_param == 1`) — the other
+/// parameters fold into constants — so the sweep needs no per-value re-lowering or
+/// per-value FFI round-trip. `base_params` is the full runtime parameter vector;
+/// `sweep_index` which of its entries each `values[k]` overwrites; `ic` the base
+/// initial condition; `components` the state-component indices to record;
+/// `transient` / `n_record` the discard / record counts; `carry_state` whether
+/// each value resumes from the previous value's final state; `jit` selects the
+/// Cranelift evaluator (numerically identical to the interpreter).
+///
+/// Returns `(points, status)`: `points` is the `(n_values * n_record,
+/// n_components)` recorded array, and `status` an `(n_values,)` i64 array of `0`
+/// (finite) / `1` (diverged — the value's block is zero, dropped to an empty set
+/// by the Python wiring). The per-iterate numerics are byte-for-byte the
+/// [`iterate_map`] path.
+#[pyfunction]
+#[allow(clippy::too_many_arguments, clippy::type_complexity)]
+fn map_param_sweep<'py>(
+    py: Python<'py>,
+    ops: PyReadonlyArray1<i32>,
+    a: PyReadonlyArray1<i32>,
+    b: PyReadonlyArray1<i32>,
+    imm: PyReadonlyArray1<f64>,
+    outputs: PyReadonlyArray1<i32>,
+    jac_outputs: PyReadonlyArray1<i32>,
+    n_state: usize,
+    n_param: usize,
+    base_params: PyReadonlyArray1<f64>,
+    sweep_index: usize,
+    values: PyReadonlyArray1<f64>,
+    ic: PyReadonlyArray1<f64>,
+    components: PyReadonlyArray1<i64>,
+    transient: usize,
+    n_record: usize,
+    carry_state: bool,
+    jit: bool,
+) -> PyResult<(Bound<'py, PyArray2<f64>>, Bound<'py, PyArray1<i64>>)> {
+    let tape = OwnedTape::copy_in(&ops, &a, &b, &imm, &outputs, &jac_outputs, n_state, n_param)?;
+    let base_params = vec_f64("base_params", &base_params)?;
+    let values = vec_f64("values", &values)?;
+    let ic = vec_f64("ic", &ic)?;
+    let components: Vec<usize> = components
+        .as_slice()
+        .map_err(|_| PyValueError::new_err("components must be a contiguous int64 array"))?
+        .iter()
+        .map(|&c| c as usize)
+        .collect();
+    let n_values = values.len();
+    let n_components = components.len();
+    let (points, status) = py
+        .detach(|| {
+            bridge::map_param_sweep(
+                tape.build()?,
+                &base_params,
+                sweep_index,
+                &values,
+                &ic,
+                &components,
+                transient,
+                n_record,
+                carry_state,
+                jit,
+            )
+        })
+        .map_err(to_py_err)?;
+    let points = PyArray1::from_vec(py, points).reshape([n_values * n_record, n_components])?;
+    Ok((points, PyArray1::from_vec(py, status)))
+}
+
 // ---------------------------------------------------------------------------
 // Integration
 // ---------------------------------------------------------------------------
@@ -961,6 +1034,138 @@ fn basin_march_map<'py>(
     Ok(basin_outcome_to_py(py, out))
 }
 
+// ---------------------------------------------------------------------------
+// Discrete-map Lyapunov spectrum (stream perf/map-lyapunov-kernel)
+// ---------------------------------------------------------------------------
+
+use bridge::map_lyapunov_bridge;
+
+/// Compute a discrete-map Lyapunov spectrum on the engine — the whole QR
+/// tangent-map iteration (iterate `f`, propagate `k` deviation vectors through
+/// `J(x_n)` at the pre-image, reorthonormalise, accumulate `log|R_ii|`) in one call.
+///
+/// The leading tape arrays are the usual `Tape.to_arrays()` tuple for the **map**
+/// step, which **must carry its Jacobian** (`with_jacobian=True`; rejected up front
+/// otherwise). `ic` is the `(dim,)` start state; `steps` the iterate budget; `k` the
+/// number of exponents (`1 ≤ k ≤ dim`); `reortho_interval` the QR cadence. The map
+/// tape folds its parameters in, so there is no parameter vector. `jit` selects the
+/// Cranelift evaluator (numerically identical to the interpreter).
+///
+/// Returns `(exponents, intervals)`: the `k` time-averaged exponents (largest
+/// first) and the number of completed reorthonormalisation intervals. A divergence
+/// before the budget is exhausted raises `RuntimeError` (the "diverge loudly"
+/// contract); a malformed call / Jacobian-less tape raises `ValueError`.
+#[pyfunction]
+#[allow(clippy::too_many_arguments)]
+fn map_lyapunov_spectrum<'py>(
+    py: Python<'py>,
+    ops: PyReadonlyArray1<i32>,
+    a: PyReadonlyArray1<i32>,
+    b: PyReadonlyArray1<i32>,
+    imm: PyReadonlyArray1<f64>,
+    outputs: PyReadonlyArray1<i32>,
+    jac_outputs: PyReadonlyArray1<i32>,
+    n_state: usize,
+    n_param: usize,
+    ic: PyReadonlyArray1<f64>,
+    steps: usize,
+    k: usize,
+    reortho_interval: usize,
+    jit: bool,
+) -> PyResult<(Bound<'py, PyArray1<f64>>, usize)> {
+    let tape = OwnedTape::copy_in(&ops, &a, &b, &imm, &outputs, &jac_outputs, n_state, n_param)?;
+    let ic = vec_f64("ic", &ic)?;
+    let out = py
+        .detach(|| map_lyapunov_bridge(tape.build()?, &[], &ic, steps, k, reortho_interval, jit))
+        .map_err(to_py_err)?;
+    Ok((PyArray1::from_vec(py, out.exponents), out.intervals))
+}
+
+// ODE Lyapunov spectrum (stream perf/ode-lyapunov-engine)
+// ---------------------------------------------------------------------------
+
+use bridge::lyapunov_spectrum_ode_bridge;
+
+/// Run the whole burn-in + averaging Benettin Lyapunov-spectrum loop for an ODE
+/// flow in one engine call.
+///
+/// The leading tape arrays are the usual `Tape.to_arrays()` tuple — here the
+/// **extended** variational tape (`dim*(k+1)` inputs/outputs: the base RHS stacked
+/// with the `k` tangent-vector RHS blocks, built by
+/// `tsdynamics.derived._variational.build_variational_tape`). `p` is the live
+/// control-parameter vector; `method` resolves through the solver registry
+/// (an implicit kernel needs a Jacobian-carrying tape — the extended tape carries
+/// one); `dim` the **base** system dimension; `k` the number of tangent vectors;
+/// `z0` the extended initial state (`embed_extended`: base IC ⊕ the seed tangent
+/// frame, column-major); `t0` the start time; `dt` the renormalisation interval;
+/// `burn_in` / `final_time` the two window lengths; `jit` selects the Cranelift
+/// evaluator (numerically identical to the interpreter).
+///
+/// Each `dt` chunk is integrated by a *fresh* two-node `integrate_grid([t, t+dt])`
+/// (byte-for-byte the released `TangentSystem._step_ode_engine` numerics, so
+/// `interp == jit`), then the `(dim, k)` tangent block is QR-reorthonormalised
+/// (modified Gram–Schmidt) and `Σ log|diag R|` accumulated over the averaging
+/// window. Returns `(spectrum, final_state, last_growths)` — the `k` exponents,
+/// the final extended state, and the last per-step log-stretch contributions. A
+/// divergence raises (it must not become a plausible-looking spectrum).
+#[pyfunction]
+#[allow(clippy::too_many_arguments, clippy::type_complexity)]
+fn lyapunov_spectrum_ode<'py>(
+    py: Python<'py>,
+    ops: PyReadonlyArray1<i32>,
+    a: PyReadonlyArray1<i32>,
+    b: PyReadonlyArray1<i32>,
+    imm: PyReadonlyArray1<f64>,
+    outputs: PyReadonlyArray1<i32>,
+    jac_outputs: PyReadonlyArray1<i32>,
+    n_state: usize,
+    n_param: usize,
+    p: PyReadonlyArray1<f64>,
+    method: String,
+    rtol: f64,
+    atol: f64,
+    dim: usize,
+    k: usize,
+    z0: PyReadonlyArray1<f64>,
+    t0: f64,
+    dt: f64,
+    burn_in: f64,
+    final_time: f64,
+    jit: bool,
+) -> PyResult<(
+    Bound<'py, PyArray1<f64>>,
+    Bound<'py, PyArray1<f64>>,
+    Bound<'py, PyArray1<f64>>,
+)> {
+    let tape = OwnedTape::copy_in(&ops, &a, &b, &imm, &outputs, &jac_outputs, n_state, n_param)?;
+    let p = vec_f64("p", &p)?;
+    let z0 = vec_f64("z0", &z0)?;
+    let out = py
+        .detach(|| {
+            lyapunov_spectrum_ode_bridge(
+                tape.build()?,
+                &p,
+                &method,
+                rtol,
+                atol,
+                dim,
+                k,
+                &z0,
+                t0,
+                dt,
+                burn_in,
+                final_time,
+                jit,
+            )
+        })
+        .map_err(to_py_err)?;
+    Ok((
+        PyArray1::from_vec(py, out.spectrum),
+        PyArray1::from_vec(py, out.final_state),
+        PyArray1::from_vec(py, out.last_growths),
+    ))
+}
+
 // ---------------------------------------------------------------------------
 // Resumable ODE stepper handle (stream WS-STEPPER)
 // ---------------------------------------------------------------------------
@@ -1171,6 +1376,7 @@ fn _rust(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(eval_jac, m)?)?;
     m.add_function(wrap_pyfunction!(iterate_map, m)?)?;
     m.add_function(wrap_pyfunction!(iterate_ensemble_final, m)?)?;
+    m.add_function(wrap_pyfunction!(map_param_sweep, m)?)?;
     m.add_function(wrap_pyfunction!(integrate_dense, m)?)?;
     m.add_function(wrap_pyfunction!(integrate_dde_dense, m)?)?;
     m.add_function(wrap_pyfunction!(integrate_ensemble_final, m)?)?;
@@ -1179,6 +1385,8 @@ fn _rust(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(integrate_events_dense, m)?)?;
     m.add_function(wrap_pyfunction!(basin_march_flow, m)?)?;
     m.add_function(wrap_pyfunction!(basin_march_map, m)?)?;
+    m.add_function(wrap_pyfunction!(map_lyapunov_spectrum, m)?)?;
+    m.add_function(wrap_pyfunction!(lyapunov_spectrum_ode, m)?)?;
     m.add_class::<PyOdeStepper>()?;
     m.add_function(wrap_pyfunction!(solvers, m)?)?;
     m.add_function(wrap_pyfunction!(_version, m)?)?;