Regular Installation on Linux#

../_images/linux.png

Important

Distributions on which compatibility was tested are: Ubuntu 22.04 LTS, Ubuntu 24.04 LTS, Centos 7 and Manjaro.

Lethe requires a modern version of the deal.II library and its dependencies (MPI, numdiff, p4est, trilinos and METIS). At the time of this writing, deal.II 9.7, deal.II 9.8 and deal.II 9.9pre (the master branch version) are supported. A dealii fork is maintained by the Lethe team. This fork does not include any modification to deal.II library, but it is the latest version with which Lethe was tested.

Important

Since September 2026, Lethe requires deal.II to be compiled with magic_enum (DEAL_II_WITH_MAGIC_ENUM=ON). The configuration of Lethe stops with an error if it is not the case. deal.II 9.8 and newer ship a bundled copy of magic_enum and enable it by default, so no action is required with these versions, including when deal.II is installed with candi or manually. The deal.II 9.7.1 packages installed with apt and the deal.II Docker images also include it. Only a deal.II 9.7 installation compiled from source requires a separate installation of magic_enum (see Installing deal.II manually).

Lethe installation steps:

  1. Installing deal.II

  2. Installing Lethe

Installing deal.II and its dependencies:

  1. Installing deal.II using apt (recommended for users)

  2. Installing deal.II using Candi (recommended for developers)

  3. Installing deal.II manually (recommended for experienced developers)

Installing deal.II using apt#

This is done following this procedure.

In case you are using Ubuntu, you will need to update the backports:

sudo add-apt-repository ppa:ginggs/deal.ii-9.7.1-backports
sudo apt update

To install deal.II, run:

sudo apt-get install libdeal.ii-dev

To verify if the correct version of deal.II is installed, run:

apt show libdeal.ii-dev

The Version field of the output should start with 9.7.1.

Note

If the installed version is other than 9.7.1, follow this link.

Installing deal.II using Candi#

To install the dependencies (MPI, p4est, trilinos and METIS) all together using candi, the procedure on the candi repository can be followed.

Clone the candi git repository in a folder of your choice (e.g. /home/username/software). Edit the candi.cfg file to alter which dependencies are compiled. This file should notably be used to force the installation of the deal.II master version directly instead of the current stable version by setting DEAL_II_VERSION=master.

The following packages (which are specified by the PACKAGES lines) should be installed:

PACKAGES="load:dealii-prepare"
PACKAGES="${PACKAGES} once:numdiff"
PACKAGES="${PACKAGES} once:opencascade"
PACKAGES="${PACKAGES} once:parmetis"
PACKAGES="${PACKAGES} once:p4est"
PACKAGES="${PACKAGES} once:trilinos"
PACKAGES="${PACKAGES} dealii"

