document conflict detection behavior

content/developers/internals/conflicts.md

@@ -0,0 +1,60 @@
+---
+title: "Détection des conflits"
+linkTitle: "Conflits"
+weight: 100
+description: "Détecte les conflits entre les différents train de la grille horaire"
+---
+
+## Définition
+
+Normalement, chaque signal vu par un train devrait afficher son état
+le moins restrictif (généralement voie libre).
+Si un train voit un autre état à cause de la présence d'un autre train dans
+la grille horaire, on considère que les deux trains sont en conflit.
+
+## Fonctionnement
+
+_note: le comportement décrit ici n'est pas encore implémenté,
+la détection est pour l'instant très simplifiée._
+
+
+### Core
+
+Quand on réalise un calcul de marche dans le core, la réponse inclue
+des informations sur l'état de la signalisation. D'une part elle contient
+les changements d'états des signaux, à afficher sur le graphique espace
+temps et sur la carte, mais ces informations ne sont pas suffisantes pour
+détecter les conflits. Il y a donc, d'autre part, un ensemble d'intervalles
+où un signal est considéré comme "non libre". Ce sont ces intervalles qui
+sont utilisés pour détecter les conflits.
+
+Le calcul de ces intervalles utilise une simulation de la signalisation,
+mais avec un comportement particulier sur les itinéraires. La signalisation
+considère que chaque itinéraire est enclenché quand il _peut_ l'être. Ainsi, on
+peut correctement calculer la cascade de signaux en amont d'un carré marquant
+le début d'un itinéraire en conflit avec le train simulé.
+
+_todo: faire beaucoup de dessins parce que c'est pas clair_
+
+
+### API
+
+Le service d'API a accès aux résultats de chaque simulation, et des nouveaux
+appels au core seraient superflus. C'est donc ce service qui calcule les
+conflits.
+
+Pour chaque signal sur le parcours des trains, pendant l'intervalle de temps
+où il est visible par le train, on cherche s'il est marqué
+comme "non libre" par un autre train. Si c'est le cas, on note un conflit
+qui débute à l'instant où le signal est vu sous un état non libre, et
+se termine quand il est de nouveau libre.
+
+Par exemple : si un signal montre un sémaphore de t=100 à t=200
+puis un avertissement de t=200 à t=300,
+et qu'un autre train voit le signal à partir de t=150, on note
+un conflit de t=150 à t=300.
+
+Un conflit est exprimé sous la forme d'un temps de début, un temps de fin,
+et un identifiant de signal ou de canton. Si le canton est sur le chemin
+projeté, on ajoute des informations de position permettant
+d'afficher le conflit.

content/developers/internals/conflicts_ressources.md

@@ -0,0 +1,70 @@
+---
+title: "Détection des conflits"
+linkTitle: "Conflits"
+weight: 100
+description: "Cette page décrit comment sont détectés les conflits entre les
+différents train de la grille horaire"
+---
+
+## Définition
+
+Normalement, chaque signal vu par un train devrait afficher son état
+le moins restrictif (généralement voie libre).
+Si la présence d'un train dans la grille horaire fait qu'un autre
+train voit un état plus contraignant (par exemple qui lui impose
+de ralentir), on considère que les deux trains sont en _conflit_.
+
+
+## Fonctionnement de la détection des conflits
+
+_note: le comportement décrit ici n'est pas encore implémenté,
+la détection est pour l'instant très simplifiée et limitée
+au chemin projeté._
+
+
+La détection de conflits se fait en plusieurs temps, avec plusieurs
+appels entre les services.
+
+Le premier calcul de marche demandé au core renvoie entre autres une liste
+d'utilisation de zones. Ensuite, au moment de lister les conflits, on demande
+une seconde simulation pour chaque train en prenant en compte
+les zones utilisées par les autres trains.
+
+
+_todo: insérer un schéma des appels_
+
+
+### Core : calcul de marche initial
+
+Quand on réalise un calcul de marche dans le core, la réponse inclue
+déjà des informations sur l'état de la signalisation, mais ce
+n'est pas suffisant pour détecter les conflits. On ajoute donc
+des informations qui permetteront plus tard de les détecter :
+pour chaque zone par laquelle passe le train, on note l'intervalle de temps
+où elle est utilisée par le train et dans quelle configuration.
+
+
+### API : réreption d'une requête demandant les conflits
+
+Quand le service d'API reçoit une demande des conflits, on demande au core
+d'effectuer une simulation de la signalisation pour chaque train, en prenant
+en compte les utilisations des zones des autres trains.
+
+
+### Core : seconde simulation de signalisation et détection des conflits
+
+Pour chaque train, on effectue une simulation de la signalisation qui prend
+en compte les utilisations de zone des autres trains.
+Dès que le train voit un signal qui n'est pas
+à son état le moins restrictif, on note un conflit depuis ce moment jusqu'à
+l'instant où le signal revient à son état attendu.
+
+
+## Difficultés avec cette méthode
+
+* On doit effectuer beaucoup de simulations à chaque modification
+* Il faut être capable de forcer des états de zones dans la simulation
+de la signalisation, en gérant des états incompatibles
+* Il peut être difficile de déterminer la durée d'un conflit :
+on doit savoir quand le signal serait revenu à son état normal
+_sans le second train_