Skip to content

Commit c32f22b

Browse files
marcin-golebiowskimarcin-golebiowski
committed
feat: Add LTspice Netlist Compatibility Plan outlining phased approach and goals
1 parent 34ad4b6 commit c32f22b

1 file changed

Lines changed: 341 additions & 0 deletions

File tree

‎roadmap/ltspice-netlist-compatibility-plan.md‎

Lines changed: 341 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,341 @@
1+
---
2+
title: LTspice Netlist Compatibility Plan
3+
status: Draft / Roadmap
4+
scope: SpiceSharpParser + SpiceSharp
5+
last_reviewed: 2026-05-03
6+
---
7+
8+
# LTspice Netlist Compatibility Plan
9+
10+
## Summary
11+
12+
The first compatibility target is LTspice-generated netlists: copied netlists, `.net` files, and model decks reached through `.include` / `.lib`. Schematic import for `.asc` / `.asy` files is out of scope for this roadmap.
13+
14+
The recommended approach is phased:
15+
16+
1. Measure current compatibility with permission-safe fixtures.
17+
2. Add parser-level dialect shims, aliases, no-op handling, and targeted diagnostics.
18+
3. Escalate only proven runtime gaps into SpiceSharp engine changes.
19+
4. Keep public support claims tied to tests and a compatibility matrix.
20+
21+
Current `B` source and function-style `LAPLACE(...)` support are baseline behavior, not missing work. SpiceSharpParser already supports arbitrary behavioral voltage/current sources, source-level `E` / `G` / `F` / `H` `LAPLACE`, function-style `LAPLACE(input, transfer)`, inline `M=` / `TD=` / `DELAY=` options, helper lowering for mixed expressions, and generated C# writer parity.
22+
23+
## Goals
24+
25+
- Make common LTspice-generated netlists parse, read, and run when they use features that can be represented safely by SpiceSharp and SpiceSharpBehavioral.
26+
- Prefer compatibility shims and explicit diagnostics in SpiceSharpParser before adding new engine behavior.
27+
- Build a small, redistributable compatibility corpus that does not copy proprietary LTspice or vendor library content without permission.
28+
- Keep parser, generated C# writer, docs, and tests aligned.
29+
- Record known divergences from LTspice instead of making blanket numeric-parity claims.
30+
31+
## Non-Goals
32+
33+
- Importing or rendering LTspice schematic files (`.asc`) or symbols (`.asy`).
34+
- Depending on LTspice itself in CI.
35+
- Claiming complete LTspice numeric parity across all device models and solver settings.
36+
- Committing copied vendor model libraries unless their license explicitly permits redistribution.
37+
- Duplicating SpiceSharpBehavioral features directly in SpiceSharpParser.
38+
39+
## Baseline To Preserve
40+
41+
Keep these existing compatibility surfaces working while adding LTspice-specific behavior:
42+
43+
```spice
44+
B1 out 0 V={V(in)*0.5}
45+
B2 out 0 I={V(ctrl)*1m}
46+
47+
ELOW out 0 LAPLACE {V(in)} = {1/(1+s*tau)} M=2 TD=1n
48+
GLOW out 0 LAPLACE {V(in)} {gm/(1+s*tau)}
49+
FLOW out 0 LAPLACE = {I(Vsense)} {1/(1+s*tau)}
50+
HLOW out 0 LAPLACE {I(Vsense)} = {1/(1+s*tau)}
51+
52+
E1 out 0 VALUE={LAPLACE(V(in), 1/(1+s*tau))}
53+
B3 out 0 V={1 + 2*LAPLACE(V(in), 1/(1+s))}
54+
B4 out 0 I={LAPLACE(V(a), 1/(1+s*t1)) - LAPLACE(V(b), 1/(1+s*t2))}
55+
B5 out 0 V={LAPLACE(2*V(in), 1/(1+s*tau), M=2, TD=1n)}
56+
```
57+
58+
The `LAPLACE` transfer subset remains a finite, proper rational polynomial in `s` with finite coefficients and non-singular DC gain. `LAPLACE` should stay a source/lowering feature, not a normal scalar expression function.
59+
60+
## Compatibility Classes
61+
62+
Each fixture or feature should be classified separately for parsing, reading, execution, and numeric confidence.
63+
64+
| Class | Meaning | Expected behavior |
65+
| --- | --- | --- |
66+
| Supported | Parser and engine can represent the feature | Parse/read/run tests pass |
67+
| Parser shim | LTspice spelling can lower to existing SpiceSharp behavior | Add parser support and writer parity |
68+
| Recognized no-op | LTspice statement is display, probing, or annotation metadata | Ignore with info/warning diagnostics |
69+
| Engine required | The netlist parses but behavior needs a SpiceSharp runtime feature | Add engine tests before parser claims run support |
70+
| Intentional unsupported | Feature is proprietary, out of scope, or unsafe to approximate | Emit targeted diagnostics |
71+
| Numeric divergence | Feature runs but differs from LTspice semantics or defaults | Document tolerances and known differences |
72+
73+
## Roadmap
74+
75+
| Priority | Phase | Main outcome | Primary repo |
76+
| --- | --- | --- | --- |
77+
| P0 | Baseline corpus | Compatibility matrix and fixtures | SpiceSharpParser |
78+
| P1 | Dialect/no-op infrastructure | More LTspice-generated netlists accepted | SpiceSharpParser |
79+
| P2 | Scalar expression and ABM compatibility | Common behavioral expressions accepted | SpiceSharpParser first |
80+
| P3 | Model and instance parameter tolerance | Vendor-style model decks fail less often and fail clearer | SpiceSharpParser first |
81+
| P4 | Runtime gap closure | Engine support for measured blockers | SpiceSharp |
82+
| P5 | Release integration | Parser depends on tested engine capability | Both |
83+
| P6 | Documentation governance | Honest compatibility docs | SpiceSharpParser |
84+
85+
## Phase 0: Compatibility Baseline
86+
87+
Goal: replace guesswork with an executable, redistributable LTspice compatibility corpus.
88+
89+
Add fixtures under the integration-test area and group them by expected outcome:
90+
91+
- Parse-only: syntax that should tokenize and parse, even if no engine entity is produced.
92+
- Read-only: netlists that should convert into a SpiceSharp model without running.
93+
- Runnable: OP, DC, AC, TRAN, and NOISE examples with analytic or permission-safe expected values.
94+
- Expected diagnostic: recognized LTspice constructs that should produce targeted warnings or errors.
95+
96+
Cover common LTspice-generated shapes:
97+
98+
- `.include` and `.lib`, including quoted paths, nested includes, selected sections, Windows path separators, and relative paths.
99+
- `.param`, `.func`, `.step`, `.meas`, `.options`, `.ic`, `.nodeset`, `.temp`, and harmless generated controls such as `.backanno`.
100+
- Behavioral `B` sources, `VALUE=`, `TABLE`, `POLY`, source-level `LAPLACE`, and function-style `LAPLACE(...)`.
101+
- Voltage/current source waveforms: `PULSE`, `SIN`, `SINE`, `PWL`, `SFFM`, and `AM`.
102+
- Model decks and subcircuits from synthetic, license-safe examples.
103+
104+
Deliverables:
105+
106+
- A compatibility matrix document or test data file.
107+
- A naming convention for fixture classes, for example `LtspiceCompatibilityTests` plus feature-specific classes.
108+
- A rule that every future compatibility claim points to a fixture.
109+
110+
## Phase 1: Dialect Infrastructure And No-Ops
111+
112+
Goal: support harmless LTspice-generated syntax without weakening diagnostics for other dialects.
113+
114+
Implementation direction:
115+
116+
- Add an explicit compatibility option, such as a `SpiceDialect` enum or flags-style `CompatibilityOptions` object.
117+
- Prefer generic syntax improvements by default only when they do not change PSpice/ngspice behavior.
118+
- Recognize display/probing/annotation statements that can be safely ignored, such as `.backanno`, with informational or warning diagnostics.
119+
- Keep the existing processor pipeline intact: includes, library expansion, macros, append-model, AKO models, sweeps, and `.if` processing.
120+
- Tighten `.include` / `.lib` tests around LTspice path conventions before changing behavior.
121+
122+
Candidate files:
123+
124+
- `src/SpiceSharpParser/SpiceNetlistParser.cs`
125+
- `src/SpiceSharpParser/ModelReaders/Netlist/Spice/SpiceNetlistReaderSettings.cs`
126+
- `src/SpiceSharpParser/ModelReaders/Netlist/Spice/SpiceObjectMappings.cs`
127+
- `src/SpiceSharpParser.IntegrationTests/`
128+
129+
Acceptance criteria:
130+
131+
- LTspice-generated metadata statements no longer cause generic parse/read failures.
132+
- Unsupported LTspice controls produce targeted diagnostics.
133+
- Existing non-LTspice tests remain unchanged.
134+
135+
## Phase 2: Scalar Expression And ABM Compatibility
136+
137+
Goal: accept more LTspice behavioral expressions when they can be represented safely by existing runtime behavior.
138+
139+
Implementation direction:
140+
141+
- Audit LTspice scalar functions against current math functions, random functions, resolver functions, `.FUNC`, and behavioral-source support.
142+
- Implement safe scalar aliases first.
143+
- Treat `table()` as an early candidate because the math-function registry already exposes it as a TODO.
144+
- Add targeted diagnostics for recognized dynamic ABM functions that need simulation state or history.
145+
- Keep `LAPLACE(...)` on the existing lowering path rather than registering it as a scalar function.
146+
147+
Function categories:
148+
149+
| Category | Examples | Plan |
150+
| --- | --- | --- |
151+
| Pure scalar aliases | clamp/limit-style helpers, sign/step variants | Add parser/evaluator aliases when semantics are clear |
152+
| Existing random/Monte Carlo | `mc`, `gauss`, `flat`, `random`, `unif` variants | Compare LTspice semantics and document differences |
153+
| Table lookup | `table(...)` scalar form | Implement or lower to existing table behavior |
154+
| Dynamic/stateful | delay, derivative, integral, time-history functions | Classify as engine-required unless already supported |
155+
| Noise/random time sources | transient noise-like expressions | Engine-required or intentionally unsupported |
156+
157+
Candidate files:
158+
159+
- `src/SpiceSharpParser/ModelReaders/Netlist/Spice/Evaluation/Functions/MathFunctions.cs`
160+
- `src/SpiceSharpParser/ModelReaders/Netlist/Spice/Evaluation/Functions/RandomFunctions.cs`
161+
- `src/SpiceSharpParser/ModelReaders/Netlist/Spice/Evaluation/ExpressionResolver.cs`
162+
- `src/SpiceSharpParser/ModelReaders/Netlist/Spice/Readers/EntityGenerators/Components/Sources/ArbitraryBehavioralGenerator.cs`
163+
- `src/docs/articles/behavioral-source.md`
164+
- `src/docs/articles/laplace.md`
165+
166+
Acceptance criteria:
167+
168+
- Safe aliases have parser, evaluator, and behavioral-source tests.
169+
- Dynamic unsupported functions produce clear diagnostics.
170+
- Generated C# writer output remains valid for every new lowering.
171+
172+
## Phase 3: Model And Instance Parameter Tolerance
173+
174+
Goal: let common LTspice model decks map cleanly where SpiceSharp has equivalent behavior, and fail clearly where it does not.
175+
176+
Implementation direction:
177+
178+
- Build alias/ignore/error tables per model family.
179+
- Map direct equivalents through existing model generators and parameter update paths.
180+
- Ignore LTspice metadata or layout-only parameters with compatibility diagnostics.
181+
- Fail for behavior-changing unsupported parameters with the component/model name and suggested fallback.
182+
- Test model parameter expressions, subcircuit parameter defaults, geometry parameters, temperature parameters, and `.MODEL` variants.
183+
184+
Model families:
185+
186+
| Family | Parser action | Engine action |
187+
| --- | --- | --- |
188+
| R/C/L | Alias tolerances, temperature coefficients, geometry forms | Usually existing behavior |
189+
| Diode | Alias supported model parameters, warn on unsupported noise/recovery terms | Add engine behavior only for measured blockers |
190+
| BJT | Map known SPICE parameters, document divergence | Engine changes only with fixtures |
191+
| JFET | Map known parameters and metadata | Engine changes only with fixtures |
192+
| MOSFET | Separate legacy levels from LTspice/vendor power models | Likely engine-required for advanced models |
193+
| Switch | Map threshold/hysteresis/resistance aliases | Existing behavior likely sufficient |
194+
| Transmission line | Preserve current lossless `T` support | Lossy/distributed variants may need engine work |
195+
196+
Candidate files:
197+
198+
- `src/SpiceSharpParser/ModelReaders/Netlist/Spice/Readers/EntityGenerators/Components/Semiconductors/`
199+
- `src/SpiceSharpParser/ModelReaders/Netlist/Spice/Readers/EntityGenerators/Models/`
200+
- `src/SpiceSharpParser/ModelReaders/Netlist/Spice/Context/Updates/`
201+
- `src/docs/articles/mosfet.md`
202+
- `src/docs/articles/diode.md`
203+
- `src/docs/articles/transmission-line.md`
204+
205+
Acceptance criteria:
206+
207+
- Each alias/ignore/error decision is covered by a fixture.
208+
- Behavior-changing unsupported parameters do not silently disappear.
209+
- Docs distinguish parse tolerance from numeric equivalence.
210+
211+
## Phase 4: SpiceSharp Runtime Gap Closure
212+
213+
Goal: add engine capabilities only after parser fixtures prove that parsing and lowering are not enough.
214+
215+
Possible engine work:
216+
217+
- LTspice/vendor-specific MOSFET or power-device models.
218+
- Lossy/distributed transmission-line variants.
219+
- Dynamic behavioral functions that require time history, derivatives, integrals, or delays.
220+
- Transient compatibility improvements around timestep guidance and fast switching.
221+
- Noise behavior differences, especially where LTspice semantics do not match SpiceSharp frequency-domain noise support.
222+
223+
Implementation direction:
224+
225+
- Add NUnit tests in the SpiceSharp repository before claiming parser runnable support.
226+
- Reuse existing SpiceSharp patterns: component parameters, binding contexts, behavior interfaces, generated behavior factories, and biasing/frequency/time/noise behaviors.
227+
- Avoid hidden solver-default changes unless they are measured and documented.
228+
- Prefer parser-side warnings for timestep-sensitive generated netlists over silent numerical tuning.
229+
230+
Candidate files in the SpiceSharp repository:
231+
232+
- `SpiceSharp/Components/`
233+
- `SpiceSharp/Simulations/`
234+
- `SpiceSharpGenerator/BehaviorGenerator.cs`
235+
- `SpiceSharpTest/`
236+
237+
Acceptance criteria:
238+
239+
- Engine changes have direct NUnit coverage.
240+
- Parser fixtures reference the minimum engine package version needed.
241+
- Runtime behavior is documented with tolerances or known divergence.
242+
243+
## Phase 5: Parser And Engine Release Integration
244+
245+
Goal: keep the parser package, engine package, and generated C# writer in lockstep.
246+
247+
Implementation direction:
248+
249+
- Land SpiceSharp engine changes first when needed.
250+
- Update SpiceSharpParser package references only after engine tests are stable.
251+
- Add versioned diagnostics when a parser feature requires newer SpiceSharp or SpiceSharpBehavioral packages.
252+
- Preserve generated C# writer parity for every lowering or new entity mapping.
253+
- Keep old behavior stable for netlists that do not opt into LTspice compatibility settings, unless the change is a safe generic parser improvement.
254+
255+
Acceptance criteria:
256+
257+
- Full parser solution tests pass after package updates.
258+
- Full engine solution tests pass before parser integration.
259+
- Generated C# writer tests cover any new LTspice-compatible entity mapping.
260+
261+
## Phase 6: Documentation And Governance
262+
263+
Goal: make compatibility claims precise enough for users to trust.
264+
265+
Documentation updates:
266+
267+
- README high-level LTspice support statement.
268+
- A compatibility matrix with separate parse, read, run, and numeric-confidence columns.
269+
- Troubleshooting entries for common unsupported LTspice constructs.
270+
- Migration examples showing equivalent supported syntax.
271+
- A fixture policy for vendor libraries and license-sensitive model decks.
272+
273+
Compatibility matrix columns:
274+
275+
| Column | Purpose |
276+
| --- | --- |
277+
| Feature | LTspice construct or netlist pattern |
278+
| Parse | Syntax accepted |
279+
| Read | Converted to SpiceSharp objects |
280+
| Run | OP/DC/AC/TRAN/NOISE execution support |
281+
| Numeric confidence | Analytic, golden, smoke-only, or divergent |
282+
| Diagnostics | Expected warnings/errors |
283+
| Notes | Known limitations and migration guidance |
284+
285+
## Verification Strategy
286+
287+
Run parser and engine tests separately:
288+
289+
```powershell
290+
dotnet test d:\dev\SpiceSharpParser\src\SpiceSharp-Parser.sln
291+
dotnet test d:\dev\SpiceSharp\SpiceSharp.sln
292+
```
293+
294+
For each compatibility feature:
295+
296+
1. Add a fixture before or with implementation.
297+
2. Classify the fixture as parse-only, read-only, runnable, or expected diagnostic.
298+
3. Use analytic expectations or permission-safe golden values for numeric checks.
299+
4. Avoid CI dependency on proprietary LTspice tooling.
300+
5. Verify generated C# writer parity when a source lowering or new entity mapping is involved.
301+
6. Update docs and the compatibility matrix before changing support claims.
302+
303+
## Open Decisions
304+
305+
- Compatibility API shape: `SpiceDialect.LTspice`, `LtspiceCompatibility`, or a flags-style `CompatibilityOptions` object. A flags-style options object is recommended if multiple dialect quirks will coexist.
306+
- Whether recognized LTspice no-ops should default to warnings or informational diagnostics.
307+
- Whether LTspice compatibility mode should be opt-in only, or whether harmless no-op recognition should be enabled by default.
308+
- How to version diagnostics for parser features that require newer SpiceSharp or SpiceSharpBehavioral packages.
309+
310+
## Key Files
311+
312+
Parser-side files:
313+
314+
- `README.md`
315+
- `src/docs/articles/behavioral-source.md`
316+
- `src/docs/articles/laplace.md`
317+
- `src/SpiceSharpParser/SpiceNetlistParser.cs`
318+
- `src/SpiceSharpParser/ModelReaders/Netlist/Spice/SpiceObjectMappings.cs`
319+
- `src/SpiceSharpParser/ModelReaders/Netlist/Spice/SpiceNetlistReaderSettings.cs`
320+
- `src/SpiceSharpParser/ModelReaders/Netlist/Spice/Evaluation/Functions/MathFunctions.cs`
321+
- `src/SpiceSharpParser/ModelReaders/Netlist/Spice/Evaluation/Functions/RandomFunctions.cs`
322+
- `src/SpiceSharpParser/ModelReaders/Netlist/Spice/Readers/EntityGenerators/Components/Sources/ArbitraryBehavioralGenerator.cs`
323+
- `src/SpiceSharpParser/ModelReaders/Netlist/Spice/Readers/EntityGenerators/Components/Sources/LaplaceFunctionExpressionLowerer.cs`
324+
- `src/SpiceSharpParser/ModelReaders/Netlist/Spice/Readers/EntityGenerators/Components/Semiconductors/`
325+
- `src/SpiceSharpParser.IntegrationTests/`
326+
- `src/SpiceSharpParser/SpiceSharpParser.csproj`
327+
328+
Engine-side files, in the sibling SpiceSharp repository:
329+
330+
- `SpiceSharp/Components/`
331+
- `SpiceSharp/Simulations/`
332+
- `SpiceSharpGenerator/BehaviorGenerator.cs`
333+
- `SpiceSharpTest/`
334+
335+
## Current Decisions
336+
337+
- LTspice-generated netlists are the first target.
338+
- `.asc` and `.asy` schematic import are excluded from the first roadmap.
339+
- Parser compatibility and diagnostics come first; engine changes follow measured blockers.
340+
- Existing `B` source and function-style `LAPLACE(...)` support are current baseline behavior.
341+
- Copyright-sensitive vendor libraries should not be committed as fixtures unless license terms clearly allow it.

0 commit comments

Comments
 (0)