This manual is a work in progress. Some to-dos are listed in Chapt. 24.3. More is surely needed. You are invited to report bugs, missing items, wrongly described items, bad English style etc.

The manual is a `work in progress'. It may accompany a specific ngspice release, e.g. ngspice-24 as manual version 24. If its name contains `Version xxplus', it describes the actual code status, found at the date of issue in the Git Source Code Management (SCM) tool. The manual is intended to provide a complete description of the ngspice functionality, its features, commands, or procedures. It is not a book about learning SPICE usage, but the novice user may find some hints how to start using ngspice. Chapter 21.1 gives a short introduction how to set up and simulate a small circuit. Chapter 32 is about compiling and installing ngspice from a tarball or the actual Git source code, which you may find on the ngspice web pages. If you are running a specific Linux distribution, you may check if it provides ngspice as part of the package. Some are listed here.

This document is covered by the Creative Commons Attribution Share-Alike (CC-BY-SA) v4.0..

Chapter 30 is covered by New BSD (chapt. 33.3.2).

Ngspice is an open source software, users can download the source code, compile, and run it. This manual has an entire chapter describing program compilation and available options to help users in building ngspice (see Chapt. 32). The source package already comes with all `safe' options enabled by default, and activating the others can produce unpredictable results and thus is recommended to expert users only. This is the first ngspice manual and I have removed all the historical material that described the differences between ngspice and spice3, since it was of no use for the user and not so useful for the developer who can look for it in the Changelogs of in the revision control system.

I want to acknowledge the work done by Emmanuel Rouat and Arno W. Peters for converting the original spice3f documentation to TeXinfo. Their effort gave ngspice users the only available documentation that described the changes for many years. A good source of ideas for this manual came from the on-line spice3f manual written by Charles D.H. Williams (Spice3f5 User Guide), constantly updated and useful for its many insights.

Due to the wealth of new material and options in ngspice the actual order of chapters has been revised. Several new chapters have been added. The LyX text processor has allowed adding internal cross references. The PDF format has become the standard format for distribution of the manual. Within each new ngspice distribution (starting with ngspice-21) a manual edition is provided reflecting the ngspice status at the time of distribution. At the same time, located at ngspice manuals, the manual is constantly updated. Every new ngspice feature should enter this manual as soon as it has been made available in the Git source code master branch.

If someone helped in the development and has not been inserted in this list then this omission was unintentional. If you feel you should be on this list then please write to <ngspice-devel@lists.sourceforge.net>. Do not be shy, we would like to make a list as complete as possible.

Some introductory remarks on how to use ngspice may be found in Chapt. 21.

The semiconductor diode model can be used for either junction diodes or Schottky barrier diodes. There are two models for JFET: the first (JFET) is based on the model of Shichman and Hodges, the second (JFET2) is based on the Parker-Skellern model. All the original six MOSFET models are implemented: MOS1 is described by a square-law I-V characteristic, MOS2 [1] is an analytical model, while MOS3 [1] is a semi-empirical model; MOS6 [2] is a simple analytic model accurate in the short channel region; MOS9, is a slightly modified Level 3 MOSFET model - not to confuse with Philips level 9; BSIM 1 [3, 4]; BSIM2 [5] are the old BSIM (Berkeley Short-channel IGFET Model) models. MOS2, MOS3, and BSIM include second-order effects such as channel-length modulation, subthreshold conduction, scattering-limited velocity saturation, small-size effects, and charge controlled capacitances. The recent MOS models for submicron devices are the BSIM3 (Berkeley BSIM3 web page) and BSIM4 (Berkeley BSIM4 web page) models. Silicon-on-insulator MOS transistors are described by the SOI models from the BSIMSOI family (Berkeley BSIMSOI web page) and the STAG [18] one. There is partial support for a couple of HFET models and one model for MESA devices.

Temperature, in ngspice, is a property associated to the entire circuit, rather than an analysis option. Circuit temperature has a default (nominal) value of 27°C (300.15 K) that can be changed using the TEMP option in an .option control line (see 15.1.1) or by the .TEMP line (see 2.11), which has precedence over the .option TEMP line. All analyses are, thus, performed at circuit temperature, and if you want to simulate circuit behavior at different temperatures you should prepare a netlist for each temperature.

For details of the BSIM temperature adjustment, see [6] and [7]. Temperature appears explicitly in the exponential terms of the BJT and diode model equations. In addition, saturation currents have a built-in temperature dependence. The temperature dependence of the saturation current in the BJT models is determined by:

The lines described in sections 2.1 to 2.12 are typically used in the core of the input file, outside of a .control section (see 16.4.3). An exception is the .include includefile line (2.6) that may be placed anywhere in the input file. The contents of includefile will be inserted exactly in place of the .include line.

For example, a resistor instance name must begin with the letter R and can contain one or more characters. Hence, R, R1, RSE, ROUT, and R3AC2ZY are valid resistor names. Details of each type of device are supplied in a following section 3. Table 2.1 lists the element types available in ngspice, sorted by their first letter.

Nodes names may be arbitrary character strings and are case insensitive, if ngspice is used in batch mode (16.4.1). If in interactive (16.4.2) or control (16.4.3) mode, node names may either be plain numbers or arbitrary character strings, not starting with a number. The ground node must be named `0' (zero). For compatibility reason gnd is accepted as ground node, and will internally be treated as a global node and be converted to `0'. If this is not feasible, you may switch the conversion off by setting set no_auto_gnd in one of the configuration files spinit or .spiceinit. Each circuit has to have a ground node (gnd or 0)! Note the difference in ngspice where the nodes are treated as character strings and not evaluated as numbers, thus `0' and 00 are distinct nodes in ngspice but not in SPICE2.

POWER AMPLIFIER CIRCUIT
* additional lines following
*...

Test of CAM cell
* additional lines following
*...

******************************
* additional lines following
*...
.TITLE Test of CAM cell
* additional lines following
*...

Test of CAM cell
* additional lines following
*...
*TITLE Test of CAM cell
* additional lines following
*...

.end

* <any comment>

* RF=1K Gain should be 100
* Check open-loop gain and phase margin

<any command> $ <any comment>

RF2=1K $ Gain should be 100
C1=10p $ Check open-loop gain and phase margin
.param n1=1 //new value

.model mname type(pname1=pval1 pname2=pval2 ... )

.model MOD1 npn (bf=50 is=1e-13 vbf=50)

For these more complex device types, each device element line contains the device name, the nodes the device is connected to, and the device model name. In addition, other optional parameters may be specified for some devices: geometric factors and an initial condition (see the following section on Transistors (8 to 11) and Diodes (7) for more details). mname in the above is the model name, and type is one of the following fifteen types:

Parameter values are defined by appending the parameter name followed by an equal sign and the parameter value. Model parameters that are not given a value are assigned the default values given below for each model type. Models are listed in the section on each device along with the description of device element lines. Model parameters and their default values are given in Chapt. 31.

The subcircuit is defined in the input deck by a grouping of element cards delimited by the .subckt and the .ends cards (or the keywords defined by the substart and subend options (see 17.7)); the program then automatically inserts the defined group of elements wherever the subcircuit is referenced. Instances of subcircuits within a larger circuit are defined through the use of an instance card that begins with the letter `X'. A complete example of all three of these cards follows:

