The coupling library preCICE

In this exercise we want to use the coupling library preCICE. We will use the current version (1.6.1) that has been release in september.

“preCICE is an open-source coupling library for partitioned multi-physics simulations, including, but not restricted to fluid-structure interaction and conjugate heat transfer simulations. Coupling adapters exist for OpenFOAM, CalculiX, Code_Aster, FEniCS, deal.II, and many more.”

Taken from the preCICE homepage

Getting started

You can learn more about preCICE on the preCICE homepage and the GitHub repository of preCICE. Checkout the preCICE wiki that explains how to get and use preCICE. It also provides a lot of examples of coupled simulations run with preCICE. In order to get a feeling for how preCICE works you should go through the preCICE tutorial in browser. You don’t have to install anything on your machine for this tutorial and the test setting is also explained on the wiki in the section FSI tutorial.

Installation

There are plenty ways of getting preCICE. We have installed preCICE on the cluster so you can use it. The easiest way would be via the precompiled package available on GitHub. Alternatively preCICE can be compiled using CMake. Compilation should be easy when using Ubuntu 18.04 as the required dependencies can be installed from the package manager.

For the exercises you do not need to compile preCICE with all features! Besides things you already have (C++ compiler and CMake) you mainly need:

  • Eigen

  • Boost (version >= 1.65.1)

  • libxml2

  • (Optional) a MPI compiler if you want to use preCICE in parallel

For detailed information about all the ways to install preCICE and how to do it, please check out the section 1. Get preCICE in the preCICE wiki.

Warning

Please make sure that you build with shared libraries, i.e. configure the preCICE with -DBUILD_SHARED_LIBS=ON!

Note

It could be beneficial to compile preCICE as debug build for testing. The output will be more verbose such that it is easier to find problems. For productive runs it makes sense to compile preCICE as release build. Both builds will be provided on the cluster.

Preparing your code to use preCICE

In order to use preCICE in your code, we have to edit the file CMakeLists.txt in the src/ directory of your project and set the necessary environment variables. You have to add the following lines to the CMakeLists.txt file:

# Add preCICE to project
find_package(precice REQUIRED CONFIG)
target_link_libraries(${PROJECT_NAME} PRIVATE precice::precice)

If you get an error afterwards, you might have to replace the line

target_link_libraries(${PROJECT_NAME} ${VTK_LIBRARIES})

by

target_link_libraries(${PROJECT_NAME} PRIVATE ${VTK_LIBRARIES})

Depending on the installation method that you use, you also have to set some environment variables. You can either set the CMAKE_PREFIX_PATH or precice_DIR variable. We will set precice_DIR in the preCICE module on the cluster. In order to set the variable in the terminal (for example in bash) you can use the following command

export precice_DIR=PathToPrecice/lib/cmake/precice

If it works you can make it permanent by adding the command to your .bashrc in your home directory (~/.bashrc).

If you run in any other problems, please let us know.

The preCICE wiki explains how to do the Linking to preCICE in more detail.

Note

You can also look in the solver dummy we wrote, see Verification and testing. The code shows how to use preCICE. It does not support implicit couplings at the moment.

Using preCICE on the cluster

We provide two modules (one debug build and one release build) on the cluster. The preCICE modules will set the environment variable Dprecice_DIR such that CMake should be able to find it.

Note

This part will be updated soon to contain information about the preCICE installation on the cluster.

Getting help and providing feedback

If you have questions concerning preCICE, please use the proper channels of communication:

  • For smaller questions you can use Gitter. The main developers and other users are often there to help.

  • Bigger questions should be asked on Discourse.

  • If you find any bugs, have an idea for improvements etc. please open an issue in the GitHub repository. Check that there does not already exist an issue!

We would be very happy if you would provide feedback on the usability and the documentation. You can use the feedback form that is also linked on the preCICE homepage.

Tasks

  • Get familiar with preCICE.

  • Go through the interactive preCICE tutorial in browser.

  • Install preCICE 1.6.1 on your local machine, please follow the installation instructions (also on the wiki). Run the tests in order to see that everything works as expected.

  • Check out the preCICE C++ API to get a feeling which function calls exists. You will only need a subset of the commands here.

  • Go through the adapter example carefully. You will have to write your own adapter(s) for your code. The example covers all function calls that you will need in this exercise.

  • Adapt your CMake files such that your code can be linked against preCICE.