v3: Make dt mandatory in documentation

images/docs/couple-your-code/couple-your-code-waveform/APIRelativeReadTime.tex

@@ -0,0 +1,43 @@
+\documentclass[]{standalone}
+
+\usepackage{tikz}
+\usepackage{pgf}
+\usepackage{pgfplots}
+\usetikzlibrary{positioning, calc, decorations.markings}
+
+\begin{document}
+
+\begin{tikzpicture}[scale=10]
+\node[circle, fill=black, label={[xshift=-1em]below right:$\vphantom{\frac{1}{2}}t_{n+1} = t_{n} + \Delta t$}](tnp1) at (1.3,0) {};
+\node[circle, fill=black, label={[xshift=-1em]below right:$\vphantom{\frac{1}{2}}\tau_{n}$}](taun) at (0,0) {};
+\node[circle, fill=black, label={[xshift=-1em]below right:$\vphantom{\frac{1}{2}}\tau_{n+1} = \tau_n + \delta t$}](taunp1) at (0.35,0) {};
+
+\draw[->](taun) edge[out=30,in=150] node[above, align=left, anchor=south west,xshift=-1cm]{(1) No more substeps: \\ \scriptsize{\texttt{precice.advance(preciceDt)}}}(tnp1);
+\draw[->](taun) edge[out=30,in=150] node[right, align=left, anchor=south west,pos=1]{(2) More substeps:\\  \scriptsize{\texttt{precice.advance(solverDt)}}} (taunp1);
+\node[above = 3cm of taun, label={[xshift=-1em, align=left]above right:Read interpolated data from current time $\tau_n$:\\ \scriptsize\texttt{precice.readBlockVectorData(relativeReadTime=dt, ...)}}](tau) {};
+\draw[->](tau) -- (taun);
+
+\node[below = of taun, label={[xshift=-1em,yshift=0.1cm]below right:\scriptsize\texttt{dt = 0}}](rdt0) {};
+\draw[->](rdt0) -- ($(taun)-(0,.2em)$);
+
+\draw[dotted] (taun) -- (taunp1);
+\draw[dotted] (taunp1) -- (tnp1);
+
+\node[circle, draw=black, fill=white, label={[xshift=-3.25em]below right:$\frac{1}{2}\left(\tau_n + \tau_{n+1}\right)$}](subcyclingmid) at ($0.5*(taun) + 0.5*(taunp1)$) {};
+\node[below = 4.5em of subcyclingmid, label={[xshift=-1em,yshift=0.2cm]below right:{\scriptsize\texttt{dt = 0.5 * solverDt}}}](rdtmid) {};
+\draw[->](rdtmid) -- ($(subcyclingmid)-(0,.2em)$);
+
+\node[below = of taunp1, label={[xshift=-1em,yshift=0.2cm]below right:\scriptsize\texttt{dt = solverDt}}](rdt1) {};
+\draw[->](rdt1) -- ($(taunp1)-(0,.2em)$);
+
+\node[below = of tnp1, label={[align=center,xshift=-1em,yshift=0.2cm]below right:\scriptsize\texttt{dt = preciceDt}}](rdtend) {};
+\draw[->](rdtend) -- ($(tnp1)-(0,.2em)$);
+
+
+\draw [decorate,decoration={brace,amplitude=2em,mirror}] ($(taun)-(0,.3)$) -- ($(taunp1)-(0,.3)$) node [black,midway,below,yshift=-2em, align=left] {Solver time step size $\delta t$\\ \scriptsize\texttt{solverDt < preciceDt} };
+
+\draw [decorate,decoration={brace,amplitude=2em,mirror}] ($(taun)-(0,.25)$) -- ($(tnp1)-(0,.25)$) node [black,midway,below,yshift=-2em, xshift=5em, align=left] {Complete time window size $\Delta t$ or remainder\\ \scriptsize\texttt{preciceDt = precice.getMaxTimeStepSize()}};
+\end{tikzpicture}
+
+\end{document}
+

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

