A hands-on introduction to preCICE, recommended for new users that want to learn how to couple their own codes and beyond.

About the course

Since 2020, we have been developing a dedicated training course on preCICE. Originally conceptualized for beginners, more and more content for advanced users has been added. We regularly give the complete course at the preCICE workshops and parts of it at various different occasions (for example as a minitutorial at SIAM CSE 2023. We also offer to give private and bespoke versions of the course through the preCICE support program. Please note that the material of the course (besides community-contributed modules) is not distributed with a FOSS license, in contrast to almost everything else we do.

Teaching concept

The course is organized in separate modules, which can be combined in various different ways. Each module typically takes 120 to 150 minutes to complete. We start each module with a short presentation explaining some background and giving an overview of the tasks. Then, students work on the tasks in a hands-on fashion, individually or in groups. Questions are answered individually by typically several instructors. We close each module by discussing solution approaches and open problems all together. We typically provide a reference system (see how to prepare) with everything installed, for convenience. The actual course material is tailored to the needs of each event and distributed via download links.

Basic previous knowledge of Python programming, the Linux command line, and numerical simulation principles are highly recommended.

Content

The course currently consists of the following modules, presented in historical order. The basics is necessary for beginners, and it is typically followed by tools, implicit coupling, and data mapping, and further modules depending on the needs of the audience. We regularly add new modules - don’t hesitate to let us know if you would have any specific needs.

Basics

We couple two simple Python codes, discussing the basic methods of the preCICE API.

Basics training: Configuration

Tools

We take a tour over available tools to configure, understand, and post-process preCICE simulations. More specifically, we have a look at the preCICE logger, config visualizer, mesh exports, and watchpoints of preCICE. We also discuss common tips for visualizing partitioned simulations in ParaView.

Basics training: Tools

Implicit coupling

We use a conjugate heat transfer scenario coupling OpenFOAM with Nutils to study implicit coupling, including acceleration methods.

Basics training: Implicit coupling

Data mapping

We explore aspects of accuracy and efficiency in data mapping, using ASTE.

Basics training: Mapping

Workflow for FSI simulations

In this community-contributed part of the course, we are going step by step through the process of creating a fluid-structure interaction simulation coupling CalculiX and OpenFOAM. We start by creating the meshes for both solvers, using FreeCAD and snappyHexMesh. We then setup and run single-physics simulations, before we couple them.

Application training: FSI workflow

Parallelization and HPC workflows

We parallelize the same Python codes used in the Basics module, we analyze the performance-related events, run partitioned simulations in parallel on SLURM-enabled systems, and look deeper into common performance-related pitfalls.

HPC training: Tracing

Macro-micro coupling

We couple many micro simulations to a macro simulation: We use the Micro Manager to set up Python and C++ micro simulations, learn how manage runtime using adaptivity, implement model adaptivity, and run the micro simulations in parallel with adaptivity and load balancing.

Macro-Micro training: Adaptivity

How to prepare?

On the technical side, the training course involves multiple components of the preCICE ecosystem, as well as third-party solvers and pre- and post-processing tools. Most of these tools work best (or only) on a Linux system. You can either (a) use a prepared system image that we provide (a virtual machine image or a bootable live USB), or (b) install the dependencies directly on your system. To reduce system-related friction during the training, we recommend starting with option (a). On virtual trainings, that is a VM image; on in-person trainings, that might be a bootable live USB.

Provided virtual machine image

Close to the training start, you will receive instructions with a link to an up-to-date provided VM image, very similar to the demo VM. We typically provide a Vagrant box made for VirtualBox.

System requirements: ideally 25GB of free storage, 8GB of RAM, and more than 4 CPU cores. By default, the VM is configured with 4GB of RAM and 4 CPU cores, both configurable. Most of the storage goes to solvers and other tools that you might not need, in which case you could directly install the tools you need on your system, or on your own VM.

Provided live USB

In our on-site trainings, some bootable USB sticks are provided, based on the Ubuntu installer, allowing you to work on a temporary live session, without installing anything on your system. These should work on any laptop with an x86-64 CPU, as long as you have the rights to boot from USB. In particular, these do not work on Apple Silicon systems.

Notes:

  • If you have secure boot enabled, this will need to be turned off to boot this unsigned OS.
  • In case you use Windows with BitLocker enabled, you will not be able to boot on Windows while secure boot is disabled (BitLocker will be asking for the decryption key). Remember to switch secure boot on again to be able to use your system as before.
  • Do not remove the USB during a live session (e.g., during a break). You would be surprised how many times this has happened already. :-)

Individual dependencies

In case you prefer to install everything on your system, you will need the following:

  • preCICE (check with running precice-version in a terminal)
  • preCICE Python bindings:
    • Create a virtual environment: python3 -m venv .venv && source .venv/bin/activate. As long as the environment is active, you will see (venv) before your command prompt. You need to activate the venv in new terminal windows.
    • Install the bindings: pip3 install pyprecice (check with running import precice in a Python interpreter)
  • matplotlib and numpy v1.x: In the same virtual environment, run pip3 install matplotlib numpy==1.26.4
  • ParaView (visualization, used in most modules apart from the basics)

The tools module also needs (all optional):

  • preCICE config visualizer (check with running precice-config-visualizer --help)
    • Optionally, install the precice-config-visualizer-gui as well.
  • gnuplot (check with gnuplot --help)

The implicit coupling module also needs:

  • OpenFOAM (openfoam.com): See the Quickstart page (check with running buoyantPimpleFoam -help)
  • OpenFOAM-preCICE (check with running the Quickstart tutorial)
  • Nutils (installed automatically when running)

The mapping module also needs:

  • ASTE (check by running ./precice-aste-run --help from the ASTE build directory)

The FSI workflow module also needs:

  • OpenFOAM (openfoam.com): See the Quickstart page (check with running pimpleFoam -help)
  • OpenFOAM-preCICE (check with running the Quickstart tutorial)
  • CalculiX and the CalculiX adapter (check by running ccx_preCICE)
  • FreeCAD 0.21 or later (check by starting the GUI)
  • ccx2paraview (pip3 install ccx2paraview, check by starting a Python terminal and executing import ccx2paraview)
  • PyFoam (pip3 install pyfoam, check by running pyFoamPlotWatcher.py --help)

The macro-micro coupling module also needs:

  • A C++ compiler (for example, g++ or clang++)
  • Micro Manager (pip3 install micro-manager-precice, check by running micro-manager-precice -h)
  • pybind11 (v3 or later, install on Ubuntu with apt install python3-pybind11, check with pybind11-config --includes --extension-suffix)