
\chapter{Advanced Options}

This section discusses options and routines that apply to most TAO
solvers and problem classes.  In particular, we focus on
linear solvers, convergence tests, and line searches.

\section{Linear Solvers}\label{sec:TaoLinearSolvers}
One of the most computationally intensive phases of many optimization
algorithms involves the solution of linear systems of equations.  
The performance of the linear solver may be critical to an efficient 
computation of the solution.  Since linear equation solvers often have 
a wide variety of options associated with them, TAO allows the user to 
access the linear solver with the
\findex{TaoGetKSP()}
\begin{verbatim}
   TaoGetKSP(Tao, KSP *);
\end{verbatim}
command. 
With access to the KSP object, users can customize it for their application
to achieve improved performance. Additional details on the KSP options in
PETSc can be found in the PETSc users manual \cite{petsc-user-ref}.



\section{Monitors}
By default the TAO solvers run silently without displaying information
about the iterations. The user can initiate monitoring with the
command \findex{TaoSetMonitor()} 
\begin{verbatim}
   TaoSetMonitor(Tao,
                     PetscErrorCode (*mon)(Tao,void*),
                     void*);
\end{verbatim}
\noindent
The routine {\tt mon} indicates a user-defined monitoring routine,
and {\tt void*} denotes an optional user-defined context for private 
data for the monitor routine.

The routine set by {\tt TaoSetMonitor()} is called once during each
iteration of the optimization solver.  Hence, the user can employ this 
routine for any application-specific computations that should be done 
after the solution update. 

% This linear solver object has a method
% that allows the user to adjust convergence tolerances.
% Alternatively, the
% specific data structures of the linear solver can be accessed and
% modified
% directly.




\section{Convergence Tests}
\label{sec:Taoconvergence}

Convergence of a solver can be defined in many ways.
The methods TAO uses by default are mentioned in 
Section \ref{sec:customize}.
These methods include absolute and relative convergence tolerances as well
as a maximum number of iterations of function evaluations.
If these choices are not sufficient, 
the user can specify a customized test\sindex{convergence tests}. 

Users can set their own customized convergence tests of the form
\begin{verbatim}
   PetscErrorCode  conv(Tao, void*);
\end{verbatim}
\noindent
The second argument is a pointer to a structure defined by the user.
Within this routine, the solver
can be queried for the solution vector, gradient vector,
or other statistic at the current iteration through routines such as
{\tt TaoGetSolutionStatus()} and  {\tt TaoGetTolerances()}.

To use this convergence test within a TAO solver, one uses
the command \findex{TaoSetConvergenceTest()}
\begin{verbatim}
   TaoSetConvergenceTest(Tao,
                     PetscErrorCode (*conv)(Tao,void*),
                     void*);
\end{verbatim}
\noindent
The second argument of this command is the convergence routine, and the
final argument of the convergence test routine denotes an optional 
user-defined context for private data.  
The convergence routine receives the TAO solver and this private data
structure. 
The termination flag can be set by using the routine
\begin{verbatim}
   TaoSetConvergedReason(Tao, TaoConvergedReason);
\end{verbatim}
\noindent



\section{Line Searches} \sindex{line search}
\label{sec:TaoLineSearch}

By using the command line option  {\tt -tao\_ls\_type}.  
Available line searches 
include Mor\'{e}-Thuente \cite{more:92}, Armijo, gpcg, and unit.

The line search routines involve several parameters, which are set
to defaults that are reasonable for many applications.  The user
can override the defaults by using the following options
\begin{itemize}
\item {\tt -tao\_ls\_maxfev <max>}
\item {\tt -tao\_ls\_stepmin <min>}
\item {\tt -tao\_ls\_stepmax <max>}
\item {\tt -tao\_ls\_ftol <ftol>}
\item {\tt -tao\_ls\_gtol <gtol>}
\item {\tt -tao\_ls\_rtol <rtol>}
\end{itemize}

One should run a TAO program with the option 
{\tt -help}
for details.  Users may write their own customized line search codes
by modeling them after one of the defaults provided.

