ngspice-jit — command reference

.ac  dec|oct|lin  n  fstart  fstop

Linearizes the circuit about its DC operating point and sweeps frequency, giving complex node voltages (magnitude/phase). Stimulus comes from sources carrying an AC value.

* RC low-pass AC magnitude, find -3 dB corner
V1 in 0 AC 1
R1 in out 1k
C1 out 0 100n
.ac dec 50 10 1meg
.control
  run
  meas ac fc WHEN vdb(out)=-3.0103
.endc
.end

fc                  =  1.59155e+03

fc = 1/(2π·R·C) = 1/(2π·1 kΩ·100 nF) = 1591.55 Hz ✓. Note vdb() gives magnitude in dB; -3.0103 dB is the half-power point.

* phase = -45 deg (= -pi/4 rad) exactly at the corner
V1 in 0 AC 1
R1 in out 1k
C1 out 0 100n
.ac dec 50 10 1meg
.control
  run
  meas ac f45 WHEN vp(out)=-0.7853982   $ vp() is in RADIANS
.endc
.end

f45                 =  1.59169e+03

Same 1592 Hz corner, cross-checked through the phase instead of the magnitude ✓.

Aname  in-ports …  out-ports …  modelname
.model modelname  codemodel_type ( params )
codemodel  library.cm                 $ load an external code-model library

The A card instantiates an XSPICE code model — a compiled behavioral block (gain, summer, limiter, s-domain transfer function, ADC/DAC, a file-driven source, …) beyond the built-in analog primitives. The code models are not linked into ngspice; they live in shared-library files (analog.cm, digital.cm, xtradev.cm, …) and are loaded at run time by the codemodel command. In a normal install spinit already issues those codemodel lines at start-up (guarded by $?xspice_enabled), so a deck can use gain, filesource, etc. with no codemodel line of its own.

* one A-device drives a 4-bit bus from a multi-column file: a binary counter
a1 %v([b3 b2 b1 b0]) bus4               $ a VECTOR port -> four nodes at once
.model bus4 filesource (file="pattern4.dat"
+ amploffset=[0 0 0 0] amplscale=[1.8 1.8 1.8 1.8]   $ per-bit: logic 1 = 1.8 V
+ timeoffset=0 timescale=1 timerelative=false amplstep=TRUE)
rb3 b3 0 1meg
rb2 b2 0 1meg
rb1 b1 0 1meg
rb0 b0 0 1meg
.tran 5n 1.5u
.control
  run
  meas tran b3_7  FIND v(b3) AT=750n    $ counter=7  (0111): b3=0,   b0=1.8
  meas tran b0_7  FIND v(b0) AT=750n
  meas tran b3_12 FIND v(b3) AT=1250n   $ counter=12 (1100): b3=1.8, b0=0
  meas tran b0_12 FIND v(b0) AT=1250n
.endc
.end

b3_7                =  0.00000e+00
b0_7                =  1.80000e+00
b3_12               =  1.80000e+00
b0_12               =  0.00000e+00

This is where code models earn their keep. A vector port %v([b3 b2 b1 b0]) lets one filesource drive a whole bus: each column of pattern4.dat feeds one bit, scaled independently by the per-port amplscale/amploffset vectors — here a 4-bit binary counter with logic-1 = 1.8 V. amplstep=TRUE holds each level (clean digital edges); false would linearly interpolate (analog PWL). At t = 750 ns the file’s row is 0 1 1 1 and t = 1250 ns is 1 1 0 0 — both read back exactly ✓. Ports carry a type sigil: %v([n]) single-ended, %vd([p n]) differential, %i current, %vnam named. A fuller version — differential sine/cosine plus an 8-bit bus — is at /users/design/ngspice/code_model_pattern.sp.

* two quadrature channels from a 3-column file (time, cos, sin)
a1 %vd([c 0 s 0]) sincos                $ %vd pairs nodes -> differential ports
.model sincos filesource (file="sincos.dat"
+ amploffset=[0 0] amplscale=[1 1]
+ timeoffset=0 timescale=1 timerelative=false amplstep=false)
rc c 0 1meg
rs s 0 1meg
.tran 2u 2m
.control
  run
  meas tran c_0 FIND v(c) AT=0          $ cos(0)   = 1
  meas tran s_0 FIND v(s) AT=0          $ sin(0)   = 0
  meas tran c_q FIND v(c) AT=250u       $ cos(90d) = 0
  meas tran s_q FIND v(s) AT=250u       $ sin(90d) = 1
.endc
.end

c_0                 =  1.00000e+00
s_0                 =  0.00000e+00
c_q                 =  1.73472e-18     (= 0)
s_q                 =  9.99920e-01     (= 1)

Here %vd([c 0 s 0]) declares two differential output ports — one across (c,0), one across (s,0) — fed by columns 2 and 3 of the file. With amplstep=false the samples are linearly interpolated, giving smooth analog waveforms; the two channels are 90° apart (cos and sin) ✓. Because each port’s reference here is ground, the pair acts single-ended — give a non-zero second node to drive a genuinely floating differential output.

* 8 bits, each parked at a distinct DC level so the traces don't overlap
a1 %v([a7 a6 a5 a4 a3 a2 a1 a0]) bus8
.model bus8 filesource (file="pattern8.dat"
+ amploffset=[0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8]      $ per-bit DC level
+ amplscale=[0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05] $ small swing
+ timeoffset=0 timescale=1 timerelative=false amplstep=TRUE)
ra7 a7 0 1meg
ra0 a0 0 1meg
.tran 5n 850n
.control
  run
  meas tran a0_hi FIND v(a0) AT=50n    $ a0 hot: 0.8 + 0.05 = 0.85
  meas tran a7_lo FIND v(a7) AT=50n    $ a7 low: 0.1 + 0    = 0.10
  meas tran a7_hi FIND v(a7) AT=750n   $ a7 hot: 0.1 + 0.05 = 0.15
  meas tran a0_lo FIND v(a0) AT=750n   $ a0 low: 0.8 + 0    = 0.80
.endc
.end

a0_hi               =  8.50000e-01
a7_lo               =  1.00000e-01
a7_hi               =  1.50000e-01
a0_lo               =  8.00000e-01

The eight-column file is a walking-1; the per-bit amploffset vector (0.1…0.8 V) parks each bit at its own DC level while amplscale keeps the swing to 0.05 V, so plotting the bus shows eight non-overlapping stacked traces — the usual way to eyeball a digital vector. All four probes match their offset + scale·bit ✓.

You only call codemodel path/lib.cm yourself to load a library that isn’t already in — typically a custom, user-compiled .cm, placed in spinit/.spiceinit (or a script sourced) before the circuit that uses it. That is why there is no standalone deck example here: the standard libraries are loaded for you at start-up, and the model just works.

alias [ name [ definition ] ]        unalias name

Defines a control-mode shortcut for a command and its arguments. alias with no arguments lists all aliases; unalias removes one.

alter  devname  value
alter  devname  param = value

Changes an instance parameter of an already-loaded device (a resistance, capacitance, source level, …) without editing or re-parsing the netlist. Follow it with run to resimulate. Ideal inside a foreach/while loop for parameter studies.

.param rval=1k
V1 in 0 DC 1
R1 in 0 {rval}
.op
.control
  run
  print @r1[resistance]
  alterparam rval=2k
  mc_source              $ rebuild the deck so the new .param takes effect
  op
  print @r1[resistance]
.endc
.end

@r1[resistance] = 1.000000e+03
@r1[resistance] = 2.000000e+03

Where alter/altermod poke a device or model directly, alterparam edits a .param value. Because parameters are resolved when the netlist is expanded, it only takes effect after a re-expansion — mc_source (or reset) — then the next run/op sees the new value.

altermod  modelname  param = value

Like alter, but targets a .model parameter — the change affects every device using that model. Useful for corner/temperature what-ifs.

@devicename[parameter]        $ e.g. @R1[resistance], @M1[gm], @Q1[ic]

The @ accessor reads a live device (or model) parameter or operating-point quantity into an expression — resistance of a resistor, gm/vds of a MOSFET, ic of a BJT, etc. It must be evaluated (via let/print), not echoed. Which parameters exist for a device is listed by devhelp / showmod.

