tsdynamics 3.0.0__tar.gz → 3.0.2__tar.gz

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

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

{tsdynamics-3.0.0 → tsdynamics-3.0.2}/crates/tsdyn-core/src/bridge.rs

@@ -28,9 +28,10 @@
 
 use tsdyn_engine::rng::SplitMix64;
 use tsdyn_engine::{
-    ensemble_final as engine_ensemble, integrate_dde_grid, integrate_grid, iterate_dense,
-    iterate_ensemble_final as engine_iterate_ensemble, sde_ensemble_final as engine_sde_ensemble,
-    sde_integrate_grid, DelaySlot, IntegrateConfig, IntegrateError, MapError, SdeConfig, SdeError,
+    ensemble_final as engine_ensemble, integrate_dde_grid, integrate_events, integrate_grid,
+    iterate_dense, iterate_ensemble_final as engine_iterate_ensemble,
+    sde_ensemble_final as engine_sde_ensemble, sde_integrate_grid, DelaySlot, EventDirection,
+    EventSpec, IntegrateConfig, IntegrateError, MapError, SdeConfig, SdeError,
 };
 use tsdyn_ir::{Evaluator, Tape};
 use tsdyn_jit::JitEvaluator;
@@ -950,6 +951,135 @@ pub fn sde_ensemble_final(
     Ok(result.states)
 }
 
