From 6fc5ae2b9d47dff2959655c9d3e5ad226a8a7392 Mon Sep 17 00:00:00 2001
From: Timo Koch <timo.koch@iws.uni-stuttgart.de>
Date: Tue, 31 Mar 2020 21:21:34 +0200
Subject: [PATCH] [examples][swe] Improve introduction
---
examples/shallowwaterfriction/.doc_config | 3 +-
examples/shallowwaterfriction/README.md | 70 +++++++++++++-------
examples/shallowwaterfriction/doc/intro.md | 68 +++++++++++++------
examples/shallowwaterfriction/doc/results.md | 2 -
4 files changed, 93 insertions(+), 50 deletions(-)
delete mode 100644 examples/shallowwaterfriction/doc/results.md
diff --git a/examples/shallowwaterfriction/.doc_config b/examples/shallowwaterfriction/.doc_config
index bd7eeb8e44..ae4ff6277f 100644
--- a/examples/shallowwaterfriction/.doc_config
+++ b/examples/shallowwaterfriction/.doc_config
@@ -3,7 +3,6 @@
"doc/intro.md",
"spatialparams.hh",
"problem.hh",
- "main.cc",
- "doc/results.md"
+ "main.cc"
]
}
diff --git a/examples/shallowwaterfriction/README.md b/examples/shallowwaterfriction/README.md
index 22447bce6b..52e9a2d10d 100644
--- a/examples/shallowwaterfriction/README.md
+++ b/examples/shallowwaterfriction/README.md
@@ -5,42 +5,64 @@ 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:
-## Shallow water model
-The shallow water equations (SWEs) are given as:
+* 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:
+
+
+
+## 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
+```
+
+## 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 $U$, $F$ and $G$ defined as
+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.
+$`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 $`S_b`$ and bed slope
-$`S_f`$ are given as
-$`
+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
+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.
.
@@ -49,26 +71,28 @@ 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:
- $` v_m = 1/n * R_{hy}^{2/3} * I_s^{1/2}`$
-
-Where the mean velocity $`v_m`$ is given as
-
-$`v_m = \frac{q}{h}`$
+```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
-$`h = \left(\frac{n*q}{\sqrt{I_s}} \right)^{3/5}`$
+```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*.
+for the simulation are given in the file `params.input`.
+
+# Implementation
## The file `spatialparams.hh`
@@ -1028,5 +1052,3 @@ catch (...)
```
-## Results
-The solution and the analytical result for the problem is shown in .
diff --git a/examples/shallowwaterfriction/doc/intro.md b/examples/shallowwaterfriction/doc/intro.md
index b9cf6c9bf9..e801e67175 100644
--- a/examples/shallowwaterfriction/doc/intro.md
+++ b/examples/shallowwaterfriction/doc/intro.md
@@ -3,42 +3,64 @@ 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:
-## Shallow water model
-The shallow water equations (SWEs) are given as:
+* 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:
+
+
+
+## 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
+```
+
+## 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 $U$, $F$ and $G$ defined as
+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.
-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
-The source terms for the bed friction $`S_b`$ and bed slope
-$`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
+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.
.
@@ -47,23 +69,25 @@ 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:
- $` v_m = 1/n * R_{hy}^{2/3} * I_s^{1/2}`$
-
-Where the mean velocity $`v_m`$ is given as
-
-$`v_m = \frac{q}{h}`$
+```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
-$`h = \left(\frac{n*q}{\sqrt{I_s}} \right)^{3/5}`$
+```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*.
+for the simulation are given in the file `params.input`.
+
+# Implementation
diff --git a/examples/shallowwaterfriction/doc/results.md b/examples/shallowwaterfriction/doc/results.md
deleted file mode 100644
index 8477f8955b..0000000000
--- a/examples/shallowwaterfriction/doc/results.md
+++ /dev/null
@@ -1,2 +0,0 @@
-## Results
-The solution and the analytical result for the problem is shown in .
--
GitLab