compose  name  values v1 v2 …
compose  name  start=a stop=b step=d      (or  lin=n / log=n)

Creates a vector from an explicit list of values, or as a linear/log ramp. Handy for building a sweep axis or a lookup table inside .control.

.csparam  name = { expression }

Copies a netlist parameter into the .control namespace (as a vector), where plain .param values are otherwise invisible. The bridge between parse-time parameters and the control script.

.dc  srcname  start  stop  step  [ srcname2 start2 stop2 step2 ]

Sweeps a source (voltage or current) — or a nested pair of sources — and records the DC solution at each step, producing curves vs. the swept value. The classic use is a device I–V characteristic.

* Diode I–V curve via .dc source sweep
Vs a 0 DC 0
R1 a d 100
D1 d 0 DMOD
.model DMOD D(IS=1e-14 N=1)
.dc Vs 0 1 0.05
.control
  run
  meas dc vd_1v FIND v(d)  AT=1.0
  meas dc id_1v FIND i(vs) AT=1.0
.endc
.end

vd_1v               =  6.84819e-01
id_1v               = -3.15181e-03

At Vs = 1 V the diode drops 0.685 V, so I = (1 − 0.685)/100 Ω = 3.15 mA ✓.

.model NM NMOS(level=1 kp=200u vto=0.5)
Vd d 0 DC 1
Vg g 0 DC 0
M1 d g 0 0 NM w=10u l=1u
.dc Vg 0 2 0.5  Vd 1 2 1      $ inner Vg sweep, outer Vd -> a family
.control
  run
  let id = i(vd)
  print id[3]                 $ Vgs=1.5 on the first Vds curve
.endc
.end

id[3] = -1.00000e-03

The outer Vd sweep repeats the inner Vg sweep for each drain voltage — the MOSFET I_D–V_GS family. At V_GS=1.5 V (saturation) I_D = ½·kp·(W/L)·(V_GS−V_to)² = 1.0 mA ✓ (i(vd) negative by source convention).

define  name(args)  expression

Defines a reusable function of one or more arguments, usable anywhere an expression is (in let, print, plotting). Handy for repeated post-processing (dB, RMS, a custom figure of merit).

devhelp [ devtype [ param ] ]      $ list a device type's parameters
devices [ regexp … ]               $ list device instance NAMES only
show    device|regexp … [ : param … ]   $ instance operating-point values
showmod model|regexp … [ : param … ]    $ model parameter values

devhelp lists what parameters a device type accepts and reports; show/showmod print the live values for instances/models after a run — the readable companion to the @dev[param] accessor.

On a real design show dumps ~50 parameters per BSIM device × dozens of devices — pages of scroll. Two features cut that down, and they combine:

• Select devices by regular expression: show r.* = every resistor, show m.* = every MOSFET, show m.x1.* = every device in subcircuit X1. (Plain names, all, and the type:subckt:dev syntax still work; a name with a bare . stays literal, so show m.x1.m7 is exact.)
• Select parameters after a :: everything past the colon names the parameters to print — show m1 : vgs vds gm id shows only those four. (An invalid name for that model prints ?????????.)

Together: show m.x1.* : id vgs vds gm → those four values for every MOSFET in X1, one tidy table instead of pages.

When you only want to know which devices exist (not their values), devices lists the instance names, one per line — the equivalent of piping show through grep. No argument lists them all; each argument is a regex (grep-style):

devices              $ every device instance
devices m.*          $ every MOSFET:  m2  m1  m.x1.m3 …
devices m.x1.*       $ the devices inside subcircuit X1
devices ^r ^c        $ every resistor and capacitor

Handy to discover names before a show … : params or an @dev[param] query. (New command in this build.)

.model NM NMOS(LEVEL=1 VTO=0.7 KP=120u)
V1 in 0 DC 1
R1 in a 1k
R2 a  b 2k
M1 b in 0 0 NM W=10u L=1u
M2 a in 0 0 NM W=4u  L=1u
.tran 1u 2u
.control
  run
  show r.*                    $ every resistor (all default params)
  show m.* : vgs vds gm id    $ every MOSFET, only these four params
.endc
.end

     device                    r2                    r1
 resistance                  2000                  1000
     device                    m2                    m1
        vgs                     1                     1
        vds                0.9244                0.8164
         gm              0.000144               0.00036
         id              2.16e-05               5.4e-05

On the two_balance chip, show m.x1.* : id vgs vds gm reads back all seven MOSFETs of instance X1 with four columns each. (Regex device selection is an extension in this build; the : param selection is standard ngspice.)

diff  plot1  plot2  [ vec … ]

Compares two saved plots vector by vector and reports only the entries that differ by more than the tolerances (set diff_abstol/diff_reltol/diff_vntol). The quick way to see what a parameter change actually moved.

V1 in 0 DC 1
R1 in out 1k
R2 out 0 1k
.op
.control
  run                    $ -> plot op1 : v(out) = 0.5
  alter r2 2k
  run                    $ -> plot op2 : v(out) = 0.667
  diff op1 op2
.endc
.end

op1.out[0] = 5.000000e-01    op2.out[0] = 6.666667e-01

Each run stores a plot (op1, op2); diff then prints exactly the node that changed when R2 doubled — the divider output moved from 0.5 to 0.667 ✓.

display [ name | keyword | regexp … ]

Shows the status (not the values) of the vectors in the current plot: each line is name : type, real/complex, length, with the scale tagged [default scale]. The quickest way to see what a run produced or what an analysis created (e.g. the sensitivity vectors of .sens). For the numbers use print; for a waveform, plot. It reports the current plot only — setplot first to inspect another.

The variable set nosort lists in internal (creation) order instead of alphabetical.

V1 in 0 SIN(0 1 1k)
Vdd vdd 0 DC 5
R1 in out 1k
C1 out 0 100n
Rl out vdd 2k
.tran 20u 1m
.control
  run
  display allv        $ voltages only
  display .*branch    $ regex: every branch current
.endc
.end

    in         : voltage, real, 59 long      <- display allv
    out        : voltage, real, 59 long
    vdd        : voltage, real, 59 long
    v1#branch  : current, real, 59 long      <- display .*branch
    vdd#branch : current, real, 59 long

An argument that isn’t an exact name (or a v()/i() form or an all* keyword) and contains regex metacharacters is treated as a POSIX extended, case-insensitive, grep-style regular expression matched against vector names: display .*branch → all branch currents, display ^v → everything starting with v, display o.*t → out. Plain names still match exactly. (Regex selection is an extension in this build; stock ngspice-46 accepts only names and the all* keywords.)

* two instances X1, X2 of a stage -> internal nodes x1.n1, x2.n1, ...
Vin in 0 DC 3
X1 in  mid stage
X2 mid out stage
RL out 0 1k
.subckt stage a z
  R1 a n1 1k
  R2 n1 n2 1k
  R3 n2 z 1k
.ends
.op
.control
  run
  display x1.*        $ only X1's internal nodes
  print "x1.*"        $ their voltages (print needs the quotes)
  unlet x2.*          $ drop X2's internals
  display .*n1        $ x2.n1 is now gone
.endc
.end

    x1.n1               : voltage, real, 1 long        <- display x1.*
    x1.n2               : voltage, real, 1 long
x1.n1 = 2.571429e+00                                   <- print "x1.*"
x1.n2 = 2.142857e+00
    x1.n1               : voltage, real, 1 long        <- display .*n1 (only x1.n1 left)

On a real design the subcircuit-internal nodes number in the dozens — the two-stage balanced amplifier in user_examples/two_balance.cir exposes x1.a, x1.b, x1.vp, x1.vcm, x2.… and the per-device @m.x1.m7[…] currents. There, display x1.* lists just one instance’s nodes and print "x1.*" dumps them — regex turns “what’s inside X1?” into one line.

.disto  dec|oct|lin  n  fstart fstop  [ f2overf1 ]

