A preCICE-FMI Runner to Couple FMUs to PDE-Based Simulations

Partitioned simulation or co-simulation allows simulating complex systems by breaking them up into smaller sub-systems. The Functional Mock-Up Interface (FMI) enables co-simulation for models based on ODEs and DAEs, but typically not PDEs. However, only PDE-based models are able to accurately simulate physical aspects requiring spatial resolution, such as heat transfer or ﬂuid-structure interaction. We present a preCICE-FMI runner software to integrate FMUs with the open-source coupling library pre-CICE. preCICE couples PDE-based simulation programs, such as OpenFOAM or FEniCS, in a black-box fashion to achieve partitioned multi-physics simulations. The runner serves as an importer to execute any FMU and to steer the simulation. Additionally, it calls preCICE to communicate and coordinate with other programs. The software is written in Python and relies on the Python package FMPy. We showcase two example cases for the coupling of FMUs to ODE-and PDE-based models.


Introduction
The simulation of complex, dynamic systems is an important task in science and engineering.It includes multiphysics simulations and the simulation of cyber-physical systems.There are two paths to achieve such simulations, the monolithic and the partitioned approach.In the monolithic setup, one software includes all the necessary computations to model the different phenomena.Contrary to that, the partitioned approach relies on multiple independent pieces of software.Each of these programs covers a specific aspect of the simulation.The programs are then coupled or co-simulated to achieve the correct outcome.This approach allows splitting complicated systems in smaller, simpler subsystems and re-using them in different scenarios.Examples include climate modeling (Gross et al. 2018), but also engineering applications such as the modeling of wind turbines (Sprague, J. M. Jonkman, and B. J. Jonkman 2015).
The Functional Mock-Up Interface FMI (Blochwitz et al. 2011) follows a so-called framework approach for co-Figure 1. Co-simulation approach of the FMI standard (a framework approach): The standardized FMU models are called and coupled by an importer program.We denote the caller (executable) with a female connector and the callee (library) with a male connector.simulation.The simulation models are implemented as standardized Functional Mock-Up Units (FMUs).FMUs are zip-archives with a pre-defined structure and content.They contain the simulation model as library (*.dll, *.so) and meta data about the model such as documentation or reference results.The coupling is done by an additional program, a so-called importer (see Figure 1).The importer loads and executes the FMUs and implements a co-simulation algorithm to ensure communication and data exchange between the models.This approach works well for simple models composed of ODEs and DAEs, but reaches its limits for more complex PDE models.The computation of PDEs often requires legacy software packages and high-performance computing, which are in general not compatible with the regulations for FMUs.preCICE (Chourdakis et al. 2022), on the other hand, is an open-source coupling library for partitioned multiphysics simulations.It couples PDE-based simulation programs, such as OpenFOAM or FEniCS, in a blackbox fashion.preCICE follows a library approach for cosimulation: The simulation programs call the coupling (see Figure 2).The programs itself ideally remain untouched and connect to preCICE through an additional software layer called adapter.Each simulation program requires a specific adapter.Ready-to-use adapters for many popular simulation programs exist.This setup ensures the re-usability of all components and a decent time- to-solution for new applications.
The main idea of this work is to combine both worlds: to couple FMU models to other simulation programs via preCICE.To this end, a new software component, the preCICE-FMI runner is developed (see Figure 3).It acts as an importer towards the FMU, loading and executing the model.Additionally, the runner calls preCICE to couple the simulation to other programs and steer the simulation.It allows coupling FMU models to any simulation program in the preCICE ecosystem.In order to understand how preCICE and the FMI standard can be coupled, Chapter 2 introduces the two existing software components.The chapter continues to explain the concept of the newly developed software, the preCICE-FMI runner, its configuration and functionalities.To showcase the software, Chapter 3 then describes two example cases.First, a partitioned mass-spring oscillator system is used to test the runner against an analytical solution and an alternative Python-based implementation.Second, a FMU model is coupled to a fluid-structure interaction scenario using OpenFOAM as fluid solver and a simple Python script as solid solver.For this scenario, we compare against results from the literature.The final Chapter 4 summarizes the presented ideas and reflects on the impact of the developed software.This paper summarizes and extends the master's thesis of Willeke (2023).
The idea of coupling FMUs to PDE-based programs has already attracted further attention.A recent tool to execute this task is FMU4FOAM 1 .It couples FMUs exclusively to the CFD program OpenFOAM.The coupling is realized with a function object, a library that is loaded by Open-FOAM at runtime.The function object embeds a Python interpreter to handle the FMU.FMU4FOAM is configurable on runtime and can be further adapted to specific needs due to its object-oriented structure.
We see the main advantage of the preCICE-FMI runner in its ability to leverage the advanced coupling functionalities of preCICE.The coupling of FMUs is not limited to OpenFOAM, but can be performed with any program in the preCICE ecosystem.Different coupling schemes and topologies are possible.Furthermore, the coupling library implements a toolbox of coupling algorithms to ensure robust and accurate simulations.

