Source code coming soon. The GitHub repository is private for now and opens to everyone very soon.
BetterSPICE Beta 0.8.0 Join the beta Download soon
Part V  The app in detailReferenceContentsIndex
28

Analyses and their setup fields

The Analysis menu runs the classic SPICE analyses. F6 opens Simulation setup, with one tab per analysis, an explanation beside every field, and a Run button. The setup is saved in the circuit file.

28.1The setup dialog

  • Tabs: Transient, AC sweep, DC sweep, Operating point, Parameter step, FFT, Tolerance, Noise, Pole-zero and Loop gain. The last three are in the Analysis menu and have no function key.
  • Values read from the circuit show in engineering notation (1G, 1µ, 1.59155k, up to six digits so nothing is lost on save), and the fields read them back.
  • Number fields check what you type as you type. Text that's not a number turns red with "Not a number. Use plain values or SI prefixes such as 200m, 1u, 10k, 1Meg." and disables Run.
  • The dialog puts the focus in its first field and keeps Tab inside. Enter anywhere runs, also from a number field. Reset tab restores that tab's defaults. Close (or Esc) keeps your changes without running.
  • Run closes the dialog and runs, and the result shows as for every run: from the Schematic view the window splits. In Split and Analysis it stays.
  • A new circuit fills the setup from its own parts: the AC and DC sources are real sources of the circuit, the step parameter is its first resistor, the FFT signal its first probe.
  • Source, output node, parameter and probe fields list what the circuit has to choose from, and say when a name you typed isn't in it. A current source's DC sweep is in amperes.
  • The source, output-node and probe fields have a pick on schematic button: the dialog closes, you click the source, net or probe on the canvas, and it opens again with the field filled. Esc cancels. Clicking something that doesn't fit says why.
  • The settings of every tab are saved in the circuit file, as an undoable edit that marks the circuit changed, and a circuit reopens on the analysis it showed last. Running an analysis doesn't mark the circuit changed and isn't an undo step.

The analysis keys. Shift+F5 (transient), F7 (AC), F8 (DC), Shift+F7 (step) and Shift+F8 (FFT) run that analysis with the setup saved in the circuit. The first time, when the circuit has no setup for it, the key opens the setup instead, and Run there saves it, so the key runs it from then on. The setup header says so: F7 runs it from now on · F6 opens this setup. F6 opens the setup of the current analysis at any time, and the toolbar's .ac and .step buttons open theirs. F9 runs the operating point at once. F5 runs a transient with the toolbar's stop time and max step.

The setup dialog
AnalysisKeyResult
TransientShift+F5, or F5 to run it directlySignals against time
AC sweepF7Gain and phase against frequency, with -3 dB points and margins
DC sweepF8Signals against a swept source value
Operating pointF9 runs it at onceA table of node voltages and branch currents
Parameter stepShift+F7One curve per parameter value, overlaid
FFTShift+F8A spectrum in dB against frequency
ToleranceShift+F9Monte Carlo or worst case on the part tolerances
NoiseAnalysis menuNoise density at an output, each part’s share, and the totals
Pole-zeroAnalysis menuPoles and zeros of a transfer function, on the s-plane and in a table
Loop gainAnalysis menuBode plot of a feedback loop with the crossover, phase margin and gain margin

28.2Transient

Setup, Transient tab.
Figure 28.1Setup, Transient tab.

Runs the circuit through time, like a scope capture: voltages and currents from t = 0 to the stop time.

Transient
FieldValuesDefaultWhat it does
Stop timeseconds, above 0200mHow long the simulated capture is. Also the Simulate for field in the toolbar.
Start saving atseconds, 0 or more0Results before this time are computed but not kept, to skip the start-up. It must be earlier than the stop time: otherwise the field says "Must be earlier than the stop time…" and Run is greyed.
Maximum timestepseconds, above 0, or empty or autoAutoThe solver never takes a longer step. Smaller is more precise and slower. Empty means Auto: the step is chosen from the circuit (Auto maximum step). Also the max step field in the toolbar.
Integration methodTrapezoidal (accurate), Gear-2 (damps ringing), Backward Euler (most robust)TrapezoidalTrapezoidal keeps the most detail. Gear-2 (second order) damps ringing in stiff circuits and allows a larger step, at some cost in accuracy. Backward Euler (first order) is the most robust and damps the most. Used by ngspice runs and by the BetterSPICE engine. Choose a damped method when the run warns W_TRAP_RINGING (a numerical oscillation of the trapezoidal rule, explained in the Fix chapter).
Start from initial conditionsNo (DC operating point), Yes (ic values)No (DC operating point)Yes skips the DC operating point and starts capacitors and inductors at their ic values. Used by ngspice runs. The BetterSPICE engine starts from ic values when the circuit sets them. A circuit can set this, the method and ngspice options itself (Settings saved in the circuit).
Try it
A buck converter start-up
  1. Open Switching converters, a synchronous buck.
  2. Press Shift+F5. Set Stop time 2m and Maximum timestep 50n. Press Enter.

