Fix Nicolas's comments

content/users/docs/technical_and_physical_choices/allowances.md → content/users/docs/running_time_calculation/allowances.md

@@ -1,14 +1,14 @@
 ---
-title: "6 - Les marges"
-linkTitle: "Les marges"
-weight: 60
+title: "5 - Les marges"
+linkTitle: "5 - Les marges"
+weight: 50
 ---
 
 ### <font color=#aa026d>La raison d'être des marges</font>
 
 Comme expliqué dans le [calcul du Max Effort Profile](../pipeline/#calcul-du-max-effort-profile), la **marche de base** représente la marche la plus tendue normalement réalisable, c'est-à-dire le trajet le plus rapide possible du matériel donné sur le parcours donné. Le train accélère au maximum, roule aussi vite que possible en fonction des différentes limites de vitesse et de ses capacités motrices, et freine au maximum.
 
-Cette marche de base présente un inconvénient majeur : si un train part avec 10mn de retard, il arrivera au mieux avec 10mn de retard, car par définition il lui est impossible de rouler plus vite que la marche de base. Par conséquent, les trains sont programmés avec un ajout d'une ou de plusieurs marges. Les marges sont une détente du trajet du train, un ajout de temps à l'horaire prévue, qui se traduit inévitablement par un abaissement des vitesses de circulation.
+Cette marche de base présente un inconvénient majeur : si un train part avec 10min de retard, il arrivera au mieux avec 10min de retard, car par définition il lui est impossible de rouler plus vite que la marche de base. Par conséquent, les trains sont programmés avec un ajout d'une ou de plusieurs marges. Les marges sont une détente du trajet du train, un ajout de temps à l'horaire prévu, qui se traduit inévitablement par un abaissement des vitesses de circulation.
 
 > Un train circulant en marche de base est incapable de rattraper son retard !
 
@@ -17,15 +17,15 @@ Cette marche de base présente un inconvénient majeur : si un train part avec 1
 On distingue deux types de marges :
 
 - **La marge de régularité** : il s'agit du temps complémentaire ajouté à la marche de base pour tenir compte de l’imprécision de la mesure de la vitesse, pour pallier les conséquences des incidents extérieurs venant perturber la marche théorique des trains, et pour maintenir la régularité de la circulation. La marge de régularité s'applique sur l'ensemble du trajet, bien que sa valeur puisse changer sur certains intervalles.
-- **La marge de construction** : il s'agit du temps ajouté / retiré sur un intervalle spécifique, en plus de la marge de régularité, mais cette-fois pour des raisons opérationnelles (esquiver un autre train, libérer une voie plus rapidement, etc)
+- **La marge de construction** : il s'agit du temps ajouté / retiré sur un intervalle spécifique, en plus de la marge de régularité, mais cette fois pour des raisons opérationnelles (esquiver un autre train, libérer une voie plus rapidement, etc.)
 
 Une marche de base à laquelle on vient ajouter une marge de régularité donne ce que l'on appelle une **marche type**.
 
 ### <font color=#aa026d>La distribution de la marge</font>
 
 L'ajout de marge se traduisant par un abaissement des vitesses le long du trajet, plusieurs marches types sont possibles. En effet, il existe une infinité de solutions aboutissant au même temps de parcours.
 
-En guise d'exemple simple, pour détendre la marche d'un train de 10% de son temps de parcours, il est possible de prolonger n'importe quel arrêt de l'équivalent en temps de ces 10%, tout comme il est possible de rouler à 1/1.1 = 90,9% des capacités du train sur l'ensemble du parcours, ou encore de rouler moins vite, mais seulement aux vitesses élevées...
+En guise d'exemple simple, pour détendre la marche d'un train de 10% de son temps de parcours, il est possible de prolonger n'importe quel arrêt de l'équivalent en temps de ces 10%, tout comme il est possible de rouler à 1/1,1 = 90,9% des capacités du train sur l'ensemble du parcours, ou encore de rouler moins vite, mais seulement aux vitesses élevées...
 
 Il y a pour l'instant deux algorithmes de distribution de la marge dans OSRD : linéaire et économique.
 
@@ -41,8 +41,8 @@ Cette distribution a pour avantage de répartir la marge de la même manière su
 
 La distribution économique de la marge, présentée en détail dans [ce document](../MARECO.pdf), consiste à répartir la marge de la manière la plus économe possible en énergie. Elle est basée sur deux principes :
 
-1. Une vitesse plafond, évitant les vitesses les plus consommatrices en énergie
-2. Des zones de marche sur l'erre, situées avant les freinages et les fortes pentes, où le train circule à moteur coupé
+1. une vitesse plafond, évitant les vitesses les plus consommatrices en énergie
+2. des zones de marche sur l'erre, situées avant les freinages et les fortes pentes, où le train circule à moteur coupé
 grâce à son inertie, permettant de ne consommer aucune énergie pendant ce laps de temps
 
 ![Python plot eco with slopes](../python_plot_eco_w_slopes.png)

content/users/docs/running_time_calculation/envelopes_system.md

@@ -0,0 +1,36 @@
+---
+title: "3 - Le système d'enveloppes"
+linkTitle: "3 - Le système d'enveloppes"
+weight: 30
+---
+
+Le système d'enveloppes est une interface créée spécifiquement pour le calcul de marche d'OSRD. Il permet de manipuler différentes courbes espace/vitesse, de les découper, de les mettre bout à bout, d'interpoler des points spécifiques, et d'adresser beaucoup d'autres besoins nécessaires au calcul de marche.
+
+### <font color=#aa026d>Une interface spécifique dans le service OSRD Core</font>
+
+Le système d'enveloppes fait partie du service core d'OSRD (voir [l'architecture du logiciel](https://dgexsolutions.github.io/osrd-website/fr/users/docs/technical_and_physical_choices/architecture/)).
+
+Ses principaux composants sont :
+
+**1 - EnvelopePart :** courbe espace/vitesse, définie comme une séquence des points et possédant des métadonnées indiquant par exemple s'il s'agit d'une courbe d'accélération, de freinage, de maintien de vitesse, etc.
+
+**2 - Envelope :** liste d'EnvelopeParts mises bout-à-bout et sur laquelle il est possible d'effectuer certaines opérations :
+
+- vérifier la continuité dans l’espace (obligatoire) et dans la vitesse (facultative)
+- chercher la vitesse minimale et/ou maximale de l'enveloppe
+- couper une partie de l’enveloppe entre deux points de l'espace
+- effectuer une interpolation de vitesse à une certaine position
+- calculer le temps écoulé entre deux positions de l’enveloppe
+
+![envelope_scheme](../envelopes_scheme.png)
+
+**3 - Overlays :** système permettant d’ajouter des EnvelopePart plus contraignantes (c'est-à-dire dont la vitesse est plus faible) à une enveloppe existante.
+
+### <font color=#aa026d>Enveloppes données vs enveloppes calculées</font>
+
+Pendant la simulation, le train est censé suivre certaines instructions de vitesse. Celles-ci sont modélisées dans OSRD par des enveloppes sous forme de courbes espace/vitesse. On en distingue deux types :
+
+- Les enveloppes provenant **des données d'infrastructure et de matériel roulant**, comme la vitesse maximale de la ligne et la vitesse maximale du train. Etant des données d'entrée de notre calcul, elles ne correspondent pas à des courbes ayant un sens physique, car elles ne sont pas issues des résultats d'une intégration réelle des équations physiques du mouvement.
+- Les enveloppes résultant **d'une intégration réelle** des équations du mouvement physique. Elles correspondent à une courbe physiquement tenable par le train et contiennent également des informations sur le temps.
+
+Un exemple simple pour illustrer cette différence : si l'on simule un trajet de TER sur une ligne de montagne, une des données d'entrée va être une enveloppe de vitesse maximale à 160km/h, correspondant à la vitesse maximale de notre TER. Mais cette enveloppe ne correspond pas à une réalité physique, car il se peut que sur certaines portions la rampe soit trop raide pour que le train arrive effectivement à maintenir cette vitesse maximale de 160km/h. L'enveloppe calculée présentera donc dans cet exemple un décrochage de vitesse dans les zones de fortes rampes, là où l'enveloppe donnée était parfaitement plate.

content/users/docs/running_time_calculation/numerical_integration.md

@@ -1,7 +1,7 @@
 ---
-title: "3 - Intégration numérique"
-linkTitle: "Intégration numérique"
-weight: 30
+title: "2 - Intégration numérique"
+linkTitle: "2 - Intégration numérique"
+weight: 20
 ---
 
 <!-- script to auto-render KaTeX extension : $$..$$ for outline formula, //(...//) for inline formula -->
@@ -29,14 +29,14 @@ $$x(t+dt) = \frac{1}{2}a(v(t), x(t))dt^2 + v(t)dt + x(t)$$ <div style="text-alig
 
 #### **Les avantages de la méthode d'Euler**
 
-La méthode d'Euler a pour avantages d'être très simple à implémenter et d'avoir un calcul plutôt rapide pour un pas de temps donné, en comparaison avec d'autres méthodes d'intégration numériques (voir [annexe](#le-choix-de-la-m%C3%A9thode-dint%C3%A9gration-pour-osrd))
+La méthode d'Euler a pour avantages d'être très simple à implémenter et d'avoir un calcul plutôt rapide pour un pas de temps donné, en comparaison avec d'autres méthodes d'intégration numérique (voir [annexe](#le-choix-de-la-m%C3%A9thode-dint%C3%A9gration-pour-osrd))
 
 #### **Les inconvénients de la méthode d'Euler**
 
 La méthode d'intégration d'Euler présente un certain nombre de problèmes pour OSRD :
 
 - Elle est relativement imprécise, et donc nécessite un faible pas de temps, ce qui génère beaucoup de données.
-- En intégrant dans le temps, on ne connaît que les conditions du point de départ du pas d'intégration (pente, paramètres d'infrastructure, etc.) car on ne peut pas prédire précisément l'endroit où il se termine
+- En intégrant dans le temps, on ne connaît que les conditions du point de départ du pas d'intégration (pente, paramètres d'infrastructure, etc.) car on ne peut pas prédire précisément l'endroit où il se termine.
 - On ne peut pas anticiper les futurs changements de directive : le train ne réagit qu'en comparant son état actuel à sa consigne au même instant. Pour illustrer c'est un peu comme si le conducteur était incapable de voir devant lui, alors que dans la réalité il anticipe en fonction des signaux, pentes, virages qu'il voit devant lui.
 
 ### <font color=#aa026d>La méthode Runge-Kutta 4</font>
@@ -62,7 +62,7 @@ $$k_4 = a\Big(v(t+k_3dt), x(t) + v(t)dt + k_3\frac{dt^2}{2}\Big)$$
 
 La méthode d'intégration de Runge Kutta 4 permet de répondre aux différents problèmes soulevés par celle d'Euler :
 
-- Elle permet d'anticiper les changements de directive au sein d'un pas de calcul, représentant ainsi d'avantage la réalité de conduite d'un train
+- Elle permet d'anticiper les changements de directive au sein d'un pas de calcul, représentant ainsi davantage la réalité de conduite d'un train.
 - Elle est plus précise pour le même temps de calcul (voir [annexe](#le-choix-de-la-m%C3%A9thode-dint%C3%A9gration-pour-osrd)), permettant des étapes d'intégration plus grandes, donc moins de points de données.
 
 #### **Les inconvénients de la méthode de Runge Kutta 4**
@@ -95,9 +95,9 @@ Une courbe de référence a été simulée en utilisant la méthode d'Euler avec
 
 ![precisions_h_equivalent](../precisions_h_equivalent.png)
 
-Il apparaît immédiatement que la méthode d'Euler est d'environ d'un ordre de grandeur moins précise que les quatre autres. Chaque courbe présente un pic où la précision est extrêmement élevée (erreur extrêmement faible), ce qui  s'explique par le fait que toutes les courbes commencent légèrement au-dessus de la courbe de référence, la croisent en un point et finissent légèrement en dessous, ou vice-versa.
+Il apparaît immédiatement que la méthode d'Euler est moins précise que les quatre autres d'environ un ordre de grandeur. Chaque courbe présente un pic où la précision est extrêmement élevée (erreur extrêmement faible), ce qui  s'explique par le fait que toutes les courbes commencent légèrement au-dessus de la courbe de référence, la croisent en un point et finissent légèrement en dessous, ou _vice versa_.
 
-Mais comme la précision n'est pas le seul indicateur important, le temps de calcul de chaque méthode a été mesuré, et voici ce que nous obtenons pour les mêmes paramètres d'entrée :
+Comme la précision n’est pas le seul indicateur important, le temps de calcul de chaque méthode a été mesuré. Voici ce que nous obtenons pour les mêmes paramètres d’entrée :
 
 | Méthode d'intégration                    | Temps de calcul (s) |
 |:-----------------------------------------|--------------------:|