Software description
Before detailing the concept, functionalities, and limitations of the new runner software, we start this section with 1 https://dlr-ry.github.io/FMU4FOAM/describing the existing software components: preCICE and FMI.

Existing software components
preCICE (Chourdakis et al. 2022) is a widely-used and open-source coupling library for multi-physics simulations.In preCICE terminology, the coupled simulation programs are called solvers or participants.preCICE implements data mapping and communication between the solvers.The user can choose between explicit and implicit as well as serial and parallel coupling schemes (Gatzhammer 2014).The coupling is not limited to two solvers, but can be easily extended to perform multi-coupling (Bungartz et al. 2015).Acceleration algorithms, such as quasi-Newton methods (Uekermann 2016) are available to stabilize and speed up implicit coupling schemes.Finally, time interpolation allows individual solvers to use different time step sizes.The exact numerical implementation is out of scope here, but can be found in the cited literature.All these coupling configurations are defined in the precice-config.xmlfile, a global file accessed by all participants.
Each solver is connected to preCICE with a specific adapter.The adapter allows the solver to access the pre-CICE API and call the coupling.It can take many forms, depending on the solver itself.For example, the preCICE-OpenFOAM adapter is an OpenFOAM function object, an indepent library, while the preCICE-FEniCS adapter is a Python module.Adapter development is facilitated by the language bindings of preCICE, which are available for C/C++, Python, Fortran, Julia, and Matlab.A more extensive introduction to preCICE is given in Chourdakis et al. (2022).
The FMI standard (Blochwitz et al. 2011) defines different types of FMU models.They share a similar interface, but implement different functionalities.Model Exchange FMUs hold the model equations and present them to an external solver algorithm.Co-Simulation FMUs hold the model equations and the solver algorithms.As such, they can compute the next time step on their own.Scheduled Execution FMUs were introduced with FMI v3 (Junghanns et al. 2021) and hold different model partitions, which are accessed by an external scheduler.We only consider the coupling of Co-Simulation FMUs in this work.
The Python library FMPy2 can be used to load, execute and steer FMU models with Python.We choose to use FMPy over other libraries such as PyFMI (Andersson, Akesson, and Führer 2016) and fmipp due to its easy installation and usability.An overview of many further FMI tools can be found on the FMI website3 .

Concept of the preCICE-FMI runner
The preCICE-FMI runner is a new piece of software, which connects FMI and preCICE.It uses FMPy to load and execute any FMU and preCICE to couple the simulation.The concept is explained in the simplified code in Figure 4. First, the runner script imports and initializes both FMPy and preCICE (lines 1-9).This includes loading the FMU, setting initial simulation parameters and preparing the communication to other participants.The main loop (lines 11-29) executes the coupled simulation.The program reads data from preCICE (line 16) and writes it to the FMU model (line 18).The model can now compute the next time step (line 20).Afterwards, the program reads the new results (line 22) and writes them to preCICE (line 24).Finally, preCICE advances the simulation as a whole and communicates data with other participant (line 26).Here, preCICE also needs to know how much the FMU model advanced in time to synchronize all participants.This is the main simulation mechanism used for both explicit and implicit coupling.Implicit coupling, however, requires one more feature: the option to repeat a time step.The solver state can be stored (line 14) and reset (line 29) to iterate over a time step.preCICE indicates whether this is necessary or not (lines 12, 27).Finally, preCICE and FMPy are terminated (lines 31-32) to close the communication channels and release the FMU.The software is developed on GitHub 4 and documented in the preCICE user documentation 5 .

