Introduction to Interactive Simulation

WRspice is an interactive circuit simulation program. One can find details about preparing WRspice input files in Chapter 2.1 -- this section assumes some familiarity with this syntax, which is basically that of SPICE2. This section is intended to be a quick introduction to the use of WRspice, and its capabilities. The remaining chapters provide details and in-depth explanations of the various modes, functions, and features.

If Xic is being run, circuits can be entered graphically, making the command line interface described here somewhat unnecessary (there are users, however, who prefer the command line interface). However, in order to use the full spectrum of capabilities, the command line interface is required.

To start WRspice, one can type

wrspice input_file

where input_file is the name of the WRspice circuit description file to run. Alternately, one can simply type

wrspice

in which case WRspice will start up without loading a circuit. A new circuit description file can be loaded into WRspice by typing the command

source input_file

If the name input_file is different from any internal or external WRspice commands, the source command can be eliminated, and the WRspice input file is loaded simply by typing the file name at the command prompt. The file is parsed into an internal circuit representation, which is held in memory until explicitly deleted. The list of circuits is shown in the panel brought up by the Circuits button in the Tools menu of the Tool Control window. One can switch the ``current circuit'' with the setcirc command.

When WRspice starts, it normally displays a Tool Control window containing command menus. The menu buttons bring up panels which control and display information. Most of the typed commands have analogues within the display panels. These panels can be arranged on the screen, and the configuration saved, so that when WRspice is started subsequently, the user's screen arrangement will be presented.

In addition, WRspice ``takes over'' the text window from which it was launched. The command interface is very much like a shell, and in fact it can be configured to run operating system commands in a manner very similar to the C-shell.

If there are any analysis lines in the input file and the user wishes to run the analyses as given there, one simply enters

run

WRspice will run the requested analyses and will prompt the user again when finished and the output data are available. If the user wishes to perform an analysis that is not specified by a line in the input file, one can type the analysis line just as it would appear in the input file, without the dot. For example, the command

ac lin 20 0.99 1.01

will initiate an ac analysis with 20 frequency values between 0.99 and 1.01.

After the analysis is complete and the WRspice prompt is displayed, the values of the nodes are available. Similarly, one can load the results from previous WRspice sessions using the load command. In either case, to plot the voltage on nodes 4 and 5, for example, one could then issue the command

plot v(4) v(5).

To display a list of the circuit variables available for plotting, type display at the command prompt. The output data items displayed are vectors, with a length generally equal to the number of analysis or output points in the simulation.

To plot vectors with the plot package, one types

plot varlist

where varlist is a list of outputs (such as v(3)) or expressions (such as v(3)*time). WRspice will plot a graph of the outputs on the screen. When finished plotting, WRspice will issue a prompt. Under windowing systems such as X, the plot will be drawn in a newly created window somewhere on the screen. This window will remain open until explicitly dismissed by the user, however the execution returns to WRspice immediately, so that any number of plots can be on-screen simultaneously.

One can also specify combinations of outputs and functions of them, as in

plot v(1) + 2 * v(2)

or

plot log(v(1)) sin(cos(v(2))).

Notice that the vector name v(1) is not a function, but rather denotes the voltage at the node named 1. One can use most algebraic functions, including trig functions, log - (base 10), ln - (base e), and functions such as mag, the magnitude of the complex number, phase, the phase, real, the real part, and imag, the imaginary part. These all operate on real or complex values. A complete list of functions and operations available can be found in 3.16. Generally, any command which expects a vector as an argument will accept an expression.

The notation

plot something vs something_else

means to plot something with something_else on the X-axis.

The plot style can be modified through buttons and features found on the plot window. These and other features can have default behavior changed through setting of shell variables. Shell variables are set with the set command from the command line, and any alphanumeric variable can be set to a value or a string. There are a number of such variables that are predefined to affect plotting. These can also be altered graphically from the panel brought up by the Plot Opts button in the Tools menu. The panel brought up by the Variables button in the Tools menu shows a listing of the shell variables currently set.

For example, one can modify the plot command to plot a subset of the data available. The command

set ylimit = "1 2"
plot v(1) v(2)

will plot the two vectors when the values are between 1 and 2, and

set xlimit = "1 2"
plot v(1) v(2)

will plot them when the scale (time or frequency) is between 1 and 2. The variables will remain set until they are unset, using

unset xlimit ylimit

or the corresponding buttons in the Plot Options panel are made inactive.

The command

set xcompress 5
plot v(1) v(2)

plots only every fifth point, and

unset xcompress
set xindices 20 30
plot v(1) v(2)

plots the values between the 20th time point and the 30th. Any of these variables may be used together, and they are also available in the asciiplot command (which produces an ASCII representation for use with text-only printers).

Typing let without arguments is synonymous with the display command. The let command is different from the set command, which sets non-vector shell variables, which may control various aspects of WRspice operation. The let command is used to assign a new vector, for example

