next up previous contents index
Next: The dc Command Up: Simulation Control Commands Previous: The cache Command   Contents   Index

The check Command

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.

If the -a flag is given, operating range analysis is performed at every point (all points mode). Otherwise, the analysis attempts to limit computation by identifying the contour containing the points of operation. This algorithm can be confused by operating ranges with strange shapes, or which possess islands of fail points. If the input file contains a .checkall line, then the -a flag to the check command is redundant, all points will be checked in this case.

If this is given, the analysis will be paused after setup and the check command will return. This is the start for atomic Monte Carlo (see 5.6); a script can call the mctrial command numerous times at this point, then ``check -c'' to clean up and end the analysis.

The -c (clear) option will clear any margin analysis in progress if the analysis has been paused, for example by pressing Ctrl-C, or if in an atomic Monte Carlo script. Return is immediate whether or not there is a present analysis to clear. Unlike in release 4.3.8 and earlier, no new analysis is started, and other options are ignored.

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.

If the -m option is given, Monte Carlo analysis is performed, rather than operating range analysis. This is the default if a .monte line appeared in the file; the -m option is only required if there is no .monte line. The -a option is ignored if -m is given, as is .checkall. Monte Carlo analysis files differ from operating range files only in the header (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 -r (remote) option is given, remote servers will be assigned simulation runs, allowing parallelism to increase analysis speed. The remote servers must have been specified through the rhost command, and each must have a wrspiced server running. More information on remote asynchronous runs can ge found in 4.6.28 and 4.6.29.

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.

The -f option will cause the data for the current trial to be retained. This is implied if any .measure lines are present, or if an iplot is active. The data are overwritten for each new trial. The data for the last trial are available after the analysis is complete, or can be accessed for intermediate trials if the analysis is paused.

The -s option also causes retention of the data for the current trial, but in addition will dump the data to a family of rawfiles, similar to the segment keyword of the .tran line (though this works with other than transient analysis). The default file name is the name of the range analysis output file, suffixed with ``.sNN'', where NN is 00, 01, etc. Each trial generates a new suffix in sequence.

With the -k option, all data are retained, in a multi-dimensional plot. Note that this can be huge, so use of the maxdata variable and .save lines may be necessary. One can see the variations by plotting some or all of the dimensions of the output. Recall forms like v(1)[N] refer to the N+1'th trial, and v(1)[N,M] includes the data for the N+1'th to the M+1'th trials. The mplot command has a facility for displaying trial data in a simplified manner.

Finally, the -h (help) option will simply print a brief summary of the options to the check command.

If -v (verbose) is given, results and other messages are printed on-screen as the analysis is performed, otherwise the analysis is silent, except for any printing statements executed in the associated command scripts. The mplot command can be used to follow progress graphically.

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.

checkPNTS (real, length > = 1)
These are the points of the scale variable (e.g., time in transient analysis) at which the pass/fail test is applied. If a fail is encountered, the simulation is stopped and the next trial started. This vector is usually specified as an array, with the compose command, and is used in operating range and Monte Carlo analysis. If not specified, the evaluation is performed after the trial completes.

checkVAL1 (real, length 1)
This is the initial central value of the first parameter to be varied during operating range analysis. It is not used in Monte Carlo analysis.

checkDEL1 (real, length 1)
The first central value will be incremented or decremented by this value between trials in operating range analysis. It is not used in Monte carlo analysis.

checkSTP1 (integer, length 1)
This is the number of trials above and below the central value. In Monte Carlo analysis, it partially specifies the number of simulation runs to perform, and specifies one coordinate of the visual array used to monitor progress (with the mplot command). In operating range analysis, the default is zero. In Monte Carlo analysis, the default is 3.

checkVAL2, checkDEL2, checkSTP2
These are as above, but relate to the second parameter to be varied in the circuit in operating range analysis. In Monte Carlo analysis, only checkSTP2 is used, in a manner analogous to checkSTP1. The total number of simulations in Monte Carlo analysis is (2*checkSTP1 + 1)*(2*checkSTP2 + 1), the same as would be checked in operating range analysis.

checkFAIL (integer, length 1, value 0 or 1)
This is the global pass/fail flag, which is set after each trial, 1 indicates failure. This variable is used in both operating range and Monte Carlo analysis.

checkINIT (integer, length 1, value 0 or 1)
This is set to 1 by WRspice before the initial execution of the header block, before operating range or the first Monte Carlo trial. It is set to 0 otherwise. Thus one can identify the first trial in Monte Carlo analysis from within the header script.

opmin1, opmax1, opmin2, opmax2 (real, length > = 1)
The operating range analysis can be directed to find the operating range extrema of the one parameter for each value of the other parameter. These vectors contain the values found. They are not used in Monte Carlo analysis.

value (real, length variable)
This vector can be used to pass trial values to the circuit, otherwise shell variables are used. This pertains to operating range and Monte Carlo analysis.

checkN1, checkN2 (integer, length 1)
These are the indices into the value array of the two parameters being varied in operating range analysis. The other entries are fixed. These vectors are not used if shell variables pass the trial values to the circuit, and are not used in Monte Carlo analysis.

The shell variables are:

checkiterate (0-10)
This is the binary search depth used in finding operating range extrema. This is not used in Monte Carlo analysis.

value1, value2
These variables are set to the current trial values to be used in the circuit (parameters 1 and 2). The WRspice deck should reference these variables (as $value1 and $value2) as the parameters to vary. Alternatively, the value array can be used for this purpose. These variables can be used in Monte Carlo analysis. Additionally, these variables, and a variable named ``value'' can be set to a string. When done, the variable or vector named by the string will take on the functionality of the assigned-to variable. For example, if set value1 = L1 is given, the variable L1 is used to pass trial parameter 1 values to the circuit (references are $L1).

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 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.

mplot -on
This will cause subsequent operating range analysis results to be plotted while the analysis is running.

mplot -off
This will return to the default (no graphical output while simulating).

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.

next up previous contents index
Next: The dc Command Up: Simulation Control Commands Previous: The cache Command   Contents   Index
Stephen R. Whiteley 2022-09-18