Getting Started with MacSpice
幸运飞艇超稳计划群 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 MacSpice or other SPICE-3 compatible simulators. It is the first of a series of tutorial worksheets and gives only brief descriptions of the most commonly used features. Most of the information is applicable to any version of SPICE compatible with Spice 3f4. MacSpice-specific features are indicated by text highlighted with a yellow background幸运飞艇超稳计划群. More detailed information can be found by following the hyperlinks to the complete:
spice originally 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, such as macspice, 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.
1.2 Install and Launch MacSpice
download, install and launch bbedit from here:
幸运飞艇超稳计划群 the free 'demo mode' is all that is needed for use with macspice.
download, install and launch macspice by following the instructions here:
幸运飞艇超稳计划群 the first time you launch macspice it will create a working directory inside your documents folder. by default, macspice will assume that any filename that does not specify an absolute path refers to files in this folder.
use the macspice preferences panel:
- MacSpice > Preferences...
to choose bbedit as the 'external editor'.
1.3 MacSpice Source Files
the macspice source is a text file comprising various types of lines each terminated by a newline character:
- Title line: the first line of the file will be printed, but otherwise ignored;
- Element lines: describe the components and how they are connected into a network;
- Comment lines: start with a '*' and are ignored by MacSpice;
- Continuation lines: lines starting with a '+' are continuations of the statement on the preceding line;
- Control lines: tell MacSpice what type(s) of analysis; to perform on the circuit and how results are to be displayed;
- Final line: must be '.end'.
spice simulators do not like 'invisible' or 'junk' characters in its source file; they often cause baffling error messages. if you are using macspice, the recommended editor (bbedit) has a 'show invisibles' option that displays such characters.
1.4 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,
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
R1 to be synonyms. One can
avoid a lot of confusion by typing source files in lower-case
幸运飞艇超稳计划群 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.4×10−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).
幸运飞艇超稳计划群 for more details about the structure and syntax of source files, refer to the user's guide:
幸运飞艇超稳计划群 the user's guide lists all the available circuit elements:
some of the more common ones are as follows.
RXXXXXXX N1 N2 VALUE
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.
CXXXXXXX N+ N− VALUE [IC=INCOND]
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, when specified, do not behave in an intuitively obvious manner. they apply only if the uic option is specified for a transient analysis.
Independent Current / Voltage SourcesGeneral form:
vxxxxxxx N+ N- TYPE VALUE iyyyyyyy N+ N- TYPE VALUE
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 MacSpice, 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 and PULSE. 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 User's Guide for many more examples and types.
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.
幸运飞艇超稳计划群 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 User's Guide gives more details.
Junction DiodesGeneral form:
dxxxxxxx N+ N- MNAME
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:
QXXXXXXXX NC NB NE MNAME
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:
JXXXXXXXX ND NG NS MNAME
J1 7 2 3 JM1
ND, NG, and NS are the drain, gate, and source nodes, respectively. MNAME is the model name
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 arbitrary 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:
XYYYYYYYY N1 <N2 N3 ...> SUBNAMExamples:
X1 2 4 17 OPAMP
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 User's Guide for more information about subcircuits.
幸运飞艇超稳计划群interactive commands (see below) can be included in the source file as follows:
.control FIRST COMMAND ... LAST COMMAND .endc
1.5 How Results are Stored
MacSpice 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 User's Guide for more details.
In general, the vector
foovec which is contained in the plot
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.
1.6 Interactive Commands
MacSpice 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 m2wx85.cnmand interpreter to create and execute very complicated tasks, but it is wise幸运飞艇超稳计划群 only to use it for things it does easily and well.
A brief summary of some the most commonly-used commands is given below. A full list is given in section 5幸运飞艇超稳计划群 of the User's Guide.
Source: Read a Spice3 input fileGeneral form:
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 analysisGeneral form:
causes macspice 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.
DC: Perform a DC-sweep analysis
during a dc-sweep analysis macspice 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 m2wx85.cnputes the ac output variables as a function of frequency. the program first computes the dc operating point of the circuit and determines linearised, small-signal models for all of the nonlinear devices in the circuit. the resultant linear circuit is then analysed 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 FstopExamples:
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 m2wx85.cnputes 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 analysed (to reach a steady state), but no outputs are stored. In the interval <Tstart, Tstop>, the circuit is analysed and outputs are stored. Tmax is the maximum step-size that MacSpice 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 MacSpice solves for the quiescent operating point before beginning the transient analysis (see User's Guide Section 4.2.2).
Plot: Plot values on the displayGeneral 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 valuesGeneral 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 MacSpiceGeneral form:
quits the macspice application.