general-mna
general-mna is an educational Rust library that converts a SPICE netlist
into the modified nodal analysis (MNA) descriptor equation
A x(t) + K dx(t)/dt = B u(t)
It deliberately separates three jobs:
general-spice-coreparses ngspice or Xyce text.- This crate constructs symbolic MNA matrices and converter phase models.
- A thin Python/PyO3 or JavaScript/WASM package can render PDFs, hand the expressions to SymPy, or drive an interactive state-space application.
The old Python ElSpice project was used as a behavioral reference. It is not modified or imported by this repository.
Implemented
- Symbolic stamps for
R,C,L,V,I,G(VCCS),E(VCVS),F(CCCS), andH(CCVS). - Time-varying
V/Isources —SIN/PULSE/EXP/PWL/SFFM, the same five forms common to both ngspice and Xyce (seespice-lsp/docs/GRAMMAR.md). This crate has no notion of "now": a source using one of these is stamped as a per-instance symbol (Expression::symbol(name), the same pattern diode Norton currents already use below) rather than a baked literal, andMnaSystem::transient_sourcesexposes the parsedTransientFunctionfor the caller to evaluate at its own currenttand supply viaevaluate()'svaluesmap every step. D(diode) as a companion-model conductance plus a Norton current source, both left as per-instance symbolic parameters ({name}_G,{name}_Ioff) rather than parsed from the netlist — this crate has no diode physics of its own; an external caller (e.g. a piecewise-linear or nonlinear circuit solver) supplies numeric values for those symbols viaevaluate(), potentially different ones every call. SeeNumericMnaSystem::input_values/::ubelow.- Mutual inductance with the SPICE relation
M = k*sqrt(L1*L2). ic=initial conditions onCandL, assigned into the starting state vector byMnaSystem::initial_state— see Initial conditions below.- Trailing parameters on a stamped device card are checked, not discarded — both the
key=valuefields and the positional ones, each against what that device letter's grammar actually permits. A build error names the line and the device, in the same shape as the block (kind=...) parser's own diagnostics. See Device-card parameter checking below, including what is deliberately left unchecked and why. - Case-insensitive node, element, and controlling-source lookup.
- One device per name. Element names share a single case-insensitive namespace, checked over every device letter before anything is stamped. Two cards of one name are a build error, not a silently merged pair -- see
docs/gotchas/GOTCHA-001for why the numbers used to come out right anyway. Subcircuit bodies are checked after flattening, so two instances of one.subcktare fine. - SPICE numeric suffixes (
k,meg,m,u,n,p, and others). - Explicit errors for devices with no linear-or-externally-parameterized stamp (e.g. a BJT); they are never silently removed from a circuit.
- Name-based
Ron/Roffswitch overrides suitable for converter phases. - Weighted descriptor averaging for any number of switching phases.
- The two-phase small-signal duty perturbation vector.
- Numeric Schur-complement reduction to
dot(x) = A_s*x + B_s*uwhen the chosen MNA storage coordinates are independent. - A string DTO that maps directly to Python dictionaries, JSON objects, or TypeScript interfaces without committing the core crate to one binding framework.
.subckt/X-instance hierarchy (src/hierarchy.rs), expanded into one flat statement list before either builder sees it: dotted-path-renamed devices/blocks (X1.R1,X1.X2.C3, so repeated instances never collide), and a.subckt's port list carries signal-domain bindings as freely as electrical nodes — an internal block'sin=field bound to an external caller's signal, or an internal block whose own name is the declared port becoming externally addressable under the caller's binding, both fall out of the same node/name substitution with no extra machinery.parse_and_flattenis the one entry point that runs this before either builder.
Full nonlinear semiconductor device physics, behavioral sources, and symbolic (as opposed to numeric) Schur-complement reduction are intentionally future work. The builder reports devices with no stamp at all instead of producing an incomplete matrix.
Initial conditions (ic=)
A storage element may declare the state it starts a transient run in:
C1 b 0 1e-6 ic=5 * 5 V across the capacitor at t = 0
L1 a b 5e-6 ic=12 * 12 A through the inductor at t = 0
MnaBuilder collects these into MnaSystem::initial_conditions without touching A/K/B/u
— an initial condition constrains x at one instant, it does not change the circuit's
equations. MnaSystem::initial_state(values, tolerance) turns them into a starting x in
unknowns order, returning None (not an all-zero vector) for a netlist that declares none, so
a caller keeps its own "start from rest" default untouched.
The .IC directive
The same state can be declared by a .IC line, which is honoured, not accepted-and-dropped:
.IC V(b)=5 * V(b) - V(0) = 5 V at t = 0: identical to ic=5 on a capacitor b-0
.IC V(b,c)=5 * V(b) - V(c) = 5 V: identical to ic=5 on a capacitor b-c
.IC I(L1)=12 * 12 A through L1, first node to second: identical to ic=12 on L1
.IC V(b)=5 I(L1)=12 * several assignments on one line
Each assignment becomes the very same InitialCondition the ic= field produces, so it is
applied by initial_state, checked by the same consistency rules below, and a .IC V(b)=5
beside C1 b 0 1e-6 ic=4 is a ConflictingConditions error, never resolved in favour of
whichever came last. A .IC that names a node no element connects to, ground, an element that
is not an inductor, or anything other than V(...)/I(...) is a build error naming the line
(line N: .IC '<target>' ...). .NODESET, a hint to a DC operating-point solve this crate does
not perform, is reported in warnings as having no effect.
A .IC inside a .subckt body is resolved through parse_and_flatten exactly like the body's
element cards and phys2sig node=/branch= fields: a declared port names the caller's
connecting node, an internal node or element name gets the instance's dotted prefix
(.IC V(mid)=5 I(L1)=2 in X1 becomes V(X1.mid), I(X1.L1)), and ground stays ground. Each
instance of the subcircuit gets its own copy, and an unknown target is reported under the
resolved name (.IC 'V(X1.nowhere)' names node 'X1.nowhere', ...).
Sign conventions
A capacitor's ic is the first node's voltage minus the second's. C1 b 0 1e-6 ic=5 means
V(b) - V(0) = 5 V; writing C1 0 b 1e-6 ic=5 declares -5 V on node b instead.
An inductor's ic is the current flowing from its first node to its second node, through the
inductor. L1 a b 5e-6 ic=12 puts 12 A into terminal a and out of terminal b. This is
exactly the sign of the system's own I(L1) unknown, because a branch device's incidence stamp
puts +1 in its first node's KCL row — a positive branch current leaves that node and enters
the element. Writing L1 b a 5e-6 ic=12 therefore declares the opposite physical current,
which is the mistake worth checking for first when an inductor starts a run backwards.
It is an assignment, not a solve
This is what "use initial conditions" means: the operating point is skipped. The declared
states are written into x, every other unknown starts at rest, and the system that actually
gets solved is not touched at all — no element is swapped for a source, nothing is opened or
shorted, and no auxiliary unknown is introduced, so the unknowns ordering (a public contract
of this crate) cannot move.
| unknown | at t = 0 |
|---|---|
an ic-bearing inductor's I(<name>) |
the declared current |
an ic-bearing capacitor's node-voltage difference |
the declared voltage |
everything else — other node voltages, source branch currents, ic-free storage |
0 |
A capacitor's condition is a statement about two unknowns, not one, so the ic-bearing
capacitors are treated as a graph over nodes — one edge per condition — and each connected
component's potentials are propagated from a root at 0: ground when the component touches
ground, otherwise the component's lowest-indexed node, since a floating island's absolute
potential is not something the netlist declared. A series chain and a floating island both come
out right, and the result does not depend on the order the cards appear in.
The returned vector therefore need not satisfy the circuit's algebraic constraints, exactly like
any hand-built starting vector. That is not a defect: a first backward-Euler step re-imposes
them. It is also the visible difference from a constrained operating-point solve, which would
let the rest of the circuit move to accommodate a value the netlist only ever declared about one
element, and would hand back an ic-free capacitor pre-charged by a circuit that has not run
yet.
What is reported rather than silently overridden
ic=values that contradict each other — a loop ofic-bearing capacitors whose declared voltages do not sum to zero — areInitialStateError::ConflictingConditions.- An assignment that violates one of the circuit's own algebraic equations, in which every
unknown is fixed by an
ic=, isInitialStateError::InconsistentWithCircuit. That covers anicon a capacitor wired directly across an ideal voltage source (the source's branch equation already fixes that voltage) and two series inductors whoseicvalues declare different currents (the shared node's KCL row already fixes them equal). Only equations with noKrow are checked, and only those all of whose unknowns are assigned: an equation with a free unknown in it, or with storage in it, is one the circuit can still satisfy on its own, and the first solved step is where that happens.
Device-card parameter checking
general-spice-core hands every token after a device card's node list over uninterpreted, so a
token this crate does not read is one it would otherwise drop in silence — leaving a plausible
waveform for a circuit nobody wrote. Every card this crate has a stamp for is therefore held to
its letter's own grammar, before any indexing or stamping:
| letter | positional parameters accepted |
|---|---|
R, C, L |
exactly one value |
K |
exactly one value, the coupling coefficient |
E, G (classic four-node form) |
exactly one value, the gain |
F, H |
exactly two: a controlling source's name, then a gain |
V, I |
a bare leading DC value and/or DC <value>, an AC <magnitude> [<phase>] specification, and at most one SIN/PULSE/EXP/PWL/SFFM call whose arguments parse as that function's own parameter list |
D |
a model name, an optional area factor, an optional OFF |
key=value fields are checked separately against the (short) list each letter accepts: ic on
C and L, nothing anywhere else. V1 1 0 10 wibble, V1 1 0 SNI(0 10 1000),
V1 1 0 PWL(0 0 1m), R1 a 0 1000 tc1=0.001 and C1 b 0 1e-6 wibble=5 are all build errors
naming the line and the device.
Known limits of that checking
These are the tokens a typo can still hide in. They are listed because the alternative is pretending the check is total:
- A diode's model name. This crate does not stamp a diode from a device model at all (a
Dcard becomes the symbolic{name}_G/{name}_Ioffpair above), so there is no parameter set to check a name against — and even a crate that had one could not settle the question from the netlist alone, because the.modelcard may live behind an.includethis crate never resolves. An unrecognized name would mean "not found here", not "misspelled". - A controlled source's controlling-source name is checked, but later and by a different
error (
UnknownControllingBranch), once the branch index exists. - A symbol where an
ACmagnitude or phase belongs.AC {gain}is a legitimate parameterized magnitude and nothing in the token distinguishes it from a misspelling, so at most two value-shaped tokens are consumed afterAC; a third falls through and is rejected. - Every parameter of a device letter this crate has no stamp for —
M,Q,Jand the rest. AnMcard'sL=1u W=10uis valid netlist text this crate simply has no model for, and those letters are governed byUnsupportedElementPolicy: underErrorthe card is already rejected outright, and underIgnoreWithWarningthe caller has explicitly asked for it to be tolerated with a warning. Field-checking it would turn that tolerance into a hard error, which is a different decision from the one this checking makes. - A switch-assigned element's positional parameters. Its value is replaced wholesale by the
configured on/off resistance, so its own grammar is not this crate's to enforce; its
key=valuefields are still checked.
Block (kind=) lines
The same rule holds for a block line, with no per-kind table to maintain: the block parser
records every key=value field it reads while building the kind= at hand, and a field left
over afterwards — one no code path for that kind consulted, present or not — is rejected as
line N: device '<name>' unknown field '<key>' (kind=<kind> accepts only: ...), listing the
keys that kind did consult. G kind=tf in=U num=[1] den=[1,1] wibble=3 is a build error, not a
transfer function with a comment. Conditionally read fields (up_down=/reset= on a counter,
clamp_lo_in=/clamp_hi_in= instead of clamp_lo=/clamp_hi= on a PID, ic=/y0=) are
accepted exactly when they are read. No kind is exempt: the cscript/pyblock/pyfunc/
octfunc/octblock escape hatches take their configuration from the library or script they
name, not from free-form fields on the netlist line.
Numeric evaluation of source values (NumericMnaSystem)
MnaSystem::evaluate() numerically evaluates a, k, b, and now also each
input's own value (input_values) and the expanded right-hand side (u) —
this matters for a source whose numeric value genuinely changes between
evaluate() calls (a diode's {name}_Ioff, or {name}_G, resolved
differently every simulation timestep by an external solver) as opposed to a
netlist-declared V/I source whose literal value never changes after
parsing. Evaluating an input's value is best-effort: a symbol with no entry
in the values map (e.g. a duty ratio a caller only cares about symbolically
while evaluating unrelated matrices) yields f64::NAN for that input rather
than failing the whole evaluate() call, and contributes 0.0 (not NAN)
to every row of u.
Basic use
use BTreeMap;
use MnaBuilder;
use Dialect;
let netlist = "V1 in 0 1\nR1 in out R\nC1 out 0 C";
let mna = new.build_fragment?;
assert_eq!;
let values = from;
let state_space = mna.evaluate?.to_state_space?;
// state_space.states == ["V(out)"]
# Ok::
Run the complete example with:
Use build_document instead of build_fragment for a normal SPICE file with
a mandatory title line.
Full system: electrical + block/signal-domain graph (build_system)
MnaBuilder::build_fragment above only sees electrical elements. A netlist may also declare
kind=... block/signal-domain statements (PID compensators, PWM modulators, logic, coordinate
transforms — see spice-lsp/docs/GRAMMAR.md §12) and .subckt/X-instance hierarchy. For
those, use build_system instead — it flattens hierarchy, builds the electrical MnaSystem,
and dispatches every block statement, all in one call:
use ;
use Dialect;
let netlist = "V1 in 0 1\nR1 in out R\nC1 out 0 C\n\
ERR kind=const value=0\nPID1 kind=pid in=ERR kp=1 ki=0 kd=0 n=1 clamp_lo=-1 clamp_hi=1";
let system = build_system?;
// system.mna -> the same MnaSystem build_fragment produces
// system.ideal_diodes -> named `D` instances (kind=ideal_diode, or no kind= at all)
// system.ideal_switches -> named ideal-switch instances (kind=ideal_switch)
// system.gates -> each ideal switch's resolved gate-drive signal
// system.blocks -> every `kind=...` instance, in declaration order
# Ok::
This crate does not evaluate the block graph over time — [block_graph] only defines the type
vocabulary (BlockKind, Signal, GateBinding, ...); a sibling dae-runtime crate imports
these types to actually step them through a transient simulation alongside the electrical
solve. Every type and field there is documented — cargo doc --open -p general-mna and start
at the block_graph module.
Converter averaging
Build each topology from the same parsed netlist and override switch names:
use ;
use Dialect;
let netlist = "V1 in 0 Vin\nS1 in sw ctrl 0 ideal\nL1 sw out L\nC1 out 0 C\nR1 out 0 R";
let mut on_options = default;
on_options.set_switch;
let on = with_options
.build_fragment?;
let mut off_options = default;
off_options.set_switch;
let off = with_options
.build_fragment?;
let d = symbol;
let one_minus_d = one - d.clone;
let averaged = average?;
# Ok::
The override applies a resistor between the first two terminals of a named device. This preserves one unknown vector across all phases, which is required for averaging. It also allows an ideal-switch instance to be treated as an idealized educational switch without implementing a MOS compact model.
Python, SymPy, and JavaScript
MnaSystem::to_string_system() returns row-major A, K, B, and expanded
U arrays plus unknown/input names. The expression syntax (+, *, /, and
sqrt) is accepted by SymPy and common JavaScript math-expression libraries.
A future PyO3 wrapper only needs to expose:
build_fragment(source, dialect, switch_states) -> StringMnaSystem
The same DTO can be exported by wasm-bindgen for a browser application. Keep
symbolic matrix reduction in SymPy; use this crate's numeric reduction for an
interactive browser after parameter values are supplied.
Native Python binding
The optional PyO3 module exposes both symbolic MNA construction and native numeric state-space reduction:
PYTHONPATH=python
For a packaged installation, python/pyproject.toml is configured for
Maturin and builds the same elspice_mna._native module.
Verified converter examples
The Python layer uses the Rust binding to construct the exact ON and OFF MNA topologies, reduces each descriptor system symbolically with SymPy, and then performs state-space averaging. Separate textbook Kirchhoff equations provide the verification oracle—generated artifacts are rejected if any symbolic matrix or transfer-function residual is nonzero.
Generated notebooks:
notebooks/buck_state_space_averaging.ipynbnotebooks/boost_state_space_averaging.ipynbnotebooks/buck_boost_state_space_averaging.ipynb
Generated reports:
artifacts/buck_converter_state_space.pdfartifacts/boost_converter_state_space.pdfartifacts/buck_boost_converter_state_space.pdf
Regenerate and verify everything with:
Development
The parser dependency is currently a sibling path so local parser work is used immediately without editing either repository:
= { = "../spice-lsp/servers/core" }
Once general-spice-core has a published version or stable Git tag, replace the path
with that immutable dependency for portable builds.
Quality gates:
Contributor workflow
Repository guidance is in AGENTS.md. Install the file-hygiene,
Rust-formatting, Python-compilation, gotcha-index, and Conventional Commit hooks
once per clone:
Recurring workflows live in .claude/skills, and the dated
continuity log lives in docs/journal.