Merge branch '674-rugofond-rediger-la-documentation' into 'devel'

Resolve "RugoFond: rédiger la documentation"

Closes #674

See merge request !269

CHANGELOG.md

@@ -4,7 +4,7 @@
 
 #### Nouvelles fonctionnalités
 
-* Ajout de la passe à rugosité de fond ([jalhyd#340](https://forgemia.inra.fr/cassiopee/jalhyd/-/issues/340), [nghyd#657](https://forgemia.inra.fr/cassiopee/nghyd/-/issues/657))
+* Ajout de la passe à rugosités de fond ([jalhyd#340](https://forgemia.inra.fr/cassiopee/jalhyd/-/issues/340), [nghyd#657](https://forgemia.inra.fr/cassiopee/nghyd/-/issues/657))
 
 #### Correction de bogues
 
@@ -15,7 +15,6 @@
 * PAB: latence de saisie sur les grosses PAB ([nghyd#660](https://forgemia.inra.fr/cassiopee/nghyd/-/issues/660))
 * PAB: Erreur d'abscisses sur le profil en long ([nghyd#652](https://forgemia.inra.fr/cassiopee/nghyd/-/issues/652))
 * Courbe de remous - génération section paramétrée : la pente de fond n'est pas copiée ([jalhyd#366](https://forgemia.inra.fr/cassiopee/jalhyd/-/issues/366))
-* Erreur d'itération sur paramètre varié ([jalhyd#362](https://forgemia.inra.fr/cassiopee/jalhyd/-/issues/362)
 
 #### Changements internes
 

docs/en/calculators/pam/rugofond.md

+# Rough bottom ramp
+
+Rough-bottom ramps are generally made up of blocks of relatively uniform dimensions
+arranged one against the other and forming a channel of varying slope.
+
+![Schematic longitudinal section of a rough bottom ramp](rugofond_schema.png)
+
+## Warning about the passability of the structure
+
+In the absence of pools and protruding elements in the flow, these ramps do not
+provide rest areas for upstream migration fishes. Fish therefore have to swim
+over them in one go, generally using their maximum swimming speed. The
+crossability of a rough bottom ramp depends on the flow velocities, the
+water heights above the crest of the embankments, the ‘quality’ of the water
+surface (absence of jumps and slumps making it difficult, if not impossible, for
+fish to swim), and also the length of the ramp that the fish have to cover
+before becoming tired. This is why rough bottom ramps are not
+considered to be crossing devices as such (Larinier et al. 2006). This type of
+device can be useful (1) to make a sill directly passable by species with the
+best swimming ability (salmonids, even shad and lampreys) or (2) to form
+pre-dams combining short ramps with reduced falls and intermediate basins.
+
+## Calculation method
+
+
+### <a name = "apron_type"></a>Inclined apron
+
+The inclined apron is calculated by discretizing the pass width into several
+horizontal aprons whose number is determined by the parameter “Number of
+flow slices".
+
+### Relationship between upstream head on the crest and flow rate
+
+The relationship between the upstream load and the flow is represented by a [formula of
+free weir].(../structures/seuil_denoye.md).
+
+### Relationship between water depth, flow velocity and uniform flow
+
+From the flow supplied or calculated at the inlet, the head of water and the flow velocity in the channel are calculated using [the Manning-Strickler formula
+for a uniform flow](../hsl/regime_uniforme.md) for a rectangular cross section
+equivalent to that of the ramp.
+
+<a name="coef_a"></a>Strickler coefficient is estimated from the
+\(D_{65}\) size of riprap:
+
+$$ K_s = \dfrac{a}{{D_{65}}^{1/6}} $$
+
+With \(a\) the **Strickler correction coefficient** function of how the riprap is placed and the level at which they are joined (Larinier et al., 2006):
+
+ - spilt rock, not grouted&nbsp;: 21
+ - riprap in a compact arrangement without jointing&nbsp;: 15.5
+ - 30% grouting&nbsp;: 16.7
+ - 50% grouting&nbsp;: 18
+
+## References
+
+Larinier, M., J. Chorda, et O. Ferlin. 1995. « Le franchissement des seuils en
+enrochements par les poissons migrateurs : étude expérimentale ». GHAAPPE
+95/05-HYDRE 161. irstea. https://hal.inrae.fr/hal-02575575.
+
+Larinier, Michel, Dominique Courret, et Peggy Gomes. 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.

docs/fr/calculators/pam/rugofond.md

+# Passe à rugosités de fond
+
+Les rampes à rugosités de fond sont généralement constituées de blocs de
+dimensions relativement uniformes disposés les uns contre les autres et formant
+un coursier de pente plus ou moins importante.
+
+![Schéma coupe longitudinale d'une passe à rugosités de fond](rugofond_schema.png)
+
+## Avertissement sur la franchissabilité de l'ouvrage
+
+En l'absence de bassins et d'éléments protubérant dans l'écoulement, ces rampes
+ne présentent pas de zones de repos pour les poissons en montaison. Les poissons
+doivent ainsi les franchir d'une traite en utilisant généralement leur vitesse
+de nage maximale. La franchissabilité d'une rampe à rugosités de fond dépend des
+vitesses de l'écoulement, des hauteurs d'eau au dessus de la crête des
+enrochements, de la "qualité" de la lame d'eau (absence de ressauts et de
+décollement rendant la nage du poisson difficile, sinon impossible), mais aussi
+de la longueur de la rampe que les poissons doivent parcourir avant d'être
+fatigués. C'est pourquoi les rampes à rugosités de fond ne sont pas considérées
+comme des dispositifs de franchissement à proprement parler (Larinier et al.
+2006). Ce type de dispositif peut être utile (1) pour rendre un seuil
+directement franchissable par les espèces aux meilleures capacités de nage
+(salmonidés, voire aloses et lamproies) ou (2) pour former des prébarrages
+associant des rampes courtes avec des chutes réduites et des bassins
+intermédiaires.
+
+## Méthode de calcul
+
+### <a name = "apron_type"></a>Radier incliné
+
+Le radier incliné est calculé en discrétisant la largeur de passe en plusieurs
+radiers horizontaux dont le nombre est déterminé par le paramètre "Nombre de
+tranches d'écoulement".
+
+### Relation entre la charge amont sur la crête et le débit
+
+La relation entre la charge amont et le débit est représenté par une [formule de
+déversoir dénoyé](../structures/seuil_denoye.md).
+
+### Relation entre la hauteur d'eau, la vitesse débitante et le débit en régime uniforme
+
+A partir du débit fourni ou calculé en entrée de passe, la hauteur d'eau et la
+vitesse débitante dans la passe sont calculées avec [la formule de
+Manning-Strickler en régime uniforme](../hsl/regime_uniforme.md) pour une section
+rectangulaire équivalente à celle de la passe.
+
+<a name="coef_a"></a>Le coefficient de Strickler est évalué à partir du
+\(D_{65}\) des enrochements:
+
+$$ K_s = \dfrac{a}{{D_{65}}^{1/6}} $$
+
+Avec \(a\) le **coefficient correcteur du Strickler** fonction du mode de mise en place des enrochements et
+de leur niveau de jointement (Larinier et al., 2006):
+
+ - enrochements déversés, non jointoyés&nbsp;: 21
+ - enrochements disposés de manière compacte sans jointoiement&nbsp;: 15.5
+ - jointoiement à 30%&nbsp;: 16.7
+ - jointoiement à 50%&nbsp;: 18
+
+## Références
+
+Larinier, M., J. Chorda, et O. Ferlin. 1995. « Le franchissement des seuils en
+enrochements par les poissons migrateurs : étude expérimentale ». GHAAPPE
+95/05-HYDRE 161. irstea. https://hal.inrae.fr/hal-02575575.
+
+Larinier, Michel, Dominique Courret, et Peggy Gomes. 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.

docs/mathjax-scrollbar.css → docs/mkdocs-custom.css

@@ -7,3 +7,8 @@
 mjx-math {
     overflow-y: clip;
 }
+
+/* Justified text in documentation content */
+.md-content {
+	text-align: justify;
+}

docs/mkdocs-en.yml

@@ -10,7 +10,7 @@ theme:
     language: 'en'
 use_directory_urls: false
 extra_css:
-    - ../stylesheets/mathjax-scrollbar.css
+    - ../stylesheets/mkdocs-custom.css
 extra_javascript:
     - ../javascripts/mathjax.config.js
     - ../javascripts/mathjax/tex-mml-chtml.js
@@ -77,6 +77,7 @@ nav:
         - calculators/pam/macrorugo_complexe.md
         - calculators/pam/concentration.md
         - calculators/pam/macrorugo_remous.md
+        - calculators/pam/rugofond.md
     - Baffle fishways:
         - Baffle fishway setup: calculators/par/calage.md
         - Baffle fishway simulation: calculators/par/simulation.md

docs/mkdocs-fr.yml

@@ -10,7 +10,7 @@ theme:
     language: 'fr'
 use_directory_urls: false
 extra_css:
-    - ../stylesheets/mathjax-scrollbar.css
+    - ../stylesheets/mkdocs-custom.css
 extra_javascript:
     - ../javascripts/mathjax.config.js
     - ../javascripts/mathjax/tex-mml-chtml.js
@@ -77,6 +77,7 @@ nav:
         - calculators/pam/macrorugo_complexe.md
         - calculators/pam/concentration.md
         - calculators/pam/macrorugo_remous.md
+        - calculators/pam/rugofond.md
     - Passes à ralentisseurs:
         - calculators/par/calage.md
         - calculators/par/simulation.md

scripts/mkdocs-postprocess.js

@@ -20,7 +20,7 @@ fs.ensureDirSync(destPath_JS_MJ + "/fonts/HTML-CSS/TeX/", { recursive: true });
 fs.copySync("node_modules/mathjax/es5/tex-mml-chtml.js", destPath_JS_MJ + "/tex-mml-chtml.js");
 fs.copySync("node_modules/mathjax/es5/output/chtml/fonts", destPath_JS_MJ + "/output/chtml/fonts");
 fs.copySync("docs/mathjax.config.js", destPath_JS + "/mathjax.config.js");
-fs.copySync("docs/mathjax-scrollbar.css", destPath_CSS + "/mathjax-scrollbar.css");
+fs.copySync("docs/mkdocs-custom.css", destPath_CSS + "/mkdocs-custom.css");
 fs.copySync("docs/matomo-tracking.js", destPath_JS + "/matomo-tracking.js");
 fs.copySync("node_modules/mermaid/dist/mermaid.min.js", destPath_JS + "/mermaid.min.js");
 fs.copySync("node_modules/mermaid/dist/mermaid.min.js.map", destPath_JS + "/mermaid.min.js.map");
@@ -30,15 +30,15 @@ Ici, on veut que les ressources copiées ci dessus soit accessibles.
 
 mkdocs-xx.yml :
 extra_css:
-    - ../stylesheets/mathjax-scrollbar.css
+    - ../stylesheets/mkdocs-custom.css
 
 Fichiers HTML générés :
-Par ex src/assets/docs/fr/calculators/maths/solver.html contient <link rel="stylesheet" href="../../stylesheets/mathjax-scrollbar.css">
+Par ex src/assets/docs/fr/calculators/maths/solver.html contient <link rel="stylesheet" href="../../stylesheets/mkdocs-custom.css">
 ce qui fait référence à stylesheets dans src/assets/docs/fr alors qu'on veut référencer stylesheets dans src/assets/docs/
 (le chemin généré dépend de l'emplacement du fichier le contenant).
 
-Le problème, c'est que si on modifie extra_css avec ../../stylesheets/mathjax-scrollbar.css, cela génère la même chose
-(href="../../stylesheets/mathjax-scrollbar.css") vraisemblablement à cause de site_dir (=docs/fr) qui limite les "remontées"
+Le problème, c'est que si on modifie extra_css avec ../../stylesheets/mkdocs-custom.css, cela génère la même chose
+(href="../../stylesheets/mkdocs-custom.css") vraisemblablement à cause de site_dir (=docs/fr) qui limite les "remontées"
 de niveau de répertoire.
 
 La solution est donc de modifier les fichiers HTML générés pour ajouter ../ dans href="...".
@@ -75,8 +75,8 @@ function replaceHtml(base_dir, s1, s2) {
     execBashCmd(cmd);
 }
 
-replaceHtml("src/assets/docs/fr/", "../../stylesheets/mathjax-scrollbar.css", "../../../stylesheets/mathjax-scrollbar.css");
-replaceHtml("src/assets/docs/en/", "../../stylesheets/mathjax-scrollbar.css", "../../../stylesheets/mathjax-scrollbar.css");
+replaceHtml("src/assets/docs/fr/", "../../stylesheets/mkdocs-custom.css", "../../../stylesheets/mkdocs-custom.css");
+replaceHtml("src/assets/docs/en/", "../../stylesheets/mkdocs-custom.css", "../../../stylesheets/mkdocs-custom.css");
 
 replaceHtml("src/assets/docs/fr/", "../../javascripts/mathjax.config.js", "../../../javascripts/mathjax.config.js");
 replaceHtml("src/assets/docs/en/", "../../javascripts/mathjax.config.js", "../../../javascripts/mathjax.config.js");

src/app/calculators/rugofondmultiple/config.json

@@ -7,26 +7,6 @@
             "Z1"
         ]
     },
-    {
-        "id": "fs_geometry_crete",
-        "type": "fieldset",
-        "fields": [
-            "L",
-            "Cd"
-        ]
-    },
-    {
-        "id": "fs_geometry_rampe",
-        "type": "fieldset",
-        "fields": [
-            {
-                "id": "If",
-                "help": "hsl/pente.html"
-            },
-            "d65",
-            "a"
-        ]
-    },
     {
         "id": "fs_type",
         "type": "fieldset",
@@ -34,26 +14,53 @@
             {
                 "id": "select_passtype",
                 "type": "select",
-                "property": "rugofondType"
+                "property": "rugofondType",
+                "help": "pam/rugofond.html#apron_type"
             },
             {
                 "id": "ZRT",
-                "allowEmpty": true
+                "help": "pam/macrorugo.html#rugosite-de-fond"
             },
             {
                 "id": "ZRB",
-                "allowEmpty": true
+                "help": "pam/macrorugo.html#rugosite-de-fond"
             },
             {
                 "id": "NbT",
-                "allowEmpty": true
-            }, 
+                "help": "pam/rugofond.html#apron_type"
+            },
             {
                 "id": "ZF1",
                 "help": "pam/macrorugo.html#rugosite-de-fond"
             }
         ]
     },
+    {
+        "id": "fs_geometry_crete",
+        "type": "fieldset",
+        "fields": [
+            "L",
+            {
+                "id": "Cd",
+                "help": "structures/seuil_denoye.html"
+            }
+        ]
+    },
+    {
+        "id": "fs_geometry_rampe",
+        "type": "fieldset",
+        "fields": [
+            {
+                "id": "If",
+                "help": "hsl/pente.html"
+            },
+            "d65",
+            {
+                "id": "a",
+                "help": "pam/rugofond.html#coef_a"
+            }
+        ]
+    },
     {
         "id": "fs_rugofond",
         "type": "fieldset_template",
@@ -64,5 +71,12 @@
                 "help": "pam/macrorugo.html#rugosite-de-fond"
             }
         ]
+    },
+    {
+        "type": "options",
+        "help": "pam/rugofond.html",
+        "resultsHelp": {
+            "V": "hsl/section_parametree.html#la-vitesse-moyenne-ms"
+        }
     }
 ]

