Building from source - Dependencies

How to use this page?

Start by checking if there is a guide for your system. It will include all required steps to get preCICE ready to build.

If there is no guide for your system, find out if there are suitable system packages for the dependencies. Then use the dependencies section to install all missing dependencies from source.

After all dependencies are ready to use, proceed with configuring the preCICE build.

Overview

The following is an overview of the required dependencies of preCICE. Note that we always strive to be forwards-compatible. If you find a problem with preCICE and a latest versions of these dependencies, please let us know.

Required dependencies

Dependency	Version required	Availability
C++ compiler	C++17	C++17 compiler support
CMake	>= 3.22.1
Eigen	>= 3.4.0
Boost	>= 1.74.0
libxml2	>= 2

Note that more recent versions of some dependencies (e.g., Boost) might also need more recent or upcoming releases of preCICE.

Optional dependencies

Dependency	Required for	Version required	Availability
MPI (opt-out)	Communication over MPI	implementation of MPI-3	Various implementations
PETSc (opt-out)	Some RBF mappings	>= 3.15
Ginkgo (opt-in)	Some RBF mappings	>= 1.8, with Kokkos >= 4.1
Python (opt-out)	Python Action interface	>= 3

Dependencies

This section lists all dependencies alongside required versions and steps on how to install them from source. Meaning, installing dependencies based on the steps in this section should be the last resort for normal users. Prefer to follow the system guides and only install custom versions if you have a reason to do so.

C++ compiler

preCICE requires a C++ compiler with full C++17 support. The following table lists the minimal requirement for compiler versions:

If you are using Debian/Ubuntu, the build-essential package will install everything needed.

When compiling with MPI enabled (the default) and using your MPI compiler wrapper as compiler, then it needs to use a suitable compiler. For example, check if the mpicxx --version reports a compatible compiler version. Check the section on MPI for more information.j

CMake

preCICE requires the build system CMake at a minimal version of 3.22.1 (CMake 4 also works). You can check your CMake version using cmake --version.

Depending on the versions of CMake and Boost, CMake may not find all libraries in boost and display warnings when configuring preCICE. This can be safely ignored, and can be fixed by upgrading CMake.

History of required version:

Download CMake binaries

Download the official binaries for your platform and extract them into a folder. Then extend the path environment variable by executing the following:

export PATH="$PATH:/path/to/extracted/location/version/bin"
cmake --version

This should now display the version of the downloaded release. If the version is correct, you can make this change persistent by appending the above export statement to your .bashrc.

Eigen

preCICE uses Eigen for linear algebra computations and for a version of global RBF mappings which does not require PETSc.

History of required version:

Download the Eigen headers

Eigen is a header-only library, i.e. it is compiled into preCICE and does not require linkage. Download the sources from their latest compatible release and extract them to some location. The folder of your choice should now contain a folder called eigen-x.y.z for version x.y.z. Set the environment variable Eigen3_ROOT to the eigen-x.y.z folder by adding this to your ~.bashrc.

export Eigen3_ROOT=/path/to/eigen/eigen-x.y.z

Boost

preCICE uses Boost for several features. The minimum required version is 1.74.0, but newer Boost versions are not always compatible to previous ones.

You might save some time and space by installing only the necessary libraries:

• boost_log
• boost_log_setup
• boost_thread
• boost_system
• boost_filesystem
• boost_program_options
• boost_unit_test_framework

These libraries may also depend on other Boost libraries. Make sure that these get installed, too.

The following header-only Boost libraries are also needed: asio, vmd, geometry, signals2, container, ranges.

History of required versions:

For help, see also the ranges set in the Spack recipe.

Build boost from source

1. Download and extract Boost into any directory. Switch to that directory.

2. Prepare the installation, selecting only the libraries that need to be built (this does not affect the header-only libraries). Select a prefix to install Boost to. This will later contain the directories include and lib. On systems using modules, we recommend to specify the toolset manually by additionally passing --with-toolset=gcc (or intel).

   Now run with the prefix of your choice:

   ./bootstrap.sh --with-libraries=log,thread,system,filesystem,program_options,test --prefix=<prefix>
   

3. Build and install the libraries. Depending on your choice, you may need root access.

   ./b2 install      # user has write access to the prefix
   sudo ./b2 install # user does not have sufficient permissions
   

   The directory you chose as prefix now contains libraries in <prefix>/lib and the all the Boost headers in <prefix>/include. You may now safely remove the boost directory from step 1.

