Design notes for interactions between signaling, speed sections, and routes

content/docs/reference/design-docs/signaling/_index.en.md

@@ -0,0 +1,84 @@
+---
+title: "Signaling"
+linkTitle: "Signaling"
+weight: 43
+description: "Describes the signaling model"
+---
+
+## Description
+
+The signaling layer includes all signals, which respond to track occupancy and
+reservation. Signals can be of different types, and are modularly loaded. Only
+their behavior towards the state of the infrastructure and the train's reaction
+to signaling matters.
+
+Signals are connected to each other by blocks. Blocks define paths permitted
+by signaling.
+
+## Goals
+
+The signaling system is at the crossroads of many needs:
+
+- it must allow for realistic signaling simulation in a multi-train simulation
+- it must allow the conflict detection system to determine which resources are required for the train
+- it must allow application users to edit and display signals
+- it must allow for visualization of signals on a map
+- it must allow for automated import from existing databases
+
+## Design requirements:
+
+All static data:
+
+- must enable the front-end to display the signals
+- must enable the infrastructure editor to configure signals
+- must enable the back-end to simulate signals
+- must be close to realistic industry models
+- must allow for the modeling of composite signals, which carry several
+  logical signals within a single physical signal
+
+To simulate signaling:
+
+- blocks must be generated for both user convenience and **pathfinding**
+- for each signal, its **next compatible signal** and **protected zones** must be deduced
+- the **minimum necessary information** must be provided to the signaling modules for their operation
+- enable using signaling modules without instantiating a complete simulation
+- allow for signals to be loaded in any order, in parallel
+
+For speed limits:
+
+- some speed limits have to be enforced depending on the train path's routes
+- speed limits can be configured to have an impact on signaling
+- ability to link the reaction of the train to a signal, and a speed limit
+
+
+## Assumptions
+
+- Each physical signal can be decomposed into a list of logical signals, all of which are associated with a signaling system.
+- Blocks have a type.
+- It is possible to compute, given a signal alone, its block and route delimiting properties.
+- Blocks never cross route boundaries.
+- Blocks which are not covered by routes do not exist, or can be ignored.
+- At any time, trains only use one signaling system capable of transmitting movement authority.
+- Speed limits change depending on which route is in use, and affect how signals behave
+- Some speed limits have an impact on signaling, and some do not
+- Either a speed limits differentiates per train category, or requires dynamic signaling, but not both
+
+## Operations
+
+- **Instantiating a view** creates a framework for observing signals
+- **Planning the path signals** to the view the blocks that the train will traverse
+- **Observing a signal** subscribe to the state of a signal (through the view)
+- **Passing a signal** signals that a signal has been passed by the train (through the view)
+
+## Research Questions
+
+- Are there any blocks that overlap the end of a route? SNCF(Loïc): No.
+- Are there any signals which rely on the state of the one after next signal? SNCF(Loïc): No.
+- Are there signals that change behavior based on the active block in front of them? SNCF(Loïc): Yes, for slowdowns.
+- Are there signals that are the start of blocks of different types? SNCF(Loïc): Yes.
+- Can the behavior of a signal depend on which block is active after the end of the current block? SNCF(Loïc): Yes, with slowdowns or blinking yellow.
+- Do some signaling systems need additional information in the blocks? SNCF(Loïc): Kind of, there are slowdowns, but it's not specifically carried by the block.
+- Is it nominal for a train to have multiple active signaling systems at the same time? SNCF(Loïc): No.
+- are there any signals which depend on which route is set, but are not route delimiters? SNCF(Loïc): Yes, see Sémaphore Clignotant
+- how do speed limits per train category and dynamic signaling interact? SNCF(Nicolas): There shouldn't be any speed limit per category signaled by dynamic signaling
+- are there any signals which depend on the state of multiple routes? SNCF(Loïc): No

content/docs/reference/design-docs/signaling/blocks-and-signals.en.md

