Ngspice Ultimate Master Command Reference Guide

General
1

Ngspice Ultimate Master Command Reference Guide

Domain Classified, Hierarchical, & Universal — Complete & Rigorous Reference with Practical Netlist Examples

  • Author: Md. Anisur Rahman

  • Role: Subject Matter Expert (Electronics Simulation Analyst) at DCAClab Circuit Simulator

  • Compatibility: NGSPICE v40+ Compatible

Overview

This master guide covers all fundamental and advanced ngspice commands classified into four core domains:

  1. Simulation & Analysis

  2. Component Models & Hierarchy

  3. Automation & Interactive Control

  4. Simulator Options & System Directives

DOMAIN 1: SIMULATION & ANALYSIS COMMANDS

.ac — Small-Signal AC Frequency Response Analysis

Calculates the AC frequency response of a linear or linearized circuit over a specified frequency range. Computes magnitude, phase, real, and imaginary components of node voltages and branch currents.

  • Syntax:

    .ac <variation_type> <n_points> <fstart> <fstop>

  • Examples:

    .ac dec 20 10 1MEG
.ac lin 1000 1kHz 10kHz

  • Parameters:

    • dec: Logarithmic sweep per decade (20 points per decade from 10 Hz to 1 MHz).

    • lin / oct: Linear sweep or octave sweep (points per octave).

  • Applications: Bode plot generation, filter cutoff frequency, amplifier bandwidth, resonant frequency response.

.dc — Direct Current (DC) Sweep Analysis

Sweeps independent DC voltage or current sources (or temperature/parameters) to determine the static DC transfer characteristics of a circuit.

  • Syntax:

    .dc <srcname> <vstart> <vstop> <vstep> [<src2> <vstart2> <vstop2> <vstep2>]

  • Examples:

    .dc VIn 0 5 0.01
.dc VDS 0 5 0.1 VGS 1 3 0.5

  • Parameters:

    • Primary Source (VIn): Sweeps VIn from 0V to 5V in increments of 0.01V.

    • Nested Sweep (VDS / VGS): Generates a family of MOSFET $I$-$V$ curves by sweeping VDS for each step of VGS.

  • Applications: Transistor $I$-$V$ curves, diode forward characteristics, inverter voltage transfer characteristics (VTC).

.tran — Transient Time-Domain Analysis

Computes time-domain response of non-linear circuits subject to time-varying input signals (pulse, sine, piecewise linear).

  • Syntax:

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

  • Examples:

    .tran 0.1n 100n 0 0.5n uic

  • Parameters:

    • tstep (0.1n): Suggested printing step size.

    • tstop (100n): Total simulation stop time.

    • uic (Use Initial Conditions): Bypasses default Operating Point (.op) calculation and uses user-defined node initial conditions (.ic).

  • Applications: Propagation delay, switching transients, oscillator startup, power supply ripple.

.op — DC Operating Point Analysis

Calculates the static DC operating point (bias point) of the circuit with inductors shorted, capacitors opened, and independent AC/transient sources set to zero.

  • Syntax:

    .op

  • Function: Solves non-linear system equations to compute all node voltages, source currents, and semiconductor device bias parameters ($V_{gs}$, $V_{ds}$, $I_c$, $g_m$, $r_\pi$).

  • Applications: Amplifier biasing check, static power dissipation analysis.

.noise — Small-Signal Noise Analysis

Calculates total integrated noise and spectral noise density at an output node generated by circuit components (thermal noise, shot noise, flicker $1/f$ noise).

  • Syntax:

    .noise V(out) <srcname> <pt_type> <pts> <fstart> <fstop> [<summary_interval>]

  • Examples:

    .noise V(out) VIn dec 10 10 1MEG 1

  • Parameters:

    • V(out): Output node where equivalent output noise is calculated.

    • VIn: Input reference source for calculating Equivalent Input Noise.

  • Applications: Low-Noise Amplifier (LNA) design, SNR evaluation, noise figure estimation.

.four — Fourier Distortion Analysis

Performs a Fourier analysis on transient simulation results to calculate fundamental frequency component, harmonic amplitudes, and Total Harmonic Distortion (THD).

  • Syntax:

    .four <fund_freq> <ov_var1> [<ov_var2> ...]

  • Examples:

    .four 1kHz V(out)

  • Parameters:

    • fund_freq (1kHz): Fundamental frequency of the periodic transient waveform.

  • Output: Computes DC component, 1st through 9th harmonics, relative magnitude, phase, and % THD.

  • Applications: Audio power amplifier linearity, harmonic distortion in power electronics.

