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

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

The {\cvode} distribution contains examples of six types: serial
{\CC} examples, parallel {\CC} examples, serial and parallel {\F}
examples, an OpenMP example, and a {\hypre} 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]_[ls]_[prec]_[p]!,
where
\begin{description}
\item [{[slv]}] identifies the solver (for {\cvode} examples this is \id{cv},
  while for {\fcvode} examples, this is \id{fcv});
\item [{[PbName]}] identifies the problem;
\item [{[ls]}] identifies the linear solver module used (for examples using
  fixed-point iteration for the nonlinear system solver, \id{non} specifies
  that no linear solver was used);
\item [{[prec]}] indicates the {\cvode} preconditioner module used, \id{bp} for {\cvbandpre}
  or \id{bbd} for {\cvbbdpre}
  (only if applicable, for examples using a Krylov linear solver);
\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 {\cvode}.

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

\begin{itemize}
\item \id{cvRoberts\_dns}
  solves a chemical kinetics problem consisting of three rate equations.
  \newline
  This program solves the problem with the BDF method and Newton
  iteration, with the {\sunlinsoldense} linear solver, {\cvls}
  interface, and a user-supplied Jacobian routine.  It also uses the
  rootfinding feature of {\cvode}.
\item \id{cvRoberts\_dns\_constraints}
  is the same as \id{cvRoberts\_dns} but imposes the constraint
  $u \geq 0.0$ for all components.
\item \id{cvRoberts\_dnsL}
  is the same as \id{cvRoberts\_dns} but uses the LAPACK
  implementation of {\sunlinsollapdense}.
\item \id{cvRoberts\_dns\_uw}
  is the same as \id{cvRoberts\_dns} but demonstrates the user-supplied error
  weight function feature of {\cvode}.
\item \id{cvRoberts\_klu}
  is the same as \id{cvRoberts\_dns} but uses the {\klu} sparse direct
  linear solver, {\sunlinsolklu}.
\item \id{cvRoberts\_sps}
  is the same as \id{cvRoberts\_dns} but uses the {\superlumt} sparse
  direct linear solver, {\sunlinsolslumt} (with one thread).
\item \id{cvAdvDiff\_bnd}
  solves the semi-discrete form of an advection-diffusion equation in 2-D.
  \newline
  This program solves the problem with the BDF method and Newton
  iteration, with the {\sunlinsolband} linear solver, {\cvls}
  interface, and a user-supplied Jacobian routine.
\item \id{cvAdvDiff\_bndL}
  is the same as \id{cvAdvDiff\_bnd} but uses the LAPACK
  implementation of {\sunlinsollapband}.
\item \id{cvDiurnal\_kry}
  solves the semi-discrete form of a two-species diurnal kinetics
  advection-diffusion PDE system in 2-D.
  \newline
  The problem is solved with the BDF/GMRES method (i.e.
  using the {\sunlinsolspgmr} linear solver and {\cvls} interface)
  and the block-diagonal part of the Newton matrix as a left
  preconditioner. A copy of the block-diagonal part of the Jacobian is
  saved and conditionally reused within the preconditioner setup routine.
\item \id{cvDiurnal\_kry\_bp}
  solves the same problem as \id{cvDiurnal\_kry}, with the BDF/GMRES method
  and a banded preconditioner, generated by difference quotients,
  using the module {\cvbandpre}.
  \newline
  The problem is solved twice: with preconditioning on the left,
  then on the right.
\item \id{cvDirectDemo\_ls}
  is a demonstration program for {\cvode} with direct linear solvers.
  \newline
  Two separate problems are solved using both the Adams and BDF linear
  multistep methods in combination with fixed-point and Newton
  iterations.
  \newline
  The first problem is the Van der Pol oscillator for which
  the Newton iteration cases use the following types of Jacobian approximations:
  (1) dense, user-supplied, (2) dense, difference-quotient approximation,
  (3) diagonal, with difference-quotient approximation. The second
  problem is a linear ODE with a
  banded lower triangular matrix derived from a 2-D advection PDE. In this
  case, the Newton iteration cases use the following types of Jacobian
  approximation: (1) banded, user-supplied, (2) banded, difference-quotient
  approximation, (3) diagonal, difference-quotient approximation.
\item \id{cvKrylovDemo\_ls}
  solves the same problem as \id{cvDiurnal\_kry}, with the BDF method, but with
  three Krylov linear solvers: {\sunlinsolspgmr}, {\sunlinsolspbcgs},
  and {\sunlinsolsptfqmr}.
