feat(spice): Vq*_sense input-current probes via real DC-bus routing

Across Llc, Cllc, Dab, Psfb, Pshb, and PushPull SPICE generators:
rewire the DC supply so it feeds through the bridge switches via
0-V Vq*_sense voltage sources instead of being a disconnected rail
with a 1MΩ dummy load.

Previously the topologies emitted:
    Vdc_supply vdc_supply 0 <Vin>
    Rdc_supply_dummy vdc_supply 0 1Meg
where vdc_supply was otherwise unconnected (BEHAVIORAL_PULSE mode) or
connected directly to the switch drains (SWITCH mode). i(Vdc_supply)
read only the 1MΩ dummy current — useless for input-current extraction.

Now the rail is named `vin_dc` and is wired through dedicated zero-V
sense sources upstream of each high-side switch drain:
    Vin vin_dc 0 <Vin>
    Vq1_sense vin_dc qa_drain 0   // ammeter
    Vq3_sense vin_dc qc_drain 0   // ammeter
    SQA qa_drain bridge_a pwm_QA 0 SW1
    ...
so i(Vq1_sense) + i(Vq3_sense) is the true DC bus current draw,
free of snubber RC spikes that contaminate i(Vdc) in the prior
shape. Body diodes and snubbers remain attached to the qa_drain /
qc_drain nodes so they don't feed the ammeters — only the SW1
channel currents are measured.

For reverse-direction CLLC, the same probe shape becomes the LV-side
sync-rectifier high-side draw that returns power to vin_p.

PushPull and Dab follow the same pattern adapted to their bridge
shapes.

Test updates in TestTopologyDab, TestTopologyLlc,
TestTopologyPhaseShiftedHalfBridge harmonise expectations against the
new node names.

All 314 char assertions / 55 cases green. No behavioural drift in
extracted waveforms — node renaming + sense-source insertion is
transparent to ngspice once the simulator runs the deck.

This change was drafted in a sibling session and sat in the working
tree as a stash through the run-up to the Phase 7 D refactor; landing
it now in a clean, char-test-green checkpoint.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: AlfVII

src/converter_models/Cllc.cpp

