From 2c8b9e6484ea6b3c9ccd09940e9db467ea49292e Mon Sep 17 00:00:00 2001
From: Dorchies David <david.dorchies@irstea.fr>
Date: Mon, 14 Sep 2020 10:46:10 +0200
Subject: [PATCH] doc(jet): add signification of parameters in equations

---
 docs/en/calculators/devalaison/jet.md | 24 +++++++++++++++++++++---
 docs/fr/calculators/devalaison/jet.md | 24 +++++++++++++++++++++---
 2 files changed, 42 insertions(+), 6 deletions(-)

diff --git a/docs/en/calculators/devalaison/jet.md b/docs/en/calculators/devalaison/jet.md
index 2e5f70b23..deacb5296 100644
--- a/docs/en/calculators/devalaison/jet.md
+++ b/docs/en/calculators/devalaison/jet.md
@@ -1,19 +1,37 @@
 # Jet impact
 
+This module performs a ballistic calculation of a jet while neglecting air friction. It allows to calculate the missing value among the following quantities:
+
+- Initial velocity at the start of the jet (m/s)
+- Initial slope at the start of the jet (m/m). Note that, contrary to the slope used in the free surface calculation module, this slope is positive for an upward directed jet and negative for a downward directed jet.
+- Abscissa of the impact or horizontal distance travelled between the start of the jet and the point of impact (m)
+- Start dimension of the jet (m)
+- Water elevation (m)
+
+The bottom elevation is used to calculate the depth and the depth to fall ratio.
+
+## Designing an outlet for fish evacuation
+
 The downstream fish evacuation outlet ends with a device that empties into the plant's tailrace. This module calculates the position and velocity at the point of impact of the free fall or water vein on the surface of the tailrace water taking into account the initial angle and velocity of the jet and the drop height.
 
 Excerpt from Courret, Dominique, and Michel Larinier. Guide for the design of ichthyocompatible water intakes for small hydroelectric power plants, 2008. https://doi.org/10.13140/RG.2.1.2359.1449, p.24:
 
 > Speeds in the structure and at the point of impact in the tailrace must remain below about 10 m/s, with some organizations even recommending that they not exceed 7-8 m/s (ASCE 1995). (...) The head between the outlet and the water body must not exceed a dozen metres to avoid any risk of injury to fish on impact, whatever their size and mode of fall (free fall or fall in the water vein) (Larinier and Travade 2002). The discharge must also be made in an area of sufficient depth to avoid any risk of injury from mechanical shock. Odeh and Orvis (1998) recommend a minimum depth of about a quarter of the fall, with a minimum of about 1 m.
 
-## Formula
-
-With \(g\): gravity acceleration = 9.81 m.s-2
+## Formulas used
 
 ### Fall height
 
 $$H = 0.5 * g * \frac{D^{2}}{\cos \alpha^{2} * V_0^{2}} - \tan \alpha * D$$
 
+With:
+
+- \(H\): height of fall (m) which corresponds to the difference in height between the jet's departure and the water surface.
+- \(g\): acceleration of gravity = 9.81 m.s-2
+- \(D\): horizontal distance travelled between the start of the jet and the point of impact (m)
+- \(\alpha\)&nbsp;: angle of shooting in relation to the horizontal (°)
+- \(\V_0\)&nbsp;: initial speed (m/s)
+
 ### Impact abscissa (horizontal distance covered)
 
 $$D = \frac{V_0}{g * \cos \alpha} \left ( V_0 * \sin \alpha + \sqrt{ \left ( V_0 * \sin \alpha \right )^{2} + 2 * g * H } \right )$$
diff --git a/docs/fr/calculators/devalaison/jet.md b/docs/fr/calculators/devalaison/jet.md
index 7454c1691..5300214ce 100644
--- a/docs/fr/calculators/devalaison/jet.md
+++ b/docs/fr/calculators/devalaison/jet.md
@@ -1,19 +1,37 @@
 # Impact de jet
 
+Ce module effectue un calcul balistique d'un jet en négligeant les frottements dus à l'air. Il permet de calculer la valeur manquante parmi les grandeurs suivantes&nbsp;:
+
+- Vitesse initiale au départ du jet (m/s)
+- Pente initiale au départ du jet (m/m). A noter que, contrairement à la pente utilisée dans le modules de calcul à surface libre, cette pente est positive pour un jet dirigé vers le haut et négative pour un jet diriger vers le bas.
+- Abscisse de l'impact ou distance horizontale parcourue entre le départ du jet et le point d'impact (m)
+- Cote de départ du jet (m)
+- Cote de l'eau (m)
+
+La cote du fond est utilisée pour calculer la profondeur et le rapport profondeur / chute.
+
+## Dimensionnement d'un exutoire d'évacuation des poissons
+
 L'exutoire d'évacuation des poissons vers l'aval se termine par un dispositif se jetant dans le canal de fuite de la centrale. Le présent module permet de calculer la position et la vitesse au point d'impact de la chute libre ou de la veine d'eau à la surface de l'eau du canal de fuite compte tenu de l'angle et de la vitesse initiaux du jet et de la hauteur de chute.
 
 Extrait de Courret, Dominique, et Michel Larinier. Guide pour la conception de prise d’eau ichtyocompatibles pour les petites centrales hydroélectriques, 2008. https://doi.org/10.13140/RG.2.1.2359.1449, p.24&nbsp;:
 
 > Les vitesses dans l’ouvrage et au point d’impact dans le bief aval doivent rester inférieures à une dizaine de m/s, certains organismes préconisant même de ne pas dépasser 7-8 m/s (ASCE 1995). (...) La hauteur de chute entre le débouché et le plan d’eau ne doit pas dépasser une douzaine de mètres pour éviter tout risque de blessures des poissons à l’impact, quels que soient leur taille et leur mode de chute (chute libre ou chute dans la veine d’eau) (Larinier et Travade 2002). Le rejet doit également se faire dans une zone d’une profondeur suffisante pour éviter tout risque de blessure par choc mécanique. Odeh et Orvis (1998) préconisent une profondeur minimale de l’ordre du quart de la chute, avec un minimum d’environ 1 m.
 
-## Formule
-
-Avec \(g\)&nbsp;: accélération de la gravité = 9.81 m.s-2
+## Formules utilisées
 
 ### Hauteur de chute
 
 $$H = 0.5 * g * \frac{D^{2}}{\cos \alpha^{2} * V_0^{2}} - \tan \alpha * D$$
 
+Avec&nbsp;:
+
+- \(H\)&nbsp;: hauteur de chute (m) qui correspond à la différence de cote entre le départ du jet et la surface de l'eau
+- \(g\)&nbsp;: accélération de la gravité = 9.81 m.s-2
+- \(D\)&nbsp;: distance horizontale parcourue entre le départ du jet et le point d'impact (m)
+- \(\alpha\)&nbsp;: angle de tir par rapport à l'horizontale (°)
+- \(\V_0\)&nbsp;: vitesse initiale (m/s)
+
 ### Abscisse de l'impact (distance horizontale parcourue)
 
 $$D = \frac{V_0}{g * \cos \alpha} \left ( V_0 * \sin \alpha + \sqrt{ \left ( V_0 * \sin \alpha \right )^{2} + 2 * g * H } \right )$$
-- 
GitLab