Accessing Simulation Data

In this topic:

Overview

When a simulation is run, a number of vectors (scalars for dc operating point) are created providing the node voltages and branch currents of the circuit. These are just like variables used in a script and can be accessed in the same way. There are however a number of differences from a normal variable. These are as follows:
  • Simulation vectors are placed in their own group.
  • They are usually attached to a reference vector.
  • They usually have a physical type (e.g. Volts, Amps etc.)
  • Some are aliases. See aliases.
Each of these is described in the following sections.

Groups

All variables are organised into groups. When SIMetrix first starts, there is only one called the Global group and all global variables are placed in it. (See Scope of Variables, Global Variables). When a script executes a new group is created for it and its own - local - variables are placed there. The group is destroyed when the script exits as are its variables.

Each time a simulation run is started a new group is created and the data generated by the analysis is placed in the group. Groups from earlier runs are not immediately destroyed so that results from earlier runs can be retrieved. By default, three simulation groups are kept at any time with the oldest being purged as new ones are created. A particular group can be prevented from being purged by selecting the menu Simulator > Manage Data Groups. Further the number of groups kept can be changed with the GroupPersistence option. See User's Manual/Sundry Topics/Options/UsingtheSetandUnsetcommands/List of Options for details about Options.

Groups provide a means of organising data especially simulation data and makes it possible to keep the results of old simulation runs.

All groups have a name. Simulation group names are related to the analysis being performed. E.g. transient analyses are always trann where n is a number chosen to make the name unique.

Variables within a group may be accessed unambiguously by using their fully qualified name. This is of the form:
groupname:variable_name
E.g. tran1:vout.

The Current Group

At any time a single group is designated the current group. This is usually the group containing the most recent simulation data but may be changed by the user with the Simulator > Manage Data Groups menu or with the SetGroup. If a variable name is used in an expression that is not local (created in a script) or global, the current group is searched for it. So when the command Plot vout is executed if vout is not a local or global variable SIMetrix will look for it in the current group.

You can view the variables in the current group with the Display command. Run a simulation and after it is completed type Display at the command line. A list of available variables from the simulation run will be displayed. Some of them will be aliases. These are explained in the aliases section.

The ':' Prefix

If a variable name is prefixed with a colon it tells SIMetrix to only search the current group for that name. Local or global variables of the same name will be ignored.

The colon prefix also has a side effect which makes it possible to access vectors created from numbered nodes. SPICE2 compatible netlists can only use numbers for their node (=net) names. SIMetrix always creates simulation vectors with the same name as the nets. If the net name is a number, so is the variable name. It was stated earlier that variable names must begin with a non-numeric character but in fact this is only partly true. Variable names that start with a digit or indeed consist of only digits can be used but the means of accessing them is restricted. Prefixing with a ':' is one method. The function Vec can also be used for this purpose.

Multi-division Vectors

Multi-step runs such as Monte Carlo produce multiple vectors representing the same physical quantity. In SIMetrix these multiple vectors are stored as a single entity in what is known as a multi-division vector. This is similar to a two dimensional vector (or array or matrix) except that the rows of the matrix are not necessarily all the same length.

When plotting a multi-division vector, each individual vector - or division - will be displayed as a single curve. If listing or printing a multi-division vector with the Show command, all the divisions will be listed separately.

You can access a single vector (or division) within a multi-division vector using the index operators - '[' and ']'. Suppose VOUT was a multi-division vector with 5 divisions. Each individual vector can be accessed using VOUT[0], VOUT[1], VOUT[2], VOUT[3] and VOUT[4]. Each of these will behave exactly like a normal single division vector. So, you can use the index operator to access single elements e.g. VOUT[2][23] retrieves the single value at index 23 in division 2.

To find the number of divisions in a multi-division vector, use the function NumDivisions.

You can collate values at a given index across all divisions using the syntax: vectorname[][index]. E.g. in the above example VOUT[][23] will return a vector of length 5 containing the values of index 23 for all 5 divisions.

Multi-division vectors may be combined using arithmetic operators provided either both sides of the operator are compatible multi-division vectors - i.e. have identical x-values - or one of the values is a scalar.

Multi-division Vectors

Not all functions accept multi-division vectors for their arguments. The following table lists the functions that do accept multi-division vectors. The entry for each argument specifies whether that argument accepts multi-division vectors and how the data is dealt with.
"X" Multi-division vectors are not accepted for this argument.
"Scalar" The function acts on the multi-division vector to obtain a scalar value.
"Vector" The function obtains a scalar value for each division within the multi-division vector.
"Multi" The function processes all the vector's data to return a multi-division vector
Function name Arg 1 Arg 2 Arg 3 Arg 4
abs Multi
atan Multi
atan_deg Multi
avg Multi
cos Multi
cosh Multi
CyclePeriod Multi Multi
cos_deg Multi
db Multi
DefineFourierDialog X Scalar
diff Multi
Execute X Multi Multi Multi
erf Multi
exp Multi
fft Multi X
FIR Multi X X
Fourier Multi X X X
FourierOptionsDialog X Scalar
FourierWindow Multi X X
gamma Multi
GetVecStepParameter Scalar
GetVecStepVals Scalar
GroupDelay Multi
HasLogSpacing Multi
Histogram Multi X
IIR Multi X X
im Multi
imag Multi
integ Multi
Interp Multi X X X
IsComplex Scalar
IsNum Scalar
IsStr Scalar
length Scalar
ln Multi
log Multi
log10 Multi
mag Multi
magnitude Multi
maxidx Multi
Maxima Multi X X
Maximum Multi X X
mean Multi
Mean1 Multi X X
minidx Multi
Minima Multi X X
Minimum Multi X X
norm Multi
NumDivisions Scalar
NumElems Vector
ph Multi
phase Multi
phase_rad Multi
PhysType Scalar
Range Multi X X
re Multi
real Multi
Ref Multi
RefName Scalar
Rms Multi
RMS1 Multi X X
rnd Multi
RootSumOfSquares Multi X X
sign Multi
sin Multi
sinh Multi
sin_deg Multi
sqrt Multi
SumNoise Multi X X
tan Multi
tanh Multi
tan_deg Multi
Truncate Multi X X
Units Scalar
Val Multi
XFromY Multi X X X
XY Multi Multi
YFromX Multi X X

Vector References

Simulation vectors are usually attached to a reference. The reference is a vector's x-values. E.g. any vector created from a transient analysis simulation will have a reference of time. AC analysis results have a reference of frequency.

Vectors created by other means may be assigned a reference using the SetRef command. Also the XY function may be used to compose a vector containing a reference.

Physical Type

Simulation vectors also usually have a physical type. This identifies the values units e.g. Volts or Amps. When evaluating expressions SIMetrix attempts to resolve the physical type of the result. For example, if a voltage is multiplied by a current SIMetrix will assign the Physical Type Watts to the result.

Any vector can be assigned a physical type using the SetUnits command.