From 9228497fd3792c57be32305d571e2fd1c43956a2 Mon Sep 17 00:00:00 2001
From: David Dorchies <david.dorchies@irstea.fr>
Date: Tue, 2 Feb 2021 14:05:57 +0100
Subject: [PATCH 1/2] doc: add pages for math operator modules and solver
Refs #433
---
docs/en/calculators/maths/operators.md | 40 ++++++++++++++++++++++++++
docs/en/calculators/maths/solver.md | 34 ++++++++++++++++++++++
docs/fr/calculators/maths/operators.md | 37 ++++++++++++++++++++++++
docs/fr/calculators/maths/solver.md | 34 ++++++++++++++++++++++
mkdocs-en.yml | 4 +++
mkdocs-fr.yml | 6 +++-
scripts/mkdocs-postprocess.js | 2 ++
src/app/calculators/spp/config.json | 2 +-
src/app/calculators/trigo/config.json | 2 +-
src/app/calculators/yaxb/config.json | 2 +-
10 files changed, 159 insertions(+), 4 deletions(-)
create mode 100644 docs/en/calculators/maths/operators.md
create mode 100644 docs/en/calculators/maths/solver.md
create mode 100644 docs/fr/calculators/maths/operators.md
create mode 100644 docs/fr/calculators/maths/solver.md
diff --git a/docs/en/calculators/maths/operators.md b/docs/en/calculators/maths/operators.md
new file mode 100644
index 000000000..18c77c3b9
--- /dev/null
+++ b/docs/en/calculators/maths/operators.md
@@ -0,0 +1,40 @@
+# 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.
diff --git a/docs/en/calculators/maths/solver.md b/docs/en/calculators/maths/solver.md
new file mode 100644
index 000000000..511fe93fe
--- /dev/null
+++ b/docs/en/calculators/maths/solver.md
@@ -0,0 +1,34 @@
+# 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.
diff --git a/docs/fr/calculators/maths/operators.md b/docs/fr/calculators/maths/operators.md
new file mode 100644
index 000000000..2f1feeaa1
--- /dev/null
+++ b/docs/fr/calculators/maths/operators.md
@@ -0,0 +1,37 @@
+# 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.
diff --git a/docs/fr/calculators/maths/solver.md b/docs/fr/calculators/maths/solver.md
new file mode 100644
index 000000000..bdce11432
--- /dev/null
+++ b/docs/fr/calculators/maths/solver.md
@@ -0,0 +1,34 @@
+# 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 :
+
+- Le module et son paramètre calculé (Ici le module `y` calculant `Output y`) ;
+- 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`) ;
+- La valeur cible désirée.
+
+Il faut aussi définir les caractéristiques du paramètre recherché :
+
+- 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`) ;
+- 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.
diff --git a/mkdocs-en.yml b/mkdocs-en.yml
index bc7a02c58..409dc0282 100644
--- a/mkdocs-en.yml
+++ b/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
diff --git a/mkdocs-fr.yml b/mkdocs-fr.yml
index dfe03ac28..947cffb05 100644
--- a/mkdocs-fr.yml
+++ b/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
diff --git a/scripts/mkdocs-postprocess.js b/scripts/mkdocs-postprocess.js
index 0efd29ea8..0e929e545 100644
--- a/scripts/mkdocs-postprocess.js
+++ b/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");
diff --git a/src/app/calculators/spp/config.json b/src/app/calculators/spp/config.json
index 24318a4e5..8506d7c73 100644
--- a/src/app/calculators/spp/config.json
+++ b/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
diff --git a/src/app/calculators/trigo/config.json b/src/app/calculators/trigo/config.json
index 34baffff0..3b9f5d97a 100644
--- a/src/app/calculators/trigo/config.json
+++ b/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
diff --git a/src/app/calculators/yaxb/config.json b/src/app/calculators/yaxb/config.json
index b834b0627..391232436 100644
--- a/src/app/calculators/yaxb/config.json
+++ b/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
--
GitLab
From 8e76f49b5890e9ee8e43e5fa7f6c1088e2e43e7e Mon Sep 17 00:00:00 2001
From: David Dorchies <david.dorchies@irstea.fr>
Date: Tue, 2 Feb 2021 15:05:17 +0100
Subject: [PATCH 2/2] doc: add link to documentation for solver module
Refs #433
---
src/app/calculators/solveur/config.json | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/app/calculators/solveur/config.json b/src/app/calculators/solveur/config.json
index f04658c8d..71a23177b 100644
--- a/src/app/calculators/solveur/config.json
+++ b/src/app/calculators/solveur/config.json
@@ -35,6 +35,6 @@
"selectIds": [ "select_target_result" ],
"customSelectIds": [ "select_target_nub", "select_searched_param" ],
"targettedResultSelectId": "select_target_result",
- "_help": "solveur.html"
+ "help": "maths/solver.html"
}
]
\ No newline at end of file
--
GitLab