* The following is the instance card: 
*
xdiv1 10 7 0 vdivide

* The following are the subcircuit definition cards: 
*
.subckt vdivide 1 2 3 
r1 1 2 10K 
r2 2 3 5K 
.ends

There is no limit on the size or complexity of subcircuits, and subcircuits may contain other subcircuits. An example of subcircuit usage is given in Chapt. 21.6.

.SUBCKT subnam N1 <N2 N3 ...>

.SUBCKT OPAMP 1 2 3 4

A circuit definition is begun with a .SUBCKT line. subnam is the subcircuit name, and N1, N2, ... are the external nodes, which cannot be zero. The group of element lines that immediately follow the .SUBCKT line define the subcircuit. The last line in a subcircuit definition is the .ENDS line (see below). Control lines may not appear within a subcircuit definition; however, subcircuit definitions may contain anything else, including other subcircuit definitions, device models, and subcircuit calls (see below). Note that any device models or subcircuit definitions included as part of a subcircuit definition are strictly local (i.e., such models and definitions are not known outside the subcircuit definition). Also, any element nodes not included on the .SUBCKT line are strictly local, with the exception of 0 (ground) that is always global. If you use parameters, the .SUBCKT line will be extended (see 2.8.3).

.ENDS <SUBNAM>

.ENDS OPAMP

