From cb8b0efbd4534453fbba35e459c2d797ef268767 Mon Sep 17 00:00:00 2001
From: Martin Utz <martin.utz@baw.de>
Date: Wed, 1 Apr 2020 14:02:47 +0200
Subject: [PATCH] [examples][shallowwater] Improve example structure
(cherry picked from commit 8732166adba7bc898bcac9bf5cc0968716f53511)
---
examples/README.md | 2 +-
examples/shallowwaterfriction/.doc_config | 26 +-
examples/shallowwaterfriction/README.md | 1032 ++---------------
examples/shallowwaterfriction/doc/_intro.md | 139 +++
examples/shallowwaterfriction/doc/intro.md | 97 --
examples/shallowwaterfriction/doc/main.md | 301 +++++
.../shallowwaterfriction/doc/main_intro.md | 12 +
examples/shallowwaterfriction/doc/swe.md | 570 +++++++++
.../shallowwaterfriction/doc/swe_intro.md | 17 +
examples/shallowwaterfriction/img/domain.png | Bin 18385 -> 0 bytes
examples/shallowwaterfriction/img/result.png | Bin 35503 -> 0 bytes
.../shallowwaterfriction/img/swe_result.png | Bin 0 -> 117570 bytes
examples/shallowwaterfriction/main.cc | 186 +--
examples/shallowwaterfriction/problem.hh | 178 +--
examples/shallowwaterfriction/properties.hh | 51 +-
.../shallowwaterfriction/spatialparams.hh | 74 +-
16 files changed, 1444 insertions(+), 1241 deletions(-)
create mode 100644 examples/shallowwaterfriction/doc/_intro.md
delete mode 100644 examples/shallowwaterfriction/doc/intro.md
create mode 100644 examples/shallowwaterfriction/doc/main.md
create mode 100644 examples/shallowwaterfriction/doc/main_intro.md
create mode 100644 examples/shallowwaterfriction/doc/swe.md
create mode 100644 examples/shallowwaterfriction/doc/swe_intro.md
delete mode 100644 examples/shallowwaterfriction/img/domain.png
delete mode 100644 examples/shallowwaterfriction/img/result.png
create mode 100644 examples/shallowwaterfriction/img/swe_result.png
diff --git a/examples/README.md b/examples/README.md
index 9d3e0ba9a2..cff9e3ed7c 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -29,7 +29,7 @@ You learn how to
### [:open_file_folder: Example 3: Shallow water model](shallowwaterfriction/README.md)
-The shallow water flow model is applied to simulate steady subcritical flow in a river including a bottom friction model.
+The shallow water flow model is applied to simulate steady subcritical flow in a channel including a bottom friction model.
You learn how to
* solve a shallow water flow problem including bottom friction
diff --git a/examples/shallowwaterfriction/.doc_config b/examples/shallowwaterfriction/.doc_config
index 7ac7201b34..d5233fd849 100644
--- a/examples/shallowwaterfriction/.doc_config
+++ b/examples/shallowwaterfriction/.doc_config
@@ -1,9 +1,29 @@
{
"README.md" : [
- "doc/intro.md",
+ "doc/_intro.md"
+ ],
+
+ "doc/swe.md" : [
+ "doc/swe_intro.md",
"properties.hh",
- "spatialparams.hh",
"problem.hh",
+ "spatialparams.hh"
+ ],
+
+ "doc/main.md" : [
+ "doc/main_intro.md",
"main.cc"
- ]
+ ],
+
+ "navigation" : {
+ "mainpage" : "README.md",
+ "subpages" : [
+ "doc/swe.md",
+ "doc/main.md"
+ ],
+ "subtitles" : [
+ "Shallow water flow simulation setup",
+ "Main program flow"
+ ]
+ }
}
diff --git a/examples/shallowwaterfriction/README.md b/examples/shallowwaterfriction/README.md
index e71e3b5460..29cb808d13 100644
--- a/examples/shallowwaterfriction/README.md
+++ b/examples/shallowwaterfriction/README.md
@@ -1,25 +1,60 @@
<!-- Important: This file has been automatically generated by generate_example_docs.py. Do not edit this file directly! -->
# Shallow water flow with bottom friction
-This example shows how the shallow water flow model can be
-applied to simulate steady subcritical flow including
-bottom friction (bed shear stress).
+In this example, the shallow water flow model is applied to simulate
+a steady subcritical flow including bottom friction (bed shear stress).
__You will learn how to__
* solve a shallow water flow problem including bottom friction
* compute and output (VTK) an analytical reference solution
-__Result__. The numerical and analytical solutions for the problem will look like this:
+__Result__. The numerical and analytical solutions for the free surface will look like this:
-
+<figure>
+ <center>
+ <img src="img/swe_result.png" alt="Shallow water result" width="60%"/>
+ <figcaption> <b> Fig.1 </b> - Setup and result for the shallow water problem with bottom friction.</figcaption>
+ </center>
+</figure>
__Table of contents__. This description is structured as follows:
[[_TOC_]]
-## Mathematical model
-The 2D shallow water equations (SWEs) are given by
+## Problem set-up
+### Model domain
+The model domain is given by a rough channel with a slope of 0.001.
+The domain is 500 meters long and 5 meters wide.
+The bottom altitude is 10 m at the inflow and hence 9.5 m at the outflow.
+Bottom friction is considered by applying
+Manning's law ($`n`$ = 0.025).
+
+### Boundary conditions
+At the lateral sides a no-flow boundary condition is applied. Also no friction is
+considered there and therefore a no slip boundary
+condition is applied. These are the default boundary condition for the shallow
+water model. At the left border a discharge boundary condition
+is applied as inflow boundary condition with $`q = -1.0 m^2 s^{-1}`$.
+At the right border a fixed water depth boundary condition
+is applied for the outflow. Normal flow is assumed, therefore the water
+depth at the right border is calculated using the equation
+of Gauckler, Manning and Strickler.
+
+### Initial conditons
+The initial water depth is set to 1 m, which is slightly higher than the normal flow
+water depth (0.87 m). Therefore, we expect a decreasing
+water level during the simulation until the normal flow condition is reached in
+the entire model domain. The inital velocity is set to zero.
+
+## Model description
+As mentioned above, this examples uses the shallow water equations (SWEs) to solve the problem.
+These are a depth averaged simplification of the Navier-Stokes equations. To calculate the
+bottom friction Manning's law is used. An alternative is Nikuradse's law, which is also implemented
+in DuMu<sup>x</sup>.
+
+### Shallow water model
+The shallow water equations are given as:
```math
\frac{\partial \mathbf{U}}{\partial t} +
@@ -35,54 +70,61 @@ where $`\mathbf{U}`$, $`\mathbf{F}`$ and $`\mathbf{G}`$ defined as
\mathbf{G} = \begin{bmatrix} hv \\ huv \\ hv^2 + \frac{1}{2} gh^2 \end{bmatrix}
```
-$`Z`$ is the bedSurface, $`h`$ the water depth, $`u`$ the velocity in
-x-direction and $`v`$ the velocity in y-direction, $`g`$ is the constant of gravity.
+$`h`$ the water depth, $`u`$ the velocity in x-direction and $`v`$ the velocity in y-direction,
+$`g`$ is the constant of gravity.
-The source terms for the bed friction $`\mathbf{S_b}`$ and bed slope
+The source terms for the bed slope $`\mathbf{S_b}`$ and friction
$`\mathbf{S_f}`$ are given as
```math
\mathbf{S_b} = \begin{bmatrix} 0 \\ -gh \frac{\partial z}{\partial x}
\\ -gh \frac{\partial z}{\partial y}\end{bmatrix},
-\mathbf{S_f} = \begin{bmatrix} 0 \\ -ghS_{fx} \\ -ghS_{fy}\end{bmatrix}.
+\mathbf{S_f} = \begin{bmatrix} 0 \\ghS_{fx} \\ghS_{fy}\end{bmatrix}.
```
-For this example, a cell-centered finite volume method (`cctpfa`) is applied to solve the SWEs
-in combination with a fully-implicit time discretization. For cases where no sharp fronts or
-traveling waves occur it is possible to apply time steps larger than CFL number = 1 to reduce
-the computation time. Even if a steady state solution is considered, an implicit time stepping method
-is applied.
+with the bedSurface $`z`$. $`S_{fx}`$ and $`S_{fy}`$ are the bed shear stess
+components in x- and y-direction, which are calculated by Manning's law.
-## Problem set-up
+### Mannings law
+The empirical Manning model specifies the bed shear stress by the following equations:
-The model domain is given by a rough channel with a slope of 0.001.
-The domain is 500 meters long and 10 meters wide.
-.
+```math
+S_{fx} = \frac{n^2u}{R_{hy}^{4/3}} \sqrt(u^2 + v^2),
-Bottom friction is considered by applying
-the friction law of Manning (Manning n = 0.025). At the lateral sides no friction is considered and a
-no-flow no slip boundary condition is applied. This is the default boundary condition for the shallow water model.
+S_{fy} = \frac{n^2v}{R_{hy}^{4/3}} \sqrt(u^2 + v^2)
+```
+
+$`n`$ is Manning's friction value and $`R_{hy}`$ is the hydraulic radius,
+which is assumed to be equal to the water depth $`h`$.
-At the left border a discharge boundary condition
-is applied as inflow boundary condition with q = -1.0 ($`m^2 s^{-1}`$). At the right border a water fixed depth boundary condition
-is applied for the outflow. Normal flow is assumed, therefore the water depth at the right border is calculated after
-the of Gaukler-Manning-Strickler equation:
+### Analytical solution
+Since normal flow conditions are assumed, the analytic solution is calculated using the equation
+of Gauckler, Manning and Strickler:
```math
v_m = n^{-1} R_{hy}^{2/3} I_s^{1/2}
```
-Where the mean velocity $`v_m`$ is given as $`v_m = \frac{q}{h}`$,
-$`n`$ is the friction value after Manning. $`R_{hy}`$ the hydraulic radius, which is assumed to be equal to
-the water depth. $`I_s`$ is the bed slope and $`q`$ the unity inflow discharge
+Where the mean velocity $`v_m`$ is given as
+
+```math
+v_m = \frac{q}{h}
+```
+
+$`I_s`$ is the bed slope and $`q`$ the unity inflow discharge.
+
+Hence, the water depth $`h`$ can be calculated by
-The water depth h can be calculated as
```math
h = \left(\frac{n q}{\sqrt{I_s}} \right)^{3/5}
```
-The formula of Gaukler Manning and Strickler is also used to calculate the analytic solution. All parameters
-for the simulation are given in the file `params.input`.
+### Discretisation
+For this example, a cell-centered finite volume method (cctpfa) is applied to solve the SWEs
+in combination with a fully-implicit time discretization. For cases where no sharp fronts or
+traveling waves occur it is possible to apply time steps larger than CFL number = 1 to reduce
+the computation time. Even if a steady state solution is considered, an implicit time stepping method
+is applied.
# Implementation
@@ -98,925 +140,13 @@ for the simulation are given in the file `params.input`.
└── spatialparams.hh -> spatial parameter fields
```
+## Part 1: Shallow water flow simulation setup
-## The file `properties.hh`
-
-The header includes will be mentioned in the text below.
-<details><summary>Click to show the header includes</summary>
-
-```cpp
-#include <dune/grid/yaspgrid.hh>
-
-#include <dumux/common/properties.hh>
-#include <dumux/discretization/cctpfa.hh>
-#include <dumux/freeflow/shallowwater/model.hh>
-
-#include "spatialparams.hh"
-#include "problem.hh"
-```
-
-</details>
-
-Let's define the properties for our simulation
-
-```cpp
-namespace Dumux::Properties {
-```
-
-First, a so-called TypeTag is created. Properties are traits specialized for this TypeTag (a simple `struct`).
-The properties of two other TypeTags are inherited by adding the alias `InheritsFrom`.
-Here, properties from the shallow water model (`TTag::ShallowWater`) and the
-cell-centered finite volume scheme with two-point-flux approximation (`TTag::CCTpfaModel`)
-are inherited. These other TypeTag definitions can be found in the included
-headers `dumux/freeflow/shallowwater/model.hh` and `dumux/discretization/cctpfa.hh`.
-
-```cpp
-namespace TTag {
-struct RoughChannel { using InheritsFrom = std::tuple<ShallowWater, CCTpfaModel>; };
-}
-```
-
-We use a structured Cartesian grid with tensor product structure.
-`Dune::YaspGrid` (Yet Another Structure Parallel Grid) is defined in `dune/grid/yaspgrid.hh`
-in the Dune module `dune-grid`.
-
-```cpp
-template<class TypeTag>
-struct Grid<TypeTag, TTag::RoughChannel>
-{ using type = Dune::YaspGrid<2, Dune::TensorProductCoordinates<GetPropType<TypeTag, Properties::Scalar>, 2> >; };
-```
-
-Next, we specialize the properties `Problem` and `SpatialParams` for our new TypeTag and
-set the type to our problem and spatial parameter classes implemented
-in `problem.hh` and `spatialparams.hh`.
-
-```cpp
-template<class TypeTag>
-struct Problem<TypeTag, TTag::RoughChannel>
-{ using type = Dumux::RoughChannelProblem<TypeTag>; };
-
-template<class TypeTag>
-struct SpatialParams<TypeTag, TTag::RoughChannel>
-{
- using GridGeometry = GetPropType<TypeTag, Properties::GridGeometry>;
- using Scalar = GetPropType<TypeTag, Properties::Scalar>;
- using ElementVolumeVariables = typename GetPropType<TypeTag, Properties::GridVolumeVariables>::LocalView;
- using VolumeVariables = typename ElementVolumeVariables::VolumeVariables;
-
- using type = RoughChannelSpatialParams<GridGeometry, Scalar, VolumeVariables>;
-};
-```
-
-Finally, we enable caching for the grid geometry. The cache
-stores values that were already calculated for later usage.
-This makes the simulation run faster but it uses more memory.
-
-```cpp
-template<class TypeTag>
-struct EnableGridGeometryCache<TypeTag, TTag::RoughChannel>
-{ static constexpr bool value = true; };
-
-} // end namespace Dumux::Properties
-```
-
-
-
-
-## The file `spatialparams.hh`
-
-
-We include the basic spatial parameters for finite volumes file from which we will inherit
-
-```cpp
-#include <dumux/material/spatialparams/fv.hh>
-```
-
-The parameters header is needed to retrieve run-time parameters.
-
-```cpp
-#include <dumux/common/parameters.hh>
-```
-
-We include all friction laws, between we can choose for the calculation of the bottom friction source.
-
-```cpp
-#include <dumux/material/fluidmatrixinteractions/frictionlaws/frictionlaw.hh>
-#include <dumux/material/fluidmatrixinteractions/frictionlaws/manning.hh>
-#include <dumux/material/fluidmatrixinteractions/frictionlaws/nikuradse.hh>
-```
-
-We enter the namespace Dumux. All Dumux functions and classes are in a namespace Dumux, to make sure they don`t clash with symbols from other libraries you may want to use in conjunction with Dumux.
-
-```cpp
-namespace Dumux {
-```
-
-In the RoughChannelSpatialParams class we define all functions needed to describe the spatial distributed parameters.
-
-```cpp
-template<class GridGeometry, class Scalar, class VolumeVariables>
-class RoughChannelSpatialParams
-: public FVSpatialParams<GridGeometry, Scalar,
- RoughChannelSpatialParams<GridGeometry, Scalar, VolumeVariables>>
-{
-```
-
-We introduce using declarations that are derived from the property system which we need in this class
-
-```cpp
- using ThisType = RoughChannelSpatialParams<GridGeometry, Scalar, VolumeVariables>;
- using ParentType = FVSpatialParams<GridGeometry, Scalar, ThisType>;
- using GridView = typename GridGeometry::GridView;
- using FVElementGeometry = typename GridGeometry::LocalView;
- using SubControlVolume = typename FVElementGeometry::SubControlVolume;
- using Element = typename GridView::template Codim<0>::Entity;
- using GlobalPosition = typename Element::Geometry::GlobalCoordinate;
-
-public:
-```
-
-In the constructor be read some values from the `params.input` and initialize the friciton law.
-
-```cpp
- RoughChannelSpatialParams(std::shared_ptr<const GridGeometry> gridGeometry)
- : ParentType(gridGeometry)
- {
- gravity_ = getParam<Scalar>("Problem.Gravity");
- bedSlope_ = getParam<Scalar>("Problem.BedSlope");
- frictionLawType_ = getParam<std::string>("Problem.FrictionLaw");
- initFrictionLaw();
- }
-```
-
-We initialize the friction law based on the law specified in `params.input`.
-
-```cpp
- void initFrictionLaw()
- {
- if (frictionLawType_ == "Manning")
- {
- Scalar manningN = getParam<Scalar>("Problem.ManningN");
- frictionLaw_ = std::make_unique<FrictionLawManning<VolumeVariables>>(gravity_, manningN);
- }
- else if (frictionLawType_ == "Nikuradse")
- {
- Scalar ks = getParam<Scalar>("Problem.Ks");
- frictionLaw_ = std::make_unique<FrictionLawNikuradse<VolumeVariables>>(ks);
- }
- else
- {
- std::cout<<"The FrictionLaw in params.input is unknown. Valid entries are `Manning` and `Nikuradse`!"<<std::endl;
- }
- }
-```
-
-Use this function, if you want to vary the value for the gravity.
-
-```cpp
- Scalar gravity(const GlobalPosition& globalPos) const
- {
- return gravity_;
- }
-```
-
-Use this function for a constant gravity.
-
-```cpp
- Scalar gravity() const
- {
- return gravity_;
- }
-```
-
-This function returns an object of the friction law class, which is initialized with the appropriate friction values. If you want to use different friciton values or laws, you have to use a vector of unique_ptr for `frictionLaw_` and pick the right friction law instances via the `element` argument.
-
-```cpp
- const FrictionLaw<VolumeVariables>& frictionLaw(const Element& element,
- const SubControlVolume& scv) const
- {
- return *frictionLaw_;
- }
-```
-
-Define the bed surface based on the `bedSlope_`.
-
-```cpp
- Scalar bedSurface(const Element& element,
- const SubControlVolume& scv) const
- {
- return 10.0 - element.geometry().center()[0] * bedSlope_;
- }
-
-private:
- Scalar gravity_;
- Scalar bedSlope_;
- std::string frictionLawType_;
- std::unique_ptr<FrictionLaw<VolumeVariables>> frictionLaw_;
-};
-```
-
-end of namespace Dumux.
-
-```cpp
-}
-```
-
-
-
-
-## The file `problem.hh`
-We start with includes
-
-```cpp
-#include <dumux/common/parameters.hh>
-#include <dumux/common/properties.hh>
-#include <dumux/freeflow/shallowwater/problem.hh>
-#include <dumux/freeflow/shallowwater/boundaryfluxes.hh>
-```
-
-We enter the problem class where all necessary boundary conditions and initial conditions are set for our simulation.
-As this is a shallow water problem, we inherit from the basic ShallowWaterProblem.
-
-```cpp
-namespace Dumux {
-
-template <class TypeTag>
-class RoughChannelProblem : public ShallowWaterProblem<TypeTag>
-{
-```
-
-We use convenient declarations that we derive from the property system.
-
-```cpp
- using ParentType = ShallowWaterProblem<TypeTag>;
- using PrimaryVariables = GetPropType<TypeTag, Properties::PrimaryVariables>;
- using BoundaryTypes = GetPropType<TypeTag, Properties::BoundaryTypes>;
- using Scalar = GetPropType<TypeTag, Properties::Scalar>;
- using Indices = typename GetPropType<TypeTag, Properties::ModelTraits>::Indices;
- using GridGeometry = GetPropType<TypeTag, Properties::GridGeometry>;
- using NeumannFluxes = GetPropType<TypeTag, Properties::NumEqVector>;
- using ElementVolumeVariables = typename GetPropType<TypeTag, Properties::GridVolumeVariables>::LocalView;
- using GridVariables = GetPropType<TypeTag, Properties::GridVariables>;
- using ElementFluxVariablesCache = typename GridVariables::GridFluxVariablesCache::LocalView;
- using VolumeVariables = typename ElementVolumeVariables::VolumeVariables;
- using FVElementGeometry = typename GetPropType<TypeTag, Properties::GridGeometry>::LocalView;
- using SubControlVolumeFace = typename FVElementGeometry::SubControlVolumeFace;
- using GridView = typename GetPropType<TypeTag, Properties::GridGeometry>::GridView;
- using Element = typename GridView::template Codim<0>::Entity;
- using GlobalPosition = typename Element::Geometry::GlobalCoordinate;
- using NumEqVector = GetPropType<TypeTag, Properties::NumEqVector>;
- using SubControlVolume = typename FVElementGeometry::SubControlVolume;
-
-public:
-```
-
-This is the constructor of our problem class.
-
-```cpp
- RoughChannelProblem(std::shared_ptr<const GridGeometry> gridGeometry)
- : ParentType(gridGeometry)
- {
-```
-
-We read the parameters from the params.input file.
-
-```cpp
- name_ = getParam<std::string>("Problem.Name");
- constManningN_ = getParam<Scalar>("Problem.ManningN");
- bedSlope_ = getParam<Scalar>("Problem.BedSlope");
- discharge_ = getParam<Scalar>("Problem.Discharge");
-```
-
-We calculate the outflow boundary condition using the Gauckler-Manning-Strickler formula.
-
-```cpp
- hBoundary_ = this->gauklerManningStrickler(discharge_,constManningN_,bedSlope_);
-```
-
-We initialize the analytic solution to a verctor of the appropriate size filled with zeros.
-
-```cpp
- exactWaterDepth_.resize(gridGeometry->numDofs(), 0.0);
- exactVelocityX_.resize(gridGeometry->numDofs(), 0.0);
- }
-```
-
-Get the analytical water depth
-
-```cpp
- const std::vector<Scalar>& getExactWaterDepth()
- {
- return exactWaterDepth_;
- }
-```
-
-Get the analytical velocity
-
-```cpp
- const std::vector<Scalar>& getExactVelocityX()
- {
- return exactVelocityX_;
- }
-```
-
-Get the water depth with Gauckler-Manning-Strickler
-
-```cpp
- Scalar gauklerManningStrickler(Scalar discharge, Scalar manningN, Scalar bedSlope)
- {
- using std::pow;
- using std::abs;
- using std::sqrt;
-
- return pow(abs(discharge)*manningN/sqrt(bedSlope), 0.6);
- }
-```
-
-Get the analytical solution
-
-```cpp
- void analyticalSolution()
- {
- using std::abs;
-
- for (const auto& element : elements(this->gridGeometry().gridView()))
- {
- const Scalar h = this->gauklerManningStrickler(discharge_,constManningN_,bedSlope_);
- const Scalar u = abs(discharge_)/h;
-
- const auto eIdx = this->gridGeometry().elementMapper().index(element);
- exactWaterDepth_[eIdx] = h;
- exactVelocityX_[eIdx] = u;
- }
- }
-```
-
-Get the problem name. It is used as a prefix for files generated by the simulation.
-
-```cpp
- const std::string& name() const
- {
- return name_;
- }
-```
-
-Get the source term.
-
-```cpp
- NumEqVector source(const Element& element,
- const FVElementGeometry& fvGeometry,
- const ElementVolumeVariables& elemVolVars,
- const SubControlVolume &scv) const
- {
-
- NumEqVector source (0.0);
-```
-
-In this model the bottom friction is the only source.
-
-```cpp
- source += bottomFrictionSource(element, fvGeometry, elemVolVars, scv);
-
- return source;
- }
-```
-
-Get the source term due to bottom friction.
-
-```cpp
- NumEqVector bottomFrictionSource(const Element& element,
- const FVElementGeometry& fvGeometry,
- const ElementVolumeVariables& elemVolVars,
- const SubControlVolume &scv) const
- {
- NumEqVector bottomFrictionSource(0.0);
- const auto& volVars = elemVolVars[scv];
-```
-
-For the calculation of the source term due to bottom friction the two-dimensional bottom shear stess vector is needed. This is the force per area, which works between the flow and the bed. It is calculated within the `FrictionLaw`, which is a spatialParameter. In this model the `FrictionLawManning` is used (see `params.input`).
-
-```cpp
- Dune::FieldVector<Scalar, 2> bottomShearStress = this->spatialParams().frictionLaw(element, scv).shearStress(volVars);
-```
-
-The bottom shear stress causes a pure loss of momentum. Thus the first entry of the `bottomFrictionSource`, which is related to the mass balance equation is zero. The second entry of the `bottomFricitonSource` corresponds to the momentum equation in x-direction and is therefore equal to the first, the x-component, of the `bottomShearStress`. Accordingly the third entry of the `bottomFrictionSource` is equal to the second component of the `bottomShearStress`.
-
-```cpp
- bottomFrictionSource[0] = 0.0;
- bottomFrictionSource[1] = bottomShearStress[0];
- bottomFrictionSource[2] = bottomShearStress[1];
-
- return bottomFrictionSource;
- }
-```
-
-We specify the boundary condition type.
-
-```cpp
- BoundaryTypes boundaryTypesAtPos(const GlobalPosition &globalPos) const
- {
- BoundaryTypes bcTypes;
-```
-
-Since we use a weak imposition all boundary conditions are of Neumann type.
-
-```cpp
- bcTypes.setAllNeumann();
- return bcTypes;
- }
-```
-
-We specify the neumann boundary. Due to the weak imposition we calculate the flux at the
-boundary, with a Rieman solver. For this the state of a virtual cell outside of the boundary
-is needed (`boundaryStateVariables`), wich is calculated with the Riemann invariants
-(see Yoon and Kang, Finite Volume Model for Two-Dimensional Shallow Water Flows on Unstructured Grids).
-The calculation of the Riemann invariants differ depending on the type of the boundary (h, q or no-flow boundary).
-
-```cpp
- NeumannFluxes neumann(const Element& element,
- const FVElementGeometry& fvGeometry,
- const ElementVolumeVariables& elemVolVars,
- const ElementFluxVariablesCache& elemFluxVarsCache,
- const SubControlVolumeFace& scvf) const
- {
- NeumannFluxes values(0.0);
-
- const auto& insideScv = fvGeometry.scv(scvf.insideScvIdx());
- const auto& insideVolVars = elemVolVars[insideScv];
- const auto& nxy = scvf.unitOuterNormal();
- const auto gravity = this->spatialParams().gravity(scvf.center());
- std::array<Scalar, 3> boundaryStateVariables;
-```
-
-Calculate the rieman invariants for imposed discharge at the left side.
-
-```cpp
- if (scvf.center()[0] < 0.0 + eps_)
- {
- boundaryStateVariables = ShallowWater::fixedDischargeBoundary(discharge_,
- insideVolVars.waterDepth(),
- insideVolVars.velocity(0),
- insideVolVars.velocity(1),
- gravity,
- nxy);
- }
-```
-
-Calculate the rieman invariants for impose water depth at the right side.
-
-```cpp
- else if (scvf.center()[0] > 100.0 - eps_)
- {
- boundaryStateVariables = ShallowWater::fixedWaterDepthBoundary(hBoundary_,
- insideVolVars.waterDepth(),
- insideVolVars.velocity(0),
- insideVolVars.velocity(1),
- gravity,
- nxy);
- }
-```
-
-Calculate the rieman invarianty for the no-flow boundary.
-
-```cpp
- else
- {
- boundaryStateVariables[0] = insideVolVars.waterDepth();
- boundaryStateVariables[1] = -insideVolVars.velocity(0);
- boundaryStateVariables[2] = -insideVolVars.velocity(1);
- }
-```
-
-We calculate the boundary fluxes based on a Riemann problem.
-
-```cpp
- auto riemannFlux = ShallowWater::riemannProblem(insideVolVars.waterDepth(),
- boundaryStateVariables[0],
- insideVolVars.velocity(0),
- boundaryStateVariables[1],
- insideVolVars.velocity(1),
- boundaryStateVariables[2],
- insideVolVars.bedSurface(),
- insideVolVars.bedSurface(),
- gravity,
- nxy);
-
- values[Indices::massBalanceIdx] = riemannFlux[0];
- values[Indices::velocityXIdx] = riemannFlux[1];
- values[Indices::velocityYIdx] = riemannFlux[2];
-
- return values;
- }
-```
-
-We set the initial conditions. In this example constant initial conditions are used. Therefore the argument `globalPos` is not needed. If you want to impose spatial variable initial conditions, you have to use the `globalPos`.
-
-```cpp
- PrimaryVariables initialAtPos(const GlobalPosition &globalPos) const
- {
- PrimaryVariables values(0.0);
-```
-
-We set the initial water depth to one meter.
+| [:arrow_right: Click to continue with part 1 of the documentation](doc/swe.md) |
+|---:|
-```cpp
- values[0] = 1.0;
-```
-
-We set the x-component of the initial velocity to zero.
-
-```cpp
- values[1] = 0.0;
-```
-
-We set the y-component of the initial velocity to zero.
-
-```cpp
- values[2] = 0.0;
-
- return values;
- };
-```
-
-\}
-
-```cpp
-
-private:
-```
-
-We declare the private variables of the problem. They are initialized in the problems constructor.
-We declare the variable for the analytic solution.
-
-```cpp
- std::vector<Scalar> exactWaterDepth_;
- std::vector<Scalar> exactVelocityX_;
-```
-
-constant friction value. An analytic solution is only available for const friction. If you want to run the simulation with a non constant friciton value (specified in the spatialParams) you have to remove the analytic solution.
-
-```cpp
- Scalar constManningN_;
-```
-
-The constant bed slope.
-
-```cpp
- Scalar bedSlope_;
-```
-
-The water depth at the outflow boundary.
-
-```cpp
- Scalar hBoundary_;
-```
-
-The discharge at the inflow boundary.
-
-```cpp
- Scalar discharge_;
-```
-
-eps is used as a small value for the definition of the boundry conditions
-
-```cpp
- static constexpr Scalar eps_ = 1.0e-6;
- std::string name_;
-};
-
-} // end namespace Dumux
-```
-
-
-
-
-## The file `main.cc`
-
-
-This is the main file for the shallow water example. Here we can see the programme sequence and how the system is solved using newton's method.
-### Includes
-
-```cpp
-#include <config.h>
-```
-
-Standard header file for C++, to get time and date information.
-
-```cpp
-#include <ctime>
-```
-
-Standard header file for C++, for in- and output.
-
-```cpp
-#include <iostream>
-```
-
-Dumux is based on DUNE, the Distributed and Unified Numerics Environment, which provides several grid managers and linear solvers. So we need some includes from that.
-
-```cpp
-#include <dune/common/parallel/mpihelper.hh>
-#include <dune/common/timer.hh>
-#include <dune/grid/io/file/dgfparser/dgfexception.hh>
-#include <dune/grid/io/file/vtk.hh>
-```
-
-We need the following class to simplify the writing of dumux simulation data to VTK format.
-
-```cpp
-#include <dumux/io/vtkoutputmodule.hh>
-```
-
-In Dumux a property system is used to specify the model. For this, different properties are defined containing type definitions, values and methods. All properties are declared in the file properties.hh.
-
-```cpp
-#include <dumux/common/properties.hh>
-```
-
-The following file contains the parameter class, which manages the definition of input parameters by a default value, the inputfile or the command line.
-
-```cpp
-#include <dumux/common/parameters.hh>
-```
-
-The file dumuxmessage.hh contains the class defining the start and end message of the simulation.
-
-```cpp
-#include <dumux/common/dumuxmessage.hh>
-#include <dumux/common/defaultusagemessage.hh>
-```
-
-The gridmanager constructs a grid from the information in the input or grid file. There is a specification for the different supported grid managers.
-
-```cpp
-#include <dumux/io/grid/gridmanager.hh>
-```
-
-We include the linear solver to be used to solve the linear system
-
-```cpp
-#include <dumux/linear/amgbackend.hh>
-#include <dumux/linear/linearsolvertraits.hh>
-```
-
-We include the nonlinear newtons method
-
-```cpp
-#include <dumux/nonlinear/newtonsolver.hh>
-```
-
-Further we include assembler, which assembles the linear systems for finite volume schemes (box-scheme, tpfa-approximation, mpfa-approximation)
-
-```cpp
-#include <dumux/assembly/fvassembler.hh>
-```
-
-We include the properties
-
-```cpp
-#include "properties.hh"
-```
-
-### Beginning of the main function
-
-```cpp
-int main(int argc, char** argv) try
-{
- using namespace Dumux;
-```
-
-We define the type tag for this problem
-
-```cpp
- using TypeTag = Properties::TTag::RoughChannel;
-```
-
-We initialize MPI, finalize is done automatically on exit
-
-```cpp
- const auto& mpiHelper = Dune::MPIHelper::instance(argc, argv);
-```
-
-We print dumux start message
-
-```cpp
- if (mpiHelper.rank() == 0)
- DumuxMessage::print(/*firstCall=*/true);
-```
-
-We parse command line arguments and input file
-
-```cpp
- Parameters::init(argc, argv);
-```
-
-### Create the grid
-A gridmanager tries to create the grid either from a grid file or the input file.
-
-```cpp
- GridManager<GetPropType<TypeTag, Properties::Grid>> gridManager;
- gridManager.init();
-```
-
-We compute on the leaf grid view
-
-```cpp
- const auto& leafGridView = gridManager.grid().leafGridView();
-```
-
-### Setup and solving of the problem
-#### Setup
-We create and initialize the finite volume grid geometry, the problem, the linear system, including the jacobian matrix, the residual and the solution vector and the gridvariables.
-We need the finite volume geometry to build up the subcontrolvolumes (scv) and subcontrolvolume faces (scvf) for each element of the grid partition.
-
-```cpp
- using GridGeometry = GetPropType<TypeTag, Properties::GridGeometry>;
- auto gridGeometry = std::make_shared<GridGeometry>(leafGridView);
- gridGeometry->update();
-```
-
-In the problem, we define the boundary and initial conditions.
-
-```cpp
- using Problem = GetPropType<TypeTag, Properties::Problem>;
- auto problem = std::make_shared<Problem>(gridGeometry);
-```
-
-We initialize the solution vector
-
-```cpp
- using SolutionVector = GetPropType<TypeTag, Properties::SolutionVector>;
- SolutionVector x(gridGeometry->numDofs());
- problem->applyInitialSolution(x);
- auto xOld = x;
-```
-
-And then use the solutionvector to intialize the gridVariables.
-
-```cpp
- using GridVariables = GetPropType<TypeTag, Properties::GridVariables>;
- auto gridVariables = std::make_shared<GridVariables>(problem, gridGeometry);
- gridVariables->init(x);
-```
-
-We get some time loop parameters from the input file.
-
-```cpp
- using Scalar = GetPropType<TypeTag, Properties::Scalar>;
- const auto tEnd = getParam<Scalar>("TimeLoop.TEnd");
- const auto maxDt = getParam<Scalar>("TimeLoop.MaxTimeStepSize");
- auto dt = getParam<Scalar>("TimeLoop.DtInitial");
-```
-
-We intialize the vtk output module. Each model has a predefined model specific output with relevant parameters for that model.
-
-```cpp
- using IOFields = GetPropType<TypeTag, Properties::IOFields>;
- VtkOutputModule<GridVariables, SolutionVector> vtkWriter(*gridVariables,x, problem->name());
-```
-
-We add the analytical solution ("exactWaterDepth" and "exactVelocityX") to the predefined specific output.
-
-```cpp
- vtkWriter.addField(problem->getExactWaterDepth(), "exactWaterDepth");
- vtkWriter.addField(problem->getExactVelocityX(), "exactVelocityX");
-```
-
-We calculate the analytic solution.
-
-```cpp
- problem->analyticalSolution();
- IOFields::initOutputModule(vtkWriter);
- vtkWriter.write(0.0);
-```
-
-We instantiate time loop.
-
-```cpp
- auto timeLoop = std::make_shared<CheckPointTimeLoop<Scalar>>(0, dt, tEnd);
- timeLoop->setMaxTimeStepSize(maxDt);
-```
-
-we set the assembler with the time loop because we have an instationary problem.
-
-```cpp
- using Assembler = FVAssembler<TypeTag, DiffMethod::numeric>;
- auto assembler = std::make_shared<Assembler>(problem, gridGeometry, gridVariables, timeLoop);
-```
-
-We set the linear solver.
-
-```cpp
- using LinearSolver = AMGBiCGSTABBackend<LinearSolverTraits<GridGeometry>>;
- auto linearSolver = std::make_shared<LinearSolver>(leafGridView, gridGeometry->dofMapper());
-```
-
-Additionaly, we set the non-linear solver.
-
-```cpp
- using NewtonSolver = Dumux::NewtonSolver<Assembler, LinearSolver>;
- NewtonSolver nonLinearSolver(assembler, linearSolver);
-```
-
-We set some check point at the end of the time loop. The check point is used to trigger the vtk output.
-
-```cpp
- timeLoop->setCheckPoint(tEnd);
-```
-
-We start the time loop.
-
-```cpp
- timeLoop->start(); do
- {
-```
-
-We start to calculate the new solution of that time step. First we define the old solution as the solution of the previous time step for storage evaluations.
-
-```cpp
- assembler->setPreviousSolution(xOld);
-```
-
-We solve the non-linear system with time step control.
-
-```cpp
- nonLinearSolver.solve(x,*timeLoop);
-```
-
-We make the new solution the old solution.
-
-```cpp
- xOld = x;
- gridVariables->advanceTimeStep();
-```
-
-We advance to the time loop to the next step.
-
-```cpp
- timeLoop->advanceTimeStep();
-```
-
-We write vtk output, if we reached the check point (end of time loop)
-
-```cpp
- if (timeLoop->isCheckPoint())
- vtkWriter.write(timeLoop->time());
-```
-
-We report statistics of this time step.
-
-```cpp
- timeLoop->reportTimeStep();
-```
-
-We set new dt as suggested by newton controller for the next time step.
-
-```cpp
- timeLoop->setTimeStepSize(nonLinearSolver.suggestTimeStepSize(timeLoop->timeStepSize()));
-
-
- } while (!timeLoop->finished());
-
- timeLoop->finalize(leafGridView.comm());
-```
-
-### Final Output
-We print dumux end message.
-
-```cpp
- if (mpiHelper.rank() == 0)
- {
- Parameters::print();
- DumuxMessage::print(/*firstCall=*/false);
- }
-
- return 0;
-} // end main
-
-catch (const Dumux::ParameterException &e)
-{
- std::cerr << std::endl << e << " ---> Abort!" << std::endl;
- return 1;
-}
-catch (const Dune::DGFException & e)
-{
- std::cerr << "DGF exception thrown (" << e <<
- "). Most likely, the DGF file name is wrong "
- "or the DGF file is corrupted, "
- "e.g. missing hash at end of file or wrong number (dimensions) of entries."
- << " ---> Abort!" << std::endl;
- return 2;
-}
-catch (const Dune::Exception &e)
-{
- std::cerr << "Dune reported error: " << e << " ---> Abort!" << std::endl;
- return 3;
-}
-catch (...)
-{
- std::cerr << "Unknown exception thrown! ---> Abort!" << std::endl;
- return 4;
-}
-```
+## Part 2: Main program flow
+| [:arrow_right: Click to continue with part 2 of the documentation](doc/main.md) |
+|---:|
\ No newline at end of file
diff --git a/examples/shallowwaterfriction/doc/_intro.md b/examples/shallowwaterfriction/doc/_intro.md
new file mode 100644
index 0000000000..172ca8fb06
--- /dev/null
+++ b/examples/shallowwaterfriction/doc/_intro.md
@@ -0,0 +1,139 @@
+# Shallow water flow with bottom friction
+In this example, the shallow water flow model is applied to simulate
+a steady subcritical flow including bottom friction (bed shear stress).
+
+__You will learn how to__
+
+* solve a shallow water flow problem including bottom friction
+* compute and output (VTK) an analytical reference solution
+
+__Result__. The numerical and analytical solutions for the free surface will look like this:
+
+<figure>
+ <center>
+ <img src="img/swe_result.png" alt="Shallow water result" width="60%"/>
+ <figcaption> <b> Fig.1 </b> - Setup and result for the shallow water problem with bottom friction.</figcaption>
+ </center>
+</figure>
+
+__Table of contents__. This description is structured as follows:
+
+[[_TOC_]]
+
+## Problem set-up
+### Model domain
+The model domain is given by a rough channel with a slope of 0.001.
+The domain is 500 meters long and 5 meters wide.
+The bottom altitude is 10 m at the inflow and hence 9.5 m at the outflow.
+Bottom friction is considered by applying
+Manning's law ($`n`$ = 0.025).
+
+### Boundary conditions
+At the lateral sides a no-flow boundary condition is applied. Also no friction is
+considered there and therefore a no slip boundary
+condition is applied. These are the default boundary condition for the shallow
+water model. At the left border a discharge boundary condition
+is applied as inflow boundary condition with $`q = -1.0 m^2 s^{-1}`$.
+At the right border a fixed water depth boundary condition
+is applied for the outflow. Normal flow is assumed, therefore the water
+depth at the right border is calculated using the equation
+of Gauckler, Manning and Strickler.
+
+### Initial conditons
+The initial water depth is set to 1 m, which is slightly higher than the normal flow
+water depth (0.87 m). Therefore, we expect a decreasing
+water level during the simulation until the normal flow condition is reached in
+the entire model domain. The inital velocity is set to zero.
+
+## Model description
+As mentioned above, this examples uses the shallow water equations (SWEs) to solve the problem.
+These are a depth averaged simplification of the Navier-Stokes equations. To calculate the
+bottom friction Manning's law is used. An alternative is Nikuradse's law, which is also implemented
+in DuMu<sup>x</sup>.
+
+### Shallow water model
+The shallow water equations are given as:
+
+```math
+\frac{\partial \mathbf{U}}{\partial t} +
+\frac{\partial \mathbf{F}}{\partial x} +
+\frac{\partial \mathbf{G}}{\partial y} - \mathbf{S_b} - \mathbf{S_f} = 0
+```
+
+where $`\mathbf{U}`$, $`\mathbf{F}`$ and $`\mathbf{G}`$ defined as
+
+```math
+\mathbf{U} = \begin{bmatrix} h \\ uh \\ vh \end{bmatrix},
+\mathbf{F} = \begin{bmatrix} hu \\ hu^2 + \frac{1}{2} gh^2 \\ huv \end{bmatrix},
+\mathbf{G} = \begin{bmatrix} hv \\ huv \\ hv^2 + \frac{1}{2} gh^2 \end{bmatrix}
+```
+
+$`h`$ the water depth, $`u`$ the velocity in x-direction and $`v`$ the velocity in y-direction,
+$`g`$ is the constant of gravity.
+
+The source terms for the bed slope $`\mathbf{S_b}`$ and friction
+$`\mathbf{S_f}`$ are given as
+
+```math
+\mathbf{S_b} = \begin{bmatrix} 0 \\ -gh \frac{\partial z}{\partial x}
+ \\ -gh \frac{\partial z}{\partial y}\end{bmatrix},
+\mathbf{S_f} = \begin{bmatrix} 0 \\ghS_{fx} \\ghS_{fy}\end{bmatrix}.
+```
+
+with the bedSurface $`z`$. $`S_{fx}`$ and $`S_{fy}`$ are the bed shear stess
+components in x- and y-direction, which are calculated by Manning's law.
+
+### Mannings law
+The empirical Manning model specifies the bed shear stress by the following equations:
+
+```math
+S_{fx} = \frac{n^2u}{R_{hy}^{4/3}} \sqrt(u^2 + v^2),
+
+S_{fy} = \frac{n^2v}{R_{hy}^{4/3}} \sqrt(u^2 + v^2)
+```
+
+$`n`$ is Manning's friction value and $`R_{hy}`$ is the hydraulic radius,
+which is assumed to be equal to the water depth $`h`$.
+
+### Analytical solution
+Since normal flow conditions are assumed, the analytic solution is calculated using the equation
+of Gauckler, Manning and Strickler:
+
+```math
+v_m = n^{-1} R_{hy}^{2/3} I_s^{1/2}
+```
+
+Where the mean velocity $`v_m`$ is given as
+
+```math
+v_m = \frac{q}{h}
+```
+
+$`I_s`$ is the bed slope and $`q`$ the unity inflow discharge.
+
+Hence, the water depth $`h`$ can be calculated by
+
+```math
+h = \left(\frac{n q}{\sqrt{I_s}} \right)^{3/5}
+```
+
+### Discretisation
+For this example, a cell-centered finite volume method (cctpfa) is applied to solve the SWEs
+in combination with a fully-implicit time discretization. For cases where no sharp fronts or
+traveling waves occur it is possible to apply time steps larger than CFL number = 1 to reduce
+the computation time. Even if a steady state solution is considered, an implicit time stepping method
+is applied.
+
+# Implementation
+
+## Folder layout and files
+
+```
+└── shallowwaterfriction/
+ ├── CMakeLists.txt -> build system file
+ ├── main.cc -> main program flow
+ ├── params.input -> runtime parameters
+ ├── properties.hh -> compile time configuration
+ ├── problem.hh -> boundary & initial conditions
+ └── spatialparams.hh -> spatial parameter fields
+```
diff --git a/examples/shallowwaterfriction/doc/intro.md b/examples/shallowwaterfriction/doc/intro.md
deleted file mode 100644
index f0f5e0a155..0000000000
--- a/examples/shallowwaterfriction/doc/intro.md
+++ /dev/null
@@ -1,97 +0,0 @@
-# Shallow water flow with bottom friction
-This example shows how the shallow water flow model can be
-applied to simulate steady subcritical flow including
-bottom friction (bed shear stress).
-
-__You will learn how to__
-
-* solve a shallow water flow problem including bottom friction
-* compute and output (VTK) an analytical reference solution
-
-__Result__. The numerical and analytical solutions for the problem will look like this:
-
-
-
-__Table of contents__. This description is structured as follows:
-
-[[_TOC_]]
-
-## Mathematical model
-The 2D shallow water equations (SWEs) are given by
-
-```math
-\frac{\partial \mathbf{U}}{\partial t} +
-\frac{\partial \mathbf{F}}{\partial x} +
-\frac{\partial \mathbf{G}}{\partial y} - \mathbf{S_b} - \mathbf{S_f} = 0
-```
-
-where $`\mathbf{U}`$, $`\mathbf{F}`$ and $`\mathbf{G}`$ defined as
-
-```math
-\mathbf{U} = \begin{bmatrix} h \\ uh \\ vh \end{bmatrix},
-\mathbf{F} = \begin{bmatrix} hu \\ hu^2 + \frac{1}{2} gh^2 \\ huv \end{bmatrix},
-\mathbf{G} = \begin{bmatrix} hv \\ huv \\ hv^2 + \frac{1}{2} gh^2 \end{bmatrix}
-```
-
-$`Z`$ is the bedSurface, $`h`$ the water depth, $`u`$ the velocity in
-x-direction and $`v`$ the velocity in y-direction, $`g`$ is the constant of gravity.
-
-The source terms for the bed friction $`\mathbf{S_b}`$ and bed slope
-$`\mathbf{S_f}`$ are given as
-
-```math
-\mathbf{S_b} = \begin{bmatrix} 0 \\ -gh \frac{\partial z}{\partial x}
- \\ -gh \frac{\partial z}{\partial y}\end{bmatrix},
-\mathbf{S_f} = \begin{bmatrix} 0 \\ -ghS_{fx} \\ -ghS_{fy}\end{bmatrix}.
-```
-
-For this example, a cell-centered finite volume method (`cctpfa`) is applied to solve the SWEs
-in combination with a fully-implicit time discretization. For cases where no sharp fronts or
-traveling waves occur it is possible to apply time steps larger than CFL number = 1 to reduce
-the computation time. Even if a steady state solution is considered, an implicit time stepping method
-is applied.
-
-## Problem set-up
-
-The model domain is given by a rough channel with a slope of 0.001.
-The domain is 500 meters long and 10 meters wide.
-.
-
-Bottom friction is considered by applying
-the friction law of Manning (Manning n = 0.025). At the lateral sides no friction is considered and a
-no-flow no slip boundary condition is applied. This is the default boundary condition for the shallow water model.
-
-At the left border a discharge boundary condition
-is applied as inflow boundary condition with q = -1.0 ($`m^2 s^{-1}`$). At the right border a water fixed depth boundary condition
-is applied for the outflow. Normal flow is assumed, therefore the water depth at the right border is calculated after
-the of Gaukler-Manning-Strickler equation:
-
-```math
-v_m = n^{-1} R_{hy}^{2/3} I_s^{1/2}
-```
-
-Where the mean velocity $`v_m`$ is given as $`v_m = \frac{q}{h}`$,
-$`n`$ is the friction value after Manning. $`R_{hy}`$ the hydraulic radius, which is assumed to be equal to
-the water depth. $`I_s`$ is the bed slope and $`q`$ the unity inflow discharge
-
-The water depth h can be calculated as
-```math
-h = \left(\frac{n q}{\sqrt{I_s}} \right)^{3/5}
-```
-
-The formula of Gaukler Manning and Strickler is also used to calculate the analytic solution. All parameters
-for the simulation are given in the file `params.input`.
-
-# Implementation
-
-## Folder layout and files
-
-```
-└── shallowwaterfriction/
- ├── CMakeLists.txt -> build system file
- ├── main.cc -> main program flow
- ├── params.input -> runtime parameters
- ├── properties.hh -> compile time configuration
- ├── problem.hh -> boundary & initial conditions
- └── spatialparams.hh -> spatial parameter fields
-```
diff --git a/examples/shallowwaterfriction/doc/main.md b/examples/shallowwaterfriction/doc/main.md
new file mode 100644
index 0000000000..01bb7c10ac
--- /dev/null
+++ b/examples/shallowwaterfriction/doc/main.md
@@ -0,0 +1,301 @@
+<!-- Important: This file has been automatically generated by generate_example_docs.py. Do not edit this file directly! -->
+
+
+| [:arrow_left: Back to the main documentation](../README.md) | [:arrow_left: Go back to part 1](swe.md) |
+|---|---:|
+
+# Part 2: Main program flow
+
+We want to solve a shallow water flow problem in a rough
+channel to obtain the water table and
+compare it to the analytic solution. This is done with the
+`main()` function
+of the program which is defined in the file `main.cc` described below.
+
+The code documentation is structured as follows:
+
+[[_TOC_]]
+
+
+
+## The main file `main.cc`
+
+<details open>
+<summary><b>Click to hide/show the file documentation</b> (or inspect the [source code](../main.cc))</summary>
+
+
+### Included header files
+<details><summary> Click to show includes</summary>
+
+These are DUNE helper classes related to parallel computations, time measurements and file I/O
+
+```cpp
+#include <dune/common/parallel/mpihelper.hh>
+#include <dune/common/timer.hh>
+#include <dune/grid/io/file/dgfparser/dgfexception.hh>
+#include <dune/grid/io/file/vtk.hh>
+```
+
+The following headers include functionality related to property definition or retrieval, as well as
+the retrieval of input parameters specified in the input file or via the command line.
+
+```cpp
+#include <dumux/common/properties.hh>
+#include <dumux/common/parameters.hh>
+```
+
+The following files contains the available linear solver backends, the non linear Newton Solver
+and the assembler for the linear systems arising from finite volume discretizations
+(box-scheme, tpfa-approximation, mpfa-approximation).
+
+```cpp
+#include <dumux/linear/amgbackend.hh>
+#include <dumux/nonlinear/newtonsolver.hh>
+#include <dumux/assembly/fvassembler.hh>
+```
+
+The following class provides a convenient way of writing of dumux simulation results to VTK format.
+
+```cpp
+#include <dumux/io/vtkoutputmodule.hh>
+```
+
+The gridmanager constructs a grid from the information in the input or grid file.
+Many different Dune grid implementations are supported, of which a list can be found
+in `gridmanager.hh`.
+
+```cpp
+#include <dumux/io/grid/gridmanager.hh>
+```
+
+We include the header file specifing the properties of this example
+
+```cpp
+#include "properties.hh"
+```
+
+</details>
+
+### The main function
+We will now discuss the main program flow implemented within the `main` function.
+At the beginning of each program using Dune, an instance of `Dune::MPIHelper` has to
+be created. Moreover, we parse the run-time arguments from the command line and the
+input file:
+
+```cpp
+int main(int argc, char** argv) try
+{
+ using namespace Dumux;
+
+ // The Dune MPIHelper must be instantiated for each program using Dune
+ Dune::MPIHelper::instance(argc, argv);
+
+ // We parse command line arguments and input file
+ Parameters::init(argc, argv);
+```
+
+We define a convenience alias for the type tag of the problem. The type
+tag contains all the properties that are needed to define the model and the problem
+setup. Throughout the main file, we will obtain types defined for these type tag
+using the property system, i.e. with `GetPropType`.
+
+```cpp
+ using TypeTag = Properties::TTag::RoughChannel;
+```
+
+#### Step 1: Create the grid
+The `GridManager` class creates the grid from information given in the input file.
+This can either be a grid file or, in the case of structured grids, one can specify the coordinates
+of the corners of the grid and the number of cells to be used to discretize each spatial direction.
+
+```cpp
+ GridManager<GetPropType<TypeTag, Properties::Grid>> gridManager;
+ gridManager.init();
+
+ // We compute on the leaf grid view
+ const auto& leafGridView = gridManager.grid().leafGridView();
+```
+
+#### Step 2: Solving the shallow water problem
+First, a finite volume grid geometry is constructed from the grid that was created above.
+This builds the sub-control volumes (scv) and sub-control volume faces (scvf) for each element
+of the grid partition.
+
+```cpp
+ using GridGeometry = GetPropType<TypeTag, Properties::GridGeometry>;
+ auto gridGeometry = std::make_shared<GridGeometry>(leafGridView);
+ gridGeometry->update();
+```
+
+We now instantiate the problem, in which we define the boundary and initial conditions.
+
+```cpp
+ using Problem = GetPropType<TypeTag, Properties::Problem>;
+ auto problem = std::make_shared<Problem>(gridGeometry);
+```
+
+We initialize the solution vector. The shallow water problem is transient,
+therefore the initial solution defined in the problem is applied to the
+solution vector. On the basis of this solution, we initialize then the grid variables.
+
+```cpp
+ using SolutionVector = GetPropType<TypeTag, Properties::SolutionVector>;
+ SolutionVector x(gridGeometry->numDofs());
+ problem->applyInitialSolution(x);
+ auto xOld = x;
+
+ using GridVariables = GetPropType<TypeTag, Properties::GridVariables>;
+ auto gridVariables = std::make_shared<GridVariables>(problem, gridGeometry);
+ gridVariables->init(x);
+```
+
+Let us now instantiate the time loop. Therefore, we read in some time loop parameters from the input file.
+The parameter `tEnd` defines the duration of the simulation, `dt` the initial time step size and `maxDt` the maximal time step size.
+Moreover, we define the end of the simulation `tEnd` as check point in the time loop at which we will write the solution to vtk files.
+
+```cpp
+ using Scalar = GetPropType<TypeTag, Properties::Scalar>; // type for scalar values
+ const auto tEnd = getParam<Scalar>("TimeLoop.TEnd");
+ const auto maxDt = getParam<Scalar>("TimeLoop.MaxTimeStepSize");
+ auto dt = getParam<Scalar>("TimeLoop.DtInitial");
+
+ // We instantiate time loop.
+ auto timeLoop = std::make_shared<CheckPointTimeLoop<Scalar>>(0.0, dt, tEnd);
+ timeLoop->setMaxTimeStepSize(maxDt);
+ timeLoop->setCheckPoint(tEnd);
+```
+
+We initialize the assembler with a time loop for the transient problem.
+Within the time loop, we will use this assembler in each time step to assemble the linear system.
+
+```cpp
+ using Assembler = FVAssembler<TypeTag, DiffMethod::numeric>;
+ auto assembler = std::make_shared<Assembler>(problem, gridGeometry, gridVariables, timeLoop);
+```
+
+We initialize the linear solver.
+
+```cpp
+ using LinearSolver = AMGBiCGSTABBackend<LinearSolverTraits<GridGeometry>>;
+ auto linearSolver = std::make_shared<LinearSolver>(leafGridView, gridGeometry->dofMapper());
+```
+
+We initialize the non-linear solver.
+
+```cpp
+ using NewtonSolver = Dumux::NewtonSolver<Assembler, LinearSolver>;
+ NewtonSolver nonLinearSolver(assembler, linearSolver);
+```
+
+The following lines of code initialize the vtk output module, add the velocity output facility
+and write out the initial solution. At each checkpoint, we will use the output module to write
+the solution of a time step into a corresponding vtk file.
+
+```cpp
+ VtkOutputModule<GridVariables, SolutionVector> vtkWriter(*gridVariables,x, problem->name());
+
+ // add model-specific output fields to the writer
+ using IOFields = GetPropType<TypeTag, Properties::IOFields>;
+ IOFields::initOutputModule(vtkWriter);
+
+ // We add the analytical solution ("exactWaterDepth" and "exactVelocityX") to the predefined specific output.
+ vtkWriter.addField(problem->getExactWaterDepth(), "exactWaterDepth");
+ vtkWriter.addField(problem->getExactVelocityX(), "exactVelocityX");
+
+ // We calculate the analytic solution.
+ problem->analyticalSolution();
+
+ // write initial solution (including the above calculated analytical solution.
+ vtkWriter.write(0.0);
+```
+
+##### The time loop
+We start the time loop and solve a new time step as long as `tEnd` is not reached. In every time step,
+the problem is assembled and solved, the solution is updated, and when a checkpoint is reached the solution
+is written to a new vtk file. In addition, statistics related to CPU time, the current simulation time
+and the time step sizes used is printed to the terminal.
+
+```cpp
+ timeLoop->start(); do
+ {
+ // First we define the old solution as the solution of the previous time step for storage evaluations.
+ assembler->setPreviousSolution(xOld);
+
+ // We solve the non-linear system with time step control, using Newthon's method.
+ nonLinearSolver.solve(x,*timeLoop);
+
+ // We make the new solution the old solution.
+ xOld = x;
+ gridVariables->advanceTimeStep();
+
+ // We advance to the time loop to the next step.
+ timeLoop->advanceTimeStep();
+
+ // We write vtk output, if we reached the check point (end of time loop)
+ if (timeLoop->isCheckPoint())
+ vtkWriter.write(timeLoop->time());
+
+ // We report statistics of this time step.
+ timeLoop->reportTimeStep();
+
+ // We set new dt as suggested by newton controller for the next time step.
+ timeLoop->setTimeStepSize(nonLinearSolver.suggestTimeStepSize(timeLoop->timeStepSize()));
+
+
+ } while (!timeLoop->finished());
+```
+
+The following piece of code prints a final status report of the time loop
+before the program is terminated.
+
+```cpp
+ timeLoop->finalize(leafGridView.comm());
+
+ return 0;
+}
+```
+
+#### Exception handling
+In this part of the main file we catch and print possible exceptions that could
+occur during the simulation.
+<details><summary> Click to show exception handler</summary>
+
+```cpp
+// errors related to run-time parameters
+catch (const Dumux::ParameterException &e)
+{
+ std::cerr << std::endl << e << " ---> Abort!" << std::endl;
+ return 1;
+}
+// errors related to the parsing of Dune grid files
+catch (const Dune::DGFException & e)
+{
+ std::cerr << "DGF exception thrown (" << e <<
+ "). Most likely, the DGF file name is wrong "
+ "or the DGF file is corrupted, "
+ "e.g. missing hash at end of file or wrong number (dimensions) of entries."
+ << " ---> Abort!" << std::endl;
+ return 2;
+}
+// generic error handling with Dune::Exception
+catch (const Dune::Exception &e)
+{
+ std::cerr << "Dune reported error: " << e << " ---> Abort!" << std::endl;
+ return 3;
+}
+// other exceptions
+catch (...)
+{
+ std::cerr << "Unknown exception thrown! ---> Abort!" << std::endl;
+ return 4;
+}
+```
+
+</details>
+
+</details>
+
+
+| [:arrow_left: Back to the main documentation](../README.md) | [:arrow_left: Go back to part 1](swe.md) |
+|---|---:|
+
diff --git a/examples/shallowwaterfriction/doc/main_intro.md b/examples/shallowwaterfriction/doc/main_intro.md
new file mode 100644
index 0000000000..15c6b8515d
--- /dev/null
+++ b/examples/shallowwaterfriction/doc/main_intro.md
@@ -0,0 +1,12 @@
+# Part 2: Main program flow
+
+We want to solve a shallow water flow problem in a rough
+channel to obtain the water table and
+compare it to the analytic solution. This is done with the
+`main()` function
+of the program which is defined in the file `main.cc` described below.
+
+The code documentation is structured as follows:
+
+[[_TOC_]]
+
diff --git a/examples/shallowwaterfriction/doc/swe.md b/examples/shallowwaterfriction/doc/swe.md
new file mode 100644
index 0000000000..8a94e8440b
--- /dev/null
+++ b/examples/shallowwaterfriction/doc/swe.md
@@ -0,0 +1,570 @@
+<!-- Important: This file has been automatically generated by generate_example_docs.py. Do not edit this file directly! -->
+
+
+| [:arrow_left: Back to the main documentation](../README.md) | [:arrow_right: Continue with part 2](main.md) |
+|---|---:|
+
+# Part 1: Implementation of the shallow water flow simulation setup
+
+The shallow water flow setup, including the bottom friction,
+is implemented in the files `properties.hh`,
+`problem.hh` and `spatialparams.hh`. In the first of these files, a new
+type tag is declared for this problem. This allows the specialization
+of DuMu<sup>x</sup> `properties` for this type tag, which can be used to customize compile-time
+settings for the simulation. Two exemplary `properties`, that are mandatory to be
+specialized, are `Problem` and `SpatialParams`. With the first, one sets the
+`Problem` class to be used, in which users can define initial and boundary conditions.
+Similarly, in the `SpatialParams` class one implements the parameter distributions
+(e.g. friction value) that should be used by the model.
+
+The documentation provided in the sequel is structured as follows:
+
+[[_TOC_]]
+
+
+
+## Compile-time settings (`properties.hh`)
+
+In this file, the type tag used for the shallow water flow simulation is defined,
+for which we then specialize `properties` to the needs of the desired setup.
+
+
+<details open>
+<summary><b>Click to hide/show the file documentation</b> (or inspect the [source code](../properties.hh))</summary>
+
+
+### Includes
+<details><summary> Click to show include files</summary>
+
+The `ShallowWater` type tag specializes most of the `properties` required for a
+shallow water flow simulation in DuMu<sup>x</sup>. We will use this in the following to inherit the
+respective properties and subsequently specialize those `properties` for our
+type tag, which we want to modify or for which no meaningful default can be set.
+
+```cpp
+#include <dumux/freeflow/shallowwater/model.hh>
+```
+
+We want to use `YaspGrid`, an implementation of the dune grid interface for structured grids:
+
+```cpp
+#include <dune/grid/yaspgrid.hh>
+```
+
+In this example, we want to discretize the equations with the cell centered finite volume
+scheme using two-point-flux approximation:
+
+```cpp
+#include <dumux/discretization/cctpfa.hh>
+```
+
+We include the problem and spatial parameters headers used for this simulation.
+
+```cpp
+#include "problem.hh"
+#include "spatialparams.hh"
+```
+
+</details>
+
+### Type tag definition
+
+First, a so-called type tag is created. Properties are traits specialized for this type tag (a simple `struct`).
+The properties of two other type tags are inherited by adding the alias `InheritsFrom`.
+Here, properties from the shallow water model (`TTag::ShallowWater`) and the
+cell-centered finite volume scheme with two-point-flux approximation (`TTag::CCTpfaModel`)
+are inherited. These other type tag definitions can be found in the included
+headers `dumux/freeflow/shallowwater/model.hh` and `dumux/discretization/cctpfa.hh`.
+
+```cpp
+// We enter the namespace Dumux::Properties in order to import the entire Dumux namespace for general use:
+namespace Dumux::Properties {
+
+namespace TTag {
+struct RoughChannel { using InheritsFrom = std::tuple<ShallowWater, CCTpfaModel>; };
+}
+```
+
+### Property specializations
+
+We use a structured Cartesian grid with tensor product structure.
+`Dune::YaspGrid` (Yet Another Structure Parallel Grid) is defined in `dune/grid/yaspgrid.hh`
+in the Dune module `dune-grid`.
+
+```cpp
+template<class TypeTag>
+struct Grid<TypeTag, TTag::RoughChannel>
+{ using type = Dune::YaspGrid<2, Dune::TensorProductCoordinates<GetPropType<TypeTag, Properties::Scalar>, 2> >; };
+```
+
+Next, we specialize the properties `Problem` and `SpatialParams` for our new type tag and
+set the type to our problem and spatial parameter classes implemented
+in `problem.hh` and `spatialparams.hh`.
+
+```cpp
+template<class TypeTag>
+struct Problem<TypeTag, TTag::RoughChannel>
+{ using type = Dumux::RoughChannelProblem<TypeTag>; };
+
+template<class TypeTag>
+struct SpatialParams<TypeTag, TTag::RoughChannel>
+{
+ using GridGeometry = GetPropType<TypeTag, Properties::GridGeometry>;
+ using Scalar = GetPropType<TypeTag, Properties::Scalar>;
+ using ElementVolumeVariables = typename GetPropType<TypeTag, Properties::GridVolumeVariables>::LocalView;
+ using VolumeVariables = typename ElementVolumeVariables::VolumeVariables;
+
+ using type = RoughChannelSpatialParams<GridGeometry, Scalar, VolumeVariables>;
+};
+```
+
+Finally, we enable caching for the grid geometry. The cache
+stores values that were already calculated for later usage.
+This makes the simulation run faster but it uses more memory.
+
+```cpp
+template<class TypeTag>
+struct EnableGridGeometryCache<TypeTag, TTag::RoughChannel>
+{ static constexpr bool value = true; };
+
+} // end namespace Dumux::Properties
+```
+
+
+</details>
+
+
+
+## The problem file (`problem.hh`)
+
+This file contains the __problem class__ which defines the initial and boundary
+conditions for the shallow water flow simulation with bottom friction.
+In addition, the analytical solution is defined here.
+
+
+<details open>
+<summary><b>Click to hide/show the file documentation</b> (or inspect the [source code](../problem.hh))</summary>
+
+
+### Include files
+
+The first include we need here is the `ShallowWaterProblem` class, the base
+class from which we will derive.
+
+```cpp
+#include <dumux/freeflow/shallowwater/problem.hh>
+```
+
+In addition, we need the boundaryflux header, which handels the flux over
+the model boundaries.
+
+```cpp
+#include <dumux/freeflow/shallowwater/boundaryfluxes.hh>
+```
+
+### The problem class
+We enter the problem class where all necessary boundary conditions and initial conditions are set for our simulation.
+In addition the analytical solution of the problem is calculated.
+As this is a shallow water problem, we inherit from the basic ShallowWaterProblem.
+
+```cpp
+namespace Dumux {
+
+template <class TypeTag>
+class RoughChannelProblem : public ShallowWaterProblem<TypeTag>
+{
+ // A few convenience aliases used throughout this class.
+ using ParentType = ShallowWaterProblem<TypeTag>;
+ using PrimaryVariables = GetPropType<TypeTag, Properties::PrimaryVariables>;
+ using BoundaryTypes = GetPropType<TypeTag, Properties::BoundaryTypes>;
+ using Scalar = GetPropType<TypeTag, Properties::Scalar>;
+ using Indices = typename GetPropType<TypeTag, Properties::ModelTraits>::Indices;
+ using GridGeometry = GetPropType<TypeTag, Properties::GridGeometry>;
+ using NeumannFluxes = GetPropType<TypeTag, Properties::NumEqVector>;
+ using ElementVolumeVariables = typename GetPropType<TypeTag, Properties::GridVolumeVariables>::LocalView;
+ using GridVariables = GetPropType<TypeTag, Properties::GridVariables>;
+ using ElementFluxVariablesCache = typename GridVariables::GridFluxVariablesCache::LocalView;
+ using FVElementGeometry = typename GetPropType<TypeTag, Properties::GridGeometry>::LocalView;
+ using SubControlVolumeFace = typename FVElementGeometry::SubControlVolumeFace;
+ using GridView = typename GetPropType<TypeTag, Properties::GridGeometry>::GridView;
+ using Element = typename GridView::template Codim<0>::Entity;
+ using GlobalPosition = typename Element::Geometry::GlobalCoordinate;
+ using NumEqVector = GetPropType<TypeTag, Properties::NumEqVector>;
+ using SubControlVolume = typename FVElementGeometry::SubControlVolume;
+
+public:
+ // This is the constructor of our problem class.
+ RoughChannelProblem(std::shared_ptr<const GridGeometry> gridGeometry)
+ : ParentType(gridGeometry)
+ {
+ // We read the parameters from the params.input file.
+ constManningN_ = getParam<Scalar>("Problem.ManningN");
+ bedSlope_ = getParam<Scalar>("Problem.BedSlope");
+ discharge_ = getParam<Scalar>("Problem.Discharge");
+ // We calculate the outflow boundary condition using the Gauckler-Manning-Strickler formula.
+ hBoundary_ = this->gaucklerManningStrickler(discharge_,constManningN_,bedSlope_);
+ // We initialize the analytic solution to a verctor of the appropriate size filled with zeros.
+ exactWaterDepth_.resize(gridGeometry->numDofs(), 0.0);
+ exactVelocityX_.resize(gridGeometry->numDofs(), 0.0);
+ }
+```
+
+#### Analytical Solution
+
+The analytical solution is calculated using the equation of Gauckler, Manning and Strickler.
+
+```cpp
+
+ // Equation of Gauckler, Manning and Strickler
+ Scalar gaucklerManningStrickler(Scalar discharge, Scalar manningN, Scalar bedSlope)
+ {
+ using std::pow;
+ using std::abs;
+ using std::sqrt;
+
+ return pow(abs(discharge)*manningN/sqrt(bedSlope), 0.6);
+ }
+
+ // Calculate the analytical solution
+ void analyticalSolution()
+ {
+ using std::abs;
+
+ for (const auto& element : elements(this->gridGeometry().gridView()))
+ {
+ const Scalar h = this->gaucklerManningStrickler(discharge_,constManningN_,bedSlope_);
+ const Scalar u = abs(discharge_)/h;
+
+ const auto eIdx = this->gridGeometry().elementMapper().index(element);
+ exactWaterDepth_[eIdx] = h;
+ exactVelocityX_[eIdx] = u;
+ }
+ }
+
+ // Getter function for the analytical solution of the water depth
+ const std::vector<Scalar>& getExactWaterDepth()
+ {
+ return exactWaterDepth_;
+ }
+
+ // Getter function for the analytical solution of the velocity in x-direction
+ const std::vector<Scalar>& getExactVelocityX()
+ {
+ return exactVelocityX_;
+ }
+```
+
+#### Bottom friction
+
+The bottom friction is a source term and therefore handled by the `source` function.
+
+```cpp
+ NumEqVector source(const Element& element,
+ const FVElementGeometry& fvGeometry,
+ const ElementVolumeVariables& elemVolVars,
+ const SubControlVolume &scv) const
+ {
+
+ NumEqVector source (0.0);
+
+ // Since the bed slope source term is handels within the flux computation,
+ // in this model the bottom friction is the only source term.
+ source += bottomFrictionSource(element, fvGeometry, elemVolVars, scv);
+
+ return source;
+ }
+```
+
+The calculation of the source term due to bottom friction needs the bottom shear stess.
+This is the force per area, which works between the flow and the channel bed
+(1D vector with two entries) and is calculated within the `FrictionLaw` class.
+The bottom friction causes a loss of momentum. Thus the first entry of the `bottomFrictionSource`,
+which is related to the mass balance equation is zero.
+The second entry of the `bottomFricitonSource` corresponds to the momentum equation in x-direction
+and is therefore equal to the first, the x-component, of the `bottomShearStress`.
+Accordingly, the third entry of the `bottomFrictionSource` is equal to the second component of the `bottomShearStress`.
+
+```cpp
+ NumEqVector bottomFrictionSource(const Element& element,
+ const FVElementGeometry& fvGeometry,
+ const ElementVolumeVariables& elemVolVars,
+ const SubControlVolume &scv) const
+ {
+ NumEqVector bottomFrictionSource(0.0);
+ const auto& volVars = elemVolVars[scv];
+
+ // bottom shear stress vector
+ Dune::FieldVector<Scalar, 2> bottomShearStress = this->spatialParams().frictionLaw(element, scv).shearStress(volVars);
+
+ // source term due to bottom friction
+ bottomFrictionSource[0] = 0.0;
+ bottomFrictionSource[1] = bottomShearStress[0];
+ bottomFrictionSource[2] = bottomShearStress[1];
+
+ return bottomFrictionSource;
+ }
+```
+
+#### Boundary conditions
+
+We define the __type of all boundary conditions__ as neumann-type,
+because we use a weak imposition.
+
+```cpp
+ BoundaryTypes boundaryTypesAtPos(const GlobalPosition &globalPos) const
+ {
+ BoundaryTypes bcTypes;
+ bcTypes.setAllNeumann();
+ return bcTypes;
+ }
+```
+
+In the following function we implement the __Neumann boundary conditions__.
+Due to the weak imposition we calculate the flux at the boundary with a Riemann solver.
+This needs the state of a virtual cell outside of the boundary (`boundaryStateVariables`),
+wich is calculated with the Riemann invariants
+(see: Yoon and Kang, "Finite Volume Model for Two-Dimensional Shallow Water Flows on Unstructured Grids").
+
+```cpp
+ NeumannFluxes neumann(const Element& element,
+ const FVElementGeometry& fvGeometry,
+ const ElementVolumeVariables& elemVolVars,
+ const ElementFluxVariablesCache& elemFluxVarsCache,
+ const SubControlVolumeFace& scvf) const
+ {
+ NeumannFluxes values(0.0);
+
+ const auto& insideScv = fvGeometry.scv(scvf.insideScvIdx());
+ const auto& insideVolVars = elemVolVars[insideScv];
+ const auto& nxy = scvf.unitOuterNormal();
+ const auto gravity = this->spatialParams().gravity(scvf.center());
+ std::array<Scalar, 3> boundaryStateVariables;
+
+ // Calculate the Riemann invariants for imposed discharge at the left side.
+ if (scvf.center()[0] < 0.0 + eps_)
+ {
+ boundaryStateVariables = ShallowWater::fixedDischargeBoundary(discharge_,
+ insideVolVars.waterDepth(),
+ insideVolVars.velocity(0),
+ insideVolVars.velocity(1),
+ gravity,
+ nxy);
+ }
+ // Calculate the Riemann invariants for imposed water depth at the right side.
+ else if (scvf.center()[0] > 500.0 - eps_)
+ {
+ boundaryStateVariables = ShallowWater::fixedWaterDepthBoundary(hBoundary_,
+ insideVolVars.waterDepth(),
+ insideVolVars.velocity(0),
+ insideVolVars.velocity(1),
+ gravity,
+ nxy);
+ }
+ // Calculate the Riemann invariants for the no-flow boundary.
+ else
+ {
+ boundaryStateVariables[0] = insideVolVars.waterDepth();
+ boundaryStateVariables[1] = -insideVolVars.velocity(0);
+ boundaryStateVariables[2] = -insideVolVars.velocity(1);
+ }
+ // Calculate the boundary fluxes based on a Riemann problem.
+ auto riemannFlux = ShallowWater::riemannProblem(insideVolVars.waterDepth(),
+ boundaryStateVariables[0],
+ insideVolVars.velocity(0),
+ boundaryStateVariables[1],
+ insideVolVars.velocity(1),
+ boundaryStateVariables[2],
+ insideVolVars.bedSurface(),
+ insideVolVars.bedSurface(),
+ gravity,
+ nxy);
+
+ values[Indices::massBalanceIdx] = riemannFlux[0];
+ values[Indices::velocityXIdx] = riemannFlux[1];
+ values[Indices::velocityYIdx] = riemannFlux[2];
+
+ return values;
+ }
+```
+
+#### Initial conditions
+
+We specify the initial conditions for the primary variables (water depth, velocity in y-direction
+and velocity in x-direction). In this example constant initial conditions are used. Therefore the
+argument `globalPos` is not needed. If you want to impose spatial variable initial conditions,
+you have to use the `globalPos` argument.
+
+```cpp
+ PrimaryVariables initialAtPos(const GlobalPosition &globalPos) const
+ {
+ PrimaryVariables initialValues(0.0);
+ // We set the initial water depth to one meter.
+ initialValues[0] = 1.0;
+ // We set the x-component of the initial velocity to zero.
+ initialValues[1] = 0.0;
+ // We set the y-component of the initial velocity to zero.
+ initialValues[2] = 0.0;
+
+ return initialValues;
+ }
+```
+
+We declare the private variables of the problem.
+
+```cpp
+private:
+ // variables for the analytic solution.
+ std::vector<Scalar> exactWaterDepth_;
+ std::vector<Scalar> exactVelocityX_;
+ // constant friction value (an analytic solution is only available for const friction).
+ Scalar constManningN_;
+ // The constant channel bed slope.
+ Scalar bedSlope_;
+ // The water depth at the outflow boundary.
+ Scalar hBoundary_;
+ // The discharge at the inflow boundary.
+ Scalar discharge_;
+ // We assign a private global variable for the epsilon:
+ static constexpr Scalar eps_ = 1.0e-6;
+
+}; // end class definition RoughChannelProblem
+} // end namespace Dumux
+```
+
+
+</details>
+
+
+
+## Parameter distributions (`spatialparams.hh`)
+
+This file contains the __spatial parameters class__ which defines the
+the friction law, including it's friction parameter, the acceleration
+due to gravity and the altitude of the channel bed surface. In this example only the bed
+surface has a non constant distribution.
+
+
+<details open>
+<summary><b>Click to hide/show the file documentation</b> (or inspect the [source code](../spatialparams.hh))</summary>
+
+
+### Include files
+We include the basic spatial parameters file for finite volumes, from which we will inherit.
+
+```cpp
+#include <dumux/material/spatialparams/fv.hh>
+```
+
+We include all friction laws.
+
+```cpp
+#include <dumux/material/fluidmatrixinteractions/frictionlaws/frictionlaw.hh>
+#include <dumux/material/fluidmatrixinteractions/frictionlaws/manning.hh>
+#include <dumux/material/fluidmatrixinteractions/frictionlaws/nikuradse.hh>
+#include <dumux/material/fluidmatrixinteractions/frictionlaws/nofriction.hh>
+```
+
+### The spatial parameters class
+
+In the `RoughChannelSpatialParams` class, we define all functions needed to describe
+the rough channel for the shallow water problem.
+We inherit from the `FVSpatialParams` class, which is the base class
+for spatial parameters in the context of
+applications using finite volume discretization schemes.
+
+```cpp
+namespace Dumux {
+
+template<class GridGeometry, class Scalar, class VolumeVariables>
+class RoughChannelSpatialParams
+: public FVSpatialParams<GridGeometry, Scalar,
+ RoughChannelSpatialParams<GridGeometry, Scalar, VolumeVariables>>
+{
+ // This convenience aliases will be used throughout this class
+ using ThisType = RoughChannelSpatialParams<GridGeometry, Scalar, VolumeVariables>;
+ using ParentType = FVSpatialParams<GridGeometry, Scalar, ThisType>;
+ using GridView = typename GridGeometry::GridView;
+ using FVElementGeometry = typename GridGeometry::LocalView;
+ using SubControlVolume = typename FVElementGeometry::SubControlVolume;
+ using Element = typename GridView::template Codim<0>::Entity;
+ using GlobalPosition = typename Element::Geometry::GlobalCoordinate;
+```
+
+In the following, the properties of the the rough channel are set. Namely, these are
+the friction law, including it's friction parameter, the acceleration
+due to gravity and the altitude of the channel bed surface.
+
+```cpp
+public:
+ // In the constructor we read some values from the `params.input` and initialize the friciton law.
+ RoughChannelSpatialParams(std::shared_ptr<const GridGeometry> gridGeometry)
+ : ParentType(gridGeometry)
+ {
+ gravity_ = getParam<Scalar>("Problem.Gravity");
+ bedSlope_ = getParam<Scalar>("Problem.BedSlope");
+ frictionLawType_ = getParam<std::string>("Problem.FrictionLaw");
+ initFrictionLaw();
+ }
+
+ // This function handles the initialization of the friction law based on the settings
+ // specified in `params.input`.
+ void initFrictionLaw()
+ {
+ if (frictionLawType_ == "Manning")
+ {
+ Scalar manningN = getParam<Scalar>("Problem.ManningN");
+ frictionLaw_ = std::make_unique<FrictionLawManning<VolumeVariables>>(gravity_, manningN);
+ }
+ else if (frictionLawType_ == "Nikuradse")
+ {
+ Scalar ks = getParam<Scalar>("Problem.Ks");
+ frictionLaw_ = std::make_unique<FrictionLawNikuradse<VolumeVariables>>(ks);
+ }
+ else if (frictionLawType_ == "None")
+ {
+ frictionLaw_ = std::make_unique<FrictionLawNoFriction<VolumeVariables>>();
+ }
+ else
+ {
+ std::cout<<"The FrictionLaw in params.input is unknown. Valid entries are `Manning`,"
+ " `Nikuradse` and `None`!"<<std::endl;
+ }
+ }
+
+ // This function returns an object of the friction law class, already initialized with a friction value.
+ const FrictionLaw<VolumeVariables>& frictionLaw(const Element& element,
+ const SubControlVolume& scv) const
+ {
+ return *frictionLaw_;
+ }
+
+ // This function returns the acceleration due to gravity.
+ Scalar gravity(const GlobalPosition& globalPos) const
+ {
+ return gravity_;
+ }
+
+ // Define the bed surface based on the bed slope and the bed level at the inflow (10 m).
+ Scalar bedSurface(const Element& element,
+ const SubControlVolume& scv) const
+ {
+ return 10.0 - element.geometry().center()[0] * bedSlope_;
+ }
+
+// We declare the private variables of the problem.
+private:
+ Scalar gravity_;
+ Scalar bedSlope_;
+ std::string frictionLawType_;
+ std::unique_ptr<FrictionLaw<VolumeVariables>> frictionLaw_;
+}; // end class definition of RoughChannelSpatialParams
+} // end of namespace Dumux.
+```
+
+
+</details>
+
+
+| [:arrow_left: Back to the main documentation](../README.md) | [:arrow_right: Continue with part 2](main.md) |
+|---|---:|
+
diff --git a/examples/shallowwaterfriction/doc/swe_intro.md b/examples/shallowwaterfriction/doc/swe_intro.md
new file mode 100644
index 0000000000..c0e5511287
--- /dev/null
+++ b/examples/shallowwaterfriction/doc/swe_intro.md
@@ -0,0 +1,17 @@
+# Part 1: Implementation of the shallow water flow simulation setup
+
+The shallow water flow setup, including the bottom friction,
+is implemented in the files `properties.hh`,
+`problem.hh` and `spatialparams.hh`. In the first of these files, a new
+type tag is declared for this problem. This allows the specialization
+of DuMu<sup>x</sup> `properties` for this type tag, which can be used to customize compile-time
+settings for the simulation. Two exemplary `properties`, that are mandatory to be
+specialized, are `Problem` and `SpatialParams`. With the first, one sets the
+`Problem` class to be used, in which users can define initial and boundary conditions.
+Similarly, in the `SpatialParams` class one implements the parameter distributions
+(e.g. friction value) that should be used by the model.
+
+The documentation provided in the sequel is structured as follows:
+
+[[_TOC_]]
+
diff --git a/examples/shallowwaterfriction/img/domain.png b/examples/shallowwaterfriction/img/domain.png
deleted file mode 100644
index 27029ab28e1de01c7736fb54be698db508f5777f..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001
literal 18385
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
diff --git a/examples/shallowwaterfriction/img/result.png b/examples/shallowwaterfriction/img/result.png
deleted file mode 100644
index 1ef7c2c9798930cfd4d6b1b8a98b78e0cb718406..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001
literal 35503
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
diff --git a/examples/shallowwaterfriction/img/swe_result.png b/examples/shallowwaterfriction/img/swe_result.png
new file mode 100644
index 0000000000000000000000000000000000000000..0c5c8025ffbf8d476d146920508c563e1cb4a951
GIT binary patch
literal 117570
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
OKZ`ade53zrm+D_$nTC}B
literal 0
HcmV?d00001
diff --git a/examples/shallowwaterfriction/main.cc b/examples/shallowwaterfriction/main.cc
index de91945bb9..21b48ed300 100644
--- a/examples/shallowwaterfriction/main.cc
+++ b/examples/shallowwaterfriction/main.cc
@@ -17,138 +17,168 @@
* along with this program. If not, see <http://www.gnu.org/licenses/>. *
*****************************************************************************/
-// ## The file `main.cc`
+// ## The main file `main.cc`
+// [[content]]
//
-//
-// This is the main file for the shallow water example. Here we can see the programme sequence and how the system is solved using newton's method.
-// ### Includes
+// ### Included header files
+// [[details]] includes
+// [[exclude]]
+// Some generic includes.
#include <config.h>
-
-// Standard header file for C++, to get time and date information.
#include <ctime>
-
-// Standard header file for C++, for in- and output.
#include <iostream>
-
-// Dumux is based on DUNE, the Distributed and Unified Numerics Environment, which provides several grid managers and linear solvers. So we need some includes from that.
+// [[/exclude]]
+//
+// These are DUNE helper classes related to parallel computations, time measurements and file I/O
#include <dune/common/parallel/mpihelper.hh>
#include <dune/common/timer.hh>
#include <dune/grid/io/file/dgfparser/dgfexception.hh>
#include <dune/grid/io/file/vtk.hh>
-// We need the following class to simplify the writing of dumux simulation data to VTK format.
-#include <dumux/io/vtkoutputmodule.hh>
-// In Dumux a property system is used to specify the model. For this, different properties are defined containing type definitions, values and methods. All properties are declared in the file properties.hh.
+// The following headers include functionality related to property definition or retrieval, as well as
+// the retrieval of input parameters specified in the input file or via the command line.
#include <dumux/common/properties.hh>
-// The following file contains the parameter class, which manages the definition of input parameters by a default value, the inputfile or the command line.
#include <dumux/common/parameters.hh>
-// The file dumuxmessage.hh contains the class defining the start and end message of the simulation.
-#include <dumux/common/dumuxmessage.hh>
-#include <dumux/common/defaultusagemessage.hh>
-// The gridmanager constructs a grid from the information in the input or grid file. There is a specification for the different supported grid managers.
-#include <dumux/io/grid/gridmanager.hh>
-// We include the linear solver to be used to solve the linear system
+
+// The following files contains the available linear solver backends, the non linear Newton Solver
+// and the assembler for the linear systems arising from finite volume discretizations
+// (box-scheme, tpfa-approximation, mpfa-approximation).
#include <dumux/linear/amgbackend.hh>
-#include <dumux/linear/linearsolvertraits.hh>
-// We include the nonlinear newtons method
#include <dumux/nonlinear/newtonsolver.hh>
-// Further we include assembler, which assembles the linear systems for finite volume schemes (box-scheme, tpfa-approximation, mpfa-approximation)
#include <dumux/assembly/fvassembler.hh>
-// We include the properties
+
+// The following class provides a convenient way of writing of dumux simulation results to VTK format.
+#include <dumux/io/vtkoutputmodule.hh>
+// The gridmanager constructs a grid from the information in the input or grid file.
+// Many different Dune grid implementations are supported, of which a list can be found
+// in `gridmanager.hh`.
+#include <dumux/io/grid/gridmanager.hh>
+
+// We include the header file specifing the properties of this example
#include "properties.hh"
+// [[/details]]
+//
-// ### Beginning of the main function
+// ### The main function
+// We will now discuss the main program flow implemented within the `main` function.
+// At the beginning of each program using Dune, an instance of `Dune::MPIHelper` has to
+// be created. Moreover, we parse the run-time arguments from the command line and the
+// input file:
+// [[codeblock]]
int main(int argc, char** argv) try
{
using namespace Dumux;
- // We define the type tag for this problem
- using TypeTag = Properties::TTag::RoughChannel;
-
- // We initialize MPI, finalize is done automatically on exit
- const auto& mpiHelper = Dune::MPIHelper::instance(argc, argv);
-
- // We print dumux start message
- if (mpiHelper.rank() == 0)
- DumuxMessage::print(/*firstCall=*/true);
+ // The Dune MPIHelper must be instantiated for each program using Dune
+ Dune::MPIHelper::instance(argc, argv);
// We parse command line arguments and input file
Parameters::init(argc, argv);
+ // [[/codeblock]]
+
+ // We define a convenience alias for the type tag of the problem. The type
+ // tag contains all the properties that are needed to define the model and the problem
+ // setup. Throughout the main file, we will obtain types defined for these type tag
+ // using the property system, i.e. with `GetPropType`.
+ using TypeTag = Properties::TTag::RoughChannel;
- // ### Create the grid
- // A gridmanager tries to create the grid either from a grid file or the input file.
+ // #### Step 1: Create the grid
+ // The `GridManager` class creates the grid from information given in the input file.
+ // This can either be a grid file or, in the case of structured grids, one can specify the coordinates
+ // of the corners of the grid and the number of cells to be used to discretize each spatial direction.
+ //[[codeblock]]
GridManager<GetPropType<TypeTag, Properties::Grid>> gridManager;
gridManager.init();
// We compute on the leaf grid view
const auto& leafGridView = gridManager.grid().leafGridView();
+ //[[/codeblock]]
- // ### Setup and solving of the problem
- // #### Setup
- // We create and initialize the finite volume grid geometry, the problem, the linear system, including the jacobian matrix, the residual and the solution vector and the gridvariables.
- // We need the finite volume geometry to build up the subcontrolvolumes (scv) and subcontrolvolume faces (scvf) for each element of the grid partition.
+ // #### Step 2: Solving the shallow water problem
+ // First, a finite volume grid geometry is constructed from the grid that was created above.
+ // This builds the sub-control volumes (scv) and sub-control volume faces (scvf) for each element
+ // of the grid partition.
using GridGeometry = GetPropType<TypeTag, Properties::GridGeometry>;
auto gridGeometry = std::make_shared<GridGeometry>(leafGridView);
gridGeometry->update();
- // In the problem, we define the boundary and initial conditions.
+ // We now instantiate the problem, in which we define the boundary and initial conditions.
using Problem = GetPropType<TypeTag, Properties::Problem>;
auto problem = std::make_shared<Problem>(gridGeometry);
- // We initialize the solution vector
+ // We initialize the solution vector. The shallow water problem is transient,
+ // therefore the initial solution defined in the problem is applied to the
+ // solution vector. On the basis of this solution, we initialize then the grid variables.
using SolutionVector = GetPropType<TypeTag, Properties::SolutionVector>;
SolutionVector x(gridGeometry->numDofs());
problem->applyInitialSolution(x);
auto xOld = x;
- // And then use the solutionvector to intialize the gridVariables.
using GridVariables = GetPropType<TypeTag, Properties::GridVariables>;
auto gridVariables = std::make_shared<GridVariables>(problem, gridGeometry);
gridVariables->init(x);
- // We get some time loop parameters from the input file.
- using Scalar = GetPropType<TypeTag, Properties::Scalar>;
+ // Let us now instantiate the time loop. Therefore, we read in some time loop parameters from the input file.
+ // The parameter `tEnd` defines the duration of the simulation, `dt` the initial time step size and `maxDt` the maximal time step size.
+ // Moreover, we define the end of the simulation `tEnd` as check point in the time loop at which we will write the solution to vtk files.
+ // [[codeblock]]
+ using Scalar = GetPropType<TypeTag, Properties::Scalar>; // type for scalar values
const auto tEnd = getParam<Scalar>("TimeLoop.TEnd");
const auto maxDt = getParam<Scalar>("TimeLoop.MaxTimeStepSize");
auto dt = getParam<Scalar>("TimeLoop.DtInitial");
- // We intialize the vtk output module. Each model has a predefined model specific output with relevant parameters for that model.
- using IOFields = GetPropType<TypeTag, Properties::IOFields>;
- VtkOutputModule<GridVariables, SolutionVector> vtkWriter(*gridVariables,x, problem->name());
- // We add the analytical solution ("exactWaterDepth" and "exactVelocityX") to the predefined specific output.
- vtkWriter.addField(problem->getExactWaterDepth(), "exactWaterDepth");
- vtkWriter.addField(problem->getExactVelocityX(), "exactVelocityX");
- // We calculate the analytic solution.
- problem->analyticalSolution();
- IOFields::initOutputModule(vtkWriter);
- vtkWriter.write(0.0);
-
// We instantiate time loop.
- auto timeLoop = std::make_shared<CheckPointTimeLoop<Scalar>>(0, dt, tEnd);
+ auto timeLoop = std::make_shared<CheckPointTimeLoop<Scalar>>(0.0, dt, tEnd);
timeLoop->setMaxTimeStepSize(maxDt);
+ timeLoop->setCheckPoint(tEnd);
+ // [[/codeblock]]
- //we set the assembler with the time loop because we have an instationary problem.
+ // We initialize the assembler with a time loop for the transient problem.
+ // Within the time loop, we will use this assembler in each time step to assemble the linear system.
using Assembler = FVAssembler<TypeTag, DiffMethod::numeric>;
auto assembler = std::make_shared<Assembler>(problem, gridGeometry, gridVariables, timeLoop);
- // We set the linear solver.
+ // We initialize the linear solver.
using LinearSolver = AMGBiCGSTABBackend<LinearSolverTraits<GridGeometry>>;
auto linearSolver = std::make_shared<LinearSolver>(leafGridView, gridGeometry->dofMapper());
- // Additionaly, we set the non-linear solver.
+ // We initialize the non-linear solver.
using NewtonSolver = Dumux::NewtonSolver<Assembler, LinearSolver>;
NewtonSolver nonLinearSolver(assembler, linearSolver);
- // We set some check point at the end of the time loop. The check point is used to trigger the vtk output.
- timeLoop->setCheckPoint(tEnd);
+ // The following lines of code initialize the vtk output module, add the velocity output facility
+ // and write out the initial solution. At each checkpoint, we will use the output module to write
+ // the solution of a time step into a corresponding vtk file.
+ // [[codeblock]]
+ VtkOutputModule<GridVariables, SolutionVector> vtkWriter(*gridVariables,x, problem->name());
+
+ // add model-specific output fields to the writer
+ using IOFields = GetPropType<TypeTag, Properties::IOFields>;
+ IOFields::initOutputModule(vtkWriter);
- // We start the time loop.
+ // We add the analytical solution ("exactWaterDepth" and "exactVelocityX") to the predefined specific output.
+ vtkWriter.addField(problem->getExactWaterDepth(), "exactWaterDepth");
+ vtkWriter.addField(problem->getExactVelocityX(), "exactVelocityX");
+
+ // We calculate the analytic solution.
+ problem->analyticalSolution();
+
+ // write initial solution (including the above calculated analytical solution.
+ vtkWriter.write(0.0);
+ // [[/codeblock]]
+
+ // ##### The time loop
+ // We start the time loop and solve a new time step as long as `tEnd` is not reached. In every time step,
+ // the problem is assembled and solved, the solution is updated, and when a checkpoint is reached the solution
+ // is written to a new vtk file. In addition, statistics related to CPU time, the current simulation time
+ // and the time step sizes used is printed to the terminal.
+ // [[codeblock]]
timeLoop->start(); do
{
- // We start to calculate the new solution of that time step. First we define the old solution as the solution of the previous time step for storage evaluations.
+ // First we define the old solution as the solution of the previous time step for storage evaluations.
assembler->setPreviousSolution(xOld);
- // We solve the non-linear system with time step control.
+ // We solve the non-linear system with time step control, using Newthon's method.
nonLinearSolver.solve(x,*timeLoop);
// We make the new solution the old solution.
@@ -170,25 +200,26 @@ int main(int argc, char** argv) try
} while (!timeLoop->finished());
+ // [[/codeblock]]
+ // The following piece of code prints a final status report of the time loop
+ // before the program is terminated.
timeLoop->finalize(leafGridView.comm());
- // ### Final Output
- // We print dumux end message.
- if (mpiHelper.rank() == 0)
- {
- Parameters::print();
- DumuxMessage::print(/*firstCall=*/false);
- }
-
return 0;
-} // end main
-
+}
+// #### Exception handling
+// In this part of the main file we catch and print possible exceptions that could
+// occur during the simulation.
+// [[details]] exception handler
+// [[codeblock]]
+// errors related to run-time parameters
catch (const Dumux::ParameterException &e)
{
std::cerr << std::endl << e << " ---> Abort!" << std::endl;
return 1;
}
+// errors related to the parsing of Dune grid files
catch (const Dune::DGFException & e)
{
std::cerr << "DGF exception thrown (" << e <<
@@ -198,13 +229,18 @@ catch (const Dune::DGFException & e)
<< " ---> Abort!" << std::endl;
return 2;
}
+// generic error handling with Dune::Exception
catch (const Dune::Exception &e)
{
std::cerr << "Dune reported error: " << e << " ---> Abort!" << std::endl;
return 3;
}
+// other exceptions
catch (...)
{
std::cerr << "Unknown exception thrown! ---> Abort!" << std::endl;
return 4;
}
+// [[/codeblock]]
+// [[/details]]
+// [[/content]]
diff --git a/examples/shallowwaterfriction/problem.hh b/examples/shallowwaterfriction/problem.hh
index 12bfbe3261..caa370dee7 100644
--- a/examples/shallowwaterfriction/problem.hh
+++ b/examples/shallowwaterfriction/problem.hh
@@ -20,21 +20,34 @@
#ifndef DUMUX_EXAMPLE_SHALLOWWATER_FRICTION_PROBLEM_HH
#define DUMUX_EXAMPLE_SHALLOWWATER_FRICTION_PROBLEM_HH
-// ## The file `problem.hh`
-// We start with includes
-#include <dumux/common/parameters.hh>
-#include <dumux/common/properties.hh>
+// ## The problem file (`problem.hh`)
+//
+// This file contains the __problem class__ which defines the initial and boundary
+// conditions for the shallow water flow simulation with bottom friction.
+// In addition, the analytical solution is defined here.
+//
+// [[content]]
+//
+// ### Include files
+//
+// The first include we need here is the `ShallowWaterProblem` class, the base
+// class from which we will derive.
#include <dumux/freeflow/shallowwater/problem.hh>
+// In addition, we need the boundaryflux header, which handels the flux over
+// the model boundaries.
#include <dumux/freeflow/shallowwater/boundaryfluxes.hh>
+// ### The problem class
// We enter the problem class where all necessary boundary conditions and initial conditions are set for our simulation.
+// In addition the analytical solution of the problem is calculated.
// As this is a shallow water problem, we inherit from the basic ShallowWaterProblem.
+// [[codeblock]]
namespace Dumux {
template <class TypeTag>
class RoughChannelProblem : public ShallowWaterProblem<TypeTag>
{
- // We use convenient declarations that we derive from the property system.
+ // A few convenience aliases used throughout this class.
using ParentType = ShallowWaterProblem<TypeTag>;
using PrimaryVariables = GetPropType<TypeTag, Properties::PrimaryVariables>;
using BoundaryTypes = GetPropType<TypeTag, Properties::BoundaryTypes>;
@@ -45,7 +58,6 @@ class RoughChannelProblem : public ShallowWaterProblem<TypeTag>
using ElementVolumeVariables = typename GetPropType<TypeTag, Properties::GridVolumeVariables>::LocalView;
using GridVariables = GetPropType<TypeTag, Properties::GridVariables>;
using ElementFluxVariablesCache = typename GridVariables::GridFluxVariablesCache::LocalView;
- using VolumeVariables = typename ElementVolumeVariables::VolumeVariables;
using FVElementGeometry = typename GetPropType<TypeTag, Properties::GridGeometry>::LocalView;
using SubControlVolumeFace = typename FVElementGeometry::SubControlVolumeFace;
using GridView = typename GetPropType<TypeTag, Properties::GridGeometry>::GridView;
@@ -60,31 +72,24 @@ public:
: ParentType(gridGeometry)
{
// We read the parameters from the params.input file.
- name_ = getParam<std::string>("Problem.Name");
constManningN_ = getParam<Scalar>("Problem.ManningN");
bedSlope_ = getParam<Scalar>("Problem.BedSlope");
discharge_ = getParam<Scalar>("Problem.Discharge");
// We calculate the outflow boundary condition using the Gauckler-Manning-Strickler formula.
- hBoundary_ = this->gauklerManningStrickler(discharge_,constManningN_,bedSlope_);
+ hBoundary_ = this->gaucklerManningStrickler(discharge_,constManningN_,bedSlope_);
// We initialize the analytic solution to a verctor of the appropriate size filled with zeros.
exactWaterDepth_.resize(gridGeometry->numDofs(), 0.0);
exactVelocityX_.resize(gridGeometry->numDofs(), 0.0);
}
+ // [[/codeblock]]
- // Get the analytical water depth
- const std::vector<Scalar>& getExactWaterDepth()
- {
- return exactWaterDepth_;
- }
-
- // Get the analytical velocity
- const std::vector<Scalar>& getExactVelocityX()
- {
- return exactVelocityX_;
- }
+ // #### Analytical Solution
+ //
+ // The analytical solution is calculated using the equation of Gauckler, Manning and Strickler.
+ // [[codeblock]]
- // Get the water depth with Gauckler-Manning-Strickler
- Scalar gauklerManningStrickler(Scalar discharge, Scalar manningN, Scalar bedSlope)
+ // Equation of Gauckler, Manning and Strickler
+ Scalar gaucklerManningStrickler(Scalar discharge, Scalar manningN, Scalar bedSlope)
{
using std::pow;
using std::abs;
@@ -93,14 +98,14 @@ public:
return pow(abs(discharge)*manningN/sqrt(bedSlope), 0.6);
}
- // Get the analytical solution
+ // Calculate the analytical solution
void analyticalSolution()
{
using std::abs;
for (const auto& element : elements(this->gridGeometry().gridView()))
{
- const Scalar h = this->gauklerManningStrickler(discharge_,constManningN_,bedSlope_);
+ const Scalar h = this->gaucklerManningStrickler(discharge_,constManningN_,bedSlope_);
const Scalar u = abs(discharge_)/h;
const auto eIdx = this->gridGeometry().elementMapper().index(element);
@@ -109,61 +114,87 @@ public:
}
}
- // Get the problem name. It is used as a prefix for files generated by the simulation.
- const std::string& name() const
+ // Getter function for the analytical solution of the water depth
+ const std::vector<Scalar>& getExactWaterDepth()
{
- return name_;
+ return exactWaterDepth_;
}
- // Get the source term.
- NumEqVector source(const Element& element,
- const FVElementGeometry& fvGeometry,
- const ElementVolumeVariables& elemVolVars,
- const SubControlVolume &scv) const
+ // Getter function for the analytical solution of the velocity in x-direction
+ const std::vector<Scalar>& getExactVelocityX()
+ {
+ return exactVelocityX_;
+ }
+ // [[/codeblock]]
+
+ // #### Bottom friction
+ //
+ // The bottom friction is a source term and therefore handled by the `source` function.
+ // [[codeblock]]
+ NumEqVector source(const Element& element,
+ const FVElementGeometry& fvGeometry,
+ const ElementVolumeVariables& elemVolVars,
+ const SubControlVolume &scv) const
{
NumEqVector source (0.0);
- // In this model the bottom friction is the only source.
+ // Since the bed slope source term is handels within the flux computation,
+ // in this model the bottom friction is the only source term.
source += bottomFrictionSource(element, fvGeometry, elemVolVars, scv);
return source;
}
-
- // Get the source term due to bottom friction.
- NumEqVector bottomFrictionSource(const Element& element,
+ // [[/codeblock]]
+
+ // The calculation of the source term due to bottom friction needs the bottom shear stess.
+ // This is the force per area, which works between the flow and the channel bed
+ // (1D vector with two entries) and is calculated within the `FrictionLaw` class.
+ // The bottom friction causes a loss of momentum. Thus the first entry of the `bottomFrictionSource`,
+ // which is related to the mass balance equation is zero.
+ // The second entry of the `bottomFricitonSource` corresponds to the momentum equation in x-direction
+ // and is therefore equal to the first, the x-component, of the `bottomShearStress`.
+ // Accordingly, the third entry of the `bottomFrictionSource` is equal to the second component of the `bottomShearStress`.
+ // [[codeblock]]
+ NumEqVector bottomFrictionSource(const Element& element,
const FVElementGeometry& fvGeometry,
const ElementVolumeVariables& elemVolVars,
const SubControlVolume &scv) const
- {
+ {
NumEqVector bottomFrictionSource(0.0);
const auto& volVars = elemVolVars[scv];
- // For the calculation of the source term due to bottom friction the two-dimensional bottom shear stess vector is needed. This is the force per area, which works between the flow and the bed. It is calculated within the `FrictionLaw`, which is a spatialParameter. In this model the `FrictionLawManning` is used (see `params.input`).
+ // bottom shear stress vector
Dune::FieldVector<Scalar, 2> bottomShearStress = this->spatialParams().frictionLaw(element, scv).shearStress(volVars);
- // The bottom shear stress causes a pure loss of momentum. Thus the first entry of the `bottomFrictionSource`, which is related to the mass balance equation is zero. The second entry of the `bottomFricitonSource` corresponds to the momentum equation in x-direction and is therefore equal to the first, the x-component, of the `bottomShearStress`. Accordingly the third entry of the `bottomFrictionSource` is equal to the second component of the `bottomShearStress`.
+ // source term due to bottom friction
bottomFrictionSource[0] = 0.0;
bottomFrictionSource[1] = bottomShearStress[0];
bottomFrictionSource[2] = bottomShearStress[1];
return bottomFrictionSource;
- }
+ }
+ // [[/codeblock]]
- // We specify the boundary condition type.
+ // #### Boundary conditions
+ //
+ // We define the __type of all boundary conditions__ as neumann-type,
+ // because we use a weak imposition.
+ // [[codeblock]]
BoundaryTypes boundaryTypesAtPos(const GlobalPosition &globalPos) const
{
BoundaryTypes bcTypes;
- // Since we use a weak imposition all boundary conditions are of Neumann type.
bcTypes.setAllNeumann();
return bcTypes;
}
-
- // We specify the neumann boundary. Due to the weak imposition we calculate the flux at the
- // boundary, with a Rieman solver. For this the state of a virtual cell outside of the boundary
- // is needed (`boundaryStateVariables`), wich is calculated with the Riemann invariants
- // (see Yoon and Kang, Finite Volume Model for Two-Dimensional Shallow Water Flows on Unstructured Grids).
- // The calculation of the Riemann invariants differ depending on the type of the boundary (h, q or no-flow boundary).
+ // [[/codeblock]]
+
+ // In the following function we implement the __Neumann boundary conditions__.
+ // Due to the weak imposition we calculate the flux at the boundary with a Riemann solver.
+ // This needs the state of a virtual cell outside of the boundary (`boundaryStateVariables`),
+ // wich is calculated with the Riemann invariants
+ // (see: Yoon and Kang, "Finite Volume Model for Two-Dimensional Shallow Water Flows on Unstructured Grids").
+ // [[codeblock]]
NeumannFluxes neumann(const Element& element,
const FVElementGeometry& fvGeometry,
const ElementVolumeVariables& elemVolVars,
@@ -178,7 +209,7 @@ public:
const auto gravity = this->spatialParams().gravity(scvf.center());
std::array<Scalar, 3> boundaryStateVariables;
- // Calculate the rieman invariants for imposed discharge at the left side.
+ // Calculate the Riemann invariants for imposed discharge at the left side.
if (scvf.center()[0] < 0.0 + eps_)
{
boundaryStateVariables = ShallowWater::fixedDischargeBoundary(discharge_,
@@ -188,8 +219,8 @@ public:
gravity,
nxy);
}
- // Calculate the rieman invariants for impose water depth at the right side.
- else if (scvf.center()[0] > 100.0 - eps_)
+ // Calculate the Riemann invariants for imposed water depth at the right side.
+ else if (scvf.center()[0] > 500.0 - eps_)
{
boundaryStateVariables = ShallowWater::fixedWaterDepthBoundary(hBoundary_,
insideVolVars.waterDepth(),
@@ -198,14 +229,14 @@ public:
gravity,
nxy);
}
- // Calculate the rieman invarianty for the no-flow boundary.
+ // Calculate the Riemann invariants for the no-flow boundary.
else
{
boundaryStateVariables[0] = insideVolVars.waterDepth();
boundaryStateVariables[1] = -insideVolVars.velocity(0);
boundaryStateVariables[2] = -insideVolVars.velocity(1);
}
- // We calculate the boundary fluxes based on a Riemann problem.
+ // Calculate the boundary fluxes based on a Riemann problem.
auto riemannFlux = ShallowWater::riemannProblem(insideVolVars.waterDepth(),
boundaryStateVariables[0],
insideVolVars.velocity(0),
@@ -223,41 +254,48 @@ public:
return values;
}
-
- // We set the initial conditions. In this example constant initial conditions are used. Therefore the argument `globalPos` is not needed. If you want to impose spatial variable initial conditions, you have to use the `globalPos`.
+ // [[/codeblock]]
+
+ // #### Initial conditions
+ //
+ // We specify the initial conditions for the primary variables (water depth, velocity in y-direction
+ // and velocity in x-direction). In this example constant initial conditions are used. Therefore the
+ //argument `globalPos` is not needed. If you want to impose spatial variable initial conditions,
+ // you have to use the `globalPos` argument.
+ // [[codeblock]]
PrimaryVariables initialAtPos(const GlobalPosition &globalPos) const
{
- PrimaryVariables values(0.0);
+ PrimaryVariables initialValues(0.0);
// We set the initial water depth to one meter.
- values[0] = 1.0;
+ initialValues[0] = 1.0;
// We set the x-component of the initial velocity to zero.
- values[1] = 0.0;
+ initialValues[1] = 0.0;
// We set the y-component of the initial velocity to zero.
- values[2] = 0.0;
-
- return values;
- };
+ initialValues[2] = 0.0;
- // \}
+ return initialValues;
+ }
+ // [[/codeblock]]
+// We declare the private variables of the problem.
+// [[codeblock]]
private:
- // We declare the private variables of the problem. They are initialized in the problems constructor.
- // We declare the variable for the analytic solution.
+ // variables for the analytic solution.
std::vector<Scalar> exactWaterDepth_;
std::vector<Scalar> exactVelocityX_;
- // constant friction value. An analytic solution is only available for const friction. If you want to run the simulation with a non constant friciton value (specified in the spatialParams) you have to remove the analytic solution.
+ // constant friction value (an analytic solution is only available for const friction).
Scalar constManningN_;
- // The constant bed slope.
+ // The constant channel bed slope.
Scalar bedSlope_;
// The water depth at the outflow boundary.
Scalar hBoundary_;
// The discharge at the inflow boundary.
Scalar discharge_;
- // eps is used as a small value for the definition of the boundry conditions
+ // We assign a private global variable for the epsilon:
static constexpr Scalar eps_ = 1.0e-6;
- std::string name_;
-};
+}; // end class definition RoughChannelProblem
} // end namespace Dumux
-
+// [[/codeblock]]
+// [[/content]]
#endif
diff --git a/examples/shallowwaterfriction/properties.hh b/examples/shallowwaterfriction/properties.hh
index d1e87e9aa4..86e03e69c1 100644
--- a/examples/shallowwaterfriction/properties.hh
+++ b/examples/shallowwaterfriction/properties.hh
@@ -20,34 +20,53 @@
#ifndef DUMUX_EXAMPLE_SHALLOWWATER_FRICTION_PROPERTIES_HH
#define DUMUX_EXAMPLE_SHALLOWWATER_FRICTION_PROPERTIES_HH
-// ## The file `properties.hh`
+// ## Compile-time settings (`properties.hh`)
//
-// The header includes will be mentioned in the text below.
-// <details><summary>Click to show the header includes</summary>
+// In this file, the type tag used for the shallow water flow simulation is defined,
+// for which we then specialize `properties` to the needs of the desired setup.
+//
+// [[content]]
+//
+// ### Includes
+// [[details]] include files
+//
+// The `ShallowWater` type tag specializes most of the `properties` required for a
+// shallow water flow simulation in DuMu<sup>x</sup>. We will use this in the following to inherit the
+// respective properties and subsequently specialize those `properties` for our
+// type tag, which we want to modify or for which no meaningful default can be set.
+#include <dumux/freeflow/shallowwater/model.hh>
+
+// We want to use `YaspGrid`, an implementation of the dune grid interface for structured grids:
#include <dune/grid/yaspgrid.hh>
-#include <dumux/common/properties.hh>
+// In this example, we want to discretize the equations with the cell centered finite volume
+// scheme using two-point-flux approximation:
#include <dumux/discretization/cctpfa.hh>
-#include <dumux/freeflow/shallowwater/model.hh>
-#include "spatialparams.hh"
+// We include the problem and spatial parameters headers used for this simulation.
#include "problem.hh"
-// </details>
+#include "spatialparams.hh"
+// [[/details]]
//
-
-// Let's define the properties for our simulation
-namespace Dumux::Properties {
-
-// First, a so-called TypeTag is created. Properties are traits specialized for this TypeTag (a simple `struct`).
-// The properties of two other TypeTags are inherited by adding the alias `InheritsFrom`.
+// ### Type tag definition
+//
+// First, a so-called type tag is created. Properties are traits specialized for this type tag (a simple `struct`).
+// The properties of two other type tags are inherited by adding the alias `InheritsFrom`.
// Here, properties from the shallow water model (`TTag::ShallowWater`) and the
// cell-centered finite volume scheme with two-point-flux approximation (`TTag::CCTpfaModel`)
-// are inherited. These other TypeTag definitions can be found in the included
+// are inherited. These other type tag definitions can be found in the included
// headers `dumux/freeflow/shallowwater/model.hh` and `dumux/discretization/cctpfa.hh`.
+// [[codeblock]]
+// We enter the namespace Dumux::Properties in order to import the entire Dumux namespace for general use:
+namespace Dumux::Properties {
+
namespace TTag {
struct RoughChannel { using InheritsFrom = std::tuple<ShallowWater, CCTpfaModel>; };
}
+// [[/codeblock]]
+// ### Property specializations
+//
// We use a structured Cartesian grid with tensor product structure.
// `Dune::YaspGrid` (Yet Another Structure Parallel Grid) is defined in `dune/grid/yaspgrid.hh`
// in the Dune module `dune-grid`.
@@ -55,7 +74,7 @@ template<class TypeTag>
struct Grid<TypeTag, TTag::RoughChannel>
{ using type = Dune::YaspGrid<2, Dune::TensorProductCoordinates<GetPropType<TypeTag, Properties::Scalar>, 2> >; };
-// Next, we specialize the properties `Problem` and `SpatialParams` for our new TypeTag and
+// Next, we specialize the properties `Problem` and `SpatialParams` for our new type tag and
// set the type to our problem and spatial parameter classes implemented
// in `problem.hh` and `spatialparams.hh`.
// [[codeblock]]
@@ -83,5 +102,5 @@ struct EnableGridGeometryCache<TypeTag, TTag::RoughChannel>
{ static constexpr bool value = true; };
} // end namespace Dumux::Properties
-
+// [[/content]]
#endif
diff --git a/examples/shallowwaterfriction/spatialparams.hh b/examples/shallowwaterfriction/spatialparams.hh
index 1638ce5c31..68f188781d 100644
--- a/examples/shallowwaterfriction/spatialparams.hh
+++ b/examples/shallowwaterfriction/spatialparams.hh
@@ -20,28 +20,40 @@
#ifndef DUMUX_ROUGH_CHANNEL_SPATIAL_PARAMETERS_HH
#define DUMUX_ROUGH_CHANNEL_SPATIAL_PARAMETERS_HH
-// ## The file `spatialparams.hh`
+// ## Parameter distributions (`spatialparams.hh`)
//
+// This file contains the __spatial parameters class__ which defines the
+// the friction law, including it's friction parameter, the acceleration
+// due to gravity and the altitude of the channel bed surface. In this example only the bed
+// surface has a non constant distribution.
//
-// We include the basic spatial parameters for finite volumes file from which we will inherit
+// [[content]]
+//
+// ### Include files
+// We include the basic spatial parameters file for finite volumes, from which we will inherit.
#include <dumux/material/spatialparams/fv.hh>
-// The parameters header is needed to retrieve run-time parameters.
-#include <dumux/common/parameters.hh>
-// We include all friction laws, between we can choose for the calculation of the bottom friction source.
+// We include all friction laws.
#include <dumux/material/fluidmatrixinteractions/frictionlaws/frictionlaw.hh>
#include <dumux/material/fluidmatrixinteractions/frictionlaws/manning.hh>
#include <dumux/material/fluidmatrixinteractions/frictionlaws/nikuradse.hh>
+#include <dumux/material/fluidmatrixinteractions/frictionlaws/nofriction.hh>
-// We enter the namespace Dumux. All Dumux functions and classes are in a namespace Dumux, to make sure they don`t clash with symbols from other libraries you may want to use in conjunction with Dumux.
+// ### The spatial parameters class
+//
+// In the `RoughChannelSpatialParams` class, we define all functions needed to describe
+// the rough channel for the shallow water problem.
+// We inherit from the `FVSpatialParams` class, which is the base class
+// for spatial parameters in the context of
+// applications using finite volume discretization schemes.
+// [[codeblock]]
namespace Dumux {
-//In the RoughChannelSpatialParams class we define all functions needed to describe the spatial distributed parameters.
template<class GridGeometry, class Scalar, class VolumeVariables>
class RoughChannelSpatialParams
: public FVSpatialParams<GridGeometry, Scalar,
RoughChannelSpatialParams<GridGeometry, Scalar, VolumeVariables>>
{
- // We introduce using declarations that are derived from the property system which we need in this class
+ // This convenience aliases will be used throughout this class
using ThisType = RoughChannelSpatialParams<GridGeometry, Scalar, VolumeVariables>;
using ParentType = FVSpatialParams<GridGeometry, Scalar, ThisType>;
using GridView = typename GridGeometry::GridView;
@@ -49,9 +61,14 @@ class RoughChannelSpatialParams
using SubControlVolume = typename FVElementGeometry::SubControlVolume;
using Element = typename GridView::template Codim<0>::Entity;
using GlobalPosition = typename Element::Geometry::GlobalCoordinate;
+ // [[/codeblock]]
+ // In the following, the properties of the the rough channel are set. Namely, these are
+ // the friction law, including it's friction parameter, the acceleration
+ // due to gravity and the altitude of the channel bed surface.
+ // [[codeblock]]
public:
- // In the constructor be read some values from the `params.input` and initialize the friciton law.
+ // In the constructor we read some values from the `params.input` and initialize the friciton law.
RoughChannelSpatialParams(std::shared_ptr<const GridGeometry> gridGeometry)
: ParentType(gridGeometry)
{
@@ -61,7 +78,8 @@ public:
initFrictionLaw();
}
- // We initialize the friction law based on the law specified in `params.input`.
+ // This function handles the initialization of the friction law based on the settings
+ // specified in `params.input`.
void initFrictionLaw()
{
if (frictionLawType_ == "Manning")
@@ -74,45 +92,45 @@ public:
Scalar ks = getParam<Scalar>("Problem.Ks");
frictionLaw_ = std::make_unique<FrictionLawNikuradse<VolumeVariables>>(ks);
}
+ else if (frictionLawType_ == "None")
+ {
+ frictionLaw_ = std::make_unique<FrictionLawNoFriction<VolumeVariables>>();
+ }
else
{
- std::cout<<"The FrictionLaw in params.input is unknown. Valid entries are `Manning` and `Nikuradse`!"<<std::endl;
+ std::cout<<"The FrictionLaw in params.input is unknown. Valid entries are `Manning`,"
+ " `Nikuradse` and `None`!"<<std::endl;
}
}
- // Use this function, if you want to vary the value for the gravity.
- Scalar gravity(const GlobalPosition& globalPos) const
+ // This function returns an object of the friction law class, already initialized with a friction value.
+ const FrictionLaw<VolumeVariables>& frictionLaw(const Element& element,
+ const SubControlVolume& scv) const
{
- return gravity_;
+ return *frictionLaw_;
}
- // Use this function for a constant gravity.
- Scalar gravity() const
+ // This function returns the acceleration due to gravity.
+ Scalar gravity(const GlobalPosition& globalPos) const
{
return gravity_;
}
- // This function returns an object of the friction law class, which is initialized with the appropriate friction values. If you want to use different friciton values or laws, you have to use a vector of unique_ptr for `frictionLaw_` and pick the right friction law instances via the `element` argument.
- const FrictionLaw<VolumeVariables>& frictionLaw(const Element& element,
- const SubControlVolume& scv) const
- {
- return *frictionLaw_;
- }
-
- // Define the bed surface based on the `bedSlope_`.
+ // Define the bed surface based on the bed slope and the bed level at the inflow (10 m).
Scalar bedSurface(const Element& element,
const SubControlVolume& scv) const
{
return 10.0 - element.geometry().center()[0] * bedSlope_;
}
+// We declare the private variables of the problem.
private:
Scalar gravity_;
Scalar bedSlope_;
std::string frictionLawType_;
std::unique_ptr<FrictionLaw<VolumeVariables>> frictionLaw_;
-};
-// end of namespace Dumux.
-}
-
+}; // end class definition of RoughChannelSpatialParams
+} // end of namespace Dumux.
+// [[/codeblock]]
+// [[/content]]
#endif
--
GitLab