%===============================================================================
\section{Introduction}\label{s:ex_intro}
%===============================================================================

This report is intended to serve as a companion document to the User
Documentation of {\kinsol} \cite{kinsol_ug}.  It provides details, with
listings, on the example programs supplied with the {\kinsol} distribution
package.

The {\kinsol} distribution contains examples of the following types: serial
{\CC} examples, parallel {\CC} examples, and an OpenMP example.
%%
With the exception of ''demo''-type example files, the names of all the examples
distributed with {\sundials} are of the form
\verb![slv][PbName]_[strat]_[ls]_[prec]_[p]!, where
\begin{description}
\item [{[slv]}] identifies the solver (for {\kinsol} examples this is \id{kin},
  while for {\fkinsol} examples, this is \id{fkin});
\item [{[PbName]}] identifies the problem;
\item [{[strat]}] identifies the strategy (absent if ``none'' or ``linesearch'');
\item [{[ls]}] identifies the linear solver module used;
\item [{[prec]}] indicates the {\kinsol} preconditioner module used
  (only if applicable, for examples using a Krylov linear solver
  and the {\kinbbdpre} module, this will be \id{bbd});
\item [{[p]}] indicates an example using the parallel vector module {\nvecp}.
\end{description}

\vspace{0.2in}\noindent
The following lists summarize all examples distributed with {\kinsol}.

\vspace{0.2in}\noindent
Supplied in the {\em srcdir}\id{/examples/kinsol/serial} directory are the
following serial examples (using the {\nvecs} module):

\begin{itemize}
\item \id{kinRoberts\_fp}
  solves the backward Euler time step for a three-species chemical kinetics
  system, using the fixed point strategy.

\item \id{kinFerTron\_dns}
  solves the Ferraris-Tronconi problem.
  \newline
  This program solves the problem with the {\sunlinsoldense} linear solver
  and uses different combinations of globalization and Jacobian
  update strategies with different initial guesses.
\item \id{kinFerTron\_klu}
  solves the same problem as in \id{kinFerTron\_dns}, but uses the
  sparse direct solver KLU via the {\sunlinsolklu} module.

\item \id{kinRoboKin\_dns}
  solves a nonlinear system from robot kinematics.
  \newline
  This program solves the problem with the {\sunlinsoldense} linear solver
  and a user-supplied Jacobian routine.
\item \id{kinRoboKin\_slu}
  is the same as \id{kinRoboKin\_dns} but uses the SuperLUMT sparse direct
  linear solver via the {\sunlinsolslumt} module.

\item \id{kinLaplace\_bnd}
  solves a simple 2-D elliptic PDE on a unit square.
 \newline
  This program solves the problem with the {\sunlinsolband} linear solver.
\item \id{kinLaplace\_picard\_bnd}
  is the same as \id{kinLaplace\_bnd} but uses the Picard strategy.

\item \id{kinFoodWeb\_kry}
  solves a food web model.
  \newline
  This is a nonlinear system that arises from a system of partial
  differential equations describing a six-species food web population
  model, with predator-prey interaction and diffusion on the unit
  square in two dimensions.
  This program solves the problem with the {\sunlinsolspgmr} linear
  solver module and a user-supplied preconditioner. The preconditioner is a
  block-diagonal matrix based on the partial derivatives of the
  interaction terms only.
\item \id{kinKrylovDemo\_ls}
  solves the same problem as \id{kinFoodWeb\_kry}, but with three Krylov
  linear solvers: {\sunlinsolspgmr}, {\sunlinsolspbcgs}, and {\sunlinsolsptfqmr}.
\end{itemize}

\vspace{0.2in}\noindent
Supplied in the {\em srcdir}\id{/examples/kinsol/parallel} directory are
the following parallel examples (using the {\nvecp} module):
\begin{itemize}
\item \id{kinFoodWeb\_kry\_p}
  is a parallel implementation of \id{kinFoodWeb\_kry}.