Other packages can be disabled by simply commenting out the lines (adding a # at the beginning of the lines)

To ensure that the Lethe test suite works, deal.II must be configured with p4est version 2.3.6. Otherwise, application tests that include restart files will fail. Since candi installs a more recent version of p4est by default, select version 2.3.6 in the deal.II-toolchain/packages/p4est.package file of candi: uncomment its VERSION=2.3.6 line and the CHECKSUM line that follows it, and comment the VERSION and CHECKSUM lines of the default version.

Note

deal.II 9.8 and newer ship a bundled copy of magic_enum, which is used if magic_enum is not found on your system. deal.II 9.7 does not. To do so, install magic_enum first (e.g. sudo apt-get install libmagicenum-dev on Ubuntu 24.04 or later). Then, modify the following line in the candi.cfg file: DEAL_II_CONFOPTS="-DMAGIC_ENUM_DIR=path/to/your/magic_enum/installation".

From the candi folder, the installation of candi can be launched using:

./candi.sh -j$numproc --prefix=$path

where $numproc is the number of threads you want to use to compile deal.II and $path the installation prefix that is desired (e.g. /home/username/software/candi).

Tip

For a computer with 8Gb of RAM, 1 thread (numproc=1) should be used. For 16 Gb, 4 threads is reasonable. For 32 Gb, 16 threads or more can be used.

After installation, you should have a deal.II-candi folder in the installation prefix directory, with the dealii folder of the desired version (see section Updating deal.II), as well as the required dependencies (p4est, trilinos, etc.).

After installation, add the following lines variable to your .bashrc :

  source candi/install/prefix/configuration/enable.sh
  export DEAL_II_DIR=candi/install/prefix/deal.II-<version>

Installing deal.II manually#

Clone deal.II from the deal.ii official repository

git clone https://github.com/dealii/dealii

Configure deal.II in a build folder at the same level as the source code

mkdir build
cd build

Depending on how you have installed p4est, Trilinos and METIS, you may need to specify the installation folder of the three libraries.

cmake ../dealii -DDEAL_II_WITH_MPI=ON -DDEAL_II_WITH_TRILINOS=ON -DTRILINOS_DIR=path/to/your/trilinos/installation -DDEAL_II_WITH_P4EST=ON -DP4EST_DIR=path/to/your/p4est/installation  -DDEAL_II_WITH_METIS=ON -DMETIS_DIR=path/to/your/metis/installation -DDEAL_II_WITH_MAGIC_ENUM=ON -DCMAKE_INSTALL_PREFIX=/path/to/desired/installation`

Note

deal.II 9.8 and newer ship a bundled copy of magic_enum, which is used if magic_enum is not found on your system. However, deal.II 9.7 does not. To do so, install magic_enum first (e.g. sudo apt-get install libmagicenum-dev on Ubuntu 24.04 or later). Then, add -DMAGIC_ENUM_DIR=path/to/your/magic_enum/installation to the command above if it is not installed in a standard location.

Compile deal.II

make -j$numprocs install

Create an environment variable for the deal.II directory

export DEAL_II_DIR=/path/to/dealii/installation

It is generally recommended to add the variable to your bashrc so it is always loaded:

echo "export DEAL_II_DIR=/path/to/dealii/installation" >> ~/.bashrc

Installing Lethe#

Clone Lethe from the Lethe official repository.

git clone https://github.com/chaos-polymtl/lethe --single-branch

Create a build folder at the same level as the lethe folder

mkdir build
cd build

Note

Installing the mold linker before configuring Lethe significantly reduces the compilation time:

sudo apt-get install mold

Every application and every unit test of Lethe is a separate executable, and linking them with the default GNU linker (ld) is slow, especially in Debug. When mold is installed, Lethe links with it automatically, unless deal.II was already configured with a linker of its own, and CMake prints Linking Lethe with mold during the configuration.

Selecting mold requires GCC 12.1 or newer. With an older compiler, such as the GCC 11 of Ubuntu 22.04, install lld instead, which Lethe uses when mold is not available:

sudo apt-get install lld

This behavior can be disabled with -DLETHE_USE_FAST_LINKER=OFF, and a specific linker can be requested with -DCMAKE_LINKER_TYPE.

Build Lethe choosing the compilation option (Debug or Release). You can also optionally specify a path to an installation directory of your choice. We recommend that you do so, since this makes using Lethe much more comfortable.

cmake ../lethe -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=/home/username/path/to/installation

or

cmake ../lethe -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/home/username/path/to/installation

Then you can compile:

make -j$numprocs install

This will install lethe to the installation folder you provided in the previous step. You can now add the following lines to your .bashrc:

export PATH=$PATH:/home/username/path/to/installation/bin

to add the Lethe executables to your path.

Warning

Hyper-threading will result in poor performance when running Lethe. Make sure that it is not turned on for your machine if you have more logical CPU(s) than the number of Core(s). To obtain this information, you can run the following command in a linux terminal:

lscpu | grep -E '^Thread|^Core|^Socket|^CPU\('

To limit the number of thread you can set the environment variable OMP_NUM_THREADS to 1 in the terminal you are running the application or in your .bashrc file to make it the default:

export OMP_NUM_THREADS=1

Testing Your Installation#

Lethe comes pre-packaged with an extensive test suit for all of its modules. It can be used to test the validity of your installation. Within the build folder, the test suite can be launched with the following command:

ctest -j$numprocs

where $numprocs can be the number of physical cores on your machine. Do not be afraid if some tests fail on your machine, they are not always as portable as we would like them to be.

Warning

The lethe test suites requires that deal.II be configured with p4est 2.3.6 otherwise the tests that include restart files or that use the lethe-fluid-vans or lethe-fluid-particles executables will fail. Even if the tests fail, the application should work as expected on your machine(including the restart capabilities).

Updating deal.II#

Through apt#

As all other apt packages, run:

sudo apt update
sudo apt upgrade -y

Through the Git Repository#

The deal.II version supported by Lethe is updated and tested every week or so, see the repository here. If Lethe was installed with this forked version of deal.II, updating your deal.II installation is as simple as pulling the repository and recompiling the deal.II library. If your deal.II was installed manually using the deal.II master repository, the same process can be used.

With Candi#

In the candi folder (for instance, /home/username/software/candi), modify the candi.cfg to get the latest dealii version, by changing the DEAL_II_VERSION variable in the case of an official release with its number (e.g. v9.8.0), or by changing it to master in the case of a development release. The candi.cfg file should contain:

# Install the following deal.II version (choose master, v9.8.0, ...)
DEAL_II_VERSION=master

Run the command ./candi.sh to install the new version of dealii.

In your /home/deal.ii-candi folder, you should have a new folder with the dealii updated version (specified in DEAL_II_VERSION, or deal.II-master in the case of development version)

You might need to delete the build folder of Lethe and redo the installation process from scratch, but this is rarely the case.