Skip to main content

Crate pyblock_ffi

Crate pyblock_ffi 

Source
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§

PyBlockInstance
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.
PyBlockRegistry
Caches each .py file’s own source text by path – a fresh PyBlockInstance execs 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”).
PyFunctionInstance
PyFunctionRegistry
Caches each .py file’s own source text by path, same convention as super::PyBlockRegistry — a fresh PyFunctionInstance execs it into its own new namespace per instance.

Enums§

PyBlockError
PyInput
One input value passed to a Python block’s own output/derivative function – a plain scalar or a fixed-length vector, converted to a Python float/numpy.ndarray respectively. Deliberately not general_mna::block_graph::SignalValue itself, to keep this crate free of a dependency on general-mna – matching cscript-ffi’s own convention of taking plain f64 slices and leaving any scalar/vector decision to the caller (dae-runtime).