You should seeThe output rises to its set voltage with the soft start, and the inductor current shows the ripple. Zoom into the end to read the steady ripple.

28.3AC sweep

Setup, AC sweep tab.
Figure 28.2Setup, AC sweep tab.

Finds the small-signal frequency response, gain and phase, around the operating point. The circuit is linearised at its DC operating point, the input source gets a 1 V small-signal stimulus, and every probe is plotted relative to it.

AC sweep
FieldValuesDefaultWhat it does
Input sourcea source designatorthe circuit's first sourceThe source that gets the 1 V stimulus. An unknown name is refused with the list of the circuit's sources.
Start frequencyHz1The lowest frequency.
Stop frequencyHz1MegThe highest frequency.
Points per decadenumber, at least 150Frequencies per decade.
Output nodea net name, optionalemptyAlso plot this net, written VOUT or V(VOUT). Probes are always plotted.

The result is a Bode plot: magnitude in dB and phase in degrees. Where the gain is below −200 dB the phase isn't drawn, and when every probe sits at that floor the result says "No small-signal path from V1 to … at this operating point". The phase is unwrapped, so it runs on past −180° without jumping by 360°, in the plot and in bode.csv. The margins strip above it shows, for the output trace, the -3 dB frequencies (up to two), the Gain crossover, the Phase margin (amber below 45°), the Phase crossover and the Gain margin (amber below 6 dB).

AC sweep of the active high-pass filter: gain and phase.
Figure 28.3AC sweep of the active high-pass filter: gain and phase.

28.4DC sweep

Setup, DC sweep tab.
Figure 28.4Setup, DC sweep tab.

Slowly sweeps one source and records the steady-state result at each value.

DC sweep
FieldValuesDefaultWhat it does
Swept sourcea DC voltage or current sourcethe circuit's first sourceA battery can't be swept. The message suggests a DC voltage or current source instead.
Start valueV or A0The first value.
Stop valueV or Atwice the source's valueThe last value. For a 300 mV source the default sweep is 0 to 600 mV.
IncrementV or Aabout 1/500 of the rangeThe step between values (1 mV for a 300 mV source).

The caption of the result carries units, for example V1 0 V to 600 mV.

Try it
A diode curve
  1. Place a DC source, a 100 Ω resistor and a diode in series, and probe the current through the diode.
  2. Press F8. Sweep the source from 0 to 2 in 5m steps.

You should seeThe current stays near zero until about 0.6 V across the diode, then rises steeply, limited by the resistor.

28.5Operating point

Setup, Operating point tab.
Figure 28.5Setup, Operating point tab.

Solves the DC steady state once. F9 runs it at once without the dialog.

Operating point
FieldValuesDefaultWhat it does
Gmin steppingAutomatic, OffAutomaticIf the first attempt fails, adds tiny conductances to ground and removes them step by step.
Source steppingAutomatic, OffAutomaticIf gmin stepping fails too, ramps the sources up from zero.

Off only applies to ngspice runs. The BetterSPICE engine uses both when it needs them and says so. The result is a table: probes first, then V(net) for every net, then I(part) and, for runs in the BetterSPICE engine, P(part). Nets are named as on the schematic: a label, else a part pin such as V(C1 pin 2). Click a row to mark its net or part on the schematic. With more than 12 rows a filter box appears, and 300 rows show until Show all. Copy as table puts the table on the clipboard. Export CSV writes Quantity, Value and Unit.

Operating point table.
Figure 28.6Operating point table.

Show on schematic above the table (or View›Operating point on the schematic) writes the result on the circuit: every net's DC voltage (ground left out) beside its net label or along one of its wires, and the current of every two-pin part that carries DC current, with a small arrow in the direction it flows through the part. A capacitor carries none and gets no label. The text is small and muted, the numbers are those of the table, and each one is placed clear of parts, labels, probe tags and the other values. When there is no room for one, it is left out: zoom in, or read it in the table. The values go away as soon as the circuit changes and come back with the next F9. The switch is remembered.

An operating point shown on the schematic: the DC voltage of every net and the current of every two-pin part, with an arrow for its direction.
Figure 28.7An operating point shown on the schematic: the DC voltage of every net and the current of every two-pin part, with an arrow for its direction.

