next up previous contents index
Next: Unused Option Variables Up: Variables Previous: Plot Variables   Contents   Index


Simulation Option Variables

These variables control defaults related to simulation. Most of these variables can be set indirectly from the Sim Defs tool in the Tools menu of the Tool Control window, which is equivalent to using the set command. They (and any variable) can also be included in an .options line in the input file. Before a simulation starts, the options from the .options line are merged with any that have been set using the shell. The result of the merge is that options that are booleans will be set if set in either case, and those that take values will assume the value set through the shell if conflicting definitions are given. The merge will be suppressed if the shell variable noshellopts is set from the shell, in which case the only options used will be those from the .options line, and those set using the set command will be ignored.

In the listing of variables provided by the set command without arguments, the variables set in the .options line of the current circuit will be listed with a ``+'' in the first column. The variables set in the .options line are available for substitution (into $variable references) when the circuit is the current circuit, but otherwise do not affect the shell. For example, setting the variable noglob from a .options line will not affect the global expansion of the shell, but references to $noglob would behave as if the boolean noglob was set, while the circuit is the current circuit.

Shell variables set in the .options line are set before the rest of the SPICE text is expanded, so that shell variable references in the text can be defined from the .options line, as in the .exec block. The .exec lines are executed before the .options lines are expanded.

abstol
This variable sets the absolute error tolerance used in convergence testing. The default value is 1e-12.

bypass
When bypassing is enabled, which is the default, semiconductor devices will skip certain computations when terminal voltages are relatively static. This is a speed optimization. This variable can be set as an integer to a value of 0 (zero) to disable bypassing. This can perhaps increase accuracy, at the expense of speed. When set to a nonzero value, or to no value, there is no effect as bypassing is enabled by default.

chgtol
This variable sets the minimum charge used when predicting the time step in transient analysis. The default value is 1e-14.

dcmu
This option variable takes a value of 0.0-0.5, with the default being 0.5. It applies during operating point analysis. When set to a value less than 0.5, the Newton iteration algorithm mixes in some of the previous solution, which can improve convergence. The smaller the value, the larger the mixing. This gives the user another parameter to twiddle when trying to achieve DC convergence. This can be set from the Convergence page of the Sim Defs tool.

defad
This variable sets the default value for MOS drain diffusion area, and applies to all MOS device models. The default is 0.0.

defas
This sets the default value for MOS source diffusion area, and applies to all MOS device models. The default is 0.0.

defl
This sets the default value for MOS channel length, and applies to all MOS device models. The default is model dependent, and is 100.0 microns for MOS levels 1-3 and 6, and typically 5.0 microns for other models.

defw
This variable sets the default value for MOS channel width, and applies to all MOS device models. The default is model dependent, and is 100.0 microns for MOS levels 1-3 and 6, and typically 5.0 microns for other models.

dphimax
This variable sets the maximum allowable phase change of sinusoidal and exponential sources between internal time points in transient analysis.

Consider a circuit consisting of a sinusoidal voltage source driving a resistor network. The internal transient time steps are normally determined from a truncation error estimation from the numerical integration of reactive elements. Since there are no such elements in this case, a large, fixed time step is used. This may not be sufficient to reasonably define the sinusoidal source waveform, so the timestep is cut. This variable sets the time scale for the cut. The default value of $ \pi$/5 provides about 10 points per cycle. All of the built-in source functions that are exponential or sinusoidal reference this variable in the timestep cutting algorithm.

This variable also limits the transient time step when Josephson junction devices are present, i.e., it is equivalent to the jjdphimax variable in Jspice3.

The variable can be set in the range $ \pi$/1000 - pi, and is taken as $ \pi$/5 if unset.

gmin
This sets the value of gmin, the minimum conductance allowed by the program. The default value is 1e-12.

gminfirst
When this boolean option variable is set, during operating point analysis, gmin stepping is attempted before source stepping. This is the default in Berkeley SPICE, however the WRspice default is to apply source stepping first, which seems more effective.

