%$Id: options.tex,v 25.95 2006/08/26 01:26:53 al Exp $ -*- LaTeX -*-
% man commands options .
% Copyright (C) 2001 Albert Davis
% Author: Albert Davis <aldavis@ieee.org>
%
% This file is part of "Gnucap", the Gnu Circuit Analysis Package
%
% This program is free software; you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation; either version 2, or (at your option)
% any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program; if not, write to the Free Software
% Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
% 02110-1301, USA.
%------------------------------------------------------------------------
\section{{\tt OPTIONS} command}
\index{options command}
\index{set command}
\index{system options}
\index{options: global}
\index{global options}
%------------------------------------------------------------------------
\subsection{Syntax}
\begin{verse}
{\tt options}\\
{\tt options} {\it option-name value} ...
\end{verse}
%------------------------------------------------------------------------
\subsection{Purpose}

Sets options, iteration parameters, global data.
%------------------------------------------------------------------------
\subsection{Comments}

Typical usage is the name of the item to set followed by the
value.

The bare command `{\tt options}' displays the values.

These options control the simulation by specifying how to
handle marginal circumstances, how long to wait for
convergence, etc.

Most of the SPICE options are supported, more have been added.
%------------------------------------------------------------------------
\subsection{Parameters}

\begin{description}

\index{accounting}
\item[{\tt acct}] Turns on accounting.  When enabled, print the
CPU time used after each command, and a summary on exit in batch
more.  This does not affect accounting done by the {\tt status}
command.

\item[{\tt noacct}] Turns off accounting.  (Not in SPICE.)

\index{echo file input}
\item[{\tt list}] Turns on echo of files read by {\tt get} and
{\tt merge} commands, and in batch mode.  (SPICE option accepted
but not implemented.)

\item[{\tt nolist}] Turns off list option.  (Not in SPICE.)

\item[{\tt mod}] Enable printout of model parameters.  (Accepted,
but not implemented, to complement {\tt nomod}.)

\item[{\tt nomod}] Suppress printout of model parameters.  (SPICE
option accepted but not implemented.)

\item[{\tt page}] Enable page ejects at the beginning of
simulation runs.  (Accepted, but not implemented, to complement
{\tt nopage}.)

\item[{\tt nopage}] Turn off page ejects.  (SPICE option accepted
but not implemented.)

\item[{\tt node}] Enable printing of the node table.  (SPICE
option accepted but not implemented.)

\item[{\tt nonode}] Disable printing of the node table.
(Accepted, but not implemented, to complement {\tt NODE}.)

\item[{\tt opts}] Enable printing of option values on every options
command.

\item[{\tt noopts}] Disable automatic printing of option values.
Option values are only printed on a null options command.

\index{gmin option}
\index{minimum conductance}
\index{open circuit error}
\item[{\tt gmin} = {\it x}] Minimum conductance allowed by the program.
(Default = 1e-12 or 1 picomho.)  Every node must have a net
minimum conductance of {\tt GMIN} to ground.  If effective open
circuits are found during the solution process (leading to a
singular matrix) a conductance of {\tt GMIN} is forced to
ground, after printing an "open circuit" error message.

\index{reltol option}
\index{relative tolerance}
\index{convergence criteria}
\item[{\tt reltol} = {\it x}] Relative error tolerance allowed.
(Default =.001 or .1\%.)
If the ratio of successive values in iteration are within {\tt
RELTOL} of one, this value is considered to have converged.

\index{abstol option}
\index{absolute tolerance}
\index{convergence criteria}
\item[{\tt abstol} = {\it x}] Absolute error tolerance
allowed.  (Default = 1e-12)
If successive values in iteration are within {\tt ABSTOL} of
each other, this value is considered to have converged.

\index{vntol option}
\index{voltage tolerance}
\index{model evaluation bypass}
\item[{\tt vntol} = {\it x}] Absolute voltage error required to
force model re-evaluation.  (Default = 1e-12 or 1 microvolt.)
If the voltage at the terminals of a model is within {\tt
VNTOL} of the previous iteration, the model is not
re-evaluated.  The old values are used directly.

\index{trtol option}
\index{transient error tolerance}
\item[{\tt trtol} = {\it x}] Transient error ``tolerance''.
(Default = 7.)  This parameter is an estimate of the factor by
which the program overestimates the actual truncation error.

\index{chgtol option}
\index{charge error tolerance}
\item[{\tt chgtol} = {\it x}] Charge tolerance.  (Default =
1e-14) It is used in step size control in transient analysis.

\index{pivtol option}
\index{pivot tolerance}
\item[{\tt pivtol} = {\it x}] Pivot tolerance.  (Default =
1e-13) SPICE option accepted but not implemented.

\index{pivrel option}
\item[{\tt pivrel} = {\it x}] Pivot ratio.  (Default = 1e-3)
SPICE option accepted but not implemented.

\index{numdgt option}
\item[{\tt numdgt} = {\it x}] Number of significant digits to print
for analysis results.  (Default = 5.)  It is silently limited to 3
to 20.

\index{tnom option}
\index{temperature}
\index{nominal temperature}
\index{reference temperature}
\item[{\tt tnom} = {\it x}]
Nominal temperature.  (Default = 27$^{\circ}$ C.)  All components have
their nominal value at this temperature.

\index{iteration count}
\index{itl? options}
\item[{\tt itl1} = {\it x}] DC iteration limit.  (Default = 100.)
Sets the maximum number of iterations in a DC, OP, or initial
transient analysis allowed before stopping and reporting that it
did not converge.

\item[{\tt itl2} = {\it x}] DC transfer curve iteration limit.
(Default = 50.)  SPICE option accepted but not implemented.
Use {\tt itl1} instead.

\item[{\tt itl3} = {\it x}] Lower transient iteration limit.
(Default = 6.)  If the number of iterations is more than {\tt itl3}
the step size is limited by {\tt trstephold}.  Otherwise,
it can grow by {\tt trstepgrow}.

\item[{\tt itl4} = {\it x}] Upper transient iteration limit.
(Default = 20.)  Sets the maximum number of iterations on a step
in transient analysis.  If the circuit fails to converge in this
many iterations the step size is reduced (by option trstepshrink),
time is backed up, and the calculation is repeated.

\item[{\tt itl5} = {\it x}] Transient analysis total iteration
limit.  (Default = 5000.)  SPICE option accepted but not
implemented.  Actual behavior is the same as {\tt itl5} = 0, in
SPICE, which omits this test.

\item[{\tt itl6} = {\it x}] Source stepping iteration limit.
(Default = 0.)  SPICE option accepted but not implemented.
Source stepping is not available.

\index{worst case iterations}
\index{iterations: worst case analysis}
\item[{\tt itl7} = {\it x}] Worst case analysis iteration
limit.  (Default = 1.)
Sets the maximum number of iterations for the individual
element trials in a DC or bias worst case analysis.  If more
iterations than this are necessary, the program silently goes
on to the next step, as if nothing was wrong, which is usually
the case.

\index{convergence diagnostics}
\item[{\tt itl8} = {\it x}] Convergence diagnostic iteration threshold.
(Default = 100.)  If the iteration count on a step exceeds {\tt itl8}
diagnostic messages are printed in an attempt to aid the user in solving the
convergence problem.

\index{cptime option}
\index{cpu time limit}
\item[{\tt cptime} = {\it x}] Total CPU job time limit.
(Default = 30000.)  SPICE option accepted but not implemented.
There is no limit imposed.

\index{limtim option}
\item[{\tt limtim} = {\it x}] CPU time reserved for plotting.
(Default = 2.)  SPICE option accepted but not implemented.

\index{limpts option}
\item[{\tt limpts} = {\it x}] Max number of points printed.
(Default = 201.)  SPICE option accepted but not implemented.

\index{lvlcod option}
\item[{\tt lvlcod} = {\it x}] Matrix solution and allocation
method.  (Default = 2, generate machine language.)  SPICE
option not implemented.

\index{lvltim option}
\index{time step control}
\item[{\tt lvltim} = {\it x}] Time step control method.
(Default = 2, truncation error.)  SPICE option not implemented.

\index{method option}
\index{integration method}
\item[{\tt method} = {\it x}]
Differentiation method.  (Default = {\tt TRAPezoidal}.)  (Incorrectly
called ``integration'' method in SPICE.) Possible values are:
\begin{description}
\item[{\tt euler}] backward Euler, unless forced to other
\item[{\tt euleronly}] backward Euler only
\item[{\tt trap}] usually trap, but Euler where better
\item[{\tt traponly}] always trapezoid
%%%\item[{\tt gear2}] usually gear2, but euler where better
%%%\item[{\tt gear2only}] always gear2 (except breakpoints)
%%%\item[{\tt trapgear}] alternate trap and gear2
%%%\item[{\tt trapeuler}] alternate trap and euler
\end{description}

\index{defl option}
\index{mosfet defaults}
\item[{\tt defl} = {\it x}] MOSFET default channel length in 
meters.  (Default = 100u.)

\index{defw option}
\item[{\tt defw} = {\it x}]  MOSFET default channel width in 
meters.  (Default = 100u.)

\index{defad option}
\item[{\tt defad} = {\it x}] MOSFET default drain diffusion area
in square meters.  (Default = 0.)

\index{defas option}
\item[{\tt defas} = {\it x}]  MOSFET default source diffusion area
in square meters.  (Default = 0.)

%%%\index{seed option}
%%%\index{random number seed}
%%%\item[{\tt SEED} = {\it x}]
%%%Seed used by the random number generator.  (Default = 1.)  (Not
%%%available in SPICE.)  The same random numbers will be used every time,
%%%determined by this seed number.  Setting this to zero is a special
%%%case, causing each run to start from a random point.

%%%\index{wczero option}
%%%\index{zero: worst case}
%%%\item[{\tt WCZERO} = {\it x}]
%%%Worst case zero window.  (Default = 1e-9) (Not available in SPICE.)
%%%Sets a window for the difference in a DC or bias worst case analysis.
%%%Differences less than this are assumed to be zero, for purposes of
%%%setting direction flags.  This prevents cluttering up the screen with
%%%very small numbers that are essentially zero.
        
\index{damp option}
\index{damped Newton's method}
\item[{\tt dampmax} = {\it x}] Normal Newton damping factor.
(Default = 1.)  Sets the damping factor for iteration by damped
Newton's method, used when all is well.  It must be between 0 and 1,
as close to 1 as possible and still achieve convergence.  The useful
range is from .9 to 1.  Setting {\tt dampmax} too low will probably cause
convergence to a nonsense result.

\item[{\tt dampmin} = {\it x}] Newton damping factor in problem
cases.  (Default = .5)  Sets the damping factor for iteration by
damped Newton's method, used when there are problems.  It must be
between 0 and 1, and is usually set somewhat less than {\tt dampmax}.
The useful range is from .5 to .9.  Setting it lower than .5 may
cause convergence to a nonsense result.  Aside from that, a lower
value (but less than {\tt dampmax}) tends to improve robustness at
the expense of convergence speed.

\item[{\tt dampstrategy} = {\it x}] Damping strategy.  (Default =
0)  The actual damping factor to use is determined by heuristics.
Normally the damping factor is {\tt dampmax}.  It is reduced to
{\tt dampmin} when certain conditions occur, then it drifts back
up on subsequent iterations.  This parameter turns the various
heuristics on or off.  The number to use is the sum of the following
flags.

\begin{description}

\item{1} the second iteration on any voltage or time step.  (usually
helps robustness, but always increases iteration count.)

\item{2} if the voltage at any nonlinear node exceeds the range
determined by {\tt vmin}, {\tt vmax}, and {\tt limit}.  (usually
not desirable.)

\item{4} if any device limiting algorithm is activated.  (usually
not desirable.)

\item{10} when any device crosses a region boundary.  (usually
desirable and has little cost.)

\item{20} when a FET or BJT is reversed.  (usually helps robustness.
sometimes increases iteration count.)

\end{description}
        
\index{floor option}
\index{suppressing numerical noise}
\item[{\tt floor} = {\it x}] Effective zero value.  (Default =
1e-21) Results values less than {\tt floor} are shown as zero.  Other
small numbers are rounded to the nearest {\tt floor}.
        
\item[{\tt vfloor} = {\it x}] Effective zero value for voltage probes.
(Default = 1e-15) Results values less than {\tt vfloor} are shown as
zero.  Other small numbers are rounded to the nearest {\tt vfloor}.
        
\item[{\tt roundofftol} = {\it x}]
Numeric rounding tolerance. (Default = 1e-13) Some internal
calculations can result in cancellations, with a result near zero even
though the operands are large.  The number is converted to zero if it
is less than {\tt roundofftol}*theoperand.

\index{temperature option}
\index{ambient temperature}
\item[{\tt temperature} = {\it x}] Simulation temperature.
(Default = 27$^{\circ}$ C.)  Sets the ambient temperature, in
degrees Celsius.  This is the temperature at which the
simulation takes place, unless changed by some other command.

\index{short option}
\index{short circuit resistance}
\index{voltage source resistance}
\index{resistance of short}
\item[{\tt short} = {\it x}] Resistance of voltage source or
short.  (Default = 1e-7 or 10 $\mu\Omega$.)  Sets the default
resistance of voltage sources.  In some cases, inductors are
replaced by resistors, if so, this is the value.  It is also
the resistance used to replace short circuits anywhere they are
not allowed and the program finds one.

\index{in option}
\index{input width option}
\index{width command}
\item[{\tt in} = {\it x}] Input width.  (Default = 80.)
Sets the last column read from each line of input.  Columns
past this are ignored.  This option is present only for SPICE
compatibility, through the {\tt width} command, which is an
alias for {\tt options}.

\index{out option}
\index{output width option}
\item[{\tt out} = {\it x}] Output width.  (Default = 80.)
Sets the output print width, for tables and character graphics.

\index{ydivisions option}
\index{plot control}
\item[{\tt ydivisions} = {\it x}]  Y axis divisions. (Default = 4)
Sets the number of divisions on the Y axis for plotting.

\item[{\tt phase} = {\it x}]
Phase units. (Default = {\tt degrees}) Valid values are {\tt degrees}
and {\tt radians}.  Selects which units are used for printing phase in
AC analysis.

\item[{\tt order} = {\it x}] Equation ordering.  (Default = auto.)
Determines how external node numbers are mapped to internal numbers.  The
values are {\tt forward}, {\tt reverse}, and {\tt auto}.

\item[{\tt mode} = {\it x}] Simulation mode selection.  (Default = mixed.)
Values are {\tt analog}, {\tt digital}, and {\tt mixed}.  In analog mode,
logic elements (type U) are replaced by their subcircuits as if they were
type X.  In digital mode, logic elements are simulated as digital regardless
of whether the signals are proper or not, as in traditional mixed-mode
simulation.  In mixed mode, logic elements may be simulated as analog or
digital depending on the signals present.

\index{transits option}
\index{mixed mode control}
\item[{\tt transits} = {\it x}] Mixed mode transition count. (Default = 2)
Sets the number of ``good'' transitions for a supposedly digital signal
to be accepted as digital.

\index{bypass option}
\item[{\tt bypass}] 
Bypass model evaluation if appropriate.  If the last two iterations
indicate that an element is converged or dormant, do not evaluate it
but use its old values directly.  (Default)

\item[{\tt nobypass}]
Do not bypass model evaluation.

\index{incmode option}
\item[{\tt incmode}]
Incrementally update the matrix.  Instead of rebuilding the matrix on
every iteration, keep as much of the old matrix as possible and make
incremental changes.  (Default)

\item[{\tt noincmode}]
Do not incrementally update the matrix.  This eliminates a possible
cause of roundoff error at the expense of a slower simulation.

\index{lcbypass option}
\item[{\tt lcbypass}]
Bypass evaluation of linear inductors and capacitors when possible.
When set, they are evaluated only on the first iteration of a time
step. (Default)

\item[{\tt nolcbypass}]
Do not bypass linear capacitor and inductors.  Evaluate on every
iteration.

\index{lubypass option}
\item[{\tt lubypass}] Bypass parts of LU decomposition if appropriate.  If
only a few elements of the matrix were changed solve only those parts
of the LU matrix that depend on them.  (Default)

\item[{\tt nolubypass}]
Do not bypass parts of LU decomposition.  Solve the entire LU matrix
whenever a matrix solution is called for regardless of whether it is
actually needed.

\index{fbbypass option}
\item[{\tt fbbypass}]
Skip matrix solution the last iteration.  In theory, it reduces
accuracy slightly, but specified tolerances will still be met.  Time
saving can be significant.  (Default)

\item[{\tt nofbbypass}]
Do not skip the matrix solution on the last iteration.

\item[{\tt traceload}] Use a queue to only load changed elements
to the matrix.  This results in faster loading and has no known
drawbacks.  (Default)

\item[{\tt notraceload}] Do not use a queue to only load changed
elements to the matrix.  Instead, load all elements, even if they
are unchanged or zero.  This is always slower, and is forced if
"noincmode".

\item[{\tt itermin} = {\it x}] 
Number of extra iterations after convergence. (Default = 1) After
convergence tolerances are met, do {\tt itermin} extra iterations to
be sure.  This provides protection against false indication of
convergence.  Setting {\tt itermin} = 0 is equivalent to SPICE, with
improved simulation speed.

\item[{\tt vmin} = {\it x}]
Initial negative node voltage limit.  (Default = -5) All node voltages
may be limited to $-x$ to aid in convergence and prevent numeric
overflow.  This is intended as a convergence aid only.  It may or may
not help.  This number is used as a starting point.  It is adjusted as
the simulation progresses.

\item[{\tt vmax} = {\it x}]
Initial positive node voltage limit.  (Default = 5) All node voltages
may be limited to $+x$ to aid in convergence and prevent numeric
overflow.  This is intended as a convergence aid only.  It may or may
not help.  This number is used as a starting point.  It is adjusted as
the simulation progresses.

\index{dtmin option}
\index{minimum resolvable time}
\index{minimum time step}
\item[{\tt dtmin} = {\it x}] Minimum time step.  (Default = 1e-12.)
The smallest internal time step in transient analysis.  The {\tt
transient} command {\tt dtmin} option and the {\tt dtratio} option
override it if it is bigger.

\item[{\tt dtratio} = {\it x}] The ratio between minimum and maximum
time step.  (Default = 1e9).

\index{rstray option}
\index{mosfet series resistance}
\item[{\tt rstray}] Include series resistance in device models.  This 
creates internal nodes and results in a significant speed and memory
penalty.  It also makes convergence characteristics worse. (Default =
true)

\item[{\tt norstray}] Do not include series resistance in device
models.  This results in faster simulations and better numerical
accuracy at the expense of model accuracy.  Differences between
{\tt rstray} and {\tt norstray} have been observed to be insignificant
most of the time.  Some popular commercial versions of SPICE do
not implement series resistance at all, so {\tt norstray} may be
more consistent with other simulators.

\index{cstray option}
\index{mosfet capacitance}
\index{diode capacitance}
\item[{\tt cstray}] Include capacitance in device models.  This may
create internal nodes and result in a significant speed and memory 
penalty.  It also may make convergence characteristics worse.  (Default)

\item[{\tt nocstray}] Do not include capacitance in device models.
This results in faster simulations and better numerical accuracy
at the expense of model accuracy.  Differences between {\tt cstray}
and {\tt nocstray} are usually significant, since often the strays
are the dominant reactive elements.

\index{harmonics option}
\index{fourier: harmonics}
\item[{\tt harmonics} = {\it x}] Harmonics in Fourier analysis.
(Default = 9) The number of harmonics to display in a Fourier
analysis, unless specified otherwise.

\item[{\tt trstepgrow} = {\it x}]
The maximum internal step size growth in transient analysis.  Default
= 1e99, which allows arbitrary changes in step size.

\item[{\tt trstephold} = {\it x}]
The maximum internal step size growth in transient analysis, when the
iteration count exceeds {\tt itl3} but still converges.  (Default =
1e99)

\item[{\tt trstepshrink} = {\it x}]
The amount to decrease the transient step size by when convergence
fails.  (Default = 2.)

\item[{\tt trreject} = {\it x}] Transient error rejection threshold.
(Default = .5)  Controls how bad the truncation error must be to
reject a time step.  A value of .5 means that if the step reqested
is smaller than .5 times the step size used, the current step will
be rejected.  If the new step is .8 times the old step size it will
be adjusted but the step just calculated will not be rejected.

\item[{\tt quitconvfail}]
Quit on convergence failure in transient analysis.  Do not adjust time
step, just stop.  (Default = false)

\item[{\tt noquitconvfail}]
Do not quit on convergence failure in transient analysis.  Instead,
try to adjust time step and try again.  If even the smallest time step
still fails, conntinue simulating and accept the bad step.  (Default)

\item[{\tt recursion} = {\it x}]
Limit recursion in expresion evaluation to x levels.  (Default = 20)
The purpose is to trap infinite recursion in user expressions.

\item[{\tt edit}] Enable command line editing. (Default)

\item[{\tt noedit}] Disable command line editing.

\end{description}
%------------------------------------------------------------------------
\subsection{Examples}

\begin{description}

\item[{\tt options}] Display the present settings.

\item[{\tt options  itl1=50}] Allows 50 iterations in a {\tt dc} or {\tt
op} analysis.

\end{description}
%------------------------------------------------------------------------
%------------------------------------------------------------------------
