Update documentation w.r.t getMaxTimeStep().

* Implements changes from precice/precice#1623

_data/sidebars/docs_sidebar.yml

@@ -388,55 +388,55 @@ entries:
         - title: Step 2 – Steering methods
           url: /couple-your-code-steering-methods.html
           output: web, pdf
-          
+
         - title: Step 3 – Mesh and data access
           url: /couple-your-code-mesh-and-data-access.html
           output: web, pdf
-          
+
         - title: Step 4 – Coupling flow
           url: /couple-your-code-coupling-flow.html
           output: web, pdf
-          
+
         - title: Step 5 – Non-matching timestep sizes
-          url: /couple-your-code-timestep-sizes.html
+          url: /couple-your-code-time-step-sizes.html
           output: web, pdf
-          
+
         - title: Step 6 – Implicit coupling
           url: /couple-your-code-implicit-coupling.html
           output: web, pdf
-          
+
         - title: Step 7 – Data initialization
           url: /couple-your-code-initializing-coupling-data.html
           output: web, pdf
-          
+
         - title: Step 8 – Mesh connectivity
           url: /couple-your-code-defining-mesh-connectivity.html
           output: web, pdf
 
         - title: Step 9 – Gradient Data
           url: /couple-your-code-gradient-data.html
           output: web, pdf
-          
+
       - title: Advanced topics
         output: web, pdf
         subfolderitems:
 
         - title: Adapter software engineering
           url: /couple-your-code-adapter-software-engineering.html
           output: web, pdf
-          
+
         - title: Initialization in existing MPI environment
           url: /couple-your-code-existing-mpi-environment.html
           output: web, pdf
- 
+
         - title: Dealing with moving meshes
           url: /couple-your-code-moving-meshes.html
           output: web, pdf
-          
+
         - title: Dealing with FEM meshes
           url: /couple-your-code-fem-meshes.html
           output: web, pdf
-          
+
         - title: Dealing with distributed meshes
           url: /couple-your-code-distributed-meshes.html
           output: web, pdf

pages/docs/configuration/configuration-coupling.md

@@ -39,7 +39,7 @@ Now, the `first` and the `second` participant are executed at the same time. Act
 With `max-time-windows`, you say how many coupling time windows you want to simulate. Alternatively, you can use:
 
 ```xml
-<max-time value="1.0"/> 
+<max-time value="1.0"/>
 ```
 
 Afterwards,
@@ -48,9 +48,9 @@ Afterwards,
 precice.isCouplingOngoing()
 ```
 
-will return false and `precice.finalize()` should be called (compare with [step 5 of the couple-your-code section](couple-your-code-timestep-sizes.html#steering-the-end-of-the-simulation)).  
+will return false and `precice.finalize()` should be called (compare with [step 5 of the couple-your-code section](couple-your-code-time-step-sizes.html#steering-the-end-of-the-simulation)).
 
-With `time-window-size`, you can define the coupling time window (=coupling time step) size. If a participant uses a smaller one, it will subcycle until this _window_ size is reached. Find more details also in [step 5 of the couple-your-code section](couple-your-code-timestep-sizes.html).
+With `time-window-size`, you can define the coupling time window (=coupling time step) size. If a participant uses a smaller one, it will subcycle until this _window_ size is reached. Find more details also in [step 5 of the couple-your-code section](couple-your-code-time-step-sizes.html).
 
 Finally, with `exchange`, you need to define which data values should be exchanged within this coupling scheme:
 
@@ -68,7 +68,7 @@ For implicit coupling, you need to specify several additional options:
 <coupling-scheme:parallel-implicit>
   <participants first="MySolver1" second="MySolver2"/>
   ...
-  <exchange data="Temperature" mesh="MyMesh2" from="MySolver2" to="MySolver1"/>        
+  <exchange data="Temperature" mesh="MyMesh2" from="MySolver2" to="MySolver1"/>
   <max-iterations value="100"/>
   <relative-convergence-measure limit="1e-4" data="Displacements" mesh="MyMesh2"/>
   <relative-convergence-measure limit="1e-4" data="Forces" mesh="MyMesh2"/>
@@ -82,7 +82,7 @@ To control the number of sub-iterations within an implicit coupling loop, you ca
 
 * `relative-convergence-measure` for a relative criterion
 * `absolute-convergence-measure` for an absolute criterion
-* `min-iteration-convergence-measure` to require a minimum of iterations  
+* `min-iteration-convergence-measure` to require a minimum of iterations
 If multiple convergence measure are combined they all need to be fulfilled to go to the next time window. Alternatively, you can specify `suffices="yes"` within any convergence measure.
 The data used for a convergence measure needs to be exchanged within the coupling-scheme (tag `exchange`).
 

pages/docs/couple-your-code/couple-your-code-existing-mpi-environment.md

@@ -31,7 +31,7 @@ precice.configure("precice-config.xml");
 
 [...] // declare meshes vertices etc.
 
-double preciceDt = precice.initialize();
+precice.initialize();
 
 [...] // solving and coupling
 

pages/docs/couple-your-code/couple-your-code-gradient-data.md

@@ -72,7 +72,7 @@ double* stress = new double[vertexSize * dim];
 // create gradient data
 double* stressGradient = new double[vertexSize * dim * dim]
 [...]
-preciceDt = precice.initialize();
+precice.initialize();
 
 while (not simulationDone()){ // time loop
   precice.readBlockVectorData(displID, vertexSize, vertexIDs, displacements);
@@ -89,7 +89,7 @@ while (not simulationDone()){ // time loop
     precice.writeBlockVectorGradientData(stressID, vertexSize, vertexIDs, stressGradient);
   }
 
-  preciceDt = precice.advance(dt);
+  precice.advance(dt);
 }
 [...]
 ```

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

