Skip to main content

Crate dae_runtime

Crate dae_runtime 

Source
Expand description

Assembles a circuit’s linear MNA system (via general-mna, including its 'D' stamp) with PWL device segments (via pwl-devices) into one Linear Complementarity Problem, solves it (via lcp-solver), and reports the resolved DC operating point. No Newton-Raphson, no voltage limiting, anywhere in this crate — see this repository’s docs/architecture.md.

§The generic Thevenin/LCP fold

general-mna stamps each diode k as a fixed conductance {k}_G plus a per-instance current-source symbol {k}_Ioff. Fixing {k}_G at the diode’s canonical reference slope g_off (see pwl_devices::IdealDiode::canonical) makes the whole linear system A0 genuinely fixed — independent of which segment every diode ends up in — with every segment’s actual nonlinearity pushed entirely into the {k}_Ioff terms via each diode’s canonical max(0, ...) (z) decomposition. Since the system is linear in those Ioff terms, each diode’s terminal voltage is an affine function of every diode’s z variables:

x(z)   = x0 + sum_j w_j * raw_Ioff_j                  (raw_Ioff_j = delta_on_j*z2_j - delta_br_j*z1_j)
V_k(z) = v0_k + sum_j gamma_kj * raw_Ioff_j            (gamma_kj = w_j[p_k] - w_j[n_k])

