The check command is used to initiate margin analysis. Margin analysis can consist of either a swept operating range analysis, or a Monte Carlo analysis.
check [-a] [-b] [-c] [-m] [-r] [-f] [-s] [-k] [-h] [-v] [[pstr1] val1 del1 stp1] [[pstr2] val2 del2 stp2] [analysis]See Chapter 5.1 for a full description of operating range and Monte Carlo analysis. The current circuit is evaluated, and must have an associated block of control statements which contain the pass/fail script. A second associated block of executable statements contains initialization commands. These blocks can be provided in the circuit file, or be previously defined codeblocks bound to the circuit. Codeblocks are executable data structures described in 4.5.1. Setting up the file in one of the formats described described in Chapter 5.1 will ensure that these blocks are created and bound transparently, however it is possible to do this by hand.
The option characters can be grouped following a single ``-'', or entered separately.
A paused margin analysis is resumed if the check command is given which does not have the -c option set, and any arguments given in this case are ignored. The resume command will also restart a paused margin analysis.
Ordinarily, during operating range and Monte Carlo analysis, only the current data point is retained. The amount of data retained can be altered with the -f, -s, and -k options. However, if a .measure line appears in the circuit deck, or the iplot runop is active, data will be retained internally so that the .measure or iplot is operational.
If an iplot is active, -f (current trial data retention) is implied. The data will be plotted for each trial in the same iplot, erasing after each trial is complete. If -k is given, all data will be plotted, without erasure. Note that an iplot doubles internal memory requirements.
The command line may include one or two range specifications. In operating range analysis, each specification consists of an optional parameter specification string, followed by three numbers. These numbers will augment or override the checkVAL1, checkDEL1, checkSTP1, checkVAL2, checkDEL2, and checkSTP2 vectors that may be in effect. The numbers are parsed in the order shown, and all are actually optional. A non-numeric token will terminate a block, and missing values must be set from the vectors.
In Monte Carlo analysis, each block can contain only a single number, which will override the checkSTP1 and checkSTP2 values (if any), in that order. These values are used to define how many Monte Carlo trials to perform.
The optional pstr1 and pstr2 strings take the same format and significance as in the sweep command. See the description of that command for a description of the format. If a parameter specifier is given, the specified device parameters will be altered directly, and the variables and vectors normally used to pass values will not be set. This applies only to operating range analysis, and the explicit parameter strings can only be applied from the check command line and not from the file. If the analysis is two dimensional, then both dimensions must have a parameter specification, or neither dimension can have a parameter specification; the two mechanisms can not be mixed.
The analysis to be performed is given, otherwise it is found in the circuit deck. In interactive mode, if no analysis is specified, the user will be prompted for an analysis string.
During operating range analysis, a file is usually created and placed in the current directory for output. This file is named with the base name of the input file, with an extension .dNN, where NN is replaced with 00, 01, etc. -- the first case where the filename is unique. If for some reason the input file name is unknown, the basename ``check'' will be used. Similarly, in Monte Carlo analysis, a file named basename.mNN is generated. In either case, the shell variable mplot_cur is set to the current output file name. These files can be plotted on-screen with the ``mplot [filename]'' command.
The results from operating range/Monte Carlo analysis are hidden away in the resulting plot structure. The plot can be displayed by entering ``mplot vec'' where vec is any vector in the plot.
When a .measure is included in an iterative analysis, data are saved as follows. Before each iteration, the previous result vector and its scale are saved to the end of a ``history'' vector and scale, and are then deleted. The result vector and scale are recreated when the measurement is completed during the iteration. Thus, at the end of the analysis, for a measurement named ``example'', one would have the following vectors:
| example | the result from the final trial |
|---|---|
| example_scale | the measurement interval or point in the last trial |
| example_hist | results from the prior trials |
| example_hist_scale | intervals from the prior trials |
Thus, during each trial, the result vector will have the same properties as in a standard run. It can be used in the .control block of a Monte Carlo or operating range file (recall that $?vector can be used to query existence, and that if there is no checkPNTS vector defined, the .control block is called once at the end of each trial).
In the current circuit, the parameters to be varied are usually included as shell variables $value1 and $value2. These are special hard-coded shell variables which contain the parameter values during simulation. Before the file is sourced (recall that variable substitution occurs during the read-in), these variables can be set with the set command, and the file simulated just as any other circuit. Initially, the variables $value1 and $value2 are set to zero. The value1 and value2 names can be changed to other names, and other mechanisms can be used to supply trial values, as described in Chapter 5.1.
Briefly, operating range analysis works as follows. The analysis range and other parameters are specified by setting certain vectors in the header script, or by hand. The range is evaluated by rows (varying value1) for each column (value2) point. Columns are then reevaluated if the terminating pass point was not previously found. For a row, starting at the left, points are evaluated until a pass point is found. The algorithm skips to the right, and evaluates toward the left until a pass point is found. This minimizes simulation time, however strange operating ranges, such as those that are reentrant or have islands, will not be reproduced correctly. The only fool-proof method is to evaluate every point, which will occur if the -a option is given, or the .checkall line was given in the input file.
The range of evaluation is set with center, step, and number variables. The number is the number of steps to take above and below the center. Thus, if number is 1, the range is over the three points center-step, center, and center+step. One can set ranges for value1 and value2, or alternatively one can set value2, and the algorithm can determine the operating range for value1 at each value2 point. These values represent the parameter variation range in operating range analysis, but serve only to determine the number of trials in Monte Carlo analysis.
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 check command creates a plot structure, which contains all of the special control vectors, plus vectors for each circuit node and branch. This plot becomes the current plot after the analysis starts. The special vectors which have relevance to the operating range analysis are listed below.
The shell variables are:
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). This is equivalent to giving pstr1, pstr2 on the command line.
The jjoprng2.cir file in the examples illustrates use of this syntax.
The checkVAL1, checkDEL1, etc. vectors used must be defined and properly initialized, either in the deck or directly from the shell.
The shell variables value1 and value2 are set to the current variable 1 and variable 2 values. 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 named value exists, as does a vector named checkN1, then the vector entry value[checkN1] is set to $value1 if checkN1 is in the range of value. Similarly, if a vector checkN2 exists, then the vector entry value[checkN2] is set to $value2, if checkN2 is in the range of value. Thus, instead of invoking $value1 and $value2 in the WRspice text, one can instead invoke $&value[$&checkN1], $&value[$&checkN2], where we have previously defined the vectors value, checkN1, checkN2. 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, and the other values would be fixed at predefined entries. The name ``value'' can be redefined by setting a shell variable named ``value'' to the name of another vector.
If any of the shell variables value1, value2, or a shell variable 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 = L1'', then the variable reference $L1 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.
In Monte Carlo analysis, the header block is executed before each simulation. In the header block, shell variables and vectors may be set for each new trial. These variables and vectors can be used in the SPICE text to modify circuit parameters. The names of the variables used, and whether to use vectors or variables, is up to the user (variables are a little more efficient). Monte Carlo analysis does not use predefined names for parameter data. Typically, the gauss function is used to specify a random value for the variables in the header block.
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 was given to the check command. The echo command can be used in the codeblock to provide more information on-screen, which is printed whether or not the -v option was given. The second method uses the mplot command, which graphically records the pass/fail points. In this mode, the relevant arguments to mplot are as follows.
The analysis can search for the actual edge of the operating region for each row and column. These data are stored in vectors named opmin1, opmax1, opmin2, and opmax2 with length equal to the number of points of the fixed variable. For example, opmin1[0] will contain the minimum parameter 1 value when parameter 2 is equal to central2 - delta2*steps2, and opmin1[2*steps2] will contain the minimum parameter 1 value when parameter 2 is central2 + delta2*steps2.
The binary search depth is controlled by a shell variable checkiterate, with possible values of 0-10. If set to 1-10, the search is performed (setting to 0 skips the range finding). Higher values provide more accuracy but take more time. If the search is performed, a vector called range and its scale r_scale are also produced. These contain the Y and X coordinates of the operating range contour, which can be plotted with the command ``plot range''.
A typical approach is to first unset checkiterate, checkSTP1, and checkSTP2. The check command is used to run a single-point analysis, while changing the values of value1 and value2 until a pass point is found. After the pass point is found, checkiterate can be set to a positive value, which will yield the ranges for the two variables. Then, the checkSTP1 and other variables can be set to cover this range with desired granularity, and the analysis performed again.
When only one point is checked (checkSTP1 = checkSTP2 = 0), no output file is generated. If checkiterate is nonzero and the -a option is given, and a vector is used to supply trial values, the range of each entry in the vector is determined, and stored in the opmin1 and opmax1 vectors. A mask vector can be defined, with the same length as the value vector and same name with the suffix ``_mask''. Value entries corresponding to nonzero entries of this vector do not have the range computed. If the -a flag is not given, the range is found in the usual way. The central value must pass, or the range will not be computed.
See Chapter 5.1 for more information on performing operating range and Monte Carlo analysis, and the suggested file formats.