Skip to main content

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}