Quickstart Tutorial for Spice 3

by Charles D.H. Williams

Introduction

SPICE is an analog-circuit simulator that is used to calculate and display the circuit behaviour. It was originally developed at the Electronics Research Laboratory of the University of California, Berkeley (1975). The source code was made freely available and has been used as the basis of many commercial simulators, and academic projects.

SPICE is a useful tool, not a magic wand, and its results should always be examined critically; in some cases it may not give results at all, for others the results may be misleading.

This document gives the basic information required to analyse a simple circuit using SPICE-3. It is intended for students learning to use SPICE by working through the PHY2028 SimSheets and gives only brief descriptions of the most commonly used features. Further information about specific features can be found by following the hyperlinks to the complete SPICE-3 User's Manual.

SPICE orignally consisted of two parts: the SPICE calculation engine which was run as a batch job, and an interactive front-end ('Nutmeg') used to extract and display the results. Recent implementations of SPICE have combined these together and, as a result there is more than one way to do some things. The interactive variants of commands will be used throughout this document.

SPICE Source Files

The SPICE-3 source is a text file comprising various types of lines each terminated by a newline character:

1. Title line: the first line of the file will be printed, but otherwise ignored;
2. Element lines: describe the components and how they are connected into a network;
3. Comment lines: start with a '*' and are ignored by SPICE
4. Continuation lines: lines starting with a '+' are continuations of the statement on the preceeding line;
5. Control lines: tell SPICE what type(s) of analysis; to perform on the circuit and how results are to be displayed;
6. Final line: must be '.end'.

SPICE does not like 'invisible' or 'junk' characters in its source file; they often cause baffling error messages. If you are using MacSpice on School of Physics machines the default editor (TextWrangler) has a 'show invisibles' option which displays such characters.

Circuit Elements

Each element in the circuit is specified in the source file by a line that gives 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. 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. 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 name field must begin with a letter (A through Z).

Note: Some versions of SPICE use case sensitive element and node names during analysis, others are case-insensitive. The interactive processor is usually case sensitive and it does not consider, for example, r1 and R1 to be synonyms. One can avoid a lot of confusion by typing source files in lower-case characters.

Number fields may be integers or floating-point numbers. A floating-point number can be followed by an integer exponent or one of the following scale factors:

T = 1012	G = 109	Meg = 106	K = 103	mil = 25.4x10-6
m = 10-3	u = 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.

Don't forget: Spice is not case-sensitive, so both scale-factors 'M' and 'm' mean 'milli-'; use 'MEG' to represent 'mega-'.

Node names can be arbitrary character strings. The 'ground' node must be present and named '0'. 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).

Section 2.1 of the Users' Manual contains more details about the structure and syntax of the SPICE-3 source file. Section 3 lists all the available circuit elements. The most common ones are as follows:

Resistors

General form:

     rxxxxxxx N1 N2 VALUE
     

Examples:

     r1 1 2 100
     rc1 12 17 1K

N1 and N2 are the two element nodes. VALUE is the resistance (in ohms) and may be positive or negative but not zero.

Capacitors

General form:

     cxxxxxxx n+ n- VALUE <ic=incond>

Examples:

     cbyp 13 0 1uF
     cosc 17 23 10u ic=3V

N+ and N- are the positive and negative element nodes, respectively. VALUE is the capacitance in farads.

The (optional) initial condition is the initial (time-zero) value of capacitor voltage (in volts). Note that the initial conditions (if any) apply 'only' if a transient analysis specifies the UIC option.

Independent Current / Voltage Sources

General form:

     vxxxxxxx N+ N- TYPE VALUE
     iyyyyyyy N+ N- TYPE VALUE

Examples:

     vcc 10 0 DC 6
     iin 13 2 AC 1
     vmeas 12 9

N+ and N− are the positive and negative nodes, respectively. Note that voltage sources need not be grounded. Voltage sources, in addition to being used for circuit excitation, are the 'ammeters' for SPICE, that is, zero-valued voltage sources may be inserted into the circuit for the purpose of measuring current. They, of course, have no effect on circuit operation since they represent short-circuits.

Possible TYPEs include DC, AC or TRAN. In the examples, 'vcc' is a 6V DC source connected between ground and node 10, 'iin' is an AC source of magnitude 1A (used during AC analysis), 'vmeas' is useful as an ammeter. Refer to section 3.2 of the Users' Manual for many more examples and types.

Polarity Conventions

