Plots and Vectors

WRspice data are in the form of vectors, which are lists of numbers that may represent, e.g., time, voltage, or any typed or untyped set of values. Vectors of length one are termed ``scalars''. During a simulation, each of the circuit variables, plus a scale vector, are filled with data from the simulation. For example, in transient analysis, the scale vector (named ``time'') will contain the time values where output is generated, and each node and other circuit variables will have a corresponding vector of the same length as the scale, containing the values for the scale points.

For each simulation, the resulting vectors are contained in a ``plot'', which is a container data structure for vectors. The plot is given a name (such as ``tran2''), and appended to a list containing other previously-generated plots. If an input file contains an .exec block in which vectors are created, a special ``exec'' plot will be created to hold these. There is also an internally generated plot named ``constants'' which contains various scalars set to constant values. The constants plot can not be deleted, thus the internal plot list is never empty.

When a plot data file is read into WRspice with the load command, a plot containing vectors is produced, as if an anaylsis had been run. The new plot becomes the current plot.

When a new plot is created by an analysis or with the load command, it becomes the ``current plot''. The current plot represents a context, where the existing vectors can be accessed by their name, and new vectors created, for example with the let command, will (by default) be added to the current plot.

The current plot is usually the last plot produced by an analysis run, or the constants plot if no analyses have been run or rawfiles loaded. The current plot can be changed with the setplot command, or with the Plots panel from the Tools menu. A vector from the current plot or the constants plot can be referenced by name. A vector from any plot can be referenced with the notation

plotname.vecname

where plotname is the name of the plot or an alias, and vecname is the vector name.

The default separation character is a period, however this can be changed by setting the variable plot_catchar. If this variable is set to a string consisting of a single punctuation character, that character becomes the separator. We will continue to use a period in the examples, but be aware that other options exist.

The plotname can also be a numerical index. Plots are saved in the order created, and as listed by the setplot command without arguments, and in the Plots tool. The numerical forms below are equivalent to the Berkeley SPICE3 syntax. These cause trouble in WRspice, however, since they are often misinterpreted as numbers, and typically require double quoting when used as arguments to commands. WRspice has an equivalent set of alias keywords which do not require special treatment.

Below is a list of the special alias keywords and constructs which can be given as the plotname, in addition to the actual name of the plot to reference. Below, N is an unsigned integer.

curplot
This is an alias for the name of the current plot. Use of this keyword may seem redundant, but it has an important use to be explained below.

-N
Use the N'th plot back from the current plot. N must be 1 or larger. For example, ``-1.v(1)'' will reference v(1) in the previous plot. It is likely that this form must be double-quoted to avoid misinterpretation as a number.

prev[N]
This is very similar functionally to the form above, but does not cause parse errors. The square brackets above are not literal, but indicate that the integer is optional. If missing, N=1 is implied. With N=0, the current plot is indicated (equivalent to curplot).

+N
This goes in the reverse direction, indicating a plot later in the list than the current plot. It is likely that this form must be double-quoted to avoid misinterpretation as a number.

next[N]
This is very similar functionally to the form above, but does not cause parse errors. The square brackets above are not literal, but indicate that the integer is optional. If missing, N=1 is implied. With N=0, the current plot is indicated (equivalent to curplot).

N
An integer without + or - indicates an absolute index into the plot list, zero-based. The value 0 will always indicate the ``constants'' plot, which is the first plot created (on program startup). It is likely that this form must be double-quoted to avoid misinterpretation as a number.

plot[N]
This is very similar functionally to the form above, but does not cause parse errors. The square brackets above are not literal, but indicate that the integer is optional. If missing, N=0 is implied, which will specify the constants plot.

When using the plotname.vecname construct, internally the vector and its scale are copied into the current plot as temporary vectors. If you do ``plot -1.v(1)'' (for example) it may be surprising to find that the plot title, etc. are from the current plot, and not the source plot.

When a script is run, the current plot when the script starts is taken as the ``context plot'' which will be used to resolve references to vectors in the script, after searching the current plot (if different). Suppose that we have a script that defines a loop counter vector, then runs a loop that performs an analysis. If we didn't save and search the context plot, the loop counter vector would not be accessible after the analysis is run, since the analysis will set a new current plot.

One should keep this behavior in mind, as it can sometimes cause surprises. For example, consider the script fragment

run
let foo = i(vds)
plot foo

Now suppose that the context plot contains a vector named ``foo''. Instead of creating a new vector in the current plot, the ``foo'' vector in the context plot will be used, probably meaning that the scale in the displayed plot is incorrect.

To enforce the desired behavior, the second line above should be changed to

let curplot.foo = i(vds)

Script authors should be in the habit of using this form when creating vectors, when there is any possibility of a name clash with the context plot.