Skip to main content

Module checkpoint

Module checkpoint 

Source
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 forced logic continues, not restarts), and the adaptive controller’s next $\Delta t$;
  • prev_outputs — what every prev: 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 (pickle for a pyblock, the library’s own cscript_state_write for a cscript, an Octave save -binary for an octblock).

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.
PointSnapshot
The previous accepted operating point, minus the unknowns names (stored once on the Checkpoint itself).

Enums§

BlockSnapshot
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).
SignalSnapshot
A SignalValue without the general_mna type — 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 not std’s DefaultHasher, whose output is not stable across Rust versions — this value lives in files.