dae_runtime/checkpoint.rs
1//! Checkpoint/resume: a complete, serializable snapshot of a transient run's loop-carried
2//! state, so a run can stop at some $t$ and continue later — from the same process, from a
3//! file, on another machine — with a trace **bit-identical** to the uninterrupted run.
4//!
5//! That bit-identity is the whole contract, and it is what makes the feature testable: every
6//! `f64` in the file is the exact value the loop held, every enum is the exact mode the loop
7//! was in, and the first resumed step is an ordinary continuation (trapezoidal, with its
8//! $x_{k-1}$ history intact), not a restart. Nothing is re-derived on load that the loop would
9//! not have re-derived itself on the next step.
10//!
11//! # What is in a checkpoint
12//!
13//! Exactly what `simulate_transient_with_blocks_streamed`'s loop carries from one accepted
14//! step to the next, and nothing that the netlist itself already determines:
15//!
16//! - the circuit state $x_k$ and $x_{k-1}$, the previous operating point (its diode segments
17//! and Norton currents), the previous gate states, the diode-segment fallback bookkeeping,
18//! and the ringing cooldown counter;
19//! - $t$, the accepted-step count / step index (so `forced` logic continues, not restarts),
20//! and the adaptive controller's next $\Delta t$;
21//! - `prev_outputs` — what every `prev:` signal reads on the next step;
22//! - every block's own state, as a [`BlockSnapshot`]: state vectors, sample-time accumulators
23//! and held outputs, phases, logic bits, counts — and for the escape-hatch hosts, the opaque
24//! state as bytes (`pickle` for a `pyblock`, the library's own `cscript_state_write` for a
25//! `cscript`, an Octave `save -binary` for an `octblock`).
26//!
27//! Not in it: the netlist, the block definitions, the diode/switch models, the time-step
28//! configuration. A checkpoint is loaded *into* a deck the caller supplies, and refuses a deck
29//! that is not the one it came from (see [`Checkpoint::deck_hash`]).
30//!
31//! # File format
32//!
33//! `postcard`-encoded [`Checkpoint`], prefixed by the four bytes [`MAGIC`] and a little-endian
34//! `u32` [`FORMAT_VERSION`]. postcard because it is compact, has a stable published wire
35//! encoding, and round-trips `f64` bit-exactly (a text format would need care to do so).
36//! A future incompatible layout bumps `FORMAT_VERSION`; an old file is then rejected up front
37//! by [`Checkpoint::from_bytes`] rather than misread. Appending a variant to
38//! [`BlockSnapshot`] is *not* such a change — postcard writes a variant as its index, so the
39//! existing variants keep their bytes — which is how the `CScript`/`OctBlock` variants landed
40//! without a bump.
41//!
42//! # Escape-hatch blocks
43//!
44//! `kind=pyblock` state round-trips via `pickle` with no author opt-in (the same reasoning as
45//! its `copy.deepcopy`-based clone). `kind=octblock` state is the `__gs_state.<name>` slot in
46//! the `octave-cli` child, saved and loaded with Octave's own `save -binary`/`load` through a
47//! short-lived temporary file — also no opt-in. `kind=cscript` state is an opaque C heap object
48//! only the author's code can lay out, so it is opt-in: a library exporting the
49//! `cscript_state_size`/`cscript_state_write`/`cscript_state_read` triple checkpoints; one
50//! exporting none of them keeps running unchanged but is refused at checkpoint time with
51//! [`DaeError::CheckpointUnsupportedBlock`], naming the block, rather than written partially;
52//! one exporting only some of them fails to load at all (`cscript_ffi::CScriptError::MissingSymbol`).
53
54use std::collections::BTreeMap;
55use std::hash::Hasher;
56use std::path::Path;
57
58use serde::{Deserialize, Serialize};
59
60use crate::DaeError;
61
62/// The four bytes every checkpoint file starts with.
63pub const MAGIC: &[u8; 4] = b"GSCK";
64/// Bumped on any incompatible change to [`Checkpoint`]'s layout.
65pub const FORMAT_VERSION: u32 = 1;
66
67/// A `SignalValue` without the `general_mna` type — that crate has no serde support, and the
68/// distinction is just "was it a vector."
69#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
70pub enum SignalSnapshot {
71 Scalar(f64),
72 Vector(Vec<f64>),
73}
74
75/// One block's own persisted state. Variants mirror `block_graph::BlockState`, minus everything
76/// the netlist rebuilds (the compiled state-space, the models, the FFI instances).
77#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
78pub enum BlockSnapshot {
79 Stateless,
80 /// `Pid`/`StateSpace`/`TransferFunction`.
81 Dynamic {
82 x: Vec<f64>,
83 },
84 /// `DiscreteStateSpace`/`DiscreteTransferFunction`.
85 DiscreteDynamic {
86 x: Vec<f64>,
87 time_since_sample: f64,
88 last_output: Vec<f64>,
89 },
90 DiscretePid {
91 int_state: f64,
92 int_prev_e: f64,
93 filt_state: f64,
94 filt_prev_v: f64,
95 time_since_sample: f64,
96 last_output: f64,
97 },
98 /// `Vco` and `PhaseShiftPwm` — both a single phase in cycles.
99 Phase(f64),
100 Pmsm {
101 x: Vec<f64>,
102 },
103 /// `Hysteresis` and `SrLatch` — a single persisted bit.
104 Bit(bool),
105 FlipFlop {
106 q: bool,
107 prev_clk: f64,
108 },
109 Counter {
110 count: i64,
111 prev_clk: f64,
112 },
113 /// `PyFunction`/`OctFunction` — stateless hosts, only the zero-order-hold bookkeeping.
114 SampledFunction {
115 time_since_sample: f64,
116 last_output: Vec<f64>,
117 },
118 /// `PyBlock` — the zero-order-hold bookkeeping, the solver-owned `xc`, and the block's own
119 /// state object as `pickle` bytes.
120 PyBlock {
121 time_since_sample: f64,
122 next_hit_dt: f64,
123 last_output: Vec<f64>,
124 xc: Vec<f64>,
125 state: Vec<u8>,
126 },
127 /// `CScript` — the same bookkeeping and `xc` as `PyBlock`, and the opaque C state as the
128 /// bytes the library's own `cscript_state_write` produced (see `cscript_ffi`'s module doc
129 /// comment, "The optional checkpoint state contract"). Only ever built for a library that
130 /// exports that contract; otherwise the run is refused as
131 /// [`DaeError::CheckpointUnsupportedBlock`].
132 ///
133 /// Appended after `PyBlock` on purpose: postcard encodes a variant as its index, so adding
134 /// variants at the end leaves every existing file's encoding unchanged and
135 /// [`FORMAT_VERSION`] stays at 1.
136 CScript {
137 time_since_sample: f64,
138 next_hit_dt: f64,
139 last_output: Vec<f64>,
140 xc: Vec<f64>,
141 state: Vec<u8>,
142 },
143 /// `OctBlock` — the same bookkeeping and `xc`, and the instance's `__gs_state.<name>` slot
144 /// as the bytes of an Octave `save -binary` of it (see
145 /// `octave_ffi::OctaveSession::save_state`). Needs no author opt-in.
146 OctBlock {
147 time_since_sample: f64,
148 next_hit_dt: f64,
149 last_output: Vec<f64>,
150 xc: Vec<f64>,
151 state: Vec<u8>,
152 },
153}
154
155/// The previous accepted operating point, minus the `unknowns` names (stored once on the
156/// [`Checkpoint`] itself).
157#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
158pub struct PointSnapshot {
159 pub x: Vec<f64>,
160 pub diode_names: Vec<String>,
161 pub diode_z: Vec<(f64, f64)>,
162 pub diode_raw_ioff: Vec<f64>,
163}
164
165/// The complete loop-carried state of a transient run at the end of an accepted step.
166#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
167pub struct Checkpoint {
168 /// Identifies the deck this was taken from — see [`deck_hash`]. A load into a deck with a
169 /// different hash is refused as [`DaeError::CheckpointDeckMismatch`].
170 pub deck_hash: u64,
171 /// The system's unknown names, in `x` order — reported in the mismatch error so the reader
172 /// can see *what* differs, and double-checked on load.
173 pub unknowns: Vec<String>,
174 pub t: f64,
175 /// Accepted steps so far (the adaptive stall guard counts from here).
176 pub accepted_steps: usize,
177 /// The loop's own step index — nonzero on resume, so the first resumed step is not treated
178 /// as a run's first step (which would force backward Euler).
179 pub step_index: usize,
180 /// The adaptive controller's suggested next step; `None` for a fixed-step run.
181 pub dt_next: Option<f64>,
182 pub ringing_cooldown: u32,
183 pub x_prev: Vec<f64>,
184 pub x_prev_prev: Option<Vec<f64>>,
185 pub point_prev: PointSnapshot,
186 pub prev_diode_raw_ioff: BTreeMap<String, f64>,
187 /// Each diode's previous segment, as `classify_segments` numbers them (`0` breakdown, `1`
188 /// leakage, `2` forward); `None` before the first accepted step.
189 pub prev_segments: Option<Vec<u8>>,
190 /// Each ideal switch's previous gate state, `true` for on.
191 pub prev_gate_states: Option<BTreeMap<String, bool>>,
192 pub prev_outputs: BTreeMap<String, SignalSnapshot>,
193 /// One entry per block, in the caller's block order, keyed by name for the mismatch check.
194 pub blocks: Vec<(String, BlockSnapshot)>,
195}
196
197impl Checkpoint {
198 /// The file encoding: [`MAGIC`], [`FORMAT_VERSION`], then the postcard payload.
199 pub fn to_bytes(&self) -> Result<Vec<u8>, DaeError> {
200 let mut out = MAGIC.to_vec();
201 out.extend_from_slice(&FORMAT_VERSION.to_le_bytes());
202 let payload = postcard::to_stdvec(self)
203 .map_err(|e| DaeError::CheckpointFormat(format!("encoding failed: {e}")))?;
204 out.extend_from_slice(&payload);
205 Ok(out)
206 }
207
208 /// The inverse of [`Self::to_bytes`]; a wrong magic or an unknown version is reported as
209 /// such rather than decoded into garbage.
210 pub fn from_bytes(bytes: &[u8]) -> Result<Self, DaeError> {
211 if bytes.len() < 8 || &bytes[..4] != MAGIC {
212 return Err(DaeError::CheckpointFormat(
213 "not a general-simulator checkpoint (missing GSCK header)".to_string(),
214 ));
215 }
216 let version = u32::from_le_bytes([bytes[4], bytes[5], bytes[6], bytes[7]]);
217 if version != FORMAT_VERSION {
218 return Err(DaeError::CheckpointFormat(format!(
219 "checkpoint format version {version} is not the {FORMAT_VERSION} this build \
220 reads"
221 )));
222 }
223 postcard::from_bytes(&bytes[8..])
224 .map_err(|e| DaeError::CheckpointFormat(format!("decoding failed: {e}")))
225 }
226
227 pub fn write_to(&self, path: &Path) -> Result<(), DaeError> {
228 let bytes = self.to_bytes()?;
229 // Write-then-rename, so a run killed mid-write (the very case `--checkpoint-every`
230 // exists for) never leaves a truncated file where the last good checkpoint was.
231 let tmp = path.with_extension("tmp");
232 std::fs::write(&tmp, bytes).map_err(|e| DaeError::CheckpointIo {
233 path: path.to_path_buf(),
234 message: e.to_string(),
235 })?;
236 std::fs::rename(&tmp, path).map_err(|e| DaeError::CheckpointIo {
237 path: path.to_path_buf(),
238 message: e.to_string(),
239 })
240 }
241
242 pub fn read_from(path: &Path) -> Result<Self, DaeError> {
243 let bytes = std::fs::read(path).map_err(|e| DaeError::CheckpointIo {
244 path: path.to_path_buf(),
245 message: e.to_string(),
246 })?;
247 Self::from_bytes(&bytes)
248 }
249}
250
251/// A deterministic 64-bit FNV-1a over everything that defines the deck a run is stepping:
252/// the flattened statements, the dialect, the blocks (name, kind, inputs, `ic`), the diode and
253/// switch models, and the shared on-resistance. Deliberately *not* `std`'s `DefaultHasher`,
254/// whose output is not stable across Rust versions — this value lives in files.
255///
256/// Uses each value's `Debug` rendering as the hashed bytes: every one of these types already
257/// derives `Debug` for its own reasons, and a `Debug` string changes exactly when the value
258/// does, which is the property needed. It would also change if a type's `Debug` layout
259/// changed between builds — acceptable, since that reads as "different deck" (a refusal), never
260/// as a silent misload.
261pub fn deck_hash(parts: &[&dyn std::fmt::Debug]) -> u64 {
262 struct Fnv(u64);
263 impl Hasher for Fnv {
264 fn finish(&self) -> u64 {
265 self.0
266 }
267 fn write(&mut self, bytes: &[u8]) {
268 for b in bytes {
269 self.0 ^= u64::from(*b);
270 self.0 = self.0.wrapping_mul(0x0000_0100_0000_01b3);
271 }
272 }
273 }
274 let mut h = Fnv(0xcbf2_9ce4_8422_2325);
275 for part in parts {
276 h.write(format!("{part:?}").as_bytes());
277 h.write(&[0xff]);
278 }
279 h.finish()
280}
281
282#[cfg(test)]
283mod tests {
284 use super::*;
285
286 #[test]
287 fn bytes_round_trip_bit_exactly() {
288 let ckpt = Checkpoint {
289 deck_hash: 42,
290 unknowns: vec!["V(a)".into()],
291 t: 0.1 + 0.2,
292 accepted_steps: 3,
293 step_index: 3,
294 dt_next: Some(f64::MIN_POSITIVE),
295 ringing_cooldown: 1,
296 x_prev: vec![1.0 / 3.0, -0.0, f64::MAX],
297 x_prev_prev: None,
298 point_prev: PointSnapshot {
299 x: vec![1e-300],
300 diode_names: vec![],
301 diode_z: vec![],
302 diode_raw_ioff: vec![],
303 },
304 prev_diode_raw_ioff: BTreeMap::new(),
305 prev_segments: Some(vec![0, 1, 2]),
306 prev_gate_states: Some([("S1".to_string(), true)].into_iter().collect()),
307 prev_outputs: [("G".to_string(), SignalSnapshot::Scalar(0.7))]
308 .into_iter()
309 .collect(),
310 blocks: vec![("G".into(), BlockSnapshot::Dynamic { x: vec![2.5] })],
311 };
312 let bytes = ckpt.to_bytes().unwrap();
313 assert_eq!(&bytes[..4], MAGIC);
314 let back = Checkpoint::from_bytes(&bytes).unwrap();
315 assert_eq!(back, ckpt);
316 // `-0.0 == 0.0` under PartialEq, so check the sign bit separately.
317 assert!(back.x_prev[1].is_sign_negative());
318 }
319
320 #[test]
321 fn a_foreign_or_future_file_is_refused_up_front() {
322 assert!(matches!(
323 Checkpoint::from_bytes(b"hello world"),
324 Err(DaeError::CheckpointFormat(_))
325 ));
326 let mut bytes = MAGIC.to_vec();
327 bytes.extend_from_slice(&(FORMAT_VERSION + 1).to_le_bytes());
328 assert!(matches!(
329 Checkpoint::from_bytes(&bytes),
330 Err(DaeError::CheckpointFormat(m)) if m.contains("version")
331 ));
332 }
333
334 #[test]
335 fn deck_hash_is_order_sensitive_and_stable() {
336 let a = deck_hash(&[&"R1 a b 1", &"C1 b 0 1u"]);
337 let b = deck_hash(&[&"C1 b 0 1u", &"R1 a b 1"]);
338 assert_ne!(a, b);
339 assert_eq!(a, deck_hash(&[&"R1 a b 1", &"C1 b 0 1u"]));
340 // FNV-1a of the empty input is the offset basis -- pins the algorithm, since these
341 // values live in files.
342 assert_eq!(deck_hash(&[]), 0xcbf2_9ce4_8422_2325);
343 }
344}