Functionalities and limitations of the preCICE-FMI runner
The ideal coupling tool should support the full functionality of both preCICE and FMPy.It should work with any co-simulation FMU and should be configurable at runtime.The software has to be well-documented and include tests to guardrail further development.This section gives insight into the abilities, limitations, and configuration of v0.1 of the preCICE-FMI runner.
The software is available for preCICE v2 and compatible with FMI 1, 2, and 3.It supports explicit and implict coupling schemes, including acceleration.It is configurable at runtime via two .jsonfiles and can be adapted to different FMU models.Time-dependent input signals can be set, output signals are stored as timeseries.The tool is easy to install and comes with a regression test.
A major difference in the coupling of two PDE solvers compared to the coupling of a PDE solver to an FMU is the role of the mesh.For PDE-PDE coupling, the exchanged data is spatial for both solvers and mapped accordingly.However, many FMUs can not deal with spatially resolved data but are designed to receive signal data.To enable the coupling of PDE solvers to such FMUs, we use the mapping capabilities of preCICE: spatial data from one mesh is mapped to a single vertex on another mesh to create signal data and vice versa.
As a result, data exchange is limited to one vertex.Moreover, the exchange of multiple data points and gra-4 https://github.com/precice/fmi-runner 5https://precice.org/tooling-fmi-runner.html dient information is not yet supported.Also, no internal errors of the FMU model are logged.Finally, the runner software can currently only be executed in serial.
To explain the configuration of the runner, we assume a FMU model Suspension.fmu, which contains the model equations for a spring-damper system.It should be coupled via preCICE to receive the variable force from another participant, calculate the displacement internally, and send the variable position back.The configuration file fmi-settings.json,shown in Figure 5, holds the settings for FMPy.The dictionary simulation_params (lines 2-9) is used to choose the FMU model and set the read and write variables.A CSV file can be set to store results.The dictionaries model_params and initial_conditions (lines 10-16) allow setting model parameters before the simulation start.Time-dependent input signals are set in input_signals (line 17-23).In this case, the variable damping_coeff is initialized with value 0.0 and To execute the coupling, the runner needs some information on how to interact with preCICE.The file precicesettings.json(Figure 6) points the runner to the global configuration file of preCICE shared with all participants.The following entries define which participant the runner is, which mesh it owns, and which preCICE variables are accessed.

Example cases
Two example cases show the functionality of the preCICE-FMI runner.First, the simulation of a partitioned mass-spring oscillator system demonstrates the coupling of two ODE systems.The obtained results are compared to a numerical simulation in Python and an analytical so-lution.Second, the fluid-structure interaction of a moving cylinder is adapted to include a FMU model for controlling the movement and compared to reference results from literature.The case files are available for reproduction.6

Partitioned mass-spring oscillator system
We assume an ideal mass-spring system (Schüller et al. 2022) as shown in Figure 8. Three springs k 1 , k 12 , and k 2 connect two masses m 1 and m 2 with each other and two fixed walls.The variables u 1 and u 2 denote the positions of the masses.To create a partitioned system, spring k 12 is cut in the middle.The resulting subsystems exchange interface forces F 1 and F 2 .The system is adaptable to perform different kinds of oscillations.We follow Schüller et al. (2022) and set the spring stiffness to k 1 = k 2 = 4π 2 N/m and k 12 = 16π 2 N/m, while the two masses are set to m 1 = m 2 = 1kg.Additionally, the initial conditions are chosen as This setup has the analytical solution depicted in Figure 7.The two masses oscillate with a period of T P = 1s.
We use this testcase to compare an FMU-based implementation executed with the preCICE-FMI runner and an existing implementation in Python (Schüller et al. 2022).Both implementations can be coupled to themselves or to one another.We end up with four possible combinations: runner-runner, Python-Python, runner-Python, and Python-runner.Moreover, we compare against the analytical solution.Proceedings of the Modelica Conference 2023 October 9-11, 2023, Aachen, Germany . Mass-spring system: The springs k 1 , k 12 and k 2 connect the two masses m 1 and m 2 which have the positions u 1 and u 2 .The middle spring k 12 is cut in half to create a partitioned setup with two subsystems that exchange interface forces F 1 and F 2 .
Both implementations use the Newmark-β method (Newmark 1959) with β = 1 4 and γ = 1 2 for time integration.A serial-implicit coupling with Aitken acceleration is used.The simulation time is set to T = 5s with a time step of ∆t = 0.005s.A more extended description is given in Willeke (2023).
The results in Figure 9 show the trajectory of m 1 .No differences are visible between all four possible combinations.Furthermore, all combinations match the analytical solution well.For a more accurate comparison, the maximum norm e ∞ between analytical solution and numeric result for u 1 is calculated over all time steps.The maximum serves as a worst-case approximation.The calculated error e(u 1 ) ∞ ≈ 3.48 × 10 −2 is identical for the FMU and the Python implementation up to a precision of 10 −5 .