@@ -33,8 +33,18 @@ void Participant::writeData(
     precice::span<const double>   values)
 ```
 
-<!-- TODO Also point to section where `relativeReadTime` is explained? We will probably solve this in https://github.com/precice/precice.github.io/pull/257 -->
-Similarly, there is a `readData` API function for reading coupling data.
+Similarly, there is a `readData` API function for reading coupling data:
+
+```cpp
+void readData(
+    precice::string_view          meshName,
+    precice::string_view          dataName,
+    precice::span<const VertexID> vertices,
+    double                        relativeReadTime,
+    precice::span<double>         values) const;
+```
+
+We will talk about the additional argument `relativeReadTime` in detail in [the section on time interpolation](couple-your-code-waveform.html).
 
 Let's define coupling meshes and access coupling data in our example code:
 

pages/docs/couple-your-code/couple-your-code-time-step-sizes.md

@@ -75,6 +75,45 @@ This procedure is independent of whether a serial or a parallel coupling scheme
 For parallel coupling, both solvers run together and everything happens simultaneously in both participants, while for serial coupling, the first participant needs reach the end of the window before the second one can start.
 {% endnote %}
 
+### Possible subcycling pitfall
+
+If you are using very small many time steps in one window, you might see the following error message:
+```
+ERROR: preCICE has detected a difference between its internal time and the time of this participant. This can happen, if you are using very many substeps per time window over multiple time windows.
+```
+preCICE ignores differences smaller than machine precision when comparing the time where a coupling window ends and the participant time it knows from subsequent `advance(dt)` calls. Such small differences are usually negligible. They, however, might add up over multiple windows and become relevant. If preCICE detects this, it raises the error message shown above as a safeguard.
+
+One strategy to avoid this error showing up is to replace the usual call for determining the `dt` you are using in the following way:
+
+```cpp
+...
+solverDt = beginTimeStep(); // e.g. compute adaptive dt
+// Can lead to using a dt that only approximately reaches end of time window
+// dt = min(preciceDt, solverDt);
+
+// Allow some tolerance
+double tol = 10e-14;
+if (preciceDt - solverDt < tol) {
+  // Use preciceDt, if difference between preciceDt and solverDt is small enough
+  dt = preciceDt;
+} else {
+  dt = min(preciceDt, solverDt);
+}
+precice.readData("FluidMesh", "Displacements", vertexIDs, dt, displacements);
+setDisplacements(displacements);
+solveTimeStep(dt);
+computeForces(forces);
+precice.writeData("FluidMesh", "Forces", vertexIDs, forces);
+// if dt = preciceDt, we will exactly reach the end of the window when calling advance
+precice.advance(dt);
+...
+```
+Here, a participant accepts `preciceDt`, even if it is bigger than `solverDt`, if the difference is not bigger than a certain tolerance `tol`. From the perspective of the participant this tolerance should be negligible with respect to the requirements (e.g. numerical stability)  that led to `solverDt`. With this modification the participant ensures that there is absolutely no difference between its internal time and the time used by preCICE and this eliminates the root cause for the error message from above.
+
+{% note %}
+The strategy presented above is only one possibility. Generally, the participant knows best how to determine the allowed time step size and there often are additional requirements you might want to consider, depending on the use case and discretization techniques the participant is using.
+{% endnote %}
+
 ## First participant prescribes time step size
 
 The `first` participant sets the time step size. This requires that the `second` participant runs after the `first` one. Thus, as stated above, this option is only applicable for serial coupling.

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

@@ -35,27 +35,26 @@ Linear interpolation between coupling boundary conditions of the previous and th
 
 If the Dirichlet participant $$\mathcal{D}$$ calls `readData`, it samples the data from a time-dependent function $$c_\mathcal{D}(t)$$. This function is created from linear interpolation of the first and the last sample $$c_{\mathcal{D}0}$$ and $$c_{\mathcal{D}5}$$ created by the Neumann participant $$\mathcal{N}$$ in the current time window. This allows $$\mathcal{D}$$ to sample the coupling condition at arbitrary times $$t$$ inside the current time window.
 
-{% note %}
-As soon as time interpolation is used to obtain data for a `relativeReadTime` that does not refer to the end of the current window, the data from the end of the previous window might be used to compute the interpolated value. For the first time window, this means one should provide appropriate initial data, since otherwise preCICE will use zero-valued initial data. There are, however, situations where initial data is not necessarily needed. For example, if one uses zeroth order time interpolation without accessing the data value at the beginning of the time window. It is still recommended to always provide initial data, if available. See ["Step 7 - Data initialization"](couple-your-code-initializing-coupling-data.md) for details on data initialization.
-{% endnote %}
+## API for waveform iteration
 
-## Experimental API for waveform iteration
-
-<!-- Related to https://github.com/precice/precice.github.io/pull/257 -->
-If we want to improve the accuracy by using waveforms, this requires an extension of the existing API, because we need a way to tell preCICE where we want to sample the waveform. For this purpose, preCICE offers an experimental API. Here, `readData` accepts an additional argument `relativeReadTime`. This allows us to choose the time where the waveform should be sampled:
+preCICE requires the argument `relativeReadTime` for the `readData` functions:
 
 ```cpp
 void Participant::readData(
     precice::string_view          meshName,
     precice::string_view          dataName,
     precice::span<const VertexID> vertices,
-    double                          relativeReadTime,
+    double                        relativeReadTime,
     precice::span<double>         values) const
 ```
 
-`relativeReadTime` describes the time relatively to the beginning of the current time step. This means that `relativeReadTime = 0` gives us access to data at the beginning of the time step. By choosing `relativeReadTime > 0` we can sample data at later points. The maximum allowed `relativeReadTime` corresponds to the remaining time until the end of the current time window. Remember that the remaining time until the end of the time window is always returned when calling `preciceDt = precice.getMaxTimeStepSize()` as `preciceDt`. So `relativeReadTime = preciceDt` corresponds to sampling data at the end of the current time window.
+In the previous sections of the step-by-step guide we always used `relativeReadTime = preciceDt` where `preciceDt = precice.getMaxTimeStepSize()` points to the end of the current time window (see, for example ["Step 5 - Non-matching time step sizes"](couple-your-code-time-step-sizes.html)). However, the original purpose of `relativeReadTime` is exactly to offer the user an interface for sampling from waveforms. The figure below illustrates how providing different values `dt` for `relativeReadTime` allows to sample interpolated values at different points in time:
+
+![API for relativeReadTime](images/docs/couple-your-code/couple-your-code-waveform/APIRelativeReadTime.png)
+
+`relativeReadTime` describes the time relatively to the beginning of the current time step starting at $$\tau_n$$. This means that `dt = 0` gives us access to data at the beginning of the time step. By choosing `dt > 0` we can sample data at points in time after $$\tau_n$$. The maximum allowed `dt = preciceDt` corresponds to $$\tau_n$$ plus the remaining time until the end of the current time window (i.e. `preciceDt = precice.getMaxTimeStepSize()`).
 
-If we choose to use a smaller time step size `dt < preciceDt`, we apply subcycling and therefore `relativeReadTime = dt` corresponds to sampling data at the end of the time step. But we can also use smaller values for `relativeReadTime`, as shown in the usage example below. When using subcycling, it is important to note that `relativeReadTime = preciceDt` is the default behavior, if no `relativeReadTime` is provided, because preCICE cannot know the `dt` our solver wants to use. This also means that if subcycling is applied one must use the experimental API and provide `relativeReadTime` to benefit from the higher accuracy waveforms.
+If we choose to use a smaller time step size `solverDt < preciceDt`, we apply subcycling and therefore `dt = solverDt` corresponds to sampling data at the end of the time step. But we can also use arbitrary values for `dt`, like `dt = 0.5 * solverDt` to implement, for example, a midpoint rule (see also the usage example below).
 
 The experimental API has to be activated in the configuration file via the `experimental` attribute. This allows us to define the order of the interpolant in the `read-data` tag of the corresponding `participant`. Currently, we support two interpolation schemes: constant and linear interpolation. The interpolant is always constructed using data from the beginning and the end of the window. The default is constant interpolation (`waveform-order="0"`). The following example uses `waveform-order="1"` and, therefore, linear interpolation: