Chapter 1
Introduction

1.1 What XLiFE++ is

Partial differential equations (PDE hereafter) are the core of modeling. A wide range of problems in Physics, Mechanics, Engineering, Mathematics, Health, Finance are modeled by PDEs.

XLiFE++ is a C++ library designed to solve these equations numerically. It is a free extended library based on finite elements methods. It is an autonomous library, providing everything you need for solving such problems, including interfaces to specific external libraries or softwares, such as Gmsh, Arpack++, UmfPack, …

What does XLiFE++ do ?

  • Problem description (real or complex, scalar or vector) by their variational formulations, with full access to the internal vectors or matrices;

  • Multi-variables, multi-equations, 1D, 2D and 3D, linear or non linear coupled systems;

  • Easy geometric input by composite description , to build meshes thanks to Gmsh;

  • Easy automatic mesh generation on elementary geometries, based on refinement methods;

  • Very high level user-friendly typed input language with full algebra of analytic and finite elements functions. Your main program will be very similar to the mathematical formulation;

  • A wide range of finite elements : segments, triangles, quadrangles, hexahedra, tetrahedra, prisms and pyramids

  • A wide set of internal linear direct and iterative solvers (LU, Cholesky, BiCG, BiCGStab, CG, CGS, GMRES, QMR, SOR, SSOR, …) and internal eigenvalues and eigenvectors solvers, plus additional interfaces to external solvers (Arpack, UmfPack,…);

  • A full documentation suite : source documentation (online or inside sources), user documentation (pdf), developer documentation (pdf);

  • A parallel version using OpenMP.

1.2 How to download XLiFE++

XLiFE++ is downloadable at the following url http://uma.ensta-paris.fr/soft/XLiFE++/. You can download releases and snapshots of either the source code or binaries. Snapshots are supposed to be generated automatically very often.

There are 2 kinds of archives (snapshots or releases):

1.
a "source" archive that contains all XLiFE++ source files and tex/pdf documentation;
2.
a "api" archive that contains only source documentation generated by Doxygen

1.2.1 How XLiFE++ sources are organized

XLiFE++ sources are organized with several directories, described as follows for the main ones:

bin

contains the xlifepp_project_setup.exe for Windows and the user scripts xlifepp.sh and xlifepp.bat. This will be explained later.

doc

contains the present user guide, the developer guide (also in pdf) and other specific documentations extracted from the present user guide, such as a tutorial, an install documentation, and explanations about examples.

etc

contains a lot of stuff such as templates for installation, the multilingual files, …

examples

contains example files ready to compile and use.

ext

contains source files for external dependencies, such as Arpack++, Eigen, Amos libraries

src

contains all C++ sources of the XLiFE++ library

tests

contains all unitary and system tests to check your installation

lib

will contain the static libraries of XLiFE++, after the compilation step.

usr

contains the user files to write and compile a C++ program using XLiFE++

You also have a very important file CMakeLists.txt, that is the CMake compilation script.

1.2.2 How XLiFE++ binaries are organized

XLiFE++ binaries are organized with several directories, described as follows for the main ones:

bin

contains the xlifepp_project_setup.exe for Windows and the user scripts xlifepp.sh and xlifepp.bat. This will be explained later.

etc

contains a lot of stuff such as templates for installation, the multilingual files, …

share/doc

contains the present user guide, the developer guide (also in pdf) and other specific documentations extracted from the present user guide, such as a tutorial, an install documentation, and explanations about examples.

share/examples

contains example files ready to compile and use.

ext

contains source files for external dependencies, such as Arpack++, Eigen, Amos libraries

tests

contains all unitary and system tests to check your installation

lib

contains the static libraries of XLiFE++.

You also have a very important file CMakeLists.txt, that is the CMake compilation script.

1.3 Requirements

1.3.1 Extensions

To use XLiFE++ full capabilities, you may need some external libraries to activate extensions:

