Merge branch '34-documentation-utilisateur-dans-les-interfaces' into 'master'

Resolve "Documentation utilisateur dans les interfaces"

Closes #34

See merge request !26

.gitignore

@@ -4,6 +4,7 @@
 /dist
 /tmp
 /out-tsc
+/src/assets/docs-*
 
 # dependencies
 /node_modules

README.md

@@ -8,6 +8,15 @@ This can be done from the command line:
 
 `npm install -g typescript karma tslint`
 
+The documentation of Cassiopee needs to install MkDocs and some extensions:
+
+```sh
+sudo apt install python3-pip
+python3 -m pip install mkdocs
+python3 -m pip install python-markdown-math
+python3 -m pip install mkdocs-material
+```
+
 ### Install the necessary packages of the library:
 
 Clone or update the JalHyd project and in the JalHyd folder, run :
@@ -16,7 +25,7 @@ Clone or update the JalHyd project and in the JalHyd folder, run :
 
 Then, back to the ngHyd project folder, run :
 
-`npm install <path to the JalHyd folder>/jalhyd-<version>.tar.gz`
+`npm run jalhyd`
 
 and then :
 
@@ -141,7 +150,7 @@ and then :
 	- dans _src/app/calculators_ : créer un répertoire (par ex _ma-calculette_)
 
 	- dans _src/app/calculators/ma-calculette_ :
-	
+
 		Créer _ma-calculette.config.json_ sur le modèle des autres.
 		Les ids utilisés doivent correspondre au symbole fourni à classe _BaseParam_ (1er paramètre du constructeur)
 
@@ -151,7 +160,7 @@ and then :
 		- éventuellement le type de noeud de paramètres particuliers (objets comportant _"type":"input"_) avec le champ _"nodeType": "MaCalculetteBleue"_ (par défaut, "_ComputeNodeType.None_")
 
 	- dans _src/app/calculators/ma-calculette_ :
-	
+
 		Créer les fichiers d'internationalisation (_ma-calculette.&lt;langue&gt;.json_). Il doivent reprendre tous les ids utilisés dans le fichier de configuration et fournir leur traduction.
 
 * créer la classe du formulaire dans _src/app/formulaire/definition/concrete_

docs-fr/avant-propos.md

+# Avant-Propos
+
+Concernant les passes à poissons, le logiciel CASSIOPEE doit être considéré comme un outil d'aide à la conception des passes à
+poissons.
+
+Son utilisateur doit être parfaitement familier de la technique de dimensionnement des passes à
+poissons.
+
+Dans le processus de mise au point d'une passe à poissons, la fonction de CASSIOPEE est de calculer
+certaines grandeurs caractérisant son fonctionnement et de présenter les résultats de façon claire et
+conviviale.
+
+Il ne peut évidemment répondre au problème de l'optimisation de l'implantation de l'ouvrage sur le
+site.
+
+Il convient à l'utilisateur de vérifier que le projet élaboré répond bien au problème posé et que toutes
+les conditions assurant sa franchissabilité sont satisfaites.
+
+En aucun cas l'AFB ou Irstea ne pourront être tenus responsables du mauvais fonctionnement
+d'un projet dimensionné avec CASSIOPEE.

src/app/calculators/regime-uniforme/regime-uniforme.fr.md → docs-fr/calculators/hsl/regime_uniforme.md

-Hydraulique à surface libre : le régime uniforme
-===
+# Le régime uniforme
+
 
 Le régime uniforme se caractérise par une hauteur d'eau appelée hauteur normale. La hauteur normale est atteinte quand la ligne d'eau est parallèle au fond, la charge est alors elle-même parallèle à la ligne d'eau et donc la perte de charge est égale à la pente du fond :
-$I_f = J$
+\(I_f = J\)
 
 Avec :
