Release v202211 (precice#305)

Author: MakisH

.github/workflows/update-website.yml

@@ -0,0 +1,23 @@
+name: Update website
+on:
+  push:
+    branches:
+      - 'develop'
+    paths:
+      - '*/*.md'
+      - '*/images/*'
+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

CHANGELOG.md

@@ -6,7 +6,30 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 <!-- markdownlint-configure-file {"MD024": { "siblings_only": true } } -->
 
-## [Unreleased]
+## [v202211.0] 2022-11-21
+
+### Added
+
+- Added an [ASTE tutorial](https://precice.org/tutorials-aste-turbine.html) [#244](https://github.com/precice/tutorials/pull/244).
+- Added an [oscillator tutorial](https://precice.org/tutorials-oscillator.html) with Python [#297](https://github.com/precice/tutorials/pull/297).
+- Added a uni-directional volume-coupled [channel transport tutorial](https://precice.org/tutorials-channel-transport.html) [#269](https://github.com/precice/tutorials/pull/269).
+- Added a volume-coupled [channel transport with chemical reactions tutorial](https://precice.org/tutorials-channel-transport-reaction.html) [#278](https://github.com/precice/tutorials/pull/278).
+- Added a [partitioned heat conduction using direct mesh access tutorial](https://precice.org/tutorials-partitioned-heat-conduction-direct.html) [#299](https://github.com/precice/tutorials/pull/299).
+- Added a [simplified heat exchanger tutorial](https://precice.org/tutorials-heat-exchanger-simplified.html) [#301](https://github.com/precice/tutorials/pull/301).
+- Added a solid-openfoam and a solid-solids4foam case for the perpendicular-flap tutorial [#286](https://github.com/precice/tutorials/pull/286).
+- Added a dune-fem case for the flow-over-heated-plate tutorial [#274](https://github.com/precice/tutorials/pull/274).
+- Added a CalculiX case for the flow-over-heated-plate tutorial [#271](https://github.com/precice/tutorials/pull/271).
+- Added a modal dynamic simulation option for the CalculiX case of the perpendicular-flap tutorial [#284](https://github.com/precice/tutorials/pull/284).
+- Added a CI workflow to automatically update the website every time there are new documentation changes [#267](https://github.com/precice/tutorials/pull/267)
+- Added a gitignore for code and binaries [#290](https://github.com/precice/tutorials/pull/290).
+- Added more documentation [#264](https://github.com/precice/tutorials/pull/264), [#265](https://github.com/precice/tutorials/pull/265), [#266](https://github.com/precice/tutorials/pull/266) and fixed some typos [#285](https://github.com/precice/tutorials/pull/285).
+
+### Changed
+
+- Adapted the multiple-perpendicular-flaps tutorial to a [new naming convention](https://precice.org/community-contribute-to-precice.html#contributing-tutorials) for tutorials with multiple participants [#303](https://github.com/precice/tutorials/pull/303).
+- Adapted the material properties of the FEniCS case in elastic-tube-3d to match the CalculiX case results [#259](https://github.com/precice/tutorials/issues/259).
+- Adapted the solid case of the Quickstart tutorial to work with the Intel oneAPI C++ compiler [#291](https://github.com/precice/tutorials/pull/291).
+- Made the Nutils case of the partitioned heat conduction tutorial compatible with Nutils versions 6 to 8 [#295](https://github.com/precice/tutorials/pull/295), [#298](https://github.com/precice/tutorials/pull/298).
 
 ## [v202202.0] 2022-02-09
 
@@ -24,7 +47,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Ported the `visualize.py` script of the partitioned-elastic-beam to Python 3 [#247](https://github.com/precice/tutorials/pull/247).
 - Reduced the writing frequency of the partitioned-pipe OpenFOAM cases [#257](https://github.com/precice/tutorials/pull/257).
 - Renamed the output directories of all FEniCS cases for consistency [#256](https://github.com/precice/tutorials/pull/257).
-- Removed unnecessary (wrong) read statment in `elastic-tube-1d` [#232](https://github.com/precice/tutorials/pull/232).
+- Removed unnecessary (wrong) read statement in `elastic-tube-1d` [#232](https://github.com/precice/tutorials/pull/232).
 - Removed unnecessary (relic) OpenFOAM parameter `nMoles` from flow-over-heated-plate cases with OpenFOAM [#234](https://github.com/precice/tutorials/pull/234).
 - Removed unnecessary (relic) OpenFOAM parameter `RAS` from the `turbulenceProperties` files of all OpenFOAM cases (we model a laminar flow everywhere and this was confusing) [#258](https://github.com/precice/tutorials/pull/258).
 - Removed unnecessary (relic) OpenFOAM files `RASProperties` and `couplingProperties` from elastic-tube-3d [#258](https://github.com/precice/tutorials/pull/258).

aste-turbine/README.md

@@ -0,0 +1,63 @@
+---
+title: ASTE (artificial solver testing environment) wind turbine blade tutorial
+permalink: tutorials-aste-turbine.html
+keywords: ASTE, mapping, data mapping, mapping configuration, turbine
+summary: This tutorial is an example case for ASTE, where we investigate different preCICE mappings using ASTE.
+---
+
+{% include note.html content="Get the [case files of this tutorial](https://github.com/precice/tutorials/tree/master/aste-turbine). Read how in the [tutorials introduction](https://precice.org/tutorials.html)." %}
+
+If you are completely new to ASTE have a look at our [ASTE documentation](https://precice.org/tooling-aste.html). This tutorial shows how to setup a mapping between two (artificial) meshes using preCICE and ASTE in parallel. The executed mapping can be investigated in terms of accuracy as well as runtime.
+
+## Setup
+
+Our example consists of a wind turbine blade geometry, which was triangulated using different refinement levels. The mesh files are stored in [this GitLab repository](https://gitlab.lrz.de/precice/precice2-ref-paper-setup) and correspond to the mesh files used for the mapping tests of our [version 2 reference paper](https://doi.org/10.12688/openreseurope.14445.1). The mesh files are automatically downloaded when the `run.sh` script is executed. In this example setup, we map the mesh `0.01.vtk` (left side of the figure) to the mesh `0.006.vtk` (right side of the figure).
+
+![Turbine setup](images/tutorials-aste-setup.png)
+
+## Running the tutorial
+
+All necessary steps in order to run the mapping setup are summarized in the `run.sh` script. Have a look at the comments in the run script in order to understand what is happening. In particular, the script executes the following steps:
+
+1. Download the mesh files and extract them in the `meshes` directory. This step is only executed when running the script for the first time. For our example, we only use two of the downloaded meshes. The tutorial can easily be modified to employ different meshes.
+2. Generate input data for our mapping problem. As described in the [ASTE documentation](https://precice.org/tooling-aste.html#precice-aste-evaluate), the python script `precice-aste-evaluate` evaluates a test function and stores the results on a mesh. Here, we select Franke's function, evaluate it on the input mesh `0.01.vtk`, and store the results on a mesh called `input_mesh.vtu`. Use `precice-aste-evaluate --list-functions` to get a complete list of available test functions and their definitions.
+3. Partition meshes. We want to execute the mapping in parallel. To this end, we need to partition our mesh files so that each rank receives its own mesh file. The python script `precice-aste-partition` partitions a given mesh in a specified number of pieces (here two for the input mesh and two for the output mesh).
+4. Execute the actual mapping. We start two instances of `precice-aste-run`, which is the ASTE core module interfacing with preCICE, to emulate two participants. Here, we map the data from the coarse input mesh to the fine output mesh. We store the mesh and data per rank in files `mapped/mapped...` with data called `InterpolatedData`.
+5. Join scattered mesh files. The python script `precice-aste-join` joins the results into one large mesh file `result.vtu`.
+6. Investigate accuracy of mapping configuration. We use `precice-aste-evaluate` again. This time, we use the `--diff` flag in order to compute the error between our test function and the mapped data. We store the difference data (`Error`) on the result mesh (`result.vtu`) as well, which allows us to visualize the error distribution, e.g., using `ParaView`. `precice-aste-evaluate` also prints several global error measures to the console:
+
+```bash
+---[ASTE-Evaluate] INFO : Vertex count 9588
+---[ASTE-Evaluate] INFO : Relative l2 error 0.002402706834866804
+---[ASTE-Evaluate] INFO : Maximum absolute error per vertex 0.009659755828445804
+---[ASTE-Evaluate] INFO : Maximum signed error per vertex 0.00888725146042224
+---[ASTE-Evaluate] INFO : Minimum absolute error per vertex 0.0
+---[ASTE-Evaluate] INFO : Minimum signed error per vertex -0.009659755828445804
+---[ASTE-Evaluate] INFO : Median absolute error per vertex 0.0011544478395176805
+---[ASTE-Evaluate] INFO : 99th percentile of absolute error per vertex 0.007066025673252374
+---[ASTE-Evaluate] INFO : 95th percentile of absolute error per vertex 0.005206080046631978
+---[ASTE-Evaluate] INFO : 90th percentile of absolute error per vertex 0.004253350142177374
+```
+
+This information is additionally stored in a JSON file `result.stats.json` for potential further processing.
+
+{% note %}
+The error measures used here are only useful for consistent mapping configurations, i.e., `constraint="consistent"`.
+{% endnote %}
+
+This tutorial is meant as a starting point to investigate mapping setups. The provided configuration uses a `nearest-neighbor` mapping, but there are other mapping configurations available (commented out) in the `precice-config.xml` file. Example: using the last configuration (`rbf-compact-polynomial-c6` with a dense matrix decomposition) leads to the following error measures:
+
+```bash
+---[ASTE-Evaluate] INFO : Vertex count 3458
+---[ASTE-Evaluate] INFO : Relative l2 error 9.588343106540401e-08
+---[ASTE-Evaluate] INFO : Maximum absolute error per vertex 1.7229951972397295e-06
+---[ASTE-Evaluate] INFO : Maximum signed error per vertex 1.7229951972397295e-06
+---[ASTE-Evaluate] INFO : Minimum absolute error per vertex 3.5638159090467525e-14
+---[ASTE-Evaluate] INFO : Minimum signed error per vertex -1.6968422637542169e-06
+---[ASTE-Evaluate] INFO : Median absolute error per vertex 6.217611314696114e-09
+---[ASTE-Evaluate] INFO : 99th percentile of absolute error per vertex 3.548732313379818e-07
+---[ASTE-Evaluate] INFO : 95th percentile of absolute error per vertex 1.6012309731194814e-07
+---[ASTE-Evaluate] INFO : 90th percentile of absolute error per vertex 8.077894064206796e-08
+```
+
+which are clearly better than the ones we got with `nearest-neighbor` mapping above. However, this comes at the cost of a much higher runtime ().

aste-turbine/clean-tutorial.sh

@@ -0,0 +1 @@
+../tools/clean-tutorial-base.sh

aste-turbine/images/tutorials-aste-turbine-setup.png

@@ -0,0 +1,51 @@
+<?xml version="1.0"?>
+
+<precice-configuration>
+
+  <log>
+    <sink
+      filter="%Severity% > debug and %Rank% = 0"
+      format="---[precice] %ColorizedSeverity% %Message%"
+      enabled="true" />
+  </log>
+  
+  <solver-interface dimensions="3">
+    
+    <data:scalar name="Data" />
+
+    <mesh name="A-Mesh">
+      <use-data name="Data" />
+    </mesh>
+
+    <mesh name="B-Mesh">
+      <use-data name="Data" />
+    </mesh>
+    
+    <m2n:sockets from="A" to="B" exchange-directory="." />
+
+    <participant name="A">
+      <use-mesh name="A-Mesh" provide="yes" />
+      <write-data name="Data" mesh="A-Mesh" />
+    </participant>
+    
+    <participant name="B">
+      <use-mesh name="A-Mesh" provide="no" from="A" />
+      <use-mesh name="B-Mesh" provide="yes" />
+      <read-data name="Data" mesh="B-Mesh" />
+
+      <mapping:nearest-neighbor constraint="consistent" direction="read" from="A-Mesh" to="B-Mesh" />
+      <!-- <mapping:nearest-projection constraint="consistent" direction="read" from="A-Mesh" to="B-Mesh" /> -->
+      <!-- <mapping:rbf-compact-polynomial-c6 support-radius="0.1" use-qr-decomposition="false" constraint="consistent" direction="read" from="A-Mesh" to="B-Mesh" /> -->
+      <!-- <mapping:rbf-compact-polynomial-c6 support-radius="0.1" use-qr-decomposition="true" constraint="consistent" direction="read" from="A-Mesh" to="B-Mesh" /> -->
+    </participant>
+    
+    <coupling-scheme:parallel-explicit>
+      <participants first="A" second="B" />
+      <max-time value="1.0" />
+      <time-window-size value="1" />
+      <exchange data="Data" mesh="A-Mesh" from="A" to="B" />
+    </coupling-scheme:parallel-explicit>
+    
+  </solver-interface>
+  
+</precice-configuration>

aste-turbine/precice-config.xml

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -e -x
+
+# This script assumes the ASTE binaries and python scripts are in $PATH or ASTE installed on your system
+
+# Download the meshes
+test -f meshes.tar.gz  || wget https://gitlab.lrz.de/precice/precice2-ref-paper-setup/-/raw/main/meshes/meshes.tar.gz
+
+mkdir -p meshes
+
+# Extract the meshes
+test -f meshes/0.006.vtk -a meshes/0.01.vtk || tar -xvf meshes.tar.gz --directory meshes
+
+# Generate input data for the mapping problem using the predefined Franke's function function
+precice-aste-evaluate -m meshes/0.01.vtk -f "franke3d" -d "Franke" -o input_mesh.vtu
+
+# Decompose both meshes to two procesors
+# Choose resolution 0.01 mesh as coarse mesh and partition the mesh using a uniform algorithm
+precice-aste-partition -m input_mesh.vtu -n 2 -o coarse_mesh --dir coarse_mesh --algorithm uniform
+# Choose resolution 0.006 mesh as coarse mesh and partition the mesh using a meshfree algorithm
+precice-aste-partition -m meshes/0.006.vtk -n 2 -o fine_mesh --dir fine_mesh --algorithm meshfree
+
+# Create results directory of precice-aste-run
+mkdir -p mapped
+
+# Map from coarse mesh to fine mesh, start two ASTE instances, one for each participant
+mpirun -n 2 precice-aste-run -p A --mesh coarse_mesh/coarse_mesh --data "Franke" &
+mpirun -n 2 precice-aste-run -p B --mesh fine_mesh/fine_mesh --output mapped/mapped --data "InterpolatedData"
+
+# Join the output files together to result.vtu
+precice-aste-join -m mapped/mapped -o result.vtu --recovery fine_mesh/fine_mesh_recovery.json
+
+# Measure the difference between the original function and the mapped values
+# Save into data array called Error
+precice-aste-evaluate -m result.vtu -f "franke3d" -d "Error" --diffdata "InterpolatedData" --diff --stats

aste-turbine/run.sh

@@ -0,0 +1,53 @@
+---
+title: Channel transport reaction
+permalink: tutorials-channel-transport-reaction.html
+keywords: FEniCS, volumetric coupling, reaction, transport
+summary: We simulate an advection-diffusion-reaction scenario in a fluid in motion. One solver simulates the fluid flow and another handles the reactions.
+---
+
+{% note %}
+Get the [case files of this tutorial](https://github.com/precice/tutorials/tree/master/channel-transport-reaction). Read how in the [tutorials introduction](https://www.precice.org/tutorials.html).
+{% endnote %}
+
+## Setup
+
+We solve a system of advection-diffusion-reaction in a fluid flowing past a cylinder. This case is inspired from a FEniCS tutorial [1]. A fluid flows inside a channel containing a cylinder as an obstacle. Chemical species A, B and C live in the fluid, with sources of A and B at the entry of the channel. Due to diffusion and fluid mixing, A and B react to form a certain amount of C.
+
+The geometry is shown below:
+
+![Geometry](images/tutorials-channel-transport-reaction-geometry.png)
+
+The simulation is split into two participants: a Fluid participant that computes the fluid flow and sends the velocity field to the Chemical participant which computes the reaction, diffusion and advection of all chemical species. The coupling is unidirectional (`serial-explicit` with only one data entity being transferred).
+
+## Available solvers and dependencies
+
+Both participants run on FEniCS. Install [FEniCS](https://fenicsproject.org/download/) and the [FEniCS-adapter](https://github.com/precice/fenics-adapter) to run this tutorial.
+
+## Running the simulation
+
+Each participant has a `run.sh` file in its subfolder.
+To start the `Fluid` participant, run:
+
+   ```bash
+   cd fluid-fenics
+   ./run.sh
+   ```
+
+To start the `Chemical` participant, run:
+
+   ```bash
+   cd chemical-fenics
+   ./run.sh
+   ```
+
+## Postprocessing
+
+The chemical participant writes `.vtu` and `.pvd` files that can be opened with ParaView. The fluid participant also produces output files representing the velocity field. Since the fluid time step is significantly smaller than the chemical time step, there are more fluid velocity files than chemical concentration files. Keep this in mind when opening both simultaneously.
+The figure below shows the state after a duration of 2 units of time. The concentration in A, B and C are plotted.
+
+![Results](images/tutorials-channel-transport-reaction-state-t40.png)
+
+## References
+
+<!-- markdownlint-configure-file {"MD034": false } -->
+[1] Hans Petter Langtangen and Anders Logg. Solving PDEs in Python. _Springer_ (2017). https://doi.org/10.1007/978-3-319-52462-7

channel-transport-reaction/README.md

@@ -0,0 +1,8 @@
+{
+    "participant_name": "Chemical",
+    "config_file_name": "../precice-config.xml",
+    "interface": {
+        "coupling_mesh_name": "Chemical-Mesh",
+        "read_data_name": "Velocity"
+    }
+}