next up previous contents index
Next: Operating Range Analysis File Up: Margin Analysis Previous: Margin Analysis   Contents   Index

Operating Range Analysis

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 filename
In 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:

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. If not specified, the pass/fail test is applied after the trial is finished. The checkPNTS vector is usually set in the header to a list of values with the compose command.

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 the X-axis 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. The checkSTP2 variable sets the number of cells in the Y-axis of the plot produced by mplot.

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

opmin1, opmax1 (real, length > = 1 )
The operating range analysis can be directed to find the operating range extrema of the first parameter for each value of the second parameter. These vectors contain the values found, and are automatically generated if the range finding feature is enabled. They are not generated in Monte Carlo analysis.

opmin2, opmax2 (real, length > = 1 )
The operating range analysis can be directed to find the operating range extrema of the second parameter for each value of the first parameter. These vectors contain the values found, and are automatically generated if the range finding feature is enabled. They are not generated in Monte Carlo analysis.

range, r_scale (real, length > = 1 )
If the range finder was active, these vectors are automatically created and added to the plot. The range vector and its scale r_scale contain all of the extrema data, formatted in such a way that the path is the contour of the boundary of the pass region. The plot command can be used to display this contour by entering ``plot range''.

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. The name of this vector can be redefined by setting a shell variable named ``value'' to a new name.

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

checkiterate (integer 0-10)
This sets the binary search depth used in finding operating range extrema. If not set or set to zero, the search is skipped. The binary search is used to find the exact values of the operating region boundary, and has no relevance to the usual set of pass/fail outputs generated with the check command. If nonzero, during operating range analysis and not in all-points mode, the extrema for each row and column are found, and saved in the opmin1, opmax1, opmin2, and opmax2 vectors, which are then used to generate the range and r_scale vectors described above.

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.

value1, value2
The value1 and value2 variables are set to the current trial values to be used in the circuit (parameters 1 and 2). The SPICE deck should reference these variables (as $value1 and $value2) as the parameters to vary. Alternatively, the vector value array can be used for this purpose. These variables can be used in Monte Carlo analysis, but are not set implicitly.

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

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.

  1. Perhaps the most direct method is to include the forms $value1 and $value2 (if two dimensional) for substitution in the current circuit. The variables will be replaced by the appropriate numerical values before each trial, as for shell variable substitution.

  2. If a variable named ``value1'' is set to a string token with the set command, then a variable of the same name as the string token will hold the trial values, instead of value1. The same applies to value2. Thus, for example, if the circuit contains expansion forms of the variables foo1 and foo2 (i.e., $foo1 and $foo2), one could perform an analysis using these variables by giving

    set value1 = foo1 value2 = foo2

  3. The method above allows the SPICE options to be set. These are the built-in keywords, which can be set with the set command or in a .options line in an input file, which control or provide parameters to the simulation.

    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

  4. If there are existing vectors named ``checkN1'' and (if two dimensions) ``checkN2'' that contain integer values, and the variable named ``value'' is set to the name of an existing vector (or a vector named ``value'' exists), then the vector components indexed by checkN1 and checkN2 will hold trial values, if within the size of the vector. For example:

    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

  5. Given that it is possible to set a vector as if a variable, by using the set command with the syntax

    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'

  6. The construct above can be extended to ``special'' vectors, which enable device and model parameters to be set ahead of the next analysis. These special vectors have the form


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

next up previous contents index
Next: Operating Range Analysis File Up: Margin Analysis Previous: Margin Analysis   Contents   Index
Stephen R. Whiteley 2022-09-18