From 1cd26d4d2b3ff7b8216b2cd7443b45dce2dc65dd Mon Sep 17 00:00:00 2001
From: Dorchies David <david.dorchies@irstea.fr>
Date: Wed, 13 May 2020 18:17:08 +0200
Subject: [PATCH] doc: Add complete documentation of Cunge80 formula

Fix #403
---
 docs/en/calculators/structures/cunge_80.md   | 53 +++++++++++++++++--
 docs/fr/calculators/structures/cunge_80.md   | 55 ++++++++++++++++++--
 docs/fr/calculators/structures/seuil_noye.md |  2 +-
 3 files changed, 101 insertions(+), 9 deletions(-)

diff --git a/docs/en/calculators/structures/cunge_80.md b/docs/en/calculators/structures/cunge_80.md
index 90abf8eef..97e65be1e 100644
--- a/docs/en/calculators/structures/cunge_80.md
+++ b/docs/en/calculators/structures/cunge_80.md
@@ -1,7 +1,52 @@
-# Cunge 80
+# Cunge 1980 formula
 
-This flow law corresponds to the equations described by Cunge in his book [1], or in more detail in an article by Mahmood and Yevjevich [2]. This law takes into account the different flow conditions: drowned, dewatered, free surface and loaded as well as the equations [Cemagref 1988](cem_88_d.md), but there is no continuity between free surface and loaded flow conditions. This can lead to computational problems in the vicinity of this transition.
+This flow law corresponds to the equations described by Cunge in his book [^1], or in more detail in an article by Mahmood and Yevjevich [^2]. This law is a compilation of the classical laws taking into account the different flow conditions: submerged, free flow, free surface and in charge as well as the equations [CEM88(D) : Weir / Orifice (important sill)](cem_88_d.md) and [CEM88(D) : Weir / Orifice (low sill)](cem_88_v.md). However, contrary to these equations, it does not provide any continuity between free surface and in charge flow conditions. This can lead to design problems in the vicinity of this transition.
 
-*[1] Cunge, Holly, Verwey, 1980, "Practical aspects of computational river hydraulics", Pitman, p. 169 for weirs and p. 266 for gates*.
+This law is suitable for a broad-crested rectangular weir, possibly in combination with a valve. The default discharge coefficient \(C_d = 1\) corresponds to the following discharge coefficients for the classical equations:
 
-*[2] Mahmood K., Yevjevich V., 1975, "Unsteady flow in open channels, Volume 1 and 2", Water resources publications, Fort Collins, USA, 923 p*.
+- \(C_d = 0.385\) for [the free flow weir](seuil_denoye.md).
+- \(C_d = 1\) for [the submerged weir](seuil_noye.md).
+- \(C_d = 1\) for [the submerged gate](vanne_noyee.md).
+- \(C_d = 0.7\) for [the free flow gate](vanne_denoyee.md) but the equation used here is different (see below) especially for an opening \(W\) greater than the critical height.
+
+## Free flow / submerged regime detection
+
+The flow regime is in free flow as long as the downstream water level is below critical height:
+
+$$ (Z_2 - Z_{dv}) < \dfrac{2}{3} (Z_1 - Z_{dv})$$
+
+with \(Z_1\) upstream water elevation, \(Z_2\) downstream water elevation, et \(Z_{dv}\) apron or sill elevation of the hydraulic structure.
+
+## Free flow / in charge flow detection
+
+The water level at the gate when the gate is open is considered here to be equal to:
+
+- the critical height in the case of a free flow regime;
+- the downstream water height in the case of a submerged regime.
+
+The flow becomes in charge when the gate touches the surface of the water at this point.
+
+In free flow, the flow is in charge when:
+
+$$ W \leq \dfrac{2}{3} (Z_1 - Z_{dv})$$
+
+In submerged flow, the condition becomes:
+
+$$ W \leq Z_2$$
+
+## Discharge equations
+
+The free flow gate equation is slightly different than the classical formulation:
+
+$$ Q = C_d L W \sqrt{2g} h_1 \sqrt{(h_1 - W)}$$
+
+For all other flow regimes, used equations here are the following:
+
+|        | Free surface | In charge |
+|--------|---------------|-----------|
+| Free flow | [Free flow weir](seuil_denoye.md) | Voir ci-dessus |
+| Submerged | [Submerged weir](seuil_noye.md) | [Submerged gate](vanne_noyee.md) |
+
+[^1]: Cunge, Holly, Verwey, 1980, "Practical aspects of computational river hydraulics", Pitman, p. 169 for weirs and p. 266 for gates.
+
+[^2]: Mahmood K., Yevjevich V., 1975, "Unsteady flow in open channels, Volume 1 and 2", Water resources publications, Fort Collins, USA, 923 p.
diff --git a/docs/fr/calculators/structures/cunge_80.md b/docs/fr/calculators/structures/cunge_80.md
index 7aac3b9a5..dff523dbb 100644
--- a/docs/fr/calculators/structures/cunge_80.md
+++ b/docs/fr/calculators/structures/cunge_80.md
@@ -1,7 +1,54 @@
-# Cunge 80
+# Formules de Cunge 1980
 
