Download and install

Warning: some background knowledge on the following topics is required. Before getting started, please make sure to get familiar with them (a few introductory references are listed, but many more resources can be easily found on the web).

• Command line interface on Unix/Linux (tutorial, cheat sheet).
• Command line text editors, such as Vim (cheat sheet), Emacs (cheat sheet), or nano (cheat sheet).
• Git (Pro Git book, cheat sheet, visual cheat sheet).

Table of contents

• Dependencies
• Step 0 - Install lifex dependencies
  • mk
  • lifex-env
  • Spack
  • Docker
• Step 1 - Install lifex
  • Step 1.0 - Setup your GitLab account
  • Step 1.1 - Get lifex
  • Step 1.2 - Configure lifex
  • Step 1.3 - Compile lifex
  • Step 1.4 - Check lifex installation
• Step 2 - What's next?

Dependencies

lifex has the following dependencies:

• A C++17-compliant compiler and related standard library (such as GCC)
• An MPI installation (such as OpenMPI or MPICH)
• CMake ≥ 3.12.0
• deal.II ≥ 9.3.1
• VTK ≥ 9.0.3
• Boost ≥ 1.76.0
• (Optional) Doxygen and Graphviz

You need to install the previous dependencies in order to be able to successfully configure and build lifex.

We recommended you to follow step 0 for a pain-free procedure to get all the dependencies you need. Then you can safely go through step 1.

Note (for advanced users): you may also consider to install all of the dependencies manually. Please refer to the above links for further instructions.

Step 0 - Install lifex dependencies

Different procedure are available depending on the operating system you are using.

The defaut installation relies upon the

• mk (Linux, recommended for MOX developers)

package.

Only if the previous option does not work for you, you may consider one of the following alternatives:

• lifex-env (Linux, macOS)
• Spack (Linux, macOS)
• Docker (Linux, macOS, Windows)

Note: Windows 10 users may consider installing Windows Subsystem for Linux (WSL), a compatibility layer for running Linux binaries on a Windows host (version WSL 2 recommended). All the above Linux options, including mk, are available for WSL.

mk

For Linux systems, we have packed a number of scientific computing softwares, including all lifex dependencies, in a x86-64 binary package called mk.

The recommended procedure is to install mk directly on your system as described below.

Note: in case you have a previous (< v2024.0) installation of mk, delete it with sudo rm -rf /u/.

Note: the following steps 1 and 2 are not needed on MOX clusters.

1. Download the mk archive from this link.
2. Open a terminal in the folder containing the archive mk-2024.0-lifex.tar.gz just downloaded and type the following command:

   sudo tar xvzf mk-2024.0-lifex.tar.gz -C /

3. Add the following lines to your ${HOME}/.bashrc file (or equivalent):

   # mk.
   source /u/sw/etc/bash.bashrc
   module load gcc-glibc/11.2.0 dealii vtk

4. Restart the shell.

You can now proceed to step 1.

Note: the mk modules are compatible with any recent enough Linux distribution. On some (old) distros, you may experience errors like "version GLIBC_X.YY not found". If this is your case, we recommend you to update your operating system to a more recent version, possibly shipping a glibc version not older than X.YY.

lifex-env

Note: Skip this step if you have already installed lifex dependencies using one of the other methods in this section.

lifex-env is a set of shell scripts that download, configure, build, and install lifex dependencies on Linux-based systems.

1. Follow the instructions available here to install lifex-env (this step may require a long time to complete).
2. Add the following line to your ${HOME}/.bashrc file (or equivalent), replacing /path/to/lifex-env/ with the prefix where lifex-env has been installed:

   # lifex-env.
   source /path/to/lifex-env/configuration/enable_lifex.sh

You can now proceed to step 1.

Spack

Note: Skip this step if you have already installed lifex dependencies using one of the other methods in this section.

lifex dependencies are also available on Spack, a package manager for Linux and macOS.

Make sure that a C/C++ compiler, python, make, git, curl are installed.

More details about deal.II on Spack can be found here.

1. Add the following lines to your ${HOME}/.bashrc file (or equivalent), replacing /path/to/spack/ with the path where you want to install Spack:

   export SPACK_ROOT=/path/to/spack/
   export PATH=${SPACK_ROOT}/bin:${PATH}

2. Clone Spack with:

   mkdir -p ${SPACK_ROOT}
   cd ${SPACK_ROOT}
   git clone https://github.com/spack/spack.git ./

3. Add the following line to your ${HOME}/.bashrc file (or equivalent):

   source ${SPACK_ROOT}/share/spack/setup-env.sh

4. Configure Spack as an environment module manager with

   spack install environment-modules