Computes steady-state harmonic (and, with f2overf1, intermodulation) distortion from the device small-signal series. Stimulus comes from sources carrying a DISTOF1/DISTOF2 spec. Results land in two plots: disto1 (2nd-order) and disto2 (3rd-order); the node vectors are the distortion products.

echo [ stuff … ]

Prints its arguments, expanding shell variables ($var). It does not evaluate vectors or expressions — use $&vec for a vector’s value, or print for expressions.

fft  vector …

After a .tran run, computes the FFT of each vector into a new spectrum plot (frequency resolution = 1/timespan). Use mag()/db() on the complex result. A windowed, more controllable alternative to .four; window via set specwindow=….

B1 s 0 V = sin(2*3.14159*1k*time) + 0.5*sin(2*3.14159*3k*time)
R1 s 0 1k
.tran 5u 10m
.control
  run
  fft v(s)
  let m = mag(v(s))
  meas sp a1k MAX m FROM=0.9k TO=1.1k
  meas sp a3k MAX m FROM=2.9k TO=3.1k
.endc
.end

FFT: Frequency resolution: 99.957 Hz, output length: 1005
a1k =  9.95417e-01  at=  9.99570e+02
a3k =  4.93659e-01  at=  2.99871e+03

Both tones are recovered at 1.0 / 3.0 kHz with a 2.01 : 1 amplitude ratio — matching the 1 : 0.5 input ✓.

B1 s 0 V = sin(2*3.14159*1k*time)
R1 s 0 1k
.tran 5u 10m
.control
  run
  psd 1 v(s)             $ 1 = averaging length; result overwrites v(s)
  let p = db(v(s))
  meas sp pk MAX p
.endc
.end

PSD: Frequency resolution: 100 Hz, output length: 1005
pk                  =  -4.60992e+01 at=  1.00000e+03

psd len vec… is a close cousin of fft that returns the power spectral density (magnitude squared, optionally smoothed over len bins). The peak lands on the 1 kHz tone ✓. Use fft when you want the complex spectrum, psd when you want power.

fopen  handle file [mode]     $ open; handle name in $handle-var
fread  handle var [len]       $ read a line into $var; status in $len-var
fclose handle

Line-oriented file reading for .control scripts (parameter tables, external stimuli).

foreach  var  word1 word2 …
  … body (use $var) …
end

Runs the body once per word, with var set to each word in turn (words are literal text — values, node names, filenames). The most common way to repeat a run over a set of parameter values.

.four  freq  output_variable ...

After a .tran run, computes the DC component, fundamental (at freq), and harmonics 2–9 of each output, plus total harmonic distortion (THD). Operates on the last period of the transient waveform.

* Half-wave rectifier -> .four shows strong harmonics
Vs in 0 SIN(0 1 1k)
R1 in a 50
D1 a out DMOD
Rout out 0 1k
.model DMOD D(IS=1e-14 N=1)
.tran 2u 20m
.four 1k v(out)
.end

Fourier analysis for v(out):
  No. Harmonics: 10, THD: 87.7379 %, Gridsize: 200, ...
 Harmonic  Frequency  Magnitude   Norm. Mag
 0         0          0.0703844   0
 1         1000       0.128272    1
 2         2000       0.0956183   0.745433
 3         3000       0.0548493   0.427601
 4         4000       0.0192777   0.150288

Half-wave rectification is strongly nonlinear → THD ≈ 88 %, with a large 2nd harmonic (74 % of the fundamental) — exactly the even-harmonic-rich spectrum expected.

Vs in 0 SIN(0 1 1k)
R1 in a 50
D1 a out DMOD
Rout out 0 1k
.model DMOD D(IS=1e-14 N=1)
.tran 2u 20m
.control
  run
  fourier 1k v(out)      $ same maths as .four, run when you choose
.endc
.end

  No. Harmonics: 10, THD: 87.7379 %, Gridsize: 200, ...

The bare command fourier freq vec… is the interactive twin of the .four card: identical result, but computed on demand inside .control (e.g. after an alter, or on a vector you just built with let) rather than automatically at end of run.

.global  node …

Declares nodes that are the same net everywhere — reachable inside any subcircuit without being wired through its ports. The usual candidates are supplies and the substrate (vdd, gnd, vss). Ground node 0 is always global.

label name        goto name

An unstructured jump within a .control block. Prefer the structured loops (foreach/while/repeat); goto is for the occasional escape or a small state machine.

.ic       v(node) = value …      $ forced initial value (with .tran uic)
.nodeset  v(node) = value …      $ hint for the DC operating-point solver

.ic forces a node to a value at the start of a transient run when the analysis uses uic. .nodeset only seeds the DC solver (to pick between multiple solutions or aid convergence) and is released once DC converges — it does not force a transient start value.

V1 in 0 DC 0
R1 in out 1k
C1 out 0 1u
.ic v(out)=1
.tran 10u 5m uic
.control
  run
  print v(out)[0]                   $ 1.0 (the initial condition)
  meas tran vend FIND v(out) AT=5m  $ decays ~ e^-5
.endc
.end

v(out)[0] = 9.999000e-01
vend      = 6.73767e-03

C starts at 1 V and discharges through R (τ=RC=1 ms); at 5 ms = 5τ it is 1·e⁻⁵ = 6.7 mV ✓.

.if(expr)
  … cards …
.elseif(expr)
  … cards …
.else
  … cards …
.endif

Includes netlist cards conditionally at parse time, based on a parameter expression — corners, options, or variant topologies selected from one deck.

.include  filename
.lib      filename  section

.include textually inserts another file (parameters, subcircuits, models). .lib file section pulls only a named section — the standard way PDKs ship process corners.

let  name = expression      $ create/assign a vector
print  expression …         $ evaluate and show

let creates or overwrites a vector from an expression over existing vectors and constants; print evaluates any expression (arithmetic, node voltages v(n), branch currents i(vs), functions). Operators include + - * /, % (mod), comparisons, and many functions (sqrt, abs, db, …).

linearize [ vec … ]

A transient runs on an adaptive timestep, so its samples are unevenly spaced. linearize interpolates the vectors onto a uniform grid (step = the .tran tstep). Required before operations that assume even spacing — notably fft — and handy for exporting clean columns with wrdata.

listing [ logical | physical | deck | expand | runnable ]

Prints the current circuit as ngspice sees it after parsing — useful to confirm parameter substitution, subcircuit expansion (expand), or the exact runnable deck (runnable).

load [ rawfile … ]

Reads a raw file (from -r or write) into a new plot, so an earlier run’s data can be re-examined, compared, or post-processed without re-simulating.

.meas  analysis  result  FIND expr  AT=t | WHEN expr=val
.meas  analysis  result  MAX|MIN|AVG|RMS|PP|INTEG  expr  [FROM=t TO=t]
.meas  analysis  result  TRIG expr VAL=a RISE=n  TARG expr VAL=b RISE=n
.meas  analysis  result  PARAM='expr'

ngspice’s measurement command — the analog of SPICE .measure / Eldo .EXTRACT. It reduces an analysis result to a named scalar you can print, reuse in a later .meas, or feed to a script: peak/trough (MAX/MIN), average/RMS/peak-to-peak/integral over a window, a value at a time or when a condition holds (FIND … AT/WHEN), and delays/rise-times (TRIG … TARG).

The dot-card and the control-mode command share one measurement engine: the grammar above (TRIG/TARG, FIND/WHEN, MAX/MIN/PP/AVG/RMS/INTEG) and the numbers are identical either way. They are not fully interchangeable, though:

Rule of thumb: if the number is the end product (a batch/regression figure of merit, or you want autostop) use .meas; if the number is an input to more work — a let expression, a second measurement, or measuring a vector you built yourself — use the control-mode meas. The Q example below relies on exactly that reuse.

V1 in 0 PULSE(0 1 0 1n 1n 1 2)
R1 in a 20
L1 a out 1m
C1 out 0 1u
.tran 1u 1m
.control
  run
  meas tran vpeak  MAX  v(out)
  meas tran vfinal FIND v(out) AT=1m
  meas tran vavg   AVG  v(out) FROM=0.6m TO=1m
  meas tran vrms   RMS  v(out) FROM=0 TO=1m
  meas tran trise  TRIG v(out) VAL=0.1 RISE=1 TARG v(out) VAL=0.9 RISE=1
