Expand description
Checkpoint/resume: a complete, serializable snapshot of a transient run’s loop-carried state, so a run can stop at some $t$ and continue later — from the same process, from a file, on another machine — with a trace bit-identical to the uninterrupted run.
That bit-identity is the whole contract, and it is what makes the feature testable: every
f64 in the file is the exact value the loop held, every enum is the exact mode the loop
was in, and the first resumed step is an ordinary continuation (trapezoidal, with its
$x_{k-1}$ history intact), not a restart. Nothing is re-derived on load that the loop would
not have re-derived itself on the next step.
§What is in a checkpoint
Exactly what simulate_transient_with_blocks_streamed’s loop carries from one accepted
step to the next, and nothing that the netlist itself already determines:
- the circuit state $x_k$ and $x_{k-1}$, the previous operating point (its diode segments and Norton currents), the previous gate states, the diode-segment fallback bookkeeping, and the ringing cooldown counter;
- $t$, the accepted-step count / step index (so
forcedlogic continues, not restarts), and the adaptive controller’s next $\Delta t$; prev_outputs— what everyprev:signal reads on the next step;- every block’s own state, as a
BlockSnapshot: state vectors, sample-time accumulators and held outputs, phases, logic bits, counts — and for the escape-hatch hosts, the opaque state as bytes (picklefor apyblock, the library’s owncscript_state_writefor acscript, an Octavesave -binaryfor anoctblock).
Not in it: the netlist, the block definitions, the diode/switch models, the time-step
configuration. A checkpoint is loaded into a deck the caller supplies, and refuses a deck
that is not the one it came from (see Checkpoint::deck_hash).
§File format
postcard-encoded Checkpoint, prefixed by the four bytes MAGIC and a little-endian
u32 FORMAT_VERSION. postcard because it is compact, has a stable published wire
encoding, and round-trips f64 bit-exactly (a text format would need care to do so).
A future incompatible layout bumps FORMAT_VERSION; an old file is then rejected up front
by Checkpoint::from_bytes rather than misread. Appending a variant to
BlockSnapshot is not such a change — postcard writes a variant as its index, so the
existing variants keep their bytes — which is how the CScript/OctBlock variants landed
without a bump.
§Escape-hatch blocks
kind=pyblock state round-trips via pickle with no author opt-in (the same reasoning as
its copy.deepcopy-based clone). kind=octblock state is the __gs_state.<name> slot in
the octave-cli child, saved and loaded with Octave’s own save -binary/load through a
short-lived temporary file — also no opt-in. kind=cscript state is an opaque C heap object
only the author’s code can lay out, so it is opt-in: a library exporting the
cscript_state_size/cscript_state_write/cscript_state_read triple checkpoints; one
exporting none of them keeps running unchanged but is refused at checkpoint time with
DaeError::CheckpointUnsupportedBlock, naming the block, rather than written partially;
one exporting only some of them fails to load at all (cscript_ffi::CScriptError::MissingSymbol).
Structs§
- Checkpoint
- The complete loop-carried state of a transient run at the end of an accepted step.
- Point
Snapshot - The previous accepted operating point, minus the
unknownsnames (stored once on theCheckpointitself).
Enums§
- Block
Snapshot - One block’s own persisted state. Variants mirror
block_graph::BlockState, minus everything the netlist rebuilds (the compiled state-space, the models, the FFI instances). - Signal
Snapshot - A
SignalValuewithout thegeneral_mnatype — that crate has no serde support, and the distinction is just “was it a vector.”
Constants§
- FORMAT_
VERSION - Bumped on any incompatible change to
Checkpoint’s layout. - MAGIC
- The four bytes every checkpoint file starts with.
Functions§
- deck_
hash - A deterministic 64-bit FNV-1a over everything that defines the deck a run is stepping:
the flattened statements, the dialect, the blocks (name, kind, inputs,
ic), the diode and switch models, and the shared on-resistance. Deliberately notstd’sDefaultHasher, whose output is not stable across Rust versions — this value lives in files.