\item \id{kinFoodWeb\_kry\_bbd\_p}
  solves the same problem as \id{kinFoodWeb\_kry\_p}, with a block-diagonal matrix
  with banded blocks as a preconditioner, generated by difference quotients,
  using the {\kinbbdpre} module.
\end{itemize}

%% \vspace{0.2in}\noindent
%% As part of the {\fkinsol} module, in the directories
%% {\em srcdir}\id{/examples/kinsol/fcmix\_serial} and
%% {\em srcdir}\id{/examples/kinsol/fcmix\_parallel}, respectively, are the
%% following examples for the {\F}-{\CC} interface:
%% \begin{itemize}
%% \item \id{fkinDiagon\_kry}
%%   is a serial example, which solves a nonlinear system of the form
%%   $u_i^2 = i^2$ using an approximate diagonal preconditioner.
%% \item \id{fkinDiagon\_kry\_p}
%%   is a parallel implementation of \id{fkinDiagon\_kry}.
%% \end{itemize}

\vspace{0.2in}\noindent
Supplied in directory {\em srcdir}\id{/examples/kinsol/C\_openmp}
is an example using the OpenMP NVECTOR module.
\id{kin\_FoodWeb\_kry\_omp} solves the same problem as
\id{kin\_FoodWeb\_kry} but uses the OpenMP module.

\vspace{0.2in}\noindent
Supplied in directory {\em srcdir}\id{/examples/kinsol/CXX\_parallel}
is an example using the {\nvecp} module.
\id{kin\_heat2D\_nonlin\_p} solves a steady-state 2D heat
equation with an additional nonlinear term.
This problem is solved via fixed point iteration with
Anderson acceleration. This example highlights the availability
of various orthogonalization methods for use within Anderson
acceleration.

\vspace{0.2in}\noindent
Supplied in directory {\em srcdir}\id{/examples/kinsol/CXX\_parhyp}
are examples using the {\nvecp} module and incorporating use
of {\hypre} preconditioners and solvers.
These example problems are solved via fixed point iteration with
Anderson acceleration. They highlight the availability
of various orthogonalization methods for use within
Anderson acceleration.
\begin{itemize}
\item \id{kin\_heat2D\_nonlin\_hypre\_pfmg}
  solves the same problem as \id{kin\_heat2D\_nonlin\_p}
  but with a different fixed point iteration setup requiring
  a linear solve that uses {\hypre}'s PFMG preconditioner.
\item \id{kin\_bratu2D\_hypre\_pfmg}
  solves a 2D Bratu equation \cite{Frank-Kam:55} requiring a linear solve
  that uses {\hypre}'s PFMG preconditioner.
\end{itemize}


\vspace{0.2in}\noindent
In the following sections, we give detailed descriptions of some (but
not all) of these examples.  We also give our output files for
each of these examples, but users should be cautioned that their
results may differ slightly from these.  Differences in solution
values may differ within the tolerances, and differences in cumulative
counters, such as numbers of Newton iterations, may differ
from one machine environment to another by as much as 10\% to 20\%.

In the descriptions below, we make frequent references to the {\kinsol}
User Document \cite{kinsol_ug}.  All citations to specific sections
(e.g. \S\ref{s:types}) are references to parts of that User Document, unless
explicitly stated otherwise.

\vspace{0.2in}\noindent {\bf Note}.
The examples in the {\kinsol} distribution are written in such a way as
to compile and run for any combination of configuration options used during
the installation of {\sundials} (see Appendix \ref{c:install} in the User Guide).
As a consequence, they contain portions of code that will not be typically present in a
user program. For example, all {\CC} example programs make use of the
variables \id{SUNDIALS\_EXTENDED\_PRECISION} and \id{SUNDIALS\_DOUBLE\_PRECISION}
to test if the solver libraries were built in extended or double precision,
and use the appropriate conversion specifiers in \id{printf} functions.
