From 1c1d33f57bba0ad844f53d4f39db4e896e32dab7 Mon Sep 17 00:00:00 2001
From: Dorchies David <david.dorchies@inrae.fr>
Date: Thu, 12 Jan 2023 13:45:40 +0100
Subject: [PATCH] docs(MacroRugo): update to Cassan et al (2023)

Refs #591
---
 docs/en/calculators/pam/macrorugo_theorie.md | 40 ++++++++++----------
 docs/fr/calculators/pam/macrorugo_theorie.md | 40 ++++++++++----------
 jalhyd_branch                                |  2 +-
 3 files changed, 43 insertions(+), 39 deletions(-)

diff --git a/docs/en/calculators/pam/macrorugo_theorie.md b/docs/en/calculators/pam/macrorugo_theorie.md
index ba7b9845e..4820a231a 100644
--- a/docs/en/calculators/pam/macrorugo_theorie.md
+++ b/docs/en/calculators/pam/macrorugo_theorie.md
@@ -1,12 +1,12 @@
 # Calculation of the flow rate of a rock-ramp pass
 
-The calculation of the flow rate of a rock-ramp pass corresponds to the implementation of the algorithm and the equations present in Cassan et al. (2016)[^1].
+The calculation of the flow rate of a rock-ramp pass corresponds to the implementation of the algorithm and the equations present in Cassan et al. (2016)[^Cassan2016].
 
 ## General calculation principle
 
 ![Organigramme de la méthode de calcul](cassan2016_flow_chart_design_method.png)
 
-*After Cassan et al., 2016[^1]*
+*After Cassan et al., 2016[^Cassan2016]*
 
 There are three possibilities:
 
@@ -60,7 +60,7 @@ $$\beta = \sqrt{(k / \alpha_t)(C_d C k / D)/(1 - \sigma C)}$$
 
 with
 
-$$C_d = C_{x} f_{h_*}(h_*)$$
+$$C_d = C_{d0} f_{h_*}(h_*)$$
 
 and \(\alpha_t\) obtained by solving the following equation:
 
@@ -116,7 +116,7 @@ $$V = \frac{Q}{B \times h}$$
 
 ### Average speed between blocks *V<sub>g</sub>*
 
-From Eq. 1 Cassan et al (2016)[^1] and Eq. 1 Cassan et al (2014)[^2]:
+From Eq. 1 Cassan et al (2016)[^Cassan2016] and Eq. 1 Cassan et al (2014)[^Cassan2014]:
 
 $$V_g = \frac{V}{1 - \sqrt{(a_x/a_y)C}}$$
 
@@ -124,7 +124,7 @@ $$V_g = \frac{V}{1 - \sqrt{(a_x/a_y)C}}$$
 ### Drag coefficient of a single block *C<sub>d0</sub>*
 
 \(C_{d0}\) is the drag coefficient of a block considering a single block
-infinitely high with \(F << 1\) (Cassan et al, 2014[^2]).
+infinitely high with \(F << 1\) (Cassan et al, 2014[^Cassan2014]).
 
 
 | Block shape | Cylinder | "Rounded face" shape | Square-based parallelepiped | "Flat face" shape |
@@ -132,7 +132,7 @@ infinitely high with \(F << 1\) (Cassan et al, 2014[^2]).
 | | ![Cylinder](bloc_cylindre.png) | !["Rounded face" shape](bloc_face_arrondie.png) | ![Square-based parallelepiped](bloc_base_carree.png) | !["Flat face" shape](bloc_face_plate.png) |
 | Value of \(C_{d0}\) | 1.0 | 1.2-1.3 | 2.0 | 2.2 |
 
