# Simulation: ngspice loop and transient, then TI's PSpice model

We simulated the design three ways:

1. An averaged small-signal model in ngspice to check loop gain and phase margin.
2. A cycle-by-cycle switching model in ngspice to check startup, ripple and load steps at 9, 12 and 16 V.
3. TI's own encrypted TPS54202 transient model in PSpice for TI (downloaded from ti.com by the AI with [Pup](https://wiki.adom.inc/adom/pup-bridge)), to check the first two against the vendor's model of the silicon.

All of it ran from Adom Hydrogen with the [Adom SPICE](https://wiki.adom.inc/adom/adom-spice-skillpack) skills: ngspice in Hydrogen's Linux workspace, and LTspice and PSpice for TI on a Windows PC, driven by the AI through [Adom Bridge](https://wiki.adom.inc/adom/adom-bridge).

Every circuit uses the values from `design/calcs.json` ([design](design.md)): L 15 uH with 118 mOhm DCR, COUT 36.3 uF effective, Rtop 73.6 k, Rbot 10 k, Cff 68 pF, EN 1 M / 150 k.

## Why a fitted model first

TI does not publish the TPS54202's internal compensation. The ngspice models therefore use an equivalent error amplifier, a gm stage (gm x Rc / Ri = 41.6), calibrated so that with no Cff the crossover equals the datasheet's own estimate, equation 14: fo = 3.95 / (VOUT x COUT). We label it as a fitted model, not the part. TI's model in the last section is the check on it.

## 1. Loop gain (ngspice, averaged peak-current-mode model)

The power stage uses the standard peak-current-mode average model: the inductor becomes a current source Vc / Ri into COUT and the load, followed by the sampling double pole at fs / 2. The loop is broken with a Middlebrook injection between VOUT and the divider. Script: `sim/loop.py`.

![Loop gain and phase margin curve at VIN 12 V for Cff 0, 47, 68 and 100 pF](docs/img/loop-gain.png)

Crossover and phase margin at 1 A:

| Cff | 9 V | 12 V | 16 V |
|---|---|---|---|
| 0 pF | 21.48 kHz, 77.9 deg | 21.45 kHz, 76.8 deg | 21.42 kHz, 76.0 deg |
| 47 pF | 24.20 kHz, 101.1 deg | 24.15 kHz, 99.9 deg | 24.11 kHz, 99.0 deg |
| **68 pF (chosen)** | **28.74 kHz, 111.4 deg** | **28.62 kHz, 109.9 deg** | **28.51 kHz, 108.9 deg** |
| 100 pF | 60.36 kHz, 115.0 deg | 57.53 kHz, 113.4 deg | 55.47 kHz, 112.1 deg |

At 0.5 A, every case is within about 1 deg and 0.1 kHz of the 1 A figures. For example, 68 pF at 12 V gives 28.64 kHz and 109.0 deg.

The 100 pF figures show why the datasheet limit wins over the model's best number. The crossover more than doubles, to 55 to 60 kHz, which is past the datasheet's 40 kHz limit. The fitted model cannot see the internal parasitics that limit protects against. With 68 pF the crossover stays under 29 kHz at every input voltage.

## 2. Switching transient (ngspice, cycle by cycle)

This model is a peak-current-mode modulator built from XSPICE parts:

- A 500 kHz clock sets an SR latch. The latch resets when Ri x iL plus the slope ramp reaches Vc, or when iL hits the 2.5 A high-side current-limit minimum.
- The synchronous FETs are switches with the datasheet Rds(on).
- The error amplifier is the same calibrated equivalent as the loop model.
- The 5 ms soft start is a ramp on the reference.

The test: VIN on, a 1 A load from t = 0 (a 10 Ohm resistor plus a switched 10 Ohm step), the step opened at 7 ms (0.5 A) and closed again at 8 ms (back to 1 A). Script: `sim/transient.py`.

| metric | 9 V | 12 V | 16 V |
|---|---|---|---|
| VOUT mean at 1 A | 4.9798 V | 4.9797 V | 4.9796 V |
| VOUT ripple (peak to peak) at 1 A | 2.35 mV | 3.19 mV | 3.88 mV |
| inductor ripple (peak to peak) | 0.298 A | 0.396 A | 0.476 A |
| peak inductor current at startup | 1.177 A | 1.226 A | 1.266 A |
| startup overshoot | 3.7 mV | 3.8 mV | 3.9 mV |
| time to 95 % VOUT | 4.757 ms | 4.757 ms | 4.757 ms |
| overshoot, 1 A to 0.5 A | 78.9 mV | 79.6 mV | 79.8 mV |
| undershoot, 0.5 A to 1 A | 77.8 mV | 78.4 mV | 78.8 mV |
| settling to 1 % after the step up | 196.9 us | 202.6 us | 204.3 us |

![Switching transient at VIN 12 V: startup, load steps, and inductor current with the SW node](docs/img/transient-12v.png)

The switching model agrees with the hand calculation. It gives an inductor ripple of 0.396 A at 12 V against 0.389 A from equation 9, and 0.476 A at 16 V against 0.458 A. Startup is the 5 ms soft-start ramp with no overshoot to speak of. The peak inductor current during startup stays under 1.3 A, far below the 3.7 A saturation current.

<details>
<summary>9 V and 16 V plots</summary>

![Switching transient at VIN 9 V](docs/img/transient-9v.png)

![Switching transient at VIN 16 V](docs/img/transient-16v.png)

</details>

## 3. TI's PSpice model (validation)

TI publishes a transient model for the TPS54202 (package SLVMBJ5, `TPS54202_TRANS.LIB`). It is Cadence-encrypted, so only PSpice can run it; ngspice cannot. It was run in PSpice for TI with `STEADY_STATE=0` on the same external parts, the same 12 V input and the same 1 A to 0.5 A to 1 A steps, and measured with the same code.

![TI encrypted TPS54202 model in PSpice for TI: startup and the load steps](docs/img/ti-pspice-transient.png)

| metric (12 V, 1 A) | fitted ngspice model | TI model |
|---|---|---|
| VOUT mean at 1 A | 4.9797 V | 5.0088 V |
| VOUT ripple (peak to peak) | 3.19 mV | 5.0 mV (1 mV output quantisation) |
| inductor ripple (peak to peak) | 0.396 A | 0.407 A |
| peak inductor current at startup | 1.226 A | 1.226 A |
| time to 95 % VOUT | 4.757 ms | 4.838 ms |
| overshoot, 1 A to 0.5 A | 79.6 mV | 93.2 mV |
| undershoot, 0.5 A to 1 A | 78.4 mV | 90.7 mV |
| settling to 1 % after the step up | 202.6 us | 171.9 us |

What the comparison shows:

- **Startup and the inductor current match.** The startup peak (1.226 A in both) and the inductor ripple (0.40 vs 0.41 A) agree to within about 2 %.
- **The fitted loop under-predicts the load-step deviation by about 15 %** (80 / 78 mV vs 93 / 91 mV).
- **VOUT is closer to nominal in TI's model** (5.009 V vs 4.980 V): TI's model regulates FB to about 0.599 V, the fitted model uses the 0.596 V reference.

## 4. Three simulators, one answer (Adom SPICE dashboard)

The fitted model was written once as a portable netlist and run in ngspice, LTspice and PSpice for TI with the Adom SPICE dashboard, which measures every engine with the same code and overlays the waveforms. TI's own model is shown as a reference that does not vote.

![Adom SPICE dashboard: ngspice, LTspice and PSpice for TI agree on all 8 measurements; TI's model as a reference](docs/img/spice-dashboard.png)

| measurement (12 V) | ngspice | LTspice | PSpice for TI | spread | TI model (reference) |
|---|---|---|---|---|---|
| VOUT at 1 A | 4.980 V | 4.980 V | 4.980 V | 0.000 | 5.009 V |
| VOUT ripple | 3.27 mV | 2.71 mV | 3.00 mV | 0.56 (limit 1.0) | 5.0 mV |
| inductor ripple | 0.399 A | 0.391 A | 0.390 A | 0.009 | 0.407 A |
| startup peak current | 1.227 A | 1.226 A | 1.226 A | 0.001 | 1.226 A |
| time to 95 % | 4.757 ms | 4.757 ms | 4.757 ms | 0.000 | 4.838 ms |
| overshoot, 1 A to 0.5 A | 79.41 mV | 79.43 mV | 79.28 mV | 0.16 | 93.21 mV |
| undershoot, 0.5 A to 1 A | 78.45 mV | 78.34 mV | 78.77 mV | 0.43 | 90.68 mV |
| settling to 1 % | 200.5 us | 202.4 us | 198.6 us | 3.9 (limit 15) | 171.9 us |

**All three engines agree on all eight measurements**, so the netlist translations are faithful and the 15 % load-step gap is the fitted model against the silicon model, not a simulator difference. LTspice and PSpice run times are not shown: their licences restrict publishing benchmarks.

## Design conclusion: COUT stays as designed

For this internally compensated part, equation 14 (fo = 3.95 / (VOUT x COUT)) makes fo x COUT a constant. A load step's deviation is roughly dI / (2 pi x fo x COUT), which becomes dI x VOUT / (2 pi x 3.95). COUT cancels out, so the deviation is independent of the output capacitance: about 0.2 V for a full 1 A step.

TI's model agrees. At 1 A its 0.5 A steps (93 and 91 mV) scale to about **185 mV for a 1 A step, 3.7 % of 5 V**.

- Adding output capacitance would lower the crossover and leave the deviation about the same.
- Only a larger Cff would help, and Cff stays at 68 pF to keep the crossover under the datasheet's 40 kHz limit.
- The 3 % step target in `calcs.py` was our own, not part of the brief. 3.7 % is inside the usual +/-5 % window for a 5 V rail.

**COUT is unchanged.** The design has not been built yet. When it is, a real 0 to 1 A step on the bench is the next check.

## Files

| file | what |
|---|---|
| `sim/loop.py`, `sim/loop.json` | averaged loop model, Cff sweep at 9 / 12 / 16 V and 0.5 / 1 A |
| `sim/transient.py`, `sim/transient_{9,12,16}V.json` | cycle-by-cycle switching model and its metrics |
| `sim/ti-pspice-validation.md` | TI model comparison and the design conclusion |
| `sim/transient_{9,12,16}V.png`, `sim/loop.png` | the plots on this page |
