Add snapshot computation docs and improve micro manager docs

docs/README.md

@@ -11,6 +11,8 @@ The Micro Manager manages many simulations on a micro scale and couples them to
 
 ![Micro Manager strategy schematic](images/docs-tooling-micro-manager-manager-solution.png)
 
+The Micro Manager can also compute snapshots of micro simulations given macro input parameters in an offline manner without preCICE.
+
 ## What can it do?
 
 The Micro Manager couples many micro simulations with one macro simulation. This includes ...
@@ -21,9 +23,13 @@ The Micro Manager couples many micro simulations with one macro simulation. This
 
 ## Documentation
 
-To use the Micro Manager for a macro-micro coupling, your micro simulation code needs to be in a library format with a specific class name and functions with specific names. For a macro-micro coupled problem, the macro simulation code is coupled to preCICE directly. The section [couple your code](couple-your-code-overview.html) of the preCICE documentation gives more details on coupling existing codes. To setup a macro-micro coupled simulation using the Micro Manager, follow these steps:
+To use the Micro Manager for a macro-micro coupling, your micro simulation code needs to be in a library format with a specific class name and functions with specific names. For a macro-micro coupled problem, the macro simulation code is coupled to preCICE directly. The section [couple your code](couple-your-code-overview.html) of the preCICE documentation gives more details on coupling existing codes. To set up a macro-micro coupled simulation using the Micro Manager, follow these steps:
 
 - [Installation](tooling-micro-manager-installation.html)
 - [Preparing micro simulation](tooling-micro-manager-prepare-micro-simulation.html)
 - [Configuration](tooling-micro-manager-configuration.html)
 - [Running](tooling-micro-manager-running.html)
+
+To compute snapshots in an offline manner your simulation code also needs to be in a library format with a specific class name and functions with specific names. To set up a snapshot computation using the Micro Manager, follow these steps:
+
+- [Snapshot computation](tooling-micro-manager-snapshot-configuration.html)

docs/configuration.md

@@ -16,11 +16,11 @@ The Micro Manager is configured with a JSON file. An example configuration file
         "config_file_name": "precice-config.xml",
         "macro_mesh_name": "macro-mesh",
         "read_data_names": {"temperature": "scalar", "heat-flux": "vector"},
