Expand description
Modified nodal analysis (MNA) for educational circuit tools.
The crate consumes the dialect-neutral AST from general-spice-core and builds
the descriptor equation
A x(t) + K dx(t)/dt = B u(t)A is the memoryless matrix (often called G), K is the storage
matrix (often called C), and B maps independent sources into the
equation. Matrices contain Expression values so downstream Python,
SymPy, JavaScript, and PDF layers can preserve component names.
Every public item is documented — cargo doc --open is a complete
reference; reading the source should never be necessary just to call
this crate. Start with MnaBuilder for parsing a netlist into an
MnaSystem, average for converter-phase averaging, and
block_graph for the signal-domain block vocabulary consumed by
dae-runtime.
Modules§
- block_
graph - The block/signal-domain type vocabulary:
BlockKind/BlockInstance(one named block and what it computes),Signal(where a block’s input comes from),GateBinding(how a an ideal switch’s gate state resolves from a block’s output),Phys2SigTarget/PidClamp(the twoBlockKindvariants complex enough to need their own payload type). Moved here fromdae-runtime(Phase 2 of the format-unification plan — seegeneral-simulator’s owndocs/journal/):general-mnais now the single place a netlist’s meaning is built, both electrical (MnaSystem, unchanged) and signal-domain (this module) —dae-runtimeonly evaluates a graph of these types over time, it doesn’t define what they are or parse them out of source text anymore.
Structs§
- Build
Options - Options controlling matrix construction.
- Device
Annotation - One registered
key=valuefield read off a device card and carried through unexamined. - Matrix
- A compact row-major dense matrix.
- MnaBuilder
- Builds MNA systems from
general-spice-corestatements or netlist text. - MnaSystem
- A symbolic MNA descriptor system.
- Numeric
MnaSystem - Numerically evaluated descriptor system.
- Numeric
State Space - Explicit state-space system
dot(x) = A*x + B*u. - PwlPoints
- A breakpoint list for
TransientFunction::Pwl— heap-allocated (unlike every other variant’s plainf64fields): a realPWLsource can have an arbitrary number of breakpoints, and a fixed-capacity inline array sized for a generous case would make everyTransientFunctionvalue pay for that space even for a plainSIN/PULSE/EXP/SFFM(clippy::large_enum_variantflags exactly this). - String
MnaSystem - Serialization-neutral string representation for language bindings.
- Symbolic
State Space - Explicit symbolic state-space system
dot(x) = A*x + B*u. - Symbolic
Transfer Function - A rational transfer function
G(s) = numerator(s) / denominator(s)between one reduced state variable and one independent source. - System
- The result of
build_system: everything a simulator needs, already split into its own electrical (mna/ideal_diodes/ideal_switches/gates) and signal-domain (blocks) halves. - Weighted
Phase - One topology and its fraction of the switching period.
Enums§
- Averaging
Error - Error returned by converter averaging helpers.
- Build
Error - Error returned while parsing or stamping a netlist.
- Evaluation
Error - Error returned while numerically evaluating an expression.
- Expression
- A small symbolic expression tree used in MNA stamps.
- Initial
Condition - One
ic=(or.IC) initial condition, already resolved against this system’s own unknown ordering. - Initial
State Error - Why a netlist’s declared
ic=values could not be turned into a starting state vector. - State
Space Error - Error returned during descriptor-to-state-space reduction.
- Switch
State - State assigned to an idealized converter switch.
- Transfer
Function Error - Error returned when deriving a transfer function from a
SymbolicStateSpace. - Transient
Function - One parsed transient-function call, in the same field order and names ngspice/Xyce use.
- Unsupported
Element Policy - Treatment of parsed devices for which this linear MNA crate has no stamp.
Constants§
- DEFAULT_
INITIAL_ STATE_ TOLERANCE - Default residual tolerance for
MnaSystem::initial_state’s consistency check, relative to the magnitude of the constraint row being checked. Matches the magnitude the state-space reduction in this module is normally called with; pass an explicit value for a circuit whose element values span a very different range.
Functions§
- average
- Produces the weighted descriptor model of converter phases.
- build_
system - Parses
sourceunderdialectand builds the completeSystem— the one entry point a simulator needs; no parsing code of its own required downstream. Electrical statements go through the existingMnaBuildermachinery unchanged; block/signal-domain statements (Statement::BlockInstance) are dispatched bybuild_kindinto anideal_diode/ideal_switch/block entry, keyed by the statement’s own name. - faddeev_
leverrier - Computes the characteristic polynomial and adjugate of
sI - afor an arbitraryn x nsymbolic matrix, via the Faddeev-LeVerrier recursion. - parse_
and_ flatten - Parses
sourceunderdialectand flattens every.subckt/X-instance into one flat, dotted-path-named statement list (seehierarchy::flatten) — the shared first step behindbuild_systemand behind any downstream consumer (e.g.dae-runtime) that needs to build its ownMnaSystemfrom the same, already-hierarchy-resolved statements rather than re-parsing raw text (and silently losing hierarchy) itself. - small_
signal_ duty_ input - Computes the steady-state duty-perturbation column for two phases.