From 6c5d5ee4b769ddac4ea1e004cc470cecf49c52da Mon Sep 17 00:00:00 2001
From: Leopold Stadler <Leopold.Stadler@baw.de>
Date: Mon, 18 Dec 2023 14:48:16 +0100
Subject: [PATCH] add formulas and citation to friction laws

---
 doc/doxygen/dumux.bib                                 |  7 +++++++
 .../frictionlaws/frictionlaw.hh                       |  8 ++++++--
 .../fluidmatrixinteractions/frictionlaws/manning.hh   | 10 +++++++++-
 .../fluidmatrixinteractions/frictionlaws/nikuradse.hh | 11 ++++++++++-
 4 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/doc/doxygen/dumux.bib b/doc/doxygen/dumux.bib
index 7d0d3efe6d..b1fcbdf433 100644
--- a/doc/doxygen/dumux.bib
+++ b/doc/doxygen/dumux.bib
@@ -2093,6 +2093,13 @@ author = {F. Fichot and F. Duval and N. Trégourès and C. Béchaud and M. Quint
   publisher = {Elsevier}
 }
 
+@inproceedings{Lomeland2005,
+  author = {Lomeland, F. and Ebeltoft, E. and Thomas, W.},
+  year = {2005},
+  title = {A New Versatile Relative Permeability Correlation},
+  journal = {Society of Core Analysis Conference Paper SCA2005-32}
+}
+
 @Article{Shomate1954,
   author    = {Shomate, C. Howard},
   title     = {A Method for Evaluating and Correlating Thermodynamic Data},
diff --git a/dumux/material/fluidmatrixinteractions/frictionlaws/frictionlaw.hh b/dumux/material/fluidmatrixinteractions/frictionlaws/frictionlaw.hh
index 047800fd84..652bc2f831 100644
--- a/dumux/material/fluidmatrixinteractions/frictionlaws/frictionlaw.hh
+++ b/dumux/material/fluidmatrixinteractions/frictionlaws/frictionlaw.hh
@@ -22,8 +22,12 @@ namespace Dumux {
  * needed to calculate on the one hand the loss of momentum due to
  * bottom friction and on the other hand the bedload transport rate.
  *
- * A LET mobility model can be used to add an artificial water depth to
- * limit the friction for small water depths.
+ * A LET mobility model of Lomeland et al. 2005 \cite Lomeland2005 can be used to add an
+ * artificial water depth to limit the friction for small water depths.
+ *
+ * \note Instead of calculating the bed friction term \f$\mathbf{S_f}\f$
+ *       of the shallow water equations, the implemented friction laws
+ *       calculate the shear stress \f$\tau_{x}\f$ and \f$\tau_{y}\f$.
  */
 
 template <typename VolumeVariables >
diff --git a/dumux/material/fluidmatrixinteractions/frictionlaws/manning.hh b/dumux/material/fluidmatrixinteractions/frictionlaws/manning.hh
index 782d29f892..3a69df5c4e 100644
--- a/dumux/material/fluidmatrixinteractions/frictionlaws/manning.hh
+++ b/dumux/material/fluidmatrixinteractions/frictionlaws/manning.hh
@@ -20,7 +20,15 @@ namespace Dumux {
  * ### Manning
  *
  * This friction law calculates the stress between the flowing fluid and the bottom,
- * which is called bottom shear stress, using the Manning friction law.
+ * which is called bottom shear stress, using the Manning friction law:
+ *
+ * \f$\tau_{x} = \frac{g}{(\frac{h^{1/6}}{n})^2} u \sqrt{u^2 + v^2}\f$ and
+ * \f$\tau_{y} = \frac{g}{(\frac{h^{1/6}}{n})^2} v \sqrt{u^2 + v^2}\f$
+ *
+ * with the gravity constant \f$\mathrm{g}\f$ in \f$\mathrm{[m/s^2]}\f$, the water depth
+ * \f$\mathrm{h}\f$ in \f$\mathrm{[m]}\f$ and the Manning friction coefficient
+ * \f$\mathrm{n}\f$ in \f$\mathrm{[s/m^{1/3}]}\f$.
+ *
  * The bottom shear stress is needed to calculate on the one hand the loss of
  * momentum due to bottom friction and on the other hand the bedload transport rate.
  *
diff --git a/dumux/material/fluidmatrixinteractions/frictionlaws/nikuradse.hh b/dumux/material/fluidmatrixinteractions/frictionlaws/nikuradse.hh
index 6dfe514691..2fdf42c971 100644
--- a/dumux/material/fluidmatrixinteractions/frictionlaws/nikuradse.hh
+++ b/dumux/material/fluidmatrixinteractions/frictionlaws/nikuradse.hh
@@ -20,12 +20,21 @@ namespace Dumux {
  * ### Nikuradse
  *
  * This friction law calculates the stress between the flowing fluid and the bottom,
- * which is called bottom shear stress, using the Nikuradse friction law.
+ * which is called bottom shear stress, using the Nikuradse \cite Nikuradse1950 friction law
+ *
+ *\f$\tau_{x} = \frac{\kappa^2}{(ln\frac{12h}{ks})^2} u \sqrt{u^2 + v^2}\f$ and
+ *\f$\tau_{y} = \frac{\kappa^2}{(ln\frac{12h}{ks})^2} v \sqrt{u^2 + v^2}\f$
+ *
+ * with the dimensionless Karman's constant \f$\mathrm{\kappa}\f$, the quivalent sand roughness
+ * \f$\mathrm{ks}\f$ in \f$\mathrm{[m]}\f$ and the water depth \f$\mathrm{h}\f$
+ * in \f$\mathrm{[m]}\f$.
+ *
  * The bottom shear stress is needed to calculate on the one hand the loss of
  * momentum due to bottom friction and on the other hand the bedload transport rate.
  *
  * The LET mobility model is used to limit the friction for small water
  * depths if a roughness height > 0.0 is provided (default roughnessHeight = 0.0).
+ *
  */
 
 template <typename VolumeVariables>
-- 
GitLab