XYYYYYYY N1 <N2 N3 ...> SUBNAM

X1 2 4 17 3 1 MULTI

Subcircuits are used in ngspice by specifying pseudo-elements beginning with the letter X, followed by the circuit nodes to be used in expanding the subcircuit. If you use parameters, the subcircuit call will be modified (see 2.8.3).

.GLOBAL nodename

.GLOBAL gnd vcc

.INCLUDE filename

.INCLUDE /users/spice/common/bsim3-param.mod

.LIB filename libname

.LIB /users/spice/common/mosfets.lib mos1

If the compatibility mode (16.13) is set to 'ps' by set ngbehavior=ps (17.7) in spinit (16.5) or .spiceinit (16.6), then a simplified syntax .LIB filename is available: a warning is issued and filename is simply included as described in Chapt. 2.6.

.param <ident> = <expr>  <ident> = <expr> ...

.param pippo=5
.param po=6 pp=7.8 pap={AGAUSS(pippo, 1, 1.67)}
.param pippp={pippo + pp}
.param p={pp}
.param pop='pp+p'

This line assigns numerical values to identifiers. More than one assignment per line is possible using a separating space. Parameter identifier names must begin with an alphabetic character. The other characters must be either alphabetic, a number, or ! # $ % [ ] _ as special characters. The variables time, temper, and hertz (see 5.1.1) are not valid identifier names. Other restrictions on naming conventions apply as well, see 2.8.6.

.param a = 123 * 3    b = sqrt(9) $ doesn't work, a <= 123 
.param a = '123 * 3'  b = sqrt(9) $ ok.
.param c = a + 123   $ won't work
.param c = 'a + 123' $ ok. 
.param c = a+123     $ ok. 

{ <expr> }

These are allowed in .model lines and in device lines. A SPICE number is a floating point number with an optional scaling suffix, immediately glued to the numeric tokens (see Chapt. 2.8.5). Brace expressions ({..}) cannot be used to parametrize node names or parts of names. All identifiers used within an <expr> must have known values at the time when the line is evaluated, else an error is flagged.

.subckt <identn> node node ...  <ident>=<value> <ident>=<value> ...

.subckt myfilter in out rval=100k cval=100nF

X<name> node node ... <identn> <ident>=<value> <ident>=<value> ...

X1 input output myfilter rval=1k cval=1n

* Param-example 
.param amplitude= 1V
*
.subckt myfilter in out rval=100k  cval=100nF 
Ra in p1   {2*rval} 
Rb p1 out  {2*rval} 
C1 p1 0    {2*cval} 
Ca in p2   {cval} 
Cb p2 out  {cval} 
R1 p2 0    {rval} 
.ends myfilter
*
X1 input output myfilter rval=1k cval=1n 
V1 input 0 AC {amplitude}
.end

<atom> where <atom> is either a spice number or an identifier 
<unary-operator> <atom> 
<function-name> ( <expr> [ , <expr> ...] ) 
<atom> <binary-operator> <expr> 
( <expr> )

* Logical operators

v1or   1 0  {1 || 0}
v1and  2 0  {1 && 0}
v1not  3 0  {! 1}
v1mod  4 0  {5 % 3}
v1div  5 0  {5 \ 3}
v0not  6 0  {! 0}  

.control
op
print allv
.endc

.end

Confusion may arise in ngspice because of its multiple numerical expression features. The .param lines and the brace expressions (see Chapt. 2.9) are evaluated in the front-end, that is, just after the subcircuit expansion. (Technically, the X lines are kept as comments in the expanded circuit so that the actual parameters can be correctly substituted). Therefore, after the netlist expansion and before the internal data setup, all number attributes in the circuit are known constants. However, there are circuit elements in Spice that accept arithmetic expressions not evaluated at this point, but only later during circuit analysis. These are the arbitrary current and voltage sources (B-sources, 5), as well as E- and G-sources and R-, L-, or C-devices. The syntactic difference is that `compile-time' expressions are within braces, but `run-time' expressions have no braces. To make things more complicated, the back-end ngspice scripting language accepts arithmetic/logic expressions that operate only on its own scalar or vector data sets (17.2). Please see Chapt. 2.13.