5. Add the following line to your ${HOME}/.bashrc file (or equivalent):

   source $(spack location -i environment-modules)/init/bash

6. Install deal.II and VTK (this step may require a long time to run) with

   spack install dealii@9.3.1
   spack install vtk@9.0.3 ^mesa~llvm

7. Add the following lines to your ${HOME}/.bashrc file (or equivalent):

   spack load openmpi
   spack load cmake
   spack load boost
   spack load dealii
   spack load vtk

You can now proceed to step 1.

Docker

Note: Skip this step if you have already installed lifex dependencies using one of the other methods in this section.

Two minimal Ubuntu distributions, with lifex-env and mk installed respectively, are available for use with Docker.

First you need to install Docker following these instructions.

The lifex image(s) can be downloaded using the following commands (root privileges are required):

docker login registry.gitlab.com
docker pull registry.gitlab.com/lifex/lifex/mk
# Or: docker pull registry.gitlab.com/lifex/lifex-env

Then a corresponding container can be run through

docker run -it registry.gitlab.com/lifex/lifex/mk
# Or: docker run -it registry.gitlab.com/lifex/lifex-env

Please refer to Docker documentation for further instructions on how to use Docker.

You can now proceed to step 1.

Step 1 - Install lifex

Step 1.0 - Setup your GitLab account

It is strongly recommended that you associate an SSH key to your GitLab account in order to be able to use all of the git functionalities without being prompted to enter your credentials each time.

1. Generate an SSH key on your system following these steps.
2. Add it to your GitLab account following these instructions.
3. Configure git with your real name and email address:

   git config --global user.name "Name(s) Surname(s)"
   git config --global user.email "my.email@address.com"

   Note: the settings above must be formatted properly, i.e. names and surname(s) should start with an uppercase letter and be separated by a (single) space character.

   Note: please make sure that these settings are consistent on all computers you are using lifex on.

Step 1.1 - Get lifex

Move to a target folder (make sure its path does not contain special characters such as &, $ or brackets) and run:

git clone --recursive git@gitlab.com:lifex/lifex.git

Note: if you are unable to use the SSH protocol, a standard-authentication HTTPS URL is available:

git clone --recursive https://your_username@gitlab.com/lifex/lifex.git

Step 1.2 - Configure lifex

First create a build folder and enter it:

cd /path/to/lifex
mkdir build
cd build

Then run lifex configuration with

cmake ..

Add the optional -DCMAKE_BUILD_TYPE=Debug flag to build with debug symbols and no compile-time optimization.

Note (for developers): lifex can use either Trilinos or PETSc as linear algebra backends. The backend can be customized with -DLIN_ALG=Trilinos (the default value) or -DLIN_ALG=PETSc.

Note (for developers): in order to enable Doxygen and Graphviz, make sure that the doxygen and dot executables are in your system PATH environment variable (see also Coding guidelines).

Note (for advanced users): if you compiled and installed deal.II, VTK or Boost manually in any other way than mk, Spack or Docker, specify the installation directories with the cmake flags -DDEAL_II_DIR=/path/to/dealii/, -DVTK_DIR=/path/to/vtk/ and -DBOOST_DIR=/path/to/boost/.

Note (for Docker users): please specify the cmake flag -DMPIEXEC_PREFLAGS="--allow-run-as-root" to enable the container to run parallel executables.

Step 1.3 - Compile lifex

Run the compilation with

make -j<N>

where <N> is the desired number of parallel processes (e.g. make -j2). By default, this builds all the targets available.

Note: this step can be very memory intensive, especially if more than one process is used for compilation (i.e. if <N> is greater than one). If compilation fails, consider reducing the number of processes.

If you only need to compile part of the library, specific targets can be selected with, e.g.:

make -j<N> electrophysiology mechanics

(make help prints the list of all possible targets).

Step 1.4 - Check lifex installation

Large additional data and meshes are required by automatic tests and available externally. Run

cd /path/to/lifex
git submodule update --init

to download (or update) them.

Finally, to check whether everything works successfully, setup and run the testing platform with

make -j<N> setup_tests
ctest -L test_soft

Note: by default, parallel tests related are run in parallel using MPI on all the processors detected on the host system. Configure lifex with the cmake flag -DMPIEXEC_MAX_NUMPROCS=<N> to set a custom number of parallel processes.

Note (for developers): more computationally intensive tests can be run with ctest -L test_hard.

You did it, have fun with lifex!

Step 2 - What's next?

1. Learn how to run a lifex app by visiting Run a lifex app.
2. If you are a new developer, make sure to read and follow our Coding guidelines.
3. Build lifex into a portable binary package: Building portable executables