inputs/dev/initialisation.tex

%%%%%%%%%%%%%%%%%%%
% XLiFE++ is an extended library of finite elements written in C++
%     Copyright (C) 2014  Lunéville, Eric; Kielbasiewicz, Nicolas; Lafranche, Yvon; Nguyen, Manh-Ha; Chambeyron, Colin
%
%     This program is free software: you can redistribute it and/or modify
%     it under the terms of the GNU General Public License as published by
%     the Free Software Foundation, either version 3 of the License, or
%     (at your option) any later version.
%     This program is distributed in the hope that it will be useful,
%     but WITHOUT ANY WARRANTY; without even the implied warranty of
%     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%     GNU General Public License for more details.
%     You should have received a copy of the GNU General Public License
%     along with this program.  If not, see <http://www.gnu.org/licenses/>.
%%%%%%%%%%%%%%%%%%%

\section{About the {\tt init} function}

Initialization is the aim of the {\lib init} library and more precisely the \emph{init.cpp} and \emph{init.hpp} files and the definition of the {\tt init} functions.

Each user program needing \xlifepp has to begin with a call to the {\cmd init} routinewith up to 4 key/value arguments:
\begin{description}
\item[{\param \_lang}] enum to set the language for print and log messages. Possible values are $en$, $fr$, or $de$. Default value is $en$.
\item[{\param \_verbose}] integer to set the verbose level. Default value is 1.
\item[{\param \_trackingMode}] boolean to set if in the log file, you have a backtrace of every call to a \xlifepp routine. Default value is false.
\item[{\param \_isLogged}] boolean to activate log. Default value is false.
\end{description}

Available languages are English, French and German, but \xlifepp is easily extendible for other languages.

\begin{lstlisting}[]{}
init(_lang=en)
\end{lstlisting}

What is the {\tt init} function doing ?

\begin{enumerate}
\item If the {\tt init} function was previously called, it stops, or does the following steps otherwise.
\item It builds the global {\class Environment} object to initializes dictionary and paths to messages formats, according to the given language. \\ The path to the english dictionary file is {\tt XLIFEPP\_DIR/etc/Messages/en/dictionary.txt}, the path to the french messages file is {\tt XLIFEPP\_DIR/etc/Messages/fr/messages.txt}, \ldots
\item It builds the global {\class Trace object} to initialize logs
\item It prints the execution header (logo + execution date, host machine \ldots)
\item It opens the print file and write the header in it.
\item It builds the global {\class Messages} object to load messages formats
\item It initializes RTI names for {\class Function} and {\class Value} objects.
\end{enumerate}

Global objects are declared in \emph{config.hpp} and defined in \emph{globalScopeData.hpp}. In the next section, we will see what is the content of these two files and of \emph{setup.hpp}

\section{Global declarations and definitions}

\subsection{\emph{setup.hpp}}

This file is automatically generated when you execute \cmake.
Its aim is to set compilation macros :

\begin{itemize}
\item {\bf OS\_IS\_UNIX}, {\bf OS\_IS\_WIN}, to set the OS. It is useful for instance to load specific source code for time management ({\em Timer.*pp})
\item {\bf XLIFEPP\_WITH\_GMSH} and {\bf XLIFEPP\_WITHOUT\_GMSH}, to activate/deactivate compilation of \xlifepp routines using a system call to \gmsh
\item {\bf XLIFEPP\_WITH\_PARAVIEW} and {\bf XLIFEPP\_WITHOUT\_PARAVIEW}, to activate/deactivate compilation of \xlifepp routines using a system call to \paraview
\item {\bf XLIFEPP\_WITH\_ARPACKPP} and {\bf XLIFEPP\_WITHOUT\_ARPACKPP}, to activate/deactivate compilation of \xlifepp interface of \arpackpp library.
\item {\bf XLIFEPP\_WITH\_UMFPACK} and {\bf XLIFEPP\_WITHOUT\_UMFPACK}, to activate/deactivate compilation of \xlifepp interface of \umfpack library.
\item {\bf XLIFEPP\_WITH\_OMP} and {\bf XLIFEPP\_WITHOUT\_OMP}, to activate/deactivate compilation of \xlifepp using OpenMP library.
\item {\bf INSTALL\_PATH}, to set the install path of \xlifepp and build paths for dictionary or messages formats.
\item {\bf GMSH\_PATH}, to set the path of \gmsh.
\item {\bf PARAVIEW\_PATH}, to set the path of \paraview.
\item {\bf STD\_TYPES}, {\bf LONG\_TYPES}, {\bf LONGLONG\_TYPES} to set the precision of scalar non integer values. The default is {\bf LONG\_TYPES}
\item {\bf STD\_STRING}, {\bf WIDE\_STRING}, to set the encoding of strings, by loading either the STL string classes, or . The default is {\bf STD\_STRING}.
\item {\bf COMPILER\_IS\_32\_BITS}, {\bf COMPILER\_IS\_64\_BITS} to set the precision od integer values
\end{itemize}

The last five macros are used in \emph{config.hpp} to define some typedefs.

\subsection{\emph{config.hpp}}

This file defines some scalar types, objects and parameters, and also enums.