28.6Parameter step

Setup, Parameter step tab.
Figure 28.8Setup, Parameter step tab.

Repeats the chosen analysis once per parameter value and overlays the results.

Parameter step
FieldValuesDefaultWhat it does
Parameterpart.keythe first resistor, R1.rThe value to step, written as the designator, a point and the parameter key: R1.r, C1.c, V1.v. The keys are in the parameter tables of the device chapters, from Devices: passives on.
Valuesa comma list, at most 12100, 220, 470, 1k, 2.2kThe values to run. For parameters other than resistance the default is half, the same and double the present value.
Analysis to repeatTransient, AC sweep, DC sweepTransientWhich analysis, with the setup of its own tab.
Probe to plota probe label, optionalevery probeOnly this probe, for example V out.

Each curve is named like V out · R1.r = 470. The Analysis bar shows the progress as a percentage. In the browser the values run in parallel, one per processor core. Errors name the problem, for example "X has no value "key", its values: …".

Parameter step over a transient: an RC charge for four resistor values.
Figure 28.9Parameter step over a transient: an RC charge for four resistor values.
Parameter step over an AC sweep: a high-pass filter for four capacitor values.
Figure 28.10Parameter step over an AC sweep: a high-pass filter for four capacitor values.

28.7Tolerance

Setup, Tolerance tab.
Figure 28.11Setup, Tolerance tab.

Repeats an analysis many times with the part values changed inside their tolerances. It answers how much the result moves and how many builds would still meet the specification.

Tolerance of a part. Select a part and set Tolerance (percent) in the inspector, and Tolerance distribution under All parameters. Gauss means the tolerance is the 3-sigma limit and a draw is cut at plus and minus 3 sigma. Uniform means every value inside the tolerance is equally likely. The two are saved in the circuit as p.tol and p.tolDist. In this analysis a resistor with no tolerance counts as 1 %, a capacitor as 10 % and an inductor as 20 %. Sources and batteries are exact unless they get one, and a tolerance of 0 makes any part exact. Every other analysis keeps the exact value of every part.

Tolerance
FieldValuesDefaultWhat it does
Analysis to repeatTransient, AC sweep, DC sweep or Operating pointTransientThe analysis to run again, with the settings of its own tab.
MethodMonte Carlo, Worst caseMonte CarloMonte Carlo draws every part at random. Worst case sets every part to its low or high end.
Runs1 to 20000200The number of Monte Carlo runs.
Seeda whole number1The same seed gives the same runs, here and in bspice.
Order corners bya measurementthe firstWorst case with more than 8 toleranced parts orders its corners by this measurement.

More parts than resistors, capacitors and inductors have a tolerance of their own, set in the inspector under Accuracy: the input offset limit of an op-amp or comparator (vos_max), the forward voltage spread of an LED or diode (vf_tol), a zener voltage (bv_tol), a regulator output (tol), a crystal frequency (ppm_tol), a transformer ratio (ratio_tol), the 555 threshold and trigger levels, NTC, PTC and RTD resistance, sensor sensitivity and offset, and the offset and gain error of an ADC or DAC. A part is varied only when it sets the value, and an old circuit gives the same runs for its resistors, capacitors and inductors. The full list is in docs/DEVICES.md under Tolerance analysis keys.

Worst case runs every corner (2 to the power of the number of parts) up to 8 parts. With more parts it first moves one part at a time, then sets the most sensitive part, the two most sensitive, and so on, all pushing the chosen measurement up and all pushing it down. That finds the extremes of a smooth response in 4 runs per part. No more than 6 runs go at the same time. The runs use the built-in engine, like a parameter step, and a circuit with vendor models runs with their fitted models.

A tolerance analysis of the RC low-pass filter, 200 Monte Carlo runs: the cloud of runs behind the nominal curve, the histogram of the -3 dB frequency, the
Figure 28.12A tolerance analysis of the RC low-pass filter, 200 Monte Carlo runs: the cloud of runs behind the nominal curve, the histogram of the -3 dB frequency, the yield against the typed limits and the bars of which parts matter.

What is judged is the circuit's measurements that fit the analysis (Measurements). A circuit with none uses the final value of its first probes, or the -3 dB frequency for an AC sweep. The result has these parts.

