Add ASTE Documentation (#126)

* Add documentation CI

* Add documentation

* Add markdown lint options

* Reformat for linter

* Adapt Discussion: rename executable and python scripts #83

* Trailing edge fix

* remove extensions

* Change file names and add step by step guide

.github/workflows/link_check.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/lint_markdown.yml

@@ -0,0 +1,14 @@
+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: "."
+          ignore: changelog-entries

.github/workflows/update_website.yml

@@ -0,0 +1,22 @@
+name: Update website
+on:
+  push:
+    branches:
+      - "develop"
+    paths:
+      - "docs/**"
+jobs:
+  trigger:
+    runs-on: ubuntu-latest
+    env:
+      WORKFLOW_FILENAME: update-submodules.yml
+    steps:
+      - name: Trigger workflow
+        run: |
+          curl \
+          --request POST \
+          --url https://api.github.com/repos/precice/precice.github.io/actions/workflows/$WORKFLOW_FILENAME/dispatches \
+          --header "authorization: token ${{ secrets.WORKFLOW_DISPATCH_TOKEN }}" \
+          --header "Accept: application/vnd.github.v3+json" \
+          --data '{"ref":"master"}' \
+          --fail

.markdownlint.json

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

docs/README.md

@@ -1,3 +1,230 @@
-# aste
+---
+title: Artificial Solver Testing Environment (ASTE)
+permalink: tooling-aste.html
+keywords: tooling, aste
+summary: "A guide to usage of artifical solver testing environment (ASTE) tool"
+---
 
-:construction: Documentation under construction :construction:
+## Motivation
+
+ASTE is a tool that can be used to understand the dynamics of preCICE. It is a lightweight wrapper around preCICE which allows investigating different mapping setups in terms of both runtime and accuracy. It can replace individual participants for development purposes. It consists of C++ and Python modules.
+
+## Installation
+
+ASTE relies on following requirements
+
+### C++ modules
+
+#### Required dependencies for C++
+
+- C++ compiler (with support for C++14, e.g. GCC version >= 5)
+- preCICE (version >= 2.0)
+- MPI
+- CMake (version >= 3.1)
+- Boost (version >= 1.65.1)
+- vtk (Visualization ToolKit)
+
+For CMake, Boost, and MPI installation, please check [preCICE Installation Guide](https://precice.org/installation-overview.html).
+
+VTK library can be installed on Ubuntu via apt
+
+On Ubuntu 18.04 and later,
+
+```bash
+sudo apt-get install libvtk7-dev
+```
+
+However it highly recommended usage of higher version on Ubuntu 20.04 and later.
+
+```bash
+sudo apt-get install libvtk9-dev
+```
+
+##### Optional dependencies for C++
+
+- METIS
+
+METIS is a graph partitioning library used for topological partitioning in a mesh partitioner.
+
+METIS library can be installed on Ubuntu 18.04 and later via apt
+
+```bash
+sudo apt-get install libmetis-dev
+```
+
+### Python modules
+
+#### Required packages for Python
+
+- NumPy
+- vtk (Visualization Toolkit)
+- sympy (optional)
+
+Requirements can be installed easily using pip
+
+```bash
+pip3 install -r requirements.txt
+```
+
+### Building and Installation
+
+In order to install ASTE on your system you can follow these steps:
+
+```bash
+mkdir build
+cd build
+cmake ..
+make
+sudo make install
+```
+
+## Usage Cases
+
+There are some flags are common in every module here is a list of them.
+
+| Flag     | Explanation          |
+| -------- | -------------------- |
+| --mesh   | Mesh filename/prefix |
+| --data   | Name of data array   |
+| --output | Output filename      |
+
+For demo usage please check [ASTE Examples](https://github.com/precice/aste/tree/develop/tests/example).
+
+### precice-aste-run
+
+The main tool used for mapping. It is a wrapper around the preCICE interface. It can be run in serial or parallel. There are two modes available, namely, mapper mode and replay mode. The first mode is used to assess mapping data from one mesh to another; later, one is mainly developed for diagnostic and adapter development purposes. In Replay mode, ASTE replicates one participant of preCICE.
+
+| Flag          | Explanation                                                   |
+| ------------- | ------------------------------------------------------------- |
+| --aste-config | ASTE configuration file for replay mode                       |
+| -v            | Enables verbose output                                        |
+| -c            | To specify preCICE config file (default="precice-config.xml") |
+| -p            | Participant name (A or B)                                     |
+| --vector      | A bool switch to specify vector data (default=False)          |
+
+Important note: For the mapper mode, `--mesh` option can be different from the one defined in the configuration file. The filename prefix should be passed. When using in mapper mode, please use `precice-config.xml` in `tests/example/nn/precice-config.xml` and change only the required mapping method.
+
+For example, mapping the data "x + y" from a mesh named fine_mesh in directory fine_mesh to anotherMesh and save into "mappedData" and "mappedMesh":
+
+```bash
+preciceMap -v -p A --mesh fine_mesh/fine_mesh --data "x + y"
+mpirun -n 4 -v -p B --mesh anotherMesh --data "mappedData" --output mappedMesh
+```
+
+For the Replay mode ASTE uses a configuration file in JSON format as follows
+
+```json
+{
+  "participant": "Participant-Name",
+  "startdt": "PreCICE mesh dt number (>= 1)",
+  "meshes": [
+    {
+      "mesh": "Mesh name in preCICE config file",
+      "meshfileprefix": "/path/to/mesh/file/with/prefix/Mesh-Participant-A",
+      "read-data": {
+        "vector": ["Vector dataname in preCICE config which has a read type"],
+        "scalar": ["Scalar dataname in preCICE config which has a read type"]
+      },
+      "write-data": {
+        "vector": ["Vector dataname in preCICE config which has a write type"],
+        "scalar": ["Scalar dataname in preCICE config which has a write type"]
+      }
+    }
+  ],
+  "precice-config": "/path/to/precice/config/file/precice-config.xml"
+}
+```
+
+The above configuration file is an example of a participant with one mesh. The user can add as many meshes as required.
+
+#### Step by Step Guide for Replay Mode
+
+The replay mode only supports explicit coupling schemes.
+
+##### Step 1: Setup export of your original coupling
+
+Set vtk or vtu export of the participant you want to replace using preCICE export flag see [Export Configuration](https://precice.org/configuration-export.html)
+
+##### Step 2: Prepare your ASTE Configuration file
+
+Prepare an ASTE configuration for the solver which will be replaced. See above for ASTE configuration format.
+
+#### Step 3: Run your solver and ASTE
+
+Run your solver and ASTE as usual preCICE coupling. At this stage ASTE would work like a solver. Instead of calculation it would just only read from your export mesh data and use them for coupling.
+
+### precice-aste-evaluate
+
+Reads a mesh as either `.vtk` or `.vtu` and evaluates a function given by `--function` on it. Using the `--diff` flag can compute the difference between the mesh values and the values of the analytical solution (usually applied after a mapping).
+
+| Flag             | Explanation                                                                         |
+| ---------------- | ----------------------------------------------------------------------------------- |
+| --function       | The function which will be calculated on mesh                                       |
+| --list-functions | Prints a list of predefined functions                                               |
+| --diffdata       | The name for difference data. Used in diff mode. If not given, --data is used.      |
+| --log            | Logging level (default="INFO")                                                      |
+| --dir            | Output directory (optional)                                                         |
+| --diff           | Calculates the difference between --diffdata and given function.                    |
+| --stat           | Store stats of the difference calculation as the separate file inputmesh.stats.json |
+| --gradient       | Calculates gradient data for given input function                                   |
+
+There are also some predefined common interpolation functions can by specified here a list of them:
+
+| Function   | Explanation                                                                             |
+| ---------- | --------------------------------------------------------------------------------------- |
+| franke     | Franke's function has two Gaussian peaks of different heights, and a smaller dip.       |
+| eggholder  | A function has many local maxima. It is difficult to optimize.                          |
+| rosenbrock | A function that is unimodal, and the global minimum lies in a narrow, parabolic valley. |
+
+All function provided has 3D and 2D variants. For example, to calculate Egg-Holder function on different meshes:
+
+```bash
+precice-aste-evaluate --mesh 3DMesh.vtk --function "eggholder3d" --data "EggHolder"
+precice-aste-evaluate --mesh 2DMeshonXY.vtk --function "eggholder2d(xy)" --data "EggHolder"
+precice-aste-evaluate --mesh 2DMeshonXZ.vtk --function "eggholder2d(xz)" --data "EggHolder"
+precice-aste-evaluate --mesh 2DMeshonYZ.vtk --function "eggholder2d(yz)" --data "EggHolder"
+```
+
+For example, calculate function "sin(x)+exp(y)" on mesh MeshA and store in "MyFunc" or calculation of difference between mapped data and function "x+y" and "MappedData" and store it in "Error":
+
+```bash
+precice-aste-evaluate --mesh MeshA.vtk --function "sin(x)+exp(y)" --data "MyFunc"
+precice-aste-evaluate --mesh Mapped.vtk --function "x+y" --data "Error" --diffdata "MappedData" --diff
+```
+
+### precice-aste-partition
+
+Reads a mesh either `.vtk` or `.vtu` , partitions it and stores the parts `output_1.vtu, output_2.vtu, ...`. For partitioning, there are there algorithms available. The meshfree and uniform algorithm does not need any mesh topology information, whereas the topological algorithm needs topology information. This python module needs the C++ module `libmetisAPI.so` if the topological algorithm is used.
+
+| Flag        | Explanation                                                                                 |
+| ----------- | ------------------------------------------------------------------------------------------- |
+| --directory | Output directory (optional)                                                                 |
+| --numparts  | The number of parts to split into                                                           |
+| --algorithm | Algorithm used for determining the partitioning (options="meshfree", "topology", "uniform") |
+
+For example, to divide a mesh into 2 parts using topological partitioning and store it in a directory:
+
+```bash
+precice-aste-partition --mesh MeshA.vtk --algorithm topology --numparts 2 --output fine_mesh --directory partitioned_mesh
+```
+
+#### libMetisAPI
+
+This is a small C++ wrapper around METIS. It is only required if `precice-aste-partition` should use a topological algorithm.
+
+### precice-aste-join
+
+Reads a partitioned mesh from a given prefix (looking for `<prefix>_<#filerank>.vtu)`) and saves it to a single `.vtk` or `.vtu` file.
+The `-r` flag also recovers the connectivity information from a mesh. Notice that for recovery, partitions should contain `GlobalIDs` data.
+
+| Flag       | Explanation                                                                           |
+| ---------- | ------------------------------------------------------------------------------------- |
+| --recovery | The path to the recovery file to fully recover its state.                             |
+| --numparts | The number of parts to read from the input mesh. By default, the entire mesh is read. |
+| --log      | Logging level (default="INFO")                                                        |
+
+For example, to join a partitioned mesh using a recovery file:
+
+```bash
+precice-aste-join --mesh partitoned_mesh_directory/partitioned_mesh --recovery partitioned_directory --output rejoined_mesh.vtk
+```

tools/mesh-generators/README.md

@@ -3,7 +3,7 @@
 These scripts can generate mesh of a unit square/cube (with triangles or tetrahedral elements) with specified resolution.
 Run with output file name and target mesh size as arguments. For instance :
 
-```
+```bash
 python generate_unit_cube.py --mesh  coarse.vtk --resolution 0.2
 ```