Circuit description

General structure and conventions

The circuit to be analyzed is described to SPICE by a set of element lines, which define the circuit topology and element values, and a set of control lines, which define the model parameters and the run controls. The first line in the input file must be the title, and the last line must be ".END". The order of the remaining lines is arbitrary (except, of course, that continuation lines must immediately follow the line being continued).

Each element in the circuit is specified by an element line that contains the element name, the circuit nodes to which the element is connected, and the values of the parameters that determine the electrical characteristics of the element. The first letter of the element name specifies the element type. The format for the SPICE element types is given in what follows. For example, a resistor 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. Some examples of element lines are:

R1 1 0 10k
C2 4 5 1.0uF
L3 2 3 10mH
V1 1 0 DC 5

The first line is a 10 kΩ resistor named R1 connected between node 1 and node 0; the second is a 1 µF capacitor named C2 connected between nodes 4 and 5. Node 0 is the ground (datum) node and is global: every reference to node 0, including one inside a subcircuit, refers to the same node.

Fields on a line are separated by one or more blanks, a comma, an equal ('=') sign, or a left or right parenthesis; extra spaces are ignored. A line may be continued by entering a '+' (plus) in column 1 of the following line; SPICE continues reading beginning with column 2.

A name field must begin with a letter (A through Z) and cannot contain any delimiters.

A number field may be an integer field (12, -44), a floating point field (3.14159), either an integer or floating point number followed by an integer exponent (1e-14, 2.65e3), or either an integer or a floating point number followed by one of the following scale factors:

suffix	factor
T	10¹²
G	10⁹
Meg	10⁶
K	10³
mil	25.4 × 10^-6
M or m	10^-3
u (or µ)	10^-6
n	10^-9
p	10^-12
f	10^-15

Letters immediately following a number that are not scale factors are ignored, and letters immediately following a scale factor are ignored. Hence, 10, 10V, 10Volts, and 10Hz all represent the same number, and M, MA, MSec, and MMhos all represent the same scale factor. Note that 1000, 1000.0, 1000Hz, 1e3, 1.0e3, 1KHz, and 1K all represent the same number.

Nodes names may be arbitrary character strings. The datum (ground) node must be named '0'. Note the difference in SPICE3 where the nodes are treated as character strings and not evaluated as numbers, thus '0' and '00' are distinct nodes in SPICE3 but not in SPICE2. The circuit cannot contain a loop of voltage sources and/or inductors and cannot contain a cut-set of current sources and/or capacitors. Each node in the circuit must have a dc path to ground. Every node must have at least two connections except for transmission line nodes (to permit unterminated transmission lines) and MOSFET substrate nodes (which have two internal connections anyway).

Title line, comment lines and .END line

Title Line

Examples

POWER AMPLIFIER CIRCUIT
TEST OF CAM CELL

The title line must be the first in the input file. Its contents are printed verbatim as the heading for each section of output.

.END Line

Examples

.END

The "End" line must always be the last in the input file. Note that the period is an integral part of the name.

Comments

General form

* <any comment>

Examples

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

The asterisk in the first column indicates that this line is a comment line. Comment lines may be placed anywhere in the circuit description. Note that SPICE3 also considers any line with leading white space to be a comment.

Device models

General form

.MODEL MNAME TYPE(PNAME1=PVAL1 PNAME2=PVAL2 ... )

Examples

.MODEL MOD1 NPN (BF=50 IS=1E-13 VBF=50)

Most simple circuit elements typically require only a few parameter values. However, some devices (semiconductor devices in particular) that are included in SPICE require many parameter values. Often, many devices in a circuit are defined by the same set of device model parameters. For these reasons, a set of device model parameters is defined on a separate .MODEL line and assigned a unique model name. The device element lines in SPICE then refer to the model name.

For these more complex device types, each device element line contains the device name, the nodes to which the device is connected, 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 and Diodes for more details).

MNAME in the above is the model name, and type is one of the following fifteen types:

R      Semiconductor resistor model
C      Semiconductor capacitor model
SW     Voltage controlled switch
CSW    Current controlled switch
URC    Uniform distributed RC model
LTRA   Lossy transmission line model
D      Diode model
NPN    NPN BJT model
PNP    PNP BJT model
NJF    N-channel JFET model
PJF    P-channel JFET model
NMOS   N-channel MOSFET model
PMOS   P-channel MOSFET model
NMF    N-channel MESFET model
PMF    P-channel MESFET model

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, model parameters, and default values are listed in the next section along with the description of device element lines.

