tsdynamics 5.2.2__tar.gz → 5.2.4__tar.gz

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

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

tsdynamics-5.2.4/crates/tsdyn-core/src/bridge/basin.rs

@@ -0,0 +1,224 @@
+//! Basin / attractor recurrence-FSM entry points (stream `perf/basin-march`).
+//!
+//! Thin bridge over the engine's [`tsdyn_engine::basin`] kernel: build the
+//! evaluator (interpreter or JIT) + resolve the solver here (the cranelift edge
+//! lives in this crate, not the engine), then drive the sequential FSM over every
+//! seed in one call. The numerics per cell-check are byte-for-byte the per-`dt`
+//! `ContinuousSystem.step()` (flows) / one map iteration (maps), so the located
+//! labels are bit-identical to the Python `_AttractorMapper`.
+//!
+//! Shared plumbing (evaluator/solver builders, the `EngineError` enum) lives in
+//! [`super::marshal`]; the FSM, the cell grid and the validation live in
+//! [`tsdyn_engine::basin`].
+
+use tsdyn_engine::basin::{
+    basin_march_flow, basin_march_map, BasinError, BasinMarchOutcome, MarchConfig,
+};
+use tsdyn_ir::Tape;
+use tsdyn_solvers::Solver;
+
+use super::marshal::{
+    build_evaluator, build_solver, guard_continuous, require_jacobian_if_needed, resolve_solver,
+    EngineError,
+};
+
+/// Map a [`BasinError`] (a kernel-side shape/grid failure) to the bridge's
+/// [`EngineError`] so the binding layer routes it to the same Python exception the
+/// other entry points use (`ValueError`).
+fn to_engine_err(e: BasinError) -> EngineError {
+    match e {
+        BasinError::BadShape(m) => EngineError::BadShape(m),
+    }
+}
+
+/// Run the basin recurrence FSM over a **flow** (ODE) tape.
+///
+/// Builds the evaluator over `tape`, resolves `method` (an implicit kernel needs a
+/// Jacobian-carrying tape, rejected up front exactly as the integrate path does),
+/// and marches every seed sequentially advancing one `dt` per cell check. `cfg`
+/// carries the six FSM thresholds. Returns the per-seed labels + the accumulated
+/// `att_cells`/`bas_cells`/`att_points` the Python wiring rebuilds the mapper from.
+#[allow(clippy::too_many_arguments)]
+pub fn basin_march_flow_bridge(
+    tape: Tape,
+    p: &[f64],
+    method: &str,
+    rtol: f64,
+    atol: f64,
+    dt: f64,
+    grid_lo: &[f64],
+    grid_hi: &[f64],
+    grid_counts: &[i64],
+    seeds: &[f64],
+    cfg: MarchConfig,
+    jit: bool,
+) -> Result<BasinMarchOutcome, EngineError> {
+    // An ODE-shaped tape only (a DDE/SDE tape has its own family path; the Python
+    // wiring already excludes DDE/SDE, but guard at the boundary too).
+    guard_continuous(&tape)?;
+    let name = resolve_solver(method)?;
+    require_jacobian_if_needed(&tape, name)?;
+    let ev = build_evaluator(tape, jit)?;
+    // A fresh kernel per `dt` segment (mirrors `OdeStepper::advance`); the name is
+    // a registry name, so `build_solver` always succeeds.
+    let factory = move || -> Box<dyn Solver> { build_solver(name, rtol, atol) };
+    basin_march_flow(
+        &*ev,
+        factory,
+        p,
+        dt,
+        grid_lo,
+        grid_hi,
+        grid_counts,
+        seeds,
+        cfg,
+    )
+    .map_err(to_engine_err)
+}
+
+/// Run the basin recurrence FSM over a **map** tape.
+///
+/// As [`basin_march_flow_bridge`], but each cell check applies the lowered `_step`
+/// map once (no solver, no `dt`). The map tape folds its parameters in, so `p` is
+/// empty.
+#[allow(clippy::too_many_arguments)]
+pub fn basin_march_map_bridge(
+    tape: Tape,
+    p: &[f64],
+    grid_lo: &[f64],
+    grid_hi: &[f64],
+    grid_counts: &[i64],
+    seeds: &[f64],
+    cfg: MarchConfig,
+    jit: bool,
+) -> Result<BasinMarchOutcome, EngineError> {
+    let ev = build_evaluator(tape, jit)?;
+    basin_march_map(&*ev, p, grid_lo, grid_hi, grid_counts, seeds, cfg).map_err(to_engine_err)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tsdyn_ir::TapeBuilder;
+
+    /// `x ← a x − x³`, `a` folded in (two fixed points at `±√(a−1)` for `1<a<2`).
+    fn cubic_map(a: f64) -> Tape {
+        let mut b = TapeBuilder::new();
+        let x = b.state(0);
+        let ac = b.constant(a);
+        let ax = b.mul(ac, x);
+        let x2 = b.mul(x, x);
+        let x3 = b.mul(x2, x);
+        let nx = b.sub(ax, x3);
+        b.finish(&[nx], &[], 1, 0).unwrap()
+    }
+
+    fn cfg() -> MarchConfig {
+        MarchConfig {
+            max_steps: 500,
+            mx_fnd: 8,
+            mx_loc: 5,
+            mx_att: 2,
+            mx_bas: 10,
+            mx_lost: 20,
+        }
+    }
+
+    #[test]
+    fn map_bridge_interp_equals_jit_bit_for_bit() {
+        // The bridge drives both evaluators; the FSM is deterministic and the
+        // per-step numerics are bit-identical, so interp == jit to the bit.
+        let seeds: Vec<f64> = (0..30).map(|i| -1.0 + 0.06 * i as f64).collect();
+        let run = |jit| {
+            basin_march_map_bridge(
+                cubic_map(1.5),
+                &[],
+                &[-2.0],
+                &[2.0],
+                &[300],
+                &seeds,
+                cfg(),
+                jit,
+            )
+            .unwrap()
+            .labels
+        };
+        assert_eq!(run(false), run(true));
+    }
+
+    #[test]
+    fn flow_bridge_decays_to_origin_and_interp_equals_jit() {
+        // dx=-x, dv=-v spirals to the origin; one attractor region. interp == jit.
+        let build = || {
+            let mut b = TapeBuilder::new();
+            let x = b.state(0);
+            let v = b.state(1);
+            let dx = b.neg(x);
+            let dv = b.neg(v);
+            b.finish(&[dx, dv], &[], 2, 0).unwrap()
+        };
+        let seeds = vec![0.5, 0.5, -0.5, -0.5, 0.3, -0.4];
+        let mcfg = MarchConfig {
+            max_steps: 2000,
+            mx_fnd: 20,
+            mx_loc: 10,
+            mx_att: 2,
+            mx_bas: 10,
+            mx_lost: 20,
+        };
+        let run = |jit| {
+            basin_march_flow_bridge(
+                build(),
+                &[],
+                "rk45",
+                1e-6,
+                1e-9,
+                0.2,
+                &[-1.0, -1.0],
+                &[1.0, 1.0],
+                &[50, 50],
+                &seeds,
+                mcfg,
+                jit,
+            )
+            .unwrap()
+            .labels
+        };
+        let interp = run(false);
+        let jit = run(true);
+        assert_eq!(interp, jit, "interp vs jit basin labels differ");
+        // No seed diverged.
+        assert!(
+            interp.iter().all(|&l| l >= 1),
+            "a seed diverged: {interp:?}"
+        );
+    }
+
+    #[test]
+    fn flow_bridge_rejects_implicit_without_jacobian() {
+        // An implicit kernel over a tape with no Jacobian is rejected at the
+        // boundary (BadShape → ValueError), exactly as the integrate path does.
+        let build = || {
+            let mut b = TapeBuilder::new();
+            let x = b.state(0);
+            let dx = b.neg(x);
+            b.finish(&[dx], &[], 1, 0).unwrap()
+        };
+        let err = basin_march_flow_bridge(
+            build(),
+            &[],
+            "bdf",
+            1e-6,
+            1e-9,
+            0.1,
+            &[-1.0],
+            &[1.0],
+            &[10],
+            &[0.5],
+            cfg(),
+            false,
+        )
+        .unwrap_err();
+        assert!(matches!(err, EngineError::BadShape(_)), "got {err:?}");
+    }
+}

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