-When establishing the statistical formulae for the 2006 technical guide (Larinier et al. 2006[^4]), the definition of the block shapes to be tested was based on the use of quarry blocks with neither completely round nor completely square faces.
+When establishing the statistical formulae for the 2006 technical guide (Larinier et al. 2006[^Larinier2006]), the definition of the block shapes to be tested was based on the use of quarry blocks with neither completely round nor completely square faces.
 The so-called "rounded face" shape was thus not completely cylindrical, but had a trapezoidal bottom face (seen in plan).
 Similarly, the "flat face" shape was not square in cross-section, but also had a trapezoidal bottom face.
 These differences in shape between the "rounded face" and a true cylinder on the one hand, and the "flat face" and a true parallelepiped with a square base on the other hand, result in slight differences between them in the shape coefficients \(C_{d0}\).
@@ -140,13 +140,13 @@ These differences in shape between the "rounded face" and a true cylinder on the
 
 ### Block shape coefficient *σ*
 
-Cassan et al. (2014)[^2], et Cassan et al. (2016)[^1] define \(\sigma\) as the ratio between the
+Cassan et al. (2014)[^Cassan2014], et Cassan et al. (2016)[^Cassan2016] define \(\sigma\) as the ratio between the
 block area in the \(x,y\) plane and \(D^2\).
 For the cylindrical form of the blocks, \(\sigma\) is equal to \(\pi / 4\) and for a square block, \(\sigma = 1\).
 
 ### Ratio between the average speed downstream of a block and the maximum speed *r*
 
-The values of (\r\) depends on the block shapes (Cassan et al., 2014[^2] et Tran et al. 2016 [^3]):
+The values of (\r\) depends on the block shapes (Cassan et al., 2014[^Cassan2014] et Tran et al. 2016 [^Tran2016]):
 
 - round : \(r_Q=1.1\)
 - "rounded face" shape : \(r=1.2\)
@@ -163,7 +163,7 @@ $$F = \frac{V_g}{\sqrt{gh}}$$
 
 ### Froude-related drag coefficient correction function *f<sub>F</sub>(F)*
 
-If \(F < 1\) (Eq. 19, Cassan et al., 2014[^2]):
+If \(F < 1\) (Eq. 19, Cassan et al., 2014[^Cassan2014]):
 
 $$f_F(F) = \min \left( \frac{r}{1- \frac{F_{g}^{2}}{4}}, \frac{1}{F^{\frac{2}{3}}} \right)^2$$
 
@@ -171,16 +171,15 @@ otherwise \(f_F(F) = 1\) because a torrential flow upstream of the blocks is the
 
 ### Maximum speed *u<sub>max</sub>*
 
-According to equation 19 of Cassan et al, 2014[^2] :
+According to equation 19 of Cassan et al, 2014[^Cassan2014] :
 
 $$ u_{max} = V_g \sqrt{f_F(F)} $$
 
 ### Drag coefficient correction function linked to relative depth *f<sub>h\*</sub>(h<sub>\*</sub>)*
 
-The equation used in Cassiopeia differs slightly from equation 20 of Cassan et al. 2014[^2] and equation 6 of Cassan et al. 2016[^1].
-This formula is a fit to the experimental measurements on circular blocks used in Cassan et al. 2016[^1]:
+The equation used in Cassiopeia is the last one proposed by Cassan et al. 2023[^Cassan2023]:
 
-$$ f_{h_*}(h_*) = (1 + 1 / h_*^{2}) $$
+$$ f_{h_*}(h_*) = 1 + \dfrac{1}{f_F(F) h_*} $$
 
 ### Coefficient of friction of the bed *C<inf>f</inf>*
 
@@ -192,7 +191,7 @@ with
 
 $$Re = u_0 \times h / \nu$$
 