Positive current is assumed to flow from the positive node, through the source, to the negative node. A current source of positive value forces current to flow into the N+ node, through the source, and out from the N− node.

Models

The elements that have been described above require only a few parameters to specify their electrical characteristics. The models of semiconductor devices have many parameters. A set of parameters is assigned a unique name and defined in a separate .MODEL line. Thus a semiconductor device is specified by two command lines: an element and model statement.

The syntax for the model statement is:

     .MODEL MODName Type (parameter values)

MODName is the name of the model for the device. The parameter Type specifies the type of device from a list including:

• d: Diode
• npn: bipolar transistor
• pnp: bipolar transistor
• njf: N-channel JFET model
• pjf: P-channel JFET model

For example, if one required 1N4148 diodes for a simulation one might include the line

     .model d1n4148 D (IS=0.1PA, RS=16 CJO=2PF TT=12N BV=100 IBV=0.1PA)

Section 3.4 of the Users' Manual gives more details.

Junction Diodes

General form:

     dxxxxxxx N+ N- MNAME

Example:

     dbridge 2 10 d1n4148

N+ and N- are the positive and negative nodes, respectively. MNAME is the model name.

Bipolar Junction Transistors (BJTs)

General form:

     qxxxxxxx NC NB NE MNAME

Example:

     q23 10 24 13 qmod

NC, NB, and NE are the collector, base, and emitter nodes, respectively. MNAME is the model name.

Junction Field-Effect Transistors (JFETs)

General form:

     jxxxxxxx ND NG NS MNAME

Example:

     j1 7 2 3 jm1

ND, NG, and NS are the drain, gate, and source nodes, respectively. MNAME is the model name

Subcircuits

A subcircuit allows you to define a collection of elements as a subcircuit (e.g. an operational amplifier) and then to use this subcircuit one or times as an element in a larger circuit. A subcircuit is defined by a .SUBCKT control statement as follows:

     .subckt SUBNAM N1 N2 N3 ...
     ELEMENT LINE
          ...
     ELEMENT LINE
     .ends SUBNAM

where SUBNAM is the subcircuit name and N1, N2, N3 are its external nodes. There can be any number of external nodes with aritrary names (but not 0). The node names used inside the subcircuit are strictly local, except for node 0 which is always global. Once defined, a subcircuit is used in a similar way to any other element:

General form:

     xyyyyyyy N1 <N2 N3 ...> SUBNAM

Examples:

     x1 2 4 17 OPAMP

which connects nodes N1, N2, N3 of the subcircuit OPAMP to nodes 2, 4, and 17 respectively in the main circuit. Refer to section 2.4 of the Users' Manual for more information about subcircuits.

Control Lines

Interactive commands (see below) can be included in the source file as follows:

     .control
     FIRST COMMAND
          ...
     LAST COMMAND
     .endc

A brief summary of some the most commonly-used commands is given below. A full list is given in section 5 of the Users' Manual.

How results are stored - Data Structures

SPICE stores the results of each analysis it performs in a data structure called (confusingly) a 'plot' (analogous to a table of results). Each 'plot' contains a set of 'vectors' (analogous to a column of data) which store the numerical results. The interactive interpreter provides a set of functions that operate on vectors. There is a command to destroy unwanted plots, and the special read-only variable 'plots' is a list of the available plots. Refer to section 5.1 of the userguide for more details.

In general, the vector foovec which is contained in the plot barplot must be referred to by using its full name barplot.foovec. However, to save typing the plot explicitly every time, it is possible to set a default 'current plot' by using the setplot command.

Interactive Commands

SPICE has a set of interactive commands can be typed by the user and execute immediately. The command-line interpreter has many facilities, and can be customised and used as a (not very elegant) programming language. Not all commands work on all platforms. Like many not-very-elegant programming languages, it is possible to use the SPICE command interpreter to create and execute very complicated tasks, but it is wise only to use it for things it does easily and well.

Source: Read a Spice3 input file

General form:

     source filespec

Reads the input file filespec which will contain a circuit netlist and/or interactive commands enclosed between the lines .control and .endc. These commands are executed immediately.

Op: Perform an operating point analysis

General form:

     op

Causes SPICE to perform an operating-point analysis to determine the the quiescent state of the circuit with inductors shorted and capacitors opened. The results of this analysis are used to calculate values for the the linearised, small-signal models of nonlinear devices (see Worksheet 7 - Nonlinear Circuits and Devices).