This keyword defines a function. The syntax of the expression is the same as for a .param (2.8.5).

.func <ident> { <expr> }
.func <ident> = { <expr> }

.func icos(x) {cos(x) - 1}
.func f(x,y) {x*y}
.func foo(a,b) = {a + b}

Create a constant vector (see 17.8.2) from a parameter in plot (17.3) const.

.csparam <ident> = <expr>

.param pippo=5
.param pp=6
.csparam pippp={pippo + pp}
.param p={pp}
.csparam pap='pp+p'

In the example shown, vectors pippp, and pap are added to the constants that already reside in plot const, having length one and real values. These vectors are generated during circuit parsing and thus cannot be changed later (same as with ordinary parameters). They may be used in ngspice scripts and .control sections (see Chapt. 17).

.temp value

.temp 27

This card overrides the circuit temperature given in an .option line (15.1.1).

A simple .IF-.ELSE(IF) block allows condition-controlling of the netlist. boolean expression is any expression according to Chapt. 2.8.5 that evaluates parameters and returns a boolean 1 or 0. The netlist block in between the .if ... .endif statements may contain device instances or .model cards that are selected according to the logic condition.

.if(boolean expression)
...
.elseif(boolean expression)
...
.else
...
.endif

* device instance in IF-ELSE block
.param ok=0 ok2=1

v1 1 0 1
R1 1 0 2

.if (ok && ok2)
R11 1 0 2
.else
R11 1 0 0.5   $ <-- selected
.endif

* .model in IF-ELSE block
.param m0=0 m1=1

M1 1 2 3 4 N1 W=1 L=0.5

.if(m0==1)
.model N1 NMOS level=49 Version=3.1
.elseif(m1==1)
.model N1 NMOS level=49 Version=3.2.4  $ <-- selected
.else
.model N1 NMOS level=49 Version=3.3.0
.endif

Parameters (Chapt. 2.8.1) and functions, either defined within the .param statement or with the .func statement (Chapt. 2.9) are evaluated before any simulation is started, that is during the setup of the input and the circuit. Therefore these statements may not contain any simulation output (voltage or current vectors), because it is simply not yet available. The syntax is described in Chapt. 2.8.5. During the circuit setup all functions are evaluated, all parameters are replaced by their resulting numerical values. Thus it will not be possible to get feedback from a later stage (during or after simulation) to change any of the parameters.

During the simulation, the B source (Chapt. 5) and their associated E and G sources, as well as some devices (R, C, L) may contain expressions. These expressions may contain parameters from above (evaluated immediately upon ngspice start up), numerical data, predefined functions, but also node voltages and branch currents resulting from the simulation. The source or device values are continuously updated during the simulation. Therefore the sources are powerful tools to define non-linear behavior, you may even create new `devices' by yourself. Unfortunately the expression syntax (see Chapt. 5.1) and the predefined functions may deviate from the ones for parameters listed in 2.8.1.

Commands, as described in detail in Chapt. 17.5, may be used interactively, but also as a command script enclosed in .control ... .endc lines. The scripts may contain expressions (see Chapt. 17.2). The expressions may work upon simulation output vectors (of node voltages, branch currents), as well as upon predefined or user defined vectors and variables, and are invoked after the simulation. Parameters from 2.8.1 defined by the .param statement are not allowed in these expressions. However you may define such parameters with .csparam (2.10). Again the expression syntax (see Chapt. 17.2) will deviate from the one for parameters or B sources listed in 2.8.1 and 5.1.

If you want to use parameters from 2.8.1 inside your control script, you may use .csparam (2.10) or apply a trick by defining a voltage source with the parameter as its value, and then have it available as a vector (e.g. after a transient simulation) with a then constant output (the parameter). A feedback from here back into parameters (2.13.1) is never possible. Also you cannot access non-linear sources of the preceding simulation. However you may start a first simulation inside your control script, then evaluate its output using expressions, change some of the element or model parameters with the alter and altermod statements (see Chapt. 17.5.3) and then automatically start a new simulation.

Expressions and scripting are powerful tools within ngspice, and we will enhance the examples given in Chapt. 21 continuously to describe these features.

When it is needed to simulate several devices of the same kind in parallel, use the `m' (parallel multiplier) instance parameter available for the devices listed in Table 3.1. This multiplies the value of the element's matrix stamp with m's value. The netlist below shows how to correctly use the parallel multiplier:

