21. Electromagnetic transient (EMT) simulation

The time-domain solver that steps the instantaneous electrical network (L·di/dt, C·dv/dt) at a fixed microsecond timestep — a Dommel nodal companion-model method. It is the counterpart, at the electromagnetic timescale, to the electromechanical swing model of ch. 5 and the frequency-domain harmonic/impedance engines of ch. 19: those work in phasors; EMT resolves the waveform itself. It is a forward simulation about the model — governed, like every Dynamics/ tool, by UnderstandingRestrictions.md as Solving, never inference (ch. 8); it does not engage the estimator's restriction-review gate.

Full design specification: design/emt-time-domain.md. This chapter is the map.

21.1 The method

Dommel's companion model: each reactive element becomes a conductance G_eq in parallel with a history current source, and the real nodal system G·v = i_history + i_sources is solved each step. G is constant between switching events, so it is factored once and back-substituted every step. See design §"Method".

21.2 Companion models (Dynamics/Emt/)

• EmtCompanionStamp / Companion — the trapezoidal and backward-Euler R-L and C rules, unified as I_hist = HistCoeffV·v_prev + HistCoeffI·i_prev. Pure functions, validated to machine epsilon.
• EmtUnits — per-unit L/C from the model's R/X/B (L = X/ω0, C = B/ω0, ω0 = 2π·FrequencyHz); Zbase for physical units when a bus carries a base voltage. Per-unit-only EMT is first-class (BaseKv = 0 runs fine).
• EmtElement — SeriesBranch (R-L), ShuntElement (G/C/L to ground), VoltageSource (Thévenin Norton, or ideal Dirichlet node), CurrentSource (the future converter/Norton seam), SwitchElement (toggling conductance, kept in the pattern).

21.3 The engine (Dynamics/Emt/EmtEngine)

Step(t) assembles the RHS from element history + sources and back-substitutes; Simulate(EmtCase) runs the fixed-step batch loop under GcScope.LowLatency. InitializeRest seeds the rest state (i_L=0, v_C=0) so a source on at t=0 gives the correct step response. Node reduction eliminates Dirichlet (ideal-source) nodes.

21.4 Switching, faults and CDA

EmtEvent/SwitchEvent open/close a SwitchElement on the crossing step; a fault is a bus-to-ground switch closed then cleared. Because switch branches stay in the matrix pattern, an event needs only a numeric re-factor. The trapezoidal Nyquist oscillation a discontinuity would excite is removed by the Critical Damping Adjustment — two backward-Euler dt/2 half-steps across the event — see design §CDA.

21.5 Numerics reused

PowerFlow/AdmittanceStamp + Harmonics/FrequencyDependentYBus (per-parameter matrix rebuild pattern), Numerics/Sparse.CsrMatrix.Builder + Numerics/SparseLu (factor-once / solve-many), Simulation/GcScope. No SPD/Cholesky or public real factor-once seam yet — the engine calls the internal SparseLuFactorization.

21.6 The emt verb

gridsim emt [case] --dt-us N --duration S [--source <bus>] [--amp pu] [--freq Hz] [--probe v:<bus>,i:<f>-<t>] [--event fault:<bus>@<t>:<Rpu>] [--event clear:<bus>@<t>] [--rule trap|be] [--no-cda] [--out <dir>]. Writes a provenance-headed timeseries.csv, summary.md and run-metadata.json. --freq 0 (DC) settles to the resistive solution; AC drives a sinusoid. Modeled on RunTransient; exit codes 0/2/3 (ok/usage/numerical). See the user manual for task guidance.

21.7 Travelling-wave lines, loads

BergeronLine models a lossless distributed line (surge conductance at each end + a delay-buffered history for the wave from the far end; EmtUnits.SurgeParams gives Zc=√(X/B), τ=√(XB)/ω0) — reflections, matched absorption and propagation delay, exactly. FromGridModel models Pd/Qd as constant-impedance shunts (IncludeLoads, default on) and can build charged branches as travelling-wave lines (UseTravellingWaveLines).

21.8 Three-phase (abc) — ThreePhaseEmtEngine

Each bus is three phase nodes; a ThreePhaseBranch stamps the 3×3 companion of its symmetric (self/mutual) R,L matrices, so inter-phase mutual coupling is exact — the difference from three independent circuits, and what reproduces unbalanced faults. Ideal 120°-apart sources, per-phase shunts/loads, and shunt faults (ThreePhaseFault, e.g. single-line-to-ground) are supported; reuses the scalar engine's nodal reduction + SparseLu factor-once path.

21.9 Validation

EmtRlcAnalyticTests (closed-form RLC step response, all three damping regimes, to <1e-5; O(dt²); determinism), EmtSteadyStateTests (DC → resistive solution), EmtSwitchingTests (TRV ≈ 2×V; CDA suppresses the Nyquist chatter), EmtLineTests (matched-line absorption; open-end doubling at τ; reflection at 2τ), ThreePhaseEmtTests (balanced coupled line matches the positive-sequence phasor to <5e-3 with zero-sequence≈0; SLG fault collapses the faulted phase and creates a zero-sequence voltage). The analytic RLC oracle passing is the proof the engine solves the electromagnetic equations correctly.

21.10 Remaining future phase

Converter/machine models behind the current-source/Norton seam (CuratedPlaceholder [VERIFY]); transformer tap; lossy travelling-wave lines; FromGridModel three-phase (needs per-phase sequence data absent from the lake).

See the 1.2.0 entry in CHANGELOG.md for the itemised list.