Tolerance
Part of the resultWhat it shows
The cloudAll runs drawn over each other, with the nominal run on top.
Spread ofA histogram of one measurement, marked with the nominal value and the mean, with sigma, minimum and maximum beside it.
YieldType the lowest and highest allowed value and the share of runs inside shows at once. Limits saved in a measurement start there. A run the engine could not solve counts as a failure.
Which parts matterA bar per part with its share of the spread. For Monte Carlo it is the squared correlation of the part value with the measurement. For worst case it is the change of the measurement when the part goes from low to high.
TableEvery measurement with nominal, mean, sigma, minimum, maximum and yield. Export CSV writes one row per run.
The same circuit as a worst case: the 4 corners run from 1.432 kHz to 1.786 kHz, outside the limits 1.5 kHz to 1.7 kHz, so every corner fails. Read the min
Figure 28.13The same circuit as a worst case: the 4 corners run from 1.432 kHz to 1.786 kHz, outside the limits 1.5 kHz to 1.7 kHz, so every corner fails. Read the minimum and maximum, not the mean.

Worst case runs corners, so its mean, sigma and yield describe the corners only. Agents reach this with the tolerance tool.

28.8FFT

Setup, FFT tab.
Figure 28.14Setup, FFT tab.

Turns a transient result into a spectrum. The FFT first runs a transient with the Transient tab's stop time and maximum timestep, then analyses one probe.

FFT
FieldValuesDefaultWhat it does
Signala probe labelthe first probeWhose waveform is analysed.
WindowHann, Blackman, Rectangular (none)HannThe taper against leakage. Amplitudes are corrected for the window: a 1 V sine reads 0 dBV with every window. Rect keeps exact amplitudes for signals that are periodic in the window.
Points4096, 16384, 65536, 26214465536The least number of points taken from the waveform. The FFT takes at least one per simulated sample, so nothing folds down, and past 220 points each point is the average of the waveform over its interval. More points show higher frequencies. The frequency resolution is set by the length of the data: the stop time minus Use data from.
Use data fromsecondshalf the transientSkips the start-up. The field warns when it's past the end of the run. At most the first half of the run is skipped. With fewer than 16 samples left the run asks for a longer stop time.
FFT of a Wien-bridge oscillator.
Figure 28.15FFT of a Wien-bridge oscillator.
Try it
Distortion of an amplifier
  1. Open a transistor amplifier example and probe its output.
  2. Set the Transient stop time to 50m, then press Shift+F8. Window Blackman, Use data from 10m.

You should seeThe fundamental stands out with its harmonics below it. Their height in dB below the fundamental is the distortion.

28.9Noise

Setup, Noise tab.
Figure 28.16Setup, Noise tab.
The Noise tab on a common-emitter amplifier: the density at the output, the share of each part, the totals and the table of parts.
Figure 28.17The Noise tab on a common-emitter amplifier: the density at the output, the share of each part, the totals and the table of parts.

Finds the electrical noise at an output over a frequency sweep. It is the analysis of ngspice’s .noise. Every part with noise adds its sources at the operating point.

Noise
FieldValuesDefaultWhat it does
Output nodea net, or V(OUT,REF) for two netsWhose noise is measured. The pick on schematic button fills it from a click.
Input sourcea source of the circuitV1The source the noise is referred to: input noise is the output noise divided by the gain from this source.
Start frequency, Stop frequencyHz1 and 1MegThe sweep. The totals are integrated over it.
Points per decadewhole number20How many frequencies are computed per factor of ten.
Noise
PartNoise it adds
ResistorThermal noise 4kT/R.
Diode, BJTShot noise 2qI, and flicker noise KF · IAF / f. RS, RB, RC and RE add thermal noise.
MOSFET, JFETChannel noise 4kT · (2/3) gm and flicker noise. MOSFET levels 1 to 3 follow ngspice’s NLEV (default 2).
Built-in op-ampThe thermal noise of its 1 Ω pole node.
Ideal sources, capacitors, inductors without resistanceNone. A behavioural block with no noise model is named under the table.

Set KF and AF on a part, or in its model card, for flicker noise. A circuit with vendor models runs in ngspice in the desktop app, so the noise sources inside the vendor subcircuits count. The result shows:

  • Total output noise in V rms over the sweep, and the input-referred total (V for a voltage source, A for a current source). Type a band in Integrate from … to and the totals, the table and the shading follow that band. The integration takes the density as a power law between two points, as ngspice does, so 1/f and white noise integrate exactly.
  • The density in V/√Hz on log-log axes: the total and each part’s own curve. Input-referred switches the plot to the input. Under it, Share of the noise power stacks what each part adds at every frequency (the six largest, the rest as Other parts). Hold the pointer over the plot for the values at a frequency.
  • A table of every part: its rms output noise over the band, its share of the noise power and its noise sources (thermal, rb, ib, ic, flicker). Hold the pointer over a row to mark the part on the schematic.

