Draft:preCICE (software)

preCICE

Developer(s)	University of Stuttgart, Technical University of Munich, and the preCICE community
Initial release	June 1, 2010 (2010-06-01)
Stable release	3.1.2  / 6 June 2024
Repository	github.com/precice/precice
Written in	C++
Operating system	Linux, macOS, Windows,FreeBSD
Predecessor	FSI*ce
Available in	English
Type	simulation software, multiphysics simulation, multiscale simulation
License	LGPL-3.0-or-later
Website	precice.org

preCICE is a coupling library for partitioned multi-physics simulations, including but not restricted to fluid-structure interaction, conjugate heat transfer, and more. preCICE is not specific to particular applications or tools, but instead couples independent, existing codes capable of simulating a subpart of the complete physics involved in a simulation. It offers convenient, robust, and efficient methods for transient equation coupling, communication, and data mapping.

To create a coupled simulation, a user would modify existing simulation codes to add calls to the preCICE API (or use one of the provided adapters), provide a preCICE configuration file, and start each code normally, e.g., in a separate terminal. preCICE follows a library approach, does not introduce any central component, and does not require modifications to the calling code in order to use a different coupling or interpolation method, keeping the integration minimally-invasive.

preCICE is free software, developed publicly on GitHub and with mainly public funding. It follows open science and the FAIR principles, demonstrated via several open access publications.

Overview of the preCICE coupling library (as of v3.1), including the main concepts, features, and examples of codes already coupled.

History

Early years

The foundations for the work leading to preCICE come from projects funded between 2003-2009 by the German Research Foundation in the Research Group FOR493. The name "preCICE" (precise code interaction coupling environment) appears in literature first in 2010. preCICE is a direct successor of FSI*ce (stylized FSI❄ce), developed at the Technical University of Munich, which mainly targeted fluid-structure interaction simulations.

preCICE v1

In May 2015, the development of preCICE was moved to its own organization on GitHub, which now includes repositories for the core library and several further components of the project. The first stable version of the core library was released in November 2017, following semantic versioning (v1.0.0). At that time, the documentation of the project was hosted in a GitHub Wiki.

The state of preCICE v1.0.0 is largely as described in what is described in the preCICE literature guide as "v1 reference paper", published in 2016, together with collaborators from the University of Stuttgart. The paper describes the core library, with main features being a variety of coupling schemes (explicit and implicit, Aitken underrelaxation, Anderson and Broyden quasi-Newton acceleration algorithms), data mapping methods (nearest-neighbor, nearest-projection, RBF), and communication methods (TCP/IP sockets, MPI ports). The paper also includes a list of coupled codes developed by the authors or collaborators, as well as FSI benchmarks demonstrating numerical accuracy and performance scalability up to 16384 processes on SuperMUC. During that time, the development of preCICE was partially funded by the German Priority Programme 1648: SPPEXA - Software for Exascale Computing via the ExaFSA project.

The v1.x release cycle saw releases until v1.6.1, in September 2019.

preCICE v2

During the v1.x release cycle, and driven primarily by a German Research Foundation project specifically intended for "Research data and software" (project number 391150578), the preCICE project saw development in different directions: extensive refactoring of the code and full migration to the CMake build system (from previously SCons), new or additional unit, integration, and system tests, large expansion of the available documentation, development of several new adapters and several community building measures. Several of these changes are connected to the acceptance of preCICE into the extreme-scale scientific software development kit (xSDK).

This development led to preCICE v2 (v2.0.0) and later on to a new reference paper describing the state of the software and the respective ecosystem at that time. This paper is currently the default citation recommendation in the literature guide.

Since constructing a coupled simulation typically involves more components beyond the core library (language bindings and adapters), the source code of selected components, together with the application cases, was published as a separate data publication. This bundle is called a preCICE distribution, and has seen semi-regular releases since, following a calendar-based versioning scheme.

The v2.x release cycle saw releases until v2.5.1, in January 2024.

preCICE v3

preCICE v3.0.0 was released in February 2024. It was soon after replaced by v3.1.0 and then v3.1.1, which is included in the preCICE Distribution v2404.0.

Notable changes of v3 include simplifications in the API and configuration, multirate and higher-order time stepping, and faster RBF mapping based on a partition of unity approach.

At the time of the v3 release cycle, the project has expanded from targeting mainly surface coupling to also targeting volume coupling (overlapping domains, see domain decomposition methods), geometric multiscale, system codes implementing the Functional Mock-up Interface, and multiscale simulations.