pict XLiFE++ provides 2 external libraries: Eigen (http://eigen.tuxfamily.org/, essentially for SVD, and Amos (http://www.netlib.org/amos/) for Bessel/Hankel functions with complex arguments.

1.3.2 Installation requirements

Basically, XLiFE++ compilation depends on the cross-platform builder CMake, available at http://cmake.org. To know how to install and use XLiFE++ this way, please read section 1.4.

For Unix systems, you can use an alternative installation procedure that does not require CMake. To know how to install and use XLiFE++ this way, please read section 1.5.

Another way to install XLiFE++ is to download a Docker container (like a virtual machine containing everything to build and run XLiFE++). It is cross-platform. To know how to install and use XLiFE++ this way, please read section 1.6.

Of course, you need a C++ compiler. To install a proper 64bits compiler on Windows, see section A.4.

1.4 Main installation and usage process, with CMake

You download XLiFE++ from its website http://uma.ensta-paris.fr/soft/XLiFE++/.

  • Either you download XLiFE++ sources: you have to unzip the archive at any place you choose in the filesystem. Then, you follow configuration procedure by setting at least a C++ compiler, paths to Gmsh and Paraview and eventually paths to external libraries Blas, Lapack, Arpack and UmfPack. When done, you will have to compile XLiFE++ source code.

  • Or you download XLiFE++ binaries: you will have to run the installer if you are on Windows (see subsection 1.4.4), or follow the configuration procedure with cmake by setting a C++ compiler, paths to Gmsh and Paraview, and eventually paths to external libraries Blas, Lapack, Arpack and UmfPack libraries. In following sections, you will be guided on which options you may use or not as far as sources or binaries are concerned.

    pict If you want to use clang++ as a compiler, please download dedicated clang++ binaries, as they are necessarily generated without OpenMP activated.

pict If you need to learn how to use cmake, please go to chapter C. Keep in mind that running CMake several times is not a problem. Indeed, as far as external dependencies are concerned, CMake is supposed to find a wide range of possible configurations, but not every time of course!

1.4.1 Configuration step

pict In the following, we will consider CMake used in command-line mode, from a build directory directly inside sources so that the path to CMakeLists.txt file is ..

Cache entries that will be explained can be set directly through GUI applications.

The default build configuration is to use Eigen and Amos libraries, as they are provided directly by XLiFE++, and multi-threading with OpenMP, if the compiler is compatible with it (for instance, clang++ on Mac OS is not).

cmake ..

As explained in chapter C, you can specify a generator with option -G, namely the native makefile or the IDE file you want. The default generator is "Unix Makefiles" on Linux and Mac OS computers, and "MinGW Makefiles" on Windows, but it can have a wide range of possible values. To know what you can do, please consult CMake help. For instance, if you want to generate a CodeBlocks project on Linux computer, you may choose Codeblocks - Unix Makefiles

cmake .. [-G <generator_name>]

In the following, we will focus on cache entries you may have to set.

pict When CMake is running, it stores values of cache entries in a cache file CMakeCache.txt in the build directory. As a result, when you run again CMake, you are not forced to give already given options.

1.4.2 How to set compilers

By default, CMake consider each directory defined in your paths environment variables to find compilers, and select the first compiler found. Nevertheless, you may select another compiler. To do so, you need 2 CMake cache entries:

CMAKE_CXX_COMPILER

to set the C++ compiler

CMAKE_Fortran_COMPILER

to set the Fortran compiler (necessary to Amos compilation, and eventually to Arpack compilation if you choose provided source distribution). Please notice the spelling, as CMake is case-sensitive !!

cmake .. -DCMAKE_CXX_COMPILER=g++-7 -DCMAKE_Fortran_COMPILER=gfortran-7 [other_options]

If you want to configure XLiFE++ in Debug mode (or another one, you may use the following entry :

CMAKE_BUILD_TYPE

Default value is "Release". Other possible values are "Debug", "RelWithDebInfo", …

cmake .. -DCMAKE_CXX_COMPILER=g++-7 -DCMAKE_Fortran_COMPILER=gfortran-7 -DCMAKE_BUILD_TYPE=Debug [other_options]

When you look at the CMake log, you are supposed to read that the rightful compiler is used with the rightful build type, and that activated dependencies are found and used and that deactivated dependencies are not used.

1.4.3 How to set external dependencies

pict In the following, [general_entries] refers to options introduced in subsection 1.4.2

To activates all dependencies, you can type the following:

cmake .. [general_entries] -DXLIFEPP_DEPS=ENABLE_ALL

XLIFEPP_DEPS

Default value is "DEFAULT". Other possible values are "ENABLE_ALL" or "DISABLE_ALL".

pict For XLiFE++ binaries, this option is used to generate them, so you don’t have to use it.

pict When you use CMake GUI application, option XLIFEPP_DEPS is useless, as the list of specific options discussed in the following warning are displayed as checkboxes.

For every external dependency, CMake search files in standard environment paths and in specific paths defined in CMake configuration script. So if external dependencies are installed by package managers, CMake will find them.

If it is not the case, or if the library found is not the one you want to use, you can tell CMake where to find them, as we will see in the following.

pict If you don’t want to activate every external dependency, but only some of them, you may use a subset of the following options (default behavior in bold):

XLIFEPP_ENABLE_ARPACK

To enable/disable use of Arpack. Possible values are ON or OFF.

XLIFEPP_ENABLE_UMFPACK

To enable/disable use of UmfPack. Possible values are ON or OFF.

XLIFEPP_ENABLE_AMOS

To enable/disable use of Amos. Possible values are ON or OFF.

XLIFEPP_ENABLE_OMP

To enable/disable use of OpenMP. Possible values are ON or OFF.

XLIFEPP_ENABLE_EIGEN

To enable/disable use of Eigen. Possible values are ON or OFF. Default is the same as XLIFEPP_ENABLE_OMP, as Eigen needs OpenMP.

XLIFEPP_ENABLE_MAGMA

To enable/disable use of Magma. Possible values are ON or OFF.

Configuring paths to Gmsh and Paraview executables

pict In the following, [general_entries] refers to options introduced in subsection 1.4.2 and [deps_entries] refers to others options introduced since subsection 1.4.3

To set the full path to Gmsh executable, you can type the following:

cmake .. [general_entries] [deps_entries] -DXLIFEPP_GMSH_EXECUTABLE=path/to/gmsh/executable

To set the full path to Paraview executable, you can type the following:

cmake .. [general_entries] [deps_entries] -DXLIFEPP_PARAVIEW_EXECUTABLE=path/to/paraview/executable

pict You have to set the full path to Gmsh/Paraview executables and not applications. Executables are inside applications. If application names are Gmsh.app and paraview.app and are located in the Applications directory, Gmsh and Paraview will be correctly detected.

Configuring dependency on Blas and Lapack libraries

pict In the following, [general_entries] refers to options introduced in subsection 1.4.2 and [deps_entries] refers to others options introduced since subsection 1.4.3

To tell to CMake where to find Blas library, you just have to set the directory containing the Blas library, with the option XLIFEPP_BLAS_LIB_DIR:

cmake .. [general_entries] [deps_entries] -DXLIFEPP_BLAS_LIB_DIR=path/to/blas/library/directory

To tell to CMake where to find Lapack library, you just have to set the directory containing the Lapack library, with the option XLIFEPP_LAPACK_LIB_DIR:

cmake .. [general_entries] [deps_entries] -DXLIFEPP_LAPACK_LIB_DIR=path/to/lapack/library/directory

pict Setting the directory is sufficient only if the Blas library name is standard, such as libblas.a, libblas.so, libblas.dylib, libblas.dll, blas.lib, …(the same goes for Lapack) If it is not the case, it means that Blas/Lapack is not installed properly (for instance with a version number as a suffix). Prefer using options XLIFEPP_BLAS_LIB and XLIFEPP_LAPACK_LIB instead, to set the full path to Blas and Lapack libraries

pict If you downloaded binary libraries provided by the XLiFE++ website, as recommended in subsection 1.3.1, it will be something like (if you downloaded 64bits binaries):

cmake .. [general_entries] [deps_entries] -DXLIFEPP_BLAS_LIB_DIR="C:/.../lapack-3.5.0_64" -DXLIFEPP_LAPACK_LIB_DIR="C:/.../lapack-3.5.0_64"

pict When using clang++, you have to set the path to Fortran library, as clang++ is not able to find it by itself (contrary to gcc, as gcc and Fortran library are in the same distribution). To do so, you just have to use the option XLIFEPP_FORTRAN_LIB_DIR:

cmake .. [general_entries] [deps_entries] -DXLIFEPP_FORTRAN_LIB_DIR=path/to/gfortran/library/directory

pict Setting the directory is sufficient only if the Fortran library name is standard, such as libgfortran.a, libgfortran.so, libgfortran.dylib, libgfortran.dll, gfortran.lib, …If it is not the case, it means that Fortran is not installed properly (for instance with a version number as a suffix). Prefer using option XLIFEPP_FORTRAN_LIB instead, to set the full path to Fortran library

Configuring dependency on Arpack library

pict In the following, [general_entries] refers to options introduced in subsection 1.4.2 and [deps_entries] refers to others options introduced since subsection 1.4.3

First of all, you have to choose if you want to use the internal Arpack distribution of XLiFE++, or an external one. Of course, the one provided by XLiFE++ is detected automatically. To select the rightful mode, you have to set the option:

XLIFEPP_SYSTEM_ARPACK

To choose an external distribution of Arpack or the one provided by XLiFE++. Possible values are ON or OFF. Default is OFF, to use the distribution provided by XLiFE++

If you choose to use an external distribution of Arpack, you now have to tell CMake where to find Arpack library. To do so, you just have to set the directory containing the Arpack library, with the option
XLIFEPP_ARPACK_LIB_DIR:

cmake .. [general_entries] [deps_entries] -DXLIFEPP_BLAS_LIB_DIR=path/to/blas/library/directory

pict Setting the directory is sufficient only if the Arpack library name is standard, such as libarpack.a, libarpack.so, libarpack.dylib, libarpack.dll, arpack.lib, …If it is not the case, it means that Arpack is not installed properly (for instance with a version number as a suffix). Prefer using option XLIFEPP_ARPACK_LIB instead, to set the full path to Arpack library

pict If you downloaded binary libraries provided by the XLiFE++ website, as recommended in subsection 1.3.1, it will be something like (if you downloaded 64bits binaries):

cmake .. [general_entries] [deps_entries] -DXLIFEPP_ARPACK_LIB_DIR="C:/.../ARPACK_64/lib_mingw64"

pict When using clang++, you have to set the path to Fortran library, as clang++ is not able to find it byt itself (contrary to gcc, as gcc and Fortran library are in ther same distribution). To do so, you just have to use the option XLIFEPP_FORTRAN_LIB_DIR:

cmake .. [general_entries] [deps_entries] -DXLIFEPP_FORTRAN_LIB_DIR=path/to/gfortran/library/directory

pict Setting the directory is sufficient only if the Fortran library name is standard, such as libgfortran.a, libgfortran.so, libgfortran.dylib, libgfortran.dll, gfortran.lib, …If it is not the case, it means that Fortran is not installed properly (for instance with a version number as a suffix). Prefer using option XLIFEPP_FORTRAN_LIB instead, to set the full path to Fortran library

Configuring dependency on SuiteSparse/ UmfPack libraries

pict In the following, [general_entries] refers to options introduced in subsection 1.4.2 and [deps_entries] refers to others options introduced since subsection 1.4.3

UmfPack is a part of SuiteSparse distribution (that also contains amd, colamd, camd, ccolamd, cholmod, metis, and suitesparseconfig, …).

To tell to CMake where to find UmfPack library/SuiteSparse distribution, you just have to set the home directory containing the SuiteSparse distribution, with the option
XLIFEPP_SUITESPARSE_HOME_DIR:

cmake .. [general_entries] [deps_entries] -DXLIFEPP_SUITESPARSE_HOME_DIR=path/to/suitesparse/home/directory

pict If you downloaded binary libraries provided by the XLiFE++ website, as recommended in subsection 1.3.1, it will be something like (if you downloaded 64bits binaries):

cmake .. [general_entries] [deps_entries] -DXLIFEPP_SUITESPARSE_HOME_DIR="C:/.../SuiteSparse_64"

pict When using clang++, you have to set the path to Fortran library, as clang++ is not able to find it byt itself (contrary to gcc, as gcc and Fortran library are in ther same distribution). To do so, you just have to use the option XLIFEPP_FORTRAN_LIB_DIR:

cmake .. [general_entries] [deps_entries] -DXLIFEPP_FORTRAN_LIB_DIR=path/to/gfortran/library/directory

pict Setting the directory is sufficient only if the Fortran library name is standard, such as libgfortran.a, libgfortran.so, libgfortran.dylib, libgfortran.dll, gfortran.lib, …If it is not the case, it means that Fortran is not installed properly (for instance with a version number as a suffix). Prefer using option XLIFEPP_FORTRAN_LIB instead, to set the full path to Fortran library

pict If setting XLIFEPP_SUITESPARSE_HOME_DIR is not enough to find every library of SuiteSparse distribution, you can use specific options of the form:

XLIFEPP_XXX_INCLUDE_DIR

to specify the XXX header, where XXX can be AMD, COLAMD, CAMD, CCOLAMD, CHOLMOD, METIS, SUITESPARSECONFIG or UMFPACK.

XLIFEPP_XXX_LIB_DIR

to specify the XXX library, where XXX can be AMD, COLAMD, CAMD, CCOLAMD, CHOLMOD, METIS, SUITESPARSE (only on Mac OS), SUITESPARSECONFIG or UMFPACK.

Setting the directories is sufficient only if the SuiteSparse library names are standard, such as libamd.a, libamd.so, libamd.dylib, libamd.dll, amd.lib, …(the same goes for the other libraries) If it is not the case, it means that SuiteSparse is not installed properly (for instance with a version number as a suffix). Prefer using option XLIFEPP_XXX_LIB instead, to set the full path to SuiteSparse libraries, where XXX can be AMD, COLAMD, CAMD, CCOLAMD, CHOLMOD, METIS, SUITESPARSE (only on Mac OS), SUITESPARSECONFIG or UMFPACK.

Configuring dependency on Magma library

pict In the following, [general_entries] refers to options introduced in subsection 1.4.2 and [deps_entries] refers to others options introduced since subsection 1.4.3

To tell to CMake where to find Magma library, you just have to set the directory containing the Magma library, with the option XLIFEPP_MAGMA_LIB_DIR and the directory containing the Magma header files, with the option XLIFEPP_MAGMA_INCLUDE_DIR:

cmake .. [general_entries] [deps_entries] -DXLIFEPP_MAGMA_LIB_DIR=path/to/magma/library/directory -DXLIFEPP_MAGMA_INCLUDE_DIR=path/to/magma/include/directory

1.4.4 Installation of binaries under Windows

When downloading binaries under Windows, you just have to run the installer. To do so, administrator elevation is required. If a previous distribution of XLiFE++ is installed in the folder you choose, the installer can remove it itself. Furthermore, it is highly recommended to install every component.

Now, in the bin subdirectory of the XLiFE++ install directory, you will find xlifepp_configure.exe. To run it, administrator elevation is required.

1.
First, you have to set the folder containing XLiFE++.
pict

2.
As mentioned in the banner, a C++ compiler, CMake and Gmsh have to be installed on your computer and defined in the Windows path1. An EDI such as CodeBlocks and Paraview are not mandatory but highly recommended. Click on the Configure button.
pict

3.
When everything is OK, message "Configuration complete" is displayed. To compile your own program, you can click on the New project button or run xlifepp_new_project.exe. See subsubsection 1.4.5

1.4.5 Compilation of a program using XLiFE++

The manual way

This way supposes that you know where XLiFE++ is installed.

1.
You create your working directory,
2.
You copy the main.cpp file into your working directory,
3.
You copy the CMakeLists.txt file from the build directory (the directory in which you ran installation process) into your working directory,
4.
You run CMake on the CMakelists.txt file to get your makefile or files for your IDE project (Eclipse, XCode, CodeBlocks, Visual C++, …),
5.
You can now edit the main.cpp file to write your program and enjoy compilation with XLiFE++.
The command-line way

This way is possible to make easier the manual way. In the bin directory of XLiFE++, you have shell script called xlifepp.sh for MacOS and Linux, and a batch script called xlifepp.bat. You can define a shortcut on it wherever you want.

Here is the list of options of both scripts:

USAGE:
    xlifepp.sh --build [--interactive] [(--generate|--no-generate)]
    xlifepp.sh --build --non-interactive [(--generate|--no-generate)]
                       [--compiler <compiler>] [--directory <dir>]
                       [--generator-name <generator>]
                       [--build-type <build-type>]
                       [(--with-omp|--without-omp)]
    xlifepp.sh --help
    xlifepp.sh --version

MAIN OPTIONS:
    --build, -b               copy cmake files and eventually sample of
                              main file and run cmake on it to prepare
                              your so-called project directory.
                              This is the default
    --generate, -g            generate the project. Used with --build option.
                              This is the default.
    --help, -help, -h         show the current help
    --interactive, -i         run xlifepp in interactive mode. Used with
                              --build option. This is the default
    --non-interactive, -noi   run xlifepp in non interactive mode. Used with
                              --build option
    --no-generate, -nog       prevent generation of your project. You will
                              do it yourself.
    --version, -v             print version number of XLiFE++ and its date
    --verbose-level <value>,  set the verbose level. Default value is 1
    -vl <value>

OPTIONS FOR BUILD IN NON INTERACTIVE MODE:
    --build-type <value>,     set cmake build type (Debug, Release, ...).
    -bt <value>
    --cxx-compiler <value>,   set the C++ compiler to use.
    -cxx <value>
    --directory <dir>,        set the directory where you want to build
    -d <dir>                  your project
    --generator-name <name>,  set the cmake generator.
    -gn <name>
    -f <filename>,            copy <filename> as a main file for the user
    --main-file <filename>    project.
    -nof,                     do not copy the sample main.cpp file. This is
    --no-main-file            the default.
    --info-dir, -id           set the directory where the info.txt file is
    --with-omp, -omp          activates OpenMP mode
    --without-omp, -nomp      deactivates OpenMP mode

The graphical way on Mac OS

This way is possible to make easier the manual way and more pleasant than the command-line way. On the website, you have a GUI application called xlifepp-qt for MacOS, (Windows and Linux will come soon). You can define a shortcut on it wherever you want.


pict

Figure 1.1: The "Configuration" tab of xlifepp-qt application


pict

Figure 1.2: The "Use" tab of xlifepp-qt application

This application is a graphical user interface to the first 3 steps of the manual way.

The graphical way on Windows
1.
You run the generator xlifepp_new_project.exe located in the bin subdirectory of the XLiFE++ install directory. The XLiFE++ folder should be correct but you can fix it if necessary.
pict

2.
You select the folder in which you will write your program using XLiFE++. If it already exists, the generator asks you to clean it or not. This window gives some information about XLiFE++: the compiler used to generate it, if the library supports omp and the debug/release status. You should use a compatible compiler with this library. If the default C++ compiler found on your computer is not compatible, you can select another one by clicking on the use compiler folder button.
pict

3.
Select the type of your project. For the moment only CodeBlocks-MinGW and Makefile are working but CodeBlocks is highly recommended! Select a main file from the proposed list. This main fill will be copied in your application folder. Be care, if you choose "none", no main file will be copied and the generator will fail if there is no main file in your application folder. This option is only useful if you want to keep an existing main file in your application folder! Click on the Generate button and wait:
pict

4.
When everything is complete, you can either exit the tool or run the program that opens the generated project (CodeBlocks in the example) by clicking on the run button.

1.4.6 Example

Here follows an example showing how to install and use XLiFE++ with command line tools described in the previous sections. The character ˜ denotes the home directory of the user. The commands are numbered starting from 1 ; each number is preceded by the name of the current working directory.

We first decompress the archive in a new directory (renamed xlifepp), create a build directory and launch the creation of the libraries:

~ (1) tar xf ~/Downloads/xlifepp-sources-v2.0.1-2018-05-09.tbz
~ (2) mv xlifepp-sources-v2.0.1-2018-05-09 xlifepp
~ (3) cd ~/xlifepp
~/xlifepp (4) mkdir build
~/xlifepp (5) cd build
~/xlifepp/build (6) cmake .. -DXLIFEPP_ENABLE_ARPACK=ON -DXLIFEPP_ENABLE_UMFPACK=ON
-- The CXX compiler identification is AppleClang 9.1.0.9020039
    .
    . (text intentionally removed)
    .
-- Build files have been written to: ~/xlifepp/build
~/xlifepp/build (7) make libs
Scanning dependencies of target xlifepp_form
[  0%] Building CXX object CMakeFiles/xlifepp_form.dir/src/form/BilinearForm.cpp.o
    .
    . (text intentionally removed)
    .
[100%] Built target libs
~/xlifepp/build (8)

Now, we can create an executable file. To do that, we choose to create a test directory and to compile one of the examples present in this documentation:

~/xlifepp/build (8) mkdir /tmp/test
~/xlifepp/build (9) cd /tmp/test
/tmp/test (10) ~/xlifepp/bin/xlifepp.sh
*********************************
*           xlifepp             *
*********************************
Project directory (default is current directory):

/tmp/test exists
The following generators are available on this platform:
1 -> Unix Makefiles
2 -> Ninja
3 -> Xcode
4 -> CodeBlocks - Ninja
5 -> CodeBlocks - Unix Makefiles
6 -> CodeLite - Ninja
7 -> CodeLite - Unix Makefiles
8 -> Sublime Text 2 - Ninja
9 -> Sublime Text 2 - Unix Makefiles
10 -> Kate - Ninja
11 -> Kate - Unix Makefiles
12 -> Eclipse CDT4 - Ninja
13 -> Eclipse CDT4 - Unix Makefiles
14 -> KDevelop3
15 -> KDevelop3 - Unix Makefiles
Your choice (default is 1): 1
The following compilers are available:
1 -> clang++-4.2.1
The following main files are available:
1 -> main.cpp
2 -> elasticity2dP1.cpp
3 -> helmholtz2d-Dirichlet_single_layer.cpp
4 -> helmholtz2dP1-DtN_scalar.cpp
5 -> helmholtz2dP1-cg.cpp
6 -> helmholtz2d_FEM_BEM.cpp
7 -> helmholtz2d_FE_IR.cpp
8 -> helmholtz3d-Dirichlet_single_layer.cpp
9 -> laplace1dGL60-eigen.cpp
10 -> laplace1dP1.cpp
11 -> laplace1dP10Robin.cpp
12 -> laplace2dP0_RT1.cpp
13 -> laplace2dP1-average.cpp
14 -> laplace2dP1-dirichlet.cpp
15 -> laplace2dP1-periodic.cpp
16 -> laplace2dP1_Neumann.cpp
17 -> laplace2dP2-eigen.cpp
18 -> laplace2dP2-transmission.cpp
19 -> maxwell2dN1.cpp
20 -> maxwell3D_EFIE.cpp
21 -> wave_2d_leap-frog.cpp
Your choice (default is 1): 14
Copying laplace2dP1-dirichlet.cpp
Cleaning CMake build files
You can use:
 
 
1 -> sequential
The following build types are available
1 -> Release
Copying CMakeLists.txt
-- The CXX compiler identification is AppleClang 9.1.0.9020039
-- Check for working CXX compiler: /usr/bin/clang++
-- Check for working CXX compiler: /usr/bin/clang++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- OpenMP is not used
-- XLiFE++ was compiled with clang++-4.2.1
-- XLiFE++ was compiled without OpenMP
-- XLiFE++ was compiled in Release mode
-- XLiFE++ libraries found !
-- Arpack is used
-- Umfpack is used
-- LAPACK is used
-- BLAS is used
-- AMOS is used
-- Magma is not used
-- Metis is not used
-- MPI is not used
-- Configuring done
-- Generating done
-- Build files have been written to: /tmp/test
/tmp/test (11) make
Scanning dependencies of target checklock
[  0%] Built target checklock
Scanning dependencies of target exec-x86_64-darwin-clang++-4.2.1-Release
[ 50%] Building CXX object CMakeFiles/exec-x86_64-darwin-clang++-4.2.1-Release.dir/laplace2dP1-
dirichlet.cpp.o
[100%] Linking CXX executable exec-x86_64-darwin-clang++-4.2.1-Release
[100%] Built target exec-x86_64-darwin-clang++-4.2.1-Release
/tmp/test (12) ./exec-x86_64-darwin-clang++-4.2.1-Release
__  __  __ _   ___  __
\ \/ / / /(_) / __\/__\_     _
 \  / / / | |/ _\ /_\_| |_ _| |_
 /  \/ /__| / /  //_|_   _|_   _|
/_/\_\____/_\/   \__/ |_|   |_|

 XLiFE++ v2.0.1-r79 (2018-07-20)
 running on july 25, 2018 at 16h08 on Darwin-i386 (MacBook-Pro)

computing FE term intg_Omega grad(u) | grad(v), using 1 threads :  done
reducing FE term A using pseudo reduction method
TermMatrix A computed, size 400 X 400 : SuTermMatrix A_u_v : block (v, u) -> matrix 400 X 400
of real scalar in symmetric_compressed sparse (csr,csc) (1521 coefficients)

solving linear system A * X = B (size 400) using umfpack
/tmp/test (13)  ls
CMakeCache.txt     cmake_install.cmake
CMakeFiles         exec-x86_64-darwin-clang++-4.2.1-Release
CMakeLists.txt     laplace2dP1-dirichlet.cpp
Makefile           log.txt
U_LD_Omega.vtu     print.txt
/tmp/test (14)

The result file U_LD_Omega.vtu can then be displayed using Paraview.

1.5 Alternative installation and usage procedure, without cmake

1.5.1 Installation process

The procedure presented above requires CMake for both the installation and the usage of XLiFE++. Here is an alternative solution that do not use CMake, and is targeted for Unix-like systems, namely Linux and Mac OS, since it needs the execution of a shell script:

  • Download the archive (release or snapshot containing the sources) from

    http://uma.ensta-paris.fr/soft/XLiFE++/?module=main&action=dl

  • Decompress the archive where the software is expected to be installed in the filesystem. This can be in the user’s home or at system-wide level, in which case administrator rights will be necessary. Let’s denote by $XLDIR the directory containing the files.

  • Open a terminal and type in the command:

    bash $XLDIR/etc/installLibs

    This will create a single library in the $XLDIR/lib directory.

XLiFE++ may use other libraries (UmfPack, Arpack, Lapack, Blas) or third party softwares (Gmsh, Paraview), depending on their presence on the computer. The script installLibs performs the installation in an automatic way, without any user action. This means that these libraries or softwares are really used only if they are detected or built.

The installation requires a C++ compiler. The C++ compiler to use can be imposed by the mean of the environment variable CPPCMP before calling the script installLibs (see details in the file $XLDIR/etc/installLibs.README). By default, its name is g++, which is the GNU compiler generally used under Linux ; under Mac OS, this will make use of the native compiler shipped with Xcode, but the GNU compiler may be used as well.

The Fortran library is needed if Arpack is used. Thus, the name of the Fortran compiler, from which is deduced the name of the Fortran library, can also be imposed by the mean of the environment variable FCMP. By default, its name is gfortran.

The installation process conforms to the following rules:

1.
if they are not found in the filesystem, Lapack and Blas are not installed, neither any third party software,
2.
UmfPack and Arpack libraries present on the system are used first and foremost,
3.
if Arpack has not been found in the system and if a Fortran compiler is available, the Arpack library is built locally,
4.
if UmfPack has not been found in the system, SuiteSparse libraries are built locally.

Some options may be used to alter the default configuration:

-noAmo prevents XLiFE++ to use Amos library (computation of Bessel functions),

-noArp prevents XLiFE++ to use Arpack library,

-noOmp prevents XLiFE++ to use OpenMP capabilities,

-noUmf prevents XLiFE++ to use UmfPack (SuiteSparse) libraries.

Thus, in case of trouble, the installation script may be relaunched with one or more of these options. Using all the options leads to the standalone installation of XLiFE++, which is perfectly allowed. The complete calling sequence is then:

bash $XLDIR/etc/installLibs [-noAmo] [-noArp] [-noOmp] [-noUmf]

Finally, the details of the installation are recorded in the file $XLDIR/installLibs.log.

1.5.2 Compilation of a program using XLiFE++

To use XLiFE++:

1.
Create a new directory to gather all the source files related to the problem to be solved.
2.
In this directory, create the source files. This can be done with any text editor. One of them (only) should be a valid "XLiFE++ main file" (see section 1.7). For example, start by copying one of the files present in $XLDIR/examples.
3.
In a terminal, change to this directory and type in the command:

$XLDIR/etc/xlmake

This will compile all the C++ source files contained in the current working directory (valid extension are standard ones .c++, .cpp, .cc, .C, .cxx) and create the corresponding executable file, named xlifeppexec.

4.
Launch the execution of the program by typing in:

./xlifeppexec

The files produced during the execution are created in the current directory.

pict To improve comfort, one can make a link to the script xlmake in the working directory, as suggested in the commentary inside the script:

ln -s $XLDIR/etc/xlmake .

or add $XLDIR/etc to the PATH environment variable. In both cases, the command typed in at step 3. above would then reduce to:

xlmake

pict If OpenMP is used, it may be useful to adjust the number of threads to the problem size. Indeed, by default all threads available are used, which may be completely counter productive for example for a small problem size and a large number of threads. The number of threads to use can be modified at program level, generally in the main function, or at system level, by setting the environment variable OMP_NUM_THREADS before the execution is launched, e.g. with a Bourne shell:

export OMP_NUM_THREADS=2 ; ./xlifeppexec

or with a C shell:

setenv OMP_NUM_THREADS 2 ; ./xlifeppexec

1.6 Alternative installation and usage process, with Docker

This procedure allows to get a pre-installed version of the libraries which are gathered in a so-called Docker container.

This first requires the installation of the Docker application, which can be downloaded from:

https://www.docker.com/products/overview

Once this is done:

  • Download the XLiFE++ image (use sudo docker on linux system):

    docker pull pnavaro/xlifepp

  • Create a workspace directory, for example:

    mkdir $HOME/my-xlifepp-project

  • Run the container with interactive mode and share the directory created above with the /home/work container directory:

    docker run -it --rm -v $HOME/my-xlifepp-project:/home/work pnavaro/xlifepp

    This allows the files created in the internal /home/work directory of the container to be stored in the $HOME/my-xlifepp-project directory of the true filesystem, making them available after Docker is stopped.

  • Everything is now ready to use XLiFE++ as explained in subsection 1.5.2 above, for example:

    xlifepp.sh

    make

    ./exec-x86_64-linux-g++-5-Release

    The files produced during the execution are in the directory $HOME/my-xlifepp-project shared with running Docker, and are then available for postprocessing.

pict The Docker application requires Windows 10, or Mac OS 10.10 and higher. For older OSes, you have to download Docker ToolBox instead. See https://docs.docker.com/toolbox/toolbox_install_windows/ for Windows or https://docs.docker.com/toolbox/toolbox_install_mac/ for Mac OS.

1.7 Writing a program using XLiFE++

All the XLiFE++ library is defined in the namespace xlifepp. Then the users, if they refer to library objects, have to add once in their programs the command using namespace xlifepp;. Besides, they have to use the "super" header file xlife++.h only in the main. A main program looks like, for instance:

#include "xlife++.h"
using namespace xlifepp;

int main()
{
init(_lang=en); // mandatory initialization of xlife++
...
}

Please see chapter 5 for a full description of command line options and of the init function and a full description of how to manage user options.

pict If the users have additional source files using XLiFE++ elements, they cannot include the "super" header file xlife++.h because of global variable definitions. Instead, they will include the "super" header file xlife++-libs.h that includes every XLiFE++ header except the one containing the definition of global variables.

1.8 License

XLiFE++ is copyright (C) 2010-2022 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 XLiFE++ and to redistribute it on a free basis. XLiFE++ is not in the public domain; it is copyrighted and there are restrictions on its distribution. You cannot integrate XLiFE++ (in full or in parts) in any closed-source software you plan to distribute (commercially or not). If you want to integrate parts of XLiFE++ into a closed-source software, or want to sell a modified closed-source version of XLiFE++, you will need to obtain a different license. Please contact us directly for more information.

The developers do not assume any responsibility in the numerical results obtained using the XLiFE++ library and are not responsible of bugs.

1.9 Credits

The XLiFE++ library has been mainly developped by E. Lunéville and N. Kielbasiewicz of POems lab (UMR 7231, CNRS-ENSTA Paris-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 :

  • Y. Lafranche (IRMAR lab), mesh tools using subdivision algorithms, wrapper to Arpack

  • C. Chambeyron (POems lab), iterative solvers, unitary tests, PhD students’ support

  • M.H N’Guyen (POems lab), eigen solvers and OpenMP implementation

  • N. Salles (POems lab), boundary element methods

  • L. Pesudo (POems lab), boundary element methods and HF coupling

  • P. Navaro (IRMAR lab), continuous integration

  • E. Darrigrand-Lacarrieu (IRMAR lab), fast multipole methods

  • E. Peillon (POems lab), evolution of (bi)linear forms