Merge branch 'devel' into '431-pab-pouvoir-varier-le-debit-d-attrait'

# Conflicts:
#   jalhyd_branch

.vscode/settings.json

@@ -6,5 +6,14 @@
         "latex",
         "plaintext",
         "markdown"
+    ],
+    "cSpell.words": [
+        "Cassan",
+        "DICHO",
+        "MACRORUGO",
+        "fdescribe",
+        "jalhyd",
+        "nghyd",
+        "prms"
     ]
 }
\ No newline at end of file

CHANGELOG.md

 # Historique des versions
 
+### 4.14.2 - 2021-03-25
+
+#### Nouvelles fonctionnalités
+
+* Passe à macro-rugosité: Retour aux formules utilisées dans la v4.13.1 ([jalhyd#297](https://gitlab.irstea.fr/cassiopee/jalhyd/issues/297), [nghyd#493](https://gitlab.irstea.fr/cassiopee/nghyd/issues/493))
+
+#### Correction de bogues
+
+* Passe à macro-rugosité: error de calcul de la vitesse max ([jalhyd#294](https://gitlab.irstea.fr/cassiopee/jalhyd/issues/294))
+* Graphiques: lorsqu'on relance un calcul les axes ne se mettent pas à jour ([nghyd#489](https://gitlab.irstea.fr/cassiopee/nghyd/issues/489))
+
+#### Documentation
+
+* Macrorugo : Documentation de Cd0 avec schéma ([nghyd#492](https://gitlab.irstea.fr/cassiopee/nghyd/issues/492))
+
+### 4.14.1 - 2021-02-17
+
+#### Nouvelles fonctionnalités
+
+* Passe à macro-rugosité: Changer Cd0 pour Cx et ajuster Cd0 aux données expérimentales ([jalhyd#291](https://gitlab.irstea.fr/cassiopee/jalhyd/issues/291))
+
+#### Correction de bogues
+
+* Vérificateur de passe: message erroné pour les passes à macro-rugosités submergées ([jalhyd#292](https://gitlab.irstea.fr/cassiopee/jalhyd/issues/292))
+
+### 4.14.0 - 2021-02-16 (Scomber scombrus)
+
+#### Nouvelles fonctionnalités
+* Passe à macro-rugosité: Mise à jour des formules de calcul ([jalhyd#283](https://gitlab.irstea.fr/cassiopee/jalhyd/issues/283))
+* Passe à macro-rugosité: Ajout de la vitesse moyenne entre les blocs ([jalhyd#285](https://gitlab.irstea.fr/cassiopee/jalhyd/issues/285))
+* Passe à macro-rugosité: Ajout du Strickler équivalent dans les résultats liables à des Strickler ([jalhyd#287](https://gitlab.irstea.fr/cassiopee/jalhyd/issues/287))
+* Passe à macro-rugosité: ajout d'un avertissement pour les concentrations en dehors de l'intervalle validé par les expérimentations ([jalhyd#284](https://gitlab.irstea.fr/cassiopee/jalhyd/issues/284))
+* Vérificateur: Les passes à macro-rugosité submergées sont non franchissables ([jalhyd#290](https://gitlab.irstea.fr/cassiopee/jalhyd/issues/290))
+
+#### Correction de bogues
+
+* Passe à macro-rugosité: Calcul de la puissance dissipée erroné ([jalhyd#282](https://gitlab.irstea.fr/cassiopee/jalhyd/issues/282))
+*  Crash au chargement d'un module contenant une parenthèse dans son nom ([nghyd#487](https://gitlab.irstea.fr/cassiopee/nghyd/issues/487))
+* Electron: l'icône de l'application n'est plus reconnue ([nghyd#485](https://gitlab.irstea.fr/cassiopee/nghyd/issues/485))
+
+#### Documentation
+
+* Documentation du solveur multi-module et des modules de calcul mathématiques ([nghyd#433](https://gitlab.irstea.fr/cassiopee/nghyd/issues/433))
+* Macrorugo : documenter le coefficient de forme Cd0 ([nghyd#477](https://gitlab.irstea.fr/cassiopee/nghyd/issues/477))
+* MacroRugo: erreur de formule de correction de Cd dans la documentation ([nghyd#488](https://gitlab.irstea.fr/cassiopee/nghyd/issues/488))
+* Documentation du module de calcul de la cote amont / aval d'un bief ([nghyd#490](https://gitlab.irstea.fr/cassiopee/nghyd/issues/490))
+
 ### 4.13.1 - 2020-10-02
 
 #### Correction de bogues
 
 * PreBarrage: Distribution des débits erronée sur exemple simple ([jalhyd#279](https://gitlab.irstea.fr/cassiopee/jalhyd/issues/279))
-* PreBarrage: rreur de calcul sur Z2 > Z1 initiale ([jalhyd#280](https://gitlab.irstea.fr/cassiopee/jalhyd/issues/280))
+* PreBarrage: erreur de calcul sur Z2 > Z1 initiale ([jalhyd#280](https://gitlab.irstea.fr/cassiopee/jalhyd/issues/280))
 * Prebarrage : avec Chrome (et electron) le schéma est mal rendu ([nghyd#482](https://gitlab.irstea.fr/cassiopee/nghyd/issues/482))
 
 ### 4.13.0 - 2020-09-24 (Michel Larinier)

docs/en/calculators/hsl/cote_amont_aval.md

+# Upstream / downstream elevations of a reach
+
+This module is based on the equations of the [backwater curves module](courbe_remous.md) and is used to calculate the following:
+
+- The water elevation upstream of a reach of a fluvial backwater curve;
+- The water elevation downstream of a reach of a torrential backwater curve;
+- The flow that connects the upstream and downstream water elevations of a fluvial or torrential backwater curve.
+
+The regime chosen on the type of water line determines whether the calculation is made from downstream to upstream (fluvial regime) and from upstream to downstream (torrential regime).
+
+This calculation module is particularly useful for calculating the water line of a series of hydraulic structures or reaches (see the typical example "Flow of a channel with structures").

docs/en/calculators/maths/operators.md

+# Operators and trigonometric functions
+
+The basic mathematical operators and functions provided by Cassiopeia make it possible above all to facilitate the link between the results of one calculation module and the input into another in the case of a sequence of calculations between several modules. The provided example "Weir jet length" shows the use of the "Linear function" module.
+
+<div style="position: relative"><a id="fonction-affine" style="position: absolute; top: -60px;"></a></div>
+## Linear function
+
+The linear function module solves the equation of a line:
+
+$$ y = a x + b $$
+
+Three parameters must be entered and the module calculates the missing parameter.
+
+<div style="position: relative"><a id="somme-et-produit-de-puissances" style="position: absolute; top: -60px;"></a></div>
+## Sum and product of powers
+
+This module allows to write an equation summing powers in the form \(a x ^ n\) with \(a\), \(x\), and \(n\) of real numbers.
+
+In the case of a sum the equation solved by the module is written:
+
+$$ y = \sum_{i=1}^{k} a_i x_i ^ {n_i} $$
+
+In the case of a product the equation solved by the module is written:
+
+$$ y = \prod_{i=1}^{k} a_i x_i ^ {n_i} $$
+
+All parameters must be entered except the last one which is the value calculated in the equation.
+
+<div style="position: relative"><a id="fonction-trigonometrique" style="position: absolute; top: -60px;"></a></div>
+## Trigonometric function
+
+This module allows to calculate the value of a trigonometric function or its inverse.
+
+The equation solved by this module is written:
+
+$$ y = f(x) $$
+
+With \(f\), a trigonometric function and \(x\) an angle in degrees or radian.
+
+The "Operation" parameter allows to choose the operator among the available functions: cos, sin, tan, cosh, sinh and tanh. The "Unit" parameter is used to choose between degree and radian.

docs/en/calculators/maths/solver.md

+# Multi-module solver
+
+The multi-module solver allows to calculate the value of an input parameter of a module depending on a calculation chain made up of several modules for which a target value for an output calculated parameter is sought.
+
+The diagram below shows the example of a calculation chain comprising two modules. The module `x` takes the parameter `Input x` and calculates the parameter `Output x`. The `y` module takes the `Input y` parameter and calculates the `Output y` parameter. The `Input y` parameter is linked to the `Output x` parameter. The problem to be solved by the solver is to get the value of the `Input x` to obtain a target value in `Output y`.
+
+<div class="mermaid">
+    graph LR
+    Ix([Input x])
+    x[Module x]
+    Ox([Output x / Input y])
+    y[Module y]
+    Oy([Output y])
+    Ix --> x
+    x --> Ox
+    Ox --> y
+    y --> Oy
+    Oy -..->|Input x for a target value Output y ?| Ix
+</div>
+
+To solve this problem, the characteristics of the target parameter must be defined which include:
+
+- The module and its calculated parameter (here the module `y` calculating `Output y`);
+- The target result which can be the parameter calculated by the module or one of its complementary results (Here `Output y`);
+- The desired target value.
+
+It is also necessary to define the characteristics of the searched parameter:
+
+- The searched parameter is to be chosen from the list of input parameters of the modules of the session (Here the `Input x` parameter of the `x` module);
+- An initial value of this parameter to start the calculation.
+
+The initial value chosen must be close enough to the solution because there is no guarantee that the function resulting from the sequence of calculations is continuous and monotonous.
+
+Examples of the use of the multi-module solver are given in the example sessions "Channel flow with structures" and "Critical slope of a channel". The notes of these sessions describe the sequence of the modules and the use of the solver.

docs/en/calculators/pam/concentration.md

 # Blocks concentration
 
-This module makes it possible to calculate the concentration of uniformly distributed blocks in a rock-ramp fish pass.
+This module makes it possible to calculate the concentration of uniformly distributed blocks in a [rock-ramp fish pass](./macrorugo.md).
 
 It allows to calculate one of the following values:
 
@@ -11,7 +11,25 @@ It allows to calculate one of the following values:
 
 ## Formula
 
-The formula is detailed in the [rock-ramp fish pass](./macrorugo.md) documentation.
+![Schematic of a regular arrangement of rockfill and notations](pam_schema_enrochement_regulier.png)
+
+*Excerpt from Larinier et al., 2006[^1]*
+
+[^1]: Larinier, Michel, Courret, D., Gomes, P., 2006. Technical guide for the design of "natural" fish passes, GHAPPE RA Report. Compagnie Nationale du Rhône / Adour Garonne Water Agency. http://dx.doi.org/10.13140/RG.2.1.1834.8562
+
+The spacing between the blocks is then calculated with the following formula:
+
+$$ax = ay = \frac{D}{\sqrt{C}}$$
+
+With :
+
+- \(ax\) and \(ay\) respectively the longitudinal and lateral distances between the centres of the blocks (m);
+- the width of the blocks facing the flow (m);
+- the concentration of the blocks (-).
+
+The number of blocks \(N\) for a pass of width \(B\) is then obtained with the equation:
+
+$$ N = B / ax $$
 
 ## Harmonization
 

docs/en/calculators/pam/macrorugo.md

@@ -24,8 +24,4 @@ It requires the following values to be entered:
 - The background roughness (m);
 - The width of the blocks \(D\) facing the flow (m);
 - The useful height of the blocks \(k\) (m);
-- The shape parameter of the blocks (1 for round, 2 for square)
-
-The spacing between the blocks is then calculated with the following formula:
-
-$$ax = ay = \frac{D}{\sqrt{C}}$$
+- The drag coefficient of a single block (1 for round, 2 for square).

docs/en/calculators/pam/macrorugo_theorie.md

 # 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 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>*.
+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].
 
 ## General calculation principle
 
+![Organigramme de la méthode de calcul](cassan2016_flow_chart_design_method.png)
+
+*After Cassan et al., 2016[^1]*
+
 There are three possibilities:
 
 - the submerged case when \(h \ge 1.1 \times k\)
@@ -55,7 +58,9 @@ with
 
 $$\beta = \sqrt{(k / \alpha_t)(C_d C k / D)/(1 - \sigma C)}$$
 
-with \(\sigma = 1\) for \(C_{d0} = 2\) (square blocks), \(\sigma = \pi/4\) otherwise (circular blocks)
+with
+
+$$C_d = C_{x} f_{h_*}(h_*)$$
 
 and \(\alpha_t\) obtained by solving the following equation:
 
@@ -93,13 +98,11 @@ $$Q_{sup} = \frac{u_*}{\kappa} \left( (h - d) \left( \ln \left( \frac{h-d}{z_0}
 
 The calculation of the flow rate is done by successive iterations which consist in finding the flow rate value allowing to obtain the equality between the flow velocity \(V\) and the average velocity of the bed given by the equilibrium of the friction forces (bottom + drag) with gravity:
 
-$$u_0 = \sqrt{\frac{2 g S D (1 - \sigma C)}{C_d C (1 + N)}}$$
+$$u_0 = \sqrt{\frac{2 g S D (1 - \sigma C)}{C_d f_F(F) C (1 + N)}}$$
 
 with
 
-$$C_d = C_{d0} (1 + 0.4 / h_*^2) f_F(F)$$
-
-$$N = \frac{\alpha C_f}{C_d C h_*}$$
+$$N = \frac{\alpha C_f}{C_d f_F(F) C h_*}$$
 
 with
 
@@ -107,29 +110,77 @@ $$\alpha = 1 - (a_y / a_x \times C)$$
 
 ## Formulas used
 
-### Throughput speed *V*
+### Bulk velocity *V*
 
 $$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]:
+
 $$V_g = \frac{V}{1 - \sqrt{(a_x/a_y)C}}$$
 
+<div style="position: relative"><a id="coefficient-de-trainee-dun-bloc-cd0" style="position: absolute; top: -60px;"></a></div>
+### 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]).
+
+
+| Block shape | Cylinder | "Rounded face" shape | Square-based parallelepiped | "Flat face" shape |
+|:------------|:--------:|:--------------------:|:-----------------------:|:--------------------:|
+| | ![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.
+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}\).
+
+
+### Block shape coefficient *σ*
+
+Cassan et al. (2014)[^2], et Cassan et al. (2016)[^1] 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]):
+
+- round : \(r_Q=1.1\)
+- "rounded face" shape : \(r=1.2\)
+- square-based parallelepiped : \(r=1.5\)
+- "flat face" shape : \(r=1.6\)
+
+Cassiopée implements a formula depending on \(C{d0}\):
+
+$$ r = 0.4 C_{d0} + 0.7 $$
+
 ### Froude *F*
 
 $$F = \frac{V_g}{\sqrt{gh}}$$
 
 ### Froude-related drag coefficient correction function *f<sub>F</sub>(F)*
 
-If \(F < 1.3\) (Eq. 5, Cassan et al., 2016)
+If \(F < 1\) (Eq. 19, Cassan et al., 2014[^2]):
 
-$$f_F(F) = \mathrm{min} \left( \frac{0.4 C_{d0} + 0.7}{1- (F^2 / 4)}, \frac{1}{F^{\frac{2}{3}}} \right)^2$$
+$$f_F(F) = \min \left( \frac{r}{1- \frac{F_{g}^{2}}{4}}, \frac{1}{F^{\frac{2}{3}}} \right)^2$$
 
-else
+otherwise \(f_F(F) = 1\) because a torrential flow upstream of the blocks is theoretically impossible because of the hydraulic jump caused by the downstream block.
 
-$$f_F(F) = F^{\frac{-4}{3}}$$
+### Maximum speed *u<sub>max</sub>*
 
-(The distinction is only numerical because \(1- (F^2 / 4)\) is not defined for \(F > 2\))
+According to equation 19 of Cassan et al, 2014[^2] :
+
+$$ 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]:
+
+$$ f_{h_*}(h_*) = (1 + 1 / h_*^{2}) $$
 
 ### Coefficient of friction of the bed *C<inf>f</inf>*
 
@@ -180,3 +231,7 @@ $$C_f = \frac{2}{(5.1 \mathrm{log} (h/k_s)+6)^2}$$
 - \(z\): vertical position (m)
 - \(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
+
+[^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

docs/fr/calculators/hsl/cote_amont_aval.md

+# Cotes amont / aval d'un bief
+
+Ce module basé sur les équations du [module de calcul des courbes de remous](courbe_remous.md) permet de calculer :
+
+- La cote de l'eau à l'amont d'un bief d'une courbe de remous fluviale 
+- La cote de l'eau à l'aval d'un bief d'une courbe de remous torrentielle 
+- Le débit permettant de relié les cotes de l'eau amont et aval d'une courbe de remous fluviale ou torrentielle.
+
+Le régime choisi sur le type de ligne d'eau détermine si le calcul s'effectue de l'aval vers l'amont (régime fluvial) et de l'amont vers l'aval (régime torrentiel).
+
+Ce module de calcul est particulièrement utile pour calculer la ligne d'eau d'un enchaînement de ouvrages hydrauliques ou de biefs (Voir l'exemple type "Débit d'un chenal avec ouvrages").
+

docs/fr/calculators/maths/operators.md

+# Opérateurs et fonctions trigonométriques
+
+Les opérateurs et fonctions mathématiques basiques pourvus par Cassiopée permettent avant tout de faciliter le lien entre les résultats d'un module de calcul et l'entrée dans autre dans le cas d'un enchaînement de calcul entre plusieurs modules. L'exemple fourni "Longueur de jet d'un déversoir" montre des utilisations du module "Fonction affine".
+
+## Fonction affine
+
+Le module fonction affine résout l'équation de droite :
+
+$$ y = a x + b $$
+
+Trois paramètres doivent être saisis et le module calcule le paramètre manquant.
+
+## Somme et produit de puissances
+
+Ce module permet d'écrire une équation sommant des puissances sous la forme \(a x ^ n\) avec \(a\), \(x\), et \(n\) des réels.
+
+Dans le cas d'une somme l'équation résolue par le module s'écrit :
+
+$$ y = \sum_{i=1}^{k} a_i x_i ^ {n_i}$$
+
+Dans le cas d'un produit l'équation résolue par le module s'écrit :
+
+$$ y = \prod_{i=1}^{k} a_i x_i ^ {n_i}$$
+
+Tous les paramètres doivent être saisis à l'exception du dernier qui est la valeur calculée dans l'équation.
+
+## Fonction trigonométrique
+
+Ce module permet de calculer la valeur d'une fonction trigonométrique ou son inverse.
+
+L'équation résolue par ce module s'écrit :
+
+$$ y = f(x) $$
+
+Avec \(f\), une fonction trigonométrique et \(x\) un angle en degré ou radian.
+
+Le paramètre "Opération" permet de choisir l'opérateur parmi les fonctions disponibles sont : cos, sin, tan, cosh, sinh et tanh. Le paramètre "Unité" permet de choisir entre degré et radian.

docs/fr/calculators/maths/solver.md

+# Solveur multimodule
+
+Le solveur multimodule permet de calculer la valeur d'un paramètre d'entrée d'un module dépendant d'une chaine de calcul constituée de plusieurs modules pour laquelle on cherche à atteindre une valeur cible pour un paramètre calculé en sortie.
+
+Le schéma ci-dessous reprend l'exemple d'une chaîne de calcul comprenant deux modules. Le module `x` prend entrée le paramètre `Input x` et calcule le paramètre `Output x`. Le module `y` prend entrée le paramètre `Input y` et calcule le paramètre `Output y`. Le paramètre `Input y` est lié au paramètre `Output x`. Le problème à résoudre par le solveur est d'obtenir la valeur de l'`Input x` permettant d'obtenir une valeur cible en `Output y`.
+
+<div class="mermaid">
+    graph LR
+    Ix([Input x])
+    x[Module x]
+    Ox([Output x / Input y])
+    y[Module y]
+    Oy([Output y])
+    Ix --> x
+    x --> Ox
+    Ox --> y
+    y --> Oy
+    Oy -..->|Input x pour une valeur cible Output y ?| Ix
+</div>
+
+Pour résoudre ce problème, il faut définir les caractéristiques du paramètre cible qui comprennent&nbsp;:
+
+- Le module et son paramètre calculé (Ici le module `y` calculant `Output y`)&nbsp;;
+- Le résultat ciblé qui peut être le paramètre calculé par le module où un de ces résultats complémentaire (Ici `Output y`)&nbsp;;
+- La valeur cible désirée.
+
+Il faut aussi définir les caractéristiques du paramètre recherché&nbsp;:
+
+- Le paramètre recherché est à choisir parmi la liste des paramètres en entrée des modules de la session (Ici le paramètre `Input x` du module `x`)&nbsp;;
+- Une valeur initiale de ce paramètre pour démarrer le calcul.
+
+La valeur initiale choisie doit être assez proche de la solution car il n'y a aucune garantie que la fonction issue de l'enchaînement des calculs soit continue et monotone.
+
+Des exemples d'utilisation du solveur multimodule sont présents dans les sessions exemples "Débit d'un chenal avec ouvrages" et "Pente critique d'un canal". Les notes de ces sessions décrivent l'enchaînement des modules et l'utilisation du solveur.