4. If you selected /usr/local as prefix, you probably do not have to do anything else (depends on your system). If you used a custom <prefix>, you have to add the following line to your .bashrc:

   export CMAKE_PREFIX_PATH=$CMAKE_PREFIX_PATH:<prefix>/lib/cmake/Boost-1.87.0
   

   The path points to the file BoostConfig.cmake which is required by CMake. If this path does not exist, you can also run locate BoostConfig.cmake to determine the path to the file.

For more information, please refer to the “Getting Started” instructions of Boost.

libxml2

preCICE uses libxml2 for parsing the configuration file.

Since libxml2 is available on close to any system you can imagine, double check if there are any system packages before attempting to build this dependency from source.

Install libxml2 from source

1. Download the latest release of libxml.
2. Extract the sources to a location of your choice.
3. Choose a directory to install the library to and use it as <prefix>.

4. Build and install the library

   ./autogen --prefix=<prefix>
   make
   make install
   

5. If you did not select /usr/local as prefix, you need to make the installation visible to the linker and compiler. Add the following to your ~/.bashrc replacing prefix with the chosen directory:

  export LIBRARY_PATH="<prefix>/lib:$LIBRARY_PATH"
  export LD_LIBRARY_PATH="<prefix>/lib:$LD_LIBRARY_PATH"
  export CPLUS_INCLUDE_PATH="<prefix>/include:$CPLUS_INCLUDE_PATH"
  export PKG_CONFIG_PATH="<prefix>/lib/pkgconfig:$PKG_CONFIG_PATH"

MPI

preCICE optionally requires an implementation of the MPI-3 specification for communication, which is provided by all major vendors including OpenMPI, MPICH, and Intel MPI.

You can build preCICE without MPI in case of compatibility issues with a certain solver (e.g. a closed source solver with a binary-distributed MPI version, or when running on Windows). To do so, use -DPRECICE_FEATURE_MPI_COMMUNICATION=OFF. In such a case, you can still use TCP/IP sockets for inter- and intra-participant communication, instead. This might, however, result in lower performance and is, therefore, not recommended if not necessary.

Keep in mind that, if you already installed PETSc, MPI must also already be installed.

PETSc

preCICE optionally uses PETSc (at least 3.15) for some global RBF mappings and is highly recommended for large cases. For small/medium-size cases, preCICE can still do a global RBF mapping in parallel without PETSc. If you don’t need this feature, you may specify -DPRECICE_FEATURE_PETSC_MAPPING=off when building preCICE.

History of required versions:

Build PETSc from source

If you prefer to install the most recent version from source, do the following:

1. Download it or get the repository using git clone -b release https://gitlab.com/petsc/petsc.git petsc
2. Change into that directory and compile with or without debugging: ./configure --with-debugging=0 (disable debugging for optimal performance)
3. Use the make command as the configure script proposes, e.g. make PETSC_DIR=/path/to/petsc PETSC_ARCH=arch-linux-c-opt all Further documentation see the PETSc installation documentation.

4. Usage: You will need to add PETSc to your pkg-config path (PKG_CONFIG_PATH). Here is an example:

   export LD_LIBRARY_PATH="/path/to/petsc/lib:$LD_LIBRARY_PATH"
   export PKG_CONFIG_PATH="/path/to/petsc/lib/pkgconfig:$PKG_CONFIG_PATH"
   

   Check that pkg-config --libs --cflags PETSc returns valid paths.

Ginkgo

preCICE optionally uses Ginkgo for GPU- and OpenMP-accelerated global radial-basis function mappings. To enable the feature in preCICE, use the CMake option -DPRECICE_FEATURE_GINKGO_MAPPING=ON. Using this feature in preCICE requires additionally Kokkos.

Both packages follow the usual CMake build instructions and can be downloaded on the GitHub release page for Ginkgo and Kokkos. For Kokkos, system packages might be available through your package manager as well.

History of required versions:

Python

preCICE optionally uses Python for the Python action interface (only used for rare applications). If you don’t need this feature, you may specify -DPRECICE_FEATURE_PYTHON_ACTIONS=off. In particular, you don’t need to build with Python if you only want to use the preCICE Python bindings.

You probably already have Python installed. However, in order to use the Python action interface, you also need to install NumPy and the header files for Python and NumPy.

History of required versions:

System guides

If you want build preCICE on your own computer and you are using one of the following Linux distributions, we provide a summary here to quickly install the dependencies. Other modern versions of popular Linux distributions are also perfectly compatible, here we just list a few popular options. Contributions to this section are particularly welcome (click “Edit me”). Trouble? Ask for help.

