Scope
This page covers the parts of a coupled setup that live in the preCICE configuration rather than in any one participant: how the coupling window relates to solver steps, how the ordering of participants interacts with the instant at which data is sampled, and what the module does and does not support. The one-window force lag described below is the most common cause of a coupled simulation that is stable in isolation but grows without bound once coupled, so it is worth reading before setting up a new case.
Time windows and solver steps
preCICE advances the coupled simulation in time windows of the size declared in its configuration. Within a window each participant asks preCICE for the maximum step it may take, and may take a smaller one; the adapter computes this in GetSolverTimeStep. If the step taken is smaller than the window, preCICE sub-cycles: the loop runs several iterations before the window completes, and data is read and written on each of them.
That is worth understanding, because sub-cycling does not mean the data changes at each sub-step. Within a window the partner has not produced anything new, so what a participant reads on the second and later sub-steps is what it read on the first. Sub-cycling refines the solver's own integration, not the coupling: the exchange rate is the window size, and improving the accuracy of the coupling means shrinking the window, not the solver step.
Of the three adapters, the MBS and SPH participants cap their step at their configured value and so will sub-cycle whenever that value is smaller than the window. The TDPF participant always takes the whole window in one call, because a time-domain potential flow solver has no internal step to refine.
Explicit coupling and the one-window lag
The shipped examples all use coupling-scheme:serial-explicit, in which the two participants run in a fixed order within each window: the one listed first runs, then the one listed second.
The subtlety is when data written by a partner becomes readable. preCICE associates the data a participant writes during a window with the end of that window. A participant that samples at the start of the window therefore receives what its partner produced during the previous window. For a fluid force applied to a solid body, that means the force acting over a window was evaluated at a solid state one full window old.
That lag is not a harmless loss of accuracy. For a restoring force, a force that lags the displacement it responds to behaves like negative damping, injecting energy into the system at a rate proportional to the window size. A case that should decay will instead grow, and refining the window only slows the growth.
The adapters expose the choice through CouplingReadTime, set from the read_data_time key of the participant YAML:
| Value | Data sampled at | When it is valid |
|---|---|---|
WINDOW_START | beginning of the window (default) | always; carries the one-window lag |
WINDOW_END | end of the window | only for the participant listed second in a serial scheme |
WINDOW_END works only because the second participant runs after the first within the same window, so the data it wants already exists. Combining participants first="Fluid" second="Solid" with read_data_time: WINDOW_END on the solid participant makes the force applied over a window derive from the solid state at the beginning of that window, which removes the lag. This is the arrangement used by all the shipped configurations.
The setting is checked during initialization against the coupling schemes found in the preCICE XML, and an inconsistent combination is rejected with an explanation rather than producing a quietly wrong answer. Requesting WINDOW_END without a serial scheme, or for the participant listed first, is an error. With more than two participants, coupled through one bi-coupling scheme per pair, the read time applies to all data a participant reads, so WINDOW_END requires that participant to be listed second in every scheme it is part of; a solid participant coupled to several fluid participants, each listed first, satisfies this.
A parallel explicit scheme, in which both participants run concurrently, is faster in wall-clock terms but cannot avoid the lag: neither participant has produced the current window's data when the other needs it. That trade is worth making only when the coupling is weak enough for the lag not to matter.
Implicit coupling
Implicit schemes iterate within a window until the exchanged data converges, which requires participants to save their state at the start of a window and restore it on each iteration. preCICE requests this through the checkpoint mechanism, which the adapters surface as OnWriteCheckpoint and OnReadCheckpoint.
Only the MBS adapter implements those. Both fluid adapters throw if preCICE asks for a checkpoint, so an implicit scheme cannot currently be used with a Chrono fluid participant. Coupling a Chrono multibody participant implicitly to an external solver that supports checkpointing is not subject to that limitation.
Added mass over the interface
When a fluid participant contributes added mass, the coefficients cannot be sent as a force: they multiply acceleration and belong in the mass matrix. The module therefore carries them on dedicated meshes, recognized by name: meshes whose names start with SolidAddedMass belong to the solid participant, which reads added mass on them, and meshes whose names start with FluidAddedMass belong to a fluid participant, which writes added mass on them. The data exchanged on these meshes (named am_coeffs in the shipped configurations) must be scalar data.
Two behaviors follow from those declarations, and the distinction is easy to miss:
- Declaring the two meshes is what enables added mass on the solid participant at all. It is a request for added mass, and the solid participant then requires an
added_massentry in its YAML naming the source of the coefficients. Nothing needs to be exchanged for this to take effect. - Added mass becomes dynamic — updated every window over the interface — only if a participant also provides one of those meshes and the scheme declares an
am_coeffsexchange. In that case theadded_massentry is optional.
With dynamic added mass, the added_mass entry of the solid participant is the baseline, typically the infinite-frequency added mass, including any body-to-body coupling terms; without it, the baseline is zero. A fluid participant sends, for each body, a 6x6 increment to that body's own (self) block relative to this baseline. At every window, the solid participant applies its baseline self blocks plus the increments received from all fluid participants, while the body-to-body coupling terms keep their baseline values. Increments are not cumulative: each window's increments replace those of the previous window. A fluid participant whose added mass is the constant infinite-frequency added mass, such as the TDPF adapter, therefore sends zero increments.
Any number of fluid participants can send added mass. preCICE requires each mesh to be provided by a single participant, so every sending participant provides its own FluidAddedMass... mesh (for example FluidAddedMass_TDPF) and writes exactly one data block on it. The solid participant provides a matching SolidAddedMass... mesh for each of them (for example SolidAddedMass_TDPF), with a read mapping from the sender's mesh, and reads the data on it; each such read data block is one source of increments, and the increments of all sources are summed. A participant either sends or receives added mass, not both, and a participant that does neither need not provide any added mass mesh.
The coefficients are sampled at the same point in the window as the forces, so that a force and the added mass it was evaluated with refer to the same instant.
Controlling the simulated duration
An adapter terminates on the coupling status reported by preCICE, and nothing else. The duration is the product of time-window-size and max-time-windows in the preCICE XML. The end_time in a participant YAML is never read by an adapter, which is why the shipped participant files set it to -1 and say so in a comment. A configuration that declares no max-time-windows runs until preCICE's own default limit.
Practical notes
Gravity and other shared physics. Each participant reads its own settings and nothing reconciles them. Gravity in particular must be set identically in both participant files; a mismatch produces a plausible but wrong result rather than an error.
Matching the solver step to the window. For the MBS participant, the integrator step from its solver specification is honored, and the adapter advances by min(step, remaining window). Setting it equal to the preCICE window size makes each window exactly one integration step, which is the easiest arrangement to reason about.
Starting and cleaning up. Participants rendezvous through the mechanism declared in the XML; with <m2n:sockets> and an exchange directory they must be started from the same directory, and the first to start waits. If one participant fails during startup the other waits indefinitely. Before re-running after a failure, make sure no participant processes survive and remove the precice-run directory, or the next attempt may hang during the handshake.
