Update documentation for initialize

pages/docs/configuration/configuration-action.md

@@ -10,9 +10,9 @@ There are two types of coupling actions: pre-implemented ones and user-defined o
 ## Basics and pre-implemented actions
 
 ```xml
-<participant name="MySolver1"> 
-    <use-mesh name="MyMesh1" provide="yes"/> 
-    <write-data name="Stresses" mesh="MyMesh1"/> 
+<participant name="MySolver1">
+    <use-mesh name="MyMesh1" provide="yes"/>
+    <write-data name="Stresses" mesh="MyMesh1"/>
     ...
     <action:multiply-by-area mesh="MyMesh1" timing="write-mapping-post">
         <target-data name="Stresses"/>
@@ -31,10 +31,10 @@ This example multiplies the stresses values by the respective element area, tran
 
 <details markdown="1"><summary>Older (preCICE version < 2.1.0) timings that are deprecated and revert to one of the above options: (click for details)</summary>
 
-* `regular-prior`: In every `advance` call (also for subcycling) and in `initializeData`, after `write` data is mapped, but _before_ data might be sent. (_v2.1 or later: reverts to `write-mapping-prior`_)
-* `regular-post`: In every `advance` call (also for subcycling), in `initializeData` and in `initialize`, before `read` data is mapped, but _after_ data might be received and after acceleration. (_v2.1 or later: reverts to `read-mapping-prior`_)
-* `on-exchange-prior`: Only in those `advance` calls which lead to data exchange (and in `initializeData`), after `write` data is mapped, but _before_ data might be sent. (_v2.1 or later: reverts to `write-mapping-post`_)
-* `on-exchange-post`: Only in those `advance` calls which lead to data exchange (and in `initializeData` and `ìnitialize`), before `read` data is mapped, but _after_ data might be received. (_v2.1 or later: reverts to `read-mapping-prior`_)
+* `regular-prior`: In every `advance` call (also for subcycling) and in `initialize`, after `write` data is mapped, but _before_ data might be sent. (_v2.1 or later: reverts to `write-mapping-prior`_)
+* `regular-post`: In every `advance` call (also for subcycling) and in `initialize`, before `read` data is mapped, but _after_ data might be received and after acceleration. (_v2.1 or later: reverts to `read-mapping-prior`_)
+* `on-exchange-prior`: Only in those `advance` calls which lead to data exchange (and in `initialize`), after `write` data is mapped, but _before_ data might be sent. (_v2.1 or later: reverts to `write-mapping-post`_)
+* `on-exchange-post`: Only in those `advance` calls which lead to data exchange (and in `initialize`), before `read` data is mapped, but _after_ data might be received. (_v2.1 or later: reverts to `read-mapping-prior`_)
 
 </details><br />
 
@@ -79,8 +79,8 @@ We show an example for the [1D elastic tube](tutorials-elastic-tube-1d.html):
 The callback interface consists of the following three (optional) functions:
 
 ```python
-performAction(time, sourceData, targetData) 
-vertexCallback(id, coords, normal) 
+performAction(time, sourceData, targetData)
+vertexCallback(id, coords, normal)
 postAction()
 ```
 
@@ -133,7 +133,7 @@ def vertexCallback(id, coords, normal):
     global mySourceData # Make global data set in performAction visible
     global myTargetData
     # Example usage, add data to vertex coords:
-    # myTargetData[id] += coords[0] + mySourceData[id] 
+    # myTargetData[id] += coords[0] + mySourceData[id]
 
 def postAction():
     # This function is called at last, if not omitted.

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

@@ -17,11 +17,11 @@ In our example, we currently use a serial coupling scheme:
 ```xml
 <coupling-scheme:serial-explicit>
   <participants first="FluidSolver" second="SolidSolver"/>