\item \id{cvKrylovDemo\_prec}
  is a demonstration program with the GMRES linear solver.
  \newline
  This program solves a stiff ODE system that arises from a system
  of partial differential equations.  The PDE system is a six-species
  food web population model, with predator-prey interaction and diffusion
  on the unit square in two dimensions.
  \newline
  The ODE system is solved using Newton iteration, the
  {\sunlinsolspgmr} linear solver (scaled preconditioned GMRES), and
  {\cvls} interface.
  \newline
  The preconditioner matrix used is the product of two matrices:
  (1) a matrix, only defined implicitly, based on a fixed number of
  Gauss-Seidel iterations using the diffusion terms only; and
  (2) a block-diagonal matrix based on the partial derivatives of the
  interaction terms only, using block-grouping.
  \newline
  Four different runs are made for this problem.
  The product preconditoner is applied on the left and on the right.
  In each case, both the modified and classical Gram-Schmidt options
  are tested.
\item \id{cvHeat2D\_klu} solves a discretized 2D heat equation using
  the {\klu} sparse-direct linear solver, {\sunlinsolklu}.
\end{itemize}

\vspace{0.2in}\noindent Supplied in the
{\em srcdir}\id{/examples/cvode/parallel} directory are the following
four parallel examples (using the {\nvecp} module):
\begin{itemize}
\item \id{cvAdvDiff\_non\_p} solves the semi-discrete form of a 1-D
  advection-diffusion equation.
  \newline
  This program solves the problem with the option for nonstiff
  systems, i.e. Adams method and fixed-point iteration.
\item \id{cvAdvDiff\_diag\_p}
  solves the same problem as \id{cvAdvDiff\_non\_p}, with the Adams method,
  but with Newton iteration and the \id{CVDiag} linear solver.
\item \id{cvDiurnal\_kry\_p}
  is a parallel implementation of \id{cvDiurnal\_kry}.
\item \id{cvDiurnal\_kry\_bbd\_p}
  solves the same problem as \id{cvDiurnal\_kry\_p}, with BDF and the GMRES linear
  solver, using a block-diagonal matrix with banded blocks as a preconditioner,
  generated by difference quotients, using the module {\cvbbdpre}.
\end{itemize}

\vspace{0.2in}\noindent Supplied in the
{\em srcdir}\id{/examples/cvode/C\_openmp} directory is
\id{cvAdvDiff\_bnd\_omp}, an example which solves the same problem as
\id{cvAdvDiff\_bnd} but with the OpenMP {\nvector} module.

\vspace{0.2in}\noindent Supplied in the
{\em srcdir}\id{/examples/cvode/parhyp} directory is an example
\id{cvAdvDiff\_non\_ph}, which solves the same problem as
\id{cvAdvDiff\_non\_p} but with {\hypre} vectors instead of
{\sundials} parallel vectors.

\vspace{0.2in}\noindent
As part of the {\fcvode} module, in the directories
{\em srcdir}\id{/examples/cvode/fcmix\_serial} and
{\em srcdir}\id{/examples/cvode/fcmix\_parallel}, are the following examples for
the {\F}-{\CC} interface.  The first five of these are serial, while
the last three are parallel.
\begin{itemize}
\item \id{fcvRoberts\_dns} is a serial chemical kinetics example (\id{BDF}/{\sunlinsoldense})
  with rootfinding.
\item \id{fcvRoberts\_dns\_constraints} is the same as \id{fcvRoberts\_dns} but
  but imposes the constraint $u \geq 0.0$ for all components.
\item \id{fcvRoberts\_dnsL} is the same as \id{fcvRoberts\_dns} but uses the Lapack
  implementation of {\sunlinsollapdense}.
\item \id{fcvAdvDiff\_bnd} is a serial advection-diffusion example (\id{BDF}/{\sunlinsolband}).
\item \id{fcvDiurnal\_kry} is a serial kinetics-transport example (\id{BDF}/{\sunlinsolspgmr}).
\item \id{fcvDiurnal\_kry\_bp} is the \id{fcvDiurnal\_kry} example with {\fcvbp}.
\item \id{fcvDiag\_non\_p} is a nonstiff parallel diagonal ODE example
  (\id{ADAMS}/\id{FIXEDPOINT}).
\item \id{fcvDiag\_kry\_p} is a stiff parallel diagonal ODE example (\id{BDF}/{\sunlinsolspgmr}).
\item \id{fcvDiag\_kry\_bbd\_p} is the same as the \id{fcvDiag\_kry\_p} example
       but using the {\fcvbbd} module.
\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 steps or Newton iterations, may differ
from one machine environment to another by as much as 10\% to 20\%.

The final section of this report describes a set of tests done with the
parallel version of CVODE, using a problem based on the
\id{cvDiurnal\_kry}/\id{cvDiurnal\_kry\_p} example.

In the descriptions below, we make frequent references to the {\cvode}
User Document \cite{cvode_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 {\cvode} distribution are written in such a way as
to compile and run for any combination of configuration options 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.