gminsteps
This variable controls the gmin stepping used in operating point analysis (see 2.7.5). The values are integers in the range -1 through 20, with the default being 0. If -1, no gmin stepping will be attempted. If set to 0 (the default) the dynamic gmin stepping algorithm is used. This will use variable-sized steps, reattempting with a smaller step after failure. If positive, the Berkeley SPICE3 gmin stepping algorithm will be used, with a fixed number of steps as given.

interplev
In transient analysis, in the default steptype mode, internal timepoint data are interpolated onto the external (user supplied) time points. Only the interpolated data are saved. This variable sets the polynomial degree of interpolation, in the range 1-3. The default is 1 (linear interpolation).

itl1
The itl1 variable sets the dc iteration limit before convergence failure is indicated. The default is 400.

itl2
The itl2 variable sets the dc transfer curve iteration limit before convergence failure is indicated. The default is 100.

itl2gmin
The itl2gmin variable sets the maximum number of iterations to allow per step during gmin stepping when finding the dc operating point. The default is 20.

itl2src
The itl2src variable sets the maximum number of iterations to allow per step during dynamic source stepping when finding the dc operating point. The default is 20.

itl4
This variable sets the number of timepoint iterations in transient analysis above which convergence failure is indicated. The default is 10.

jjaccel
This applies only when Josephson junctions are present in the circuit, and performing transient analysis. It causes a faster convergence testing and iteration control algorithm to be used, rather than the standard more comprehensive algorithm suitable for all devices. If the circuit consists of Josephson junctions, passive elements, and sources only, then setting this option may provide a reduction in simulation time. It probably should not be used if semiconductor devices are present.

maxdata
This variable sets the maximum allowable memory stored as plot data during an analysis, in kilobytes. The default is 256000. For all analyses except transient with the steptype variable set to ``nousertp'', the run will abort at the beginning if the memory would exceed the limit. Otherwise, the run will end when the limit is reached.

maxord
This variable sets the maximum order of the integration method used. Setting this to 1 will always use rectangular integration. If unset, the value taken is 2, which is the maximum order for the default trapezoidal integration. If Gear integration is used, the maximum order is 6.

method
This string can be set to either of the keywords ``trap'', which is the default and sets trapezoidal integration, or ``gear'', for Gear integration. The maxord variable sets the maximum order of the integration.

minbreak
This sets the minimum interval between breakpoints in transient analysis, which is otherwise set to 1e-20.

noadjoint
Most of the BSIM device models in WRspice have added code that builds an adjoint matrix which is used to accurately compute device currents. The computed currents are not used in the device models, but are available as simulation outputs. This has a small performance overhead which can be eliminated by setting this boolean variable. The cost is that it may not be possible to obtain device currents during the simulation, using the device[param] ``pseudo-vector''.

noiter
Not currently implemented.

During transient analysis, at each new time step, Newton iterations are used to solve the nonlinear circuit equations. The first iteration, the prediction step, uses extrapolation from past values to obtain a best guess at the solution for use as input. Additional iterations use the previous output values as input.

In cases where the nonlinearity is weak, or where the internal time step is forced to be small (as when Josephson junctions are present) iterations beyond the predictor sometimes lead to unneeded accuracy. Setting the variable noiter causes skipping of iterations beyond the prediction step, and also skipping of certain other code. This maximizes the simulation rate, but can lead to errors if not used carefully. Much the same effect can be obtained by setting reltol to a large value, however noiter is more efficient as convergence testing and matrix loading are skipped, as there is a-priori knowledge that no iterations are to take place. The iteration count and total internal timepoint count are available from the rusage command.

nojjtp
During transient analysis with Josephson junctions present, the default time step is given by T = $ \phi$/vmax, where $ \phi$ = $ \Phi_{0}^{}$/2$ \pi$ ($ \phi$ = 3.291086546e-16, $ \Phi_{0}^{}$ is the magnetic flux quantum) and vmax = max(Vj, sqrt($ \phi$Jc/C)). If the variable nojjtp is set, the timestep is determined from a truncation error calculation, as is the case when Josephson junctions are not present in the circuit. The user should experiment to determine which timestep leads to faster execution.

