\chapter{Getting Started}
\label{chapter:intro_tao}

TAO can be used on a personal
computer with a single processor or within a parallel environment.  
Its basic usage involves only a few commands, but fully 
understanding its usage requires time.
Application programmers can easily begin to use TAO by working with 
the examples provided and then gradually learn more details according to
their needs.  The current version of TAO and the most recent help 
concerning installation and usage can be found at  
\url{http://www.mcs.anl.gov/tao}.

See the PETSc users manual and \url{http://www.mcs.anl.gov/petsc} for how to install and start using PETSc/TAO.

\section{Writing Application Codes with TAO}

Examples throughout the library demonstrate the software usage and
can serve as templates for developing custom applications.  We suggest
that new TAO users examine programs in
\begin{verbatim}
   ${PETSC_DIR}/src/tao/<unconstrained,bound,..>/examples/tutorials.
\end{verbatim} 
The HTML version of the manual pages located at
\begin{verbatim}
   ${PETSC_DIR}/docs/manpages/index.html
\end{verbatim} % To fool the coloring algorithm $
\noindent
and
\begin{verbatim}
   http://www.mcs.anl.gov/petsc/documentation/index.html
\end{verbatim}
\noindent
provides indices (organized by both routine names and concepts) to the
tutorial examples.

We suggest the following procedure for writing a new application
program using TAO:

\begin{enumerate}
\item Install PETSc/TAO according to the instructions in
  \url{http://www.mcs.anl.gov/petsc/documentation/installation.html}.
\item Copy an example and makefile from the directories
\begin{verbatim}
   ${PETSC_DIR}/src/tao/<unconstrained,bound,..>/examples/tutorials.
\end{verbatim} 
  compile the example, and run the program. 
\item Select the example program matching the application most
  closely, and use it as a starting point for developing a customized
  code.
\end{enumerate}

\section{A Simple TAO Example}
\label{sec:simple}

To help the user start using TAO immediately, we introduce here a simple
uniprocessor example. Please read Section~\ref{chapter:tao_solver} for a 
more in-depth discussion on using the TAO solvers.
The code presented in Figure~\ref{fig:example1} minimizes the
extended Rosenbrock function $f: \Re^n \to \Re$ defined by
\[
 f(x) = 
 \sum_{i=0}^{m-1} \left( \alpha(x_{2i+1}-x_{2i}^2)^2 + (1-x_{2i})^2 \right),
\]
where $n = 2m$ is the number of variables.  Note that while we use the C 
language to introduce the TAO software, the package is fully usable from 
C++ and Fortran77/90.  Section~\ref{chapter:fortran} discusses additional 
issues concerning Fortran usage.

\afterpage{
\begin{figure}[H]
  {\footnotesize \verbatiminput{rosenbrock1.c}}
\caption{Example of Uniprocessor TAO Code\label{fig:example1}}
\end{figure}
}


The code in Figure~\ref{fig:example1} contains many of the components
needed to write most TAO programs and thus is illustrative of the
features present in complex optimization problems.  Note that for
display purposes we have omitted some nonessential lines of code as well as the
(essential) code required for the routine \texttt{FormFunctionGradient},
which evaluates the function and gradient, and the code for
\texttt{FormHessian}, which evaluates the Hessian matrix for Rosenbrock's
function. The complete code is available in \url{$TAO\_DIR/src/unconstrained/examples/tutorials/rosenbrock1.c}. %$
The following sections annotates the lines of code in
Figure~\ref{fig:example1}.

\section{Include Files}

The include file for TAO should be used via the statement
\begin{verbatim}
   #include <petsctao.h>
\end{verbatim}
\noindent
The required lower-level include files are automatically included
within this high-level file.

\section{TAO Solvers}

Many TAO applications will follow an ordered set of procedures for 
solving an optimization problem:
The user creates a \texttt{Tao} context and selects a default algorithm. 
Call-back routines as well as vector (\texttt{Vec}) and matrix (\texttt{Mat}) 
data structures are then set.  These call-back routines will be used for 
evaluating the objective function, gradient, and perhaps the Hessian 
matrix.  The user then invokes TAO to solve the optimization problem and 
finally destroys
the \texttt{Tao} context. A list of the necessary functions for 
performing these steps
using TAO are shown in Figure \ref{fig:tao_commands}.  Details of these commands are presented in
Chapter~\ref{chapter:tao_solver}.

\findex{TaoCreate()} \findex{TaoSetObjectiveAndGradientRoutine()}
\findex{TaoSetRoutine()} \findex{TaoSolve()}
\findex{TaoDestroy()} \findex{TaoSetInitialVector()}
\begin{figure}[H]
\begin{verbatim}
   TaoCreate(MPI_Comm comm, Tao *tao); 
   TaoSetType(Tao tao, TaoType type);
   TaoSetInitialVector(Tao tao, Vec x);
   TaoSetObjectiveAndGradientRoutine(Tao tao, 
        PetscErrorCode (*FormFGradient)(Tao,Vec,PetscReal*,Vec,void*), 
        void *user);
   TaoSetHessianRoutine(Tao tao, Mat H, Mat Hpre,
        PetscErrorCode (*FormHessian)(Tao,Vec,Mat,Mat,
        void*), void *user);
   TaoSolve(Tao tao);
   TaoDestroy(Tao tao);
\end{verbatim}
\caption{Commands for Solving an Unconstrained Optimization Problem
\label{fig:tao_commands}}
\end{figure}

Note that the solver algorithm selected through the function 
\texttt{TaoSetType()} can be overridden
at runtime by using an options database.  Through this
database, the user not only can select a minimization method (e.g.,
limited-memory variable metric, conjugate gradient, Newton with line
search or trust region) but also can prescribe the convergence
tolerance, set various monitoring routines, set iterative methods
and preconditions for solving the linear systems, and so forth.  See 
Chapter~\ref{chapter:tao_solver} for more information on the 
solver methods available in TAO.

\section{Function Evaluations}

Users of TAO are required to provide routines that perform function
evaluations. Depending on the solver chosen, they may also have to
write routines that evaluate the gradient vector and Hessian matrix.

\section{Programming with PETSc}
\label{sec:tao_programming}
TAO relies heavily on PETSc not only for its vectors, matrices, and linear
solvers but also for its programming utilities such as command line option 
handling, error handling, and compiling system.  We provide here a quick 
overview of some of these PETSc features.  Please refer to the PETSc 
manual \cite{petsc-user-ref} for a more in-depth
discussion of PETSc.

\subsection*{Vectors}

In the example in Figure \ref{fig:example1}, the vector data structure
(\texttt{Vec}) is used to store the solution and gradient for the TAO
unconstrained minimization solvers.  A new parallel or sequential
vector \texttt{x} of global dimension \texttt{M} is created with the
command 
\begin{verbatim}
   info = VecCreate(MPI_Comm comm,int m,int M,Vec *x);
\end{verbatim}
\noindent
where \texttt{comm} denotes the MPI communicator. The type of storage
for the vector may be set with calls either to \texttt{VecSetType()}
or to \texttt{VecSetFromOptions()}.  Additional vectors of the same type
can be formed with 
\begin{verbatim}
   info = VecDuplicate(Vec old,Vec *new);
\end{verbatim}
\noindent
The commands
\begin{verbatim}
   info = VecSet(Vec X,PetscScalar value);
   info = VecSetValues(Vec x,int n,int *indices,
                       Scalar *values,INSERT_VALUES);
\end{verbatim}
\noindent
respectively set all the components of a vector to a particular scalar
value and assign a different value to each component.  More detailed
information about PETSc vectors, including their basic operations,
scattering/gathering, index sets, and distributed arrays, may be found
in the PETSc users manual \cite{petsc-user-ref}.

\subsection*{Matrices}

Usage of matrices and vectors is similar. \sindex{matrix} 
The user can create a new parallel or sequential matrix \texttt{H} with 
\texttt{M} global rows and \texttt{N} global columns, with the routines

\begin{verbatim}
   ierr = MatCreate(MPI_Comm comm,Mat *H);
   ierr = MatSetSizes(H,PETSC_DECIDE,PETSC_DECIDE,M,N);
\end{verbatim}
\noindent
where the matrix format can be specified at runtime.  The user could
alternatively specify each processes's number of local rows and columns
using \texttt{m} and \texttt{n} instead of \texttt{PETSC\_DECIDE}.  
\texttt{H} can then be used to store
the Hessian matrix, as indicated by the call to
\texttt{TaoSetHessianMat()}.  Matrix entries can be set with the
command
\begin{verbatim}
   ierr = MatSetValues(Mat H,PetscInt m,PetscInt *im, PetscInt n,
                       PetscInt *in, PetscScalar *values,INSERT_VALUES);
\end{verbatim}
\noindent
After %\findex{MatSetValues()} 
all elements have been inserted into the
matrix, it must be processed with the pair of commands

\begin{verbatim}
   ierr = MatAssemblyBegin(Mat H,MAT_FINAL_ASSEMBLY);
   ierr = MatAssemblyEnd(Mat H,MAT_FINAL_ASSEMBLY);
\end{verbatim}
\noindent
The PETSc users manual \cite{petsc-user-ref} discusses
various matrix formats as
well as the details of some basic matrix manipulation routines.


\subsection*{The Options Database}
\label{sec:options}
A TAO application can access the command line options presented at
runtime through the PETSc options database. This database gives the application
author the ability to set and change application parameters without
the need to recompile the application. For example, 
an application may have a grid discretization parameter \texttt{nx}
that can be set with the command line option \texttt{-nx <integer>}.
The application can read this option with the following line of code:
\begin{verbatim}
   PetscOptionsGetInt(NULL,NULL, "-nx", &nx, &flg);
\end{verbatim}
\noindent
If the command line option is present, the variable \texttt{nx} is set
accordingly; otherwise, \texttt{nx} remains unchanged. A complete
description of the options database may be found in the PETSc users
manual \cite{petsc-user-ref}.

\subsection*{Error Checking}

All TAO commands begin with the \texttt{Tao} prefix and return an
integer indicating whether an error has occurred during the call.  The
error code equals zero after the successful completion of the routine
and is set to a nonzero value if an error has been detected.  The
macro \texttt{CHKERRQ(ierr)} checks the value of \texttt{ierr} and calls an
error handler upon error detection.  \texttt{CHKERRQ()} should be used after
all subroutines to enable a complete error traceback.

In Figure \ref{fig:traceback} we indicate a traceback generated by
error detection within a sample program. The error occurred on line
2110 of the file \texttt{\$\{PETSC\_DIR\}/src/mat/inter\-face/mat\-rix.c} in the
routine \texttt{MatMult()} and was caused by failure to assemble the 
matrix in the Hessian evaluation routine.
The \texttt{MatMult()} routine was called from
the \texttt{TaoSolve\_NLS()} routine, which was in turn called on line 
154 of \texttt{TaoSolve()} from the \texttt{main()} routine 
in the program \texttt{rosenbrock1.c}.  The PETSc users
manual \cite{petsc-user-ref} provides further details
regarding error checking, including
information about error handling in Fortran.

\begin{figure}[htb]
{\footnotesize
\begin{verbatim}
> rosenbrock1 -tao_type nls
[0]PETSC ERROR: --------------------- Error Message ------------------------------------
[0]PETSC ERROR: Object is in wrong state!
[0]PETSC ERROR: Not for unassembled matrix!
[0]PETSC ERROR: ------------------------------------------------------------------------
[0]PETSC ERROR: Petsc Development HG revision: b95ffff514b66a703d96e6ae8e78ea266ad2ca19
[0]PETSC ERROR: See docs/changes/index.html for recent updates.
[0]PETSC ERROR: See docs/faq.html for hints about trouble shooting.
[0]PETSC ERROR: See docs/index.html for manual pages.
[0]PETSC ERROR: ------------------------------------------------------------------------
[0]PETSC ERROR: Libraries linked from petsc/arch-linux2-c-debug/lib
[0]PETSC ERROR: Configure run at Tue Jul 19 14:13:14 2011
[0]PETSC ERROR: Configure options --with-shared-libraries --with-dynamic-loading
[0]PETSC ERROR: ------------------------------------------------------------------------
[0]PETSC ERROR: MatMult() line 2110 in petsc/src/mat/interface/matrix.c
[0]PETSC ERROR: TaoSolve_NLS() line 291 in src/unconstrained/impls/nls/nls.c
[0]PETSC ERROR: TaoSolve() line 154 in src/interface/tao.c
[0]PETSC ERROR: main() line 94 in src/unconstrained/examples/tutorials/rosenbrock1.c
application called MPI_Abort(MPI_COMM_WORLD, 73) - process 0
\end{verbatim}
}
\caption{Example of Error Traceback}
\label{fig:traceback}
\end{figure}

When running the debugging version of the TAO software (PETSc configured 
with the (default) \texttt{--with-debugging} option), checking is performed for 
memory corruption
(writing outside of array bounds, etc). The macros \texttt{CHKMEMQ} and
\texttt{CHKMEMA} can be called anywhere in the code and, when used together 
with the command line option \texttt{-malloc\_debug}, check the current
status of the memory for corruption.  By putting several (or many) of
these macros into an application code, one can usually track
down the code segment where corruption has occurred.

\subsection*{Parallel Programming}

Since TAO uses the message-passing model for parallel programming and
employs MPI for all interprocessor communication, the user is free to
employ MPI routines as needed throughout an application code.
By default, however, the user is shielded from many of the details of
message passing within TAO, since these are hidden within parallel
objects, such as vectors, matrices, and solvers.  In addition, TAO
users can interface to external tools, such as the generalized vector
scatters/gathers and distributed arrays within PETSc, for assistance in
managing parallel data.

%\sindex{collective operations} 
The user must specify a communicator
upon creation of any PETSc or TAO object (such as a vector, matrix, or 
solver)
to indicate the processors over which the object is to be distributed. 
For example, some commands for matrix, vector, and solver creation
are as follows.
\begin{verbatim}
   ierr = MatCreate(MPI_Comm comm,Mat *H);
   ierr = VecCreate(MPI_Comm comm,Vec *x);
   ierr = TaoCreate(MPI_Comm comm,Tao *tao); 
\end{verbatim}
\noindent
In most cases, the value for \texttt{comm} will be either 
\texttt{PETSC\_COMM\_SELF} for single-process objects or 
\texttt{PETSC\_COMM\_WORLD} for objects distributed over all processors.
The creation routines are collective over all processors in the
communicator; thus, all processors in the communicator {\em must} call
the creation routine.  In addition, if a sequence of collective
routines is being used, the routines {\em must} be called in the same
order on each processor.

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