1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
//! Writes a SPICE **rawfile** (`.raw`) — the binary/ASCII waveform format `ngspice` (and the
//! broader SPICE-tooling ecosystem, including Python readers such as PySpice and `spicelib`)
//! reads and writes — as an alternative to this crate's own CSV output, for interoperability
//! with existing SPICE-adjacent tooling. This module writes the **binary** variant (the format's
//! own default and the one most third-party readers expect first): an ASCII header block
//! (`Title:`/`Date:`/`Plotname:`/`Flags:`/`No. Variables:`/`No. Points:`/`Variables:`, one
//! `\t<index>\t<name>\t<type>` line per variable) followed by a `Binary:` marker and then, for
//! each point in order, one little/native-endian `f64` per variable, contiguous (point-major,
//! variable-minor) — the layout every mainstream SPICE-family writer and reader (`ngspice`,
//! Xyce, and the third-party Python rawfile libraries this feature was cross-validated against;
//! see `docs/journal/` for the exact validation run) agrees on for a "normal access" (not
//! "FastAccess") real (non-complex) plot.
//!
//! ## Header field format, verified against the real spec
//!
//! Confirmed against the ngspice manual's own worked example (§12.13, "console like a raw
//! file") and by writing a file with this module and reading it back with two independent
//! Python rawfile readers (PySpice's `Spice.Xyce.RawFile.RawFile`, which reads a standalone
//! rawfile exactly like this one with no `Circuit:`/`Doing analysis` preamble, and
//! `spicelib.RawRead`, which additionally validates against a whitelist of known SPICE
//! dialects). Both require the file to start with `Title:` as its very first bytes (no leading
//! preamble line), and require `Variables:` to be followed by exactly `No. Variables` lines each
//! `\t<index>\t<name>\t<type>` (tab-separated, `<type>` conventionally `time`/`voltage`/
//! `current` — see "Variable-type compatibility caveat" below).
//!
//! ## Variable-type compatibility caveat
//!
//! Every variable in a real SPICE rawfile is either a circuit voltage, a circuit current, the
//! `time`/`frequency` axis, or (in some dialects) another physically-typed quantity — there is
//! no "generic signal" type in the format. This crate's own CSV output has no such restriction
//! (a `kind=pid`/`kind=phys2sig`/... block's named output is just another column), so a
//! signal-domain block output written here that isn't a `V(...)`/`I(...)` circuit unknown is
//! given the type `voltage` as the broadest-compatibility fallback: PySpice's own rawfile reader
//! hard-codes a 4-entry `time`/`voltage`/`current`/`frequency` lookup table and raises `KeyError`
//! on anything else, so `voltage` (rather than inventing a `signal`/`unknown` type a stricter
//! reader would reject) is the only choice that reads cleanly in every reader this was tested
//! against. This only affects the header's declared *type* string, purely descriptive metadata —
//! the actual numeric value written is identical to the same column's CSV value either way (see
//! `book/user-guide/src/reading-output.md`).
use ;
/// One column of the waveform: `name` is the exact CSV header text (`t`, `V(node)`, `I(branch)`,
/// or a block/vector-signal name), `values[i]` is that column's value at point `i`.
/// The SPICE rawfile `Variables:` type string for a given CSV column name — see this module's
/// own "Variable-type compatibility caveat" doc section above for why every non-`V`/`I` column
/// (including the leading time axis, handled separately by the caller) falls back to `voltage`.
/// Writes `waveform` as a binary SPICE rawfile to `w`. `waveform.names[0]` is expected to be the
/// time/sweep column (`"t"` in this crate's own CSV header) and is renamed to SPICE's own
/// conventional `time` variable name in the header — see this module's doc comment for "same
/// data, different serialization" and the exact byte layout.
///
/// A thin wrapper over [`write_header`]/[`write_row`] — kept for callers (and this module's own
/// round-trip test) that already have the whole waveform in memory. A streaming writer that
/// doesn't need `waveform.rows.len()` known upfront (the SPICE format's `No. Points:` header
/// field means it otherwise would be) should call those two functions directly instead — see
/// `general-simulator-cli::main`'s own streaming CSV/raw writer for the pattern: write each row's
/// binary data to a temporary file as it's produced (via `write_row`, `No. Points` not needed
/// yet), then once the real point count is known, write the real output file's header (`write_header`)
/// followed by a plain byte-for-byte copy of the temp file's contents.
/// The text header + `Binary:` marker only — everything in a rawfile before the first row's
/// binary bytes. `n_points` must be the REAL, final point count (the format's own `No. Points:`
/// field is read upfront by every reader this was validated against, so writing it before all
/// points are known — e.g. a placeholder later patched — isn't an option; a streaming caller
/// must know or compute this before calling, which is exactly why `write_raw` itself can't
/// stream: it only has `waveform.rows.len()` once the whole `Vec` already exists).
/// One row's worth of binary `f64`s (point-major, variable-minor, matching `write_raw`'s own
/// layout) — `n_vars` is asserted against `row.len()` the same way `write_raw`'s own loop did,
/// just per-call instead of once over the whole `rows` slice.
/// `Date:` is documentation-only metadata to every reader this was validated against (neither
/// PySpice's nor `spicelib`'s parser does anything with its *value* beyond confirming the field
/// is present) — a plain Unix timestamp avoids pulling in a date-formatting dependency for a
/// field nothing downstream actually parses.