Add snapshot computation docs and improve micro manager docs (#116)

* Add snapshot docs and update micro manager docs

* Add snapshot configuration docs

* Adapt documentation

* Update postprocessing description

* Remove next step

* Apply suggestions from code review

Co-authored-by: Ishaan Desai <[email protected]>

* Move snapshot mention to -what can it do?-

---------

Co-authored-by: Ishaan Desai <[email protected]>

docs/README.md

@@ -19,11 +19,17 @@ The Micro Manager couples many micro simulations with one macro simulation. This
 - ... running micro simulations in parallel using MPI.
 - ... adaptively activating and deactivating micro simulations based on a similarity calculation.
 
+The Micro Manager can also compute snapshots of micro simulations given macro input parameters in an offline manner without preCICE.
+
 ## 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 use the Micro Manager for snapshot computation, the dependency `h5py` is necessary. 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
+
+Prepare your micro simulation for the Micro Manager snapshot computation by following the instructions in the [preparation guide](tooling-micro-manager-preparation.html).
+
+Note: The `initialize()` method is not supported for the snapshot computation.
+
+## Configuration
+
+Configure the snapshot computation functionality 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
+
+Run the snapshot computation directly from the terminal by adding the `--snapshot` argument to the Micro Manager executable, 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
+```
+
+Run the snapshot computation in parallel by
+
+```bash
+mpiexec -n <number-of-processes> micro-manager-precice --snapshot snapshot-config.json
+```
+
+where `<number-of-processes>` is the number of processes 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.