Skip to main content

pyblock_ffi/
lib.rs

1//! Embeds a Python interpreter (PyO3's `auto-initialize` feature) and calls user-supplied
2//! Python functions once per resolved block-graph step -- the Python-hosted counterpart to
3//! `cscript_ffi`'s dynamically-linked C blocks. See `general-simulator`'s own
4//! `book/dev-guide/src/python-blocks.md` for the full design and the measurements behind it;
5//! this module doc comment covers the Python-side contract only.
6//!
7//! ## The Python-side contract
8//!
9//! A block's `.py` file must define:
10//!
11//! ```python
12//! def start():
13//!     # Called once, when this block instance is created. Return any Python object (a dict, a
14//!     # plain class instance, ...) as this instance's own persistent state, or None. Put every
15//!     # import, every precomputed table, every one-time-expensive thing here -- never in
16//!     # output(). See the module doc comment's own measurements for why this matters.
17//!     ...
18//!
19//! def output(state, t, dt, inputs):
20//!     # Called once per resolved step (or once per sample period under ts=, mirroring
21//!     # cscript's own zero-order-hold convention). `inputs` is a list, one entry per declared
22//!     # `inputs=` signal -- a float for a scalar signal, a numpy.ndarray for a vector one
23//!     # (never flattened into one array the way cscript's C `in[]` has to be -- Python can
24//!     # keep each declared input's own shape). Return a single float, or a tuple/list of
25//!     # floats matching this block's own declared `outputs=` count (deliberately scalar-only
26//!     # outputs -- see the design doc).
27//!     ...
28//! ```
29//!
30//! ## The optional continuous-state (`xc`) contract
31//!
32//! A block declaring `xc_count > 0` exports `derivative`/`output_xc` *instead of* `output` --
33//! the exact same split `cscript`'s own `xc` contract uses, for the same reason (a state the
34//! *solver* numerically integrates, not the block's own hand-rolled update):
35//!
36//! ```python
37//! def derivative(state, t, inputs, xc):
38//!     # xc: numpy.ndarray, this RK4 stage's own candidate continuous-state vector. Must not
39//!     # mutate `state` -- called up to four times per accepted step. Return dxc/dt,
40//!     # array-like, same length as xc.
41//!     ...
42//!
43//! def output_xc(state, t, dt, inputs, xc):
44//!     # xc: numpy.ndarray, this step's own already-integrated continuous state. May still
45//!     # mutate `state` for its own discrete bookkeeping, exactly like output() can.
46//!     ...
47//! ```
48//!
49//! ## The optional discrete-state update function
50//!
51//! `output`/`output_xc` are permitted to mutate `state` themselves (documented above) -- fine
52//! for the common case, but it conflates computing this step's output with committing state
53//! forward to the next step. Some block-diagram tools' own code-block feature keeps these
54//! deliberately separate (an output function expected to be side-effect-free, plus a dedicated
55//! update function that's the only place discrete state actually advances) -- `pyblock` now
56//! offers the same split, as an **entirely optional** function, mirroring `cscript`'s own
57//! `cscript_update`:
58//!
59//! ```python
60//! def update(state, t, dt, inputs):
61//!     # Optional. Called once per resolved (or per-sample-period, under ts=) step, immediately
62//!     # after output(). The dedicated place to commit `state`'s own discrete bookkeeping
63//!     # forward to the next step, instead of doing it inside output() itself. If this function
64//!     # is absent, a pyblock is expected to keep updating `state` directly inside output(),
65//!     # exactly as before this function existed.
66//!     ...
67//!
68//! # For a block declaring xc_count > 0, update() additionally receives this step's own
69//! # already-integrated continuous state, mirroring output_xc's own extra parameter:
70//! def update(state, t, dt, inputs, xc):
71//!     ...
72//! ```
73//!
74//! `update`'s own arity (four or five positional parameters) is inferred from which contract
75//! this instance was created under ([`PyBlockRegistry::instantiate`] vs.
76//! `instantiate_xc`) -- there is no separate `update_xc` name, the same one `update` function
77//! just receives one more argument under the `xc` contract, matching `output`/`output_xc`'s own
78//! naming split being about the *return* value (`y`) rather than the input shape here.
79//!
80//! ## The optional block-controlled sample time
81//!
82//! A block's own `ts=`/`freq=` fixes a period at netlist-parse time. Some blocks instead know
83//! their own *next* execution time only at runtime — `ts=variable` in the netlist selects this
84//! mode, mirroring `cscript`'s own `cscript_next_sample_hit`, and **requires** the `.py` file to
85//! define one more function (checked once, up front, by whichever caller resolves the netlist's
86//! own `ts=variable` request — this crate itself never enforces it, the same way it never
87//! enforces which of `output`/`output_xc` a plain vs. `xc`-contract instance needs):
88//!
89//! ```python
90//! def next_sample_hit(state, t, dt, inputs):        # plain contract
91//!     # Required when this block declares ts=variable (never called otherwise). Called
92//!     # immediately after output(). Returns the number of seconds, relative to this call
93//!     # (a duration, not an absolute time stamp — even though `t` itself is absolute, matching
94//!     # output's own signature, what this function *returns* is deliberately not), until this
95//!     # block should next be executed. Must return a value > 0.
96//!     ...
97//! def next_sample_hit(state, t, dt, inputs, xc):    # xc contract -- one extra argument
98//!     ...
99//! ```
100//!
101//! ## State, cloning, and per-instance isolation
102//!
103//! Each instance gets its own Python namespace (`PyModule::from_code` execs the cached source
104//! text fresh per instance), so two instances of the same `.py` file never share module-level
105//! state -- while still sharing the *process-wide* `sys.modules` cache, so `import numpy`
106//! genuinely only pays its real cost once per process, not once per instance. The registry
107//! caches each file's own *source text* (avoiding repeat disk reads across instances), not a
108//! separately-compiled code object -- `from_code` recompiles per instance, which is fast enough
109//! (well under a millisecond for a block-sized file) not to be worth a second cache layer.
110//!
111//! Cloning (needed only for [`PyBlockInstance::try_clone`], itself only needed under adaptive
112//! step-size control's own trial-and-discard retry loop) uses Python's own generic
113//! `copy.deepcopy` on the instance's state object -- unlike `cscript`, there is no author
114//! opt-in required and no "doesn't support clone" rejection path: `deepcopy` works on ordinary
115//! Python state automatically. A state object that genuinely can't be deep-copied (an open file
116//! handle) surfaces as an ordinary Python exception -> [`PyBlockError::Exception`], not a panic.
117
118use std::ffi::CString;
119use std::path::{Path, PathBuf};
120
121use pyo3::prelude::*;
122use pyo3::types::PyModule;
123
124#[derive(Debug, Clone, PartialEq)]
125pub enum PyBlockError {
126    Load {
127        path: PathBuf,
128        message: String,
129    },
130    MissingFunction {
131        path: PathBuf,
132        name: &'static str,
133        message: String,
134    },
135    Exception {
136        path: PathBuf,
137        function: &'static str,
138        message: String,
139    },
140}
141
142impl std::fmt::Display for PyBlockError {
143    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
144        match self {
145            PyBlockError::Load { path, message } => {
146                write!(
147                    f,
148                    "failed to load Python block {}: {message}",
149                    path.display()
150                )
151            }
152            PyBlockError::MissingFunction {
153                path,
154                name,
155                message,
156            } => write!(
157                f,
158                "Python block {} is missing required function `{name}`: {message}",
159                path.display()
160            ),
161            PyBlockError::Exception {
162                path,
163                function,
164                message,
165            } => write!(
166                f,
167                "Python block {} raised in `{function}`: {message}",
168                path.display()
169            ),
170        }
171    }
172}
173
174impl std::error::Error for PyBlockError {}
175
176/// One input value passed to a Python block's own `output`/`derivative` function -- a plain
177/// scalar or a fixed-length vector, converted to a Python `float`/`numpy.ndarray` respectively.
178/// Deliberately not `general_mna::block_graph::SignalValue` itself, to keep this crate free of
179/// a dependency on `general-mna` -- matching `cscript-ffi`'s own convention of taking plain
180/// `f64` slices and leaving any scalar/vector decision to the caller (`dae-runtime`).
181#[derive(Debug, Clone, Copy)]
182pub enum PyInput<'a> {
183    Scalar(f64),
184    Vector(&'a [f64]),
185}
186
187fn py_traceback(_py: Python<'_>, err: &PyErr) -> String {
188    err.to_string()
189}
190
191fn build_args<'py>(
192    py: Python<'py>,
193    inputs: &[PyInput],
194) -> PyResult<pyo3::Bound<'py, pyo3::types::PyList>> {
195    use numpy::PyArray1;
196    use pyo3::types::PyList;
197    let list = PyList::empty(py);
198    for input in inputs {
199        match input {
200            PyInput::Scalar(x) => list.append(*x)?,
201            PyInput::Vector(xs) => list.append(PyArray1::from_slice(py, xs))?,
202        }
203    }
204    Ok(list)
205}
206
207/// Extracts `output()`/`output_xc()`'s own return value: a bare `float` when the block
208/// declares exactly one output (the natural Python idiom -- `return x`, not `return [x]`), or a
209/// `tuple`/`list` of `float`s matching a multi-output block's own declared count.
210fn extract_outputs(result: pyo3::Bound<'_, PyAny>, out_len: usize) -> PyResult<Vec<f64>> {
211    if out_len <= 1 {
212        let v: f64 = result.extract()?;
213        return Ok(vec![v]);
214    }
215    extract_vector(result)
216}
217
218/// Extracts `derivative()`'s own return value: always array-like (`dxc/dt`, one entry per `xc`
219/// element), regardless of `xc`'s own length -- unlike [`extract_outputs`], a length-1
220/// continuous state is still a state *vector* conceptually, so `derivative()` never gets the
221/// bare-scalar shortcut (its own docstring says "array-like, same length as xc," not "a bare
222/// float when there's only one").
223fn extract_vector(result: pyo3::Bound<'_, PyAny>) -> PyResult<Vec<f64>> {
224    let seq = result.try_iter()?;
225    let mut out = Vec::new();
226    for item in seq {
227        out.push(item?.extract::<f64>()?);
228    }
229    Ok(out)
230}
231
232/// Caches each `.py` file's own source text by path -- a fresh [`PyBlockInstance`] execs it
233/// into its own new namespace, so multiple instances of the same file never share module-level
234/// state (see the module doc comment, "State, cloning, and per-instance isolation").
235#[derive(Default)]
236pub struct PyBlockRegistry {
237    sources: std::collections::BTreeMap<PathBuf, String>,
238}
239
240impl PyBlockRegistry {
241    pub fn new() -> Self {
242        Self::default()
243    }
244
245    fn load_source(&mut self, path: &Path) -> Result<String, PyBlockError> {
246        if let Some(source) = self.sources.get(path) {
247            return Ok(source.clone());
248        }
249        let source = std::fs::read_to_string(path).map_err(|e| PyBlockError::Load {
250            path: path.to_path_buf(),
251            message: e.to_string(),
252        })?;
253        self.sources.insert(path.to_path_buf(), source.clone());
254        Ok(source)
255    }
256
257    /// The plain contract: requires `start`/`output`, for a block with `xc_count == 0`.
258    pub fn instantiate(&mut self, path: &Path) -> Result<PyBlockInstance, PyBlockError> {
259        let source = self.load_source(path)?;
260        PyBlockInstance::new(path, &source, false)
261    }
262
263    /// The continuous-state (`xc`) contract: requires `start`/`derivative`/`output_xc`, for a
264    /// block with `xc_count > 0`.
265    pub fn instantiate_xc(&mut self, path: &Path) -> Result<PyBlockInstance, PyBlockError> {
266        let source = self.load_source(path)?;
267        PyBlockInstance::new(path, &source, true)
268    }
269}
270
271/// One block instance: its own Python namespace (a fresh module exec'd from the cached source),
272/// its own state object (`start()`'s own return value), and the specific function handles this
273/// instance's own contract (plain or `xc`) needs.
274#[derive(Debug)]
275pub struct PyBlockInstance {
276    path: PathBuf,
277    source: String,
278    state: Py<PyAny>,
279    output_fn: Option<Py<PyAny>>,
280    derivative_fn: Option<Py<PyAny>>,
281    output_xc_fn: Option<Py<PyAny>>,
282    // Always optional regardless of contract (plain or xc) -- see the module doc comment, "The
283    // optional discrete-state update function." Never required by `new`.
284    update_fn: Option<Py<PyAny>>,
285    // Optional here too, but *required* when this block's netlist line declares `ts=variable`
286    // -- that requirement is checked by `dae-runtime`, not this crate. See the module doc
287    // comment, "The optional block-controlled sample time."
288    next_sample_hit_fn: Option<Py<PyAny>>,
289}
290
291impl PyBlockInstance {
292    fn new(path: &Path, source: &str, want_xc: bool) -> Result<Self, PyBlockError> {
293        Python::attach(|py| {
294            let module = exec_fresh_module(py, path, source).map_err(|e| PyBlockError::Load {
295                path: path.to_path_buf(),
296                message: py_traceback(py, &e),
297            })?;
298
299            let get = |name: &'static str| -> Option<Py<PyAny>> {
300                module.getattr(name).ok().map(|f| f.unbind())
301            };
302
303            let start_fn = get("start").ok_or_else(|| PyBlockError::MissingFunction {
304                path: path.to_path_buf(),
305                name: "start",
306                message: "not found".to_string(),
307            })?;
308            let output_fn = get("output");
309            let derivative_fn = get("derivative");
310            let output_xc_fn = get("output_xc");
311            let update_fn = get("update");
312            let next_sample_hit_fn = get("next_sample_hit");
313
314            if want_xc {
315                if derivative_fn.is_none() {
316                    return Err(PyBlockError::MissingFunction {
317                        path: path.to_path_buf(),
318                        name: "derivative",
319                        message: "required because this block declares xc_count > 0".to_string(),
320                    });
321                }
322                if output_xc_fn.is_none() {
323                    return Err(PyBlockError::MissingFunction {
324                        path: path.to_path_buf(),
325                        name: "output_xc",
326                        message: "required because this block declares xc_count > 0".to_string(),
327                    });
328                }
329            } else if output_fn.is_none() {
330                return Err(PyBlockError::MissingFunction {
331                    path: path.to_path_buf(),
332                    name: "output",
333                    message: "not found (or this block only implements the xc contract -- see \
334                              PyBlockRegistry::instantiate_xc)"
335                        .to_string(),
336                });
337            }
338
339            let state = start_fn
340                .bind(py)
341                .call0()
342                .map_err(|e| PyBlockError::Exception {
343                    path: path.to_path_buf(),
344                    function: "start",
345                    message: py_traceback(py, &e),
346                })?
347                .unbind();
348
349            Ok(PyBlockInstance {
350                path: path.to_path_buf(),
351                source: source.to_string(),
352                state,
353                output_fn,
354                derivative_fn,
355                output_xc_fn,
356                update_fn,
357                next_sample_hit_fn,
358            })
359        })
360    }
361
362    /// Calls `output(state, t, dt, inputs)`, returning `out_len` values (a single-element
363    /// `Vec` for a scalar return, or as many elements as the Python function's own returned
364    /// tuple/list has).
365    ///
366    /// # Panics
367    /// If this instance was created via [`PyBlockRegistry::instantiate_xc`] (no `output`
368    /// function resolved) -- unreachable in practice, since `dae-runtime` only ever calls this
369    /// on an instance created via the plain [`PyBlockRegistry::instantiate`].
370    pub fn call(
371        &mut self,
372        t: f64,
373        dt: f64,
374        inputs: &[PyInput],
375        out_len: usize,
376    ) -> Result<Vec<f64>, PyBlockError> {
377        if self.output_fn.is_none() {
378            panic!(
379                "call requires an instance created via PyBlockRegistry::instantiate (which \
380                 already requires `output` up front -- this should be unreachable)"
381            );
382        }
383        Python::attach(|py| {
384            let output_fn = self.output_fn.as_ref().unwrap().clone_ref(py);
385            let args = build_args(py, inputs).map_err(|e| self.exception(py, "output", e))?;
386            let result = output_fn
387                .bind(py)
388                .call1((self.state.bind(py), t, dt, args))
389                .map_err(|e| self.exception(py, "output", e))?;
390            extract_outputs(result, out_len).map_err(|e| self.exception(py, "output", e))
391        })
392    }
393
394    /// Calls `output_xc(state, t, dt, inputs, xc)`.
395    ///
396    /// # Panics
397    /// If this instance doesn't have an `output_xc` function resolved -- unreachable in
398    /// practice, since [`PyBlockRegistry::instantiate_xc`] already requires it up front.
399    pub fn call_xc(
400        &mut self,
401        t: f64,
402        dt: f64,
403        inputs: &[PyInput],
404        xc: &[f64],
405        out_len: usize,
406    ) -> Result<Vec<f64>, PyBlockError> {
407        if self.output_xc_fn.is_none() {
408            panic!(
409                "call_xc requires an instance created via PyBlockRegistry::instantiate_xc \
410                 (which already requires `output_xc` up front -- this should be unreachable)"
411            );
412        }
413        Python::attach(|py| {
414            let output_xc_fn = self.output_xc_fn.as_ref().unwrap().clone_ref(py);
415            let args = build_args(py, inputs).map_err(|e| self.exception(py, "output_xc", e))?;
416            let xc_arr = numpy::PyArray1::from_slice(py, xc);
417            let result = output_xc_fn
418                .bind(py)
419                .call1((self.state.bind(py), t, dt, args, xc_arr))
420                .map_err(|e| self.exception(py, "output_xc", e))?;
421            extract_outputs(result, out_len).map_err(|e| self.exception(py, "output_xc", e))
422        })
423    }
424
425    /// Calls `update(state, t, dt, inputs)` -- a no-op if this instance's `.py` file didn't
426    /// define `update` (see the module doc comment, "The optional discrete-state update
427    /// function"). Unlike [`Self::call`]/[`Self::call_xc`], genuinely optional for both
428    /// contracts, so there's no panic path: call it every step it's due exactly like output,
429    /// and it simply does nothing if the author never wrote one. For an instance created via
430    /// [`PyBlockRegistry::instantiate_xc`], use [`Self::update_xc`] instead (extra `xc`
431    /// argument, matching `output`/`output_xc`'s own split).
432    pub fn update(&mut self, t: f64, dt: f64, inputs: &[PyInput]) -> Result<(), PyBlockError> {
433        if self.update_fn.is_none() {
434            return Ok(());
435        }
436        Python::attach(|py| {
437            let update_fn = self.update_fn.as_ref().unwrap().clone_ref(py);
438            let args = build_args(py, inputs).map_err(|e| self.exception(py, "update", e))?;
439            update_fn
440                .bind(py)
441                .call1((self.state.bind(py), t, dt, args))
442                .map_err(|e| self.exception(py, "update", e))?;
443            Ok(())
444        })
445    }
446
447    /// The `xc`-aware counterpart to [`Self::update`] -- calls `update(state, t, dt, inputs,
448    /// xc)`, a no-op if `update` wasn't defined. `xc` should be this step's own already-
449    /// integrated continuous state, the same value passed to [`Self::call_xc`].
450    pub fn update_xc(
451        &mut self,
452        t: f64,
453        dt: f64,
454        inputs: &[PyInput],
455        xc: &[f64],
456    ) -> Result<(), PyBlockError> {
457        if self.update_fn.is_none() {
458            return Ok(());
459        }
460        Python::attach(|py| {
461            let update_fn = self.update_fn.as_ref().unwrap().clone_ref(py);
462            let args = build_args(py, inputs).map_err(|e| self.exception(py, "update", e))?;
463            let xc_arr = numpy::PyArray1::from_slice(py, xc);
464            update_fn
465                .bind(py)
466                .call1((self.state.bind(py), t, dt, args, xc_arr))
467                .map_err(|e| self.exception(py, "update", e))?;
468            Ok(())
469        })
470    }
471
472    /// Whether this instance's `.py` file defined `next_sample_hit` — check this once, up
473    /// front, when this block's netlist line declares `ts=variable` (see the module doc
474    /// comment, "The optional block-controlled sample time") and reject the netlist with a
475    /// clear error if not, before ever calling [`Self::next_sample_hit`]/[`Self::next_sample_hit_xc`].
476    pub fn supports_next_sample_hit(&self) -> bool {
477        self.next_sample_hit_fn.is_some()
478    }
479
480    /// Calls `next_sample_hit(state, t, dt, inputs)`, returning the number of seconds
481    /// (relative to this call) until this block should next be executed.
482    ///
483    /// # Panics
484    /// If this instance's `.py` file doesn't define `next_sample_hit` — unreachable in
485    /// practice, since a caller is expected to check [`Self::supports_next_sample_hit`] once,
486    /// up front, before ever using `ts=variable` for this block at all.
487    pub fn next_sample_hit(
488        &self,
489        t: f64,
490        dt: f64,
491        inputs: &[PyInput],
492    ) -> Result<f64, PyBlockError> {
493        if self.next_sample_hit_fn.is_none() {
494            panic!(
495                "next_sample_hit requires a .py file defining next_sample_hit (required for \
496                 ts=variable — this should be unreachable, since that's checked up front)"
497            );
498        }
499        Python::attach(|py| {
500            let f = self.next_sample_hit_fn.as_ref().unwrap().clone_ref(py);
501            let args =
502                build_args(py, inputs).map_err(|e| self.exception(py, "next_sample_hit", e))?;
503            let result = f
504                .bind(py)
505                .call1((self.state.bind(py), t, dt, args))
506                .map_err(|e| self.exception(py, "next_sample_hit", e))?;
507            result
508                .extract::<f64>()
509                .map_err(|e| self.exception(py, "next_sample_hit", e))
510        })
511    }
512
513    /// The `xc`-aware counterpart to [`Self::next_sample_hit`] -- calls `next_sample_hit(state,
514    /// t, dt, inputs, xc)`.
515    ///
516    /// # Panics
517    /// Same as [`Self::next_sample_hit`].
518    pub fn next_sample_hit_xc(
519        &self,
520        t: f64,
521        dt: f64,
522        inputs: &[PyInput],
523        xc: &[f64],
524    ) -> Result<f64, PyBlockError> {
525        if self.next_sample_hit_fn.is_none() {
526            panic!(
527                "next_sample_hit_xc requires a .py file defining next_sample_hit (required for \
528                 ts=variable — this should be unreachable, since that's checked up front)"
529            );
530        }
531        Python::attach(|py| {
532            let f = self.next_sample_hit_fn.as_ref().unwrap().clone_ref(py);
533            let args =
534                build_args(py, inputs).map_err(|e| self.exception(py, "next_sample_hit", e))?;
535            let xc_arr = numpy::PyArray1::from_slice(py, xc);
536            let result = f
537                .bind(py)
538                .call1((self.state.bind(py), t, dt, args, xc_arr))
539                .map_err(|e| self.exception(py, "next_sample_hit", e))?;
540            result
541                .extract::<f64>()
542                .map_err(|e| self.exception(py, "next_sample_hit", e))
543        })
544    }
545
546    /// Evaluates `derivative(state, t, inputs, xc)` once: given the current continuous-state
547    /// vector `xc` and this step's already-resolved inputs, returns `dxc/dt`. Must not mutate
548    /// `state` (documented, not enforced, same as `cscript`'s equivalent contract).
549    ///
550    /// # Panics
551    /// If this instance doesn't have a `derivative` function resolved -- unreachable in
552    /// practice, since [`PyBlockRegistry::instantiate_xc`] already requires it up front.
553    pub fn derivative(
554        &self,
555        t: f64,
556        inputs: &[PyInput],
557        xc: &[f64],
558    ) -> Result<Vec<f64>, PyBlockError> {
559        if self.derivative_fn.is_none() {
560            panic!(
561                "derivative requires an instance created via PyBlockRegistry::instantiate_xc \
562                 (which already requires `derivative` up front -- this should be unreachable)"
563            );
564        }
565        Python::attach(|py| {
566            let derivative_fn = self.derivative_fn.as_ref().unwrap().clone_ref(py);
567            let args = build_args(py, inputs).map_err(|e| self.exception(py, "derivative", e))?;
568            let xc_arr = numpy::PyArray1::from_slice(py, xc);
569            let result = derivative_fn
570                .bind(py)
571                .call1((self.state.bind(py), t, args, xc_arr))
572                .map_err(|e| self.exception(py, "derivative", e))?;
573            extract_vector(result).map_err(|e| self.exception(py, "derivative", e))
574        })
575    }
576
577    /// RK4-integrates `xc` forward by `dt`, holding `t`/`inputs` fixed across all four stages --
578    /// the same zero-order-hold convention `cscript_ffi::CScriptInstance::rk4_step_xc`/
579    /// `continuous_blocks::StateSpace::rk4_step` both use for every other dynamic block.
580    pub fn rk4_step_xc(
581        &self,
582        xc: &[f64],
583        t: f64,
584        inputs: &[PyInput],
585        dt: f64,
586    ) -> Result<Vec<f64>, PyBlockError> {
587        let add = |a: &[f64], b: &[f64], scale: f64| -> Vec<f64> {
588            a.iter().zip(b).map(|(ai, bi)| ai + scale * bi).collect()
589        };
590        let k1 = self.derivative(t, inputs, xc)?;
591        let k2 = self.derivative(t, inputs, &add(xc, &k1, dt / 2.0))?;
592        let k3 = self.derivative(t, inputs, &add(xc, &k2, dt / 2.0))?;
593        let k4 = self.derivative(t, inputs, &add(xc, &k3, dt))?;
594        Ok((0..xc.len())
595            .map(|i| xc[i] + (dt / 6.0) * (k1[i] + 2.0 * k2[i] + 2.0 * k3[i] + k4[i]))
596            .collect())
597    }
598
599    /// A real, independent deep copy of this instance's state via Python's own generic
600    /// `copy.deepcopy` -- no author opt-in required, unlike `cscript_clone` (see the module doc
601    /// comment). `Err` if the state genuinely can't be deep-copied (e.g. an open file handle),
602    /// a normal Python exception, not a panic.
603    pub fn try_clone(&self) -> Result<PyBlockInstance, PyBlockError> {
604        Python::attach(|py| {
605            let module = exec_fresh_module(py, &self.path, &self.source).map_err(|e| {
606                PyBlockError::Load {
607                    path: self.path.clone(),
608                    message: py_traceback(py, &e),
609                }
610            })?;
611            let get = |name: &'static str| -> Option<Py<PyAny>> {
612                module.getattr(name).ok().map(|f| f.unbind())
613            };
614            let copy_mod = py
615                .import("copy")
616                .map_err(|e| self.exception(py, "try_clone", e))?;
617            let cloned_state = copy_mod
618                .call_method1("deepcopy", (self.state.bind(py),))
619                .map_err(|e| self.exception(py, "try_clone", e))?
620                .unbind();
621            Ok(PyBlockInstance {
622                path: self.path.clone(),
623                source: self.source.clone(),
624                state: cloned_state,
625                output_fn: get("output"),
626                derivative_fn: get("derivative"),
627                output_xc_fn: get("output_xc"),
628                update_fn: get("update"),
629                next_sample_hit_fn: get("next_sample_hit"),
630            })
631        })
632    }
633
634    /// This instance's state object as `pickle` bytes -- the checkpoint counterpart of
635    /// [`Self::try_clone`], same no-author-opt-in reasoning: anything `copy.deepcopy` accepts is
636    /// almost always picklable, and the exceptions (an open handle, a lambda held in state)
637    /// surface as an ordinary Python exception naming this block's file, never a panic. The
638    /// module's functions are *not* serialized -- a resumed run re-executes the block's own
639    /// `.py` file and only swaps the state object back in (see [`Self::restore_state`]).
640    pub fn pickle_state(&self) -> Result<Vec<u8>, PyBlockError> {
641        Python::attach(|py| {
642            let pickle = py
643                .import("pickle")
644                .map_err(|e| self.exception(py, "pickle_state", e))?;
645            let bytes = pickle
646                .call_method1("dumps", (self.state.bind(py),))
647                .map_err(|e| self.exception(py, "pickle_state", e))?;
648            bytes
649                .extract::<Vec<u8>>()
650                .map_err(|e| self.exception(py, "pickle_state", e))
651        })
652    }
653
654    /// Replaces this instance's state object with the unpickled `bytes` -- the load half of
655    /// [`Self::pickle_state`]. The instance itself (its module, its functions) is the one the
656    /// netlist built; only the state it carries changes.
657    pub fn restore_state(&mut self, bytes: &[u8]) -> Result<(), PyBlockError> {
658        Python::attach(|py| {
659            let pickle = py
660                .import("pickle")
661                .map_err(|e| self.exception(py, "restore_state", e))?;
662            let state = pickle
663                .call_method1("loads", (pyo3::types::PyBytes::new(py, bytes),))
664                .map_err(|e| self.exception(py, "restore_state", e))?;
665            self.state = state.unbind();
666            Ok(())
667        })
668    }
669
670    fn exception(&self, py: Python<'_>, function: &'static str, err: PyErr) -> PyBlockError {
671        PyBlockError::Exception {
672            path: self.path.clone(),
673            function,
674            message: py_traceback(py, &err),
675        }
676    }
677}
678
679impl Clone for PyBlockInstance {
680    /// # Panics
681    /// If `copy.deepcopy` itself fails on this instance's own state -- see [`Self::try_clone`]
682    /// for the non-panicking form.
683    fn clone(&self) -> Self {
684        self.try_clone()
685            .unwrap_or_else(|e| panic!("cannot clone this PyBlockInstance: {e}"))
686    }
687}
688
689fn exec_fresh_module<'py>(
690    py: Python<'py>,
691    path: &Path,
692    source: &str,
693) -> PyResult<pyo3::Bound<'py, PyModule>> {
694    let code = CString::new(source)?;
695    let filename = CString::new(path.to_string_lossy().as_bytes())?;
696    let module_name = CString::new(
697        path.file_stem()
698            .map(|s| s.to_string_lossy().to_string())
699            .unwrap_or_else(|| "pyblock".to_string()),
700    )?;
701    PyModule::from_code(py, &code, &filename, &module_name)
702}
703
704/// A genuinely separate, additive contract from [`PyBlockInstance`] above — never modifies or
705/// reuses its own lifecycle (no `start`, no `state`, no `t`/`dt`), for a plain, pure, stateless
706/// Python function: the closest equivalent to a named-input/named-output function block in
707/// other block-diagram tools (`function [Y1, Y2] = f(X1, X2) ... end`-style):
708///
709/// ```python
710/// def compute_gate_pattern(phase_degrees):
711///     phase = phase_degrees % 360
712///     if phase == 0:
713///         return 9, 6
714///     elif 0 < phase < 180:
715///         return 2066, 1057
716///     # ...
717///     return AQCTLA, AQCTLB
718/// ```
719///
720/// [`PyFunctionRegistry::instantiate`] resolves whichever function name is given and calls it
721/// **positionally** (`f(*inputs)`, one declared `inputs=` entry per positional argument — never
722/// bundled into one list the way [`PyBlockInstance::call`]'s own `inputs` parameter is), so a
723/// function with N named parameters, one with `*args`, or any mix, all work unchanged: there is
724/// no parameter-*name* matching against the netlist's own signal names, only positional order,
725/// the same way every other block in this graph maps `inputs=A,B,C` to its own computation by
726/// position. A single return value or a tuple/list of them (multiple outputs) both work, via
727/// the same [`extract_outputs`] this module's other contract already uses.
728///
729/// Being genuinely stateless, [`PyFunctionInstance`] is always cheaply, trivially cloneable
730/// (just `clone_ref`ing the function handle) — unlike [`PyBlockInstance::try_clone`], there is
731/// no `copy.deepcopy` call and no way for it to fail.
732mod pure_function {
733    use std::path::{Path, PathBuf};
734
735    use pyo3::prelude::*;
736    use pyo3::types::PyTuple;
737
738    use super::{exec_fresh_module, extract_outputs, py_traceback, PyBlockError, PyInput};
739
740    // Deliberately not shared with `super::build_args` (which builds a `PyList` bundling every
741    // input into *one* list argument, for `PyBlockInstance`'s own `output(state, t, dt,
742    // inputs)` contract) -- this module never touches that function or its behavior, only
743    // reads the same `PyInput` values a completely independent way (one positional argument
744    // per input, via a `PyTuple`).
745    fn build_positional_args<'py>(
746        py: Python<'py>,
747        inputs: &[PyInput],
748    ) -> PyResult<pyo3::Bound<'py, PyTuple>> {
749        use numpy::PyArray1;
750        let mut items: Vec<Py<PyAny>> = Vec::with_capacity(inputs.len());
751        for input in inputs {
752            let obj: Py<PyAny> = match input {
753                PyInput::Scalar(x) => x.into_pyobject(py)?.into_any().unbind(),
754                PyInput::Vector(xs) => PyArray1::from_slice(py, xs).into_any().unbind(),
755            };
756            items.push(obj);
757        }
758        PyTuple::new(py, items)
759    }
760
761    /// Caches each `.py` file's own source text by path, same convention as
762    /// [`super::PyBlockRegistry`] — a fresh [`PyFunctionInstance`] execs it into its own new
763    /// namespace per instance.
764    #[derive(Default)]
765    pub struct PyFunctionRegistry {
766        sources: std::collections::BTreeMap<PathBuf, String>,
767    }
768
769    impl PyFunctionRegistry {
770        pub fn new() -> Self {
771            Self::default()
772        }
773
774        fn load_source(&mut self, path: &Path) -> Result<String, PyBlockError> {
775            if let Some(source) = self.sources.get(path) {
776                return Ok(source.clone());
777            }
778            let source = std::fs::read_to_string(path).map_err(|e| PyBlockError::Load {
779                path: path.to_path_buf(),
780                message: e.to_string(),
781            })?;
782            self.sources.insert(path.to_path_buf(), source.clone());
783            Ok(source)
784        }
785
786        /// Loads `path` if not already cached, resolves `function_name` as a callable, and
787        /// returns a fresh [`PyFunctionInstance`] — no `start()` call, no state at all.
788        pub fn instantiate(
789            &mut self,
790            path: &Path,
791            function_name: &str,
792        ) -> Result<PyFunctionInstance, PyBlockError> {
793            let source = self.load_source(path)?;
794            PyFunctionInstance::new(path, &source, function_name)
795        }
796    }
797
798    #[derive(Debug)]
799    pub struct PyFunctionInstance {
800        path: PathBuf,
801        function_name: String,
802        function: Py<PyAny>,
803    }
804
805    impl PyFunctionInstance {
806        fn new(path: &Path, source: &str, function_name: &str) -> Result<Self, PyBlockError> {
807            Python::attach(|py| {
808                let module =
809                    exec_fresh_module(py, path, source).map_err(|e| PyBlockError::Load {
810                        path: path.to_path_buf(),
811                        message: py_traceback(py, &e),
812                    })?;
813                let function = module
814                    .getattr(function_name)
815                    .map_err(|_| PyBlockError::MissingFunction {
816                        path: path.to_path_buf(),
817                        name: "function",
818                        message: format!("`{function_name}` not found"),
819                    })?
820                    .unbind();
821                Ok(PyFunctionInstance {
822                    path: path.to_path_buf(),
823                    function_name: function_name.to_string(),
824                    function,
825                })
826            })
827        }
828
829        /// Calls the function positionally with `inputs`, in declared order (`f(*inputs)`),
830        /// returning `out_len` values.
831        pub fn call(&self, inputs: &[PyInput], out_len: usize) -> Result<Vec<f64>, PyBlockError> {
832            Python::attach(|py| {
833                let args = build_positional_args(py, inputs).map_err(|e| self.exception(py, e))?;
834                let result = self
835                    .function
836                    .bind(py)
837                    .call1(args)
838                    .map_err(|e| self.exception(py, e))?;
839                extract_outputs(result, out_len).map_err(|e| self.exception(py, e))
840            })
841        }
842
843        fn exception(&self, py: Python<'_>, err: PyErr) -> PyBlockError {
844            PyBlockError::Exception {
845                path: self.path.clone(),
846                function: "call",
847                message: format!("in `{}`: {}", self.function_name, py_traceback(py, &err)),
848            }
849        }
850    }
851
852    impl Clone for PyFunctionInstance {
853        fn clone(&self) -> Self {
854            Python::attach(|py| PyFunctionInstance {
855                path: self.path.clone(),
856                function_name: self.function_name.clone(),
857                function: self.function.clone_ref(py),
858            })
859        }
860    }
861}
862pub use pure_function::{PyFunctionInstance, PyFunctionRegistry};