API

The native API of preCICE is written in C++. Language bindings for C and Fortran are compiled into the preCICE library itself. Further language bindings are available externally.

Language	Repository	License	Package	Usage (v3)
C++	precice on GitHub	LGPL-3.0-or-later	GitHub Releases	#include <precice/precice.hpp> precice::Participant p(…);
C				#include <precice/preciceC.h> preciceC_createParticipant(…);
Fortran				CALL precicef_create(…)
Fortran Module	fortran-module on GitHub	LGPL-3.0-or-later		use precice CALL precicef_create(…)
Python	python-bindings on GitHub	LGPL-3.0-or-later	PyPi	import precice p = precice.Participant(…)
Rust	rust-bindings on GitHub	LGPL-3.0-or-later	crates.io	use precice let mut participant = precice::Participant::new(…);
Julia	PreCICE.jl on GitHub	LGPL-3.0-or-later		using PreCICE PreCICE.createParticipant(…)
Matlab	matlab-bindings on GitHub	LGPL-3.0-or-later		p = precice.Participant(…)

Configuration

The individual coupled codes (coupling participants) share a common XML-based configuration file, which specifies the data and coupling meshes, the communication, coupling scheme, acceleration method, and more at runtime. Using a different coupling scheme does not require any changes to the code calling preCICE, but only to the configuration file.

The coupled codes often group the preCICE API calls into an adapter code. This adapter is typically configured by a separate configuration file (with a format appropriate for the respective simulation code), and specifies the exact region of the simulation domain to be coupled, as well as the exact data exchanged..

Example

An adapted fluid solver written in Python using preCICE v3 (ported from v2 reference paper).

import precice

participant = precice.Participant("Fluid", "../precice-config.xml", 0, 1)

positions = ... # define coupling mesh, 2D array with shape (number of vertices, dimension of physical space)
vertex_ids = participant.set_mesh_vertices("Fluid-Mesh", positions)

participant.initialize()

t = 0 # time

u = initialize_solution() # returns initial solution

while participant.is_coupling_ongoing(): # main time loop
        
    if participant.requires_writing_checkpoint():
        u_checkpoint = u

    solver_dt = compute_adaptive_time_step_size() 
    precice_dt = participant.get_max_time_step_size()
    dt = min(precice_dt, solver_dt) # actual time step size
    
    # returns 2D array with shape (n, dim)
    displacements = participant.read_data("Fluid-Mesh", "Displacement", vertex_ids, dt)
    
    u = solve_time_step(dt, u, displacements) # returns new solution
    
    # returns 2D array with shape (n, dim)
    forces = compute_forces(u) 
    participant.write_data("Fluid-Mesh", "Force", vertex_ids, forces)
    
    participant.advance(dt)

    if participant.requires_reading_checkpoint():
        u = u_checkpoint
    else: # continue to next time step 
        t = t + dt    

participant.finalize()

Coupled codes

While preCICE is a software library with an API that can be used by programmers to couple their own code, there exist several integrations with several simulation codes, making preCICE more accessible to end users that are not primarily programmers (such as applied mathematicians, mechanical engineers, or climate scientists).

In the terminology used by preCICE, the integrations to simulation codes are called adapters and can be maintained by the preCICE developers or third parties. A non-exhaustive list of adapters is available on the preCICE website.

Example codes that preCICE integrates with via adapters include, among others:

• CalculiX
• deal.II
• DUNE
• Elmer
• FEBio
• FEniCS
• OpenFOAM
• SU2

Applications

Academic publications by the developers and by independent research groups have demonstrated preCICE for several applications, while further examples are listed on the website of the project.

Mechanical and civil engineering

• Aeroacoustics
• Aerodynamics
• Astronautics
• Explosions
• Manufacturing processes
• Urban wind modeling

TODO: Add examples

Marine engineering

TODO: Add examples

Bioengineering

• Heat valves
• Aortic blood flow
• Fish locomotion
• Muscle-tendon systems

TODO: Add examples

Nuclear fission and fusion reactors

The GRS (in collaboration with the Technical University of Munich and the preCICE developers) has coupled the system code ATHLET with OpenFOAM and CalculiX, for reactor thermohydraulics .

Geophysics

TODO: Add examples

See also

• Multiphysics simulation
• List of numerical analysis software
• List of finite element software packages
• Fluid-structure interaction
• Computer-aided engineering