\section{{\protect \bf Aztec}: Unadvertised use of Aztec Options\label{unadvertised options}}

The integer array {\it options\/} of length {\sf AZ\_OPTIONS\_SIZE} is set by 
the user. It is used (but not altered) by the function {\sf AZ\_solve} and 
{\sf AZ\_iterate} to choose between iterative solvers, preconditioners, etc.  
Default values for this array (as well as for {\it params}) are set by invoking 
{\sf AZ\_defaults()}.
Below we discuss some options not described in the standard \Az{} manual. 

\vspace{2em}
{\flushleft{\bf Specifications} \hrulefill}
\nopagebreak \\[0.5em]
%
\optionbox{options[{\sf AZ\_solver}]}{Specifies solution
  algorithm. DEFAULT: \sf AZ\_gmres.}
\choicebox{AZ\_GMRESR}{A recursive GMRES algorithm similar to flexible GMRES
                       in that it allows preconditioners which change at 
                       each iteration to be used. Note: recursive GMRES requires
                       approximately twice the storage as GMRES.} 
\choicebox{AZ\_fixed\_pt}{This is a fixed point iterative solver. For the most
                         part, this solver is used for debugging purposes.
                         It occasionally might have some use when a very good
                         preconditioner is supplied (e.g. multigrid). It can
                         also be used to perform one \Az{} preconditioning
                         iteration (set {\it options[ {\sf AZ\_max\_iter} ]} = 1
                         and {\it options[{\sf AZ\_init\_guess}]} = 
                         {\sf AZ\_ZERO}).  }
                       
\choicebox{AZ\_symmlq}{Currently not compiled. This is a SYMMLQ solver that is
                       suitable for systems that are symmetric indefinite
                       systems.} 
%
\optionbox{options[{\sf AZ\_scaling}]}{Specifies scaling algorithm.
  The entire matrix is scaled (overwriting the old
  matrix). Additionally, the right hand side, the initial guess and
  the final computed solution are scaled if necessary. For 
  symmetric scaling, this transforms $ A x = b$ into
  $ S A S y = S b $ as opposed to $ S A x = S b $ when symmetric
  scaling is not used. NOTE: The residual within \Az{} is now 
  given by $ S (b - A x) $. Thus, residual printing and convergence
  checking are effected by scaling. {\bf However}, see {\sf AZ\_ignore\_scaling}
  for ways around this.  DEFAULT: \sf AZ\_none.}
%
\optionbox{options[{\sf AZ\_precond}]}{Specifies preconditioner.
  DEFAULT: \sf AZ\_none. \\[5pt] 1) Multigrid preconditioning can be done
  via the ML package. At present, there is no complete
  manual for ML. Please ask \Az{} authors for
  more information.\\[2pt] 2) Any Aztec solver can be used as a 
  preconditioner. Pick a solver to be used
  as a preconditioner via a second {\it options} array (e.g.
     {\it options2}) and perform:\\[5pt]
handle = AZ\_set\_solver\_parameters(params, \\
\phantom{handle = AZ\_set\_solver} 
options2,Amat,precond,scaling);\\
     options[AZ\_precond] = handle\\
}

\optionbox{options[{\sf AZ\_subdomain\_solve}]}{Specifies the solver
  to use on each subdomain when {\it options}[{\sf AZ\_precond}] is set
  to {\sf AZ\_dom\_decomp} DEFAULT: \sf AZ\_ilut.}
\choicebox{AZ\_bilu\_ifp}{Mike, I think it is okay to reference another
                          document. Could you also say something about 
                          the complex solves? Once again, a pointer
                          to another document is okay.}
\choicebox{handle}{Any Aztec solver can be used as a subdomain
                   solver. Pick a solver to be used on a subdomain via a 
                   second {\it options} array (e.g.  {\it options2}) and 
                   perform:\\[5pt]
handle = AZ\_set\_solver\_parameters(params, \\
\phantom{abfghijklmno} options2, Amat, precond, scaling); \\
     options[AZ\_subdomain\_solve] = handle
}