+/// Map a Python-side direction code (`+1` / `-1` / `0`) to an [`EventDirection`].
+fn event_direction(direction: i32) -> Result<EventDirection, EngineError> {
+    match direction {
+        1 => Ok(EventDirection::Rising),
+        -1 => Ok(EventDirection::Falling),
+        0 => Ok(EventDirection::Either),
+        other => Err(EngineError::BadShape(format!(
+            "event direction must be +1 (rising), -1 (falling) or 0 (either), got {other}"
+        ))),
+    }
+}
+
+/// Integrate `[t0, t1]` and return every crossing of the event function
+/// `g(u, t) = 0` in `direction`, refined with the engine's O(h⁴) cubic-Hermite
+/// dense output (stream WS-CROSSKERNEL — wiring the previously dead
+/// [`tsdyn_engine::integrate_events`]).
+///
+/// `rhs` is the system right-hand side; `g` a single-output tape evaluated over
+/// the full state (`g.dim() == 1`, `g.n_param() <= rhs.n_param()`). `first_step`
+/// seeds the solver; with the fixed-step `rk4` it *is* the march step, so a caller
+/// that wants the Python `PoincareMap`'s dt-grid detection (no skipped crossings,
+/// answer-identical refinement) passes `method = "rk4"`, `first_step = dt`.
+///
+/// Returns `(times, states_flat, t_final, u_final, terminated)` — the `K` crossing
+/// times, the row-major `(K, dim)` crossing states, the time/state the run stopped
+/// at (so a caller can resume the next span exactly), and whether a terminal event
+/// stopped it. Divergence raises ([`EngineError::Diverged`]), preserving the
+/// "diverge loudly" contract of the per-`dt` Python path.
+#[allow(clippy::too_many_arguments, clippy::type_complexity)]
+pub fn integrate_events_dense(
+    rhs: Tape,
+    g: Tape,
+    ic: &[f64],
+    p: &[f64],
+    t0: f64,
+    t1: f64,
+    first_step: f64,
+    direction: i32,
+    terminal: bool,
+    method: &str,
+    rtol: f64,
+    atol: f64,
+    jit: bool,
+) -> Result<(Vec<f64>, Vec<f64>, f64, Vec<f64>, bool), EngineError> {
+    guard_continuous(&rhs)?;
+    check_inputs(&rhs, ic, p)?;
+    if let Some(&bad) = ic.iter().find(|x| !x.is_finite()) {
+        return Err(EngineError::BadShape(format!(
+            "initial state must be finite, found {bad}"
+        )));
+    }
+    let dim = rhs.dim();
+    if dim == 0 {
+        return Err(EngineError::BadShape(
+            "system dimension is zero (the tape has no outputs)".to_string(),
+        ));
+    }
+    // The event function is a single-output tape over the full state; it shares
+    // the system parameter vector (it may declare fewer and read the leading
+    // slice). `eval_event` in the engine asserts both, so reject violations here
+    // as a clean `ValueError` rather than a release-build panic.
+    if g.dim() != 1 {
+        return Err(EngineError::BadShape(format!(
+            "event function must have a single output, got {}",
+            g.dim()
+        )));
+    }
+    if g.n_state() > dim {
+        return Err(EngineError::BadShape(format!(
+            "event function reads {} state inputs but the system has dim = {dim}",
+            g.n_state()
+        )));
+    }
+    if g.n_param() > p.len() {
+        return Err(EngineError::BadShape(format!(
+            "event function declares {} parameters but the system has {}",
+            g.n_param(),
+            p.len()
+        )));
+    }
+    if !(t0.is_finite() && t1.is_finite()) {
+        return Err(EngineError::BadShape(format!(
+            "event integration span must be finite, got t0 = {t0}, t1 = {t1}"
+        )));
+    }
+    if t1 < t0 {
+        return Err(EngineError::BadShape(format!(
+            "integrate_events is forward only: need t1 >= t0, got t0 = {t0}, t1 = {t1}"
+        )));
+    }
+    // The engine asserts a finite, positive first step (a hard `assert!`, not a
+    // debug one) — turn a bad value into a clean error at the boundary.
+    if !(first_step.is_finite() && first_step > 0.0) {
+        return Err(EngineError::BadShape(format!(
+            "first step (the detection dt) must be finite and positive, got {first_step}"
+        )));
+    }
+    let dir = event_direction(direction)?;
+    let name = resolve_solver(method)?;
+    require_jacobian_if_needed(&rhs, name)?;
+
+    let rhs_ev = build_evaluator(rhs, jit)?;
+    let g_ev = build_evaluator(g, jit)?;
+    let mut solver = build_solver(name, rtol, atol);
+    let cfg = IntegrateConfig::new(first_step);
+
+    let spec = if terminal {
+        EventSpec::terminal(&*g_ev, dir)
+    } else {
+        EventSpec::new(&*g_ev, dir)
+    };
+    let outcome = integrate_events(&*rhs_ev, &mut *solver, &ic[..dim], p, t0, t1, &[spec], &cfg)
+        .map_err(|e| EngineError::Diverged(diverge_msg(&e)))?;
+
+    let mut times = Vec::with_capacity(outcome.hits.len());
+    let mut states = Vec::with_capacity(outcome.hits.len() * dim);
+    for hit in &outcome.hits {
+        times.push(hit.t);
+        states.extend_from_slice(&hit.u);
+    }
+    Ok((
+        times,
+        states,
+        outcome.t_final,
+        outcome.u_final,
+        outcome.terminated,
+    ))
+}
+
 /// Prefix the engine's diverge message so the Python `RuntimeError` reads clearly.
 fn diverge_msg(e: &IntegrateError) -> String {
     format!("integration diverged before reaching the final time: {e}")

{tsdynamics-3.0.0 → tsdynamics-3.0.2}/crates/tsdyn-core/src/lib.rs

@@ -591,6 +591,103 @@ fn integrate_sde_ensemble_final<'py>(
     PyArray1::from_vec(py, flat).reshape([n_ic, dim])
 }
 
