1%%%%%%%%%%%%%%%%%%% 2% XLiFE++ is an extended library of finite elements written in C++ 3% Copyright (C) 2014 Lunéville, Eric; Kielbasiewicz, Nicolas; Lafranche, Yvon; Nguyen, Manh-Ha; Chambeyron, Colin 4% 5% This program is free software: you can redistribute it and/or modify 6% it under the terms of the GNU General Public License as published by 7% the Free Software Foundation, either version 3 of the License, or 8% (at your option) any later version. 9% This program is distributed in the hope that it will be useful, 10% but WITHOUT ANY WARRANTY; without even the implied warranty of 11% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12% GNU General Public License for more details. 13% You should have received a copy of the GNU General Public License 14% along with this program. If not, see <http://www.gnu.org/licenses/>. 15%%%%%%%%%%%%%%%%%%% 16 17 18\section{Licence} 19 20\xlifepp is copyright (C) 2014 by E. Lunéville and N. Kielbasiewicz and is distributed under the terms of the GNU General Public License (GPL) (Version 3 or later, see https://www.gnu.org/licenses/gpl-3.0.en.html). This means that everyone is free to use \xlifepp and to redistribute it on a free basis. \xlifepp is not in the public domain; it is copyrighted and there are restrictions on its distribution. You cannot integrate \xlifepp (in full or in parts) in any closed-source software you plan to distribute (commercially or not). If you want to integrate parts of \xlifepp into a closed-source software, or want to sell a modified closed-source version of \xlifepp, you will need to obtain a different license. Please contact us directly for more information.\\ 21 22The developers do not assume any responsibility in 23the numerical results obtained using the \xlifepp library and are not responsible of bugs. 24 25\section{Credits} 26 27The \xlifepp library has been mainly developped by E. Lunéville and N. Kielbasiewicz of POEMS lab (UMR 7231, CNRS-ENSTA ParisTech-INRIA). Some parts are inherited from Melina++ library developped by D. Martin (IRMAR lab, Rennes University, now retired) and E. Lunéville. Other contributors are : 28\begin{itemize} 29\item Y. Lafranche (IRMAR lab), mesh tools using subdivision algorithms and wrapper to \arpackpp 30\item C. Chambeyron (POEMS lab), iterative solvers 31\item M.H N'Guyen (POEMS lab), eigen solvers and OpenMP implementation 32\end{itemize} 33 34\section{Installation} 35 36\xlifepp is under a git repository on the INRIA Gforge. So access to source code needs to log to the forge and to define a ssh-key for authentication. 37The first part is to be registered to INRIA GForge and to be accepted as member of \xlifepp project. To do so, please do as follows: 38 39\begin{enumerate} 40\item Please go to \url{https://gforge.inria.fr/projects/xlifepp/}. 41\item If you have already had a user account, please go to step \#4 42\item If you don't have a user account, please create it. 43\item If you have already been member of the \xlifepp project on INRIA GForge, please go to step \#6 44\item If you are not member of the \xlifepp project on INRIA GForge, please contact one of the \xlifepp administrators to join the \xlifepp development team on \url{http://uma.ensta-paristech.fr/soft/XLiFE++/} and wait until your registration to \xlifepp project on INRIA GForge is done to go to next section. 45\item For further documentation, you may go to the \xlifepp main page : \url{http://uma.ensta-paristech.fr/soft/XLiFE++/} 46\end{enumerate} 47 48\subsection{Under MacOS and Linux} 49 50To install \xlifepp in order to take part to its development, you may use the following steps: 51 52\begin{enumerate} 53\item Please install \git (\url{http://www.git-scm.com}) and \cmake (\url{http://cmake.org}). 54\item If you have already generated a ssh key and want to use it for \xlifepp project, please go to step \#4 55\item If you don't have generated a ssh key, please use the command {\tt ssh-keygen} to generate one. 56\item To add the public ssh key you want to use, please go to your account settings on INRIA GForge and add the key by clicking on ``Edit keys'' at the bottom. Copy the public key where it is needed, validate and register changes to your account. This may take some time so that the key is truly activated. 57\item On \url{https://gforge.inria.fr/projects/xlifepp/}, please go to the "Sources" tab to see the {\tt git clone ...} command-line you have to run in a terminal to create your local \xlifepp repository. 58\item In the root directory of \xlifepp, you have a shell script {\em pre-commit.sh} and a hidden directory {\em .git}. Copy the script to {\em .git/hooks/pre-commit} (without extension) and make the copy executable. When done, you will update file VERSION.txt automatically. 59\item You can now compile and develop. See next section. 60\end{enumerate} 61 62\subsection{Under Windows} 63 64To install \xlifepp in order to take part to its development, you may use the following steps: 65 66\begin{enumerate} 67\item Please install \git (\url{http://www.git-scm.com}) and \cmake (\url{http://cmake.org}). Under Windows, git is usable with the contextual menu showed with clicks on the right mouse button. 68\item Please open Git GUI in the contextual menu. 69\item Please click on ``Cloning existing repository''. A window opens. 70\item Please open the ``Help'' tab and select ``Show SSH key'' 71\item Click on ``Generate key''. The public key will be shown. Copy it. 72\item To add the public ssh key, please go to your account settings on INRIA GForge and add the key by clicking on ``Edit keys'' at the bottom. Copy the public key where it is needed, validate and register changes to your account. This may take some time so that the key is truly activated. 73\item To set the ``Source location'' in the Git GUI window, please go to the ``Sources'' tab on \url{https://gforge.inria.fr/projects/xlifepp/} to see the {\tt git clone ...} command-line. Copy the url (beginning by git+ssh//). Define a non-existing directory for the ``Target' Directory'. And click on ``Clone'' to create your local repository. 74\item In the root directory of \xlifepp, you have a shell script {\em pre-commit.sh} and a hidden directory {\em .git}. Copy the script to {\em .git/hooks/pre-commit} (without extension) and make the copy executable. When done, you will update file VERSION.txt automatically. 75\item You can now compile and develop. See next section. 76\end{enumerate} 77 78\section{Compilation} 79 80Compilation of \xlifepp is managed by \cmake, a high-level cross-platform compilation tool, running on MacOS, Windows, and Linux. This application only needs a configuration file named CMakeLists.txt, at the root directory of the \xlifepp archive. Whatever the OS, cmake also asks for another directory where to put generated files for compilation, called build directory hereafter. This directory can be everywhere. It will contains compilation files (objects files, \ldots), a Makefile or an IDE project file named XLiFE++ (for Eclipse, CodeBlocks, Visual Studio, XCode, \ldots). So we suggest you to set this directory as a subdirectory of \xlifepp install directory, with the name "build" for instance. 81 82\subsection{Under MacOS and Linux} 83 84\begin{figure}[H] 85\begin{center} 86\includePict[width=10cm]{cmake-ccmake.png} 87\end{center} 88\vspace{-1cm} 89\caption{{\tt ccmake} (MacOS, Unix)} 90\end{figure} 91 92When running {\tt ccmake}, the default \cmake GUI under MacOS or Linux, the build directory is given in argument. 93\begin{lstlisting}{language=} 94ccmake [options] path/to/CMakeLists.txt path/to/buildDirectory 95\end{lstlisting} 96 97When running \cmake GUI application, you have to set the directory ``Where is the source code'' containing CMakeLists.txt you want to run \cmake on, and to set the build directory: ``Where to build the binaries''. Then, you click the ``Configure'' button. It will ask ou the generator you want. Then, you click the ``Generate'' button, to generate your IDE project file or your Makefile. 98 99\begin{figure}[H] 100\begin{center} 101\includePict[width=8cm]{cmake-gui.png} 102\end{center} 103\vspace{-1cm} 104\caption{\cmake application (MacOS)} 105\end{figure} 106 107When running \cmake in command-line mode, the build directory is generally the directory in which you are when calling the \cmake command. If you want to know the general case, please take a look at \cmake option -b. 108 109To compile \xlifepp, you just have to run \cmake on the CMakeLists.txt file: 110\begin{lstlisting}[]{language=} 111cmake path/to/CMakeLists.txt 112\end{lstlisting} 113If you generated a project file, you launch your IDE on this file and can compile and run tests. The following command chooses for instance to use codeblocks on unix platform: 114\begin{lstlisting}[]{language=} 115cmake path/to/CMakeLists.txt -G "CodeBlocks - Unix Makefiles" 116\end{lstlisting} 117 118If you generated a Makefile, you have to run the {\tt make} command, to compile \xlifepp sources and tests. If you want to compile \xlifepp sources only, the target is "libs": 119 120\begin{lstlisting} 121make libs 122make 123\end{lstlisting} 124 125If you generated an IDE project file, you have to open it and compile target all to compile everything, sources and tests, or target libs, to compile sources only. 126 127\subsection{Under Windows} 128 129When running \cmake GUI application, you have to set the directory ``Where is the source code'' containing CMakeLists.txt you want to run \cmake on, and to set the build directory: ``Where to build the binaries''. Then, you click the ``Configure'' button. It will ask ou the generator you want. Then, you click the ``Generate'' button, to generate your IDE project file or your Makefile. 130 131\begin{figure}[H] 132\begin{center} 133\includePict[width=15cm]{cmake-Windows.png} 134\end{center} 135\vspace{-0.5cm} 136\caption{{\tt cmake} (Windows), after you clicked the configure button.} 137\end{figure} 138 139\begin{remark} 140You can have the list of available generators inside \cmake help. It does not tell that eclipse, codeblocks, \ldots are installed, but it tells that they can be installed on your computer and how you can tell \cmake to use them as generators. 141\end{remark} 142 143\subsection{Useful general options to \cmake} 144 145Four options may be very useful: 146\begin{description} 147\item[CMAKE\_CXX\_COMPILER] This option is used to set the compiler \cmake will use to compile your code: 148\begin{lstlisting} 149cmake path/to/CMakeLists.txt -DCMAKE_CXX_COMPILER=g++-48 150\end{lstlisting} 151\item[CMAKE\_BUILD\_TYPE] This option is used to set the type of build (debug, release, \ldots). Possible values are essentially Debug and Release. The default value is Release. 152\begin{lstlisting} 153cmake path/to/CMakeLists.txt -DCMAKE_BUILD_TYPE=Debug 154\end{lstlisting} 155\item[XLIFEPP\_PRECISION] This option is used to set the precision of numerical types (int, \ldots). Possible values are STD, LONG and LONGLONG. The default value is LONG. 156\begin{lstlisting} 157cmake path/to/CMakeLists.txt -DXLIFEPP_PRECISION=LONG 158\end{lstlisting} 159Except if you have a very good reason, you are not supposed to use this option. 160\item[XLIFEPP\_STRING\_TYPE] This option is used to set string type: STD (for std::string) and WIDE (for std::wstring). The default value is STD. 161\begin{lstlisting} 162cmake path/to/CMakeLists.txt -DXLIFEPP_STRING_TYPE=STD 163\end{lstlisting} 164Except if you have a very good reason, you are not supposed to use this option. 165\end{description} 166 167\subsection{Configuring \xlifepp with \gmsh and/or \paraview} 168 169\begin{description} 170\item[XLIFEPP\_GMSH\_EXECUTABLE] to specify the \gmsh binary with full path. If \gmsh is in your PATH, it will be automatically detected, else you can use this option: 171\begin{lstlisting} 172cmake path/to/CMakeLists.txt -DXLIFEPP_GMSH_EXECUTABLE=gmsh/exe/with/full/path 173\end{lstlisting} 174\item[XLIFEPP\_PARAVIEW\_EXECUTABLE] to specify the \paraview binary with full path. If \paraview is in your PATH, it will be automatically detected, else you can use this option: 175\begin{lstlisting} 176cmake path/to/CMakeLists.txt -DXLIFEPP_PARAVIEW_EXECUTABLE=paraview/exe/with/full/path 177\end{lstlisting} 178\end{description} 179 180\subsection{Configuring \xlifepp with \omp} 181 182\begin{description} 183\item[XLIFEPP\_ENABLE\_OMP] Activates/Deactivates use of OpenMP 184\begin{lstlisting} 185cmake path/to/CMakeLists.txt -DXLIFEPP_ENABLE_OMP=ON 186\end{lstlisting} 187\end{description} 188 189\subsection{Configuring \xlifepp with \arpack} 190 191Configuring with \arpack also means configuring with \blas and \lapack. When asked, these 3 libraries are automatically searched in standard paths. If these libraries are installed in other paths, you can give it directly. 192Otherwise, sources files of \arpack inside \xlifepp sources will be compiled and used. 193 194\begin{description} 195\item[XLIFEPP\_ENABLE\_ARPACK] Activates/Deactivates configuration with \arpack 196\item[XLIFEPP\_BLAS\_LIB\_DIR] to specify the directory containing \blas library 197\item[XLIFEPP\_LAPACK\_LIB\_DIR] to specify the directory containing \lapack library 198\item[XLIFEPP\_ARPACK\_LIB\_DIR] to specify the directory containing \arpack library 199\end{description} 200 201See \autoref{a.s.arpackpp} for more details 202 203\subsection{Configuring \xlifepp with \umfpack} 204 205Configuring with \umfpack also means configuring with \blas and \lapack. It can also mean configuring with other libraries provided by \suitesparse, insofar as \umfpack is now distributed inside \suitesparse. 206 207\begin{description} 208\item[XLIFEPP\_ENABLE\_UMFPACK] Activates/Deactivates configuration with \umfpack 209\item[XLIFEPP\_BLAS\_LIB\_DIR] to specify the directory containing \blas library 210\item[XLIFEPP\_LAPACK\_LIB\_DIR] to specify the directory containing \lapack library 211\item[XLIFEPP\_UMFPACK\_INCLUDE\_DIR] to specify the directory containing \umfpack header 212\item[XLIFEPP\_UMFPACK\_LIB\_DIR] to specify the directory containing \umfpack header 213\item[XLIFEPP\_SUITESPARSE\_HOME\_DIR] to specify the home directory of \suitesparse, containing \umfpack. This option is to be used if you compiled \suitesparse by yourself. In this case, \umfpack will be searched in the UMFPACK subdirectory. 214\end{description} 215 216There are specific options to each library provided by \suitesparse \umfpack may depend on. See \autoref{a.s.umfpack} for more details 217 218\begin{remark3} 219Using \cmake generates a cache file (CMakeCache.txt) containing value of every option defined during execution of \cmake, so that when reusing cmake on the same file resuses CMakeCache.txt, unless you change some options. This is why XLIFEPP\_ENABLE\_XXX options can take the value OFF. 220\end{remark3} 221 222\section{Folder organisation} 223 224The \xlifepp main directory is organised as follows : 225 226\begin{description} 227\item[bin] the binary directory containing the test executable and the output files for test execution 228\item[CMakeLists.txt] this is the parameters file for \cmake 229\item[doc] the documentation directory with the source documentation (the {\bf api} subdirectory), generated by \doxygen, and the TeX/pdf documentation (the {\bf tex} subdirectory) 230\item[etc] this directory contains templates files for installation, parameters files for \doxygen, dictionaries and messages formats 231\item[include] this directory contains the header aliases for each sublibrary of \xlifepp and config files 232\item[lib] this directory contains the static sublibraries of \xlifepp 233\item[README] the README file 234\item[src] this directory contains all source and header files. Each subdirectory represents a sublibrary of \xlifepp 235\item[tests] this directory contains source files for unitary and non-regressive tests 236\item[usr] this directory contains all files needed by the user to write a program using \xlifepp and compile it. 237\end{description} 238 239\section{Namespace} 240 241The whole \xlifepp library is defined in the namespace \emph{\textbf{xlifepp}}. Then, the developers 242have to encapsulate all their developments in this namespace either in the header files (.hpp) 243or in the implementation files (.cpp). For instance, a header file looks like : 244 245\begin{lstlisting}[]{} 246#ifndef FILE_HPP 247#define FILE_HPP 248 249#include "otherfile.hpp" 250#include <sysinclude> 251 252namespace xlifepp{ 253 ... 254 255} //end of namespace 256#endif 257\end{lstlisting} 258 259\section{Headers} 260 261All the header files of the library end by \emph{.hpp} and are located in the folder related 262to the topics of the header file. There are four particular header files located in the \emph{init} 263folder : 264\begin{itemize} 265\item \textit{setup.hpp} defining the pre-compiler macro related to the install path, the operating 266system, the precision type, the string type, the language and debug feature. Be cautious, changing 267one of this macro implies the recompilation of all the library. 268\item \textit{config.hpp} declaring all the general stuff : scalar definitions, string definition, 269enumeration, numerical constants and global variables used by general tools. It includes the 270header \emph{setup.hpp}. Note that this file may be (and must be) included everywhere. 271\item \textit{globalScopeData.hpp} initializing global variables declared in \emph{config.hpp}. 272This file has to be included once. 273\end{itemize} 274Some header interface files are defined in the \emph{include} folder, their name end with \emph{.h}. 275The header interface files are 276\begin{itemize} 277\item \textit{\emph{lib}.h} for each library folder (e.g \emph{init.h}, \emph{utils.h}, ...). 278This header file included all the header files (.hpp) of the library folder and is used by 279other libraries that require objects of this library folder. 280\item \textit{config.h} is an alias to the \emph{config.hpp} located in the \emph{init} folder. 281\item \textit{globalScopeData.h} is an alias to the \emph{globalScopeData.hpp} located in the 282{\lib init} folder. 283\item \textit{xlife++.h} is the global header file. As this file includes the \emph{globalScopeData.hpp} 284initializing all the global variables it must be included only in the main program. 285\end{itemize} 286 287\begin{figure}[H] 288\centering 289\inputTikZ{header} 290\caption{Headers organisation} 291\end{figure} 292 293From a practical point of view : 294 295\begin{itemize} 296\item when you develop a new class or utilities in the \emph{mystuff.cpp} file in the library 297{\lib lib}, create the header file \emph{mystuff.hpp} and add the alias \emph{\#include "../src/lib/mystuff.hpp"} 298in the \emph{lib.h} located in the \emph{include} folder. 299\item include the \emph{config.h} in your files to access to all general definitions, local 300header files (.hpp) if you refer to some stuff of the library and global header files (.h) 301if you refer to some stuff of other libraries 302\item when you develop a new library ({\lib mylib}), you have to create the \emph{mylib.h} 303header file in the \emph{include} folder and add \emph{\#include "mylib.h" } in the \emph{xlife++.h}. 304\end{itemize} 305 306\section{Development principles} 307This section gives some "philosophical" principles to developp the library \xlifepp. These 308principles can be sum up in the following commandments : 309\begin{itemize} 310\item \textbf{Code has to be efficient} \\ 311It means that time consuming functions and memory consuming object has to be designed to be 312the most efficient as possible. It is not required else. 313\item \textbf{Be friendly with end users}\\ 314 no templated and not too much end user's classes, no pointers, friendly syntaxes, ... 315\item \textbf{Be friendly with not advanced developers} \\ 316 it means that the intermediate code has to be not too intricate 317\item \textbf{Make code documentation} \\ 318Write inline documentation along \doxygen syntax and outline documentation in Latex: the developer 319documentation gives principles, useful comments and a description of classes and functions, 320user documentation describes how to use the end user's classes and functions. 321\item \textbf{Write test functions} \\ 322It is mandatory to perform low level tests and to archive it (see chapter Test Policy) 323\end{itemize} 324As usual, there may be exceptions to the rules but they have to be approved. 325 326\subsection*{Dealing with multithreading} 327Up to now, \xlifepp supports OMP if library is compiled with the OMP flag. It is up to the developer to use it or not but when heavy computation it is advised to. As \xlifepp already uses OMP in all FE computations or matrix computations, be care when using it at a high level of the code. 328 329\subsection*{How to encapsulate a class hierarchy in an end user class} 330The problem is to propose to end user a single class ({\class User}) masking a class hierarchy 331({\class Child1},{\class Child2},... that inherits from {\class User}): 332\vspace{.1cm} 333\begin{lstlisting}[] 334class Child1 : public User {...}; 335class Child2 : public User {...}; 336\end{lstlisting} 337\vspace{.2cm} 338There are at least three solutions : 339\begin{itemize} 340\item using child pointers of child classes inherited from {\class BaseChild} base class : 341\vspace{.1cm} 342\begin{lstlisting}[] 343class BaseChild {...} 344class Child1 : public BaseChild {...}; 345class Child2 : public BaseChild {...}; 346 347class User 348{ChildType childType; //type of child 349 Child1 * ch1_p; //pointer to Child1 object 350 Child2 * ch2_p; //pointer to Child2 object 351 ... //common attributes and functions 352}; 353\end{lstlisting} 354\vspace{.1cm} 355All the member functions of {\class User} class analyse the child type to adress the right 356child functions. 357\item using pointer to {\class BaseChild} base class : 358\vspace{.1cm} 359\begin{lstlisting}[] 360class BaseChild {...} 361class Child1 : public BaseChild {...}; 362class Child2 : public BaseChild {...}; 363 364class User 365{BasicChild * bch_p; //pointer to BaseChild object 366 ... 367}; 368\end{lstlisting} 369\vspace{.1cm} 370All the member functions of {\class User} class call their equivalent {\class BaseChild} member 371functions. 372\item using a contraction of the previous model named "abstact/non abstract pattern" : 373\vspace{.1cm} 374\begin{lstlisting} 375class User 376{User* us_p; //pointer to child or itself if it is a child 377 virtual Child1* child1() 378 {if(us_p!=this) us_p->child1(); 379 return 0;} 380}; 381 382class Child1 : public User 383{Child1* child1(){return this;} 384 ... 385}; 386class Child2 : public User 387{Child2* child2(){return this;} 388 ... 389}; 390\end{lstlisting} 391\vspace{.1cm} 392This model is named "abstract/non abstract" because {\class User} class is a non abstract class 393but is used as an abstract class. In this model, {\class User} class attributes are duplicated. 394If they take a large amount of memory, encapsulate it in a structure and use a pointer to this 395structure : 396\vspace{.1cm} 397\begin{lstlisting}[] 398class Attributes 399{... 400}; 401 402class User 403{User* us_p; //pointer to child or itself if it is a child 404 Attributes* at_p; //pointer to User attributes 405}; 406\end{lstlisting} 407\vspace{.1cm} 408\end{itemize} 409Each of them has their advantages and defaults. Use the one you prefer. 410 411