Add tutorial of free flow over porous media

changelog-entries/678.md

@@ -0,0 +1 @@
+- Added new [free-flow-over-porous-media tutorial](https://precice.org/tutorials-free-flow-over-porous-media-2d.html) (migrated from the [example case in dumux-adapter](https://github.com/precice/dumux-adapter/tree/77e0fe5ca0dc6a1414d6cce5813ca914f0904259/examples/ff-pm)).

free-flow-over-porous-media/README.md

@@ -0,0 +1,71 @@
+---
+title: Free flow over porous media 2D
+permalink: tutorials-free-flow-over-porous-media-2d.html
+keywords: DuMux, porous media
+summary: Flow-flow coupling example with porous media field and free flow field.
+---
+
+{% note %}
+Get the [case files of this tutorial](https://github.com/precice/tutorials/tree/master/free-flow-over-porous-media-2d). Read how in the [tutorials introduction](https://precice.org/tutorials.html).
+{% endnote %}
+
+## Setup
+
+This tutorial solves a coupled system consisting of a one-phase free flow and a one-phase flow in a porous media.
+
+A pressure gradient is applied to the free flow domain from left to right. The top edge of the free-flow is a non-permeable wall with no-slip boundary conditions. In the porous media, there is a no-flow condition across the domain boundaries (left, bottom, and right boundaries). At the interface, a no-slip condition applies. The case is stationary (solved to a steady-state solution).
+
+The setting is illustrated in the following figure:
+
+![Free flow over porous media setup](images/tutorials-free-flow-over-porous-media-setup.png)
+
+## Configuration
+
+preCICE configuration (image generated using the [precice-config-visualizer](https://precice.org/tooling-config-visualization.html)):
+
+![preCICE configuration visualization](images/tutorials-free-flow-over-porous-media-precice-config-visualization.png)
+
+## Available solvers
+
+Both the participants are computed using the simulation code [DuMu<sup>x</sup>](https://git.iws.uni-stuttgart.de/dumux-repositories/dumux/).
+
+## Solver setup
+
+To solve the flows with the DuMux framework, the necessary DUNE modules need to be downloaded and set up. This is done by running `sh setup-dumux.sh` in the tutorial folder.
+
+Note that if an existing installation of DUNE modules is detected in a default location, this may lead to problems in running the `setup-dumux.sh` script. The script suppresses the environment variable `DUNE_CONTROL_PATH`.
+
+To only recompile the participants, run `sh compile-dumux-cases.sh` in the tutorial folder.
+
+## Running the simulation
+
+Each participant has a `run.sh` script.
+
+To run the free-flow participant, run:
+
+```bash
+cd free-flow-dumux
+./run.sh
+```
+
+To run the porous-media participant, run:
+
+```bash
+cd porous-media-dumux
+./run.sh
+```
+
+Participants can be executed only in serial. Parallel execution is not supported. The case takes approximately two minutes to finish.
+
+## Post-processing
+
+Both participants write VTU outputs, which can be viewed using ParaView.
+
+## Further information
+
+The results of the pressure and the velocity fields are as follows:
+
+![Free flow over porous media results - pressure](images/tutorials-free-flow-over-porous-media-result-pressure.png)
+![Free flow over porous media results - velocity](images/tutorials-free-flow-over-porous-media-result-ux.png)
+
+Each solver folder contains an input file (`params.input`) that will be passed to the solver executables. This is a DuMUX input file describing the simulation setting, e.g., pressure, mesh size, time stepping, etc.

free-flow-over-porous-media/clean-tutorial.sh

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

free-flow-over-porous-media/compile-dumux-cases.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env sh
+set -e -u
+
+(
+cd free-flow-dumux/build-cmake/solver-dumux
+make free_flow_dumux
+)
+
+(
+cd porous-media-dumux/build-cmake/solver-dumux
+make porous_media_dumux
+)
+
+# Move free-flow-dumux and porous-media-dumux executables to the participant folder level
+mv free-flow-dumux/build-cmake/solver-dumux/free_flow_dumux free-flow-dumux/
+mv porous-media-dumux/build-cmake/solver-dumux/porous_media_dumux porous-media-dumux/

free-flow-over-porous-media/free-flow-dumux/CMakeLists.txt

@@ -0,0 +1,26 @@
+cmake_minimum_required(VERSION 3.13)
+project(free-flow-dumux CXX)
+
+if(NOT (dune-common_DIR OR dune-common_ROOT OR
+      "${CMAKE_PREFIX_PATH}" MATCHES ".*dune-common.*"))
+    string(REPLACE  ${PROJECT_NAME} dune-common dune-common_DIR
+      ${PROJECT_BINARY_DIR})
+endif()
+
+#find dune-common and set the module path
+find_package(dune-common REQUIRED)
+list(APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake/modules"
+  ${dune-common_MODULE_PATH})
+
+#include the dune macros
+include(DuneMacros)
+
+# start a dune project with information from dune.module
+dune_project()
+
+dune_enable_all_packages()
+
+add_subdirectory(solver-dumux)
+
+# finalize the dune project, e.g. generating config.h etc.
+finalize_dune_project(GENERATE_CONFIG_H_CMAKE)

free-flow-over-porous-media/free-flow-dumux/clean.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env sh
+set -e -u
+
+. ../../tools/cleaning-tools.sh
+
+clean_dumux .

free-flow-over-porous-media/free-flow-dumux/config.h.cmake

@@ -0,0 +1,45 @@
+/* begin free-flow-dumux
+   put the definitions for config.h specific to
+   your project here. Everything above will be
+   overwritten
+*/
+
+/* begin private */
+/* Name of package */
+#define PACKAGE "@DUNE_MOD_NAME@"
+
+/* Define to the address where bug reports for this package should be sent. */
+#define PACKAGE_BUGREPORT "@DUNE_MAINTAINER@"
+
+/* Define to the full name of this package. */
+#define PACKAGE_NAME "@DUNE_MOD_NAME@"
+
+/* Define to the full name and version of this package. */
+#define PACKAGE_STRING "@DUNE_MOD_NAME@ @DUNE_MOD_VERSION@"
+
+/* Define to the one symbol short name of this package. */
+#define PACKAGE_TARNAME "@DUNE_MOD_NAME@"
+
+/* Define to the home page for this package. */
+#define PACKAGE_URL "@DUNE_MOD_URL@"
+
+/* Define to the version of this package. */
+#define PACKAGE_VERSION "@DUNE_MOD_VERSION@"
+
+/* end private */
+
+/* Define to the version of free-flow-dumux */
+#define FREE_FLOW_DUMUX_VERSION "@FREE_FLOW_DUMUX_VERSION@"
+
+/* Define to the major version of free-flow-dumux */
+#define FREE_FLOW_DUMUX_VERSION_MAJOR @FREE_FLOW_DUMUX_VERSION_MAJOR@
+
+/* Define to the minor version of free-flow-dumux */
+#define FREE_FLOW_DUMUX_VERSION_MINOR @FREE_FLOW_DUMUX_VERSION_MINOR@
+
+/* Define to the revision of free-flow-dumux */
+#define FREE_FLOW_DUMUX_VERSION_REVISION @FREE_FLOW_DUMUX_VERSION_REVISION@
+
+/* end free-flow-dumux
+   Everything below here will be overwritten
+*/

free-flow-over-porous-media/free-flow-dumux/dune.module

@@ -0,0 +1,12 @@
+################################
+# Dune module information file #
+################################
+
+# Name of the module
+Module: free-flow-dumux
+Version: 1.0
+Maintainer: jun.chen@ipvs.uni-stuttgart.de
+# Required build dependencies
+Depends: dumux-precice
+# Optional build dependencies
+#Suggests:

free-flow-over-porous-media/free-flow-dumux/free-flow-dumux.pc.in

@@ -0,0 +1,15 @@
+prefix=@prefix@
+exec_prefix=@exec_prefix@
+libdir=@libdir@
+includedir=@includedir@
+CXX=@CXX@
+CC=@CC@
+DEPENDENCIES=@REQUIRES@
+
+Name: @PACKAGE_NAME@
+Version: @VERSION@
+Description: free-flow module
+URL: http://dune-project.org/
+Requires: dumux-precice
+Libs: -L${libdir}
+Cflags: -I${includedir}

free-flow-over-porous-media/free-flow-dumux/params.input

@@ -0,0 +1,37 @@
+[FreeFlow]
+EnableUnsymmetrizedVelocityGradientForBeaversJoseph = false
+
+[FreeFlow.Grid]
+Verbosity = true
+LowerLeft = 0 1
+UpperRight = 1 2
+Cells = 40 40
+Grading1 = 1
+
+[Darcy.Grid]
+Verbosity = true
+LowerLeft = 0 0
+UpperRight = 1 1
+Cells = 40 40
+Grading1 = 1
+
+[FreeFlow.Problem]
+Name = free-flow-dumux
+EnableInertiaTerms = false
+PressureDifference = 1e-2
+
+[Darcy.SpatialParams]
+Permeability = 1e-6 # m^2
+Porosity = 0.4
+AlphaBeaversJoseph = 1.0
+
+[Problem]
+Name = fvca-iterative
+EnableGravity = false
+CouplingMode = ReconstructFreeFlowNormalStress
+
+[Vtk]
+AddVelocity = 1
+
+[Output]
+EnableCSVWriter = false

free-flow-over-porous-media/free-flow-dumux/run.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -e -u
+
+. ../../tools/log.sh
+exec > >(tee --append "$LOGFILE") 2>&1
+
+./free_flow_dumux params.input
+
+close_log

free-flow-over-porous-media/free-flow-dumux/solver-dumux/CMakeLists.txt

@@ -0,0 +1,5 @@
+add_executable(free_flow_dumux main.cc)
+target_compile_definitions(free_flow_dumux PUBLIC "ENABLEMONOLITHIC=0")
+target_link_libraries(free_flow_dumux PRIVATE dumux-precice)
+
+add_input_file_links()