pub struct PyBlockInstance { /* private fields */ }Expand description
One block instance: its own Python namespace (a fresh module exec’d from the cached source),
its own state object (start()’s own return value), and the specific function handles this
instance’s own contract (plain or xc) needs.
Implementations§
Source§impl PyBlockInstance
impl PyBlockInstance
Sourcepub fn call(
&mut self,
t: f64,
dt: f64,
inputs: &[PyInput<'_>],
out_len: usize,
) -> Result<Vec<f64>, PyBlockError>
pub fn call( &mut self, t: f64, dt: f64, inputs: &[PyInput<'_>], out_len: usize, ) -> Result<Vec<f64>, PyBlockError>
Calls output(state, t, dt, inputs), returning out_len values (a single-element
Vec for a scalar return, or as many elements as the Python function’s own returned
tuple/list has).
§Panics
If this instance was created via PyBlockRegistry::instantiate_xc (no output
function resolved) – unreachable in practice, since dae-runtime only ever calls this
on an instance created via the plain PyBlockRegistry::instantiate.
Sourcepub fn call_xc(
&mut self,
t: f64,
dt: f64,
inputs: &[PyInput<'_>],
xc: &[f64],
out_len: usize,
) -> Result<Vec<f64>, PyBlockError>
pub fn call_xc( &mut self, t: f64, dt: f64, inputs: &[PyInput<'_>], xc: &[f64], out_len: usize, ) -> Result<Vec<f64>, PyBlockError>
Calls output_xc(state, t, dt, inputs, xc).
§Panics
If this instance doesn’t have an output_xc function resolved – unreachable in
practice, since PyBlockRegistry::instantiate_xc already requires it up front.
Sourcepub fn update(
&mut self,
t: f64,
dt: f64,
inputs: &[PyInput<'_>],
) -> Result<(), PyBlockError>
pub fn update( &mut self, t: f64, dt: f64, inputs: &[PyInput<'_>], ) -> Result<(), PyBlockError>
Calls update(state, t, dt, inputs) – a no-op if this instance’s .py file didn’t
define update (see the module doc comment, “The optional discrete-state update
function”). Unlike Self::call/Self::call_xc, genuinely optional for both
contracts, so there’s no panic path: call it every step it’s due exactly like output,
and it simply does nothing if the author never wrote one. For an instance created via
PyBlockRegistry::instantiate_xc, use Self::update_xc instead (extra xc
argument, matching output/output_xc’s own split).
Sourcepub fn update_xc(
&mut self,
t: f64,
dt: f64,
inputs: &[PyInput<'_>],
xc: &[f64],
) -> Result<(), PyBlockError>
pub fn update_xc( &mut self, t: f64, dt: f64, inputs: &[PyInput<'_>], xc: &[f64], ) -> Result<(), PyBlockError>
The xc-aware counterpart to Self::update – calls update(state, t, dt, inputs, xc), a no-op if update wasn’t defined. xc should be this step’s own already-
integrated continuous state, the same value passed to Self::call_xc.
Sourcepub fn supports_next_sample_hit(&self) -> bool
pub fn supports_next_sample_hit(&self) -> bool
Whether this instance’s .py file defined next_sample_hit — check this once, up
front, when this block’s netlist line declares ts=variable (see the module doc
comment, “The optional block-controlled sample time”) and reject the netlist with a
clear error if not, before ever calling Self::next_sample_hit/Self::next_sample_hit_xc.
Sourcepub fn next_sample_hit(
&self,
t: f64,
dt: f64,
inputs: &[PyInput<'_>],
) -> Result<f64, PyBlockError>
pub fn next_sample_hit( &self, t: f64, dt: f64, inputs: &[PyInput<'_>], ) -> Result<f64, PyBlockError>
Calls next_sample_hit(state, t, dt, inputs), returning the number of seconds
(relative to this call) until this block should next be executed.
§Panics
If this instance’s .py file doesn’t define next_sample_hit — unreachable in
practice, since a caller is expected to check Self::supports_next_sample_hit once,
up front, before ever using ts=variable for this block at all.
Sourcepub fn next_sample_hit_xc(
&self,
t: f64,
dt: f64,
inputs: &[PyInput<'_>],
xc: &[f64],
) -> Result<f64, PyBlockError>
pub fn next_sample_hit_xc( &self, t: f64, dt: f64, inputs: &[PyInput<'_>], xc: &[f64], ) -> Result<f64, PyBlockError>
The xc-aware counterpart to Self::next_sample_hit – calls next_sample_hit(state, t, dt, inputs, xc).
§Panics
Same as Self::next_sample_hit.
Sourcepub fn derivative(
&self,
t: f64,
inputs: &[PyInput<'_>],
xc: &[f64],
) -> Result<Vec<f64>, PyBlockError>
pub fn derivative( &self, t: f64, inputs: &[PyInput<'_>], xc: &[f64], ) -> Result<Vec<f64>, PyBlockError>
Evaluates derivative(state, t, inputs, xc) once: given the current continuous-state
vector xc and this step’s already-resolved inputs, returns dxc/dt. Must not mutate
state (documented, not enforced, same as cscript’s equivalent contract).
§Panics
If this instance doesn’t have a derivative function resolved – unreachable in
practice, since PyBlockRegistry::instantiate_xc already requires it up front.
Sourcepub fn rk4_step_xc(
&self,
xc: &[f64],
t: f64,
inputs: &[PyInput<'_>],
dt: f64,
) -> Result<Vec<f64>, PyBlockError>
pub fn rk4_step_xc( &self, xc: &[f64], t: f64, inputs: &[PyInput<'_>], dt: f64, ) -> Result<Vec<f64>, PyBlockError>
RK4-integrates xc forward by dt, holding t/inputs fixed across all four stages –
the same zero-order-hold convention cscript_ffi::CScriptInstance::rk4_step_xc/
continuous_blocks::StateSpace::rk4_step both use for every other dynamic block.
Sourcepub fn try_clone(&self) -> Result<PyBlockInstance, PyBlockError>
pub fn try_clone(&self) -> Result<PyBlockInstance, PyBlockError>
A real, independent deep copy of this instance’s state via Python’s own generic
copy.deepcopy – no author opt-in required, unlike cscript_clone (see the module doc
comment). Err if the state genuinely can’t be deep-copied (e.g. an open file handle),
a normal Python exception, not a panic.
Sourcepub fn pickle_state(&self) -> Result<Vec<u8>, PyBlockError>
pub fn pickle_state(&self) -> Result<Vec<u8>, PyBlockError>
This instance’s state object as pickle bytes – the checkpoint counterpart of
Self::try_clone, same no-author-opt-in reasoning: anything copy.deepcopy accepts is
almost always picklable, and the exceptions (an open handle, a lambda held in state)
surface as an ordinary Python exception naming this block’s file, never a panic. The
module’s functions are not serialized – a resumed run re-executes the block’s own
.py file and only swaps the state object back in (see Self::restore_state).
Sourcepub fn restore_state(&mut self, bytes: &[u8]) -> Result<(), PyBlockError>
pub fn restore_state(&mut self, bytes: &[u8]) -> Result<(), PyBlockError>
Replaces this instance’s state object with the unpickled bytes – the load half of
Self::pickle_state. The instance itself (its module, its functions) is the one the
netlist built; only the state it carries changes.
Trait Implementations§
Source§impl Clone for PyBlockInstance
impl Clone for PyBlockInstance
Source§fn clone(&self) -> Self
fn clone(&self) -> Self
§Panics
If copy.deepcopy itself fails on this instance’s own state – see Self::try_clone
for the non-panicking form.
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more