-Else (Eq. 3, Cassan et al., 2016 d'après Rice et al., 1998[^5])
+Else (Eq. 3, Cassan et al., 2016 d'après Rice et al., 1998[^Rice1998])
 
 $$C_f = \frac{2}{(5.1 \mathrm{log} (h/k_s)+6)^2}$$
 
@@ -232,12 +231,15 @@ $$C_f = \frac{2}{(5.1 \mathrm{log} (h/k_s)+6)^2}$$
 - \(z_0\): hydraulic roughness (m)
 - \(\tilde{z}\): dimensionless stand \(\tilde{z} = z / k\)
 
-[^1]: Cassan L, Laurens P. 2016. Design of emergent and submerged rock-ramp fish passes. Knowl. Manag. Aquat. Ecosyst., 417, 45. https://doi.org/10.1051/kmae/2016032
 
-[^2]: Cassan, L., Tien, T.D., Courret, D., Laurens, P., Dartus, D., 2014. Hydraulic Resistance of Emergent Macroroughness at Large Froude Numbers: Design of Nature-Like Fishpasses. Journal of Hydraulic Engineering 140, 04014043. https://doi.org/10.1061/(ASCE)HY.1943-7900.0000910
+[^Cassan2023]: Cassan, L., Miranda, F.C., Laurens, P., 2023. Hydraulic Resistance in Rock-Ramp Fish Passes for Various Shapes of Macroroughness. Journal of Hydraulic Engineering 149, 06022018. https://doi.org/10.1061/JHEND8.HYENG-13096
 
-[^3]: Tran, T.D., Chorda, J., Laurens, P., Cassan, L., 2016. Modelling nature-like fishway flow around unsubmerged obstacles using a 2D shallow water model. Environmental Fluid Mechanics 16, 413–428. https://doi.org/10.1007/s10652-015-9430-3
+[^Cassan2016]: Cassan L, Laurens P. 2016. Design of emergent and submerged rock-ramp fish passes. Knowl. Manag. Aquat. Ecosyst., 417, 45. https://doi.org/10.1051/kmae/2016032
 
-[^4]: Larinier, Michel, Courret, D., Gomes, P., 2006. Guide technique pour la conception des passes à poissons “naturelles,” Rapport GHAPPE RA. Compagnie Nationale du Rhône / Agence de l’Eau Adour Garonne. http://dx.doi.org/10.13140/RG.2.1.1834.8562
+[^Cassan2014]: Cassan, L., Tien, T.D., Courret, D., Laurens, P., Dartus, D., 2014. Hydraulic Resistance of Emergent Macroroughness at Large Froude Numbers: Design of Nature-Like Fishpasses. Journal of Hydraulic Engineering 140, 04014043. https://doi.org/10.1061/(ASCE)HY.1943-7900.0000910
 
-[^5]: Rice C. E., Kadavy K. C., et Robinson K. M., 1998. Roughness of Loose Rock Riprap on Steep Slopes. Journal of Hydraulic Engineering 124, 179‑85. https://doi.org/10.1061/(ASCE)0733-9429(1998)124:2(179)
+[^Tran2016]: Tran, T.D., Chorda, J., Laurens, P., Cassan, L., 2016. Modelling nature-like fishway flow around unsubmerged obstacles using a 2D shallow water model. Environmental Fluid Mechanics 16, 413–428. https://doi.org/10.1007/s10652-015-9430-3
+
+[^Larinier2006]: Larinier, Michel, Courret, D., Gomes, P., 2006. Guide technique pour la conception des passes à poissons “naturelles,” Rapport GHAPPE RA. Compagnie Nationale du Rhône / Agence de l’Eau Adour Garonne. http://dx.doi.org/10.13140/RG.2.1.1834.8562
+
+[^Rice1998]: Rice C. E., Kadavy K. C., et Robinson K. M., 1998. Roughness of Loose Rock Riprap on Steep Slopes. Journal of Hydraulic Engineering 124, 179‑85. https://doi.org/10.1061/(ASCE)0733-9429(1998)124:2(179)
diff --git a/docs/fr/calculators/pam/macrorugo_theorie.md b/docs/fr/calculators/pam/macrorugo_theorie.md
index 4af840788..93f0c5426 100644
--- a/docs/fr/calculators/pam/macrorugo_theorie.md
+++ b/docs/fr/calculators/pam/macrorugo_theorie.md
@@ -1,12 +1,12 @@
 # Calcul du débit d'une passe à macro-rugosité
 
-Le calcul du débit d'une passe à macro-rugosité correspond à l'implémentation de l'algorithme et des équations présentent dans Cassan et al. (2016)[^1].
+Le calcul du débit d'une passe à macro-rugosité correspond à l'implémentation de l'algorithme et des équations présentent dans Cassan et al. (2016)[^Cassan2016].
 
 ## Principe général du calcul
 
 ![Organigramme de la méthode de calcul](cassan2016_flow_chart_design_method.png)
 
-*Extrait de Cassan et al., 2016[^1]*
+*Extrait de Cassan et al., 2016[^Cassan2016]*
 
 Il existe trois cas :
 
@@ -60,7 +60,7 @@ $$\beta = \sqrt{(k / \alpha_t)(C_d C k / D)/(1 - \sigma C)}$$
 
 avec :
 
-$$C_d = C_{x} f_{h_*}(h_*)$$
+$$C_d = C_{d0} f_{h_*}(h_*)$$
 
 et \(\alpha_t\) obtenu à partir de la résolution de l'équation suivante&nbsp;:
 
@@ -116,32 +116,32 @@ $$V = \frac{Q}{B \times h}$$
 
 ### Vitesse moyenne entre les blocs *V<sub>g</sub>*
 
-Eq. 1 Cassan et al (2016)[^1] et Eq. 1 Cassan et al (2014)[^2]:
+Eq. 1 Cassan et al (2016)[^Cassan2016] et Eq. 1 Cassan et al (2014)[^Cassan2014]:
 
 $$V_g = \frac{V}{1 - \sqrt{(a_x/a_y)C}}$$
 
 ### Coefficient de trainée d'un bloc *C<sub>d0</sub>*
 
-\(C_{d0}\) est le coefficient de trainée théorique d'un bloc de hauteur infinie pour un Froude \(F << 1\) (Cassan et al, 2014[^2]).
+\(C_{d0}\) est le coefficient de trainée théorique d'un bloc de hauteur infinie pour un Froude \(F << 1\) (Cassan et al, 2014[^Cassan2014]).
 
 | Forme du bloc | Cylindre | Forme "face arrondie" | Parallélépipède à base carré | Forme "face plate" |
 |:--------------|:--------:|:---------------------:|:----------------------------:|:------------------:|
 | | ![Cylindre](bloc_cylindre.png) | ![Forme "face arrondie"](bloc_face_arrondie.png) | ![Parallélépipède à base carré](bloc_base_carree.png) | ![Forme "face plate"](bloc_face_plate.png) |
 | Valeur de \(C_{d0}\) | 1.0 | 1.2-1.3 | 2.0 | 2.2 |
 
-Lors de l'établissement des formules statistiques du guide technique de 2006 (Larinier et al. 2006[^4]), la définition des formes de blocs à tester a été établie dans la perspective de l'utilisation de blocs de carrière à faces ni complètement rondes, ni complètement carrées.
+Lors de l'établissement des formules statistiques du guide technique de 2006 (Larinier et al. 2006[^Larinier2006]), la définition des formes de blocs à tester a été établie dans la perspective de l'utilisation de blocs de carrière à faces ni complètement rondes, ni complètement carrées.
 La forme dite à « face arrondie » n'était ainsi pas complètement cylindrique, mais présentait une face aval trapézoïdale (vue en plan).
 De même, la forme dite à « face plane » ne présentait pas une section carrée, mais également une face aval trapézoïdale.
 Ces différences de forme entre la « face arrondie » et un véritable cylindre d’une part, et la « face plate » et un véritable parallélépipède à base carrée d’autre part, se traduisent par de légères différences entre celles-ci sur les coefficients de forme \(C_{d0}\).
 
 ### Coefficient de forme de bloc *σ*
 
-Cassan et al. (2014)[^2], et Cassan et al. (2016)[^1] définit \(\sigma\) comme le ratio entre l'aire du bloc vu du dessus et \(D^2\).
+Cassan et al. (2014)[^Cassan2014], et Cassan et al. (2016)[^Cassan2016] définit \(\sigma\) comme le ratio entre l'aire du bloc vu du dessus et \(D^2\).
 On a donc \(\sigma = \pi / 4\) pour un bloc circulaire et \(\sigma = 1\) pour un bloc carré.
 
 ### Rapport entre la vitesse moyenne à l'aval d'un bloc et la vitesse max *r*
 
-Les valeurs de \(r\) dépendent de la forme des blocs (Cassan et al., 2014[^2] et Tran et al. 2016 [^3])&nbsp;:
+Les valeurs de \(r\) dépendent de la forme des blocs (Cassan et al., 2014[^Cassan2014] et Tran et al. 2016 [^Tran2016])&nbsp;:
 
 - rond : \(r=1.1\)
 - face arrondie : \(r=1.2\)
@@ -158,7 +158,7 @@ $$F = \frac{V_g}{\sqrt{gh}}$$
 
 ### Fonction de correction du coefficient de trainée liée au Froude *f<sub>F</sub>(F,r)*
 
-Si \(F < 1\) (Eq. 19, Cassan et al., 2014[^2])&nbsp;:
+Si \(F < 1\) (Eq. 19, Cassan et al., 2014[^Cassan2014])&nbsp;:
 
 $$f_F(F) = \min \left( \frac{r}{1- \frac{F_{g}^{2}}{4}}, \frac{1}{F^{\frac{2}{3}}} \right)^2$$
 
@@ -166,7 +166,7 @@ sinon \(f_F(F) = 1\) car un écoulement torrentiel à l'amont des blocs est thé
 
 ### Vitesse maximale *u<sub>max</sub>*
 
-D'après l'équation 19 de Cassan et al., 2014[^2] :
+D'après l'équation 19 de Cassan et al., 2014[^Cassan2014] :
 
 
 $$ u_{max} = V_g \sqrt{f_F(F)} $$
@@ -174,10 +174,9 @@ $$ u_{max} = V_g \sqrt{f_F(F)} $$
 
 ### Fonction de correction du coefficient de trainée lié à la profondeur relative *f<sub>h\*</sub>(h<sub>\*</sub>)*
 
-L'équation utilisée dans Cassiopée diffère légèrement de l'équation 20 de Cassan et al. 2014[^2] et l'équation 6 de Cassan et al. 2016[^1].
-Cette formule est un ajustement sur les mesures expérimentales sur les blocs circulaires utilisées dans de Cassan et al. 2016[^1]&nbsp;:
+L'équation utilisée dans Cassiopée correspond à la dernière version proposée par Cassan et al. 2023[^Cassan2023]&nbsp;:
 
-$$ f_{h_*}(h_*) = (1 + 1 / h_*^{2}) $$
+$$ f_{h_*}(h_*) = 1 + \dfrac{1}{f_F(F) h_*} $$
 
 ### Coefficient de friction du lit *C<inf>f</inf>*
 
@@ -189,7 +188,7 @@ avec
 
 $$Re = u_0 \times h / \nu$$
 
-Sinon (Eq. 3, Cassan et al., 2016 d'après Rice et al., 1998[^5])
+Sinon (Eq. 3, Cassan et al., 2016 d'après Rice et al., 1998[^Rice1998])
 
 $$C_f = \frac{2}{(5.1 \mathrm{log} (h/k_s)+6)^2}$$
 
@@ -229,12 +228,15 @@ $$C_f = \frac{2}{(5.1 \mathrm{log} (h/k_s)+6)^2}$$
 - \(z_0\)&nbsp;: rugosité hydraulique (m)
 - \(\tilde{z}\)&nbsp;: position verticale adimensionnelle \(\tilde{z} = z / k\)
 
-[^1]: Cassan L, Laurens P. 2016. Design of emergent and submerged rock-ramp fish passes. Knowl. Manag. Aquat. Ecosyst., 417, 45. https://doi.org/10.1051/kmae/2016032
 
-[^2]: Cassan, L., Tien, T.D., Courret, D., Laurens, P., Dartus, D., 2014. Hydraulic Resistance of Emergent Macroroughness at Large Froude Numbers: Design of Nature-Like Fishpasses. Journal of Hydraulic Engineering 140, 04014043. https://doi.org/10.1061/(ASCE)HY.1943-7900.0000910
+[^Cassan2023]: Cassan, L., Miranda, F.C., Laurens, P., 2023. Hydraulic Resistance in Rock-Ramp Fish Passes for Various Shapes of Macroroughness. Journal of Hydraulic Engineering 149, 06022018. https://doi.org/10.1061/JHEND8.HYENG-13096
 
-[^3]: Tran, T.D., Chorda, J., Laurens, P., Cassan, L., 2016. Modelling nature-like fishway flow around unsubmerged obstacles using a 2D shallow water model. Environmental Fluid Mechanics 16, 413–428. https://doi.org/10.1007/s10652-015-9430-3
+[^Cassan2016]: Cassan L, Laurens P. 2016. Design of emergent and submerged rock-ramp fish passes. Knowl. Manag. Aquat. Ecosyst., 417, 45. https://doi.org/10.1051/kmae/2016032
 
-[^4]: Larinier, Michel, Courret, D., Gomes, P., 2006. Guide technique pour la conception des passes à poissons “naturelles,” Rapport GHAPPE RA. Compagnie Nationale du Rhône / Agence de l’Eau Adour Garonne. http://dx.doi.org/10.13140/RG.2.1.1834.8562
+[^Cassan2014]: Cassan, L., Tien, T.D., Courret, D., Laurens, P., Dartus, D., 2014. Hydraulic Resistance of Emergent Macroroughness at Large Froude Numbers: Design of Nature-Like Fishpasses. Journal of Hydraulic Engineering 140, 04014043. https://doi.org/10.1061/(ASCE)HY.1943-7900.0000910
 
-[^5]: Rice C. E., Kadavy K. C., et Robinson K. M., 1998. Roughness of Loose Rock Riprap on Steep Slopes. Journal of Hydraulic Engineering 124, 179‑85. https://doi.org/10.1061/(ASCE)0733-9429(1998)124:2(179)
+[^Tran2016]: Tran, T.D., Chorda, J., Laurens, P., Cassan, L., 2016. Modelling nature-like fishway flow around unsubmerged obstacles using a 2D shallow water model. Environmental Fluid Mechanics 16, 413–428. https://doi.org/10.1007/s10652-015-9430-3
+
+[^Larinier2006]: Larinier, Michel, Courret, D., Gomes, P., 2006. Guide technique pour la conception des passes à poissons “naturelles,” Rapport GHAPPE RA. Compagnie Nationale du Rhône / Agence de l’Eau Adour Garonne. http://dx.doi.org/10.13140/RG.2.1.1834.8562
+
+[^Rice1998]: Rice C. E., Kadavy K. C., et Robinson K. M., 1998. Roughness of Loose Rock Riprap on Steep Slopes. Journal of Hydraulic Engineering 124, 179‑85. https://doi.org/10.1061/(ASCE)0733-9429(1998)124:2(179)
diff --git a/jalhyd_branch b/jalhyd_branch
index d64531f13..1c41109b3 100644
--- a/jalhyd_branch
+++ b/jalhyd_branch
@@ -1 +1 @@
-devel
+336-macrorugo-mise-a-jour-de-la-formule-f-h-a-partir-de-cassan-2023
-- 
GitLab