src/app/calculators/rugofondmultiple/en.json

@@ -21,6 +21,6 @@
     "Cd": "Discharge coefficient",
     "d65": "d65",
 
-    "PASSTYPE_0": "Horizontal aprons",
+    "PASSTYPE_0": "Horizontal apron",
     "PASSTYPE_1": "Inclined apron"
 }
\ No newline at end of file

src/app/calculators/rugofondmultiple/fr.json

@@ -16,11 +16,11 @@
     "ZF1": "Cote de fond amont rampe",
     "ZRT": "Cote de fond haut amont",
     "ZRB": "Cote de fond bas amont",
-    "NbT": "Nombre de tranche d'écoulement",
-    "L": "Largeur totale de la rampe", 
+    "NbT": "Nombre de tranches d'écoulement",
+    "L": "Largeur totale de la rampe",
     "Cd": "Coefficient de débit",
     "d65": "d65",
-    
+
     "PASSTYPE_0": "Radier horizontal",
     "PASSTYPE_1": "Radier incliné"
 }
\ No newline at end of file

src/locale/messages.en.json

@@ -517,10 +517,8 @@
     "INFO_PARALLELSTRUCTURE_TITRE_COURT": "// structures",
     "INFO_PARALLELSTRUCTURE_TITRE": "Parallel structures",
     "INFO_PAR_TITRE": "Baffle fishway: setup",