.endc
.end

vpeak  =  1.35098e+00  at=  1.04838e-04
vfinal =  1.00001e+00
vavg   =  9.99799e-01  from=6.0e-04 to=1.0e-03
vrms   =  9.97501e-01  from=0.0     to=1.0e-03
trise  =  4.24622e-05  targ=5.74e-05 trig=1.50e-05

Damping ζ = (R/2)·√(C/L) = 0.316 → overshoot e^{−πζ/√(1−ζ²)} ≈ 0.35, so the peak is 1.35 V ✓, reached at 105 µs (≈ half the ringing period), and the output settles to 1.0 V.

* parallel RLC tank: Q = R*sqrt(C/L) ; here R=316.23, L=1u, C=1n -> Q=10
Iac in 0 AC 1
R1 in 0 316.23
L1 in 0 1u
C1 in 0 1n
.ac dec 2000 1e6 30e6
.control
  run
  meas ac zmax MAX vm(in)              $ peak impedance = R, at fo
  let thr = zmax/sqrt(2)               $ -3 dB level
  meas ac flo WHEN vm(in)=thr RISE=1   $ lower skirt
  meas ac fhi WHEN vm(in)=thr FALL=1   $ upper skirt
  let Q = sqrt(flo*fhi)/(fhi-flo)      $ Q = fo / bandwidth
  print Q
.endc
.end

zmax                =  3.16211e+02 at=  5.03567e+06
flo                 =  4.78753e+06
fhi                 =  5.29089e+06
q = 9.998790e+00

A current source drives the tank, so vm(in) is its impedance: it peaks at R at the resonance f_o, and the two frequencies where it falls to R/√2 bound the bandwidth. Combining meas (peak + both skirts) with let yields Q = f_o/BW = 10, matching R·√(C/L) ✓. The RISE=1/FALL=1 qualifiers pick the lower and upper crossings.

.model  name  type ( param=value … )

Defines a named parameter set shared by every instance that references it. The instance card names the model in its model position (e.g. D1 a k MYDIODE).

* force 10uA base current, read back beta = Ic/Ib
.model MYNPN NPN(IS=1e-16 BF=100 VAF=80)
IB 0 b DC 10u
Q1 c b 0 MYNPN
VC c 0 DC 5
.op
.control
  run
  let beta = -i(vc)/10u      $ negate: current is into the VC source
  print beta
.endc
.end

beta = 1.052822e+02

β comes out just above the model’s BF=100: the Early effect (VAF=80) lifts it to BF·(1+V_CE/VAF) ≈ 106 at V_CE=5 V ✓.

* LEVEL-1 NMOS in saturation, drain current from KP/VTO
.model NMOS1 NMOS(LEVEL=1 VTO=0.7 KP=120u LAMBDA=0)
M1 d g 0 0 NMOS1 W=10u L=1u    $ drain gate source bulk model
VG g 0 DC 1.7
VD d 0 DC 3
.op
.control
  run
  let id = -i(vd)               $ negate: current is into VD
  print id
.endc
.end

id = 6.000000e-04

The M card names four nodes (drain, gate, source, bulk) then the model, with W/L per-instance. With V_GS=1.7, V_DS=3 (saturated) and LAMBDA=0, I_D = ½·KP·(W/L)·(V_GS−V_TO)² = ½·120 µ·10·(1.0)² = 600 µA ✓.

.noise  v(output [,ref])  input_source  dec|oct|lin  n  fstart  fstop  [ pts_per_summary ]

Computes output-referred and input-referred noise spectral density vs. frequency (vectors onoise_spectrum, inoise_spectrum), and their integrals over the band (scalars onoise_total, inoise_total, in V and V/√Hz-integrated → V rms).

* Output noise of RC low-pass -> integrates to sqrt(kT/C)
V1 in 0 DC 0 AC 1
R1 in out 1k
C1 out 0 100n
.noise v(out) V1 dec 100 0.1 100meg
.control
  run
  print onoise_total
.endc
.end

onoise_total = 2.035612e-07

The resistor’s thermal noise, low-pass filtered by C, integrates to the classic √(kT/C) = √(1.38e-23·300/100 nF) = 2.03e-7 V rms — independent of R ✓. A textbook result the tool reproduces to three digits.

* thermal floor of a 1k resistor = sqrt(4kTR) = 4.07 nV/rtHz, flat
V1 in 0 DC 0 AC 1
R1 in out 1k
C1 out 0 1p
.noise v(out) V1 dec 10 1 1k
.control
  run
  setplot noise1              $ spectra live in noise1, totals in noise2
  print onoise_spectrum[0]
.endc
.end

onoise_spectrum[0] = 4.071372e-09

√(4kTR) = √(4·1.38e-23·300·1 kΩ) = 4.07 nV/√Hz ✓.

.op

Solves the quiescent DC bias: all capacitors open, all inductors shorted, sources at their DC value. Prints every node voltage and source current, and (in interactive mode) makes the small-signal device operating-point parameters available. It is the starting point of .tran (unless uic) and .ac.

* DC operating point of a resistive divider
V1 in 0 DC 1
R1 in mid 1k
R2 mid 0 1k
.op
.end

Node                                   Voltage
in                               1.000000e+00
mid                              5.000000e-01

v(mid) = 1 V · R2/(R1+R2) = 0.5 V ✓.

.option  name[=value] …

Sets tolerances, temperature, integration method, and output behavior. The most common:

When Newton–Raphson fails to converge, ngspice does not simply give up: it escalates through a ladder of progressively more robust (and more expensive) methods — dynamic gmin stepping, true gmin stepping, source stepping, and finally optran/pseudo-transient. The itl options decide how long it flails at Newton before moving on, and the whole value of a fallback ladder is reaching it early.

The catch: for decades the solver silently raised any of these limits to a floor of 100. That made itl4 (default 10) and itl2 (default 50) inoperative at their own documented defaults, and made a user-supplied itl1 below 100 a no-op. On a small circuit this is invisible: every timepoint converges in two or three iterations, so the limit is never reached and it cannot matter — which is exactly why it went unnoticed, and why no regression test catches it: every circuit in the suite converges. It becomes visible only on a deck that fails to converge, where the solver then burns the full 100 iterations — ten times the budget itl4 asked for — at every rejected timestep, before it will consider a method that might actually work.

maxiterfloor exposes that floor. It defaults to 100, so every existing deck behaves exactly as before; set maxiterfloor=0 and itl1/itl2/itl4 mean what the table says.

.option itl1=3            $ ask Newton to give up after 3 iterations
.option maxiterfloor=0    $ ... and actually mean it
.control
  set iter_verbose
  op
.endc

  NIiter: iteration 1 of at most 3  (0.00 s)
  NIiter: iteration 2 of at most 3  (0.00 s)
  NIiter: iteration 3 of at most 3  (0.00 s)
  NIiter: iteration 4 of at most 3  (0.00 s)
Note: Newton iteration failed, escalating to fallback OP methods
Note: Starting dynamic gmin stepping
  NIiter: iteration 1 of at most 50  (0.00 s)

Newton is abandoned after 3 iterations and the ladder takes over. Delete the maxiterfloor=0 line and the very same deck prints iteration 1 of at most 100: itl1=3 is discarded.

set iter_verbose (a front-end variable, not an option) is what produces those lines. It reports every Newton iteration with its wall-clock cost, flushed immediately — without it a long solve is completely silent, and there is no way to tell a slow iteration from a hang, nor to measure what an iteration actually costs on a big circuit.

These are ordinary options — use them on any deck when you want the behaviour they describe. They earn their keep most often on a post-layout (extracted) netlist, because extraction produces things a hand-written circuit rarely has — millions of parasitic elements, resistors of 0 Ω, capacitors of 0 F, and nodes that nothing actually connects to — but nothing about them is specific to extracted decks. The three answer three different problems.

The mechanism, concretely. At DC a capacitor is an open circuit and a MOSFET gate draws no current, so a floating gate — a gate wired to nothing else — has no resistive path to anywhere. Its row in the conductance matrix is all zeros: nothing sets its voltage, the matrix loses rank, and the solver stops with singular matrix. floatgmin attaches a single conductance of 1e-12 S (a 1 TΩ resistor, the default) from that node to ground. That places one nonzero term on the node's diagonal, which is all the matrix needs: the row is no longer empty, the node acquires a DC reference and simply sits at 0 V. Because 1 TΩ passes essentially no current (a picoamp per volt), it changes nothing else in the circuit — it is a reference, not a load. The classic structures it rescues, both routine in extracted layout, are exactly this dangling gate and the MOS with only its bulk connected (drain, gate and source all going nowhere); commercial simulators prune such devices at elaboration, ngspice keeps them, so their nodes stay unreferenced until floatgmin supplies the path.

* Floating nodes: a dangling MOS gate and a bulk-only MOS
.model nm nmos level=1 vto=0.7 kp=100u
V1 d 0 2
R1 d dd 1k
VG g 0 1.5
M1 dd g 0 0 nm w=10u l=1u             $ working device, gate driven
M2 dd floatg 0 0 nm w=10u l=1u        $ gate dangles -> node floatg floats
M3 dead1 dead2 dead3 0 nm w=10u l=1u  $ only the bulk is connected
.control
  set topo_verbose
  op
  print v(dd)
.endc
.end

  floating node: floatg
  floating node: dead1
  floating node: dead2
  floating node: dead3
Topology reduction: 4 floating node(s) tied to ground through 1e-12 S (.option floatgmin).
v(dd) = 1.680000e+00

The working device M1 solves normally. Add .option floatgmin=0 to the same deck and every DC method fails in turn:

Warning: singular matrix:  check node dead2
Note: Newton iteration failed, escalating to fallback OP methods
Warning: Dynamic gmin stepping failed
Warning: True gmin stepping failed
Warning: source stepping failed

set topo_verbose (a front-end variable, not an option) prints the offending node names and also writes them to float_nodes.txt — on a real extracted deck that file is how you find out which nets your extraction left dangling. Without it the reduction is silent.

Not every hard operating point is a broken one. A circuit can be perfectly well-posed — a unique DC solution exists — and still defeat Newton–Raphson from a cold start: high-gain feedback loops (bandgaps, comparators, ring oscillators, latches) make the Newton map oscillate, and gmin- and source-stepping lose the path. For these, ngspice inherits the standard escalation ladder — Newton → gmin stepping → source stepping → optran — and pstran adds one more, final rung.

pstran is pseudo-transient continuation: it finds the DC point by pretending to run a transient and letting the circuit settle. It attaches an artificial capacitor Cp (pstrancp, default 1 nF) from every node to ground and steps forward in a fictitious “pseudo time” using backward Euler, with no truncation-error control — the trajectory is meaningless, only the resting state matters.

The mechanics are the useful part. At each pseudo step of size dt, the backward-Euler companion of each artificial capacitor puts a conductance g = Cp/dt on that node's matrix diagonal and a current source g·v_prev (its voltage at the previous step) on the right-hand side. That added diagonal term is what buys the robustness: it makes each step's Jacobian diagonally dominant and well-conditioned, so Newton converges at that step even on a circuit where a cold-start Newton would oscillate or diverge. The step is solved, vprev is updated, and dt is grown aggressively (×2, then ×10 on repeated success). As dt → ∞, g = Cp/dt → 0: the artificial capacitor's conductance and its RHS current both vanish, the added terms disappear from the system, and what remains is the original circuit at steady state — the exact DC operating point. So it is a homotopy: it walks from an easy, heavily-damped problem (small dt, large g) to the real one (g → 0) in continuous steps, and each intermediate step is one Newton solve that actually converges. Physically it is the numerical form of bringing a bench supply up through a soft-start instead of slamming the rail on.

dptran is the damped variant: on top of the pseudo capacitor it also clamps how far any node voltage may move in a single Newton iteration (0.3 V), which stops a positive-feedback stage — a latch, a bandgap, a comparator — from overshooting past its solution and re-diverging. It trades more iterations for that safety; reach for it when plain pstran still will not settle.

* pstran: a high-gain feedback ring that defeats Newton
b1 n2 0 v = 0.9 - 0.89*tanh(200*(v(n1)-0.9))
b2 n3 0 v = 0.9 - 0.89*tanh(200*(v(n2)-0.9))
b3 n1 0 v = 0.9 - 0.89*tanh(200*(v(n3)-0.9))
r1 n1 0 1meg
.option pstran
.control
  op
  print v(n1) v(n2) v(n3)
.endc
.end

Note: Newton iteration failed, escalating to fallback OP methods
Note: Starting dynamic gmin stepping        ... (fails)
Note: Starting source stepping              ... (fails)
Note: Starting pseudo-transient continuation (pstran)
Note: Pseudo-transient continuation completed
v(n1) = 9.000000e-01
v(n2) = 9.000000e-01
v(n3) = 9.000000e-01

Three high-gain tanh stages in a ring: Newton two-cycles on the steep map, gmin stepping cannot damp voltage-forced nodes, and source stepping loses the path near full value — yet the circuit has one honest solution (all nodes at 0.9 V), and pstran relaxes into it.

The remaining cp_coms commands, for completeness. Aliases point at their documented twin; developer/debug dumps are grouped at the end.

.param  name = value   [ name2 = expr … ]
.func   name(args) = { expression }

.param defines named constants (usable in any value via {name}); .func defines a parameter-time function. Both are resolved during parsing — they cannot see simulation results (for that, use let/define in .control).

.param rval=agauss(1k,100,3)   $ gaussian: nominal 1k, ±100 at 3σ
V1 in 0 DC 1
R1 in 0 {rval}
.op
.control
  setseed 7
  run
  print @R1[resistance]        $ one random draw
.endc
.end

@r1[resistance] = 1.009399e+03

agauss/gauss/unif draw random parameter values (fixed with setseed for reproducibility) — the basis of a Monte-Carlo loop with foreach + alter.

.plot  analysis  expr ...          $ batch: ASCII line plot
plot   expr ... [ vs xexpr ]       $ control mode: graphical window
plot   "regexp" ...                $ plot every matching vector

A double-quoted argument is a regular expression matched over the current plot (like display): plot ".*#branch" plots all branch currents. The quotes are required because bare metacharacters are expression operators; unquoted vs/limit keywords and expressions are untouched. (Applies equally to gnuplot and hardcopy, which share the plot engine.)

Three siblings render the same vectors different ways: asciiplot vec… draws the text plot shown above straight into the log (identical to a .plot card); gnuplot file vec… hands off to gnuplot; and hardcopy file vec… writes a PostScript file — the only one that works cleanly under -b for automated figure generation.

V1 in 0 SIN(0 1 1k)
R1 in out 1k
C1 out 0 100n
.tran 20u 1m
.control
  run
  set hcopypscolor=1     $ colour instead of monochrome
  hardcopy plot.ps v(out)
.endc
.end

plot.ps : %!PS-Adobe-3.0 EPSF-3.0   (a ~9 kB Encapsulated PostScript figure)

print  expr ...                    $ control mode: dump values to stdout
print  "regexp" ...                $ control mode: values of all matching vectors
.print  analysis  expr ...         $ batch: a formatted table