where x0 = solve(A0, u0) is the baseline operating point with every diode’s Ioff = 0, and w_j = solve(A0, B[:, diode j's input column]) is how much a unit “raw Ioff” on diode j moves every unknown. Substituting V_k(z) into each diode’s guard equations (w1_k = V_k - v_breakdown_k + z1_k, w2_k = v_f_k - V_k + z2_k) gives exactly the LCP (M, q) this crate builds and hands to lcp_solver::solve.

Modules§

checkpoint
Checkpoint/resume: a complete, serializable snapshot of a transient run’s loop-carried state, so a run can stop at some $t$ and continue later — from the same process, from a file, on another machine — with a trace bit-identical to the uninterrupted run.

Structs§

AdaptiveConfig
Parameters for [lte_attempt]’s local-truncation-error step-size control.
BlockInstance
One named block instance and where its inputs (if any) come from. Const/Pwc/Pwl/Waveform/Phys2Sig blocks must have zero inputs; Sum/Product need one input per sign/factor; Gain/ StateSpace/TransferFunction/Vco/Saturation/Table/MathFn1/Sig2Phys each need exactly one; Pid needs exactly one (the error signal) when its clamp is PidClamp::Fixed, or exactly three (error, clamp_lo, clamp_hi, in that order) when PidClamp::Dynamic; MathFn2 needs two; MathFn3 needs three; CoordinateTransform needs kind.input_count() (3 for Clarke/ClarkeInv, 4 for the others — see continuous_blocks::CoordinateTransform::input_count); Pmsm needs exactly three (vd, vq, t_load, in that order). Evaluated once per step in the causal order topological_order (in dae-runtime) derives from the slice’s own Signal::Block dependency graph — not the order the slice happens to be given in; a Signal::Block input may name any block in the same slice regardless of declared position (source blocks, naturally, need none, and a genuine cycle among these edges is rejected as DaeError::AlgebraicLoop before any step runs — see topological_order’s own doc comment for how).
CheckpointControl
How a run interacts with checkpoints — see simulate_transient_with_blocks_checkpointed.
OperatingPoint

Enums§

BlockKind
One block’s behavior. Const/Pwc/Pwl/Sin/Pulse/Exp/Sffm are sources (zero inputs); Sum/Gain are stateless (recomputed fresh from their inputs every step); Pid/StateSpace/TransferFunction/Vco carry their own state forward across steps.
ConstValue
A BlockKind::Const’s own fixed value.
DaeError
GainValue
A BlockKind::Gain’s own scale factor — a plain scalar (the only form before vector signals existed, unchanged), or a fixed M x N matrix (row-major, matrix[row][col]) for a genuine matrix-vector product.
GateBinding
How one ideal switch’s gate state is resolved, every step: always from a named block’s current output, on while it’s >= 0.5. No non-block-driven variant exists — even a permanently-off gate is an explicit Const(0.0) wired through a domain=voltage BlockKind::Sig2Phys, the same as every other gate — and no bare carrier-comparator variant exists either: that comparison now lives entirely inside gate-driving BlockKinds themselves (BlockKind::Pwm/BlockKind::PhaseShiftPwm, or a hand-built chain of ordinary blocks), so GateBinding has exactly one job — reading a number and thresholding it — regardless of what produced that number: a modulator’s own main/complement output, a BlockKind::Hysteresis block (no carrier at all, event-driven bang-bang switching), or any other block a caller composes.
GateState
State assigned to an idealized converter switch.
Phys2SigTarget
What a BlockKind::Phys2Sig reads from the circuit’s own previous-step operating point — V(node) or I(branch), anything OperatingPoint::value (in dae-runtime) accepts, keyed by exactly the same V(...)/I(...) naming convention general-mna itself uses for MNA unknowns.
PhysicalDomain
Which physical quantity a BlockKind::Sig2Phys converter drives. Purely a type-level tag for the enforcement sites in dae-runtime (DaeError::GateTargetNotSig2Voltage, DaeError::SourceNotSig2PhysicalConverter) — evaluation itself (value = input) is identical for both.
PidClamp
A BlockKind::Pid’s anti-windup bound: fixed at model-build time, or read fresh from the graph every step. Fixed is every existing use of Pid before this variant existed — unchanged behavior, one input (the error signal) as always. Dynamic is for a controller whose achievable output range genuinely depends on other, still-evolving state (e.g. a current-loop PID commanding a pole voltage that can’t physically exceed roughly half the DC bus voltage, itself still rising during a soft-start ramp) — a Fixed bound sized for the final steady-state range is badly oversized early on, so the PID’s own anti-windup never engages even though the real plant is already saturated far below that fixed bound, producing sustained, hard-to-diagnose windup-driven oscillation (worked example: an elspice-pwl-pfc-three-phase-vsc experiment’s own three-phase active-front-end current loop, in the sibling internal-archive repo). Dynamic reads two extra inputs beyond the error signal, in order (clamp_lo, clamp_hi), evaluated fresh every step exactly like any other block input — see BlockInstance’s own doc comment for the resulting input count.
SampleTimeSpec
How a CScript/PyBlock/PyFunction/OctFunc block’s own execution is scheduled, independent of the circuit’s own resolved step (see each BlockKind variant’s own sample_time field).
Signal
Where a block’s input value comes from: another block’s output this same step, or that (or any) block’s own output from the previous step. There is deliberately no variant that reads a circuit quantity (V(node)/I(branch)) directly — that crossing from the physical domain into the signal domain must go through an explicit, named BlockKind::Phys2Sig block instead (referenced afterward like any other block, via Signal::Block). See BlockKind::Phys2Sig’s own doc comment for why this boundary is enforced rather than implicit, the same way a real block-diagram tool requires an explicit physical/signal converter block between a physical port and a signal port instead of wiring them together directly.
SignalValue
The value one named block produces (or one Signal resolves to) at a given step: a bare scalar — everything this graph supported before this variant existed — or a fixed-length vector of scalars. Arity is fixed once a block declares it (known at graph-build time from its own parameters, e.g. a matrix Gain’s own row count, a Const vector literal’s own length, StateSpace’s own C row count) — there is no dynamic/runtime-determined length.
TimeStep
How a transient run picks its step size.
TransientFunction
One parsed transient-function call, in the same field order and names ngspice/Xyce use.

Constants§

ADAPTIVE_STEP_HARD_CAP
Hard ceiling on accepted TimeStep::Adaptive steps for one simulate_transient_with_blocks call — see DaeError::AdaptiveStepStalled’s own doc comment for why this exists. Sized generously above any legitimate run this project has actually needed (the largest real fixed-step run on record is 1,000,000 rows for a 20ms/dt=2e-8 transient; adaptive stepping should need far fewer accepted steps than that to cover the same window) while staying well under what would exhaust a typical machine’s RAM before this check can fire (each row holds every node voltage/branch current/block output as f64s — a few hundred bytes for a medium-sized circuit — so even 10,000,000 rows stays in the hundreds-of-MB-to-low-GB range, not the tens-of-GB range that actually crashed a machine running the unpatched bug this guards against).

Functions§

reject_sig2phys_wired_into_circuit
Rejects a kind=sig2phys converter that was wired into the physical network — i.e. a block whose own name is also used as a node on some element line — before any system is built or any step is solved. See DaeError::Sig2PhysUsedAsCircuitNode for the full rationale; the short version is that a Sig2Phys block has no terminals and stamps nothing, so such a net is an ordinary undriven node that silently solves to 0 instead of failing.
sawtooth_carrier
A free-running sawtooth PWM carrier in [0, 1) at frequency freq_hz. Compare a duty command (also [0, 1]) against this to decide gate state: on while the carrier is below the duty command, off otherwise (a standard trailing-edge PWM comparator).
simulate_closed_loop
Runs a closed-loop transient: at each timestep, measure reads a scalar from the previous step’s OperatingPoint (e.g. an output node voltage), controller (its own state carried forward internally) is stepped with reference(t) - measured as its input via RK4, and pwm(controller_output, t) decides every ideal switch’s gate state for this step from that controller output. Everything else matches crate::simulate_transient_with_ideal_switches (system rebuilt per step, trapezoidal with backward-Euler fallback on any diode-segment or gate-state change).
simulate_transient
simulate_transient_with_blocks
Runs a transient with every ideal switch’s gate resolved from a GateBinding each step — see this module’s doc comment for why there’s no separate “closed-loop” entry point: a device gated by a plain BlockKind::Hysteresis and one gated by a Sum-Pid-BlockKind::PhaseShiftPwm chain that happens to read a BlockKind::Phys2Sig are resolved by exactly the same loop below — every GateBinding is Block(name), reading whatever name’s current output happens to be. step picks fixed or adaptive timing — see TimeStep/[AdaptiveConfig]. Adaptive mode here can’t reuse [step_control::adaptive_step] directly (that assumes a dt-independent system): this circuit’s gate states, and so its system, are themselves a function of dt through the block graph, so a rejected trial has to redo block evaluation and gate resolution at the smaller dt, not just re-solve the same system — see the retry loop below.
simulate_transient_with_blocks_capped
Identical to simulate_transient_with_blocks, with one addition: max_adaptive_steps overrides ADAPTIVE_STEP_HARD_CAP (see DaeError::AdaptiveStepStalled’s own doc comment for what this guards against) instead of always using the built-in default. A separate function, rather than adding a parameter to simulate_transient_with_blocks itself, so this project’s own ~20 existing call sites (mostly tests, positional-argument calls) don’t all need updating for a cap most of them will never want to change — general-simulator-cli’s own --max-steps flag is the intended caller.
simulate_transient_with_blocks_checkpointed
simulate_transient_with_blocks_streamed plus checkpointing: optionally starts from a Checkpoint, optionally hands one out every so often, and optionally returns the run’s final state as one — the exact loop-carried state after the last accepted step, from which a later call continues bit-identically to a run that never stopped. See checkpoint’s own module doc comment for what a snapshot holds and the identity check a resume performs.
simulate_transient_with_blocks_streamed
The actual transient engine — every other simulate_transient_with_blocks* function is a thin wrapper over this one. Calls on_step(t, point, outputs) once per accepted step, in order, and holds nothing beyond one step’s own data itself: a caller that only needs summary statistics, or that writes each row straight to a file/stream as it arrives, never pays for a full in-memory trace the way simulate_transient_with_blocks/_capped do by design (they exist for exactly the callers — mostly this project’s own tests — that want the whole Vec back). on_step returning Err aborts the run immediately with that error.
simulate_transient_with_ideal_switches
Runs a transient simulation of a netlist containing linear devices, ordinary D diodes, and any number of IdealSwitch instances whose gate state can vary over time — a PWM driver, unlike solve_dc_with_ideal_switches’s fixed per-call state. gate_signal(name, t) is called once per ideal switch per timestep to get that instance’s GateState at time t; the caller owns the PWM logic entirely (duty cycle, frequency, phase — this crate has no opinion).
solve_dc
Solves the DC operating point of a netlist containing linear devices plus any number of D (diode) elements, whose piecewise-linear parameters are supplied in diodes (keyed by element name) rather than parsed from the netlist — SPICE’s .model syntax has no notion of this crate’s breakdown/leakage/forward segments.
solve_dc_with_ideal_switches
Solves the DC operating point of a netlist containing linear devices, ordinary D diodes (diodes), and any number of IdealSwitch instances (ideal_switches), each with its own known gate state (see GateState, a re-export of general_mna::SwitchState — the same concept: an exogenous, externally-decided mode, not something the LCP resolves).

Type Aliases§

CheckpointSink
What CheckpointControl::on_checkpoint points at.
TransientWithBlocksStep
One step’s result: (t, OperatingPoint, block_outputs), where block_outputs is every block’s value that step (by name) — useful for plotting a controller’s internal signals (e.g. a Vco’s commanded frequency) without needing to separately re-derive them.