@@ -0,0 +1,181 @@
+---
+title: "Blocks and signals"
+linkTitle: "Blocks and signals"
+weight: 20
+---
+
+
+# Blocks
+
+The blocks have several attributes:
+
+- A signaling system that corresponds to that displayed by its first signal.
+- A **path**, which is a list of direction + detector pairs (just like route paths).
+- An **entry signal**, (optional when the block starts from a buffer stop).
+- **Intermediate signals**, if any (only used by systems with distant signals).
+- An **exit signal**, (optional when the block ends at a buffer stop).
+
+The path is expressed from detector to detector so that it can be overlayed with the route graph.
+
+A few remarks:
+
+- There can be multiple blocks with the same path, as long as they have different signaling systems. Trains only use a block at a time, and ignore others.
+- Blocks do not have a state: one can rely on the dynamic state of the zones that make it up.
+- Blocks are used to figure out which signals protect which zones in a given context.
+
+## Dependencies
+
+   - route graph. For each route:
+       - `waypoints: List<DiDetector>`
+       - `signals: OrderedMap<Position, UnloadedSignal>`
+       - `speed_limits: RangeMap<Position, SpeedLimit>`, including the logic for train category limits
+   - signaling systems
+   - drivers
+
+
+# Signals
+
+Physical signal are made up of one or more logical signals, which are displayed as a single unit on the field. During simulation, logical signals are treated as separate signals.
+
+Each logical signal is associated with a signaling system, which defines if the
+signal transmits Movement Authority, speed limits, or both.
+
+Logical signals have one or more drivers. Signal drivers are responsible for computing
+signal state. Any given signal driver only works for a given pair of signaling systems,
+where the first one is displayed by the signal, and the second is the one displayed by
+the next signal.
+
+When a logical signal has an empty driver list, its content is deduced from neighboring signals.
+
+For example, a BAL signal that is both a departure of the TVM block and a
+departure of the BAL block, it will have two drivers: `BAL-BAL` and `BAL-TVM`.
+
+## Announcing speed limits
+
+When a signal announces a speed limit, it needs to be linked with a speed section object.
+This is meant to enable smooth transitions between the reaction to the announce signal, and the limit itself.
+
+If multiple signals are involved in the announce process, only the one closest to the speed limit has to have
+this attribute set.
+
+```yaml
+{
+    # ...
+    "announce_speed_section": "${SPEED_SECTION_ID}"
+    # ...
+}
+```
+
+## Conditional parameters
+
+Some signal parameters vary depending on which route is set. On each signal, an arbitrary number of rules can be added.
+If the signal is last to announce a speed limit, it must be explicitly mentionned in the rule.
+
+```yaml
+{
+    # ...
+    "announce_speed_section": "${SPEED_SECTION_ID}",
+    "default_parameters": {"short_block": "false"},
+    "conditional_parameters": [
+        {
+            "on_route": "${ROUTE_ID}",
+            "announce_speed_section": "${SPEED_SECTION_ID}",
+            "parameters": {"rappel30": "true", "short_block": "true"}
+        }
+    ]
+    # ...
+}
+```
+
+Signal parameter values are looked up in the following order:
+1) per route conditional parameters
+2) per signal default parameters (`default_parameters`)
+3) parameter default value, from the signaling system's `.signal_parameters[].default`
+
+
+## Serialized format
+
+The serialized / raw format is the user-editable description of a physical signal.
+
+Raw signals have a list of logical signals, which are independently simulated units sharing
+a common physical display. Each logical signal has:
+
+- a signaling system
+- user-editable properties, as specified in the signaling system description
+- a list of default parameters, which can get overriden per-route
+- an optional announced speed section, which can get overriden per-route
+- a list of allowed next signaling systems, which are used to load drivers
+
+For example, this signal encodes a BAL signal which:
+- starts both a BAL and a TVM block
+- announces speed limit B on all routes except route A, where speed limit C is announced
+- on route A, the block is shorter than usual
+
+```yaml
+{
+    # signals must have location data.
+    # this data is omitted as its format is irrelevant to how signals behave
+
+    "logical_signals": [
+        {
+            # the signaling system shown by the signal
+            "signaling_system": "BAL",
+            # the settings for this signal, as defined in the signaling system manifest
+            "properties": {"has_ralen30": "true", "Nf": "true"},
+            # this signal can react to BAL or TVM signals
+            # if the list is empty, the signal is assumed to be compatible with all following signaling systems
+            "next_signaling_systems": ["BAL", "TVM"]
+            "announce_speed_section": "${SPEED_SECTION_B}",
+            "default_parameters": {"rappel30": "true", "short_block": "false"},
+            "conditional_parameters": [
+                {
+                    "on_route": "${ROUTE_A}",
+                    "announce_speed_section": "${SPEED_SECTION_C}",
+                    "parameters": {"short_block": "true"}
+                }
+            ]
+        }
+    ]
+}
+```
+
+For example, this signal encodes a BAL signal which starts a BAL block, and shares its physical display / support with a BAPR signal starting a BAPR block:
+```yaml
+{
+    # signals must have location data.
+    # this data is omitted as its format is irrelevant to how signals behave
+
+    "logical_signals": [
+        {
+            "signaling_system": "BAL",
+            "properties": {"has_ralen30": "true", "Nf": "true"},
+            "next_signaling_systems": ["BAL"]
+        },
+        {
+            "signaling_system": "BAPR",
+            "properties": {"Nf": "true", "distant": "false"},
+            "next_signaling_systems": ["BAPR"]
+        }
+    ]
+}
+```
+
+## Signal description strings
+
+Signal definitions need to be condensed into a shorter form, just to look up signal icons.
+In order to store this into MVT map tiles hassle free, it's condensed down into a single string.
+
+It looks something like that: `BAL[Nf=true,ralen30=true]+BAPR[Nf=true,distant=false]`
+It's built as follows:
+- a list of logical signals, sorted by signaling system name, separated by `+`
+- inside each logical signal, signal properties are sorted by name, enclosed in square brackets and separated by `,`
+
+
+## Dependencies
+
+For signal state evaluation:
+
+   - train path in blocks
+   - portion of the path to evaluate
+   - drivers
+   - state of the zones in the section to evaluate