%
\optionbox{options[{\sf AZ\_conv}]}{Determines the residual expression used
  in convergence checks and printing.  DEFAULT: {\sf AZ\_r0}.
  The iterative solver terminates if the corresponding residual expression
  is less than {\it params}[{\sf AZ\_tol}]:}
\choicebox{AZ\_expected\_values}{$\|r\|_{Wmax} $
  where $\| \cdot\|_{Wmax} = \max_{i=1}^{n} (r_i/w_i)$, 
%= \max_{i=1}^n (r_i/w_i)$,
  $n$ is the total number of unknowns, $w$ is a weight
  vector with $w_i = \sum_{i=1}^n | a_{i,j} x_j |$ using
  for $x$ the initial guess supplied by the user.}
%
%
\optionbox{options[{\sf AZ\_keep\_kvecs}]}{When using the solver {\sf AZ\_cg}, this integer determines how many Krylov vectors are stored. Default: 0.}
%
%
\optionbox{options[{\sf AZ\_orth\_kvecs}]}{When set to {\sf AZ\_TRUE}, 
using the solver {\sf AZ\_cg}, 
and with {\it options[{\sf AZ\_keep\_kvecs}]} $> 0 $, conjugate gradient
will explicitly A-orthogonalize new Krylov vectors against kept Krylov
vectors. Default: {\sf AZ\_false}.}
%
%
\optionbox{options[{\sf AZ\_apply\_kvecs}]}{When set to {\sf AZ\_TRUE}
and using the solver {\sf AZ\_cg}, the initial guess will be improved 
using previously kept Krylov vectors (obtained by setting
{\it options[{\sf AZ\_keep\_info}]} to `1' and {\it 
options[{\sf AZ\_keep\_kvecs}] } $> 0 $ on a previous solve) before running 
the conjugate gradient algorithm. Default: {\sf AZ\_false}.}
%
%
\optionbox{options[{\sf AZ\_ignore\_scaling}]}
{When set to {\sf AZ\_TRUE} and when scaling is also requested, 
\Az{} performs scaling as usual, however, convergence and the 
printed residual correspond to the unscaled residual.
{\bf IMPORTANT NOTE:} When used in conjunction with multiple solves
of the same matrix, an identical scaling object must be passed
into {\sf AZ\_iterate()} each time: \\[2pt]
\phantom{hi} struct AZ\_SCALING $*$scaling;  \\
\phantom{hi} scaling = AZ\_scaling\_create(); \\
\phantom{hi} AZ\_iterate( ..., scaling);    \\
\phantom{hi} AZ\_iterate( ..., scaling);    \\
\phantom{hi} AZ\_scaling\_destroy(\&scaling);  
}
%
%
\optionbox{options[{\sf AZ\_check\_update\_size}]}{
When set to {\sf AZ\_TRUE}, convergence will be declared only if both
the convergence test set via {\it options[{\sf AZ\_conv}]} is satisfied
and the 
change in the solution at the current iteration, $k$ is small.
Specifically, \\
\phantom{hi}
  $ || \delta x ||_2 < $
{\it params [{\sf AZ\_update\_reduction}]} $ || x^{(k)} ||_2 $ \\
where \\
\phantom{hi}
$x^{(k)} = x^{(k-1)} + \delta x $. 
}
%
%
%
\subsection{\Az{} parameters\label{optionD}}

The double precision array {\it params\/} set by the user and normally of
length {\sf AZ\_PARAMS\_SIZE}. However, when a weight vector is needed for the
convergence check (i.e. {\it options}[{\sf AZ\_conv}] = {\sf AZ\_weighted}), it
is embedded in {\it params\/} whose length must now be {\sf AZ\_PARAMS\_SIZE} +
\# of elements updated on this processor.  In either case, the contents of {\it
  params\/} are used (but not altered) by the function {\sf AZ\_solve} to
control the behavior of the iterative methods.  The array elements are
specified as follows: \vspace{2em}
{\flushleft{\bf Specifications} \hrulefill} \nopagebreak \\[0.5em]
%
\optionbox{params[{\sf AZ\_update\_reduction}]}{See 
{\it options[{\sf AZ\_check\_update\_size}]}. }

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "az_ug_20"
%%% End:
