You always need to install the preCICE library and you have a few ways to do this: using a binary package, building from source manually, or building using Spack. You may additionally need to install bindings for Python, Fortran, Matlab or Julia separately.

Installing the core library

The aim of this section is to help you to install preCICE on your system. Depending on your system and your requirements, this process may vary greatly in complexity. To find the right method for you, follow this decision graph, or read on!

Decision tree for installation method

System packages Build from source: Preparation Using Spack Demo Virtual Machine

Note that preCICE is much more than the core library. To find out which library, bindings, adapters, and tutorials versions work together, have a look at the preCICE distribution.

Operating systems

Linux

Linux is the easiest option, see figure above. We provide binary packages for Ubuntu and an AUR package for Arch Linux and Manjaro. If a binary package is not enough for you, keep reading.

macOS

The recommended way is to use Homebrew to install the preCICE dependencies and then compile preCICE from source. You can alternatively build preCICE using Spack.

Microsoft Windows

We are currently working on native builds of preCICE on Windows. Until then, you can Ubuntu on Windows via the Windows subsystem for Linux (WSL). You can then follow all the instructions for Ubuntu, and all codes that work on Linux, also work under WSL. Coupling between a code running on Windows and a code running on Linux should be at least complicated.

In case you want to use "Ubuntu on Windows", note the following: (click to reveal)
  • You first need to enable WSL. Both WSL 1 and 2 are fine. Simplest option: in your system settings, find the menu Turn Windows features on or off and activate WSL there.
  • Whenever you run a coupled simulation, you will get a warning from the Windows firewall. This is because preCICE uses local network addresses to communicate. Give permission to use your network.
  • Whenever you need to start a second terminal, you can just start a second “Ubuntu on Windows” window.
  • In WSL 1, it is complicated to start applications with a graphical user interface, such as ParaView (to visualize your results). Instead, you can install ParaView on Windows and access your files in \\wsl$\Ubuntu\home.

Running preCICE on Windows via WSL, while post-processing in the Windows Desktop

Alternatively, you can get preCICE built with MinGW from MSYS2 (package maintained by the community).

Use cases

Are there packages available for my system?

Check our packages to see if there are binary packages available for your system. If they are available, install them and you are done!

Are you not allowed to install packages? Do you need to build preCICE in multiple variants and configurations?

Maybe you want to compare how preCICE performs when built with different compilers, MPI versions or dependency versions. If this is the case, strongly consider using the preCICE Spack package. Once set up, this will simplify your work tremendously.

Do you need to build the debug version of preCICE?

The debug version of preCICE provides a lot of additional debug information and may be necessary for isolating bugs and understanding error messages. If your system provides packages for all required dependencies, installing from source is the easiest way of installing preCICE. If there are packages missing, things get complicated. At this point it is wiser to invest your time in setting up Spack and install precice using spack than attempting to install everything by yourself.

Do you want to hack preCICE?

Build preCICE from source is the way to go here. In addition to building from source, Spack is useful for building and testing with various dependency version in-place.

Do you just want to play around?

We have a sandbox for your first adventures: a demo virtual machine, with preCICE and most adapters and related tools already installed. Perfect if you just want a system to experiment on in the beginning and then throw it away.

Nothing of the above grabs your attention?

If your system provides packages for all required dependencies, installing from source is the easiest way of installing preCICE. If there are packages missing, things get complicated. At this point it is wiser to invest your time in setting up Spack and install precice using spack than attempting to install everything by yourself.

Installing language bindings

preCICE offers further language bindings. Please refer to the following pages for installation instructions: