Expand description
Embeds a Python interpreter (PyO3’s auto-initialize feature) and calls user-supplied
Python functions once per resolved block-graph step – the Python-hosted counterpart to
cscript_ffi’s dynamically-linked C blocks. See general-simulator’s own
book/dev-guide/src/python-blocks.md for the full design and the measurements behind it;
this module doc comment covers the Python-side contract only.
§The Python-side contract
A block’s .py file must define:
def start():
# Called once, when this block instance is created. Return any Python object (a dict, a
# plain class instance, ...) as this instance's own persistent state, or None. Put every
# import, every precomputed table, every one-time-expensive thing here -- never in
# output(). See the module doc comment's own measurements for why this matters.
...
def output(state, t, dt, inputs):
# Called once per resolved step (or once per sample period under ts=, mirroring
# cscript's own zero-order-hold convention). `inputs` is a list, one entry per declared
# `inputs=` signal -- a float for a scalar signal, a numpy.ndarray for a vector one
# (never flattened into one array the way cscript's C `in[]` has to be -- Python can
# keep each declared input's own shape). Return a single float, or a tuple/list of
# floats matching this block's own declared `outputs=` count (deliberately scalar-only
# outputs -- see the design doc).
...§The optional continuous-state (xc) contract
A block declaring xc_count > 0 exports derivative/output_xc instead of output –
the exact same split cscript’s own xc contract uses, for the same reason (a state the
solver numerically integrates, not the block’s own hand-rolled update):
def derivative(state, t, inputs, xc):
# xc: numpy.ndarray, this RK4 stage's own candidate continuous-state vector. Must not
# mutate `state` -- called up to four times per accepted step. Return dxc/dt,
# array-like, same length as xc.
...
def output_xc(state, t, dt, inputs, xc):
# xc: numpy.ndarray, this step's own already-integrated continuous state. May still
# mutate `state` for its own discrete bookkeeping, exactly like output() can.
...§The optional discrete-state update function
output/output_xc are permitted to mutate state themselves (documented above) – fine
for the common case, but it conflates computing this step’s output with committing state
forward to the next step. Some block-diagram tools’ own code-block feature keeps these
deliberately separate (an output function expected to be side-effect-free, plus a dedicated
update function that’s the only place discrete state actually advances) – pyblock now
offers the same split, as an entirely optional function, mirroring cscript’s own
cscript_update:
def update(state, t, dt, inputs):
# Optional. Called once per resolved (or per-sample-period, under ts=) step, immediately
# after output(). The dedicated place to commit `state`'s own discrete bookkeeping
# forward to the next step, instead of doing it inside output() itself. If this function
# is absent, a pyblock is expected to keep updating `state` directly inside output(),
# exactly as before this function existed.
...
# For a block declaring xc_count > 0, update() additionally receives this step's own
# already-integrated continuous state, mirroring output_xc's own extra parameter:
def update(state, t, dt, inputs, xc):
...update’s own arity (four or five positional parameters) is inferred from which contract
this instance was created under (PyBlockRegistry::instantiate vs.
instantiate_xc) – there is no separate update_xc name, the same one update function
just receives one more argument under the xc contract, matching output/output_xc’s own
naming split being about the return value (y) rather than the input shape here.
§The optional block-controlled sample time
A block’s own ts=/freq= fixes a period at netlist-parse time. Some blocks instead know
their own next execution time only at runtime — ts=variable in the netlist selects this
mode, mirroring cscript’s own cscript_next_sample_hit, and requires the .py file to
define one more function (checked once, up front, by whichever caller resolves the netlist’s
own ts=variable request — this crate itself never enforces it, the same way it never
enforces which of output/output_xc a plain vs. xc-contract instance needs):
def next_sample_hit(state, t, dt, inputs): # plain contract
# Required when this block declares ts=variable (never called otherwise). Called
# immediately after output(). Returns the number of seconds, relative to this call
# (a duration, not an absolute time stamp — even though `t` itself is absolute, matching
# output's own signature, what this function *returns* is deliberately not), until this
# block should next be executed. Must return a value > 0.
...
def next_sample_hit(state, t, dt, inputs, xc): # xc contract -- one extra argument
...§State, cloning, and per-instance isolation
Each instance gets its own Python namespace (PyModule::from_code execs the cached source
text fresh per instance), so two instances of the same .py file never share module-level
state – while still sharing the process-wide sys.modules cache, so import numpy
genuinely only pays its real cost once per process, not once per instance. The registry
caches each file’s own source text (avoiding repeat disk reads across instances), not a
separately-compiled code object – from_code recompiles per instance, which is fast enough
(well under a millisecond for a block-sized file) not to be worth a second cache layer.
Cloning (needed only for PyBlockInstance::try_clone, itself only needed under adaptive
step-size control’s own trial-and-discard retry loop) uses Python’s own generic
copy.deepcopy on the instance’s state object – unlike cscript, there is no author
opt-in required and no “doesn’t support clone” rejection path: deepcopy works on ordinary
Python state automatically. A state object that genuinely can’t be deep-copied (an open file
handle) surfaces as an ordinary Python exception -> PyBlockError::Exception, not a panic.
Structs§
- PyBlock
Instance - 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 orxc) needs. - PyBlock
Registry - Caches each
.pyfile’s own source text by path – a freshPyBlockInstanceexecs it into its own new namespace, so multiple instances of the same file never share module-level state (see the module doc comment, “State, cloning, and per-instance isolation”). - PyFunction
Instance - PyFunction
Registry - Caches each
.pyfile’s own source text by path, same convention assuper::PyBlockRegistry— a freshPyFunctionInstanceexecs it into its own new namespace per instance.
Enums§
- PyBlock
Error - PyInput
- One input value passed to a Python block’s own
output/derivativefunction – a plain scalar or a fixed-length vector, converted to a Pythonfloat/numpy.ndarrayrespectively. Deliberately notgeneral_mna::block_graph::SignalValueitself, to keep this crate free of a dependency ongeneral-mna– matchingcscript-ffi’s own convention of taking plainf64slices and leaving any scalar/vector decision to the caller (dae-runtime).