-  ...  
+  ...
 </coupling-scheme:serial-explicit>
 ```
 
-`FluidSolver` is first and `SolidSolver` second. This means that `FluidSolver` starts the simulation and computes the first timestep, while `SolidSolver` still waits. Where does it wait? Well, communciation in preCICE only happens within `initialize` and `advance` (and `initializeData`, but more about this in [Step 7](couple-your-code-initializing-coupling-data.html)):
+`FluidSolver` is first and `SolidSolver` second. This means that `FluidSolver` starts the simulation and computes the first timestep, while `SolidSolver` still waits. Where does it wait? Well, communciation in preCICE only happens within `initialize` and `advance`:
 
 * `FluidSolver` computes the first timestep and then sends and receives data in `advance`. The receive call blocks.
 * `SolidSolver` waits in `initialize` for the first data. When it receives the data it computes its first timestep and then calls `advance`.
@@ -31,7 +31,7 @@ In our example, we currently use a serial coupling scheme:
 ***
 
 <img class="img-responsive" src="images/docs/couple-your-code-serial-coupling.svg" alt="Serial coupling flow" style="width:100%">
-  
+
 ***
 
 Try to swap the roles of `first` and `second` in your example. Do you see the difference? If everything is just too fast, add some `sleep` calls.

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

@@ -5,19 +5,17 @@ keywords: api, adapter, initialization, coupling scheme, restart
 summary: "As default values, preCICE assumes that all coupling variables are zero initially. For fluid-structure interaction, for example, this means that the structure is in its reference state. Sometimes, you want to change this behavior – for instance, you may want to restart your simulation."
 ---
 
-For initializing coupling data, you can add the following **optional** method:
+{% version 3.0.0 %}
+`initializeData()` will be removed in preCICE version 3.0.0. You can do data initialization now by calling `initialize()`.
+{% endversion %}
+
+By default preCICE assumes that all coupling variables are zero initially. If you want to provide non-zero initial values, you can write data before calling `initialize()`. This data will then be used as initial data. The preCICE action interface that was introduced in [Step 6](couple-your-code-implicit-coupling) provides the following action to check whether initial data has to be written by a participant:
 
 ```cpp
-void initializeData();
+const std::string& constants::actionWriteInitialData()
 ```
 
-Before jumping into the implementation, let's try to clarify how the usual the sequence of events in a serial and in a parallel coupling as studied in [Step 4](couple-your-code-coupling-flow) changes.
-
-TODO: picture
-
-In a serial coupling, only the second participant can send data inside `initializeData()`. In parallel coupling, both participants can initialize data.
-
-The high-level API of preCICE makes it possible to enable this feature at runtime, irrelevant of serial or parallel coupling configuration. To support this feature, we extend our example as follows:
+To support data initialization, we extend our example as follows:
 
 ```cpp
 [...]
@@ -26,21 +24,19 @@ const std::string& cowid = precice::constants::actionWriteInitialData();
 
 [...]
 
-int displID = precice.getDataID("Displacements", meshID); 
-int forceID = precice.getDataID("Forces", meshID); 
+int displID = precice.getDataID("Displacements", meshID);
+int forceID = precice.getDataID("Forces", meshID);
 double* forces = new double[vertexSize*dim];
 double* displacements = new double[vertexSize*dim];
 
 [...]
 
-precice_dt = precice.initialize();
-
 if(precice.isActionRequired(cowid)){
   precice.writeBlockVectorData(forceID, vertexSize, vertexIDs, forces);
   precice.markActionFulfilled(cowid);
 }
 
-precice.initializeData();
+precice_dt = precice.initialize();
 
 while (precice.isCouplingOngoing()){
   [...]
@@ -54,3 +50,9 @@ Now, you can specify at runtime if you want to initialize coupling data. For exa
 <exchange data="Displacements" mesh="StructureMesh" from="SolidSolver" to="FluidSolver" initialize="yes"/>
 [...]
 ```
+
+If you are using a serial coupling scheme, only initial data that is written from the second to the first participant is actually used. Initial data written from the first to the second participant will be ignored, because in a serial coupling scheme the first participant already computes its first result before the second participant even starts.
+
+{% note %}
+preCICE still supports data initialization for both participants, even if a serial coupling scheme is used. You can read our section on [time interpolation](couple-your-code-waveform) to learn more about the reasons.
+{% endnote %}