@@ -49,7 +49,8 @@ double dt; // actual time step size
 ```
 
 ```cpp
-preciceDt = precice.initialize();
+precice.initialize();
+preciceDt = precice.getMaxTimeStepSize();
 while (precice.isCouplingOngoing()){
   if(precice.isActionRequired(cowic)){
     saveOldState(); // save checkpoint
@@ -62,7 +63,8 @@ while (precice.isCouplingOngoing()){
   solveTimeStep(dt);
   computeForces(forces);
   precice.writeBlockVectorData(forceID, vertexSize, vertexIDs, forces);
-  preciceDt = precice.advance(dt);
+  precice.advance(dt);
+  preciceDt = precice.getMaxTimeStepSize();
   if(precice.isActionRequired(coric)){ // timestep not converged
     reloadOldState(); // set variables back to checkpoint
     precice.markActionFulfilled(coric);

pages/docs/couple-your-code/couple-your-code-initializing-coupling-data.md

@@ -33,14 +33,13 @@ double* displacements = new double[vertexSize*dim];
 
 [...]
 
-preciceDt = precice.initialize();
 
 if(precice.isActionRequired(cowid)){
   precice.writeBlockVectorData(forceID, vertexSize, vertexIDs, forces);
   precice.markActionFulfilled(cowid);
 }
 
-precice.initializeData();
+precice.initialize();
 
 while (precice.isCouplingOngoing()){
   [...]

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

@@ -64,16 +64,18 @@ double solverDt; // solver timestep size
 double preciceDt; // maximum precice timestep size
 double dt; // actual time step size
 
-preciceDt = precice.initialize();
+precice.initialize();
+preciceDt = precice.getMaxTimeStepSize();
 while (not simulationDone()){ // time loop
-        precice.readBlockVectorData(displID, vertexSize, vertexIDs, displacements);
+  precice.readBlockVectorData(displID, vertexSize, vertexIDs, displacements);
   setDisplacements(displacements);
   solverDt = beginTimeStep(); // e.g. compute adaptive dt
   dt = min(preciceDt, solverDt);
   solveTimeStep(dt);
   computeForces(forces);
   precice.writeBlockVectorData(forceID, vertexSize, vertexIDs, forces);
-  preciceDt = precice.advance(dt);
+  precice.advance(dt);
+  preciceDt = precice.getMaxTimeStepSize();
   endTimeStep(); // e.g. update variables, increment time
 }
 precice.finalize(); // frees data structures and closes communication channels

pages/docs/couple-your-code/couple-your-code-preparing-your-solver.md

@@ -8,12 +8,12 @@ summary: "If you want to couple your own code you need to properly understand it
 Let's say you want to prepare a fluid solver for fluid-structure interaction and that your code looks like this:
 
 ```cpp
-turnOnSolver(); //e.g. setup and partition mesh 
+turnOnSolver(); //e.g. setup and partition mesh
 
 double dt; // solver timestep size
 
 while (not simulationDone()){ // time loop
-  dt = beginTimeStep(); // e.g. compute adaptive dt 
+  dt = beginTimeStep(); // e.g. compute adaptive dt
   solveTimeStep(dt);
   endTimeStep(); // e.g. update variables, increment time
 }

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

@@ -11,18 +11,24 @@ 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 );
+void initialize();
+void advance ( double computedTimeStepSize );
 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 (`dt`). Again, the function returns the next maximum timestep size you can use (`preciceDt`). 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.
+* `initialize` establishes communication channels and sets up data structures of preCICE.
+* `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`). Additionally, 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:
+The following function allows us to query the maximum allowed time step size from preCICE:
+
+```cpp
+double getMaxTimeStepSize();
+```
+
+But let's ignore the details of time step sizes for the moment. This will be the topic of [Step 5](couple-your-code-time-step-sizes.html). We can now extend the code of our fluid solver:
 
 ```cpp
 #include "precice/SolverInterface.hpp"
@@ -35,12 +41,14 @@ double solverDt; // solver timestep size
 double preciceDt; // maximum precice timestep size
 double dt; // actual time step size
 
-preciceDt = precice.initialize();
+precice.initialize();
+preciceDt = getMaxTimeStepSize();
 while (not simulationDone()){ // time loop
   solverDt = beginTimeStep(); // e.g. compute adaptive dt
   dt = min(preciceDt, solverDt); // more about this in Step 5
   solveTimeStep(dt);
-  preciceDt = precice.advance(dt);
+  precice.advance(dt);
+  preciceDt = getMaxTimeStepSize();
   endTimeStep(); // e.g. update variables, increment time
 }
 precice.finalize(); // frees data structures and closes communication channels