Subcircuits

A subcircuit that consists of SPICE elements can be defined and referenced in a fashion similar to device models. The subcircuit is defined in the input file by a grouping of element lines; the program then automatically inserts the group of elements wherever the subcircuit is referenced. 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 Appendix A.

.GLOBAL

.GLOBAL node [node ...]

Nodes named on a .GLOBAL line are the same node everywhere, including inside subcircuits, instead of being local to each subcircuit call. This is typically used for supplies:

.GLOBAL vdd! gnd!
.SUBCKT nand2 A B Z
M3 vdd! B Z vdd! pch w=3.2u l=0.13u
M2 vdd! A Z vdd! pch w=3.2u l=0.13u
M1 Z A n0 gnd! nch w=1.6u l=0.13u
M0 n0 B gnd! gnd! nch w=1.6u l=0.13u
.ENDS
VGND gnd! 0 DC 0
VVDD vdd! 0 DC 1.2

.SUBCKT Line

General form

.SUBCKT subnam N1 <N2 N3 ...> <PARAM=DEFAULT ...>

Examples

.SUBCKT OPAMP 1 2 3 4
.SUBCKT nand2 A B Z wp=1.6u wn=0.8u lp=0.13u ln=0.13u

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 which 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) which is always global.

A subcircuit may have parameters, given as name=default after the nodes; a default value must be given for each. The parameter values are set in each subcircuit call. Inside the subcircuit a parameter can be used in a quoted expression, as the value of any keyword=value field of an element or model, such as w=wp on a MOSFET, and as the value of a resistor, capacitor or inductor:

.SUBCKT div a b r1=1k r2=1k
ra a b r1
rb b 0 r='r2*2'
.ENDS

A subcircuit may also contain .param cards. As in HSPICE, they are the subcircuit's own: they are evaluated for each call, with that call's parameters, in whatever order they use each other, and may use the global parameters. See subcircuit parameters.

.ENDS Line

General form

.ENDS <SUBNAM>

Examples

.ENDS OPAMP

The "Ends" line must be the last one for any subcircuit definition. The subcircuit name, if included, indicates which subcircuit definition is being terminated; if omitted, all subcircuits being defined are terminated. The name is needed only when nested subcircuit definitions are being made.

Subcircuit Calls

General form

XYYYYYYY N1 <N2 N3 ...> SUBNAM <PARAM=VALUE ...>

Examples

X1 2 4 17 3 1 MULTI
X12 n2 QB Q nand2 wp=3.2u wn=1.6u
X2 1 2 div r2=3k

Subcircuits are used in SPICE by specifying pseudo-elements beginning with the letter X, followed by the circuit nodes to be used in expanding the subcircuit.

For a subcircuit with parameters, name=value pairs after the subcircuit name set them for this call; parameters not given take the defaults from the .SUBCKT line. A value may be a number, a global parameter's name, or a quoted expression. With the div subcircuit above, X2 1 2 div r2=3k makes a divider of 1kΩ and 6kΩ.

Foundry model libraries often wrap their devices in subcircuits, with the device models local to them: the TSMC RF MOSFETs, for example, are called as X1 d g s b nmos_rf lr=40n wr=600n nr=1, not as MOSFETs of model nch_rf.

Combining files: .INCLUDE lines

General form

.INCLUDE filename
.LIB filename section

Examples

.INCLUDE /users/spice/common/wattmeter.cir
.LIB 'c013hv32v.l' TT

Frequently, portions of circuit descriptions will be reused in several input files, particularly with common models and subcircuits. In any spice input file, the ".include" line may be used to copy some other file as if that second file appeared in place of the ".include" line in the original file. There is no restriction on the file name imposed by spice beyond those imposed by the local operating system.

The ".lib" line reads one section of a model library, in the form used by HSPICE and by foundry model files: only the lines between .LIB section and .ENDL section in the file are copied in. Section names are not case sensitive. Foundry libraries usually have one section for each process corner, such as TT, SS and FF; the file's header lists them.

File names may be in quotes, and may start with ~ for the home directory. A file is looked for in the directories of the sourcepath variable and then in the current directory. When a file is named with a directory, that directory is added to sourcepath, so a library whose sections refer to other files by name alone (as foundry libraries often do) finds them.

Parameters and expressions: .PARAM lines

Name values with .param, and use expressions for element and model values.

