In operating range analysis, a suitably configured source file containing a circuit description is evaluated over a two dimensional area of parameter space, producing an output file describing a true/false result at each evaluated point. The algorithm and implementation are designed to be as efficient as possible to speed execution. Results can be viewed graphically during or after simulation.
As with conventional circuit and command files, operating range analysis files can be sourced by simply typing in the file name. If the file name happens to conflict with a WRspice command, then the file can be input with the source command by typing
source filenameIn batch mode, the operating range analysis is performed immediately. Otherwise, actual operating range analysis is performed with the check command (see 4.6.6). In batch mode, the check command is run automatically, if the file has certain properties to be described.
In order to initiate margin analysis with the check command, the current circuit must be from a margin analysis file, or have appropriate bound codeblocks. Every circuit suitable for margin analysis must have a control block which contains a shell routine which will evaluate the circuit variables and establish whether or not the operation is correct. If operation is incorrect, a vector named ``checkFAIL'' must be set to a non-zero value. Alternatively, the script can return the value 1 to indicate trial failure. These control statements can be supplied in the circuit file in a block initiated with a .control line and ending with a .endc line, or through another file added as a codeblock and bound to the ``controls'' of the circuit, through use of the codeblock command.
A second block of statements, the ``header'' or ``exec'' block, is typically required, though it is not an error if none is provided. This block provides initializing statements, and is executed at the start of operating range analysis, or at the start of each trial in Monte Carlo analysis. This block can be provided in the circuit file within an .exec and an .endc line, or can be a bound codeblock, bound to the ``execs'' of the circuit.
Monte Carlo analysis files differ from operating range files only in the header or .exec lines (or header codeblock). During Monte Carlo analysis, the header block is executed before every simulation so that variables can be updated. In operating range analysis variables are initialized by the header block only once, at the start of analysis.
If the circuit has a line with the characters .monte, then Monte Carlo analysis is assumed, and the -m option to the check command is unnecessary. Similarly, a .checkall line will imply the checking of all points in operating range analysis, making the -a option to the check command unnecessary. A line containing the characters .check will indicate (the default) operating range analysis. One of these lines must appear if the file is to be analyzed in batch mode. These lines also suppress the automatic execution of the .exec lines and the .control lines as the file is sourced (the .exec lines are actually executed, but no vectors are saved, to enable correct shell variable expansion). A line containing the string .noexec appearing in the circuit file will have the same effect.
There are a number of vectors with defined names which control operating range and Monte Carlo analysis. In addition, there are relevant shell variables. The vectors created for use in an analysis run are assigned to a plot structure created for the analysis. This plot becomes the current plot after the analysis starts. These vectors are usually set in the header (.exec) block, unless the defaults are used. They can also be set by hand, or under the control of another script, if the current plot is the constants plot, before starting the analysis. The pre-named vectors are as follows:
The name of these vectors can be redefined by setting a shell variable of the same name (``checkN1'' or ``checkN2''). The value of this variable, if a non-numeric string token, is taken as the name of a vector containing the index. If the variable is set to a positive integer, that integer will be taken as the index, and no vector is used.
The shell variables are:
If both of the input vectors checkSTP1 and checkSTP2 are unset or set to zero, the range finder behaves somewhat differently. In this case, if the all-points mode is active, and the file is using an input ``value'' vector rather than shell variables for alterable parameters, then the range of each of these parameters is determined. A masking facility allows some of these inputs to be skipped. If the all-points mode is not set, the range for the two variables is found. The range finder is described in more detail below. The range finder is not used in Monte Carlo analysis, and the checkiterate variable is ignored in that case.
Instead of using shell substitution and the value1/value2 variables to set varying circuit parameters, one can use an internal parameter passing method which is probably more efficient.
The form, given before the analysis,
set value1="%devicelist,paramlist"sets up a direct push into the named parameters of listed devices, avoiding shell expansion and vectors. Note that the list must follow a magic `%' character, which tells the system to use the devlist,paramlist syntax, as used in the sweep command (see 4.6.39.2).
The jjoprng2.cir file in the examples illustrates use of this syntax.
If any of the shell variables value1, value2, or a shell variable named ``value'' are set to a string, then the shell variable or vector named in the string will have the same function as the assigned-to variable. For example, if in the header one has set value1 = C1, then the variable reference $C1 would be used in the file to introduce variations, rather than $value1. Similarly, if we have issued set value = myvec, the vector myvec would contain values to vary (using the pointer vectors checkN1 and checkN2), and a reference would have the form $&myvec[$&checkN1]. Note that the alternate variables are not automatically defined before the circuit is parsed, so that they should be set to some value in the header. The default $value1 and $value2 are predefined to zero.
The ``checkN1'' and ``checkN2'' names can also be set as a shell variable, the value of which if a positive integer will supply the index, or if a string token will redefine the name of the vector which provides the index.
The checkVAL1, checkDEL1, etc. vectors to be used must be defined and properly initialized, either in the deck or directly from the shell, before analysis.
The operating range analysis sets the shell variables value1 and value2 to the variables being varied. In addition, vector variables can be set. This is needed for scripts such as optimization where the parameter to be varied is required to be under program control. If a vector called value is defined, and a vector called checkN1 is defined, and checkN1 >= 0 and checkN1 < the length of value, then value[checkN1] is set to $value1. Similarly, if a vector called value is defined, and a vector called checkN2 is defined, and checkN2 >= 0 and checkN2 < the length of value, then value[checkN2] is set to $value2. Thus, instead of invoking $value1 and $value2 in the SPICE text, one can instead invoke $&value[$&checkN1], $&value[$&checkN2], where we have previously defined the vectors value, checkN1, checkN2. Thus, the file could have a number of parameters set to $&value[0], $&value[1], ... . If checkN1 is set to 2, for example, $&value[2] would be varied as parameter 1. The unreferenced values would be fixed at predefined entries. As mentioned above, the ``value1'', ``value2'', ``value'', ``checkN1'', and ``chackN2'' names can be redefined by assigning the name of a new variable to the shell variable name being reassigned, using the set command.
There are a number of ways to introduce the trial variations into the circuit. Of these, we have explicitly identified shell variable and vector substitution. Below is a review of these methods.
set value1 = foo1 value2 = foo2
The most important example is temperature, using the temp option. To include temperaure as one of the parameters to vary, one could provide, for example
set value1=temp
let vec[10] = 0
let checkN1 = 5 checkN2 = 6
set value = vec
The first line creates a vector named ``vec'' of size sufficient to contain the indices. The iterated values will be placed in vec[5] and vec[6]. The circuit should reference these values, either through shell substitution (e.g., $&vec[5]) or directly as vectors.
Alternatively, a variable named ``checkN1'' can be set. If the value of this variable is an integer, that integer will be used as the index. If the variable is a name token, then the index will be supplied by a vector of the given name. The same applies to checkN2. The following example illustrates these alternatives:
let vec[10] = 0
set checkN1 = 5
let foo = 6
set checkN2 = foo
set &vector = value
it is possible to place trial values into vectors during analysis. The form above is equivalent to
let vector = value
Note, however, that the `&' character has special significance to the WRspice shell, so when this form if given on the command line the ampersand should be quoted, e.g., by preceding it with a backslash.
Thus, suppose that the circuit depends on a vector named delta. One can set up trial substitution using this vector as
set value1 = '&delta'
@devname[param]
where devname is the name of a device or model in the circuit, and param is one of the parameter keywords for the device or model. These keywords can be listed with the show command.
For example, if the circuit contains a MOS device m1 one might have
set value1 = '&@m1[w]'
This will perform the analysis while setting the m1 w (device width) parameter as parameter 1.
The range is constructed by row, where columns represent different values for value1. A second pass fills in concave contours in column order, thus the same pattern should be obtained independently of the parameter ordering. Patterns with islands or reentrancy may not be displayed correctly. The only way to make the algorithm completely foolproof is to check every point, which is achieved by giving the -a option to the check command, or by using .checkall.
During the analysis, a binary search can be employed to determine the actual values of the edges of the operating region. This feature is enabled by setting the shell variable checkiterate to some value between 1 and 10. This is the depth of the binary search used to find the endpoint. A binary search will be performed during conventional operating range analysis only, and is skipped (other than in the exception noted below) if in all-points mode (-a flag or .checkall line given). The search is skipped if there are no pass points in the row or column. The computed values are stored in the opmin1, etc. vectors, where the zeroth element corresponds to the lowest value of the fixed parameter. For example, opmin1[0] is the minimum value of parameter 1 when parameter 2 is value2 - steps2*delta2. Entries of these vectors corresponding to points that were not found are zero.
The value to set for the checkiterate variable is a trade-off between accuracy and execution time. If the boundary is found within the parameter range defined by the input vectors (and as plotted with the mplot command), the error is bounded by delta/2n , where delta is the appropriate checkDEL1 or checkDEL2 value, and n is the checkiterate value. If the extremum is found outside of the given parameter space, the error may be val /2n , where val is the value at the edge of the parameter space nearest the solution.
After an operating range analysis with range finding is complete, two new vectors, range and r_scale, are created from the opmin1, etc. vectors and added to the current plot. These vectors incorporate all of the nonzero entries in such a way that they form a path describing the boundary of the operating region, with range containing Y-data and r_scale containing X-data. This contour can be displayed by plotting the range vector with the plot command.
The algorithm used the evaluate a row is shown below. This is the normal algorithm; if the -a flag is given to the check command, or a .checkall line was found in the file, the points are simply stepped through, and no binary searching is done.
for each value2 value {
start at left
value1 = central1 - delta1 * nsteps1
loop {
analyze
record point
if (pass) break
value1 = value1 + delta1
if (value1 >
central1 + delta1 * nsteps1) break
}
if (pass)
do binary search for lower extremum
start at right
value1 = central1 + delta1 * nsteps1
loop {
analyze
record point
if (pass) break
value1 = value1 - delta1
if (value1 <
central1 - delta1 * nsteps1) break
}
if (pass)
do binary search for upper extremum
}
If both checkSTP1 and checkSTP2 are zero or not defined, the range finder can have an additional operating mode. This mode is made active if the all-points mode is active (-a option or .checkall given), and a vector is being used to supply trial values, rather than shell variables. If a vector named ``value'' is defined, or a vector defined whose name is assigned to the shell variable named ``value'', the range of each of the components can be computed. Note that the vector can have arbitrarily many entries, and each of these ranges can be found. The range finding can be skipped for certain entries by defining a mask vector. This is a vector with the same length as the value vector, and the same name as the value vector but suffixed with ``_mask'' as in value_mask. Each non-zero entry in the mask signifies that the corresponding variable in the value array will not be tested for range. Additionally, any entry in the value vector which is zero will not be tested. If no mask vector is defined, the range will be computed for all nonzero entries. The results are placed, somewhat arbitrarily, in the opmin1 and opmax1 vectors, which will have lengths equal to that of the value vector. Skipped entries will be zero. No range vector will be produced, since it is not relevant in this mode.
If not in all-points mode, the range will be computed for the shell variables. The opmin1, etc. will contain the maximum and minimum values (length 1). The range vector will contain the four points found. Note that the central value must be a pass point in either of these modes, or the range finding is skipped. There is no output file produced when both checkSTP1 and checkSTP2 are zero or undefined.
One can keep track of the progress of the analysis in two ways. WRspice will print the analysis point on the screen, plus indicate whether the circuit failed or passed at the point, if the -v option is given to the check command. Shell echo commands can be used in the executable blocks to provide more information on screen, and echoed output is printed whether or not -v is given. The second method uses the mplot command, which graphically records the pass/fail points. If ``mplot -on'' is given before the analysis, the results are plotted as simulation proceeds.
During operating range analysis, a file named basename.dxx is created in the current directory, where basename is the base name of the input file, and xx is 00-99, set automatically to avoid clobbering existing files. The output file name is stored in the mplot_cur shell variable.
There is a special echof command that allows text to be printed in the output file. The echof command is used exactly as the echo command. If there is no output file open, the command returns with no action. The echof command can be used in either .control or .exec blocks in the input file.