\chapter{Examples}

Many different examples are provided with \pastix{} librairy sources.

These examples are meant to be simple and documented to simplify user's
work when including \pastix{} in their softwares.

Examples are stored in \texttt{src/example/src/} and compiled with
\texttt{make examples}. The resulting binaries are stored in
\texttt{src/example/bin/} directory.

\section{Examples in \texttt{C}}

As \pastix{} is written in \texttt{C}, there are many examples in this
language.

\subsection{Parameters}
 
All this examples are sharing the same parameter option that can be
listed with \texttt{example/bin/simple} or any other example without
parameters or with \texttt{-h}.

\begin{verbatim}
Usage : ./example/bin/simple [option] 
	options : 
		 -rsa    [filename]          driver RSA (use Fortran) 
		 -chb    [filename]          driver CHB
		 -ccc    [filename]          driver CCC
		 -rcc    [filename]          driver RCC
		 -olaf   [filename]          driver OLAF
		 -peer   [filename]          driver PEER
		 -hb     [filename]          driver HB (double)
		 -3files [filename]          driver IJV 3files 
		 -mm     [filename]          driver Matrix Market
		 -ord    <scotch|metis>      select ordering library
		 -lap    <integer>           generate a laplacian of size <integer>
		 -incomp <integer> <integer> incomplete factorization, with the 
		                             given level of fill [1-5]
		                             and amalgamation [10-70]
		 -ooc    <integer>           Memory limit in Mo/percent depending 
		                             on compilation options
		 -kass   <integer>           kass, with the given amalgamation
		 -t      <integer>           define thread number
		 -v      <integer>           define verbose level (1,2 or 3)
		 -h                          print this help
\end{verbatim}

\subsection{\texttt{simple.c}}

The \texttt{simple.c} example is an example simply using \pastix{}
with no particular option.\\
It reads the matrix, check the matrix structure, set options depending
on the matrix (ie: \iparm{IPARM\_SYM}), run \pastix{} on the builded
system.\\
After that the returned solution is tested.

The compilation of the example generate \texttt{simple},
\texttt{ssimple}, \texttt{dsimple}, \texttt{csimple} and
\texttt{zsimple}, each one corresponding to one arithmetic.
\index{Multi-arithmetic}

This example is tested every day with our regression tests.

\subsection{\texttt{simple\_dist.c}}

This example is similar to \texttt{simple.c} example, except that it
uses the distributed interface.
It read and check the matrix, set the parameters, run preprocessing
steps.\\
After that it get solvers distribution, redistribute the matrix to
follow it and run the factorization and solve steps.

This example also produce five executables corresponding to the five
arithmetics.

This example is also tested with our daily runs.

%%\subsection{\texttt{simple\_param.c}}
%%
%%This example is similar to \texttt{simple.c}, except that it reads
%%\texttt{iparm.txt} and \texttt{dparm.txt}.
%%
%%\textcolor{red}{Euh mathieu, je pensais qu'il lisais iparm et dparm
%%  sur disque celui là, pourquoi il y a un get\_iparm et on ne lit pas
%%  les -iparm/-dparm avec le get\_options comme pour les autres ?}
%%
%%\textcolor{red}{Pourquoi les -ooc sont redéfinis dans get\_iparm ???}
%%
%%\textcolor{red}{  Je comprends pas bien...}

\subsection{\texttt{do\_not\_redispatch\_rhs.c}}

In this example the factorization is computed using user's matrix in
it's original distribution, then the right-hand-side member is built
in \pastix{} distribution.

To allow this kind of mixed usage, user has to set
\iparm{IPARM\_RHSD\_CHECK} to \texttt{API\_NO}.

\subsection{\texttt{step-by-step.c}}

This examples call each \pastix{} steps one after one. \texttt{nfact}
  - which is 2 in the code - factorisation are called, and, for each one,
  \texttt{nsolv} - 2 - solving steps are performed.

\subsection{\texttt{step-by-step\_dist.c}}

This example is similar to \texttt{step-by-step} one but calls are
performed with distributed matrices. Pre-processing is performed with
user's distribution, then the matrices are re-distributed in the
solver's distribution to perform several factorizations and resolutions.

\subsection{\texttt{reentrant.c}}

In this example, \pastix{} is called from several threads. This
example is here to check that the library can be called from any
number of threads, which could be problematic.

\subsection{\texttt{multi-comm.c}}

This example check the possibility to call \pastix{} in different
\texttt{MPI} communicators.

\subsection{\texttt{multi-comm-step.c}}

This example is similar to \texttt{multi-comm.c} but it also uses step
by step calls, as in \texttt{step-by-step.c}

\subsection{\texttt{schur.c}}

In this example, we build the \texttt{Schur} complement of the matrix.
The user provide a list of unknown corresponding to the \texttt{Schur}
complement, run the matrix factorization and then get the
\texttt{Schur} complement as a dense block array.

After that we can perform updown step on the non-schur part of the matrix.

\subsection{\texttt{isolate\_zeros.c}}

In this example, \pastix{} first isolate zeros diagonal terms at the
end of the matrix before factorizing the matrix.
 
\section{Examples in \texttt{Fortran}}

As many \pastix{} users are \texttt{Fortran} users, we provide some
examples using our fortran interface to \pastix{}


\subsection{Parameters}

All this examples are sharing the same parameter option that can be
listed with \texttt{example/bin/simple -h}.

All this examples - except the murge one - are sharing the same parameter option that can be
listed with \texttt{example/bin/fsimple} or any other example without
parameters or with \texttt{-h}.

\begin{verbatim}
 Usage : ./example/bin/fsimple [option] 
    options : 
      -rsa    [filename], default driver RSA (use Fortran) 
      -lap    <integer>           generate a laplacian of size <integer>
      -t      <integer>           define thread number
      -v      <integer>           verbose level (1, 2 or 3)
      -h                          print this help
\end{verbatim}

\subsection{\texttt{fsimple.f90}}

This example correspond to \texttt{simple.c} example, but it is
written in \texttt{Fortran}.

\subsection{\texttt{fstep-by-step.f90}}

This example is the \texttt{Fortran} version of
\texttt{step-by-step.c}

\subsection{\texttt{Murge-Fortran.f90}}

In this example we use \murge{} interface to solve a system in
\texttt{Fortran}.

The system correspond to a Laplacian.