+// ---------------------------------------------------------------------------
+// Event detection (two tapes: right-hand side + event function g)
+// ---------------------------------------------------------------------------
+
+/// Integrate `[t0, t1]` and return the crossings of the event function
+/// `g(u, t) = 0` in `direction` (`+1` rising / `-1` falling / `0` either),
+/// refined with the engine's O(h⁴) cubic-Hermite dense output.
+///
+/// The two tapes are passed back to back — first the right-hand side `f`, then the
+/// single-output event function `g` (`g`'s `outputs.len() == 1`; it reads the full
+/// state and may declare fewer parameters than the system, reading the leading
+/// slice). `first_step` seeds the solver; with the fixed-step `rk4` it *is* the
+/// detection step, so `method="rk4"`, `first_step=dt` reproduces the Python
+/// `PoincareMap` dt-grid march and its refinement (answer-identical). `terminal`
+/// stops the run at the first crossing. Divergence raises `RuntimeError`.
+///
+/// Returns `(times, states, t_final, u_final, terminated)`: the `(K,)` crossing
+/// times, the `(K, dim)` crossing states, the time and state the run stopped at
+/// (to resume the next span exactly), and whether a terminal event stopped it.
+#[pyfunction]
+#[allow(clippy::too_many_arguments, clippy::type_complexity)]
+fn integrate_events_dense<'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,
+    ops_g: PyReadonlyArray1<i32>,
+    a_g: PyReadonlyArray1<i32>,
+    b_g: PyReadonlyArray1<i32>,
+    imm_g: PyReadonlyArray1<f64>,
+    outputs_g: PyReadonlyArray1<i32>,
+    jac_outputs_g: PyReadonlyArray1<i32>,
+    n_state_g: usize,
+    n_param_g: usize,
+    ic: PyReadonlyArray1<f64>,
+    p: PyReadonlyArray1<f64>,
+    t0: f64,
+    t1: f64,
+    first_step: f64,
+    direction: i32,
+    terminal: bool,
+    method: String,
+    rtol: f64,
+    atol: f64,
+    jit: bool,
+) -> PyResult<(
+    Bound<'py, PyArray1<f64>>,
+    Bound<'py, PyArray2<f64>>,
+    f64,
+    Bound<'py, PyArray1<f64>>,
+    bool,
+)> {
+    let rhs = OwnedTape::copy_in(&ops, &a, &b, &imm, &outputs, &jac_outputs, n_state, n_param)?;
+    let g = OwnedTape::copy_in(
+        &ops_g,
+        &a_g,
+        &b_g,
+        &imm_g,
+        &outputs_g,
+        &jac_outputs_g,
+        n_state_g,
+        n_param_g,
+    )?;
+    let dim = rhs.dim();
+    let ic = vec_f64("ic", &ic)?;
+    let p = vec_f64("p", &p)?;
+    let (times, states, t_final, u_final, terminated) = py
+        .detach(|| {
+            bridge::integrate_events_dense(
+                rhs.build()?,
+                g.build()?,
+                &ic,
+                &p,
+                t0,
+                t1,
+                first_step,
+                direction,
+                terminal,
+                &method,
+                rtol,
+                atol,
+                jit,
+            )
+        })
+        .map_err(to_py_err)?;
+    let n_hits = times.len();
+    let times = PyArray1::from_vec(py, times);
+    let states = PyArray1::from_vec(py, states).reshape([n_hits, dim])?;
+    let u_final = PyArray1::from_vec(py, u_final);
+    Ok((times, states, t_final, u_final, terminated))
+}
+
 // ---------------------------------------------------------------------------
 // Introspection
 // ---------------------------------------------------------------------------
@@ -644,6 +741,7 @@ fn _rust(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(integrate_ensemble_final, m)?)?;
     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!(solvers, m)?)?;
     m.add_function(wrap_pyfunction!(_version, m)?)?;
     Ok(())

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

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "tsdynamics"
-version = "3.0.0"
+version = "3.0.2"
 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"

{tsdynamics-3.0.0 → tsdynamics-3.0.2}/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.0"
+__version__ = "3.0.2"
 
 # 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.0 → tsdynamics-3.0.2}/src/tsdynamics/analysis/__init__.py

@@ -177,6 +177,7 @@ __all__ = [
     "correlation_dimension",
     "correlation_sum",
     "dimension_spectrum",
+    "discover_plugins",
     "dispersion_entropy",
     "embed",
     "embedding_dimension",
@@ -250,3 +251,13 @@ def discover_plugins(*, strict: bool = False) -> list[str]:
 # analyses register themselves from their own subpackages (the analysis streams);
 # plugin failures are isolated inside `register_entry_points`.
 discover_plugins()
+
+
+def __dir__() -> list[str]:
+    """Expose only the curated public API (``__all__``) to ``dir()`` / autocomplete.
+
+    The capability subpackages (``basins``, ``chaos``, …) and plugin-wiring
+    helpers are re-exported flat or used internally; they stay importable but are
+    kept off the tab-completion surface so only the public quantifiers show.
+    """
+    return sorted(__all__)