Arch Linux

Good news: preCICE is already on AUR, so you can directly use or modify the respective PKGBUILD.

See also the Arch Linux Dockerfile used in the preCICE tests.

The same instructions apply to Manjaro, EndeavourOS, and other derived distributions.

Debian

With every release, we also ship binary packages for Debian. However, if you still want to build from source, everything is available through the distribution’s repositories:

su
apt update && \
apt install build-essential cmake libeigen3-dev libxml2-dev libboost-all-dev petsc-dev python3-dev python3-numpy

These instructions are known to work with Debian 10, and should apply to later releases as well (release history).

Fedora

In Fedora, everything is available through the distribution’s repositories:

sudo dnf update
sudo dnf install gcc-c++ cmake libxml2-devel boost-devel openmpi-devel petsc-openmpi-devel eigen3-devel python3-devel

Afterwards, start a new terminal, to make MPI discoverable (read more about MPI on Fedora). Before configuring & building preCICE, load MPI using the module:

module load mpi/openmpi-x86_64

In case module is not available, you may need to log out and in again first. If you use the docker image of fedora, you need to install the support for environment modules: sudo dnf install environment-modules

These instructions are known to work with Fedora 43, and should apply to later releases as well (release history). See also the Fedora Dockerfile used in the preCICE tests.

OpenSUSE

In OpenSUSE, things are a bit more complicated (please contribute in this section). Get the basic dependencies:

sudo zypper refresh
sudo zypper install gcc-c++ make cmake libxml2-devel eigen3-devel
sudo zypper install libboost_log*-devel libboost_thread*-devel libboost_system*-devel libboost_filesystem*-devel libboost_program_options*-devel libboost_test*-devel
sudo zypper install python3-devel python3*-numpy  # optional
sudo zypper install openmpi5-devel                # optional, other versions work as well

If you don’t already have a fitting combination of PETSc (not shown here), disable the respective feature when configuring preCICE:

cmake -DPRECICE_FEATURE_PETSC_MAPPING=OFF <options as usual>

or get PETSc from source. See also a related discussion on the preCICE forum for more details.

These instructions are known to work with OpenSUSE Leap 16, and should apply to later releases as well (release history).

Rocky Linux

Rocky Linux very closely follows the conventions previously set by CentOS. We first need to install common development tools, enable the CRB repository (only for Eigen), install the dependencies, load the MPI module, and continue with building preCICE.

1. First, install the Development Tools group (compilers, Git, make, pkg-config, …):

   sudo dnf update
   sudo dnf install dnf-plugins-core
   sudo dnf groupinstall "Development Tools"
   

2. Then, enable the CRB repostitory to install Eigen3, and the install the rest of the available preCICE dependencies:

   sudo dnf config-manager --set-enabled crb
   sudo dnf install eigen3-devel
   sudo dnf install cmake libxml2-devel boost-devel openmpi-devel python3-devel
   

3. Before configuring & building preCICE, load MPI (you may need to log out and in again, if module is not found):

   module load mpi/openmpi-x86_64
   

4. Unfortunately, PETSc does not seem to be available in this distribution., so we need to switch that off later when building preCICE. If you don’t plan to use RBF mappings in large parallel cases, you can continue without installing PETSc and build preCICE with -DPRECICE_FEATURE_PETSC_MAPPING=OFF. If you need PETSc, follow the steps in the PETSc section and you are done.

These instructions are known to work with Rocky 9, 10, and should apply to later releases as well (release history).

Ubuntu

With every release, we also ship binary packages for Ubuntu. However, if you still want to build from source, everything is available through the distribution’s repositories:

sudo apt update && \
sudo apt install build-essential cmake libeigen3-dev libxml2-dev libboost-all-dev petsc-dev python3-dev python3-numpy

These instructions are known to work for Ubuntu 22.04, 24.04, and they should apply to later releases as well (release history). See also the Ubuntu Dockerfile used in the preCICE tests.

macOS

First, install XCode Command Line Tools from the Apple Developer page or from XCode.

You can then install all dependencies using Homebrew:

brew install cmake eigen libxml2 boost petsc openmpi python3 numpy

or, alternatively, using MacPorts

port install cmake eigen3 libxml2 boost petsc openmpi python3 numpy

These instructions were written for macOS Catalina (10) (release history). We are aware of users using preCICE in newer macOS versions, while our automated tests run on the GitHub Actions macos-latest runner. Contributions to this section would be particularly helpful.