-        "write_data_names": {"porosity": "scalar", "conductivity": "vector"},
-        "micro_time_window_size": 1.0
+        "write_data_names": {"porosity": "scalar", "conductivity": "vector"}
     },
     "simulation_params": {
         "macro_domain_bounds": [0.0, 1.0, 0.0, 1.0, 0.0, 1.0],
+        "micro_dt": 1.0
     },
     "diagnostics": {
       "output_micro_sim_solve_time": "True"
@@ -42,7 +42,6 @@ Parameter | Description
 `macro_mesh_name` |  Name of the macro mesh as stated in the preCICE configuration.
 `read_data_names` |  A Python dictionary with the names of the data to be read from preCICE as keys and `"scalar"` or `"vector"`  as values depending on the nature of the data.
 `write_data_names` |  A Python dictionary with the names of the data to be written to preCICE as keys and `"scalar"` or `"vector"`  as values depending on the nature of the data.
-`micro_dt` | Initial time window size (dt) of the micro simulation.
 
 ## Simulation Parameters
 
@@ -51,6 +50,7 @@ Parameter | Description
 `macro_domain_bounds`| Minimum and maximum bounds of the macro-domain, having the format `[xmin, xmax, ymin, ymax, zmin, zmax]` in 3D and `[xmin, xmax, ymin, ymax]` in 2D.
 Domain decomposition parameters | See section on [domain decomposition](#domain-decomposition). But default, the Micro Manager assumes that it will be run in serial.
 Adaptivity parameters | See section on [adaptivity](#adaptivity). By default, adaptivity is disabled.
+`micro_dt` | Initial time window size (dt) of the micro simulation.
 
 ## Diagnostics
 

docs/installation.md

@@ -40,6 +40,7 @@ Ensure that the following dependencies are installed:
 #### Optional dependencies
 
 * [sklearn](https://scikit-learn.org/stable/index.html)
+* [h5py](https://www.h5py.org/) (required for snapshot computations)
 
 #### Clone the Micro Manager
 

docs/running.md

@@ -17,6 +17,6 @@ The Micro Manager can also be run in parallel
 mpiexec -n micro-manager-precice micro-manager-config.json
 ```
 
-## What Happens When a Micro Simulation Crashes?
+### What happens when a micro simulation crashes?
 
 If a micro simulation crashes and the Micro Manager is configured to [interpolate a crashed micro simulation](tooling-micro-manager-configuration.html/#Interpolate-a-crashed-micro-simulation), the Micro Manager attempts to continue running. The error message from the micro simulation, along with the macro location are logged in the Micro Manager log file. The Micro Manager continues the simulation run even if a micro simulation crashes. Results of the crashed micro simulation are generated by interpolating results of a certain number of similar running simulations. The [inverse distance weighed](https://en.wikipedia.org/wiki/Inverse_distance_weighting) method is used. If more than 20% of global micro simulations crash or if locally no neighbors are available for interpolation, the Micro Manager terminates.

docs/snapshot_configuration.md

@@ -0,0 +1,106 @@
+---
+title: Snapshot Computation
+permalink: tooling-micro-manager-snapshot-configuration.html
+keywords: tooling, macro-micro, two-scale, snapshot
+summary: Set up the Micro Manager snapshot computation.
+---
+
+## Installation
+
+To perform snapshot computations, the in the coupled case optional dependency `h5py` becomes mandatory. To install `micro-manager-precice` with `h5py`, run
+
+```bash
+pip install --user micro-manager-precice[snapshot]
+```
+
+If you have already installed `micro-manager-precice`, you can install `h5py` separately by running
+
+```bash
+pip install --user h5py
+```
+
+## Preparation
+
+To prepare a micro simulation for the Micro Manager, follow the instructions in the [Micro Manager preparation guide](tooling-micro-manager-preparation.html).
+
+Note: The `initialize()` method is not supported for the snapshot computation.
+
+## Configuration
+
+The Micro Manager snapshot computation is configured with a JSON file. An example configuration file is
+
+```json
+{
+    "micro_file_name": "python-dummy/micro_dummy",
+    "coupling_params": {
+        "parameter_file_name": "parameter.hdf5",
+        "read_data_names": {"macro-scalar-data": "scalar", "macro-vector-data": "vector"},
+        "write_data_names": {"micro-scalar-data": "scalar", "micro-vector-data": "vector"},
+    },
+    "simulation_params": {
+        "micro_dt": 1.0,
+    },
+    "snapshot_params": {
+        "post_processing_file_name": "snapshot_postprocessing"
+    },
+    "diagnostics": {
+        "output_micro_sim_solve_time": "True"
+    }
+}
+```
+
+This example configuration file is in [`examples/snapshot-config.json`](https://github.com/precice/micro-manager/tree/develop/examples/snapshot-config.json).
+
+The path to the file containing the Python importable micro simulation class is specified in the `micro_file_name` parameter. If the file is not in the working directory, give the relative path.
+
+There are four main sections in the configuration file, the `coupling_params`, the `simulations_params`, the `snapshot_params` and the optional `diagnostics`.
+
+## Coupling Parameters
+
+Parameter | Description
+--- | ---
+`parameter_file_name` | Path to the HDF5 file containing the parameter space from the current working directory. Each macro parameter must be given as a dataset. Macro data for the same micro simulation should have the same index in the first dimension. The name must correspond to the names given in the config file.
+`read_data_names` | A Python dictionary with the names of the data to be read from preCICE as keys and `"scalar"` or `"vector"` as values depending on the nature of the data.
+`write_data_names` | A Python dictionary with the names of the data to be written to the database as keys and `"scalar"` or `"vector"` as values depending on the nature of the data.
+
+## Simulation Parameters
+
+Parameter | Description
+--- | ---
+`micro_dt` | Initial time window size (dt) of the micro simulation. Must be set even if the micro simulation is time-independent.
+
+## Snapshot Parameters
+
+Parameter | Description
+--- | ---
+`post_processing_file_name`| Path to the post-processing Python script from the current working directory. Providing a post-processing script is optional. The script must contain a class `PostProcessing` with a method `postprocessing(sim_output)` that takes the simulation output as an argument. The method can be used to post-process the simulation output before writing it to the database.
+
+## Diagnostics
+
+Parameter | Description
+--- | ---
+`output_micro_sim_solve_time` | If `True`, the Micro Manager writes the wall clock time of the `solve()` function of each micro simulation to the database.
+
+## Running
+
+The Micro Manager snapshot computation is run directly from the terminal by adding the `--snapshot` argument and by providing the path to the configuration file as an input argument in the following way
+
+```bash
+micro-manager-precice --snapshot snapshot-config.json
+```
+
+The Micro Manager snapshot computation can also be run in parallel
+
+```bash
+mpiexec -n <number-of-processes> micro-manager-precice --snapshot snapshot-config.json
+```
+
+where `<number-of-processes>` must be replaced with the number of processes to be used.
+
+### Results
+
+The results of the snapshot computation are written into `output/` in HDF5-format. Each parameter is stored in a separate dataset. The dataset names correspond to the names specified in the configuration file. The first dimension of the datasets corresponds to the macro parameter index.
+
+### What happens when a micro simulation crashes during snapshot computation?
+
+If the computation of a snapshot fails, the snapshot is skipped.