Reworking documentation (#50)

* Incorporate first feedback

* Add Manager Solution image to overview page

* Using PNG image and not a PDF image

* Further incorporation of feedback

* Reworking converting micro simulation part

* Incorporate feedback for Configuration section of documentation

* Add workflows to check markdown and links, and incorporate further feedback

.github/workflows/check-links.yml

@@ -0,0 +1,14 @@
+name: Check links (manual)
+on: workflow_dispatch
+jobs:
+  check_links:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v2
+      - name: Check links in markdown files (markdown-link-check)
+        uses: gaurav-nelson/github-action-markdown-link-check@v1
+        with:
+          use-quiet-mode: 'yes'
+          use-verbose-mode: 'no'
+          config-file: '.markdown-link-check-config.json'

.github/workflows/check-markdown.yml

@@ -0,0 +1,13 @@
+name: Lint docs
+on: [push, pull_request]
+jobs:
+  check_md:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v2
+      - name: Lint markdown files (markdownlint)
+        uses: articulate/actions-markdownlint@v1
+        with:
+          config: .markdownlint.json
+          files: '.'

.markdown-link-check-config.json

@@ -0,0 +1,3 @@
+{
+  "aliveStatusCodes": [429, 200]
+}

.markdownlint.json

@@ -0,0 +1,5 @@
+{
+    "MD013": false,
+    "MD033": false,
+    "MD034": false
+}

docs/README.md

@@ -2,28 +2,28 @@
 title: The Micro Manager
 permalink: tooling-micro-manager-overview.html
 keywords: tooling, macro-micro, two-scale
-summary: The Micro Manager is a tool for solving two-scale (macro-micro) coupled problems using the coupling library preCICE.
+summary: A tool to manage many micro simulations and couple them to a macro simulation via preCICE.
 ---
 
 ## What is this?
 
-The Micro Manager is a tool for solving coupled problems where the coupling is across scales (for example macro-micro). It is developed as a library extension to the coupling library [preCICE](https://www.precice.org/).
+The Micro Manager manages many simulations on a micro scale and couples them to one simulation on a macro scale. For the coupling itself, it heavily relies on the coupling library [preCICE](https://precice.org/index.html).
+
+![Micro Manager strategy schematic](images/ManagerSolution.png)
 
 ## What can it do?
 
-The Micro Manager couples many micro simulations with one macro simulation. This includes
+The Micro Manager couples many micro simulations with one macro simulation. This includes ...
 
-- transferring scalar and vector data to and from a large number of micro simulations.
-- running micro simulations in parallel using MPI.
-- adaptively activating and deactivating micro simulations based on whether their similar exist.
+- ... transferring scalar and vector data to and from a large number of micro simulations.
+- ... running micro simulations in parallel using MPI.
+- ... adaptively activating and deactivating micro simulations based on a similarity calculation.
 
 ## Documentation
 
-The Micro Manager creates instances of several micro simulations and couples them to one macro simulation, using preCICE.
-
-An existing micro simulation code needs to be converted into a library with a specific class name which has 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 the 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 setup a macro-micro coupled simulation using the Micro Manager, follow these steps:
 
 - [Installation](tooling-micro-manager-installation.html)
-- [Micro simulation as callable library](tooling-micro-manager-micro-simulation-callable-library.html)
+- [Preparing micro simulation](tooling-micro-manager-micro-simulation-callable-library.html)
 - [Configuration](tooling-micro-manager-configuration.html)
 - [Running](tooling-micro-manager-running.html)

docs/configuration.md

@@ -1,11 +1,13 @@
 ---
-title: Configuration of the Micro Manager
+title: Configure the Micro Manager
 permalink: tooling-micro-manager-configuration.html
 keywords: tooling, macro-micro, two-scale
-summary: The Micro Manager uses a JSON file to configure the coupling. The coupled data has to be specified in the preCICE configuration file.
+summary: Provide a JSON file to configure the Micro Manager.
 ---
 
-The Micro Manager is configured at runtime using a JSON file. An example configuration file is
+{% note %} In the preCICE XML configuration the Micro Manager is a participant with the name `Micro-Manager`. {% endnote %}
+
+The Micro Manager is configured with a JSON file. An example configuration file is
 
 ```json
 {
@@ -25,10 +27,12 @@ The Micro Manager is configured at runtime using a JSON file. An example configu
 }
 ```
 
-There are three main sections in the configuration file, the `coupling_params`, the `simulation_params` and the optional `diagnostics`.
+This example configuration file is in [`examples/micro-manager-config.json`](https://github.com/precice/micro-manager/tree/main/examples/micro-manager-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 three main sections in the configuration file, the `coupling_params`, the `simulation_params` and the optional `diagnostics`.
+
 ## Coupling Parameters
 
 Parameter | Description
@@ -43,43 +47,66 @@ Parameter | Description
 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.
-*optional:* `adaptivity_similarity_measure`| Similarity measure to be used for adaptivity. Can be either `L1`, `L2`, `L1rel` or `L2rel`. By default, `L1` is used. The `rel` variants calculate the respective relative norms.
-*optional:* Domain decomposition parameters | See section on [Domain decomposition](#domain-decomposition). But default, the Micro Manager assumes that it will be run in serial.
-*optional:* Adaptivity parameters | See section on [Adaptivity](#adaptivity). By default, adaptivity is disabled.
+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.
 
-## *Optional*: Diagnostics
+## Diagnostics
 
 Parameter | Description
 --- | ---
-`data_from_micro_sims` | A Python dictionary with the names of the data from the micro simulation to be written to VTK files as keys and `"scalar"` or `"vector"` as values. This relies on the [export functionality](configuration-export.html#enabling-exporters) of preCICE and requires the corresponding export tag to be set in the preCICE XML configuration script.
-`output_micro_sim_solve_time` | If `True`, the Manager writes the wall clock time of the `solve()` function of each micro simulation to the VTK output.
+`data_from_micro_sims` | A Python dictionary with the names of the data from the micro simulation to be written to VTK files as keys and `"scalar"` or `"vector"` as values.
+`output_micro_sim_solve_time` | If `True`, the Micro Manager writes the wall clock time of the `solve()` function of each micro simulation.
 `micro_output_n`|  Frequency of calling the optional output functionality of the micro simulation in terms of number of time steps. If not given, `micro_sim.output()` is called every time step.
 
-An example configuration file can be found in [`examples/micro-manager-config.json`](https://github.com/precice/micro-manager/tree/main/examples/micro-manager-config.json).
+### Adding diagnostics in the preCICE XML configuration
+
+If the parameter `data_from_micro_sims` is set, the data to be output needs to be written to preCICE, and an export tag needs to be added for the participant `Micro-Manager`. For example, let us consider the case that the data `porosity`, which is a scalar, needs to be exported. Unless already defined, define the data, and then write it to preCICE. Also, add an export tag. The resulting entries in the XML configuration file look like:
+
+```xml
+<data:scalar name="porosity"/>
+
+<participant name="Micro-Manager">
+  ...
+  <write-data name="porosity" mesh="macro-mesh"/>
+  <export:vtu directory="Micro-Manager-output" every-n-time-windows="5"/>
+</participant>
+```
+
+If `output_micro_sim_solve_time` is set, add similar entries for the data `micro_sim_time` in the following way:
+
+```xml
+<data:scalar name="micro_sim_time"/>
+
+<participant name="Micro-Manager">
+  ...
+  <write-data name="micro_sim_time" mesh="macro-mesh"/>
+  <export:vtu directory="Micro-Manager-output" every-n-time-windows="5"/>
+</participant>
+```
 
 ## Domain decomposition
 
-The Micro Manager can be run in parallel. For a parallel run, set the desired number of paritions in each axis by setting the `axiswise_ranks` variable. For example, if the domain is 3D and the decomposition needs to be two paritions in x, one partition in y, and sixteen partitions in z, the setting is
+The Micro Manager can be run in parallel. For a parallel run, set the desired partitions in each axis by setting the `decomposition` parameter. For example, if the domain is 3D and the decomposition needs to be two partitions in x, one partition in y, and sixteen partitions in forz, the setting is
 
 ```json
 "simulation_params": {
     "macro_domain_bounds": [0, 1, 0, 1, 0, 1],
-	"axiswise_ranks": [2, 1, 16]
+    "decomposition": [2, 1, 16]
 }
 ```
 
-For a 2D domain, only two values need to be set `axiswise_ranks`.
+For a 2D domain, only two values need to be set for `decomposition`. The total number of partitions provided in the `decomposition` should be the same as the number of processors provided in the `mpirun`/`mpiexec` command.
 
 ## Adaptivity
 
-{% note %} This feature is optional. {% endnote %}
-
 The Micro Manager can adaptively control micro simulations. The adaptivity strategy is taken from
 
 1. Redeker, Magnus & Eck, Christof. (2013). A fast and accurate adaptive solution strategy for two-scale models with continuous inter-scale dependencies. Journal of Computational Physics. 240. 268-283. [10.1016/j.jcp.2012.12.025](https://doi.org/10.1016/j.jcp.2012.12.025).
 
 2. Bastidas, Manuela & Bringedal, Carina & Pop, Iuliu. (2021). A two-scale iterative scheme for a phase-field model for precipitation and dissolution in porous media. Applied Mathematics and Computation. 396. 125933. [10.1016/j.amc.2020.125933](https://doi.org/10.1016/j.amc.2020.125933).
 
+All the adaptivity parameters are chosen from the second publication.
+
 To turn on adaptivity, the following options need to be set in `simulation_params` under the sub-heading `adaptivity`:
 
 Parameter | Description
@@ -89,9 +116,8 @@ Parameter | Description
 `history_param` | History parameter $$ \Lambda $$, set as $$ \Lambda >= 0 $$.
 `coarsening_constant` | Coarsening constant $$ C_c $$, set as $$ C_c < 1 $$.
 `refining_constant` | Refining constant $$ C_r $$, set as $$ C_r >= 0 $$.
-`<every_implicit_iteration` | If True, adaptivity is calculated in every implicit iteration. <br> If False, adaptivity is calculated once at the start of the time window and then reused in every implicit time iteration.
-
-All variables are chosen from the [second publication](https://doi.org/10.1016/j.amc.2020.125933) mentioned above.
+`every_implicit_iteration` | If True, adaptivity is calculated in every implicit iteration. <br> If False, adaptivity is calculated once at the start of the time window and then reused in every implicit time iteration.
+`adaptivity_similarity_measure`| Similarity measure to be used for adaptivity. Can be either `L1`, `L2`, `L1rel` or `L2rel`. By default, `L1` is used. The `rel` variants calculate the respective relative norms. This parameter is *optional*.
 
 Example of adaptivity configuration
 
@@ -109,14 +135,16 @@ Example of adaptivity configuration
 }
 ```
 
-If adaptivity is turned on, the Micro Manager will attempt to write two scalar data per micro simulation to preCICE, called `active_state` and `active_steps`.
+### Adding adaptivity in the preCICE XML configuration
+
+If adaptivity is used, the Micro Manager will attempt to write two scalar data per micro simulation to preCICE, called `active_state` and `active_steps`.
 
 Parameter | Description
 --- | ---
 `active_state` | `1` if the micro simulation is active in the time window, and `0` if inactive.
 `active_steps` | Summation of `active_state` up to the current time window.
 
-The Micro Manager uses the output functionality of preCICE, hence these data sets to the preCICE configuration file. In the mesh and the micro participant add the following lines:
+The Micro Manager uses the output functionality of preCICE, hence these data sets need to be manually added to the preCICE configuration file. In the mesh and the participant Micro-Manager add the following lines:
 
 ```xml
 <data:scalar name="active_state"/>
@@ -127,12 +155,12 @@ The Micro Manager uses the output functionality of preCICE, hence these data set
     <use-data name="active_steps"/>
 </mesh>
 
-<participant name="micro-mesh">
+<participant name="Micro-Manager">
     <write-data name="active_state" mesh="macro-mesh"/>
     <write-data name="active_steps" mesh="macro-mesh"/>
 </participant>
 ```
 
 ## Next Steps
 
-After creating a configuration file you are ready to [run the Micro Manager](tooling-micro-manager-usage-running.html).
+After creating a configuration file you are ready to [run the Micro Manager](tooling-micro-manager-running.html).

docs/installation.md

@@ -1,48 +1,62 @@
 ---
-title: Installing the Micro Manager
+title: Get the Micro Manager
 permalink: tooling-micro-manager-installation.html
 keywords: tooling, macro-micro, two-scale
 summary: Install the Micro Manager by running `pip install --user micro-manager-precice`.
 ---
 
-## Installation
+## Get the latest Micro Manager release
 
-The Micro Manager is a Python package that can be installed using `pip`. Make sure [preCICE](installation-overview.html) is installed before installing the Micro Manager. The Micro Manager is compatible with preCICE version [2.5.0](https://github.com/precice/precice/releases/tag/v2.5.0).
+The Micro Manager can be installed using `pip`. Make sure [preCICE](installation-overview.html) is installed before installing the Micro Manager. The Micro Manager is compatible with preCICE version [2.3.0](https://github.com/precice/precice/releases/tag/v2.3.0) and higher.
 
-### Option 1: Using pip
+### Option 1: Install from PyPI
 
-It is recommended to install [micro-manager-precice from PyPI](https://pypi.org/project/micro-manager-precice/) by running
+The Micro Manager package has the name [micro-manager-precice](https://pypi.org/project/micro-manager-precice/) on PyPI. To install `micro-manager-precice`, run
 
 ```bash
 pip install --user micro-manager-precice
 ```
 
 Unless already installed, the dependencies will be installed by `pip` during the installation procedure. preCICE itself needs to be installed separately. If you encounter problems in the direct installation, see the [dependencies section](#required-dependencies) below.
 
-### Option 2: Clone this repository and install manually
+### Option 2: Install manually
 
 #### Required dependencies
 
 Ensure that the following dependencies are installed:
 
-* Python 3 or higher
-* [preCICE](installation-overview.html) [v2.5.0](https://github.com/precice/precice/releases/tag/v2.5.0)
+* Python 3
+* [preCICE](installation-overview.html) [v2.3.0](https://github.com/precice/precice/releases/tag/v2.3.0) or higher
 * [pyprecice: Python language bindings for preCICE](installation-bindings-python.html)
 * [numpy](https://numpy.org/install/)
 * [mpi4py](https://mpi4py.readthedocs.io/en/stable/install.html)
 
-#### Build and install the Manager using pip
+#### Clone this repository
 
-After cloning this repository, go to the directory `micro-manager/` and run
+```bash
+git clone https://github.com/precice/micro-manager.git
+```
+
+#### Build manually using pip
+
+Go to the directory `micro-manager/` and run
 
 ```bash
 pip install --user .
 ```
 
-#### Build and install the Manager using Python
+#### Build manually using Python
 
-After cloning this repository, go to the project directory `micro-manager/` and run
+Go to the project directory `micro-manager/` and run
 
 ```bash
 python setup.py install --user
 ```
+
+## Get the latest development version
+
+If you want to use the latest development version of the Micro Manager, clone the develop[https://github.com/precice/micro-manager/tree/develop] branch and then [build manually using pip](#build-manually-using-pip).
+
+## Next steps
+
+After successfully installing the Micro Manager, proceed to [preparing your micro simulation for the coupling](tooling-micro-manager-prepare-micro-simulation.html).