From 3cfaf18a14acb59672882d75b209072f938c5d7b Mon Sep 17 00:00:00 2001
From: Martin Utz
Date: Mon, 11 Apr 2022 15:05:20 +0200
Subject: [PATCH 1/2] [Shallowwater] Update model description

dumux/freeflow/shallowwater/model.hh  42 +++++++++++++++++
1 file changed, 25 insertions(+), 17 deletions()
diff git a/dumux/freeflow/shallowwater/model.hh b/dumux/freeflow/shallowwater/model.hh
index db984d34c9..85d702fb9c 100644
 a/dumux/freeflow/shallowwater/model.hh
+++ b/dumux/freeflow/shallowwater/model.hh
@@ 21,40 +21,48 @@
* \ingroup ShallowWaterModel
*
* \brief A twodimensional shallow water equations model
 * The twodimensonal shallow water equations (SWEs) can be written as
+ *
+ * The twodimensional shallow water equations (SWEs) can be written as:
*
* \f[
* \frac{\partial \mathbf{U}}{\partial t} +
 * \frac{\partial \mathbf{F}}{\partial x} + \\
+ * \frac{\partial \mathbf{F}}{\partial x} +
* \frac{\partial \mathbf{G}}{\partial y}  \mathbf{S_b}  \mathbf{S_f} = 0
* \f]
*
 * with U, F, G are defined as
+ * The first equation is the water balance equation (volume balance) and the following two equations balance the
+ * momentum in xdirection and ydirection. \f$ \mathbf{U} \f$, \f$ \mathbf{F} \f$ and \f$ \mathbf{G} \f$ are defined as:
*
* \f[
* \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}
+ * \mathbf{F} = \begin{bmatrix} hu \\ hu^2 + \frac{1}{2} gh^2  \nu\frac{\partial uh}{\partial x} \\ huv  \nu\frac{\partial vh}{\partial x} \end{bmatrix},
+ * \mathbf{G} = \begin{bmatrix} hv \\ huv  \nu\frac{\partial uh}{\partial y} \\ hv^2 + \frac{1}{2} gh^2  \nu\frac{\partial vh}{\partial y} \end{bmatrix}
* \f]
*
 * Z is the bedSurface, h the water depth, u the velocity in
 * xdirection and v the velocity in ydirection, g is the constant of gravity.
+ * \f$ h \f$ is the water depth (in \f$ m \f$), \f$ u \f$ the velocity in
+ * xdirection and \f$ v \f$ the velocity in ydirection (in \f$ ms^{1} \f$). \f$ g \f$ is the constant of gravity (in \f$ ms^{2} \f$).
+ * \f$ \nu \f$ is the effective turbulent viscosity (in \f$ m^2s^{1} \f$).
+ * By default the shallow water model neglects the viscous terms, but they can be enabled by setting the parameter `ShallowWater.EnableViscousFlux = true`.
*
 * The source terms for the bed friction S_b and bed slope
 * S_f are given as
+ * The source terms for bed slope \f$ \mathbf{S_b} \f$ and bottom friction \f$ \mathbf{S_f} \f$
+ * are given as:
* \f[
* \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 \\ \frac{\tau_{x}}{\rho} \\ \frac{\tau_{y}}{\rho}\end{bmatrix}.
* \f]
*
 * A cellcentered finte volume method (cctpfa) is applied to solve the SWEs
 * in combination with a fullyimplicit time discretization. For large time
 * step sizes (CFL > 1) this can lead to a strong semearing of sharp fronts.
 * This can be seen in the movement of short traveling waves (e.g. dam break
 * waves). Nevertheless the fully implicit time discretization showes often
 * no drawbacks in cases where no short waves are considered. Thus the model
 * can be a good choice for simulating flow in rivers and channels, where the
+ * \f$ z \f$ is the bed surface (in \f$ m \f$), \f$ \tau_{x} \f$ and \f$ \tau_{y} \f$ the bottom shear stress (in \f$ Nm^{2} \f$) in x an ydirection, respectively.
+ * \f$ \rho \f$ is the water density (in \f$ kgm^{3} \f$). The bed slope source term \f$ \mathbf{S_b} \f$ is covered by the hydrostatic reconstruction
+ * within the flux computation and must therefore not be treated separately within the computation of the source terms.
+ * On the contrary, the bottom friction source term must be implemented in the problem (have a look at the shallow water example).
+ *
+ * When using a fully implicit Euler time discretization, note the following:
+ * Large time step sizes (CFL > 1) can lead to a strong smearing of sharp fronts.
+ * This can be seen in the movement of fast traveling waves (e.g. dam break
+ * waves). Nevertheless, the fully implicit time discretization shows
+ * good results in cases where slowly moving waves are considered. Thus, the model
+ * is a good choice for simulating flow in rivers and channels, where the
* fullyimplicit discretization allows large time steps and reduces the
* overall computation time drastically.
*

GitLab
From 77b185a1523ba0b4c09ce2992b30f051b18d059c Mon Sep 17 00:00:00 2001
From: Martin Utz
Date: Tue, 19 Apr 2022 10:36:16 +0200
Subject: [PATCH 2/2] [Shallowwater] Update example description

examples/shallowwaterfriction/README.md  21 ++++++++++
1 file changed, 10 insertions(+), 11 deletions()
diff git a/examples/shallowwaterfriction/README.md b/examples/shallowwaterfriction/README.md
index 2b98d77446..e5327b6a8b 100644
 a/examples/shallowwaterfriction/README.md
+++ b/examples/shallowwaterfriction/README.md
@@ 73,29 +73,27 @@ where $`\mathbf{U}`$, $`\mathbf{F}`$ and $`\mathbf{G}`$ defined as
$`h`$ the water depth, $`u`$ the velocity in xdirection and $`v`$ the velocity in ydirection,
$`g`$ is the constant of gravity.
The source terms for the bed slope $`\mathbf{S_b}`$ and friction
+The source terms for bed slope $`\mathbf{S_b}`$ and bottom 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 \\ \frac{\tau_x}{\rho} \\ \frac{\tau_y}{\rho} \end{bmatrix}.
```
with the bedSurface $`z`$. $`S_{fx}`$ and $`S_{fy}`$ are the bed shear stess
components in x and ydirection, which are calculated by Manning's law.
+with the bed surface $`z`$. $`\rho`$ is the water density. $`\tau_x`$ and $`\tau_y`$ are the bottom shear stress components in x an ydirection, respectively.
+The bottom shear stress is calculated by Manning's law.
### Mannings law
The empirical Manning model specifies the bed shear stress by the following equations:
+The empirical Manning model specifies the bottom shear stress by the following equation
```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)
+\mathbf{\tau} = \frac{n^2 g\rho}{h^{1/3}} \sqrt{u^2 + v^2} \begin{bmatrix} u \\ v \end{bmatrix}
```
$`n`$ is Manning's friction value and $`R_{hy}`$ is the hydraulic radius,
which is assumed to be equal to the water depth $`h`$.
+$`n`$ is Manning's friction value.
+In addition, the dumux shallow water model extends the water depth by a roughness hight to limit the friction for small water depth.
### Analytical solution
Since normal flow conditions are assumed, the analytic solution is calculated using the equation
@@ 105,7 +103,8 @@ of Gauckler, Manning and Strickler:
v_m = n^{1} R_{hy}^{2/3} I_s^{1/2}
```
Where the mean velocity $`v_m`$ is given as
+$`R_{hy}`$ is the hydraulic radius, which is assumed to be equal to the water depth $`h`$.
+The mean velocity $`v_m`$ is given as
```math
v_m = \frac{q}{h}

GitLab