let aa = v(1)

will assign a new vector aa with all components equal to v(1). If no arguments are given, a listing of output vectors from the most recent simulation is shown. This listing is also shown in the panel brought up by the Vectors button in the Tools menu.

One can print the values of vectors with the print command:

print time

The command

print all

will print the values of all the data available. Incidentally, one can also use the keyword all with any of the other commands that take vector names, like plot. There are also alias and history mechanisms available (see 3.15 for details), and a shell command, which passes its arguments to the operating system shell, or starts a subshell.

If the user wishes to save the output values in a data file known as a rawfile, one can then type

write filename v(4) v(5)

to put the values of v(4), and v(5) into filename. If the user wishes to save everything, one can type

write filename.

There are also many commands for tracing the analysis -- one can print the values at a node for each time point or cause WRspice to stop whenever a value gets to a certain point. Descriptions of the commands stop, trace, and step can be found in 4.6. A listing of these commands that are currently in force is available in the panel brought up with the Trace button in the Tools menu.

After the user is done with the values obtained from the simulation run, one can change the circuit and re-run the analysis. If it is desired to edit the circuit itself, one can use the command edit -- it will bring up an internal text editor (or a favorite external editor) and allow changes to the circuit in whatever way is necessary, and then when the editor is exited, WRspice can re-load the circuit and be ready to run it again. Under UNIX with X windows, a default internal editor is provided. This editor is also available as the ``xeditor'' command from the UNIX shell. Also, one can give another analysis (ac, dc, tran, ...) command after the first one completes. If the analysis is not finished, i.e. the user typed an interrupt (Ctrl-C), or the run stopped under the stop command, then one must type reset in order to re-run an analysis from the beginning.

Each separate analysis that is performed will create one or more sets of values. Such a set of values is called a plot -- if several analyses have been performed, and the user wishes to switch from the results of one to the results of another, the setplot command will inform the user as to which analysis results are available and let the user choose one. The plots are displayed in the panel brought up by the Plots button in the Tools menu.

To see what other commands are available, skip to Chapter 4, or type Ctrl-D in WRspice. For information about a particular command, type help command, where command is one of those listed by Ctrl-D. This introduction should be enough to get started.

Here is a sample WRspice run:

csh% wrspice
wrspice 10 -> source xtal.in
Circuit: crystal filter

wrspice 11 -> listing

(listing of the circuit is printed)

wrspice 12 -> run
wrspice 15 -> display
Here are the vectors currently active:

Title: crystal filter
Plotname: AC analysis curves.
Date: Thu Sep 26 12:16:34 PDT 1985

     FREQ    : frequency (complex, 20 long) [scale]
     V(4)    : voltage (complex, 20 long)
     V(6)    : voltage (complex, 20 long)
     V(5)    : voltage (complex, 20 long)

(and so on...)

wrspice 16 -> plot v(4)

(plot takes place)

wrspice 17 -> write outfile freq v(4)
wrspice 18 -> ac lin 30 1 2
wrspice 19 -> display
Here are the vectors currently active:

Title: crystal filter
Plotname: AC analysis curves.
Date: Thu Sep 26 12:16:34 PDT 1985

     FREQ    : frequency (complex, 30 long) [scale]
     V(4)    : voltage (complex, 30 long)
     V(6)    : voltage (complex, 30 long)
     V(5)    : voltage (complex, 30 long)

(and so on...)

wrspice 20 -> print v(4) > tempfile

(print to tempfile takes place)

wrspice 21 -> shell lpr tempfile

(a printout is made of the results)

wrspice 22 -> load testh
Title: SPICE 3-C raw output test heading
Name: Transient analysis.
Date: 08/19/84 03:17:11

wrspice 23 -> display
Here are the variables currently active:

Title: SPICE 3-C raw output test heading
Plotname: Transient analysis.
Date: Sun Dec 1 11:18:25 PST 1985

     TIME    : time (real, 152 long) [scale]
     v(1)    : voltage (real, 152 long)
     v(2)    : voltage (real, 152 long)
     v(3)    : voltage (real, 152 long)
     v(4)    : voltage (real, 152 long)
     v(5)    : voltage (real, 152 long)

wrspice 24 -> print v(1)

(prints v(1) values)

wrspice 25 -> plot v(1)

(plot takes place)

wrspice 26 -> let xxx = log(v(1))
wrspice 27 -> plot xxx

(plot takes place)

wrspice 28 -> plot v(1) v(2) v(3) + 1 vs TIME * 2

(plot takes place)

wrspice 30 -> asciiplot v(1) v(2) TIME + 2 > File
wrspice 31 -> shell lpr File

(Pick up ASCII plot ...)

wrspice 33 -> quit
Warning: the following plot hasn't been saved:
crystal filter, AC analysis curves.

Are you sure you want to quit? y

csh%

Note that WRspice will issue a warning if there is work in progress that has not been saved.