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 it's 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.