Lessons In Electric Circuits -- Volume V Chapter 7 (Part 1)

USING THE SPICE CIRCUIT SIMULATION PROGRAM

 Lessons In Electric Circuits -- Volume V Chapter 7 (Part 2)

Lessons In Electric Circuits -- Volume V Chapter 7 (Part 3)

Introduction

"With Electronics Workbench, you can create circuit schematics that look just the same as those you're already familiar with on paper -- plus you can flip the power switch so the schematic behaves like a real circuit. With other electronics simulators, you may have to type in SPICE node lists as text files -- an abstract representation of a circuit beyond the capabilities of all but advanced electronics engineers."
(Electronics Workbench User's guide -- version 4, page 7)

This introduction comes from the operating manual for a circuit simulation program called Electronics Workbench. Using a graphic interface, it allows the user to draw a circuit schematic and then have the computer analyze that circuit, displaying the results in graphic form. It is a very valuable analysis tool, but it has its shortcomings. For one, it and other graphic programs like it tend to be unreliable when analyzing complex circuits, as the translation from picture to computer code is not quite the exact science we would want it to be (yet). Secondly, due to its graphics requirements, it tends to need a significant amount of computational "horsepower" to run, and a computer operating system that supports graphics. Thirdly, these graphic programs can be costly.
However, underneath the graphics skin of Electronics Workbench lies a robust (and free!) program called SPICE, which analyzes a circuit based on a text-file description of the circuit's components and connections. What the user pays for with Electronics Workbench and other graphic circuit analysis programs is the convenient "point and click" interface, while SPICE does the actual mathematical analysis.
By itself, SPICE does not require a graphic interface and demands little in system resources. It is also very reliable. The makers of Electronic Workbench would like you to think that using SPICE in its native text mode is a task suited for rocket scientists, but I'm writing this to prove them wrong. SPICE is fairly easy to use for simple circuits, and its non-graphic interface actually lends itself toward the analysis of circuits that can be difficult to draw. I think it was the programming expert Donald Knuth who quipped, "What you see is all you get" when it comes to computer applications. Graphics may look more attractive, but abstracted interfaces (text) are actually more efficient.
This document is not intended to be an exhaustive tutorial on how to use SPICE. I'm merely trying to show the interested user how to apply it to the analysis of simple circuits, as an alternative to proprietary ($$$) and buggy programs. Once you learn the basics, there are other tutorials better suited to take you further. Using SPICE -- a program originally intended to develop integrated circuits -- to analyze some of the really simple circuits showcased here may seem a bit like cutting butter with a chain saw, but it works!
All options and examples have been tested on SPICE version 2g6 on both MS-DOS and Linux operating systems. As far as I know, I'm not using features specific to version 2g6, so these simple functions should work on most versions of SPICE.

History of SPICE

SPICE is a computer program designed to simulate analog electronic circuits. It original intent was for the development of integrated circuits, from which it derived its name: Simulation Program with Integrated Circuit Emphasis.
The origin of SPICE traces back to another circuit simulation program called CANCER. Developed by professor Ronald Rohrer of U.C. Berkeley along with some of his students in the late 1960's, CANCER continued to be improved through the early 1970's. When Rohrer left Berkeley, CANCER was re-written and re-named to SPICE, released as version 1 to the public domain in May of 1972. Version 2 of SPICE was released in 1975 (version 2g6 -- the version used in this book -- is a minor revision of this 1975 release). Instrumental in the decision to release SPICE as a public-domain computer program was professor Donald Pederson of Berkeley, who believed that all significant technical progress happens when information is freely shared. I for one thank him for his vision.
A major improvement came about in March of 1985 with version 3 of SPICE (also released under public domain). Written in the C language rather than FORTRAN, version 3 incorporated additional transistor types (the MESFET, for example), and switch elements. Version 3 also allowed the use of alphabetical node labels rather than only numbers. Instructions written for version 2 of SPICE should still run in version 3, though.
Despite the additional power of version 3, I have chosen to use version 2g6 throughout this book because it seems to be the easiest version to acquire and run on different computer systems.

Fundamentals of SPICE programming

Programming a circuit simulation with SPICE is much like programming in any other computer language: you must type the commands as text in a file, save that file to the computer's hard drive, and then process the contents of that file with a program (compiler or interpreter) that understands such commands.
In an interpreted computer language, the computer holds a special program called an interpreter that translates the program you wrote (the so-called source file) into the computer's own language, on the fly, as its being executed:




In a compiled computer language, the program you wrote is translated all at once into the computer's own language by a special program called a compiler. After the program you've written has been "compiled," the resulting executable file needs no further translation to be understood directly by the computer. It can now be "run" on a computer whether or not compiler software has been installed on that computer:

SPICE is an interpreted language. In order for a computer to be able to understand the SPICE instructions you type, it must have the SPICE program (interpreter) installed:

SPICE source files are commonly referred to as "netlists," although they are sometimes known as "decks" with each line in the file being called a "card." Cute, don't you think? Netlists are created by a person like yourself typing instructions line-by-line using a word processor or text editor. Text editors are much preferred over word processors for any type of computer programming, as they produce pure ASCII text with no special embedded codes for text highlighting (like italic or boldface fonts), which are uninterpretable by interpreter and compiler software.
As in general programming, the source file you create for SPICE must follow certain conventions of programming. It is a computer language in itself, albeit a simple one. Having programmed in BASIC and C/C++, and having some experience reading PASCAL and FORTRAN programs, it is my opinion that the language of SPICE is much simpler than any of these. It is about the same complexity as a markup language such as HTML, perhaps less so.
There is a cycle of steps to be followed in using SPICE to analyze a circuit. The cycle starts when you first invoke the text editing program and make your first draft of the netlist. The next step is to run SPICE on that new netlist and see what the results are. If you are a novice user of SPICE, your first attempts at creating a good netlist will be fraught with small errors of syntax. Don't worry -- as every computer programmer knows, proficiency comes with lots of practice. If your trial run produces error messages or results that are obviously incorrect, you need to re-invoke the text editing program and modify the netlist. After modifying the netlist, you need to run SPICE again and check the results. The sequence, then, looks something like this:

• Compose a new netlist with a text editing program. Save that netlist to a file with a name of your choice.
• Run SPICE on that netlist and observe the results.
• If the results contain errors, start up the text editing program again and modify the netlist.
• Run SPICE again and observe the new results.
• If there are still errors in the output of SPICE, re-edit the netlist again with the text editing program. Repeat this cycle of edit/run as many times as necessary until you are getting the desired results.
• Once you've "debugged" your netlist and are getting good results, run SPICE again, only this time redirecting the output to a new file instead of just observing it on the computer screen.
• Start up a text editing program or a word processor program and open the SPICE output file you just created. Modify that file to suit your formatting needs and either save those changes to disk and/or print them out on paper.

To "run" a SPICE "program," you need to type in a command at a terminal prompt interface, such as that found in MS-DOS, UNIX, or the MS-Windows DOS prompt option:

spice < example.cir

The word "spice" invokes the SPICE interpreting program (providing that the SPICE software has been installed on the computer!), the "<" symbol redirects the contents of the source file to the SPICE interpreter, and example.cir is the name of the source file for this circuit example. The file extension ".cir" is not mandatory; I have seen ".inp" (for "input") and just plain ".txt" work well, too. It will even work when the netlist file has no extension. SPICE doesn't care what you name it, so long as it has a name compatible with the filesystem of your computer (for old MS-DOS machines, for example, the filename must be no more than 8 characters in length, with a 3 character extension, and no spaces or other non-alphanumerical characters).
When this command is typed in, SPICE will read the contents of the example.cir file, analyze the circuit specified by that file, and send a text report to the computer terminal's standard output (usually the screen, where you can see it scroll by). A typical SPICE output is several screens worth of information, so you might want to look it over with a slight modification of the command:

spice < example.cir | more

This alternative "pipes" the text output of SPICE to the "more" utility, which allows only one page to be displayed at a time. What this means (in English) is that the text output of SPICE is halted after one screen-full, and waits until the user presses a keyboard key to display the next screen-full of text. If you're just testing your example circuit file and want to check for any errors, this is a good way to do it.

spice < example.cir > example.txt

This second alternative (above) redirects the text output of SPICE to another file, called example.txt, where it can be viewed or printed. This option corresponds to the last step in the development cycle listed earlier. It is recommended by this author that you use this technique of "redirection" to a text file only after you've proven your example circuit netlist to work well, so that you don't waste time invoking a text editor just to see the output during the stages of "debugging."
Once you have a SPICE output stored in a .txt file, you can use a text editor or (better yet!) a word processor to edit the output, deleting any unnecessary banners and messages, even specifying alternative fonts to highlight the headings and/or data for a more polished appearance. Then, of course, you can print the output to paper if you so desire. Being that the direct SPICE output is plain ASCII text, such a file will be universally interpretable on any computer whether SPICE is installed on it or not. Also, the plain text format ensures that the file will be very small compared to the graphic screen-shot files generated by "point-and-click" simulators.
The netlist file format required by SPICE is quite simple. A netlist file is nothing more than a plain ASCII text file containing multiple lines of text, each line describing either a circuit component or special SPICE command. Circuit architecture is specified by assigning numbers to each component's connection points in each line, connections between components designated by common numbers. Examine the following example circuit diagram and its corresponding SPICE file. Please bear in mind that the circuit diagram exists only to make the simulation easier for human beings to understand. SPICE only understands netlists:

Example netlist
v1 1 0 dc 15
r1 1 0 2.2k
r2 1 2 3.3k     
r3 2 0 150
.end

Each line of the source file shown above is explained here:

• v1 represents the battery (voltage source 1), positive terminal numbered 1, negative terminal numbered 0, with a DC voltage output of 15 volts.
• r1 represents resistor R₁ in the diagram, connected between points 1 and 0, with a value of 2.2 kΩ.
• r2 represents resistor R₂ in the diagram, connected between points 1 and 2, with a value of 3.3 kΩ.
• r3 represents resistor R₃ in the diagram, connected between points 2 and 0, with a value of 150 kΩ.

Electrically common points (or "nodes") in a SPICE circuit description share common numbers, much in the same way that wires connecting common points in a large circuit typically share common wire labels.
To simulate this circuit, the user would type those six lines of text on a text editor and save them as a file with a unique name (such as example.cir). Once the netlist is composed and saved to a file, the user then processes that file with one of the command-line statements shown earlier (spice < example.cir), and will receive this text output on their computer's screen:

1*******10/10/99 ******** spice 2g.6 3/15/83 ********07:32:42*****

0example netlist    

0****   input listing                 temperature =   27.000 deg c

 v1 1 0 dc 15    
 r1 1 0 2.2k     
 r2 1 2 3.3k     
 r3 2 0 150      
 .end    

*****10/10/99 *********  spice 2g.6  3/15/83 ******07:32:42******

0example netlist   
0****   small signal bias solution     temperature =   27.000 deg c


  node   voltage     node   voltage

 (  1)   15.0000    (  2)    0.6522


     voltage source currents
     name       current

     v1       -1.117E-02


     total power dissipation   1.67E-01  watts
         
        job concluded
0         total job time            0.02
1*******10/10/99 ********  spice 2g.6  3/15/83 ******07:32:42*****


0****   input listing                 temperature =   27.000 deg c

SPICE begins by printing the time, date, and version used at the top of the output. It then lists the input parameters (the lines of the source file), followed by a display of DC voltage readings from each node (reference number) to ground (always reference number 0). This is followed by a list of current readings through each voltage source (in this case there's only one, v1). Finally, the total power dissipation and computation time in seconds is printed.
All output values provided by SPICE are displayed in scientific notation.
The SPICE output listing shown above is a little verbose for most peoples' taste. For a final presentation, it might be nice to trim all the unnecessary text and leave only what matters. Here is a sample of that same output, redirected to a text file (spice < example.cir > example.txt), then trimmed down judiciously with a text editor for final presentation and printed:

example netlist    
v1 1 0 dc 15    
r1 1 0 2.2k     
r2 1 2 3.3k     
r3 2 0 150      
.end    

node    voltage    node     voltage
(  1)   15.0000    (  2)    0.6522

voltage source currents
name       current
v1       -1.117E-02

total power dissipation   1.67E-01  watts

One of the very nice things about SPICE is that both input and output formats are plain-text, which is the most universal and easy-to-edit electronic format around. Practically any computer will be able to edit and display this format, even if the SPICE program itself is not resident on that computer. If the user desires, he or she is free to use the advanced capabilities of word processing programs to make the output look fancier. Comments can even be inserted between lines of the output for further clarity to the reader.

The command-line interface

If you've used DOS or UNIX operating systems before in a command-line shell environment, you may wonder why we have to use the "<" symbol between the word "spice" and the name of the netlist file to be interpreted. Why not just enter the file name as the first argument to the command "spice" as we do when we invoke the text editor? The answer is that SPICE has the option of an interactive mode, whereby each line of the netlist can be interpreted as it is entered through the computer's Standard Input (stdin). If you simple type "spice" at the prompt and press [Enter], SPICE will begin to interpret anything you type in to it (live).
For most applications, its nice to save your netlist work in a separate file and then let SPICE interpret that file when you're ready. This is the way I encourage SPICE to be used, and so this is the way its presented in this lesson. In order to use SPICE this way in a command-line environment, we need to use the "<" redirection symbol to direct the contents of your netlist file to Standard Input (stdin), which SPICE can then process.

Circuit components

Remember that this tutorial is not exhaustive by any means, and that all descriptions for elements in the SPICE language are documented here in condensed form. SPICE is a very capable piece of software with lots of options, and I'm only going to document a few of them.
All components in a SPICE source file are primarily identified by the first letter in each respective line. Characters following the identifying letter are used to distinguish one component of a certain type from another of the same type (r1, r2, r3, rload, rpullup, etc.), and need not follow any particular naming convention, so long as no more than eight characters are used in both the component identifying letter and the distinguishing name.
For example, suppose you were simulating a digital circuit with "pullup" and "pulldown" resistors. The name rpullup would be valid because it is seven characters long. The name rpulldown, however, is nine characters long. This may cause problems when SPICE interprets the netlist.
You can actually get away with component names in excess of eight total characters if there are no other similarly-named components in the source file. SPICE only pays attention to the first eight characters of the first field in each line, so rpulldown is actually interpreted as rpulldow with the "n" at the end being ignored. Therefore, any other resistor having the first eight characters in its first field will be seen by SPICE as the same resistor, defined twice, which will cause an error (i.e. rpulldown1 and rpulldown2 would be interpreted as the same name, rpulldow).
It should also be noted that SPICE ignores character case, so r1 and R1 are interpreted by SPICE as one and the same.
SPICE allows the use of metric prefixes in specifying component values, which is a very handy feature. However, the prefix convention used by SPICE differs somewhat from standard metric symbols, primarily due to the fact that netlists are restricted to standard ASCII characters (ruling out Greek letters such as µ for the prefix "micro") and that SPICE is case-insensitive, so "m" (which is the standard symbol for "milli") and "M" (which is the standard symbol for "Mega") are interpreted identically. Here are a few examples of prefixes used in SPICE netlists:


r1 1 0 2t (Resistor R₁, 2t = 2 Tera-ohms = 2 TΩ)
r2 1 0 4g (Resistor R₂, 4g = 4 Giga-ohms = 4 GΩ)
r3 1 0 47meg (Resistor R₃, 47meg = 47 Mega-ohms = 47 MΩ)
r4 1 0 3.3k (Resistor R₄, 3.3k = 3.3 kilo-ohms = 3.3 kΩ)
r5 1 0 55m (Resistor R₅, 55m = 55 milli-ohms = 55 mΩ)
r6 1 0 10u (Resistor R₆, 10u = 10 micro-ohms 10 µΩ)
r7 1 0 30n (Resistor R₇, 30n = 30 nano-ohms = 30 nΩ)
r8 1 0 5p (Resistor R₈, 5p = 5 pico-ohms = 5 pΩ)
r9 1 0 250f (Resistor R₉, 250f = 250 femto-ohms = 250 fΩ)


Scientific notation is also allowed in specifying component values. For example:


r10 1 0 4.7e3 (Resistor R₁₀, 4.7e3 = 4.7 x 10³ ohms = 4.7 kilo-ohms = 4.7 kΩ)
r11 1 0 1e-12 (Resistor R₁₁, 1e-12 = 1 x 10^-12 ohms = 1 pico-ohm = 1 pΩ)


The unit (ohms, volts, farads, henrys, etc.) is automatically determined by the type of component being specified. SPICE "knows" that all of the above examples are "ohms" because they are all resistors (r1, r2, r3, . . . ). If they were capacitors, the values would be interpreted as "farads," if inductors, then "henrys," etc.

Passive components

CAPACITORS

General form:  c[name] [node1] [node2] [value] ic=[initial voltage]
Example 1:     c1 12 33 10u 
Example 2:     c1 12 33 10u ic=3.5
 

Comments: The "initial condition" (ic=) variable is the capacitor's voltage in units of volts at the start of DC analysis. It is an optional value, with the starting voltage assumed to be zero if unspecified. Starting current values for capacitors are interpreted by SPICE only if the .tran analysis option is invoked (with the "uic" option).

INDUCTORS

General form:  l[name] [node1] [node2] [value] ic=[initial current]
Example 1:     l1 12 33 133m 
Example 2:     l1 12 33 133m ic=12.7m
 

Comments: The "initial condition" (ic=) variable is the inductor's current in units of amps at the start of DC analysis. It is an optional value, with the starting current assumed to be zero if unspecified. Starting current values for inductors are interpreted by SPICE only if the .tran analysis option is invoked.

INDUCTOR COUPLING (transformers)

General form:  k[name] l[name] l[name] [coupling factor]
Example 1:     k1 l1 l2 0.999
 

Comments: SPICE will only allow coupling factor values between 0 and 1 (non-inclusive), with 0 representing no coupling and 1 representing perfect coupling. The order of specifying coupled inductors (l1, l2 or l2, l1) is irrelevant.

RESISTORS

General form:  r[name] [node1] [node2] [value]
Example:       rload 23 15 3.3k
 

Comments: In case you were wondering, there is no declaration of resistor power dissipation rating in SPICE. All components are assumed to be indestructible. If only real life were this forgiving!