timetable: describe how margins and scheduled points interact

Author: multun

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

@@ -121,31 +121,46 @@ labels: ["INOUI", "TCHOU"]
 # used to select speed limits for simulation
 speed_limit_tags: ["MA100"]
 
-# the departure time has to have a timezone
-# all durations and times are specified using ISO 8601
-departure_time: "2023-12-21T08:51:11.914897+00:00"
+# the start time is an ISO 8601 datetime with timezone. it is not always the
+# same at the departure time, as there may be a stop at the starting point
+start_time: "2023-12-21T08:51:11.914897+00:00"
 
 path:
- - {id: a, waypoint: true, uic: 87210}
+ - {id: a, uic: 87210}
  - {id: b, track: foo, offset: 10}
- - {id: c, deleted: true, waypoint: true, trigram: ABC}
- - {id: d, waypoint: true, operational_point: operational_point.id}
-
-# the algorithm used for computing the standard margins AND scheduled points
-distribution_margins: MARECO
+ - {id: c, deleted: true, trigram: ABC}
+ - {id: d, operational_point: X}
 
-standard_margins:
-  # the begin and end waypoints are always implicitly added
-  intermediate_waypoints: [b]
-  values: ["5%", "2%"]
+# the algorithm used for distributing margins and scheduled times
+constraint_distribution: MARECO
 
 # all durations and times are specified using ISO 8601
-scheduled_points:
- - {at: a, arrival: PT0M, stop_for: PT5M}
- - {at: b, arrival: PT10M}
- - {at: c, arrival: PT25M}
-
-# train speed at departure, in meters per second
+# times are defined as time elapsed since start. Even if the attribute is omitted,
+# a scheduled point at the starting point is infered to have departure=start_time
+# the "locked" flag is ignored by the backend.
+schedule:
+ - {at: a, stop_for: PT5M, locked: true} # infered arrival to be equal to start_time
+ - {at: b, arrival: PT10M, departure: PT15M} # equivalent to a 5m stop
+ - {at: c, stop_for: PT5M}
+ - {at: d, arrival: PT50M, locked: true}
+
+margins:
+  # This example encodes the following margins:
+  #   a --- 5% --- b --- 3% --- d
+
+  # /!\ all schedule points with either an arrival or departure time must also be
+  # margin boundaries. departure and arrival waypoints are implicit boundaries. /!\
+  # boundaries delimit margin sections. A list of N boundaries yields N + 1 sections.
+  boundaries: [b]
+
+  # the following units are supported:
+  #  - 0 is a special value which indicates no margin. It's the default
+  #  - % means added percentage of the base simulation time
+  #  - min/km means minutes per kilometers
+  values: ["5%", "3%"]
+
+# train speed at simulation start, in meters per second.
+# must be zero if the train starts at a stop
 initial_speed: 2.5
 
 power_restrictions:
@@ -157,6 +172,57 @@ options:
   use_electrical_profiles: true
 ```
 
+
+# Combining margins and schedule
+
+Margins and scheduled points are two ways to add time constraints to a train's schedule.
+Therefore, there most be a clear set of rules to figure out how these two interfaces interact.
+
+Their interaction is defined as follows:
+
+ - The path is subdivided into **known time sections**, which are separated by locations where
+   an arrival or departure time is known. If the is no known arrival time at destination, a
+   **relaxed time section** is created between the end of the last known time section and the arrival
+   location.
+ - Margin boundaries separate margin section. Margin sections cover the entire path.
+ - Margin sections are grouped by known time section. It can only be done because
+   **margins are not allowed to cross known time section boundaries**.
+
+**The end goal is to compute a target time loss per margin section**.
+
+
+## Computing a target time loss per margin section
+
+The target time loss is computed as follows:
+
+ - A **base simulation** is computed, without any time constraint whatsoever.
+ - For each margin section, a provisional target time loss is computed based on the margin value and the base simulation.
+   The timetable that would be achieved if a train were to achieve these targets is called the **standard working**.
+ - For each known time section:
+    - compute the standard working trip duration for each margin section
+    - compute the total standard working trip duration for the known time section
+    - compute the difference between the standard working trip duration and the expected trip duration for the known time section.
+      This value is known as the schedule point impact.
+    - correct the provisional target time loss of margin sections by distributing the schedule point impact proportionally
+      to the standard working trip duration of each margin sections. The result is the target time loss.
+    - at this point, if the target time loss is negative on any section, it cannot be computed, and an
+      error is returned
+
+
+## Impossible margins
+
+It may occur that a target time loss cannot be achieved:
+
+- it can be too low, as transitions from high density margin to low margin section force the train to loose
+  time after it has exited to high density margin section.
+- it can also be too high, as the train may not have time to slow down enough, or drive so slow as to be
+  unacceptable.
+
+During simulation, if a target time loss cannot be achieved, the error value is added to the target time loss
+of the following section. This is a best effort measure to preserve scheduled points time targets despite failing
+margins.
+
+
 ## Endpoints
 
 ```