Running the netlists in ngspice

Intent

• Run a library netlist in batch mode and read its measurements.
• See what an integration rule does to a mode much faster than its time step, and why the trapezoidal rule can ring where the circuit does not.
• Choose the options that make a switching waveform trustworthy.

Theory

Running a netlist

The repository’s sim/ngspice/ folder has each converter case as a netlist for ngspice [ngspice – open source SPICE simulator]. Run ngspice -b buck-ccm.cir and it prints the .meas results of the last period: averages, largest and smallest values of the switch node’s voltage, the inductor current (the flyback’s primary current) and the output voltage. Run ngspice buck-ccm.cir, then run, to plot what the folder’s README lists. CI runs every netlist again and requires each value within one percent of the ideal equations, measured against the quantity’s largest magnitude over the period, and the output settled.

How SPICE steps a circuit

SPICE computes the circuit at a sequence of time points. It chooses each step so that the error it estimates for its integration rule stays within its tolerances, and the relative tolerance is 0.001 unless the netlist sets another [The ngspice team, Ngspice User's Manual]. Between two points, every capacitor and inductor follows the rule that .options method selects: trapezoidal unless told otherwise, or Gear’s method, which uses the backward differentiation formulas, by default up to the second [The ngspice team, Ngspice User's Manual].

What the rule does to a fast mode

A converter’s circuit can have modes far faster than the time step, for example where a diode stops conducting. A one-step rule, such as the trapezoidal rule or backward Euler, multiplies such a mode’s deviation by a fixed factor per step. The trapezoidal rule averages the slopes at both ends of the step:

$$g_\mathrm{TR} = \frac{1 - \frac{\Delta t}{2 \tau}}{1 + \frac{\Delta t}{2 \tau}}$$

$g_\mathrm{TR}$

trapezoidal rule's factor per step

$\Delta t$

time step

$\tau$

time constant

Trapezoidal rule's factor per step on a decaying mode✓ verified by 8 tests

Assumptions, convention and source

Assumptions

• one decaying mode on its own: its rate of change is minus its deviation over tau (the test equation)
• the same time step every step

Notes

the rule averages the slopes at both ends of the step. Its factor stays between -1 and 1 for any step (the rule is A-stable), but a step much longer than $\tau$ gives a factor close to -1: the mode is hardly damped and changes sign every step, a ringing from one step to the next that the circuit does not have. ngspice integrates with this rule unless told otherwise

Source

Hairer & Wanner 1996, Sec. IV.3 (Stability Function of Implicit RK-Methods: the trapezoidal rule is A-stable, |R| tends to 1); derived here; The ngspice team, Ngspice User's Manual, .options, transient analysis: METHOD, trapezoidal by default

Derivation

step-by-step sympy derivation

Equation id

num.gain_tr · equations.yaml entry

Its factor stays within one in size for any step, so the solution does not blow up, but for a step much longer than the mode’s time constant it approaches minus one: the mode barely decays and flips its sign at every time point, a ringing that the circuit does not have [Hairer & Wanner 1996]. The first of the backward differentiation formulas that Gear’s method uses is backward Euler, which takes the slope at the end of the step:

$$g_\mathrm{BE} = \frac{1}{1 + \frac{\Delta t}{\tau}}$$

$g_\mathrm{BE}$

backward Euler's factor per step

$\Delta t$

time step

$\tau$

time constant

Backward Euler's factor per step on a decaying mode✓ verified by 8 tests

Assumptions, convention and source

Assumptions

• one decaying mode on its own: its rate of change is minus its deviation over tau (the test equation)
• the same time step every step

Notes

the rule takes the slope at the end of the step. Its factor lies between 0 and 1 for any step and tends to zero as the step grows (the rule is L-stable): a mode much faster than the step is almost gone after one step, without ringing. It is the first of the backward differentiation formulas, which ngspice uses, up to the second by default, when .options method=gear asks for Gear's method

Source

Hairer & Wanner 1996, Sec. IV.3 (implicit Euler is L-stable) and Ch. V (Multistep Methods for Stiff Problems: backward differentiation formulas, the first of which is implicit Euler); derived here; The ngspice team, Ngspice User's Manual, .options, transient analysis: METHOD=gear, and MAXORD, 2 by default

Derivation

step-by-step sympy derivation

Equation id

num.gain_be · equations.yaml entry

Its factor tends to zero instead, so such a mode is almost gone after a single step [Hairer & Wanner 1996], and the second formula, too, damps it away within a few steps [Hairer & Wanner 1996, Ch. V].

What the library found

With ngspice’s defaults, the trapezoidal rule and a relative tolerance of 0.001, the library’s DCM flyback shows exactly this: once the diode stops conducting, the secondary current rings through zero from one step to the next, and the drain voltage swings to about a kilovolt below zero. Gear’s method at the same tolerance removes the ringing, but the diode’s current still overshoots through zero as its conduction ends, and the drain dips tens of volts below zero for that instant. With .options method=gear reltol=1e-4, the line every netlist and schematic in the library carries, both are gone.