noklu
When this boolean variable is set, KLU will not be used for sparse matrix calculations. Otherwise, if the KLU plug-in is available, KLU will be used by default. The KLU plug-in is provided with all WRspice distributions, and is installed in the startup directory.

nomatsort
When using Sparse (i.e., KLU is unavailable or disabled), this boolean variable when set will prevent using element sorting to improve speed. This corresponds to the legacy WRspice sparse code. It may be interesting for comparison purposes, but setting this variable will slow simulation of most circuits. This variable has no effect if KLU is being used.

noopiter
This boolean variable applies when one of gminsteps or srcsteps is given a positive value, and thus operating point analysis (see 2.7.5) is using a Berkeley algorithm. In this case, by default a direct iterative solution of the circuit matrix is attempted, and if this fails the stepping methods are attempted. This initial direct solution attempt most often fails with complex circuits and can be time consuming. Setting noopiter> will skip this initial attempt.

noshellopts
If set, do not use WRspice options that have been set interactively through the shell. Use only options that appear in a .options line in the circuit file when running a simulation of the circuit.

notrapcheck
In some circuits, whose equations are ``stiff'' in a mathematical sense, trapezoidal integration may not converge in transient analysis. These circuits likely have a low impedance (voltage source) driving a capacitor, and/or a high impedance driving an inductor. Non-convergence can take several forms:

  1. The run exits with a ``timestep too small'' message.
  2. The run exits with a math error such as overflow or underflow.
  3. Circuit variables oscillate between values at every internal time point. The oscillations increase in amplitude as simulation progresses.
  4. Circuit variables monotonically diverge to huge values.

When using trapezoidal integration, there is a test to check for the oscillatory behavior characteristic of this type of nonconvergence. If nonconvergence is detected, the present time point is rejected, the time step is cut by a factor of eight, and the time point calculation is repeated using backward Euler integration. The circuit will return to trapezoid integration in a few internal time steps.

This is an improvement, but does not solve all convergence problems. In particular, this test will not detect monotonic divergence, which could be detected by other means but too late to do anything about it.

The new test may slow down transient analysis of some circuits. For circuits that are known to be stable, the test can be avoided by setting the option variable notrapcheck.

oldlimit
When set, the SPICE2 limiting algorithm for MOS devices is used. Otherwise, an improved limiting procedure is used.

parhier
By default, parameters from .param lines, subcircuit instantiation lines, and subcircuit definition lines have top-down precedence, meaning that when resolving parameter name clashes, the definition at the highest level in the subcircuit hierarchy takes precedence. Thus, by default, parameters defined in .param lines outside of any subcircuit will override parameters of the same name anywhere in the hierarchy.

The parhier option variable can be set to one of the keywords ``global'' or ``local''. The ``global'' setting retains default behavior. The ``local'' setting reverses the precedence to bottom-up. In this case, parameter definitions at the lowest level within subcircuits will have precedence.

The parameter scoping rules are identical to HSPICE in release 3.2.15 and later. Earlier releases had different scoping rules, with the default being closer but not identical to the ``local'' rule.

pivrel
This variable sets the relative ratio between the largest column entry and an acceptable pivot value. The default value is 1e-3. In the numerical pivoting algorithm the allowed minimum pivot value is determined by epsrel=max(pivrel*maxval,pivtol) where maxval is the maximum element in the column where a pivot is sought (partial pivoting).

pivtol
This variable sets the absolute minimum value for a matrix entry to be accepted as a pivot. The default value is 1e-13.

reltol
This sets the relative error tolerance used in convergence testing. The default value is 0.001 (0.1 percent).

renumber
When set, the source lines are renumbered sequentially after subcircuit expansion.

savecurrent
If this variable is set, then all device current special vectors are saved in the plot by default during analysis. This enables plotting of device currents using the @device[param] construct.