The result was checked against ngspice-47 on a divider, an RC filter, a common-emitter amplifier, an op-amp amplifier, MOSFET and JFET stages and a diode: the densities agree to 0.005 % and the output totals to 0.003 %. ngspice’s own input-referred total holds the gain of each interval’s upper point over the whole interval, which reads up to 11 % high at 10 points per decade. BetterSPICE integrates the input-referred density itself.

28.10Pole-zero

The Pole-zero tab on a Sallen-Key filter: poles (×) and zeros (○) on the s-plane, and the table with frequency, Q and damping.
Figure 28.18The Pole-zero tab on a Sallen-Key filter: poles (×) and zeros (○) on the s-plane, and the table with frequency, Q and damping.

Finds the poles and zeros of the transfer function from an input source to an output node, at the operating point, like ngspice’s .pz. A voltage source gives V(OUT)/V(V1), a current source V(OUT)/I(I1).

Pole-zero
FieldValuesDefaultWhat it does
Output nodea net, or V(OUT,REF)The output of the transfer function.
Input sourcea source of the circuitV1The input: a voltage source gives a voltage gain, a current source a transimpedance.

The result shows the roots on the s-plane (poles as ×, zeros as ○). Log axes spread roots that lie decades apart and Linear axes show them as they are. The table lists each root in rad/s, its natural frequency in Hz, and Q and damping ζ for a complex pair. A pole in the right half plane is flagged, because the circuit is unstable. The summary gives the DC gain and the constant k in H(s) = k · Π(s − z) / Π(s − p).

The roots are the eigenvalues of the circuit’s small-signal matrices, each refined and checked. The result checks itself: the response rebuilt from the poles, zeros and k is compared with a direct AC solve, and the line under the table says how well they agree. ngspice’s .pz searches for roots one at a time and often gives up on filters and amplifiers (iteration limit reached). Where it finishes, BetterSPICE agrees with it to 10 significant figures. A transmission line has no finite set of poles and zeros and is refused. Pole-zero handles at most 600 unknowns, so run it on the stage that sets the response.

28.11Loop gain

Setup, Loop gain tab.
Figure 28.19Setup, Loop gain tab.
The Loop gain tab on an op-amp that drives a capacitive load: the loop gain T(f) as a Bode plot, with the crossover, the phase margin and the gain margin.
Figure 28.20The Loop gain tab on an op-amp that drives a capacitive load: the loop gain T(f) as a Bode plot, with the crossover, the phase margin and the gain margin.

Measures how stable a feedback loop is: an op-amp circuit, a linear regulator, a switching regulator with an averaged or vendor model. It plots the loop gain T(f), the gain a small signal picks up on one trip around the loop.

Loop gain
FieldValuesDefaultWhat it does
Break pointa wire, a pin, a net or a 0 V sourceWhere the loop is opened. Press the pick button and click a wire of the loop, or type U1.in- (that pin is cut off its net, the usual choice is the inverting input of the error amplifier), a net that joins exactly two pins such as FB, a 0 V voltage source already in series with the loop such as VINJ, or wire:x,y (what the pick writes). A circuit with a 0 V source in series opens with it filled in.
Start frequency, Stop frequencyHz10 and 10MegThe sweep. The stop should lie well above the crossover.
Points per decadewhole number20How many frequencies are plotted per factor of ten. The crossover and the margins are solved exactly between points, so they do not depend on it.
  • The crossover is where |T| falls through 1 (0 dB).
  • The phase margin is 180° plus the phase of T at the crossover. Below 45° the step response rings, at 0° the loop oscillates.
  • The gain margin is how far |T| is below 0 dB where the phase reaches -180°. There is none when the phase never gets there.
  • The gain at the start of the sweep, and a table of every crossing. A conditionally stable loop crosses 0 dB several times, and the margins in the header are at the highest crossing.

The circuit is not changed: the break exists only during the analysis. Any point that the whole loop signal passes through gives the same loop gain, and the direction of the break does not matter, because the analysis finds it. At the break it injects a 1 V signal in series and, in a second solve, a 1 A signal into the node, and combines the two (the double injection of Middlebrook, in the form of Tian, Kolar and Middlebrook). Unlike a single voltage injection, which needs a low impedance on one side of the break and a high one on the other, this is exact for any loop, also where the parts at the break load each other. A circuit with vendor models runs both injections in ngspice in the desktop app. An op-amp with a capacitive load agrees with its loop gain worked out by hand to 3e-9 at every frequency, and on four vendor regulator examples it agrees with the AC sweep to 0.001 %. Try the example Loop gain of an op-amp driving a capacitive load in Op-amp circuits.