DC: Perform a DC-sweep analysis

During a DC-sweep analysis SPICE steps the value of a specified independent voltage or current source over the user-specified range and performs an operating point analysis at each value. This permits the evaluation of the DC transfer function, and also provides a mechanism for plotting the characteristic curves of devices and models.

General form:

     dc Source-Name Vstart Vstop Vincr [ Source2 Vstart2 Vstop2 Vincr2 ]

Examples:

     dc vin 0.25 5.0 0.25
     dc vin 0 10 .5 vgs 0 5 1
     dc vce 0 10 .25 ib 0 10u 1u

The parameters define the dc transfer-curve source and sweep limits. Source-Name is the name of an independent voltage or current source. Vstart, Vstop, and Vincr are the starting, final, and incrementing values respectively. The first example causes the value of the voltage source vin to be swept from 0.25 volts to 5.0 volts in increments of 0.25 volts. A second source (Source2) may optionally be specified with associated sweep parameters. In this case, the first source is swept over its range for each value of the second source.

AC: Small-Signal AC Analysis

The ac small-signal portion of SPICE computes the ac output variables as a function of frequency. The program first computes the dc operating point of the circuit and determines linearized, small-signal models for all of the nonlinear devices in the circuit. The resultant linear circuit is then analyzed over a user-specified range of frequencies. The desired output of an ac small-signal analysis is usually a transfer function (voltage gain, transimpedance, etc). If the circuit has only one ac input, it is convenient to set that input to unity and zero phase, so that output variables have the same value as the transfer function of the output variable with respect to the input.

General form:

     ac ( DEC | OCT | LIN ) N Fstart Fstop

Examples:

     ac dec 10 1 10K
     ac dec 10 1k 100meg
     ac lin 100 1 100HZ

Use: 'dec' for decade variation, in which case N is the number of points per decade; 'oct' for octave variation, in which case N is the number of points per octave; 'lin' for linear variation, when N is the total number of points. Fstart is the starting frequency, and Fstop is the final frequency.

Tran: Perform a transient analysis

The transient analysis portion of SPICE computes the transient output variables as a function of time over a user-specified time interval. The initial conditions are automatically determined by a dc analysis. All sources which are not time dependent (for example, power supplies) are set to their dc value.

General form:

     tran Tstep Tstop [ Tstart [ Tmax ] ] [ uic ]

Examples:

     tran 1ns 100ns 0ns 2ns
     tran 1ns 1000ns 500ns 10ns
     tran 10ns 1us 0us 20ns uic

Tstep is the printing or plotting increment for line-printer output. For use with the post-processor, Tstep is the suggested computing increment. Tstop is the final time, and Tstart is the initial time. If Tstart is omitted, it is assumed to be zero. The transient analysis always begins at time zero. In the interval <zero, Tstart>, the circuit is analyzed (to reach a steady state), but no outputs are stored. In the interval <Tstart, Tstop>, the circuit is analyzed and outputs are stored. Tmax is the maximum step-size that SPICE uses; try Tmax=(Tstop-Tstart)/50.0 to start with.

The optional keyword 'uic' (use initial conditions) indicates that the user wants interfere with how SPICE solves for the quiescent operating point before beginning the transient analysis (see Users' Manual Section 4.2.2).

Plot: Plot values on the display

General form:

     plot exprs [ylimit ylo yhi] [xlimit xlo xhi] [xlog] [ylog] [loglog]
          [vs xname] [xlabel word] [ylabel word] [title word] [linear]

Plot the given exprs on the screen. The xlimit and ylimit arguments determine the high and low x- and y-limits of the axes, respectively.

The xname argument is an expression to use as the scale on the x-axis. If xlog or ylog are present then the X or Y scale, respectively, is logarithmic (loglog is the same as specifying both). The xlabel and ylabel arguments cause the specified labels to be used for the X and Y axes, respectively. The title argument is used in the place of the plot name at the bottom of the graph. The linear keyword is used to override a default log-scale plot (as in the output for an AC analysis).

Print: Print values

General form:

     print expr ...

Prints the vector described by the expression expr. If the expression is all, all of the vectors available are printed. Thus the command 'print col all > myfile' prints everything into the file 'myfile' (in SPICE2 format). The scale vector (time, frequency, etc) is printed in the first column.

Quit: Leave Spice3 or Nutmeg

General form:

     quit

Quits the SPICE application.