The latest hotfix release 3.1.2 tackles a major problem in a niche use case. In addition to the short release notes, we think it is worth diving deeper into this topic.
What is compositional coupling?
Imagine three participants A, B, and C. A is coupled to B, and B is coupled to C. Then the configuration describes two coupling schemes and the participant in the middle B takes part in both of them. This is what we call compositional coupling. A concrete example is our simplified heat exchanger tutorial which couples the central solid with the top and bottom fluid.
Composing explicit schemes
If both schemes are explicit, then this is fairly trivial to handle as explicit schemes do not perform iterations. As all schemes advance simultaneously, explicitly coupled solvers are always synchronized.
Composing implicit schemes
If both schemes are implicit, then preCICE raises an error. Composing implicit coupling schemes is extremely difficult to get numerically stable, which is why preCICE provides a multi coupling scheme (Sections 4.1.2 and 4.2), extending a parallel implicit scheme to an arbitrary amount of participants. This is so much more robust, that we decided to disallow composing multiple implicit schemes.
Mixing schemes
If one of the schemes is implicit, then things start to get interesting. Starting from a new time window, all schemes advance simultaneously, therefore they eventually reach the end of the time window together. At this point the convergence measure decides whether the implicit scheme will perform another iteration or not.
If the convergence measure succeeds, all schemes perform their data exchanges and advance to the next time window. Pretty straightforward as this essentially means this behaves the same as a step of an explicit scheme.
If the convergence measure fails, then the implicit scheme needs to perform another iteration. The implicit scheme applies the acceleration (if defined) and requests the solver to read the latest checkpoint. Then all schemes perform their data exchanges and all explicit schemes are put on hold until the implicit scheme has successfully converged. Once the implicit scheme converges, all schemes are in sync again and continue to the next time window.
The partitioned flow over a heated plate tutorial is a practical example of this case. A schema of a parallel-explicit scheme and a parallel-implicit scheme looks as follows:
The names A, B and C denote a participant computing a time window. The arrows are data exchanges between the participants, the additional dot denotes a failed convergence measure and accelerated data.
The bug and the fix
This leads us to the hotfix release 3.1.2. Astute readers may notice something off in this schematic. Take a close look at the data exchange of the explicit scheme in case of multiple iterations. What does this mean for both schemes?
The explicit scheme exchanges data before the implicit scheme has successfully converged, namely at the end of the first iteration. Leading to:
- the explicitly coupled participant receiving data that may not match the one of the last iteration. So coupled solvers may use different values of the same data when they proceed to the next time window.
- the implicit scheme solving a different problem after the first iteration, which is numerical nonsense. This hurts convergence and reduces the effectiveness of acceleration schemes.
The explicit scheme needs to wait with the data exchange until the implicit scheme has reached convergence. The correct scheme looks like this:
Conclusion
Compositional coupling is a complex matter. The above example of parallel schemes was chosen for demonstrative purposes and represents the simplest case. Drawing this scheme for two serial schemes and all permutations of which solver goes first can easily get mind-bending. This is why a solution is difficult to implement correctly and why the hotfix is accompanied by over 2000 lines for additional testing code.
So, if you are using compositional coupling and run into strange behavior like this, then it’s time to upgrade.