spice3
By default, WRspice uses a custom algorithm for controlling integration order during transient analysis. This algorithm provides the following advantages over the SPICE3 algorithm:

  1. It provides a possibly better determination of when to use higher integration orders. This is slightly different from the SPICE3 algorithm even for the order 2 that SPICE3 supports, and probably takes a few more Euler time steps, but the WRspice code appears to be less susceptible to trapezoid integration nonconvergence.

  2. WRspice allows the full range of Gear integration orders, unlike SPICE3 which does not advance integration order above 2, when maxord is larger than 2. It is not clear how useful higher-order Gear integration is. Unlike Gear 2, which is much more stable in general than trapezoidal integration for stiff systems, this is not true of the higher orders.

  3. When the time step is reduced and integration order is cut due to non-convergence, backward-Euler is now enforced for the next two time steps. In SPICE3, only the first time step is forced to be backward-Euler. The new approach reduces the tendency of some circuits to not converge when trapezoidal integration is used.

The standard SPICE3 logic can be used if desired, by setting the boolean option variable spice3. WRspice releases prior to 3.2.13 used the SPICE3 algorithm exclusively.

srcsteps
This variable controls the source stepping used in operating point analysis (see 2.7.5). The values are integers in the range -1 through 20, with the default being 0. If -1, no source stepping will be attempted. If set to 0 (the default) the dynamic source stepping algorithm is used. This will use variable-sized steps, reattempting with a smaller step after failure. If positive, the Berkeley SPICE3 source stepping algorithm will be used, with a fixed number of steps as given.

steptype
This string can be set to one of three keywords which determine the data output mode in transient analysis. It can be set to ``interpolate'', which is the default, ``hitusertp'', or ``nousertp''.

If not set, or set to ``interpolate'', output points are interpolated from internal time points to the user time increments, with degree 1 (the default) to 3, set by the interplev variable.

If set to ``hitusertp'', then during transient analysis the time step will be cut so as to land on the user time points. This requires more simulation time, but provides the greatest accuracy.

Setting to ``nousertp'' will cause internal timepoint data to be saved, either in internal data structures in interactive mode or in the rawfile in batch mode. The amount of data can grow quite large.

temp
This variable specifies the assumed operating temperature of the circuit under simulation. The default value is 25C (298K).

tnom
The tnom variable sets the nominal temperature. The default value is 25C (298K). This is the temperature at which device model parameters are assumed to have been measured.

trtol
This is a factor used during time step prediction in transient analysis. The default value is 7.0. This parameter is an estimate of the factor by which WRspice overestimates the actual truncation error. Larger values will cause WRspice to attempt larger time steps.

trapratio
This controls the ``sensitivity'' of the trapezoid integration convergence test, as described with the notrapcheck variable. Higher values make the test less sensitive (and effective) but reduce the number of false positives that can slow down simulation. The default value is 10.0.

trytocompact
This boolean variable is applicable only to the LTRA model. When specified, the simulator tries to condense LTRA transmission line past history of input voltages and currents.

vntol
This variable sets the absolute voltage error tolerance used in convergence testing. The default value is 1 microvolt.

xmu
This is the trapezoid/Euler mixing parameter that was provided in SPICE2, but not in SPICE3. It effectively provides a mixture of trapezoidal and backward Euler integration, which can be useful if trapezoid integration produces nonconvergence. It applies only when trapezoidal integration is in use, and the maximum order is larger than 1. When xmu is 0.5 (the default), pure trapezoid integration is used. If 0.0, pure backward-Euler (rectangular) integration is used, but the time step predictor still uses the trapezoid formula, so this will not be the same as setting maxord to 1 (which also enforces backward-Euler integration). Trapezoidal integration convergence problems can sometimes be solved by setting xmu to values below 0.5. Setting xmu below about 0.4 is not recommended, better to use Gear integration.


next up previous contents index
Next: Unused Option Variables Up: Variables Previous: Plot Variables   Contents   Index
Stephen R. Whiteley 2012-09-24