@@ -30,6 +30,7 @@
 //! Errors surface as [`EngineError`], a Python-free enum the binding layer maps
 //! onto the right Python exception type.
 
+pub mod basin;
 pub mod dde;
 pub mod events;
 pub mod map;
@@ -42,6 +43,7 @@ pub mod stepper;
 // pre-split single-file module exposed it. `lib.rs` and the unit tests below
 // depend on this flat surface; keeping it here means the file split is invisible
 // to every caller.
+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};

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

@@ -710,6 +710,257 @@ fn integrate_events_dense<'py>(
     Ok((times, states, t_final, u_final, terminated))
 }
 
+// ---------------------------------------------------------------------------
+// Basin / attractor recurrence FSM (stream perf/basin-march)
+// ---------------------------------------------------------------------------
+
+use bridge::{basin_march_flow_bridge, basin_march_map_bridge};
+use tsdyn_engine::basin::{BasinMarchOutcome, MarchConfig};
+
+/// Marshal a [`BasinMarchOutcome`] into the flat NumPy tuple the Python wiring
+/// rebuilds the mapper from.
+///
+/// Returns `(labels, att_keys, att_ids, bas_keys, bas_ids, point_ids,
+/// point_counts, points_flat, dim)`:
+///
+/// - `labels` `(n_seeds,)` i64 — per-seed attractor id (or `-1` diverged);
+/// - `att_keys`/`att_ids` `(A,)` i64 — the `att_cells` map (flat cell → id);
+/// - `bas_keys`/`bas_ids` `(B,)` i64 — the `bas_cells` map;
+/// - `point_ids`/`point_counts` `(P,)` i64 — one row per attractor id with its
+///   point-cloud row count; `points_flat` `(sum(counts)*dim,)` f64 the row-major
+///   clouds, sliced back per id by the cumulative counts; `dim` the row width.
+#[allow(clippy::type_complexity)]
+fn basin_outcome_to_py(
+    py: Python<'_>,
+    out: BasinMarchOutcome,
+) -> (
+    Bound<'_, PyArray1<i64>>,
+    Bound<'_, PyArray1<i64>>,
+    Bound<'_, PyArray1<i64>>,
+    Bound<'_, PyArray1<i64>>,
+    Bound<'_, PyArray1<i64>>,
+    Bound<'_, PyArray1<i64>>,
+    Bound<'_, PyArray1<i64>>,
+    Bound<'_, PyArray1<f64>>,
+    usize,
+) {
+    let labels = PyArray1::from_vec(py, out.labels);
+
+    let (att_keys, att_ids): (Vec<i64>, Vec<i64>) = out
+        .att_cells
+        .into_iter()
+        .map(|(k, v)| (k as i64, v))
+        .unzip();
+    let (bas_keys, bas_ids): (Vec<i64>, Vec<i64>) = out
+        .bas_cells
+        .into_iter()
+        .map(|(k, v)| (k as i64, v))
+        .unzip();
+
+    let mut point_ids: Vec<i64> = Vec::with_capacity(out.att_points.len());
+    let mut point_counts: Vec<i64> = Vec::with_capacity(out.att_points.len());
+    let mut points_flat: Vec<f64> = Vec::new();
+    for (id, m, flat) in out.att_points {
+        point_ids.push(id);
+        point_counts.push(m as i64);
+        points_flat.extend_from_slice(&flat);
+    }
+
+    (
+        labels,
+        PyArray1::from_vec(py, att_keys),
+        PyArray1::from_vec(py, att_ids),
+        PyArray1::from_vec(py, bas_keys),
+        PyArray1::from_vec(py, bas_ids),
+        PyArray1::from_vec(py, point_ids),
+        PyArray1::from_vec(py, point_counts),
+        PyArray1::from_vec(py, points_flat),
+        out.dim,
+    )
+}
+
+/// Build the six FSM thresholds from the positional ints the Python wiring passes.
+fn march_config(
+    max_steps: usize,
+    mx_fnd: usize,
+    mx_loc: usize,
+    mx_att: usize,
+    mx_bas: usize,
+    mx_lost: usize,
+) -> MarchConfig {
+    MarchConfig {
+        max_steps,
+        mx_fnd,
+        mx_loc,
+        mx_att,
+        mx_bas,
+        mx_lost,
+    }
+}
+
+/// Run the basin recurrence FSM over a **flow** (ODE) — the whole per-IC march
+/// (stepping + cell-binning + the shared-label early-out) for every seed in one
+/// sequential engine call.
+///
+/// The leading tape arrays are the usual `Tape.to_arrays()` tuple; `p` the live
+/// control parameters; `method` resolves through the solver registry (an implicit
+/// kernel needs `with_jacobian=True`, rejected up front); `dt` the per-cell-check
+/// step (byte-for-byte the `ContinuousSystem.step(dt)` numerics); `grid_lo` /
+/// `grid_hi` / `grid_counts` the recurrence cell tessellation; `seeds` an
+/// `(n_seeds, dim)` array of initial conditions; the six `mx_*` ints the FSM
+/// thresholds; `jit` selects the Cranelift evaluator (numerically identical).
+///
+/// Returns the flat tuple [`basin_outcome_to_py`] documents — per-seed labels plus
+/// the accumulated `att_cells`/`bas_cells`/`att_points` the Python wiring rebuilds
+/// the mapper from. Divergence is a `-1` label, never an error; an engine
+/// unavailability or a shape error raises (it must not become divergence).
+#[pyfunction]
+#[allow(clippy::too_many_arguments, clippy::type_complexity)]
+fn basin_march_flow<'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,
+    dt: f64,
+    grid_lo: PyReadonlyArray1<f64>,
+    grid_hi: PyReadonlyArray1<f64>,
+    grid_counts: PyReadonlyArray1<i64>,
+    seeds: PyReadonlyArray2<f64>,
+    max_steps: usize,
+    mx_fnd: usize,
+    mx_loc: usize,
+    mx_att: usize,
+    mx_bas: usize,
+    mx_lost: usize,
+    jit: bool,
+) -> PyResult<(
+    Bound<'py, PyArray1<i64>>,
+    Bound<'py, PyArray1<i64>>,
+    Bound<'py, PyArray1<i64>>,
+    Bound<'py, PyArray1<i64>>,
+    Bound<'py, PyArray1<i64>>,
+    Bound<'py, PyArray1<i64>>,
+    Bound<'py, PyArray1<i64>>,
+    Bound<'py, PyArray1<f64>>,
+    usize,
+)> {
+    let tape = OwnedTape::copy_in(&ops, &a, &b, &imm, &outputs, &jac_outputs, n_state, n_param)?;
+    let p = vec_f64("p", &p)?;
+    let grid_lo = vec_f64("grid_lo", &grid_lo)?;
+    let grid_hi = vec_f64("grid_hi", &grid_hi)?;
+    let grid_counts = grid_counts
+        .as_slice()
+        .map_err(|_| PyValueError::new_err("grid_counts must be a contiguous int64 array"))?
+        .to_vec();
+    let seeds_vec = seeds
+        .as_slice()
+        .map_err(|_| {
+            PyValueError::new_err("seeds must be a C-contiguous (n_seeds, dim) float64 array")
+        })?
+        .to_vec();
+    let cfg = march_config(max_steps, mx_fnd, mx_loc, mx_att, mx_bas, mx_lost);
+    let out = py
+        .detach(|| {
+            basin_march_flow_bridge(
+                tape.build()?,
+                &p,
+                &method,
+                rtol,
+                atol,
+                dt,
+                &grid_lo,
+                &grid_hi,
+                &grid_counts,
+                &seeds_vec,
+                cfg,
+                jit,
+            )
+        })
+        .map_err(to_py_err)?;
+    Ok(basin_outcome_to_py(py, out))
+}
+
+/// Run the basin recurrence FSM over a **map** (discrete system).
+///
+/// As [`basin_march_flow`], but each cell check applies the lowered `_step` map
+/// once (no `method`/`rtol`/`atol`/`dt`). The map tape folds its parameters in, so
+/// `p` is empty.
+#[pyfunction]
+#[allow(clippy::too_many_arguments, clippy::type_complexity)]
+fn basin_march_map<'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>,
+    grid_lo: PyReadonlyArray1<f64>,
+    grid_hi: PyReadonlyArray1<f64>,
+    grid_counts: PyReadonlyArray1<i64>,
+    seeds: PyReadonlyArray2<f64>,
+    max_steps: usize,
+    mx_fnd: usize,
+    mx_loc: usize,
+    mx_att: usize,
+    mx_bas: usize,
+    mx_lost: usize,
+    jit: bool,
+) -> PyResult<(
+    Bound<'py, PyArray1<i64>>,
+    Bound<'py, PyArray1<i64>>,
+    Bound<'py, PyArray1<i64>>,
+    Bound<'py, PyArray1<i64>>,
+    Bound<'py, PyArray1<i64>>,
+    Bound<'py, PyArray1<i64>>,
+    Bound<'py, PyArray1<i64>>,
+    Bound<'py, PyArray1<f64>>,
+    usize,
+)> {
+    let tape = OwnedTape::copy_in(&ops, &a, &b, &imm, &outputs, &jac_outputs, n_state, n_param)?;
+    let p = vec_f64("p", &p)?;
+    let grid_lo = vec_f64("grid_lo", &grid_lo)?;
+    let grid_hi = vec_f64("grid_hi", &grid_hi)?;
+    let grid_counts = grid_counts
+        .as_slice()
+        .map_err(|_| PyValueError::new_err("grid_counts must be a contiguous int64 array"))?
+        .to_vec();
+    let seeds_vec = seeds
+        .as_slice()
+        .map_err(|_| {
+            PyValueError::new_err("seeds must be a C-contiguous (n_seeds, dim) float64 array")
+        })?
+        .to_vec();
+    let cfg = march_config(max_steps, mx_fnd, mx_loc, mx_att, mx_bas, mx_lost);
+    let out = py
+        .detach(|| {
+            basin_march_map_bridge(
+                tape.build()?,
+                &p,
+                &grid_lo,
+                &grid_hi,
+                &grid_counts,
+                &seeds_vec,
+                cfg,
+                jit,
+            )
+        })
+        .map_err(to_py_err)?;
+    Ok(basin_outcome_to_py(py, out))
+}
+
 // ---------------------------------------------------------------------------
 // Resumable ODE stepper handle (stream WS-STEPPER)
 // ---------------------------------------------------------------------------
@@ -926,6 +1177,8 @@ fn _rust(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(integrate_sde_dense, m)?)?;
     m.add_function(wrap_pyfunction!(integrate_sde_ensemble_final, m)?)?;
     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_class::<PyOdeStepper>()?;
     m.add_function(wrap_pyfunction!(solvers, m)?)?;
     m.add_function(wrap_pyfunction!(_version, m)?)?;