-    "INFO_RUGOFOND_TITRE": "Bed roughness fishpasses",
-    "INFO_RUGOFOND_TITRE_COURT": "Bed roughness",
-    "INFO_RUGOFONDMULTIPLE_TITRE": "Bed roughness fishpasses",
-    "INFO_RUGOFONDMULTIPLE_TITRE_COURT": "Bed roughness",
+    "INFO_RUGOFONDMULTIPLE_TITRE": "Rough bottom ramps",
+    "INFO_RUGOFONDMULTIPLE_TITRE_COURT": "Bottom ramp",
     "INFO_PAR_DESCRIPTION": "planes Denil Fatou superactive mixte chevrons canoe",
     "INFO_PAR_TITRE_COURT": "HF: setup",
     "INFO_PARSIMULATION_TITRE": "Baffle fishway: simulation",
@@ -654,8 +652,8 @@
     "INFO_THEME_PASSE_A_BASSIN_TITRE": "Fish ladder",
     "INFO_THEME_PASSE_A_RALENTISSEURS_TITRE": "Baffle fishway",
     "INFO_THEME_PASSE_A_RALENTISSEURS_DESCRIPTION": "Baffle fishway",
-    "INFO_THEME_PASSE_NATURELLE_DESCRIPTION": "Tools for sizing a evenly distributed macro-roughnesses pass in rockfill or prefabricated",
-    "INFO_THEME_PASSE_NATURELLE_TITRE": "Evenly distributed macro-roughness fish pass",
+    "INFO_THEME_PASSE_NATURELLE_DESCRIPTION": "Tools for sizing a evenly distributed macro-roughnesses pass or a bottom roughness pass",
+    "INFO_THEME_PASSE_NATURELLE_TITRE": "Macro-roughness or bottom roughness fish pass",
     "INFO_THEME_VERIFICATION_DESCRIPTION": "The purpose of this tool is to carry out a simple check of the compatibility between certain fish pass sizing criteria and the passage capacities of the target fish species. It may prove useful during the design phase of a facility to ensure that the proposed design is consistent with its hydrological operating range",
     "INFO_THEME_VERIFICATION_TITRE": "Crossability verification",
     "INFO_TITREJOURNAL": "Calculation log",