content/docs/reference/design-docs/signaling/signaling-systems.en.md

@@ -0,0 +1,57 @@
+---
+title: "Signaling systems"
+linkTitle: "Signaling systems"
+weight: 10
+---
+
+Each signaling system has:
+
+- A unique identifier (a string).
+- Its signal state type, which enables deducing:
+    - The graphical representation of the signal
+    - How a train would react to the signal
+    - If the signal state constrains Movement Authority
+- The signal parameter types, names and description, which enable front-end edition of signal parameters.
+- The block and route conditions, which enable evaluating whether a signal delimits blocks or routes, given its parameters.
+
+
+```yaml
+{
+    # unique identifier for the signaling system
+    "id": "BAL",
+    "version": "1.0",
+    # the schema of the dynamic state of signals of this type
+    "signal_state": [
+        {"kind": "enum", "field_name": "aspect", values: ["VL", "A", "S", "C"]},
+        {"kind": "flag", "field_name": "ralen30"},
+        {"kind": "flag", "field_name": "ralen60"},
+        {"kind": "flag", "field_name": "ralen_rappel"}
+    ],
+    # describes static properties of the signal
+    "signal_properties": [
+        {"kind": "flag", "field_name": "Nf", "display_name": "Non-franchissable"},
+        {"kind": "flag", "field_name": "has_ralen30", "default": false, "display_name": "Ralen 30"},
+        {"kind": "flag", "field_name": "has_rappel30", "default": false, "display_name": "Rappel 30"},
+        {"kind": "flag", "field_name": "has_ralen60", "default": false, "display_name": "Ralen 60"},
+        {"kind": "flag", "field_name": "has_rappel60", "default": false, "display_name": "Rappel 60"}
+    ],
+    # describes dynamic properties of the signal. These can be set on a per-route basis
+    "signal_parameters": [
+        {"kind": "flag", "field_name": "short_block", "default": false, "display_name": "Short block"},
+        {"kind": "flag", "field_name": "rappel30", "default": false, "display_name": "Rappel 30"},
+        {"kind": "flag", "field_name": "rappel60", "default": false, "display_name": "Rappel 60"}
+    ],
+
+    # these are C-like boolean expressions:
+    # true, false, <flag>, <enum> == value, &&, || and ! can be used
+
+    # used to evaluate whether a signal is a block boundary. Only properties can be used, not parameters.
+    "block_boundary_when": "true",
+
+    # used to evaluate whether a signal is a route boundary. Only properties can be used, not parameters.
+    "route_boundary_when": "Nf",
+
+    # A predicate used evaluate whether a signal state can make a train slow down. Used for naive conflict detection.
+    "constraining_ma_when": "aspect != VL"
+}
+```