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};