Installation

• Download sources
• Dependencies
• Configuration
• Compilation
• Tested Platforms
• Troubleshooting
• Test your installation with examples

Download sources

Latest version released:

• ceps-21.03.tar.gz

It is for now the first version that is released publicly.

Dependencies

CEPS build system relies on CMake. You need CMake version 3.10.1 or higher to be installed.

Before installing CEPS, several required libraries must be installed on your system. You can install these libraries manually, or using the build tool provided (see below).

Manual installation

For now, compiling will require:

• An MPI implementation, such as openMpi
• Eigen
• PETSc, version 3.13 or higher
• CxxTest

One of the following partitionning libraries:

• ParMETIS
• PTScotch

Optional but highly recommended libraries are:

• VTK, version 8.0 or higher

Although some applications will require VTK for outputs.

The build system and some libraries need the following packages to be installed

Distribution	Package names
Ubuntu	pkgconf, libgl1-mesa-dev, libxt-dev, zlib1g-dev
CentOS	pkgconfig, mesa-libGL-devel, libXt-devel, zlib-devel

Also, PETSc configuration step requires Python 2.7 to be installed on your system (hopefully, this remark may be deprecated).

Build tool

You can download and compile those dependencies all at once by using the build system in contrib/build_dependencies. Please refer to the related README file.

Configuration

CEPS uses CMake to configure the code and the build for your system. In order to generate the Makefiles properly, the following environment variables must be set to the absolute paths of your libraries locations:

EIGEN_DIR
PETSC_DIR
PETSC_ARCH (if relevent, cf your PETSc installation)
PARMETIS_DIR (if you want parmetis)
SCOTCH_DIR (if you want scotch)
VTK_DIR
CXXTEST_DIR

This can be done either through export commands, which can be put in your .bashrc or .bash_profile, or using a preload file to give to CMake using the option -C (see below). An example of such a file is given in the contrib directory. If you used the build tool cited above for installation of libraries, a preload file has been generated in the installation directory, ready to use.

To configure:

mkdir build && cd build
cmake ..

Or

mkdir build && cd build
cmake -C /path/to/the/preload/file ..

Notes on compatible CEPS options:**

It is highly recommended to compile CEPS with the same MPI compiler you used to build PETSc. To do this, use the following cmake command line:

CXX=/path/to/the/mpi/compiler/bin/cxx cmake -C /path/to/the/preload/file ..

Also, CEPS must be compiled with the same data types as the linked libraries. For example, if ParMETIS was configured with 64-bit integers, you should add the Ceps option WITH_64_BIT_INTEGERS. The same goes for PETSc for single or double precision floating point numbers, with the option WITH_DOUBLE_PRECISION. Example:

cmake -DWITH_64_BIT_INTEGERS=ON -DWITH_DOUBLE_PRECISION=OFF ..

will compile CEPS with 64 bit integers and single precision floating point values.

Deactivating a partitionner**

If both partitioners are installed on your system and you want to generate CEPS executables with only one, add either the option -DUSE_PARMETIS=OFF or -DUSE_PTSCOTCH=OFF to the cmake command.

Compilation

Once the configuration step is complete, you can use:

make          : build all applications (main files in the src/applications directory)
make my_appli : build only my_appli
make examples : build only example executables (dev)
make tests    : build only unit tests (dev, be careful of plural 'tests')

In order to run the executables, you may have to link some shared VTK libraries at runtime. To do so:

export LD_LIBRARY_PATH="/path/to/VTK/lib:$LD_LIBRARY_PATH"

Once built, the tests can be run by using make test or just ctest.

Tested platforms

CEPS build, as well as the build_dependencies script are tested on the following architectures:

• Through continuous integration:
  • Ubuntu latest (docker image)
  • CentOS latest (docker image)
  • OSX 10.13 (High Sierra) with Xcode 9.4 (deactivated because of inconsistencies and unability to configure the runner)
• Developpers machines:
  • Ubuntu 20.04
  • Gentoo
  • Debian Wheezy

Troubleshooting

• cmake not found or cmake version not compatible.

Some distributions provide old versions of CMake in their package repositories. You can download CMake and compile it on your own. Then, instead of just typing cmake at configuration step, provide the full path to your newly installed cmake binary. For example:

/home/me/mySofts/myCmakeInstallDir/bin/cmake ..

• Be aware that cmake may cause problem with paths with non-ASCII characters (French developpers may encounter this with accentuated letters!)
• MPI troubles when running ctest

Note : all the following flags can be cumulated. Some of these flags may already be set at configuration after PETSc's options.

If you are running ctest as root, then you must add this option at configuration step, on top of all other options:

cmake -DCXXTEST_MPI_FLAGS="--allow-run-as-root" <other options> ..

If you encounter ressources assignment problems, try

cmake -DCXXTEST_MPI_FLAGS="--oversubscribe" <other options> ..

If the VTK libraries cannot be found at runtime, try

cmake -DCXXTEST_MPI_FLAGS="-x LD_LIBRARY_PATH" <other options> ..

Test your installation by running examples.

Several examples of input files are located in the directory called examples (!). The commands that must be executed to run the examples are given in the header of each input file. For example, in order to run the monodomain simulation on 4 cores, assuming you have compiled CEPS in a build directory, against a MPI implementation located in /path/to/my/ceps/libs, and that you have not moved the executables:

cd examples
/path/to/my/ceps/libs/bin/mpiexec -n 4 ../build/src/applications/monodomain monodomain.in -v

If all goes well, you will now have a results directory which contains the output of the simulation. You can visualize the results by opening the .pvd file in this directory with Paraview. An activation map is written in the *_APD.pvd file.