Flow around a moving cylinder
As a second example, consider the flow in a channel around a cylinder as shown in Figure 11.The cylinder with diameter D and mass m is not fixed in its position y.Instead, the cylinder is mounted upon a spring-damper system with spring stiffness k and damper coefficient d.The flow with velocity v 0 induces vortex shedding behind the cylinder.This leads to varying lift forces and results in an oscillation of the cylinder position y.This setup has been used as a test case for numerical simulations (Placzek, Sigrist, and Hamdouni 2009) and is especially interesting because experimental reference data is available (Anagnostopoulus and Bearman 1992).The experimentalists report lock-in effects for the cylinder oscillation for Reynolds numbers between 104 < Re < 126 with the highest excitation at the lower end.For our simulation, we chose a Reynolds number of Re = 108.83.The remaining system parameters are set to m = 0.03575kg, d = 0.0043N/s and k = 69.48N/m.All are in accordance with the referenced literature.We further adapt the case to be able to move the root point of the spring u (Sicklinger 2014).Now, the spring force acting on the cylinder can be actively controlled by adjusting u.  Figure 12 shows the simulation results obtained with a time step of ∆t = 0.0001s.First, the controller is deactivated until the cylinder has reached a state of stable oscillation.The displacement has an amplitude of ŷ = 0.48mm, which is close to the reference amplitude of ŷre f = 0.6mm.
The differences may be attributed to the explicit solver in the spring-damper system and the explicit coupling scheme, both of which are implicit in the reference simulation.The PID controller is activated at T = 40s.The control gains are set to K P = 0.02, K I = 0.02 and K D = 0.01 to ensure a robust transient behaviour (Sicklinger 2014).The cylinder displacement is reduced by orders of magnitude with a fast transition phase.

Conclusions
We presented the preCICE-FMI runner, a new software to couple FMU models to PDEs.The software loads and executes FMU models and calls preCICE to execute the coupling.It is written in Python to leverage the Python package FMPy and the preCICE Python bindings.The runner software is configured with two settings files, enabling different simulation scenarios.An easy, standard installation process lowers the entry barrier for new users.The preCICE-FMI runner is compatible with co-simulation FMUs of FMI versions 1, 2, and 3 and preCICE version 2. It supports explicit and implicit coupling via preCICE, as well as the use of acceleration methods.Time-dependent input signals can be set for the FMU model during simulation.Output signals from the FMU are stored for postprocessing.
Two example cases introduced the functionalities of the runner software.The partitioned simulation of a massspring oscillator system showed good agreement with another numerical solver and an analytical solution.The simulation of the flow around a moving cylinder was coupled to a FMU-based control algorithm and showed qualitatively meaningful results.
The new software is focused on providing a general coupling of co-simulation FMUs to PDE-based solvers.It enables plug-and-play coupling to many popular solvers thanks to the preCICE library approach.The software is documented on precice.org and the presented test cases are available for reproduction.Some limitations, such as the lack of error logging or full mesh exchange remain.
FMI is a widely used industry standard for the cosimulation of cyber-physical systems.preCICE, on the other hand, has a growing user base in academia and industry focused on high-fidelity multi-physics applications.The preCICE-FMI runner connects these two communities.With our work, we hope to spark a discussion about the specific needs of both communities to guide further developments.

Figure 2 .
Figure2.Co-simulation approach of preCICE (a library approach): The simulation programs call preCICE as a library to perform the coupling.

Figure 3 .
Figure 3. Concept of the preCICE-FMI runner: The new software executes the FMU and calls preCICE to couple the simulation to other programs.

Figure 4 .
Figure 4. Concept of the FMI runner: The script utilizes the library FMPy to execute the FMU and calls the preCICE API to couple the simulation.For conciseness, API calls are simplified.

Figure 9 .
Figure 9.Comparison of different implementations for the mass-spring oscillator system.Velocity u1 is plotted over position u 1 to show the trajectory of m 1 .The results from a coupling of both the runner and the Python solver to itself have no visible differences and track the analytical solution well.The results for the cross-combinations runner-Python and Python-runner show no visual difference and are omitted for simplicity.

Figure 10 .Figure 11 .
Figure 10.Coupling topology for the flow around a moving cylinder example: Three participants are coupled in two bicoupling schemes.The fluid participant and the spring-damper participant exchange lift force F and cylinder displacement y.The spring-damper participant and the controller exchange displacement y and spring root displacement u.

Figure 12 .
Figure12.Cylinder displacement with activation of the PID controller: The cylinder oscillates in a stable state until the controller is activated at T = 40s.This reduces the displacement y by orders of magnitude.