%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                  %
% Titre  : m_s.tex                 %
% Sujet  : Manuel de maintenance   %
%          du projet 'Scotch'      %
%          Structure generale      %
% Auteur : Francois Pellegrini     %
%                                  %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{General structure of the \libscotch\ library}
\label{sec-structure}

\subsection{Naming conventions}

All of the files of the \scotch\ project have been written using
strict coding conventions, to ease maintenance and further extension
by external contributors. Therefore, contributors are {\bf strongly}
invited to follow these coding conventions so as to ease the work of
their followers.

\subsubsection{Variables}

Variables are named by specialization, with prefixes and suffixes.

Common prefixes are:
\begin{itemize}
\item
act : active, wrt. source
\item
src : source, wrt. active
\item
tgt : target.
\item
coar : coarse, wrt. fine.
\item
fine : fine, wrt. coarse.
\item
mult : multinode, for coarsening.
\end{itemize}

Common radicals are:
\begin{itemize}
\item
vert : vertex.
\item
velo : vertex load.
\item
vnum : vertex number, used as index, for instance in {\tt vnumtab}).
\item
vlbl : vertex label (for interface).
\item
edge : edge.
\item
edlo : edge load.
\end{itemize}

Common suffices are:
\begin{itemize}
\item
{\tt nbr} : number of (instances of).
\item
{\tt num} : number of some instance of.
\item
{\tt val} : value of.
\item
{\tt sum} : sum of several values of.
\item
{\tt tab} : pointer to the first memory element of an array of, for
instance as returned by a {\tt mem\lbt Alloc} routine.
\item
{\tt tax} : (for ``{\it table access}'') pointer to the first element
of an array that is to be accessed by means of based indices. The
\libscotch\ library can accept data structures that come both from
FORTRAN, where array indices start at $1$, and C, where they start at
$0$. By accessing ``{\tt tax}'' arrays, where the {\tt tax} pointer is
equal to the {\tt tab} pointer minus the value of the indexing base,
this is completely transparent for coding, save for memory allocation
and freeing operations, which must operate on {\tt tab} pointers only.
\item
{\tt tnd} : pointer to the end of an array of (mostly used as a bound
in loops).
\item
{\tt ptr} : pointer to an instance of.
\end{itemize}

For instance, {\tt coarvertnum} is a variable that holds the number of
a coarse vertex, within some coarsening algorithm. It is also easy to
guess how to name a variable that holds a pointer to an active edge.

\subsubsection{Functions}

Routines that operate on data structures are named by specialization,
from the name of the structure type they apply to.

Common suffixes are:
\begin{itemize}
\item
{\tt Init} : initialization of a structure (object) passed as parameter.
\item
{\tt Free} : freeing of the external structures of the object, to save
space. The object may still be used after it is initialized again.
\item
{\tt Exit} : freeing of the internal structures of the object. The
object must not be passed to other routines after the {Exit} method
has been called.
\item
{\tt Copy} : make a fully operational, independent, copy of the object.
\item
{\tt Load} : load from stream.
\item
{\tt Save} : save to stream.
\item
{\tt View} : display internal structures and statistics, for debugging
purposes.
\item
{\tt Check} : check internal coherence, for debug.
\end{itemize}

\subsection{Structure of the library}

%\subsubsection{Modules}

All of the routines that comprise the \libscotch\ libraries are
grouped by the type of data structure onto which they apply and by
function, in an object-oriented manner. This organization is reflected
into the naming and contents of all of the source files.

The main modules of the \libscotch\ library are the following :
\begin{itemize}
\item
{\tt arch} : target architectures used by the static mapping methods.
\item
{\tt bgraph} : graph edge bipartitioning methods.
\item
{\tt graph} : basic graph handling methods.
\item
{\tt hgraph} : graph ordering methods. These are based on an extended
``halo'' graph structure, thus for the name.
\item
{\tt hmesh} : mesh ordering methods.
\item
{\tt kgraph} : k-way graph partitioning methods.
\item
{\tt library} : interface routines for the \libscotch\ library.
\item
{\tt mapping} : definition of the mapping structure.
\item
{\tt mesh} : basic mesh handling methods.
\item
{\tt order} : definition of the ordering structure.
\item
{\tt parser} : strategy parsing routines, based on a Lex-Yacc
parser.
\item
{\tt vgraph} : graph vertex bipartitioning methods.
\item
{\tt vmesh} : mesh node bipartitioning methods.
\end{itemize}

Each of the file names is prefixed by the name of the module, followed
by one or two words that describe the type of action performed by the
routines of the file.
For instance, in module {\tt bgraph} :
\begin{itemize}
\item
{\tt bgraph.h} is the header file that defines the {\tt bgraph}
structure,
\item
{\tt bgraph\_bipart\_fm.[ch]} are the files that contain the
Fiduccia-Mattheyses-like graph bipartitioning method,
\item
{\tt bgraph\_check.c} is the file that contains the consistency
checking routine for {\tt Bgraph} structures,
\end{itemize}
and so on. Every source file has a comments header briefly describing
the purpose of the routines it contains.

%This section lists the main structures used within \libscotch. Each of
%these is defined in a C header file of same name in the {\tt
%libscotch\_\lbt 4.x/\lbo src} directory. For instance, the {\tt Graph}
%structure is defined in file {\tt graph.h}, the {Vmesh} structure is
%defined in file {\tt vmesh.h}, and so on.