Because arguments are expressions (where *, (, … are operators), a regular expression must be double-quoted: print ".*#branch" prints every branch current, print "v.*" every v-node — matched over the current plot (same regex as display). Unquoted expressions like v(out) or vdb(a)-vdb(b) are unaffected.

Control-mode print writes the value of vectors/expressions to the console (a scalar prints on one line; a vector prints all points). The dot-card .print tran|ac|dc … produces a numbered table of the named vectors after the run — and is one of the output directives that make an analysis actually run in batch mode.

* two instances X1, X2 of a stage -> internal nodes x1.n1, x2.n1, ...
Vin in 0 DC 3
X1 in  mid stage
X2 mid out stage
RL out 0 1k
.subckt stage a z
  R1 a n1 1k
  R2 n1 n2 1k
  R3 n2 z 1k
.ends
.op
.control
  run
  print "x1.*"        $ every node inside instance X1 (quotes required)
.endc
.end

x1.n1 = 2.571429e+00
x1.n2 = 2.142857e+00

One line dumps every node inside X1. On a real design this is the fast way to inspect a subcircuit — the two-stage amplifier in user_examples/two_balance.cir (see .subckt) exposes x1.a, x1.b, x1.vp, x1.vcm, x2.…, so print "x1.*" reads back that whole instance at once. Two gotchas — both covered in the display entry — apply here: the quotes are required (bare */( are operators), and a batch .op also prints a separate operating-point device dump that is not from print. Empty @dev[i] vectors (AC savecurrents) are skipped automatically; use "^x1\." to match only nodes and exclude device-current vectors.

.pz  node1 node2 node3 node4  cur|vol  pz|pol|zer

Finds the poles and/or zeros of a small-signal transfer function about the DC operating point. node1 node2 are the input port, node3 node4 the output port; vol (voltage transfer) or cur (transimpedance); pz = both, pol = poles only, zer = zeros only. Results appear as complex vectors pole(k), zero(k) (rad/s).

* Pole–zero of an RC low-pass: v(out)/v(in)
V1 in 0 AC 1
R1 in out 1k
C1 out 0 100n
.pz in 0 out 0 vol pz
.control
  run
  print pole(1)
.endc
.end

pole(1) = -1.00000e+04,0.000000e+00

A single real pole at −10⁴ rad/s = −1/RC (= −1591 Hz), with no finite zero ✓. Poles are in rad/s; divide by 2π for Hz.

repeat [ n ]        if condition        break / continue
  … body …            … body …          (exit / skip a loop pass)
end                 else
                      … body …
                    end

reset      $ re-setup the circuit to its just-parsed state
rehash     $ rebuild the executable-command hash
help [subject]     quit     bug     tutorial

reset restores the circuit to its initial state, undoing alters and prior runs; help browses the built-in docs; quit exits; bug shows the bug-report address; tutorial points at the tutorials.

reshape   vec …  [dim1,dim2,…]   $ change a vector's dimensions
transpose var …                  $ transpose a multi-dimensional vector
cutout    vec …                  $ keep only the current scale range
cross     newvec index vec …     $ build a vector from one index across others

Manipulate the shape/contents of data vectors — reshape a flat vector into a matrix, transpose it, trim to a window, or gather a cross-section. Mostly for post-processing multi-dimensional (e.g. swept) results.

Without any .save, a -r run stores the default set: every node voltage and every voltage-source current. A .save (or control-mode save) replaces that with exactly the vectors you name, always alongside the time/frequency scale. Use it to shrink large raw files, or to store an expression such as a differential voltage.

save runs before the circuit, so a regex argument matches the circuit node names (not plot vectors): save vd.* saves every node starting with vd, save .*out.* every node containing out. The save spec forms v(..)/i(..), @dev[param] and all are not treated as patterns. Bare regex is fine here (unlike print) because save’s arguments are names, not expressions.

V1 p 0 SIN(0 1 1k)
V2 n 0 SIN(0 0.7 1k)
R1 p 0 1k
R2 n 0 1k
.save v(p) v(n) vdiff=par('v(p)-v(n)')
.tran 50u 1m
.end

No. Variables: 4
   1  v(p)      voltage
   2  v(n)      voltage
   3  v(vdiff)  voltage      ← the saved expression

.save name=par('expr') stores a computed vector straight into the raw file — the clean way to capture a differential output without post-processing.

* @device[param] exposes a model's internal quantities
.model NMOS1 NMOS(LEVEL=1 VTO=0.7 KP=120u LAMBDA=0)
M1 d g 0 0 NMOS1 W=10u L=1u
VG g 0 DC 1.7
VD d 0 DC 3
.options savecurrents      $ makes @m1[id] @m1[is] ... available too
.op
.control
  run
  print @m1[gm] @m1[vdsat] @m1[id]
.endc
.end

@m1[gm]    = 1.200000e-03
@m1[vdsat] = 1.000000e+00
@m1[id]    = 6.000000e-04

Beyond node voltages and source currents, @name[param] reads a device's internal values — here g_m = KP·(W/L)·(V_GS−V_TO) = 1.2 mA/V and V_dsat = 1.0 V ✓. Hierarchical instances use the full path, e.g. @m.x1.x2.m1[vgs]. Per-terminal branch currents (@m1[id], @m1[is], …) need .options savecurrents; you can save or plot any of these like an ordinary vector.

.sens  output_variable                        $ DC sensitivity
.sens  output_variable  ac  dec n fstart fstop  $ AC sensitivity

Computes the sensitivity of an output to every circuit element and model parameter, at the DC operating point (or over frequency with the ac form). Results land in a Sensitivity Analysis plot: the bare element name (e.g. r1) is d(output)/d(element value), and elem:param (e.g. r1:tc1) breaks it down per model parameter.

V1 in 0 DC 1
R1 in out 1k
R2 out 0 3k
.sens v(out)
.control
  run
  print r1 r2 v1     $ dV(out)/dR1, /dR2, /dV1
.endc
.end

r1 = -1.87500e-04
r2 =  6.249994e-05
v1 =  7.500000e-01

For v(out) = V·R2/(R1+R2) = 0.75 V: dV/dR1 = −V·R2/(R1+R2)² = −1.875e-4, dV/dR2 = +V·R1/(R1+R2)² = +6.25e-5, and dV/dV1 = R2/(R1+R2) = 0.75 — all matched ✓.

set name = value          $ define a shell variable
$name                     $ expand a shell variable (text)
$&vecname                 $ expand the numeric value of a vector

set makes a shell variable (a string/flag, e.g. set appendwrite). $name substitutes its text. To drop a vector’s numeric value into a command line (e.g. an echo or a filename), use $&vecname — the & is what says “take the value of the vector”, not “look up a shell variable”.

Some behaviour is controlled by set variables rather than .option, because it belongs to the front end. The two most useful when a large deck misbehaves — set iter_verbose (report every Newton iteration and its cost) and set topo_verbose (report what topology reduction tied or removed) — are described under .option, and are best placed in .spiceinit so they are active before the deck is even read.

setplot [ plotname ]     $ list plots / switch the current one
setscale [ vecname ]     $ set the default scale of the current plot
destroy [ plotname … ]   $ free a plot's data (or 'all')

Each run/analysis makes a new plot (a named vector set: tran1, ac1, sens1, …) — so the plot list is your list of completed simulations. setplot with no argument lists them, marks the current, and shows each one’s analysis type and title (and interactively prompts you to pick one); with a name it switches. Cross-plot references use plot.vector (e.g. ac1.inp). destroy reclaims memory.

V1 in 0 AC 1 SIN(0 1 1k)
R1 in out 1k
C1 out 0 100n
.control
  op                 $ -> plot op1
  ac dec 10 1 1meg   $ -> plot ac1
  tran 20u 1m        $ -> plot tran1
  setplot            $ list all plots, marks the current
  setplot ac1        $ switch to the AC plot
  display            $ vectors in ac1
.endc
.end

List of plots available:

Current tran1   * … (Transient Analysis)
        ac1     * … (AC Analysis)
        op1     * … (Operating Point)
        const   Constant values (constants)

Three runs → three plots, each tagged with its analysis. A second tran would add tran2, so the list doubles as a run history. echo $plots gives the same names tersely (const op1 ac1 tran1) when you need them in a script.

setseed  integer

Fixes the seed of the random generator used by agauss/gauss/unif and Monte-Carlo draws, so a randomized run is exactly reproducible — set the same seed before each run to repeat a sequence.

settype  type  vec | regexp …     $ type = voltage | current | time | frequency | impedance | …

Relabels a computed vector’s physical type so plots and printouts carry the correct axis label and units (a derived impedance, power, gain, …). A vector argument containing regex metacharacters retypes every current-plot vector whose name matches — e.g. settype impedance .*#branch (same regex selection as display).

shell [ command ]     cd [ dir ]     getcwd

shell runs an OS command (or forks an interactive shell); cd/getcwd change and print the working directory. Handy for pre/post-processing around a run.

R1 1 0 1k
V1 1 0 DC 5
.op
.control
  run
  set nwords = `echo one two three four five | wc -w`   $ capture OS stdout
  echo "the shell counted $nwords words"
  let total = $nwords * 2                                $ feed it into a let
  print total
.endc
.end

the shell counted 5 words
total = 1.000000e+01

Backticks `…` run a command and paste its standard output straight into the .control line — the ngspice analogue of shell command substitution. Combined with set/let it lets an external tool (sed, awk, wc, a helper script) feed values back into the simulation.

snsave file      snload file

Writes (or reloads) a full simulator snapshot — node values and internal state — so a long run can be checkpointed and continued later, or a hard-won operating point reused as a starting condition.

source  file        edit [ file ]

source reads and loads another netlist file into the running session; edit opens the current (or a named) deck in $EDITOR and reloads it on exit. Interactive workflow aids; use .include for static composition.

.sp   dec|lin n fstart fstop     $ S-parameters (needs P RF-port elements)
.pss  fund tstop points …        $ periodic steady state (shooting method)
.hb   fund nharm                 $ harmonic balance

.sp computes scattering parameters and requires P RF-port elements (each with a reference impedance) on the ports of interest. .pss (periodic steady state) and .hb (harmonic balance) are large-signal RF analyses for finding a circuit’s steady periodic response directly.

spec  fstart  fstop  fstep  vector …

Like fft, but computes the spectrum at the exact frequencies you name (fstart…fstop by fstep), rather than the FFT’s fixed 1/timespan bins. Run linearize first.

stop [ after n ] [ when expr ] …    $ set a breakpoint / condition
resume                              $ continue a stopped run
delete [ all | number … ]           $ remove breakpoints

Pause a transient at a time, iteration, or condition to inspect state, then resume. Most useful interactively (or when driven from a script that examines vectors at each stop).

strcmp   var s1 s2            $ var = C strcmp(s1,s2): 0 if equal
strstr   var s1 s2            $ var = index of s2 in s1 (-1 if absent)
strslice var s1 offset len    $ var = s1[offset .. offset+len)

Each sets a shell variable from a string operation, for scripting file names, labels, and conditionals in .control.

.subckt  name  node1 node2 …  [ param=default … ]
  … elements …
.ends
Xname  net1 net2 …  name  [ param=value … ]      $ instantiation

A subcircuit is a reusable block with external ports and optional parameters. Instantiate it with an X card, wiring your nets to its ports and overriding parameters by name. Internal nodes are addressed hierarchically as Xinstance.node (e.g. v(x1.mid) above).

* one parameterized RC low-pass, reused at three cutoffs
V1 in 0 AC 1
Xdef in def rclp                 $ takes the default  c=1n  -> ~159 kHz
Xmid in mid rclp c=10n           $ override by name   -> ~15.9 kHz
Xlo  in lo  rclp c=100n          $ override by name   -> ~1.59 kHz
.subckt rclp a b r=1k c=1n       $ r,c are params with defaults
  R1 a b {r}                     $ {..} evaluates the param
  C1 b 0 {c}
.ends
.ac dec 100 100 1meg
.control
  run
  meas ac fcdef WHEN vdb(def)=-3.0103
  meas ac fcmid WHEN vdb(mid)=-3.0103
  meas ac fclo  WHEN vdb(lo)=-3.0103
.endc
.end

fcdef               =  1.59155e+05
fcmid               =  1.59155e+04
fclo                =  1.59155e+03

Parameters are declared as name=default on the .subckt line and used inside as {name}. Each X card overrides by name (Xmid … c=10n) or, like Xdef, inherits the default. The three cutoffs land exactly on 1/(2π·1 kΩ·C) for C = 1 n, 10 n, 100 n ✓ — one definition, three behaviours.

* two instances of the same subcircuit, chained
xa vcasc inp inn ib0 op   on   vdd gnd balance_simple
xb vcasc op  on  ib1 outp outn vdd gnd balance_simple
.include ngspice_stimuli2               $ models + sources + .control

.subckt balance_simple vcasc inp inn ib outn outp vdd gnd
  M3 a inp vcm gnd nch w=10u l=0.18u m=1000    $ input diff pair
  M1 b inn vcm gnd nch w=10u l=0.18u m=1000
  M2 outn vcasc a gnd nch w=10u l=0.18u m=100  $ cascode devices
  M4 outp vcasc b gnd nch w=10u l=0.18u m=100
  M5 vcm ib gnd gnd nch w=10u l=0.6u m=100     $ tail current sink
  M6 outn vp  vdd vdd pch w=5u l=0.25u m=500   $ PMOS load
  M7 outp vp  vdd vdd pch w=5u l=0.25u m=500
  R1 vp outn 10meg   $  R2 vp outp 10meg  (common-mode feedback)
.ends

* --- ngspice_stimuli2 (excerpt): extract Cdiff from two AC runs ---
.control
  ac dec 100 1k 11e6                       $ ac1: common-mode drive
  meas ac vinp_cm   find ac1.inp at=1e3
  alter vinp acphase 0
  alter vinn acphase 180                   $ ac2: differential drive
  ac dec 100 1k 11e6
  meas ac vinp_diff find ac2.inp at=1e3
  let cinp = 10p*(1/ac2.vinp_diff - 1/ac1.vinp_cm)/2
  echo "Cdiff = $&cinp"
.endc

Warning: command 'plot' is not available during batch simulation, ignored!
vinp_cm   = 4.887917e-01
vinp_diff = 4.803305e-01
Cdiff  = 1.80193E-13

The block is instantiated twice (xa, xb) and chained; the script drives it common-mode then differentially and computes the differential input capacitance, Cdiff ≈ 0.18 pF. Note the batch warning: the interactive plot is ignored under -b (use .plot / gnuplot) — see § plot vs .plot. (User-contributed example; generic LEVEL-3 models, no foundry data.)

Passband differential gain ≈ 3.93 dB, flat to ~1 MHz, rolling off by ~10 MHz — the amplifier bandwidth. (This is what the batch-ignored plot would have shown; here it is drawn from the saved data.)

.temp  value_in_celsius        $ or, in .control:  set temp = value

Sets the analysis temperature (°C). Every temperature-dependent model (diode/BJT/MOS saturation currents, resistor tc1/tc2, …) is re-evaluated. In .control you can change set temp between runs to sweep temperature.

.model DMOD D(IS=1e-14)
V1 a 0 DC 0.65
D1 a 0 DMOD
.tran 1u 5u
.control
  set temp = 27
  run
  print -i(v1)[0]        $ 0.82 mA
  set temp = 100
  run
  print -i(v1)[0]        $ 51 mA
.endc
.end

-i(v1)[0] = 8.204764e-04
-i(v1)[0] = 5.113547e-02

At a fixed 0.65 V the diode conducts 62× more at 100 °C — the strong temperature dependence of the saturation current ✓.

.tf  output_variable  input_source

Computes, at the DC operating point, the small-signal ratio output/input, the resistance seen at the input source, and the resistance seen at the output. One command for gain and both port impedances.

* DC small-signal transfer function
V1 in 0 DC 1
R1 in out 1k
R2 out 0 3k
.tf v(out) V1
.end

transfer_function          = 7.500000e-01
output_impedance_at_v(out) = 7.500000e+02
v1#input_impedance         = 4.000000e+03

Gain = R2/(R1+R2) = 0.75; Z_out = R1‖R2 = 750 Ω; Z_in = R1+R2 = 4 kΩ ✓.

.tran  tstep  tstop  [ tstart  [ tmax ] ]  [ uic ]

Computes the circuit response in the time domain from tstart (default 0) to tstop. tstep is the printing/initial step; the actual internal step is chosen adaptively by local-truncation-error control and never exceeds tmax (default (tstop−tstart)/50). Results are stored in the current plot as vectors indexed by the time scale.

* RC low-pass step response
V1 in 0 PULSE(0 1 0 1n 1n 1 2)
R1 in out 1k
C1 out 0 1u
.tran 0.1m 5m
.control
  run
  meas tran v5ms  FIND v(out) AT=5m
  meas tran trise TRIG v(out) VAL=0.1 RISE=1 TARG v(out) VAL=0.9 RISE=1
.endc
.end

ngspice -b rc.cir

No. of Data Rows : 79
v5ms                =  9.93289e-01
trise               =  2.19596e-03   targ=  2.30186e-03   trig=  1.05894e-04

The output settles to 0.993 V at 5 ms (= 5τ, so 1 − e⁻⁵ ≈ 0.993 ✓), and the 10–90 % rise time is 2.196 ms ≈ 2.2τ, as expected for a single-pole RC.

L1 n 0 1m
C1 n 0 100n ic=1        $ start the cap at 1 V
.tran 1u 400u uic       $ no DC op; use the initial condition
.control
  run
  meas tran period TRIG v(n) VAL=0 FALL=1 TARG v(n) VAL=0 FALL=2
.endc
.end

period = 6.28842e-05

An LC tank has no DC operating point to settle to; uic starts it from C1’s ic=1 and it oscillates at T = 2π√(LC) = 2π√(1 mH·100 nF) = 62.8 µs ✓.

unlet  vecname | regexp …

Removes vectors from the current plot (frees memory, or drops intermediates before a write). The inverse of let. An argument containing regex metacharacters deletes every current-plot vector whose name matches — e.g. unlet temp.*, unlet .*#branch (same grep-style regex selection as display; the scale vector is protected).

version [n]     sysinfo     rusage [resource]     history [-r] [n]

version prints the ngspice version (and can assert a minimum); sysinfo reports CPU/memory; rusage prints resource counters (time, memory, iterations) — useful for benchmarking; history lists past commands.

where     $ node/device with the largest residual (non-convergence)
dump      $ the circuit's node/branch matrix
state     $ current analysis state
status    $ analyses in progress and breakpoints

Convergence and state introspection. where names the node or device carrying the largest residual after a failed Newton step — the first thing to check on a “no convergence” error; dump prints the raw matrix; state/status report the analysis and any breakpoints.

while  condition          dowhile  condition
  … body …                  … body …
end                       end

wrdata  file  expr ...

Writes the scale (time/frequency) and each expression as whitespace-separated columns of plain text — the easiest format to hand to gnuplot, a spreadsheet, or a script. Control mode only (no dot-card form). A double-quoted argument is a regular expression over the current plot — wrdata f.txt ".*#branch" writes every branch current as columns (same rule as print).

V1 in 0 SIN(0 1 1k)
R1 in out 1k
C1 out 0 100n
.tran 100u 1m
.control
  run
  set wr_singlescale     $ one time column, not one per expression
  set wr_vecnames        $ prepend a header row of vector names
  wrdata multi.txt v(in) v(out)
.endc
.end

 time            v(in)           v(out)
 0.00000000e+00  0.00000000e+00  0.00000000e+00
 1.00000000e-07  6.28318489e-04  6.27690799e-07
 …

By default wrdata repeats the scale column before every expression (so N exprs give 2N columns). set wr_singlescale collapses that to one scale + N value columns; set wr_vecnames adds the name header — the two settings that make the file gnuplot- and spreadsheet-ready.

V1 in 0 SIN(0 1 1k)
R1 in out 1k
C1 out 0 100n
.tran 20u 1m
.control
  run
  wrnodev nodes.ic       $ present node voltages -> .ic cards
.endc
.end

# nodes.ic
* Recorded at simulation time: 0.001
.ic v(in) = -2.44929e-16
.ic v(out) = -0.450639

Unlike wrdata (which writes a whole waveform), wrnodev captures just the present operating state of every node as ready-to-.include .ic cards — a convenient way to seed another run from where this one stopped.

-r file dumps the run’s default (or .save-restricted) set to file. write file2 expr…, inside .control, writes a chosen set to file2. They coexist only if the filenames differ. A double-quoted argument is a regular expression over the current plot — write br.raw ".*#branch" writes every branch current (same rule as print).

V1 in 0 SIN(0 1 1k)
R1 in out 1k
C1 out 0 100n
.tran 100u 1m
.control
  run
  set filetype=ascii      $ default is binary
  write out_ascii.raw v(out)
.endc
.end

Title: * set filetype=ascii makes 'write' emit a human-readable rawfile.
Plotname: Transient Analysis
Flags: real
No. Variables: 2
No. Points: 63
Variables:
	0	time	time
	1	v(out)	voltage
Values:
 0	0.000000000000000e+00
	0.000000000000000e+00
 …

Rawfiles are binary by default (compact, exact). set filetype=ascii before write emits the same structure as text — readable, diff-able, and loadable back with load. It applies to -r too.

V1 in 0 SIN(0 1 1k)
R1 in out 1k
C1 out 0 100n
.tran 20u 1m
.control
  let rk = 1k
  while rk le 3k
    alter r1 rk
    run
    write sweep.raw v(out)
    set appendwrite      $ 2nd run onward: append, don't overwrite
    let rk = rk + 1k
  end
  destroy all            $ clear the in-memory run plots first
  load sweep.raw         $ ...so echo shows only what the FILE holds
  echo $plots
.endc
.end

const tran1 tran2 tran3

Normally each write overwrites; set appendwrite makes subsequent writes append a new plot instead — the idiom for sweeping a parameter with alter and keeping every run in one raw file. Reload it and each run reappears as tran1, tran2, … (the destroy all is only so the echo isn’t cluttered by the plots still live from this session).

Automatic: any behavioral resistor (R='…v(a,b)…') or capacitor (C='…v(a,b)…') in the netlist is compiled at parse time. The run log reports what was generated, e.g. osdi-res: N resistor(s) + M capacitor(s) -> K C-OSDI model(s).

The codegen is the default; one boolean variable is the global opt-out. With set osdi_res_bsource, every behavioral R=/C= keeps its original B-source implementation instead — no compilation, no OSDI device. It governs resistors and capacitors together.

* in .spiceinit (it is read before the deck is parsed):
set osdi_res_bsource        $ keep all behavioral R/C as B-sources, skip OSDI codegen

Put it in .spiceinit, not in the deck’s .control: codegen runs at parse time, before an in-deck .control block executes, so setting it there would be too late. Verified — with the flag the osdi-res: line disappears and the circuit runs the behavioral network. Two more behaviors: even with codegen on, a device whose expression uses an unsupported function, or a system with no gcc, falls back to B-source automatically (warned once); and set osdi_res_include="/path" overrides the C header include directory used when compiling the generated model.

.param r0=1000 k=0.1 c0=1e-12 vc=0.05
* voltage-dependent resistor  R(v) = r0*(1 + k*v^2)
vr a 0 dc 1
Rtest a 0 R='r0*(1 + k*v(a,0)*v(a,0))'
* voltage-dependent capacitor  C(v) = c0*(1 + vc*v)
vx n 0 dc 0 pulse(0 1 1n 1n 1n 20n 40n)
Rin n x 1k
Ctest x 0 c='c0*(1 + vc*v(x,0))'
.control
  op
  print i(vr)
  tran 0.5n 40n
.endc
.end

osdi-res: 1 resistor(s) + 1 capacitor(s) -> 2 C-OSDI model(s); 0 kept behavioral; 0 shorted/dangling cap(s) dropped
i(vr) = -9.09091e-04

The two behavioral expressions are compiled into two native OSDI devices, and the DC check is exact: at v(a)=1 V, R = r0(1 + k·1²) = 1100 Ω, so i(vr) = −1/1100 = −9.09e-4 A ✓ (negative by source convention — see .dc).

Besides the automatic path, two .control commands emit a C-OSDI model on demand:

osdigen   modelname n1 n2 expr    $ resistor  R(v) from a behavioral expression
osdigenc  modelname n1 n2 qexpr   $ capacitor from a charge expression Q(v)

Use them to pre-generate and inspect a model (e.g. to check the emitted C, or build a library) rather than letting the parser compile netlist behaviorals silently. Same generator, same output devices.