Worked example

A mode with a time constant of one nanosecond, stepped by twenty:

Stiff-mode example

Symbol	Value	How it is obtained
$\tau$ time constant	1 ns	given
$\Delta t$ time step	20 ns	given
$g_\mathrm{TR}$ trapezoidal rule's factor per step	−0.818	Trapezoidal rule's factor per step on a decaying mode
$g_\mathrm{BE}$ backward Euler's factor per step	0.0476	Backward Euler's factor per step on a decaying mode

The trapezoidal rule multiplies the mode by −0.818 in every step: after ten steps about a seventh of it is left, with its sign flipping at every point. Backward Euler multiplies it by 0.0476: after two steps less than a four-hundredth of it is left.

Try it

▶ Open in the equation explorer: Trapezoidal rule's factor per step on a decaying mode
Preset from the example num-stiff

Sweep the step: the factor falls through zero at twice the time constant and approaches minus one beyond it.

▶ Open in the equation explorer: Backward Euler's factor per step on a decaying mode
Preset from the example num-stiff

Backward Euler’s factor falls towards zero instead.

Bench exercise

Capture a DCM converter’s switch node on the bench as the diode stops conducting. The ring there is real: the inductance rings with the capacitance at the switch node, at a frequency those parts set. Simulate the same circuit twice: with the trapezoidal rule and a long maximum step, and with Gear’s method and a maximum step short enough to resolve the real ring, a small fraction of its period. A ring that alternates at every time point, and moves when you change the maximum step, is numerical; one that keeps its frequency is the circuit’s, and it should match the bench, apart from the losses the bench adds.

Gotchas

• A ring that flips sign at every time point belongs to the integration rule, not to the circuit (the trapezoidal rule's factor).
• Gear’s method also damps real rings it does not resolve. For an undamped oscillation, backward Euler’s factor is below one in size and the trapezoidal rule’s is exactly one [Hairer & Wanner 1996]: a lightly damped L-C ring decays faster in a Gear simulation than in the circuit unless the step is short compared with its period.
• A tighter tolerance is not free. It shortens the steps and lengthens the run. The library chose it for the DCM flyback’s diode turn-off and applies it to every case alike.

Go deeper

• Tool ngspice — the ngspice project · retrieved 2026-09-24
  An open-source SPICE simulator; the site's simulator is cross-checked against it in CI.
• Tool Ngspice User's Manual — the ngspice team · retrieved 2026-09-25
  The reference for every netlist line: the .tran and .meas statements, and the .options that set the integration method and the tolerances.

Quiz

1. Which integration rule does ngspice use unless the netlist says otherwise?

   1. Backward Euler
   2. The trapezoidal rule
   3. Forward Euler
   4. Gear's method
   Answer and explanation

   Correct answer: B The manual gives the trapezoidal rule as the default of .options method; Gear's method has to be asked for.

2. A mode with a time constant of 1 ns is stepped by 20 ns with the trapezoidal rule. What does each step multiply it by?

   1. About 0.05
   2. About 1
   3. About -19
   4. About -0.82
   Answer and explanation

   Correct answer: D Half the step over the time constant is 10, and the factor is (1 - 10)/(1 + 10), or -9/11: the mode keeps most of its size and changes sign.

3. What does that factor look like in the simulated waveform?

   1. A ring that flips its sign at every time point
   2. A slow exponential decay
   3. A single step
   4. Nothing: the mode is too fast to show
   Answer and explanation

   Correct answer: A A factor near -1 leaves the mode almost undamped and flips it at every point: a ringing of the integration rule, not of the circuit.

4. The same mode is stepped by 20 ns with backward Euler, the first of the backward differentiation formulas that Gear's method uses. What happens to it?

   1. It rings at every time point
   2. It grows
   3. It is almost gone after a step or two
   4. It stays undamped
   Answer and explanation

   Correct answer: C The factor is 1/(1 + 20), about 0.05: after two steps less than a four-hundredth of the mode is left.

5. Why can a Gear simulation misrepresent a lightly damped L-C ring?

   1. It makes the ring grow
   2. It doubles the ring's frequency
   3. It cannot simulate inductors
   4. It damps an oscillation its steps do not resolve finely, so the ring decays faster than in the circuit
   Answer and explanation

   Correct answer: D For an undamped oscillation, backward Euler's factor is below one in size and the trapezoidal rule's is exactly one; short steps make the difference small.

6. What did the library's DCM flyback show at ngspice's default settings?

   1. The secondary current ringing through zero from step to step after the diode stopped conducting, and the drain far below zero
   2. A correct waveform
   3. A higher output voltage than expected
   4. No result at all
   Answer and explanation

   Correct answer: A The trapezoidal rule rang on the fast mode left when the diode turned off; Gear's method with a relative tolerance of 1e-4 removed it.