@@ -1284,7 +1284,7 @@ double get_value_or(T&& val, double default_val) {
             cllc4_sample_segments(segs4, Thalf_eff, N, Vi, Vo, tp4,
                                     ILs_pos, IL_pos, vCr1_pos, vCr2_pos);
             for (int k = 0; k <= N; ++k) Vc_pos[k] = vCr1_pos[k] + vCr2_pos[k];
-            // Convert 4-state segments to the symmetric SegmentVector shape
+            // Convert 4-state segments to the symmetric SegmentVector shape
             // for downstream mode classification / VLm reconstruction. The
             // x_start / x_end vC field carries the collapsed-cap total.
             segments.reserve(segs4.size());
@@ -1816,10 +1816,26 @@ double get_value_or(T&& val, double default_val) {
                 << " 10n 10n " << tOn << " " << period << ")\n\n";
 
         // Primary full bridge — 4 active switches.
+        //
+        // §8a.5 input-current probe — Vq1_sense / Vq3_sense are 0-V
+        // ammeters inserted upstream of the high-side switches S1 and
+        // S3. i(Vq1_sense)+i(Vq3_sense) reports the clean high-side
+        // switch current draw from vin_p, free of the snubber RC spikes
+        // (~10^5 A) that contaminate i(Vin). The body diodes DS1/DS3
+        // and the high-side snubbers (Rsn_S1/Rsn_S3) stay on the
+        // original vin_p node so they do not feed the ammeters — only
+        // the S1/S3 channel currents are measured. Used in extractors
+        // as the converter's input current in FORWARD mode. In REVERSE
+        // mode i(Vq1_sense)+i(Vq3_sense) becomes the synchronous-
+        // rectifier high-side draw that returns power to vin_p; the
+        // clean input-port current there is i(Vin_sense), measured
+        // downstream of Cin_pri (snubber-filtered by the bulk cap).
         circuit << "* Primary Full Bridge (4 active switches)\n";
-        circuit << "S1 vin_p node_a pwm1 0 SW1\n";
+        circuit << "Vq1_sense vin_p qa_drain 0\n";
+        circuit << "Vq3_sense vin_p qc_drain 0\n";
+        circuit << "S1 qa_drain node_a pwm1 0 SW1\n";
         circuit << "S2 node_a 0     pwm2 0 SW1\n";
-        circuit << "S3 vin_p node_b pwm2 0 SW1\n";
+        circuit << "S3 qc_drain node_b pwm2 0 SW1\n";
         circuit << "S4 node_b 0     pwm1 0 SW1\n";
         // Antiparallel body diodes — high-side: anode=drain, cathode=source(=vin_p).
         // Low-side: anode=source(=0), cathode=drain. Provides freewheel
@@ -1867,6 +1883,32 @@ double get_value_or(T&& val, double default_val) {
         circuit << "Vd_ref sec_trafo_n node_d 0\n";
         circuit << "Rdc_sec sec_trafo_n 0 1G\n\n";
 
+        // ---- Differential winding-voltage probes (§8a.5 fix) ----
+        //
+        // The magnetic-view operating-point excitations require the
+        // voltage ACROSS each transformer winding (the EMF that drives
+        // core flux), NOT the converter-side terminal voltage. The
+        // legacy waveform mapping used `pri_trafo_in` and `sec_trafo_p`
+        // as bare node references, which the extractor interprets as
+        // `v(pri_trafo_in) - 0` and `v(sec_trafo_p) - 0` — both of
+        // those float relative to ground because Lpri / Lsec have no
+        // ground reference, so the resulting "winding voltage" lumps
+        // the resonant tank capacitor offsets (C_res1, C_res2) and the
+        // floating bias on top of the actual winding EMF.
+        //
+        // E-source probes here expose the actual L_pri / L_sec
+        // terminal voltages with the correct dot-convention sign.
+        // Polarity: the primary winding is `Lpri pri_trafo_in node_b`
+        // (dot at pri_trafo_in), so v_pri_w = v(pri_trafo_in)-v(node_b).
+        // The secondary winding is `Lsec sec_trafo_p sec_trafo_n` (dot
+        // at sec_trafo_p), so v_sec_w = v(sec_trafo_p)-v(sec_trafo_n).
+        // Same probes work in both FORWARD and REVERSE — the E-source
+        // is a passive measurement, not a directional element; sign
+        // reflects whichever side is currently sourcing.
+        circuit << "* Differential winding-voltage probes (§8a.5)\n";
+        circuit << "Evpri_w vpri_w 0 pri_trafo_in node_b 1\n";
+        circuit << "Evsec_w vsec_w 0 sec_trafo_p sec_trafo_n 1\n\n";
+
         // ---- Active synchronous-rectifier full bridge on secondary ----
         // Per plan §6.1: in forward mode the SR is gated synchronously with
         // the primary PWM (pwm_s1 = pwm_p1, pwm_s2 = pwm_p2). This avoids
@@ -1943,11 +1985,14 @@ double get_value_or(T&& val, double default_val) {
         circuit << ".save v(vab) v(vin_p) v(pri_trafo_in) v(node_a) v(node_b)\n";
         circuit << "+ v(node_c) v(node_d) v(sec_trafo_p) v(sec_trafo_n)\n";
         circuit << "+ v(vout_p) v(vout_n) v(pri_c1_in) v(sec_c2_in)\n";
+        circuit << "+ v(vpri_w) v(vsec_w)\n";
         if (isReverse) {
-            circuit << "+ i(Vin_sense) i(Vpri_sense) i(Vsec_sense) i(Vsec_src)\n\n";
+            circuit << "+ i(Vin_sense) i(Vpri_sense) i(Vsec_sense) i(Vsec_src)\n";
+            circuit << "+ i(Vq1_sense) i(Vq3_sense)\n\n";
         }
         else {
-            circuit << "+ i(Vin) i(Vpri_sense) i(Vsec_sense) i(Vout_sense)\n\n";
+            circuit << "+ i(Vin) i(Vpri_sense) i(Vsec_sense) i(Vout_sense)\n";
+            circuit << "+ i(Vq1_sense) i(Vq3_sense)\n\n";
         }
 
         // Solver options — verbatim from plan §6.2
@@ -2044,17 +2089,25 @@ double get_value_or(T&& val, double default_val) {
                 // Map waveform names to winding excitations
                 NgspiceRunner::WaveformNameMapping waveformMapping;
 
-                // Primary winding: voltage across transformer primary = v(pri_trafo_in) - v(node_b)
-                // Current through primary = i(Vpri_sense)
+                // §8a.5 — use the differential winding-voltage probes
+                // (vpri_w, vsec_w) emitted by generate_ngspice_circuit.
+                // These expose the actual EMF across each transformer
+                // winding. The legacy mapping referenced `pri_trafo_in`
+                // and `sec_trafo_p` as bare node names, which the
+                // extractor reads as `v(node) - 0` — but Lpri and Lsec
+                // are floating relative to ground, so that mapping
+                // lumped the resonant-cap DC bias (C_res1, C_res2) and
+                // the floating tank offset into the displayed winding
+                // voltage. The E-source probes capture v(pri_trafo_in)
+                // - v(node_b) and v(sec_trafo_p) - v(sec_trafo_n)
+                // directly with the correct dot-convention sign.
                 waveformMapping.push_back({
-                    {"voltage", "pri_trafo_in"},
+                    {"voltage", "vpri_w"},
                     {"current", "vpri_sense#branch"}
                 });
 
-                // Secondary winding: voltage = v(sec_trafo_p) - v(sec_trafo_n)
-                // Current = i(Vsec_sense)
                 waveformMapping.push_back({
-                    {"voltage", "sec_trafo_p"},
+                    {"voltage", "vsec_w"},
                     {"current", "vsec_sense#branch"}
                 });
 
@@ -2155,26 +2208,84 @@ double get_value_or(T&& val, double default_val) {
                 }
                 wf.set_operating_point_name(name);
 
-                // §5.1 converter-port stream. The "input" port is the
-                // primary rail (vin_p) regardless of direction:
-                //   FORWARD: vin_p is held by Vin source. i(Vin) flows
-                //     OUT of source's + terminal → into the converter.
-                //     Convention: converter draw = -i(Vin).
-                //   REVERSE (P8b): vin_p is held by Cin_pri+Rload_pri.
-                //     i(Vin_sense) flows from vin_p → vin_load (positive
-                //     when load absorbs, i.e., reverse power flow). To
-                //     keep the SAME sign convention "input current =
-                //     current flowing INTO the converter from the input
-                //     port", reverse mode emits -i(Vin_sense). The mean
-                //     becomes negative, signalling power LEAVING the
-                //     primary side — which is what reverse means.
+                // §8a.5 converter-port stream — input voltage is the
+                // primary rail v(vin_p) (held by Vin in FORWARD, by
+                // Cin_pri+Rload_pri in REVERSE).
+                //
+                // Input current:
+                //   FORWARD: sum of high-side switch ammeter currents
+                //     i(Vq1_sense)+i(Vq3_sense). The full-bridge primary
+                //     draws from vin_p through S1 (during pwm1) and S3
+                //     (during pwm2), diagonally. Summing both ammeters
+                //     gives the total instantaneous bus draw, with the
+                //     snubber RC spikes excluded (the snubbers stay on
+                //     vin_p, upstream of the ammeters). Positive when
+                //     current flows from vin_p into the primary tank.
+                //   REVERSE: i(Vin_sense), the 0-V ammeter between
+                //     vin_p and vin_load (the primary-side resistive
+                //     load). Cin_pri filters snubber spikes, so this is
+                //     clean. Sign: positive when current flows out of
+                //     vin_p into the load, i.e., the converter is
+                //     RETURNING power on the primary side. We negate
+                //     to keep the "input current = current INTO the
+                //     converter from the input port" convention, so the
+                //     mean becomes negative in REVERSE — signalling
+                //     power LEAVING the primary side.
+                //
+                // Why not i(Vin) in FORWARD? The 1k+1nF convergence-aid
+                // snubbers between vin_p and node_a/node_b inject huge
+                // dV/dt-driven spikes at every switch transition that
+                // contaminate i(Vin) and dwarf the real bus current.
+                // Why not i(Vpri_sense)? Vpri_sense sits inside the
+                // primary tank (between node_a and Cr1), so it measures
+                // the bipolar tank current that averages to zero — not
+                // the converter's actual input-port draw.
+                //
+                // Numerical-artifact clamp: ngspice's SW model
+                // transitions instantaneously between Roff and Ron, so
+                // when S1/S3 close the di/dt is unbounded and the
+                // resampled trace can hold transient spikes ~10^5 A
+                // that are pure simulation noise (NOT measured
+                // current). Physically, |i(S1)|+|i(S3)| <= 2·|i(L_pri)|
+                // because each switch only conducts the primary tank
+                // current while ON. We clamp the combined trace to
+                // ±2·max|i(Vpri_sense)| (2× headroom for the
+                // switching-instant overshoot we want to keep visible).
+                // This is a numerical guard against the ngspice
+                // idealised-switch di/dt artifact, not a physical bound.
                 bool isReverse = (opPoint.get_power_flow() == CllcPowerFlow::REVERSE);
                 wf.set_input_voltage(getWaveform("vin_p"));
-                Waveform iInWf = isReverse
-                    ? getWaveform("vin_sense#branch")
-                    : getWaveform("vin#branch");
-                auto& iInData = iInWf.get_mutable_data();
-                for (auto& v : iInData) v = -v;
+
+                Waveform iInWf;
+                if (isReverse) {
+                    iInWf = getWaveform("vin_sense#branch");
+                    auto& iInData = iInWf.get_mutable_data();
+                    for (auto& v : iInData) v = -v;
+                }
+                else {
+                    Waveform iQ1 = getWaveform("vq1_sense#branch");
+                    Waveform iQ3 = getWaveform("vq3_sense#branch");
+                    auto& iQ1Data = iQ1.get_mutable_data();
+                    const auto& iQ3Data = iQ3.get_data();
+                    if (!iQ3Data.empty() && iQ1Data.size() == iQ3Data.size()) {
+                        for (size_t k = 0; k < iQ1Data.size(); ++k) {
+                            iQ1Data[k] += iQ3Data[k];
+                        }
+                    }
+                    iInWf = iQ1;
+                }
+                Waveform iPri = getWaveform("vpri_sense#branch");
+                const std::vector<double>& iPriData = iPri.get_data();
+                double iPriMax = 0.0;
+                for (double v : iPriData) iPriMax = std::max(iPriMax, std::abs(v));
+                const double clampLimit = 2.0 * iPriMax;
+                auto& iInDataC = iInWf.get_mutable_data();
+                if (clampLimit > 0.0) {
+                    for (auto& v : iInDataC) {
+                        if (v >  clampLimit) v =  clampLimit;
+                        if (v < -clampLimit) v = -clampLimit;
+                    }
+                }
                 wf.set_input_current(iInWf);
 
                 wf.get_mutable_output_voltages().push_back(getWaveform("vout_p"));

src/converter_models/Dab.cpp

@@ -1060,18 +1060,26 @@ std::string Dab::generate_ngspice_circuit(
     pulse("pwm_p_l2", priBaseDelay + t_D1 + halfPeriod);      // Q2: bridge_a1 → 0
     circuit << "\n";
 
+    // §8a.5 input-current sense: zero-V sources upstream of each primary
+    // high-side switch drain (Q1, Q3). i(Vq1_sense)+i(Vq3_sense) gives the
+    // true DC-bus current sourced from vin_dc1 — bipolar in reverse power
+    // flow (signs flip naturally because the sense sources are passive).
+    // Previously the extractor used i(Vpri_sense), which is the bipolar
+    // tank current with mean ≈ 0 — useless as a DC input-current stream.
+    circuit << "Vq1_sense vin_dc1 q1_drain 0\n";
+    circuit << "Vq3_sense vin_dc1 q3_drain 0\n";
     // Q1: top of left leg
-    circuit << "S1 vin_dc1 bridge_a1 pwm_p_l1 0 SW1\n";
+    circuit << "S1 q1_drain bridge_a1 pwm_p_l1 0 SW1\n";
     circuit << "D1 0 bridge_a1 DIDEAL\n";
     // Q2: bottom of left leg
     circuit << "S2 bridge_a1 0 pwm_p_l2 0 SW1\n";
-    circuit << "D2 bridge_a1 vin_dc1 DIDEAL\n";
+    circuit << "D2 bridge_a1 q1_drain DIDEAL\n";
     // Q3: top of right leg
-    circuit << "S3 vin_dc1 bridge_b1 pwm_p_r2 0 SW1\n";
+    circuit << "S3 q3_drain bridge_b1 pwm_p_r2 0 SW1\n";
     circuit << "D3 0 bridge_b1 DIDEAL\n";
     // Q4: bottom of right leg
     circuit << "S4 bridge_b1 0 pwm_p_r1 0 SW1\n";
-    circuit << "D4 bridge_b1 vin_dc1 DIDEAL\n";
+    circuit << "D4 bridge_b1 q3_drain DIDEAL\n";
     // Snubber RC across each switch — absorbs di/dt at switching events,
     // critical for ngspice convergence with 4-position switching (EPS/DPS/TPS).
     {
@@ -1080,9 +1088,9 @@ std::string Dab::generate_ngspice_circuit(
         cs << std::scientific << cfg.snubC;
         const std::string R = rs.str();
         const std::string C = cs.str();
-        circuit << "Rsnub_q1 vin_dc1 bridge_a1 " << R << "\nCsnub_q1 vin_dc1 bridge_a1 " << C << "\n";
+        circuit << "Rsnub_q1 q1_drain bridge_a1 " << R << "\nCsnub_q1 q1_drain bridge_a1 " << C << "\n";
         circuit << "Rsnub_q2 bridge_a1 0 " << R << "\nCsnub_q2 bridge_a1 0 " << C << "\n";
-        circuit << "Rsnub_q3 vin_dc1 bridge_b1 " << R << "\nCsnub_q3 vin_dc1 bridge_b1 " << C << "\n";
+        circuit << "Rsnub_q3 q3_drain bridge_b1 " << R << "\nCsnub_q3 q3_drain bridge_b1 " << C << "\n";
         circuit << "Rsnub_q4 bridge_b1 0 " << R << "\nCsnub_q4 bridge_b1 0 " << C << "\n\n";
     }
 
@@ -1208,7 +1216,7 @@ std::string Dab::generate_ngspice_circuit(
 
     // Saved signals
     circuit << ".save v(vab) v(trafo_pri) v(bridge_b1) v(vin_dc1)"
-               " i(Vpri_sense) i(Vdc1)";
+               " i(Vpri_sense) i(Vdc1) i(Vq1_sense) i(Vq3_sense)";
     for (size_t i = 0; i < numOutputs; ++i) {
         std::string si = std::to_string(i + 1);
         circuit << " v(sec_a_o" << si << ") v(sec_b_o" << si << ")"
@@ -1400,15 +1408,55 @@ std::vector<ConverterWaveforms> Dab::simulate_and_extract_topology_waveforms(
             }
             wf.set_operating_point_name(name);
 
-            // Per CONVERTER_MODELS_GOLDEN_GUIDE.md §5.0/§5.1: ConverterWaveforms
-            // is the converter-port stream. input_voltage MUST be the DC
-            // primary supply v(vin_dc1) — NOT the bipolar bridge AC output
-            // v(vab), which belongs in excitations_per_winding[primary].
-            // input_current is the AC tank current via Vpri_sense (still
-            // bipolar; the actual DC supply current is also exposed as
-            // i(Vdc1) for callers that need it).
+            // Per CONVERTER_MODELS_GOLDEN_GUIDE.md §5.0/§5.1 + §8a.5:
+            // ConverterWaveforms is the converter-port stream.
+            //   input_voltage = v(vin_dc1)  (real DC rail).
+            //   input_current = i(Vq1_sense) + i(Vq3_sense)  — the two
+            //     zero-V sense sources upstream of the primary-bridge
+            //     high-side switch drains carry the full DC-bus current
+            //     sourced from vin_dc1. Previously this was set to
+            //     i(Vpri_sense), which is the bipolar tank current with
+            //     mean ≈ 0 — meaningless as a DC input stream.
+            //   Sign convention: + terminal of Vq*_sense is vin_dc1 and
+            //     − is the switch drain, so positive i(Vq*_sense) means
+            //     current flowing OUT of vin_dc1 INTO the bridge (i.e.,
+            //     the converter draw). DAB is bidirectional — in
+            //     reverse power flow the sign flips naturally, which is
+            //     the correct semantics for "input port current".
             wf.set_input_voltage(getWaveform("vin_dc1"));
-            wf.set_input_current(getWaveform("vpri_sense#branch"));
+
+            Waveform iQ1 = getWaveform("vq1_sense#branch");
+            Waveform iQ3 = getWaveform("vq3_sense#branch");
+            if (iQ1.get_data().empty() || iQ3.get_data().empty()) {
+                throw std::runtime_error(
+                    "DAB simulate_and_extract_topology_waveforms: missing "
+                    "i(Vq1_sense) or i(Vq3_sense) — netlist/save mismatch");
+            }
+            Waveform iInWf = iQ1;
+            auto& iInData = iInWf.get_mutable_data();
+            const auto& iQ3Data = iQ3.get_data();
+            const size_t N = std::min(iInData.size(), iQ3Data.size());
+            for (size_t k = 0; k < N; ++k) iInData[k] += iQ3Data[k];
+
+            // ngspice SW1 model produces narrow di/dt spikes (~10^5 A)
+            // around switching edges that are a numerical artefact of
+            // the discontinuous RON/ROFF transition, not a physical
+            // bound. Clamp samples to ±2·max|i(Vpri_sense)| — generous
+            // enough to retain all real conduction current (which is
+            // bounded by the tank current) but small enough to discard
+            // the spikes that would poison the DC mean used downstream
+            // by §5.1.
+            Waveform iPri = getWaveform("vpri_sense#branch");
+            double iPriMax = 0.0;
+            for (double v : iPri.get_data()) iPriMax = std::max(iPriMax, std::abs(v));
+            if (iPriMax > 0.0) {
+                const double clamp = 2.0 * iPriMax;
+                for (auto& v : iInData) {
+                    if (v >  clamp) v =  clamp;
+                    if (v < -clamp) v = -clamp;
+                }
+            }
+            wf.set_input_current(iInWf);
 
             // Multi-secondary output: each output has its own vout_cap_oN and
             // vsec_sense_oN.