src/locale/messages.fr.json

@@ -518,8 +518,8 @@
     "INFO_PARALLELSTRUCTURE_TITRE_COURT": "Ouvrages",
     "INFO_PARALLELSTRUCTURE_TITRE": "Lois d'ouvrages",
     "INFO_PAR_TITRE": "Passe à ralentisseurs : calage",
-    "INFO_RUGOFOND_TITRE": "Passe à rugosité de fond",
-    "INFO_RUGOFOND_TITRE_COURT": "Rugofond",
+    "INFO_RUGOFOND_TITRE": "Passe à rugosités de fond",
+    "INFO_RUGOFOND_TITRE_COURT": "Rugo-fond",
     "INFO_RUGOFONDMULTIPLE_TITRE": "Passe à rugosité de fond",
     "INFO_RUGOFONDMULTIPLE_TITRE_COURT": "Rugofond",
     "INFO_PAR_DESCRIPTION": "plans Denil Fatou fonds suractifs mixte chevrons canoë",
@@ -655,8 +655,8 @@
     "INFO_THEME_PASSE_A_BASSIN_TITRE": "Passe à bassins",
     "INFO_THEME_PASSE_A_RALENTISSEURS_TITRE": "Passe à ralentisseurs",
     "INFO_THEME_PASSE_A_RALENTISSEURS_DESCRIPTION": "Passe à ralentisseurs",
-    "INFO_THEME_PASSE_NATURELLE_DESCRIPTION": "Outils de dimensionnement d'une passe à poissons de type passe à macro-rugosités régulièrement réparties en enrochements ou préfabriquées",
-    "INFO_THEME_PASSE_NATURELLE_TITRE": "Passes à macro-rugosités régulièrement réparties",
+    "INFO_THEME_PASSE_NATURELLE_DESCRIPTION": "Outils de dimensionnement d'une passe à poissons de type passe à macro-rugosités régulièrement réparties ou à rugosités de fond",
+    "INFO_THEME_PASSE_NATURELLE_TITRE": "Passes à macro-rugosités ou rugosités de fond",
     "INFO_THEME_VERIFICATION_DESCRIPTION": "Cet outil a pour objectif de réaliser une vérification simple de la compatibilité entre certains critères de dimensionnement des passes à poissons et les capacités de franchissement des espèces de poissons cibles. Il peut s'avérer utile lors de la phase de conception d'un dispositif afin de s’assurer de la cohérence du dimensionnement projeté sur sa plage de fonctionnement hydrologique",
     "INFO_THEME_VERIFICATION_TITRE": "Vérification des critères de franchissement",
     "INFO_TITREJOURNAL": "Journal de calcul",