doc: add pages for math operator modules and solver

Refs #433

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/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.

mkdocs-en.yml

@@ -13,6 +13,7 @@ extra_javascript:
     - ../javascripts/mathjax.config.js
     - ../javascripts/mathjax/tex-mml-chtml.js
     - ../javascripts/matomo-tracking.js
+    - ../javascripts/mermaid.min.js
 markdown_extensions:
     - mdx_math
     - footnotes
@@ -85,6 +86,9 @@ nav:
     - Downstream migration:
         - Loss of charge, water grid: calculators/devalaison/grille.md
         - Jet impact: calculators/devalaison/jet.md
+    - Mathematical tools:
+        - calculators/maths/operators.md
+        - calculators/maths/solver.md
     - Numerical methods:
         - Runge-Kutta 4: methodes_numeriques/rk4.md
         - Euler explicit: methodes_numeriques/euler_explicite.md

mkdocs-fr.yml

@@ -13,6 +13,7 @@ extra_javascript:
     - ../javascripts/mathjax.config.js
     - ../javascripts/mathjax/tex-mml-chtml.js
     - ../javascripts/matomo-tracking.js
+    - ../javascripts/mermaid.min.js
 markdown_extensions:
     - mdx_math
     - footnotes
@@ -85,7 +86,10 @@ nav:
     - Dévalaison:
         - Perte de charge sur grille de prise d'eau: calculators/devalaison/grille.md
         - Impact de jet: calculators/devalaison/jet.md
-    - Méthodes numériques de résolution :
+    - Outils mathématiques:
+        - calculators/maths/operators.md
+        - calculators/maths/solver.md
+    - Méthodes numériques de résolution:
         - Runge-Kutta 4: methodes_numeriques/rk4.md
         - Euler explicite: methodes_numeriques/euler_explicite.md
         - Intégration de trapèzes: methodes_numeriques/integration_trapezes.md

scripts/mkdocs-postprocess.js

@@ -23,5 +23,7 @@ fs.copySync("docs/mathjax.config.js", destPath + "/mathjax.config.js");
 
 fs.copySync("docs/matomo-tracking.js", destPath + "/matomo-tracking.js");
 
+fs.copySync("node_modules/mermaid/dist/mermaid.min.js", destPath + "/mermaid.min.js");
+
 // copy illustrated guide (not related to MkDocs, but still a part of the doc)
 fs.copySync("docs/cassiopee_notice_illustree_fr.pdf", "src/assets/docs/pdf/cassiopee_notice_illustree_fr.pdf");

src/app/calculators/spp/config.json

@@ -32,6 +32,6 @@
     {
         "type": "options",
         "selectIds": [ "select_sppoperation" ],
-        "_help": "util/spp.html"
+        "help": "maths/operators.html#somme-et-produit-de-puissances"
     }
 ]
\ No newline at end of file

src/app/calculators/trigo/config.json

@@ -25,6 +25,6 @@
     {
         "type": "options",
         "selectIds": [ "select_operation", "select_unit" ],
-        "_help": "util/trigo.html"
+        "help": "maths/operators.html#fonction-trigonometrique"
     }
 ]
\ No newline at end of file

src/app/calculators/yaxb/config.json

@@ -6,6 +6,6 @@
     },
     {
         "type": "options",
-        "_help": "util/yaxb.html"
+        "help": "maths/operators.html#fonction-affine"
     }
 ]
\ No newline at end of file