Clearly differentiate between solver_dt and dt (#245)

* Differentiate between participant_dt and dt

* Consistently introduce solver_dt.

* Fix order.

pages/docs/couple-your-code/couple-your-code-implicit-coupling.md

@@ -43,8 +43,9 @@ int forceID = precice.getDataID("Forces", meshID);
 double* forces = new double[vertexSize*dim];
 double* displacements = new double[vertexSize*dim];
 
-double dt; // solver timestep size
+double solver_dt; // solver timestep size
 double precice_dt; // maximum precice timestep size
+double dt; // actual time step size
 ```
 
 ```cpp
@@ -56,8 +57,8 @@ while (precice.isCouplingOngoing()){
   }
   precice.readBlockVectorData(displID, vertexSize, vertexIDs, displacements);
   setDisplacements(displacements);
-  dt = beginTimeStep(); // e.g. compute adaptive dt 
-  dt = min(precice_dt, dt);
+  solver_dt = beginTimeStep(); // e.g. compute adaptive dt
+  dt = min(precice_dt, solver_dt);
   solveTimeStep(dt);
   computeForces(forces);
   precice.writeBlockVectorData(forceID, vertexSize, vertexIDs, forces);

pages/docs/couple-your-code/couple-your-code-mesh-and-data-access.md

@@ -60,15 +60,16 @@ int forceID = precice.getDataID("Forces", meshID);
 double* forces = new double[vertexSize*dim];
 double* displacements = new double[vertexSize*dim];
 
-double dt; // solver timestep size
+double solver_dt; // solver timestep size
 double precice_dt; // maximum precice timestep size
+double dt; // actual time step size
 
 precice_dt = precice.initialize();
 while (not simulationDone()){ // time loop
         precice.readBlockVectorData(displID, vertexSize, vertexIDs, displacements);
   setDisplacements(displacements);
-  dt = beginTimeStep(); // e.g. compute adaptive dt 
-  dt = min(precice_dt, dt);
+  solver_dt = beginTimeStep(); // e.g. compute adaptive dt
+  dt = min(precice_dt, solver_dt);
   solveTimeStep(dt);
   computeForces(forces);
   precice.writeBlockVectorData(forceID, vertexSize, vertexIDs, forces);

pages/docs/couple-your-code/couple-your-code-steering-methods.md

@@ -12,14 +12,14 @@ The handle to the preCICE API is the class `precice::SolverInterface`. Its const
 ```cpp
 SolverInterface( String participantName, String configurationFileName, int rank, int size );
 double initialize();
-double advance ( double computedTimestepLength ); 
+double advance ( double computedTimestepLength );
 void finalize();
 ```
 
 What do they do?
 
 * `initialize` establishes communication channels, sets up data structures of preCICE, and returns the maximum timestep size the solver should use next. But let's ignore timestep sizes for the moment. This will be the topic of [Step 5](couple-your-code-timestep-sizes.html).
-* `advance` needs to be called after the computation of every timestep to _advance_ the coupling. As an argument, you have to pass the solver's last timestep size. Again, the function returns the next maximum timestep size you can use. More importantly, it maps coupling data between the coupling meshes, it communicates coupling data between the coupled participants, and it accelerates coupling data. One could say the complete coupling happens within this single function.
+* `advance` needs to be called after the computation of every timestep to _advance_ the coupling. As an argument, you have to pass the solver's last timestep size (`dt`). Again, the function returns the next maximum timestep size you can use (`precice_dt`). More importantly, it maps coupling data between the coupling meshes, it communicates coupling data between the coupled participants, and it accelerates coupling data. One could say the complete coupling happens within this single function.
 * `finalize` frees the preCICE data structures and closes communication channels.
 
 So, let's extend the code of our fluid solver:
@@ -31,13 +31,14 @@ turnOnSolver(); //e.g. setup and partition mesh
 
 precice::SolverInterface precice("FluidSolver","precice-config.xml",rank,size); // constructor
 
-double dt; // solver timestep size
+double solver_dt; // solver timestep size
 double precice_dt; // maximum precice timestep size
+double dt; // actual time step size
 
 precice_dt = precice.initialize();
 while (not simulationDone()){ // time loop
-  dt = beginTimeStep(); // e.g. compute adaptive dt 
-  dt = min(precice_dt, dt); // more about this in Step 5
+  solver_dt = beginTimeStep(); // e.g. compute adaptive dt
+  dt = min(precice_dt, solver_dt); // more about this in Step 5
   solveTimeStep(dt);
   precice_dt = precice.advance(dt);
   endTimeStep(); // e.g. update variables, increment time

pages/docs/couple-your-code/couple-your-code-timestep-sizes.md

@@ -9,13 +9,14 @@ In previous steps, you have already seen that there are quite some things going
 
 ```cpp
 ...
-double dt; // solver timestep size
+double solver_dt; // solver timestep size
 double precice_dt; // maximum precice timestep size
+double dt; // actual timestep size
 
 precice_dt = precice.initialize();
 while (not simulationDone()){ // time loop
-  dt = beginTimeStep(); // e.g. compute adaptive dt 
-  dt = min(precice_dt, dt);
+  solver_dt = beginTimeStep(); // e.g. compute adaptive dt
+  dt = min(precice_dt, solver_dt);
   solveTimeStep(dt);
   precice_dt = precice.advance(dt);
   endTimeStep(); // e.g. update variables, increment time
@@ -50,18 +51,18 @@ The figure below illustrates this procedure (k is the subcycling index, the dash
 precice_dt = precice.advance(dt);
 ```  
 
-* Both participants compute their next (adaptive) timestep size. It can be larger or smaller than the remainder.
+* Both participants compute their next (adaptive) timestep size. It can be larger or smaller than the remainder `precice_dt`.
 
 ```c++
-dt = beginTimeStep();
+solver_dt = beginTimeStep();
 ```
 
-If it is larger, the remainder `dt_precice` is used instead (orange participant, dark orange is used).
-If it is smaller, the participant's timestep size `dt` can be used (blue participant, dark blue is used).
+If it is larger, the remainder `precice_dt` is used instead (orange participant, dark orange is used).
+If it is smaller, the participant's timestep size `solver_dt` can be used (blue participant, dark blue is used).
 These two cases are reflected in:
 
 ```c++
-dt = min(precice_dt, dt)
+dt = min(precice_dt, solver_dt)
 ```
 
 * Once both participants reach the end of the time window, coupling data is exchanged.
@@ -86,8 +87,8 @@ while (not simulationDone()){ // time loop
     precice.readBlockVectorData(displID, vertexSize, vertexIDs, displacements);
     setDisplacements(displacements);
   }
-  dt = beginTimeStep(); // e.g. compute adaptive dt 
-  dt = min(precice_dt, dt);
+  solver_dt = beginTimeStep(); // e.g. compute adaptive dt
+  dt = min(precice_dt, solver_dt);
   solveTimeStep(dt);
   if (precice.isWriteDataRequired(dt)){
     computeForces(forces);
@@ -115,21 +116,21 @@ precice_dt = precice.advance(dt);
 * A computes its next (adaptive) timestep size. It can now be larger or smaller than the remainder.
 
 ```c++
-dt = beginTimeStep();
+solver_dt = beginTimeStep();
 ```
 
-If it is larger, the remainder `dt_precice` is used instead (the case below in Step 3, dark orange is used).
-If it is smaller, the participant's timestep size `dt` can be used (not visualized).
+If it is larger, the remainder `precice_dt` is used instead (the case below in Step 3, dark orange is used).
+If it is smaller, the participant's timestep size `solver_dt` can be used (not visualized).
 These two cases are again reflected in the formula:
 
 ```c++
-dt = min(precice_dt, dt)
+dt = min(precice_dt, solver_dt)
 ```
 
 * The procedure starts over with the blue participant B.
 
 {% note %}
-`precice_dt` on the blue side is always infinity such that `min(dt,precice_dt)==dt`.
+`precice_dt` on the blue side is always infinity such that `min(solver_dt,precice_dt)==solver_dt`.
 {% endnote %}
 
 {% important %}

pages/docs/couple-your-code/couple-your-code-waveform.md

@@ -78,8 +78,8 @@ precice_dt = precice.initialize();
 while (not simulationDone()){ // time loop
   // write checkpoint
   ...
-  dt = beginTimestep(); // e.g. compute adaptive dt
-  dt = min(precice_dt, dt);
+  solver_dt = beginTimestep(); // e.g. compute adaptive dt
+  dt = min(precice_dt, solver_dt);
   if (precice.isReadDataAvailable()){ // if waveform order >= 1 always true, because we can sample at arbitrary points
     // sampling in the middle of the timestep
     precice.readBlockVectorData(displID, vertexSize, vertexIDs, 0.5 * dt, displacements);