Check if initial data returned from the micro simulation is the data …

…that the adaptivity computation requires (#109)

* Check if initial data returned from the micro simulation is the data that the adaptivity computation requires

* Add CHANGELOG entry

* Rephrase exception

* Add documentation about initializing micro simulations

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## latest
 
+- Check if initial data returned from the micro simulation is the data that the adaptivity computation requires https://github.com/precice/micro-manager/pull/109
 - Use executable `micro-manager-precice` by default, and stop using the script `run_micro_manager.py` https://github.com/precice/micro-manager/pull/105
 - Make `initialize()` method of the MicroManager class public https://github.com/precice/micro-manager/pull/105
 - Optionally use initial macro data to initialize micro simulations https://github.com/precice/micro-manager/pull/104

docs/micro-simulation-convert-to-library.md

@@ -28,6 +28,8 @@ class MicroSimulation: # Name is fixed
         """
         Initialize the micro simulation and return initial data which will be used in computing adaptivity before the first time step.
 
+        Defining this function is OPTIONAL.
+
         Returns
         -------
         initial_data : dict
@@ -95,6 +97,10 @@ The `solve()` function should have the following signature:
     This will create a shared library `micro_dummy.so` which can be directly imported in Python.
     For more information on compiling C++ libraries, see the [pybind11 documentation](https://pybind11.readthedocs.io/en/stable/compiling.html).
 
+## Initializing micro simulations
+
+Micro simulations can be initialized before the actual coupling starts. To initialize a micro simulation, define an `initialize()` function in the code. The Micro Manager calls the initialize function for every micro simulation. If the macro simulation writes initial data to preCICE, the Micro Manager attempts to pass it to the micro simulation. If the `initialize()` function does not have input parameters, the initial data will not be passed. The `initialize()` function can return data to the Micro Manager. This data is only relevant to compute the adaptivity before the coupling starts. Therefore, if the `initialize()` functions returns data, it must be the data expected by the adaptivity.
+
 ## Next step
 
 After restructuring your micro simulation code into a Python-importable class structure, [configure the Micro Manager](tooling-micro-manager-configuration.html).

micro_manager/micro_manager.py

@@ -488,7 +488,7 @@ def initialize(self) -> None:
 
         if not is_initial_data_required and is_initial_data_available:
             warn(
-                "The initialize() method of the micro simulation does not require initial data, but initial data has been provided. The provided initial data will be ignored."
+                "The initialize() method is only allowed to return data which is required for the adaptivity calculation."
             )
 
         # Get initial data from micro simulations if initialize() method exists
@@ -519,7 +519,14 @@ def initialize(self) -> None:
                 if self._is_adaptivity_on:
                     # Save initial data from first micro simulation as we anyway have it
                     for name in initial_micro_output.keys():
-                        self._data_for_adaptivity[name][0] = initial_micro_output[name]
+                        if name in self._data_for_adaptivity:
+                            self._data_for_adaptivity[name][0] = initial_micro_output[
+                                name
+                            ]
+                        else:
+                            raise Exception(
+                                "The initialize() method needs to return data which is required for the adaptivity calculation."
+                            )
 
                     # Gather initial data from the rest of the micro simulations
                     if is_initial_data_required: