PRECICE

preCICE is an open-source coupling library and ecosystem for general partitioned multi-physics and multi-scale simulations, including surface and volume coupling [1]. For more information, see https://precice.org/. Note: The development of the preCICE co-simulation is currently still in an experimental stage. To simplify the process for MESHFREE users, the coupling is controlled directly through the MESHFREE InputFiles in addition to the preCICE configuration file precice-config.xml. This will eventually be replaced by a standardized version.

Installation

For installation of preCICE and its dependencies, please refer to https://precice.org/installation-overview.html. Set the environment variables for preCICE appropriately in your PATH. The MESHFREE build then finds the preCICE library dynamically, which can be used to start coupled runs.

Coupling Multiple MESHFREE Chambers

Currently, we focus on a simplified two-phase scenario, in which a water phase is coupled to an air phase. A typical usage pattern for this scenario in USER_common_variables is as follows. Water chamber: Air chamber: MESHFREE uses the following data structures to initialize and drive the preCICE coupling.

Command	Description
PRECICE_ParticipantName	Participant name (string) that must exactly correspond to the participant name defined in the preCICE configuration file precice-config.xml.
PRECICE_MeshName	Mesh name (string) that should match the mesh name defined in the preCICE configuration file precice-config.xml.
PRECICE_WriteDataName	WriteData flag (string) describing what data should be written for preCICE.
PRECICE_ReadDataName	ReadData flag (string) describing what data should be read for preCICE.
PRECICE_ReadData	Read and map to the preCICE data fields configured in precice-config.xml at the beginning of the time step with the help of UserDefinedIndices %indU_...%.
PRECICE_WriteData	Map and store to the preCICE data fields configured in precice-config.xml at the end of the time step with the help of %ind_xxx%, see __Indices__.
PRECICE_DtJump	Relative allowed increase (less or equal 1) of the MESHFREE-recommended time step size during time-window synchronizations to avoid unnecessarily small time steps.
PRECICE_Mapping	(OPTIONAL) 'JustinTimeMapping' for Lagrangian point cloud triggering the preCICE mapping only at the coupling synchronization points, see section below for details.
PRECICE_BoundingBox	(OPTIONAL) Bounding box for 'JustinTimeMapping' with 6 arguments (xmin, xmax, ymin, ymax, zmin, zmax) denoting the access region from the corresponding neighboring participant.

Notes:

• The use of %indU_...% in PRECICE_ReadData allows to visualize the mapped, interpolated (or approximated) data at the beginning of the time step. This provides an alternative to the approxY() or projY() functionalities supported by MESHFREE.
• Only one participant can use PRECICE_Mapping = 'JustinTimeMapping'. The other participant needs to use an Eulerian point cloud. For details, see the section below.
• Defining multiple PRECICE_BoundingBox statements is not yet supported.

Just-In-Time Mapping

The just-in-time mapping (JIT) concept used here, which allows the point cloud to change adaptively in every time step in a Lagrangian formulation (and not only during coupling synchronizations), is described in [2]. Currently, this requires the definition of a bounding box to access the mesh (Eulerian point cloud) of the other participant. With this functionality, the user can couple Eulerian-Lagrangian point clouds. We consider the following scenario.

• Air chamber: Eulerian point cloud ('AirMesh'), invariant in time and space
• Water chamber: Lagrangian point cloud which may change in size or location during the simulation
• preCICE: data exchange and performs spatial mapping between the water point cloud and the air point cloud

In JIT mode, the water chamber does not register its own mesh in preCICE. Instead, it works directly on the received 'AirMesh', based on the current water point cloud coordinates in each coupling step. To activate just-in-time mapping for the water chamber (JIT configuration), use the following settings in USER_common_variables: PRECICE_DtJump controls how much the time step size can be modified in the last time-window synchronization. The water coupling interface uses this to limit overly aggressive reductions of the time step size. This is extremely important since it has an effect on all successive time steps and significantly slows down the simulations if not done. PRECICE_Mapping = 'JustinTimeMapping' activates the just-in-time mapping mode for water.

• The water coupling interface uses run-time point cloud coordinates (PC%Y(ind_x(1:3), :)) to perform the mapping with preCICE, instead of static vertex IDs.
• No water mesh is registered in preCICE; instead, water works directly on the received 'AirMesh'.

PRECICE_BoundingBox = (xmin, xmax, ymin, ymax, zmin, zmax) defines the bounding box of the region, in physical coordinates, where water wants to access the 'AirMesh'.

• The six values define an axis-aligned box: x --> [xmin, xmax], y --> [ymin, ymax], z --> [zmin, zmax]
• The water coupling interface passes this box to preCICE as the mesh access region.
• All water point cloud coordinates used for coupling must lie inside this region; otherwise, preCICE will report an error at run-time.

In addition, the preCICE configuration must be adapted.

• The preCICE configuration file must be marked as experimental.
• Water must receive the air point cloud mesh ('AirMesh') with API access enabled.
  • the air participant provides 'AirMesh'
  • the water participant receives 'AirMesh' with api-access="true"
• The spatial mapping between water and air point cloud must be defined on the water side.

Critical Remarks

Currently, only the following settings are supported.

• precice_dimensions = 3 (3D problem), i.e. only 3D problems are supported in MESHFREE.
• The preCICE configuration file precice-config.xml is required in the directory where the individual MESHFREE setup folders for each participant are located. If it is not found, the simulation terminates with an error.

The performance of the preCICE initialization and mapping methods can be monitored in MESHFREE. The following NamesOfStopWatches are available: PRECICE_Initialize, PRECICE_ReadData, PRECICE_WriteData.

Known Limitations

• preCICE is initialized only after the second time step. This is done for the following reasons:
  • Several MESHFREE features are introduced after the second time step, which can have considerable effects on the point cloud data structures.
  • Even when PC-organization is turned off and an Eulerian point cloud is used, it is still observed that the number of points changes from the first to the second time step.
  • The hole-filling algorithms have different default values in the initial and in the successive filling cycles.
• Only one entry for PRECICE_ReadData, PRECICE_WriteData, PRECICE_BoundingBox, PRECICE_Mapping, etc. can currently be defined. An extension to a more general setup is planned in the future.
• The complete point cloud in the current chamber is passed for interpolation. An extension to selectively pass a subset of the point cloud is planned for the future.