rs-categories: add documentation for rs categories and open-data rs (#…

…275)

* rs-categories: add documentation for rolling stock categories and open-data rolling stocks

Signed-off-by: Louis Greiner <[email protected]>

* typos: fix typos

Signed-off-by: Louis Greiner <[email protected]>

---------

Signed-off-by: Louis Greiner <[email protected]>

content/docs/explanation/models/realistic-rolling-stocks/_index.en.md

@@ -0,0 +1,57 @@
+---
+title: "Rolling stock categories"
+linkTitle: "Rolling stock categories"
+weight: 20
+description: "Defines rolling stock categories"
+---
+
+Categories are groupings of rolling stock, either by their characteristics, performance or by the nature of the services for which they have been designed or are used.
+
+The same rolling stock can be used for different types of operations and services. This versatility is reflected in the following attributes:
+- `primary_category` (required) indicates the main use of a rolling stock
+- `other_categories` (optional) indicates other possible uses of a rolling stock
+
+The primary category of a rolling stock enables several features, such as filtering, differentiated display on charts or network graphic views, and, more broadly, the aggregation of rolling stocks.
+
+#### Categories of rolling stocks
+
+The different default rolling stock categories are as follows:
+
+- `High-speed train` (see [High-speed train](https://en.wikipedia.org/wiki/High-speed_rail))
+- `Intercity train` (see [Intercity train](https://en.wikipedia.org/wiki/Inter-city_rail))
+- `Regional train` (see [Regional train](https://en.wikipedia.org/wiki/Regional_rail))
+- `Commuter train` (see [Commuter train](https://en.wikipedia.org/wiki/Commuter_rail))
+- `Freight train` (see [Freight train](https://en.wikipedia.org/wiki/Rail_freight_transport))
+- `Fast freight train` (same as Freight train, but with a different composition code, `ME140` instead of `MA100` for example)
+- `Night train` (see [Night train](https://en.wikipedia.org/wiki/Sleeping_car))
+- `Tram-train` (see [Tram-train](https://en.wikipedia.org/wiki/Tram-train))
+- `Touristic train` (see [Touristic train](https://en.wikipedia.org/wiki/Heritage_railway))
+- `Work train` (see [Work train](https://en.wikipedia.org/wiki/Work_train))
+
+It is also planned that, in the future, a user will be able to create new rolling stock categories directly.
+
+### Realistic open data rolling stocks
+
+To make the application more accessible to users outside the railway industry, such as external contributors and research laboratories, and to prepare for the release of the public playground version of OSRD, several rolling stock created with mock data are available to all users.
+
+These rolling stocks are designed to cover most simulation scenarios that users may encounter.
+
+These rolling stocks are not actual rolling stocks, due to confidentiality reasons, but they have been created based on real data to ensure a high level of realism.
+
+The rolling stocks are provided as [JSON files](https://github.com/OpenRailAssociation/osrd/tree/dev/tests/data/rolling_stocks). We created one representative rolling stock for each category listed above.
+
+The characteristics of these rolling stocks have been calculated based on the average values of real rolling stocks within each category. Additionally, most of these models are designed to be compatible across various networks: they are primarily bi-mode (supporting multiple electric voltage and current supply types), which is not always the case for real-world rolling stocks.
+
+An example of rolling stock, a **high-speed train**, is represented below, from the rolling stock editor of the application:
+
+![Rolling stock](high-speed-rolling-stock.en.png)
+
+#### Open data
+
+Since these rolling stocks are fictional (yet realistic), they can be freely used in projects beyond OSRD.
+
+To access and use them in the application:
+
+- **From the open-source playground:** The rolling stocks are available by default.
+
+- **From a locally launched application:** Use the corresponding command in the [README](https://github.com/OpenRailAssociation/osrd/blob/dev/README.md) to import the test rolling stocks in your database.

content/docs/explanation/models/realistic-rolling-stocks/_index.fr.md

@@ -0,0 +1,62 @@
+---
+title: "Catégories de matériels roulants"
+linkTitle: "Catégories de matériels roulants"
+weight: 20
+description: "Définit les catégories de matériels roulants"
+---
+
+Les catégories sont des regroupements de matériel roulant, soit par leurs caractéristiques, leurs performances ou par la nature des dessertes pour lesquelles ils ont été conçus ou sont utilisés.
+
+Un même matériel roulant peut être utilisé pour différents types de circulation, et de desserte. Ce caractère versatile est contenu dans les attributs :
+- `primary_category` (requis) indique l'utilisation principale d'un matériel roulant
+- `other_categories` (optionnel) indique les autres utilisations d'un matériel roulant
+
+La catégorie principale d'un matériel roulant permet plusieurs fonctionnalités, comme le filtrage, un affichage différencié sur les graphiques ou réticulaire, et plus globalement, d'agréger des matériels roulants. 
+
+#### Catégories de matériels roulants
+
+Les différentes catégories de matériel roulant disponibles par défaut sont les suivantes :
+
+- `Train à grande vitesse` (voir [High-speed train](https://fr.wikipedia.org/wiki/Train_%C3%A0_grande_vitesse))
+- `Train interurbain` (voir [Intercity train](https://fr.wikipedia.org/wiki/InterCity))
+- `Train régional` (voir [Regional train](https://en.wikipedia.org/wiki/Regional_rail))
+- `Train suburbain` (voir [Commuter train](https://fr.wikipedia.org/wiki/Train_de_banlieue))
+- `Train de fret` (voir [Freight train](https://fr.wikipedia.org/wiki/Train_de_fret))
+- `Train de fret rapide` (pareil que Train de fret, mais avec un code de composition différent, `ME140` au lieu de `MA100` par exemple)
+- `Train de nuit` (voir [Night train](https://fr.wikipedia.org/wiki/Train_de_nuit))
+- `Tram-train` (voir [Tram-train](https://fr.wikipedia.org/wiki/Tram-train))
+- `Train touristique` (voir [Touristic train](https://fr.wikipedia.org/wiki/Chemin_de_fer_touristique))
+- `Train de travaux` (voir [Work train](https://fr.wikipedia.org/wiki/Train_de_travaux))
+
+Il est aussi prévu que, plus tard, un utilisateur puisse créer directement de nouvelles catégories de matériel roulant.
+
+### Matériels roulants réalistes open data
+
+Afin de rendre l’application plus accessible aux utilisateurs en dehors de l’industrie ferroviaire, tels que des contributeurs externes et des laboratoires de recherche, et de préparer la sortie de la version publique "bac à sable" d'OSRD, plusieurs matériels roulants créés avec des données fictives sont disponibles pour tous les utilisateurs.
+
+Ces matériels roulants ont été conçus pour couvrir la majorité des scénarios de simulation que les utilisateurs pourraient rencontrer.
+
+Ces matériels roulants ne sont pas des matériels roulants existant réellement en raison de la confidentialité des données, mais ils s’en inspirent pour garantir le réalisme des simulations.
+
+Ces matériels roulants sont fournis sous forme de [fichiers JSON](https://github.com/OpenRailAssociation/osrd/tree/dev/tests/data/rolling_stocks). Nous avons créé un matériel roulant représentatif de chaque catégorie présentée ci-dessus.
+
+Les caractéristiques de ces matériels roulants ont été calculées à partir des valeurs moyennes des matériels roulants réels de chaque catégorie. De plus, la plupart de ces modèles ont été conçus pour être compatibles avec divers réseaux : ils sont principalement bi-modes (supportant plusieurs tensions et courants d'alimentation), ce qui n’est pas toujours le cas des matériels roulants réels.
+
+Un exemple de matériel roulant, un **train à grande vitesse**, est représenté ci-dessous, depuis l'éditeur de matériel roulant de l'application :
+
+![Matériel roulant](high-speed-rolling-stock.fr.png)
+
+#### Open data
+
+Puisque ces matériels roulants sont fictifs (mais réalistes), ils peuvent être librement utilisés dans des projets en dehors d’OSRD.
+
+Pour y avoir accès et les utiliser dans l'application :
+
+- **Depuis l'application open-source "bac à sable" :** Les matériels roulants sont disponibles par défaut.
+
+- **Depuis une application lancée localement :** Utilisez la commande associée dans le [README](https://github.com/OpenRailAssociation/osrd/blob/dev/README.md) pour importer les matériels roulants de test dans votre base de données.
+
+```sh
+./scripts/load-railjson-rolling-stock.sh tests/data/rolling_stocks/realistic/*.json
+```
+

content/docs/explanation/running_time_calculation/_index.en.md

@@ -25,7 +25,7 @@ A running time calculation is based on 5 inputs:
 
 - **The rolling stock:** The characteristics of which needed to perform the simulation are shown below.
 
-![Rolling Stock Material](mat_roulant.png)
+![Rolling Stock Material](../models/realistic-rolling-stocks/high-speed-rolling-stock.en.png)
 
 > The orange curve, called the effort-speed curve, represents the maximum motor effort as a function of the speed of travel.
 >

content/docs/explanation/running_time_calculation/_index.fr.md

@@ -25,7 +25,7 @@ Un calcul de marche est basé sur 5 entrées :
 
 - **Le matériel roulant :** Dont les caractéristiques nécessaires pour effectuer la simulation sont représentées ci-dessous.
 
-![Matériel roulant](mat_roulant.png)
+![Matériel roulant](../models/realistic-rolling-stocks/high-speed-rolling-stock.fr.png)
 
 > La courbe orange, appelée courbe effort-vitesse du matériel, représente l'effort moteur maximal en fonction de la
 > vitesse de circulation.

content/docs/reference/design-docs/timetable/index.en.md

@@ -301,13 +301,13 @@ GET /paced_train/ID/path?infra_id=42 # Retrieve the path from a paced_train
 # Retrieve the list of conflict of the timetable (invalid trains are ignored)
 GET /timetable/ID/conflicts?infra=N
 # Retrieve the space, speed and time curve of a given train
-GET /train_schedule/ID/simulation?infa=N
+GET /train_schedule/ID/simulation?infra=N
 # Retrieve the space, speed and time curve of a given paced train
-GET /paced_train/ID/simulation?infa=N
+GET /paced_train/ID/simulation?infra=N
 # Retrieves simulation information for a given train list. Useful for finding out whether pathfinding/simulation was successful.
-GET /train_schedule/simulations_sumary?infa=N&ids[]=X&ids[]=Y
+GET /train_schedule/simulations_summary?infra=N&ids[]=X&ids[]=Y
 # Retrieves simulation information for a given paced train list. Useful for finding out whether pathfinding/simulation was successful.
-GET /paced_train/simulations_sumary?infa=N&ids[]=X&ids[]=Y
+GET /paced_train/simulations_summary?infra=N&ids[]=X&ids[]=Y
 # Projects the space time curves and paths of a number of train schedules onto a given path
 POST /v2/train_schedule/project_path?infra=N&ids[]=X&ids[]=Y
 # Projects the space time curves and paths of a number of paced trains onto a given path