-Cette loi de débit correspond aux équations décrites par Cunge dans son livre [1], ou avec plus de détails dans un article de Mahmood et Yevjevich [2]. Cette loi prend en considération les différentes conditions d’écoulement : noyé, dénoyé, à surface libre et en charge tout comme les équations [Cemagref 1988](cem_88_d.md), mais il n’y a aucune continuité entre les conditions d’écoulement à surface libre et en charge. Cela peut entraîner des problèmes de calcul au voisinage de cette transition.
+Cette loi de débit correspond aux équations décrites par Cunge dans son livre [^1], ou avec plus de détails dans un article de Mahmood et Yevjevich [^2]. Cette loi est une compilation des lois classiques prenant en considération les différentes conditions d’écoulement : noyé, dénoyé, à surface libre et en charge tout comme les équations [CEM88(D) : Déversoir / Orifice (pelle importante)](cem_88_d.md) et [CEM88(V) : Déversoir / Vanne de fond (pelle faible)](cem_88_v.md). Cependant contrairement à ces équations, celle-ci n'asssure aucune continuité entre les conditions d’écoulement à surface libre et en charge. Cela peut entraîner des problèmes de calcul au voisinage de cette transition.
 
-*[1] Cunge, Holly, Verwey, 1980, "Practical aspects of computational river hydraulics", Pitman, p. 169 pour les seuils et p. 266 pour les vannes*
+Cette loi est adaptée pour un seuil rectangulaire à crête épaisse, éventuellement associée à une vanne. Le coefficient de débit par défaut \(C_d = 1\) correspond aux coefficients de débits suivant pour les équations classiques:
 
-*[2] Mahmood K., Yevjevich V., 1975, "Unsteady flow in open channels, Volume 1 and 2", Water resources publications, Fort Collins, USA, 923 p*
+- \(C_d = 0.385\) pour [le seuil dénoyé](seuil_denoye.md).
+- \(C_d = 1\) pour [le seuil noyé](seuil_noye.md).
+- \(C_d = 1\) pour [la vanne noyée](vanne_noyee.md).
+- \(C_d = 0.7\) pour [la vanne dénoyée](vanne_denoyee.md) mais l'équation utilisée ici est différente (voir ci-dessous) notamment pour une ouverture \(W\) supérieure à la hauteur critique.
+
+Une modification du coefficient de débit modifiera proportionnellement les coefficients ci-dessus.
+
+## Détection du régime noyé / dénoyé
+
+Le régime d'écoulement est dénoyé lorsque la hauteur d'eau à l'aval est inférieure à la hauteur critique :
+
+$$ (Z_2 - Z_{dv}) < \dfrac{2}{3} (Z_1 - Z_{dv})$$
+
+avec \(Z_1\) la cote de l'eau à l'amont, \(Z_2\) la cote de l'eau à l'aval, et \(Z_{dv}\) la cote de radier de l'ouvrage.
+
+## Détection de l'écoulement en charge ou à surface libre
+
+On considère ici que la hauteur d'eau au niveau de la vanne quand celle-ci est ouverte est égale à&nbsp;:
+
+- la hauteur critique dans le cas d'un régime dénoyé&nbsp;:
+- la hauteur d'eau aval dans le cas d'un régime noyé.
+
+L'écoulement se met en charge à partir du moment où la pelle de la vanne touche la surface de l'eau à cet endroit.
+
+En régime dénoyé, l'écoulement est donc en charge quand&nbsp;:
+
+$$ W \leq \dfrac{2}{3} (Z_1 - Z_{dv})$$
+
+En régime noyé, la condition devient&nbsp;:
+
+$$ W \leq Z_2$$
+
+## Equations de débit
+
+L'équation de la vanne dénoyée est un peu différente de la formulation classique&nbsp;:
+
+$$ Q = C_d L W \sqrt{2g} h_1 \sqrt{(h_1 - W)}$$
+
+Pour tous les autres régimes d'écoulement les équations utilisées sont les équations classiques suivantes&nbsp;:
+
+|        | Surface libre | En charge |
+|--------|---------------|-----------|
+| Dénoyé | [Seuil dénoyé](seuil_denoye.md) | Voir ci-dessus |
+| Noyé   | [Seuil noyé](seuil_noye.md) | [Vanne noyée](vanne_noyee.md) |
+
+[^1]: Cunge, Holly, Verwey, 1980, "Practical aspects of computational river hydraulics", Pitman, p. 169 pour les seuils et p. 266 pour les vannes.
+
+[^2]: Mahmood K., Yevjevich V., 1975, "Unsteady flow in open channels, Volume 1 and 2", Water resources publications, Fort Collins, USA, 923 p.
diff --git a/docs/fr/calculators/structures/seuil_noye.md b/docs/fr/calculators/structures/seuil_noye.md
index 6e572057e..37fbfa811 100644
--- a/docs/fr/calculators/structures/seuil_noye.md
+++ b/docs/fr/calculators/structures/seuil_noye.md
@@ -1,4 +1,4 @@
-# Formule du déversoir noyé
+# Formule du déversoir noyé (Rajaratnam, 1969)
 
 ![Schéma du seuil noyé](seuil_noye_schema.png)
 
-- 
GitLab