doc: stdcm: update the design docs (en)

Author: eckter

content/docs/reference/design-docs/stdcm/pathfinding_module/conflict_avoidance/index.en.md

@@ -57,4 +57,28 @@ computing an
 [engineering allowance]({{< ref "docs/explanation/running_time_calculation/allowances" >}} "allowances")
 is a feature of the running-time
 calculation module. It adds a given delay between two points of
-a path, without affecting the speeds on the rest of the path.
+a path, without affecting the speeds on the rest of the path.
+
+
+## Post-processing
+
+We **used to** compute the engineering allowances during the graph
+exploration, but that process was far too expensive. We used to
+run binary searches on full simulations, which would sometimes
+go back for a long distance in the path.
+
+What we *actually need* is to know whether an engineering allowance
+is *possible* without causing any conflict. We can use heuristics
+here, as long as we're on the conservative side: we can't
+say that it's possible if it isn't, but missing solutions with
+extremely tight allowances isn't a bad thing in our use cases.
+
+
+But this change means that, once the solution is found, we can't
+simply concatenate the simulation results. We need to run
+a full simulation, with actual engineering allowances,
+that avoid any conflict. This step has been merged
+with the one described on the
+[standard allowance]({{< ref "docs/reference/design-docs/stdcm/pathfinding_module/standard_allowance" >}} "standard allowance")
+page, which is now run even when no standard allowance
+have been set.

content/docs/reference/design-docs/stdcm/pathfinding_module/conflict_detection/index.en.md

@@ -0,0 +1,35 @@
+---
+title: "Conflict detection"
+linkTitle: "2 - Conflict detection"
+weight: 20
+---
+
+
+
+Once we know what paths we can use, we need to know when they
+can actually be used.
+
+The [documentation]({{< ref "docs/reference/design-docs/conflict-detection" >}} "documentation")
+of the conflict detection module explains how it's done internally.
+Generally speaking, a train is in conflict when it has to slow down
+because of a signal. In our case, that means the solution would not
+be valid, we need to arrive later (or earlier) to see the signal
+when it's not restricting anymore.
+
+The complex part is that we need to do the conflict detection *incrementally*
+Which means that:
+1. When running simulations up to t=x, we need to know all conflicts
+   that happen before x, *even if they're indirectly caused by a
+   signal seen at t > x* down the path.
+2. We need to know the conflicts and resource uses right as they start
+   even if their end time can't be defined yet.
+
+
+For that to be possible, we need to know where the train will go
+*after* the section that is being simulated (see
+[infra exploration]({{< ref "docs/reference/design-docs/stdcm/pathfinding_module/infrastructure_exploration" >}} "infra exploration"):
+we need some elements in the lookahead section).
+
+To handle it, the conflict detection module
+returns an error when more lookahead is required. When it happens
+we extend it by cloning the infra explorer objets.

content/docs/reference/design-docs/stdcm/pathfinding_module/infrastructure_exploration/index.en.md

@@ -0,0 +1,70 @@
+---
+title: "Infrastructure exploration"
+linkTitle: "1 - Infrastructure exploration"
+weight: 10
+---
+
+The first thing we need to define is *how we move through the infrastructure*,
+without dealing with conflicts yet.
+
+We need a way to define and enumerate the different possible paths and
+explore the infrastructure graph, with several constraints:
+1. The path must be compatible with the given rolling stock
+   (loading gauge / electrification / signaling system)
+2. At any point, we need to access path properties from its start up to the
+   considered point. This includes block and route lists.
+3. We sometimes need to know where the train will go *after* the
+   point being evaluated, for proper conflict detection
+
+
+
+To do this, we have defined the class `InfraExplorer`. It uses blocks
+(sections from signal to signal) as a main subdivision.
+It has 3 sections: the current block, predecessors, and a "lookahead".
+
+
+![InfraExplorer structure](infra_explorer.svg)
+
+
+In this example, the green arrows are the predecessor blocks.
+What happens there is considered to be immutable.
+
+The red arrow is the current block. This is where we run
+train and signaling simulations, and where we deal with conflicts.
+
+The blue arrows are part of the lookahead. This section hasn't
+been simulated yet, its only purpose is to know in advance
+where the train will go next. In this example, it would tell us
+that the bottom right signal can be ignored entirely.
+**A different `InfraExplorer` would be instantiated that would
+go toward the bottom section instead of the top one**,
+but this would be the path currently being evaluated.
+
+
+The `InfraExplorer` is manipulated with two main functions
+(the accessors have been removed here for clarity):
+
+```kotlin
+interface InfraExplorer {
+    /**
+     * Clone the current object and extend the lookahead by one route, for each route starting at
+     * the current end of the lookahead section. The current instance is not modified.
+     */
+    fun cloneAndExtendLookahead(): Collection<InfraExplorer>
+
+    /**
+     * Move the current block by one, following the lookahead section. Can only be called when the
+     * lookahead isn't empty.
+     */
+    fun moveForward(): InfraExplorer
+}
+```
+
+`cloneAndExtendLookahead()` is the method that actually enumerates the
+different paths, returning clones for each possibility.
+It's called when we need a more precise lookahead to properly identify
+conflicts, or when it's empty and we need to move forward.
+
+A variation of this class can also keep track of the train simulation
+and time information (called `InfraExplorerWithEnvelope`).
+This is the version that is actually used to explore the infrastructure.