.sens — DC/AC Small-Signal Sensitivity Analysis

Calculates the sensitivity of an output node voltage or branch current with respect to circuit device parameters (resistances, capacitances, device dimensions).

  • Syntax:

    .sens <outvar> [ac <dec|lin|oct> <pts> <fstart> <fstop>]

  • Examples:

    .sens V(out)
.sens V(out) ac dec 10 100 100kHz

  • DC Sensitivity: Evaluates $\frac{d(V_{out})}{dR_1}$, identifying dominant component tolerances affecting bias points.

  • Applications: Component tolerance optimization, yield analysis, critical component identification.

.tf — Small-Signal Transfer Function Analysis

Computes the DC small-signal transfer function (gain), input impedance, and output impedance of a circuit.

  • Syntax:

    .tf <outvar> <insrc>

  • Examples:

    .tf V(out) VIn

  • Returns: Small-signal voltage gain $\frac{V_{out}}{V_{in}}$, input resistance $R_{in}$ at source VIn, and output resistance $R_{out}$ at node out.

  • Applications: Operational amplifier gain-stage sizing, impedance matching.

.pz — Pole-Zero Analysis

Computes the poles and zeros of the small-signal AC transfer function in the complex $s$-plane ($s = \sigma + j\omega$).

  • Syntax:

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

  • Examples:

    .pz 1 0 2 0 vol pz

  • Nodes: Input nodes (1,0) and output nodes (2,0).

  • vol pz: Voltage transfer function ($\frac{V_{out}}{V_{in}}$); computes both poles and zeros.

  • Applications: Feedback amplifier stability, phase margin optimization, root locus determination.

.disto — Small-Signal Distortion Analysis

Computes small-signal harmonic and intermodulation distortion components under multi-frequency AC excitation.

  • Syntax:

    .disto <variation> <pts> <fstart> <fstop> [<f2overf1>]

  • Examples:

    .disto dec 10 1kHz 1MEG 0.9

  • Output: Analyzes 2nd and 3rd harmonic distortion ($2f_1, 3f_1$) and intermodulation products ($f_1 \pm f_2$).

  • Applications: High-fidelity RF mixing analysis and low-distortion preamplifier design.

.measure / .meas — Automatic Data Extraction Command

Evaluates custom metrics (rise time, peak-to-peak voltage, bandwidth, propagation delay, duty cycle) from simulation output vectors.

  • Syntax Examples:

    .meas tran v_pp PP V(out)
.meas tran t_delay TRIG V(in)=2.5 RISE=1 TARG V(out)=2.5 FALL=1
.meas ac bw WHEN vdb(out)=-3

  • Parameters:

    • v_pp: Calculates peak-to-peak amplitude of V(out).

    • t_delay: Measures time delay between 1st rising edge of V(in) at 2.5V and 1st falling edge of V(out) at 2.5V.

    • bw: Finds frequency where gain drops by -3dB.

DOMAIN 2: COMPONENT MODELS, PARAMETERS & HIERARCHY

.ic — Set Initial Conditions

Sets explicit initial voltage levels for nodes or initial currents for inductors at time $t=0$ for transient analysis.

.ic V(out)=0 V(nodeA)=3.3 L1#branch=1.0m

Forces node out to start at 0V and nodeA to start at 3.3V during .tran with the uic flag.

.nodeset — Specify Initial Node Voltage Guesses

Provides initial voltage hints to aid the Newton-Raphson convergence algorithm for difficult DC operating point calculations.

.nodeset V(bias)=1.2 V(net12)=2.5

Note: Unlike .ic, .nodeset is used as a solver initial guess and releases control once the iterative convergence succeeds.

.param — Parameter Definition & Expressions

Defines global circuit variables and dynamic mathematical expressions evaluated prior to simulation execution.

.param Rin=1k Rf=10k Gain={1 + (Rf/Rin)}
R1 in out {Rin}

Allows dynamic parameter sweeps, parameterized netlist blocks, and expression-based sizing.

.include — External File Inclusion

Imports external SPICE files, model libraries, subcircuits, or netlists into the current simulation context.