d1 2 0 mydiode m=10
d01 1 0 mydiode
d02 1 0 mydiode
d03 1 0 mydiode
d04 1 0 mydiode
d05 1 0 mydiode
d06 1 0 mydiode
d07 1 0 mydiode
d08 1 0 mydiode
d09 1 0 mydiode
d10 1 0 mydiode
...

When the X line (e.g. x1 a b sub1 m=5) contains the token m=value (as shown) or m=expression, subcircuit invocation is done in a special way. If an instance line of the subcircuit sub1 contains any of the elements shown in table 3.1, then these elements are instantiated with the additional parameter m (in this example having the value 5). If such an element already has an m multiplier parameter, the element m is multiplied with the m derived from the X line. This works recursively, meaning that if a subcircuit contains another subcircuit (a nested X line), then the latter m parameter will be multiplied by the former one, and so on.

.param madd = 6
X1 a b sub1 m=5
.subckt sub1 a1 b1
   Cs1 a1 b1 C=5p m='madd-2'
.ends

.param madd = 4
X1 a b sub1 m=3
.subckt sub1 a1 b1
   X2 a1 b1 sub2 m='madd-2'
.ends
.subckt sub2 a2 b2
   Cs2 a2 b2 3p m=2
.ends

Lload 1 2 1u ind1 dtemp=5 
.MODEL ind1 L tc1=0.001

Instance parameters are listed in each of the following device descriptions. Model parameters sometimes are given below as well, for complex models like the BSIM transistor models, they are available in the model makers documentation. Instance parameters may also be placed in the .model line. Thus they are reckognized by each device instance referring to that model. Their values may be overridden for a specific instance of a device by placing them additionally onto its instance line.

This is implemented for BSIM3 (11.2.10) and BSIM4 (11.2.11) models.

