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 free/open-source 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.

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.

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

History

Early years

The name "preCICE" (precise code interaction coupling environment) appears in literature first in 2010. preCICE is a direct successor of FSI*ce, developed at the Technical University of Munich, which mainly targeted fluid-structure interaction simulations. FSI*ce was a result of a German Research Foundation project in the Research Group FOR493.

preCICE v1

In May 2015, the development of preCICE was moved to its own organization on GitHub. The first stable version of the core library was released in November 2017 (v1.0.0).

preCICE v1 included 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 v1.x release cycle saw releases until v1.6.1, in September 2019.

preCICE v2

By 2020, the preCICE project saw development in different directions: extensive refactoring and testing of the core library, 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). Due to increased number of components, the preCICE distribution was introduced as a citable bundle of components working together.

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. 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 mapping, 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). While this example is inspired from fluid-structure interaction (exchanging forces and displacements), the model, solution fields, and the exchanged fields can be arbitrary.

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.

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

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

The community has also coupled CAMRAD II, DLR TAU, DUST, DuMuX, Rhoxyz, Ateles, XDEM, FLEXI, MBDyn, OpenFAST, LS-DYNA, and G+Smo.

Applications

Academic publications by the developers and by independent research groups have demonstrated preCICE for several applications (see pointers to literature in the v2 paper ), while further examples are listed on the website of the project.

• Mechanical and civil engineering
  • Aeroacoustics: See, e.g., the ExaFSA HPC project (Germany, Netherlands, Japan).
  • Aerodynamics: See, e.g., work by the TU Delft on inflatable kites (Netherlands).
  • Aerodynamic heating: See, e.g., a paper on hypersonic aerothermal simulations (USA).
  • Explosions: See, e.g., work by the National University of Defense Technology (China).
  • Urban wind modeling: See, e.g., work by the University of Manchester (UK).
  • Manufacturing processes: See, e.g., work by the Austrian Institute of Technology (Austria).
• Marine engineering
  • See, e.g., work by the University of Split (Croatia).
• Bioengineering
  • Hemodynamics - heart valves: See, e.g., work by the University of Stellenbosch (South Africa).
  • Hemodynamics - aorta: See, e.g., work by the UPC (Spain) and the University of Stuttgart (Germany).
  • Fish locomotion: See, e.g., work by the University of Strathclyde (UK) and collaborators (China).
  • Muscle-tendon systems: See, e.g., work by the University of Stuttgart (Germany).
• Nuclear fission and fusion reactors
  • Thermohydraulics: See, e.g., work by GRS (in collaboration with the Technical University of Munich and the preCICE developers) on coupled reactor thermohydraulics (Germany).
• Geophysics
  • Porous media flow: See, e.g., work by the University of Stuttgart (Germany).
  • Geothermal energy: See, e.g., work by the GeoKW project (Germany).
• Further examples
  • Inductively coupled plasma wind tunnels: See, e.g., work by the University of Illinois (USA)

See also

• Other coupling libraries/frameworks with similar goals are MUI, OpenPALM (CWIPI), and MpCCI.
• Multiphysics simulation
• List of numerical analysis software
• List of finite element software packages
• Fluid-structure interaction
• Computer-aided engineering