General form

.param name=value [name=value ...]
.param name='expression' ...
.param name(arg, ...)='expression'

Examples

.param rval=1k fc=1meg
.param cval='1/(2*pi*rval*fc)'
.param bin3(bin,k0,k1,k2)='bin==0 ? k0 : (bin==1 ? k1 : k2)'
r1 in out 'rval'
c1 out 0 'cval'

A .param card defines one or more named values. A value may be a number, with the usual scale factors, or an expression in single quotes. Expressions are those of the interactive interpreter, which include HSPICE's operators and functions such as c ? a : b, ==, **, pwr() and agauss(). They can use other parameters, the built-in constants such as pi, and functions such as sqrt and exp.

As in HSPICE, the cards may be in any order: each parameter is evaluated once those it uses have been, so a parameter may be used before the card that defines it. If a name is defined more than once, the last definition is the one used, also by the parameters that use it. Parameters that use each other in a circle, or names that are never defined, are reported as errors.

They are evaluated as the input file is read, before the rest of the circuit. Each parameter is kept as a vector of the same name among the constants, so it can also be used in interactive commands and expressions after the circuit is loaded:

print rval cval
let x = rval * 2

Because they are evaluated as the file is read, variables that change how they are evaluated, such as hspicelog (natural logarithms, as HSPICE) and montecarlo (random values from agauss() etc.), must be set before the circuit is loaded, for example in spinit or .spiceinit, not in its .control section.

Functions

A name with arguments in parentheses defines a function, as the define command does:

.param sel(x,lo,hi)='x<lo ? 0 : x<hi ? 1 : 2'
.param band='sel(freq, 1k, 1meg)'

Functions are defined before the other parameters are evaluated, so they may be used anywhere. An argument name hides a parameter of the same name.

temper

temper is HSPICE's name for the circuit temperature in °C, and can be used in any expression. It is the temperature the devices are simulated at: the TEMP of a .OPTIONS card if the circuit has one, otherwise 27. A .step temp sets it for each step. It is evaluated when the circuit is loaded, so a set temp in the .control section afterwards changes the devices' temperature but not temper. (A set temp before the circuit is loaded, e.g. in .spiceinit, changes neither.) A .param temper= card replaces it.

Expressions in element and model lines

A value on an element or .model line written in single quotes is evaluated as an expression, and the result used as the value:

r1 in out 'rval'
r2 out 0 '2*rval'
.model dmod d is='1e-14*area_scale'

The result is used at full (15 significant digit) precision, so r1 in 0 'rval' with rval=1.23456789k gives the same resistance, 1234.56789Ω, as r1 in 0 1.23456789k.

The value of a resistor, capacitor or inductor can also be given as r=, c= or l=, and there the name of a parameter may be written without quotes: r1 in out r=rval is the same as r1 in out 'rval'. A name that is not a parameter is reported as an error on that line. Other keyword values, such as a MOSFET's w=, need the quotes: w='wval', except inside a subcircuit (below).

A line of just ) ends the .model card above it, as in HSPICE model libraries.

Subcircuit parameters

Each call of a subcircuit has its own parameters, as in HSPICE: those on its .SUBCKT line, with the values given in the call or the defaults, and the .param cards inside the subcircuit, which may be in any order and use each other and the global parameters:

.subckt rdiv a b rv=1k k=2
.param rbot='rtop/2'
.param rtop='rv*k'
r1 a m r='rtop'
r2 m b rbot
.model dm d (is='1e-14*k')
d1 m b dm
.ends
x1 in 0 rdiv rv=2k k=4

A name that is one of the subcircuit's parameters means that parameter, even if there is a global parameter of the same name; any other name is a global parameter. Inside the subcircuit the parameters can be used in quoted expressions, as the value of any keyword=value field (including a .model's name = value), and as the value of a resistor, capacitor or inductor. Node and model names are not changed. In a B source's expression the global parameters can be used too.

Stepping parameters

A parameter can be stepped with .step param name; for each step the circuit is read again, the parameters that depend on it are evaluated again, and the subcircuits are expanded again, so their parameters follow it too. A .step temp of a circuit that uses temper does the same. See .step. The optimise command varies device and model parameters directly, not .params.

Limitations

Only the first element of a vector-valued expression is used.
Parameters and temper are evaluated when the circuit is loaded (or reread by reset or .step): changing a parameter vector with let, or the temperature with set temp, afterwards does not change the circuit until it is reread.