The .NODESET control line (see Chapt. 15.2.1) serves a similar purpose as the OFF option. The .NODESET option is easier to apply and is the preferred means to aid convergence. The second form of initial conditions are specified for use with the transient analysis. These are true `initial conditions' as opposed to the convergence aids above. See the description of the .IC control line (Chapt. 15.2.2) and the .TRAN control line (Chapt. 15.3.9) for a detailed explanation of initial conditions.

RXXXXXXX n+ n- <resistance|r=>value <ac=val> <m=val>
+ <scale=val> <temp=val> <dtemp=val> <tc1=val> <tc2=val>
+ <noisy=0|1>

R1 1 2 100
RC1 12 17 1K
R2 5 7 1K ac=2K
RL 1 4 2K m=2

RE1 1 2 800 newres dtemp=5
.MODEL newres R tc1=0.001

RE2 a b 1.4k tc1=2m tc2=1.4u

RE3 n1 n2 1Meg tce=700m

The temperature coefficients tc1 and tc2 describe a quadratic temperature dependence (see equation 6) of the resistance. If given in the instance line (the R... line) their values will override the tc1 and tc2 of the .model line (3.2.3). Ngspice has an additional temperature model equation 12 parametrized by tce given in model or instance line. If all parameters are given (quadratic and exponential) the exponential temperature model is chosen.

Rmd 134 57 1.5k noisy=0 

RXXXXXXX n+ n- <value> <mname> <l=length> <w=width>
+ <temp=val> <dtemp=val> <m=val> <ac=val> <scale=val>
+ <noisy = 0|1>

RLOAD 2 10 10K
RMOD 3 7 RMODEL L=10u W=1u

This is the more general form of the resistor presented before (3.2.1) and allows the modeling of temperature effects and for the calculation of the actual resistance value from strictly geometric information and the specifications of the process. If value is specified, it overrides the geometric information and defines the resistance. If mname is specified, then the resistance may be calculated from the process information in the model mname and the given length and width. If value is not specified, then mname and length must be specified. If width is not specified, then it is taken from the default width given in the model.

RXXXXXXX n+ n- R = 'expression' <tc1=value> <tc2=value> <noisy=0>
RXXXXXXX n+ n- 'expression' <tc1=value> <tc2=value> <noisy=0>

R1 rr 0 r = 'V(rr) < {Vt} ? {R0} : {2*R0}' tc1=2e-03 tc2=3.3e-06
R2 r2 rr r = {5k + 50*TEMPER}
.param rp1 = 20
R3 no1 no2 r = '5k * rp1' noisy=1

Expression may be an equation or an expression containing node voltages or branch currents (in the form of i(vm)) and any other terms as given for the B source and described in Chapt. 5.1. It may contain parameters (2.8.1) and the special variables time, temper, and hertz (5.1.2). An example file is given below. Small signal noise in the resistor (15.3.4) may be evaluated as white noise, depending on resistance, temperature and tc1, tc2. To enable noise calculation, add the flag noisy=1 to the instance line. As a default the behavioral resistor is noiseless.

Non-linear resistor   
.param R0=1k Vi=1 Vt=0.5
* resistor depending on control voltage V(rr) 
R1 rr 0 r = 'V(rr) < {Vt} ? {R0} : {2*R0}'
* control voltage 
V1 rr 0 PWL(0 0 100u {Vi})
.control 
unset askquit 
tran 100n 100u uic 
plot i(V1) 
.endc   
.end

CXXXXXXX n+ n- <value> <mname> <m=val> <scale=val> <temp=val> 
+ <dtemp=val> <tc1=val> <tc2=val> <ic=init_condition>

CBYP 13 0 1UF
COSC 17 23 10U IC=3V

C1 15 5 cstd
C2 2 7 cstd
.model cstd C cap=3n

CEB 1 2 1u cap1 dtemp=5 
.MODEL cap1 C tc1=0.001

The temperature coefficients tc1 and tc2 describe a quadratic temperature dependence (see equation77) of the capacitance. If given in the instance line (the C... line) their values will override the tc1 and tc2 of the .model line (3.2.7).

CXXXXXXX n+ n- <value> <mname> <l=length> <w=width> <m=val> 
+ <scale=val> <temp=val> <dtemp=val> <ic=init_condition>

CLOAD 2 10 10P
CMOD 3 7 CMODEL L=10u W=1u

This is the more general form of the Capacitor presented in section (3.2.5), and allows for the calculation of the actual capacitance value from strictly geometric information and the specifications of the process. If value is specified, it defines the capacitance and both process and geometrical information are discarded. If value is not specified, the capacitance is calculated from information contained model mname and the given length and width (l, w keywords, respectively).

It is possible to specify mname only, without geometrical dimensions and set the capacitance in the .model line (3.2.5).

CXXXXXXX n+ n- C = 'expression' <tc1=value> <tc2=value>
CXXXXXXX n+ n- 'expression' <tc1=value> <tc2=value>

C1 cc 0 c = 'V(cc) < {Vt} ? {C1} : {Ch}' tc1=-1e-03 tc2=1.3e-05

Expression may be an equation or an expression containing node voltages or branch currents (in the form of i(vm)) and any other terms as given for the B source and described in Chapt. 5.1. It may contain parameters (2.8.1) and the special variables time, temper, and hertz (5.1.2).

Behavioral Capacitor   
.param Cl=5n Ch=1n Vt=1m Il=100n 
.ic v(cc) = 0    v(cc2) = 0 
* capacitor depending on control voltage V(cc)
C1 cc 0 c = 'V(cc) < {Vt} ? {Cl} : {Ch}' 
*C1 cc 0 c ={Ch} 
I1 0 1 {Il}
Exxx  n1-copy n2  n2 cc2  1 
Cxxx  n1-copy n2  1 
Bxxx  cc2 n2  I = '(V(cc2) < {Vt} ? {Cl} : {Ch})' * i(Exxx) 
I2 n2 22 {Il} 
vn2 n2 0 DC 0
* measure charge by integrating current 
aint1 %id(1 cc) 2 time_count 
aint2 %id(22 cc2) 3 time_count
.model time_count int(in_offset=0.0 gain=1.0 
+ out_lower_limit=-1e12 out_upper_limit=1e12 
+ limit_range=1e-9 out_ic=0.0)   
.control 
unset askquit 
tran 100n 100u 
plot v(2) 
plot v(cc) v(cc2) 
.endc   
.end

LYYYYYYY n+ n- <value> <mname> <nt=val> <m=val>
+ <scale=val> <temp=val> <dtemp=val> <tc1=val>
+ <tc2=val> <ic=init_condition>