\begin{itemize}
\item {\bf Scalar types :} \xlifepp uses scalar types that depend on the precision given in \emph{setup.hpp} : {\class int\_t} , {\class real\_t}, {\class complex\_t} are typedefs for respectively {\tt int}, {\tt float}, {\tt complex<float>} and their families ({\tt long int}, {\tt double},\ldots) according to the corresponding macro.  Two additional typedefs are {\class number\_t} and {\class dimen\_t} respectively for {\tt size\_t} and {\tt short unsigned int}, independent on precision. These scalar types can be called by users. According to the \xlifepp code convention, they have user typedefs : {\class Int}, {\class Real}, {\class Complex}, {\class Number}, {\tt Dimen}. For the same reason, there is the {\class String} typedef for STL classes {\tt string} or {\tt wstring} according to the corresponding macro, and the {\class Strings} typedef for {\tt std::vector<\class String\tt >}
\item {\bf Global parameters :} This is about output format parameters and extremal values :
\begin{lstlisting}[deletekeywords={[3] size_t},morekeywords={size_t}]
extern const number_t entriesPerRow;
extern const number_t entryWidth;
extern const number_t entryPrec;
extern const number_t addrPerRow;
extern const number_t addrWidth;
extern const number_t numberPerRow;
extern const number_t numberWidth;
extern const number_t theNumberMax;
extern const size_t theSizeMax;
extern const dimen_t theDimMax;
extern const real_t theRealMax;
extern const real_t theEpsilon;
extern const real_t theTolerance;
extern const real_t theZeroThreshold;
extern const number_t theLanguage;
extern unsigned int theGlobalVerboseLevel;
extern unsigned int theVerboseLevel;
\end{lstlisting}
There is also some mathematical constants :
\begin{lstlisting}
extern const real_t over3;
extern const real_t over6;
extern const real_t pi;
extern const real_t overpi;
extern const real_t over2pi;
extern const real_t over4pi;
extern const real_t sqrtOf2_;
extern const real_t sqrtOf3_;
extern const real_t logOf2_;
extern const real_t theEulerConst;
\end{lstlisting}
\item {\bf Global objects :} Global Trace, Messages, Parameters and Environment are also declared here
\item {\bf enums :} This is the list of enums defined here. For convenience, we give only their declaration :
\begin{lstlisting}
enum Language;
enum ShapeType;
enum ShapesType;
enum StrucType;
enum SymType;
enum ValueType;
enum FunctType;
enum FuncFormType;
enum SobolevType;
enum SpaceType;
enum DofType;
enum SupportType;
enum UnknownType;
enum FEType;
enum FESubType;
enum PolynomType;
enum QolynomType;
enum LinearFormType;
enum QuadRule

//for matrix storages
enum StorageType;
enum AccessType;
enum MatrixPart;

// for solver purpose
enum FactorizationType;
enum PreconditionerType;
enum EigenComputationalMode;
enum EigenSolverMode;
enum MsgEigenType;

enum ComputationInfo;
enum IOFormat;
enum TestStatus;
enum DataAccess;

\end{lstlisting}
Each enum has a dictionary counter-part for output.
\end{itemize}

\subsection{\emph{globalScopeData.hpp}}

This file is the last file include by main programs. Its aim is to define the global parameters and objects declared in \emph{config.hpp}, and also the static class attributes :

\begin{lstlisting}[deletekeywords={[3] map}]
std::vector<Interpolation*> Interpolation::theInterpolations;
std::vector<Space*>  Space::theSpaces;
Number FeSpace::lastEltIndex = 0;
std::vector<Unknown*> Unknown::theUnknowns;
std::vector<DifferentialOperator*> DifferentialOperator::theDifferentialOperators;
std::map<String, std::pair<ValueType, StrucType> > Function::returnTypes;
std::map<String, std::pair<ValueType, StrucType> > Function::returnArgs;
std::map<String, std::pair<ValueType, StrucType> > Value::theValueTypeRTInames;
std::vector<const GeomDomain*> GeomDomain::theDomains;
std::vector<GeomRefElement*> GeomRefElement::theGeomRefElements;
std::vector<RefElement*> RefElement::theRefElements;
std::vector<Quadrature*> Quadrature::theQuadratures;
std::vector<Term*> Term::theTerms;
std::vector<MatrixStorage*> MatrixStorage::theMatrixStorages;
\end{lstlisting}

You may read their function in the chapter dedicated to the corresponding classes.

\section{About the {\tt finalize} function}

The \texttt{finalize} function is defined in the {\lib finalize} library. Its aim is to clean every global static list defined in {\emph globalScopeData.hpp}. Why a library with a single external function ? For dependencies purpose. As the {\lib init} library and {\lib utils} library depend on each other through headers, the {\tt finalize function} depends on libraries concerned by those global static lists, namely {\lib finiteElements}, {\lib operator}, {\lib space}, {\lib geometry}, {\lib largeMatrix} and {\lib term}.
To preserve independence of the {\lib utils} library, the {\tt finalize} function cannot be placed in the {\lib init} library.

Here is the implementation of this function :

\begin{lstlisting}
void finalize()
{
  // clean all non user run-time lists
  Interpolation::clearGlobalVector();
  GeomRefElement::clearGlobalVector();
  RefElement::clearGlobalVector();
  DifferentialOperator::clearGlobalVector();
  Domain::clearGlobalVector();
  Space::clearGlobalVector();
  Unknown::clearGlobalVector();
  Quadrature::clearGlobalVector();
  MatrixStorage::clearGlobalVector();
  Term::clearGlobalVector();
}
\end{lstlisting}

It is used to preserve independence of tests when running all tests.