-- $I_f$ : la pente du fond en m/m
-- $J$ : la perte de charge en m/m
+
+- \(I_f\) : la pente du fond en m/m
+- \(J\) : la perte de charge en m/m
 
 La perte de charge {J} est ici calculée avec la formule de Manning-Strickler :
 
 $$J=\frac{U^2}{K^{2}R^{4/3}}=\frac{Q^2}{S^2K^{2}R^{4/3}}$$
 
 Avec :
-- $K$ : le coefficient de Strickler en m<sup>1/3</sup>/s
+
+- \(K\) : le coefficient de Strickler en m<sup>1/3</sup>/s
 
 En régime uniforme, on obtient la formule :
 
 $$Q=KR^{2/3}S\sqrt{I_f}$$
 
-A partir de laquelle, on peut calculer analytiquement le débit $Q$, la pente $I_f$ et le Strickler $K$ analytiquement.
+A partir de laquelle, on peut calculer analytiquement le débit \(Q\), la pente \(I_f\) et le Strickler \(K\) analytiquement.
 
-Pour calculer la hauteur normale $h_n$, on peut résoudre $f(h_n)=Q-KR^{2/3}S\sqrt{I_f}=0$
+Pour calculer la hauteur normale \(h_n\) , on peut résoudre \(f(h_n)=Q-KR^{2/3}S\sqrt{I_f}=0\)
 
 en utilisant la méthode de Newton :
 
 $$h_{k+1} = h_k - \frac{f(h_k)}{f'(h_k)}$$
 
  avec :
-- $f(h_k) = Q-KR^{2/3}S\sqrt{I_f}$
-- $f'(h_k) = -K \sqrt{I_f}(\frac{2}{3}R'R^{-1/3}S+R^{2/3}S')$
 
-Pour calculer les paramètres géométriques de la section, la calculette utilise l'équation de calcul du débit et résout le problème par dichotomie.
\ No newline at end of file
+- \(f(h_k) = Q-KR^{2/3}S\sqrt{I_f}\)
+- \(f'(h_k) = -K \sqrt{I_f}(\frac{2}{3}R'R^{-1/3}S+R^{2/3}S')\)
+
+Pour calculer les paramètres géométriques de la section, la calculette utilise l'équation de calcul du débit et résout le problème par dichotomie.

src/app/calculators/cond_distri/cond_distri.fr.md → docs-fr/calculators/hyd_en_charge/cond_distri.md

-Relation analytique pour le calcul direct des pertes de charge en conduite distribuant un débit de façon homogène établi à partir de la formule de Blasius.
-===
+# Relation analytique pour le calcul direct des pertes de charge en conduite distribuant un débit de façon homogène établi à partir de la formule de Blasius.
 
-Hypothèses
----
+## Hypothèses
 
-![Schéma conduite](assets/doc/cond-distri-1.png)
+![Schéma conduite](cond_distri.png)
 
-On suppose une conduite de longueur $L$, diamètre intérieur $D$, avec un débit en tête $Q$. On calcule la perte de charge $\Delta H$ entre les 2 extrémités de la conduite. Dans une section de débit $q$ constant, on évalue le coefficient de frottement avec la formule de Blasius, valide pour des nombres de Reynolds modérés pour des parois lisses:
+On suppose une conduite de longueur \(L\), diamètre intérieur \(D\), avec un débit en tête \(Q\). On calcule la perte de charge \(\Delta H\) entre les 2 extrémités de la conduite. Dans une section de débit \(q\) constant, on évalue le coefficient de frottement avec la formule de Blasius, valide pour des nombres de Reynolds modérés pour des parois lisses:
 $$\lambda \simeq a Re^{-0.25}$$
 
-Développement analytique
----
-On note $x$ la position depuis l'aval de la conduite. Le débit est supposé varier linéairement avec $x$, et s'écrit alors:
+## Développement analytique
+
+On note \(x\) la position depuis l'aval de la conduite. Le débit est supposé varier linéairement avec \(x\), et s'écrit alors:
 $$q(x)=Q x/L$$
-Notons $S=\pi D^2/4$ la surface intérieure de la conduite.
+Notons \(S=\pi D^2/4\) la surface intérieure de la conduite.
 On obtient la perte de charge en intégrant la relation de Darcy-Weisbach:
 $$\Delta H=\int_{x=0}^{L} a Re^{-0.25} \frac{u^2(x)}{2gD}dx$$
-Notons $\nu$ la viscosité cinématique. On remplace alors $Re$ par $u D/\nu$, ce qui donne
+Notons \(\nu\) la viscosité cinématique. On remplace alors \(Re\) par \(u D/\nu\), ce qui donne
 $$\Delta H=\int_{x=0}^{L} a u(x)^{-0.25}D^{-0.25}\nu ^{0.25} \frac{u^2(x)}{2gD}dx$$
 En réarrangeant, on obtient:
 $$\Delta H=\int_{x=0}^{L} a \nu ^{0.25} \frac{u^{1.75}(x)}{2gD^{1.25}}dx$$
 Utilisons l'équation du débit pour faire apparaître le débit ($u(x)=q(x)/S$):
 $$\Delta H=\int_{x=0}^{L} a \nu ^{0.25} \frac{(Qx/(LS))^{1.75}}{2gD^{1.25}}dx$$
-puis le diamètre $D$:
+puis le diamètre \(D\) :
 $$\Delta H=\int_{x=0}^{L} a \nu ^{0.25} \frac{(4Qx/(L\pi D^2))^{1.75}}{2gD^{1.25}}dx$$
 On réarrange pour obtenir
 $$\Delta H=a \nu ^{0.25} \frac{(4/\pi)^{1.75}Q^{1.75}}{2g D^{4.75}} \int_{x=0}^{L} (x/L)^{1.75}dx$$
 En intégrant, on obtient
-$$\Delta H=a \nu ^{0.25} \frac{(4/\pi)^{1.75}Q^{1.75}}{2g D^{4.75}}\frac{L}{2.75} $$
-$$\Delta H=a \nu ^{0.25} \frac{4^{1.75}}{5.5g \pi^{1.75}}\frac{Q^{1.75}L}{D^{4.75}} $$
-
-Application numérique
----
-Pour une  eau à 20°C: $\nu\simeq 10^{-6}m^2/s$, ce qui donne
-$$\Delta H=0.323\ 10^{-3}\frac{Q^{1.75}}{D^{4.75}}L $$
-avec $\Delta H$ en mètres.
-Pour une eau à 50°C, $\nu\simeq 0.556 10^{-6}m^2/s$, ce qui implique que la perte de charge est réduite d'environ 14%, soit
-$$\Delta H= 0.28\ 10^{-3}\frac{Q^{1.75}}{D^{4.75}}L $$
+$$\Delta H=a \nu ^{0.25} \frac{(4/\pi)^{1.75}Q^{1.75}}{2g D^{4.75}}\frac{L}{2.75}$$
+$$\Delta H=a \nu ^{0.25} \frac{4^{1.75}}{5.5g \pi^{1.75}}\frac{Q^{1.75}L}{D^{4.75}}$$
+
+## Application numérique
+
+Pour une  eau à 20°C: \(\nu\simeq 10^{-6}\) m<sup>2</sup>/s, ce qui donne
+
+$$\Delta H=0.323\ 10^{-3}\frac{Q^{1.75}}{D^{4.75}}L$$
+
+avec \(\Delta H\) en mètres.
+
+Pour une eau à 50°C, \(\nu\simeq 0.556 10^{-6}\)  m<sup>2</sup>/s, ce qui implique que la perte de charge est réduite d'environ 14%, soit
+
+$$\Delta H= 0.28\ 10^{-3}\frac{Q^{1.75}}{D^{4.75}}L$$

docs-fr/calculators/hyd_en_charge/lechapt-calmon.md

+# Pertes de charge dans une conduite circulaire : abaques de Lechapt et Calmon
+
+La formule de Lechapt et Calmon est basée sur des ajustements de la formule de  [Cyril Frank Colebrook](http://fr.wikipedia.org/wiki/Cyril_Frank_Colebrook) :
+
+$$J=L.Q^M.D^{-N}$$
+
+Avec :
+
+- \(J\) : la perte de charge en mm/m ou m/km;
+- \(Q\) : le débit en L/s;
+- \(D\) : le diamètre de la conduite en m;
+- \(L\), \(M\) et \(N\) des coefficients dépendants de la rugosité {ϵ}.
+
+L'erreur commise par rapport à la formule de Colebrook est inférieure à 3 % pour des vitesses comprises entre 0,4 et 2 m/s.
+
+Le tableau de correspondance des coefficients est le suivant :
+
+
+| Matériau | ϵ (mm) | \(L\) | \(M\) | \(N\) |
+|----------|-------------:|----:|----:|-----:|
+| Fonte ou acier non revêtus - Béton grossier (eau corrosive) | 2 | 1.863 | 2 | 5.33 |
+| Fonte ou acier non revêtus - Béton grossier (eau peu corrosive) | 1 | 1.601 | 1.975 | 5.25 |
+| Fonte ou acier revêtement ciment | 0.5 | 1.40 | 1.96 | 5.19 |
+| Fonte ou acier revêtement bitume - béton centrifugé | 0.25 | 1.16 | 1.93 | 5.11 |
+| Acier laminé - béton lisse | 0.1 | 1.10 | 1.89 | 5.01 |
+| Fonte ou acier revêtement centrifugé | 0.05 | 1.049 | 1.86 | 4.93 |
+| PVC - polyéthylène | 0.025 | 1.01 | 1.84 | 4.88 |
+| Tuyau hydrauliquement lisse - 0.05 ≤ D ≤ 0.2 | 0.00 | 0.916 | 1.78 | 4.78 |
+| Tuyau hydrauliquement lisse - 0.25 ≤ D ≤ 1 | 0.00 | 0.971 | 1.81 | 4.81 |

docs-fr/calculators/pab/cloisons.md

+# Cloisons
+
+Cet outil est une aide au prédimensionnement hydraulique d'une passe à bassins : il
+est utilisé le plus souvent pour le dimensionnement des échancrures, fentes, orifices
+caractérisant les cloisons d'une passe ainsi que pour le calage en altitude des échancrures,
+fentes et radier du bassin amont d'une passe.
+
+Il permet de calculer la valeur manquante des 7 valeurs caractérisant la chute, la surface
+de l'orifice noyé, la largeur de la fente, la charge sur la fente, la largeur de l'échancrure,
+la charge sur l'échancrure et le débit.
+
+Les données à fournir obligatoirement sont les dimensions des bassins (largeur et longueur) ainsi que le
+tirant d'eau moyen en mètres. Ces données associées à la chute entre bassins permettent de calculer [la puissance volumique dissipée](volume.md).
+
+## Ouvrages hydrauliques pouvant constituer la cloison
+
+L'outil permet de placer un ou plusieurs ouvrages en parallèle parmi les types d'ouvrages suivants:
+
+### Orifice noyé
+
+![Schéma orifice noyé](../structures/orifice_noye_schema.png)
+
+*Extrait de Larinier, M., Travade, F., Porcher, J.-P., Gosset, C., 1992. Passes à poissons : expertise et conception des ouvrages de franchissement. CSP. (page 94)*
+
+L'équation de l'orifice noyé est décrite sur [la page de la formule de l'orifice noyé](../structures/orifice_noye.md).
+
+### Fente noyée
+
+![Schéma de la fente noyée](../structures/fente_noyee_schema.png)
+
+*Extrait de Larinier, M., Travade, F., Porcher, J.-P., Gosset, C., 1992. Passes à poissons : expertise et conception des ouvrages de franchissement. CSP. (page 94)*
+
+L'équation de la fente noyée est décrite sur [la page de la formule de la fente noyée](../structures/fente_noyee.md).
+
+### Echancrure
+
+![Schéma de l'échancrure](../structures/echancrure_schema.png)
+
+*Extrait de Larinier, M., Travade, F., Porcher, J.-P., Gosset, C., 1992. Passes à poissons : expertise et conception des ouvrages de franchissement. CSP. (page 94)*
+
+L'équation utilisée pour l'échancrure est [celle de Kindsvater-Carter et Villemonte](../structures/kivi.md).

docs-fr/calculators/pab/dimensions.md

+# Passes à bassins : Dimensions
+
+Cet outil est une aide au dimensionnement des bassins d'une passe : il permet de
+calculer la valeur manquante des quatre grandeurs :
+
+- le volume d'eau (\(V\)) en m<sup>3</sup>;
+- le tirant d'eau moyen (\(Y_{moy}\)) en m;
+- la longueur du bassin (\(L\)) en m;
+- la largeur du bassin (\(B\)) en m.
+
+Le calcul est effectué en appliquant la formule :
+
+$$V = Y_{moy} \times L \times B$$

docs-fr/calculators/pab/volume.md

+# Passes à bassins : Puissance dissipée
+
+Cet outil est une aide au prédimensionnement d'une passe à bassins : il permet de calculer la valeur manquante des quatre grandeurs :
+
+- la chute entre les bassins (\(\Delta H\)) en m;
+- le débit (\(Q\)) en m<sup>3</sup>/s;
+- le volume des bassins (\(V\)) en m<sup>3</sup>;
+- la puissance volumique dissipée (\(P_v\)) en W/m<sup>3</sup>.
+
+La formule de calcul de la puissance dissipée est alors :
+
+$$P_v = \frac{\rho \mathrm{g} Q \Delta H}{V}$$
+
+avec :
+
+- \(\rho\) : la masse volumique de l'eau;
+- \(\mathrm{g}\) : l'accélération de la gravité terrestre = 9,81 m.s<sup>-2</sup>

docs-fr/calculators/structures/fente_noyee.md

+# Formule de la fente noyée
+
+![Schéma de la fente noyée](fente_noyee_schema.png)
+
+*Extrait de Larinier, M., Travade, F., Porcher, J.-P., Gosset, C., 1992. Passes à poissons : expertise et conception des ouvrages de franchissement. CSP. (page 94)*
+
+Larinier (1992) propose l'équation suivante :
+
+$$Q = \mu b H_1\sqrt{2g \Delta H}$$
+
+Avec :
+
+* *b* la largeur de la fente en m 
+* *H<sub>1</sub>* la charge sur la fente m&nbsp;
+* *μ* le coefficient de débit (égal à 0.65 par défaut).
+
+N.B. : la littérature propose plutôt la formule suivante:
+
+$$Q = \mu b H_2\sqrt{2g \Delta H}$$

src/app/calculators/parallel-structures/parallel-structures.fr.md → docs-fr/calculators/structures/kivi.md

-# Lois de débit sur les ouvrages
+# Formule de Kindsvater-Carter et Villemonte
+
 
 La calculette permet d'effectuer des calculs hydrauliques pour plusieurs ouvrages en parallèle.
 
-## Formule de Kindsvater-Carter et Villemonte (1957)
+## Formule de Kindsvater-Carter (1957)
 
-![Schéma déversoir](assets/doc/structure_kivi_schema_seuil.png)
+![Schéma déversoir](kivi_schema_seuil.png)
 
 La formule de Kindsvater-Carter correspond à la formule classique du déversoir :
 
 $$Q = \mu L \sqrt{2g}h_1^{1.5}$$
 
 Avec :
-- $\mu$ le coefficient de débit $\mu = \alpha + \beta h_1/p$
-- $L$ la largeur du déversoir
-- $h_1$ la hauteur d'eau au dessus de la crête du déversoir
-- $p$ la pelle ou hauteur de la crête du déversoir
 
-Les coefficient $\alpha$ et $\beta$ dépendent du rapport entre la largeur du déversoir ($L$) et la largeur du bassin ($B$). Leurs valeurs sont données par les abaques ci dessous (extrait de Larinier, M., Porcher, J.-P., 1986. Programmes de calcul sur HP86 : hydraulique et passes à poissons) :
+- \(\mu\) le coefficient de débit \(\mu = \alpha + \beta h_1/p\)
+- \(L\) la largeur du déversoir
+- \(h_1\) la hauteur d'eau au dessus de la crête du déversoir
+- \(p\) la pelle ou hauteur de la crête du déversoir
+
+Les coefficient \(\alpha\) et \(\beta\) dépendent du rapport entre la largeur du déversoir (\(L\)) et la largeur du bassin (\(B\)). Leurs valeurs sont données par les abaques ci dessous (extrait de Larinier, M., Porcher, J.-P., 1986. Programmes de calcul sur HP86 : hydraulique et passes à poissons) :
 
-![Schéma déveroir](assets/doc/structure_kivi_abaques_alpha_beta.png)
+![Schéma déveroir](kivi_abaques_alpha_beta.png)
 
 ## Écoulement noyé : formule de Villemonte (1947)
 
-![Schéma déversoir](assets/doc/structure_villemonte_schema_seuil_noye.png)
+![Schéma déversoir](kivi_villemonte_schema_seuil_noye.png)
 
 Pour une cote de l'eau aval supérieur à la cote de la crête du déversoir, l'écoulement est noyé et un coefficient de noyage s'applique sur le coefficient de débit.
 
 Villemonte propose la formule suivante :
 
-$$ K = \frac{Q_{noyé}}{Q_{dénoyé}} = \left [ 1- \left ( \frac{h2}{h1} \right)^n \right]^{0.385} $$
+$$K = \frac{Q_{noyé}}{Q_{dénoyé}} = \left [ 1- \left ( \frac{h2}{h1} \right)^n \right]^{0.385}$$
 
 Avec :
-- $h_1$ la hauteur d'eau amont au dessus de la crête du déversoir
-- $h_2$ la hauteur d'eau aval au dessus de la crête du déversoir
-- $n$ l'exposant dans les relations d'écoulement dénoyé (rectangulaire=1.5, triangulaire=2.5, parabolique=2)
+- \(h_1\)la hauteur d'eau amont au dessus de la crête du déversoir
+- \(h_2\)la hauteur d'eau aval au dessus de la crête du déversoir
+- \(n\)l'exposant dans les relations d'écoulement dénoyé (rectangulaire=1.5, triangulaire=2.5, parabolique=2)
 
 

docs-fr/calculators/structures/orifice_noye.md

+# Formule de l'orifice noyé
+
+![Schéma orifice noyé](orifice_noye_schema.png)
+
+*Extrait de Larinier, M., Travade, F., Porcher, J.-P., Gosset, C., 1992. Passes à poissons : expertise et conception des ouvrages de franchissement. CSP. (page 94)*
+
+L'équation correspond à peu de chose près à celle de la calculette de la vanne rectangulaire noyée à la différence près que la surface de l'orifice est donnée directement plutôt que par le rapport de la largeur avec la hauteur :
+
+$$Q = \mu S \sqrt{2g \Delta H}$$
+
+Avec :
+
+* *Q* le débit en m<sup>3</sup>/s&nbsp;;
+* *μ* le coefficient de débit (égal à 0.7 par défaut);
+* *S* la surface de l'orifice en m<sup>2</sup>&nbsp;;
+* *ΔH* La perte de charge *H<sub>1</sub> - H<sub>2</sub>* en m&nbsp;(noté "Chute" dans Cassiopée).

docs-fr/general/parametres_application.md

+# Paramètres de l'application
+
+Accessible depuis le menu latéral gauche, les paramètres de l'application modifiables par l'utilisateur sont les suivants :
+
+- Précision d'affichage : Nombre de décimales affichées pour les résultats des calculs;
+- Précision de calcul : précision de calcul utilisée par défaut lors de la création d'un module de calcul;
+- Nombre d'itération de l'algorithme de résolution : pour les calculs résolus avec un algorithme de résolution, nombre d'itération maximum de l'algorithme.