.include "./models/opamp.lib"
.include "555_timer.cir"

.lib — Library Inclusion / Definition

Includes specific corner models (e.g., Fast-Fast, Slow-Slow, Typical) from a structured model library file.

.lib "tsmc180nm.lib" TT_CORNER

.subckt / .ends — Subcircuit Block Definition

Defines reusable hierarchical macro-blocks (op-amps, logic gates, sub-modules) with local node scoping.

.subckt INVERTER in out vdd gnd Wn=1u Wp=2u
M1 out in gnd gnd NMOS W={Wn} L=0.18u
M2 out in vdd vdd PMOS W={Wp} L=0.18u
.ends INVERTER

.model — Semiconductor Device Model Definition

Defines physical parameter sets for semiconductor components (Diode, BJT, MOSFET, JFET).

.model NPN_GENERIC NPN (IS=1e-14 BF=100 VAF=100 CJE=2pF)
.model 1N4148 D (IS=2.52n RS=0.568 N=1.752 BV=100 IBV=10u)

DOMAIN 3: AUTOMATION, SCRIPTS & TERMINAL CONTROL

.control / .endc — Interactive Scripting Engine

Encapsulates interactive ngspice scripting commands (loops, conditional logic, dynamic sweeps, custom plotting, parameter tuning).

.control
  run
  let temp_var = 25
  while temp_var <= 100
    set temp = $temp_var
    tran 0.1n 50n
    let temp_var = temp_var + 25
  end
  plot V(out)
.endc

.print & .plot — Legacy Numerical Logging and ASCII Plotting

  • .print: Forces numerical tabular output logging to standard output or file.

  • .plot: Renders legacy interactive ASCII character plots directly in terminal windows.

.print tran V(out) I(VIn)
.plot tran V(out) V(in)

.save & .probe — Simulation Data Storage Options

  • .save: Restricts data saving strictly to specified node vectors (drastically reduces RAM usage and output binary file size).

  • .probe: Saves specific voltages and currents for external post-processors (e.g., Rawfile/Nutmeg format).

.save V(out) V(in) @m1[id]
.probe V(1) I(VIn)

.end — Absolute End of Netlist File

Mandatory terminal line required at the absolute end of every SPICE netlist file. Lines following .end are ignored by the parser.

.end

DOMAIN 4: SIMULATOR & SYSTEM OPTIONS

.options — Numerical Solver Tolerance Controls

Configures internal numerical integration, matrix solver options, and error tolerance thresholds.

.options RELTOL=0.001 ABSTOL=1pA VNTOL=1uV PIVOT=1 GMIN=1e-12 METHOD=gear


.title High-Speed Differential Amplifier AC/Transient Master Deck

MASTER EXAMPLE: COMPLETE COMPREHENSIVE NETLIST

The following standalone netlist combines subcircuit hierarchy, component modeling, parameter pass-through, transient, AC, Fourier, and automated data measurement:

.title Master Complete SPICE Reference Circuit Demo

* Include Models (if external)
*.include models.inc

* Parameters
.param VDD_VAL=5.0 R_LOAD=2k

* Power Supply and Input Signal
VDD vdd 0 DC {VDD_VAL}
VIn in 0 DC 0 AC 1 SIN(0 0.1 1kHz)

* Subcircuit Block Call
X1 in out vdd 0 GainBlock Rload={R_LOAD}

* Subcircuit Definition
.subckt GainBlock input output vcc gnd Rload=1k
  C1 input bias 10u
  R1 vcc bias 100k
  R2 bias gnd 22k
  Q1 collector bias emitter NPN_MODEL
  RC vcc collector 4.7k
  RE emitter gnd 1k
  CE emitter gnd 100u
  C2 collector output 10u
  RL output gnd {Rload}
.ends GainBlock

* Component Model
.model NPN_MODEL NPN (IS=1e-14 BF=150 VAF=100)

* Initial Condition and Node Guess
.nodeset V(X1.bias)=0.9
.ic V(out)=0

* Simulation Commands
.op
.tran 10u 5m
.ac dec 20 10 1MEG
.four 1kHz V(out)

* Automated Measurement Commands
.meas tran vpeak MAX V(out)
.meas ac max_gain MAX vdb(out)

* Control Script Block
.control
  run
  plot V(in) V(out)
  plot vdb(out)
.endc

.end

Smart Master Ngspice Command Guide PDF