Step 6 – Implicit coupling

The main ingredient needed for implicit coupling is move backwards in time. For that, we need a flux capacitor. Just kidding 😉. What we really need is that your solver can write and read iteration checkpoints. An iteration checkpoint should contain all the information necessary to reload a previous state of your solver. What exactly is needed depends solely on your solver. preCICE tells you when you need to write and read checkpoints. To this end, preCICE uses the following interface:

bool requiresWritingCheckpoint()
bool requiresReadingCheckpoint()

These functions perform double duty:

1. They inform the adapter that writing or reading a checkpoint is required by the solver.
2. They let preCICE know that your adapter is capable of implicit coupling. preCICE will show an error if you configure implicit coupling without calling these functions.

Let’s extend our example code to also handle implicit coupling.

turnOnSolver(); //e.g. setup and partition mesh

precice::Participant precice("FluidSolver","precice-config.xml",rank,size); // constructor

// [...] define mesh

double solverDt; // solver time step size
double preciceDt; // maximum precice time step size
double dt; // actual time step size

precice.initialize();
while (precice.isCouplingOngoing()){
  if(precice.requiresWritingCheckpoint()){ // new time window
    saveOldState(); // save checkpoint
  }
  preciceDt = precice.getMaxTimeStepSize();
  solverDt = beginTimeStep(); // e.g. compute adaptive dt
  dt = min(preciceDt, solverDt);
  precice.readData("FluidMesh", "Displacements", vertexIDs, dt, displacements);
  setDisplacements(displacements);
  solveTimeStep(dt);
  computeForces(forces);
  precice.writeData("FluidMesh", "Forces", vertexIDs, forces);
  precice.advance(dt);
  if(precice.requiresReadingCheckpoint()){ // iteration did not converge
    reloadOldState(); // set variables back to checkpoint
  }
  else{ // iteration converged
    endTimeStep(); // e.g. update variables, increment time
  }
}
precice.finalize(); // frees data structures and closes communication channels
turnOffSolver();

The methods saveOldState and reloadOldState need to be provided by your solver. You wonder when writing and reading checkpoints is required? Well, that’s no black magic. In the first coupling iteration of each time window, preCICE tells you to write a checkpoint. In every iteration in which the coupling does not converge, preCICE tells you to read a checkpoint. This gets a bit more complicated if your solver subcycles (we learned this in Step 5), but preCICE still does the right thing. By the way, the actual convergence measure is computed in advance in case you wondered about that as well.

Of course, with the adapted code above, explicit coupling still works. You do not need to alter your code for that. In case of explicit coupling, both actions reading and writing iteration checkpoints always return false.

At this state, you can again test your adapted solver against a solver dummy. Make sure to adjust the config file for implicit coupling scheme:

[...]
<coupling-scheme:serial-implicit>
  <participants first="FluidSolver" second="SolidSolver" />
  <max-time-windows value="10" />
  <time-window-size value="1.0" />
  <max-iterations value="15" />
  <relative-convergence-measure limit="1e-3" data="Displacements" mesh="StructureMesh"/>
  <exchange data="Forces" mesh="StructureMesh" from="FluidSolver" to="SolidSolver" />
  <exchange data="Displacements" mesh="StructureMesh" from="SolidSolver" to="FluidSolver"/>
</coupling-scheme:serial-implicit>
[...]