From c9a7bd188f8a4fb8e732a301800cc0b32ad05a2e Mon Sep 17 00:00:00 2001 From: "Victor \"multun\" Collod" Date: Wed, 28 Feb 2024 17:57:35 +0100 Subject: [PATCH] fix the toc --- .../running-time-calculation/_index.en.md | 32 ++++++++++--------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/content/docs/reference/design-docs/running-time-calculation/_index.en.md b/content/docs/reference/design-docs/running-time-calculation/_index.en.md index fa7b025ae..1cec5b5f5 100644 --- a/content/docs/reference/design-docs/running-time-calculation/_index.en.md +++ b/content/docs/reference/design-docs/running-time-calculation/_index.en.md @@ -21,7 +21,7 @@ changes are required to meet our needs. This document goes into: - a list of questions designed to challenge design limits, answered by domain experts -# System requirements +## System requirements The new system is expected to: @@ -41,7 +41,7 @@ In the long-term, this system is expected to: - integrate driver behavior properties -# Previous implementation +## Previous implementation The current implementation has a number of shortcomings make it pretty much impossible to evolve to meet current system requirements. It also has a number of less severe flaws, such as the over-reliance @@ -55,7 +55,7 @@ The previous implementation cannot be changed to: These limitations are the primary reasons for this redesign. -## Margins +### Margins - are defined as post-processing filter passes on simulation results. This has a number of undesirable side effects: @@ -78,7 +78,7 @@ These limitations are the primary reasons for this redesign. in the section. -## Input modeling +### Input modeling With the previous implementation, the simulation takes sequence of constraint position and speed curves as an input (continuous in position, can be discontinuous in speed), and produces a continuous curve. @@ -90,7 +90,7 @@ The output is fine, but the input is troublesome: - constraints cannot evolve over time, and cannot be interpreted differently depending on when the train reached these constraints - constraints cannot overlap. the input is pre-processed to filter out obscured constraints -# Design specification +## Design specification ```mermaid flowchart TD @@ -134,7 +134,7 @@ SimResults[simulation result curve] ``` -## Driving instructions +### Driving instructions Driving instructions model what the train has to do, and under what conditions. Driving instructions are generated using domain constraints such as: @@ -147,6 +147,7 @@ Driving instructions are generated using domain constraints such as: - dynamically signaled speed restrictions - neutral zones - stops +- margins There are two types of driving instructions: @@ -171,7 +172,7 @@ Compiler --> ConcreteDrivingInstruction ``` -### Interpreting driving instructions +#### Interpreting driving instructions During the simulation, driving instructions are partitionned into 4 sets: @@ -215,7 +216,7 @@ These sets evolve as follows: - when simulation state exceeds an instruction's retirement position, it becomes `RETIRED` -### Overrides +#### Overrides When an instruction transitions to the `RECEIVED` or `ENFORCED` state, it can disable active instructions which match some metadata predicate. There are two metadata attributes which can be relied on for overrides: @@ -228,7 +229,7 @@ This is required to implement a number of signaling features, as well as stops, by the restart instruction. -### Data model +#### Data model @@ -281,9 +282,9 @@ enum RankRelation { ``` -# Design decisions +## Design decisions -## Lowering constraints to an intermediate representation +### Lowering constraints to an intermediate representation Early on, we started making lists of what domain constraints can have an impact on train behavior. Meanwhile, to simulate train behavior, we figured out that we need to know which constraints apply at any given time. @@ -293,7 +294,7 @@ There's a fundamental tension between these two design constraints, which can be - either treat each type of constraint as its own thing during the simulation - abstract away constraints into a common representation, and then simulate that -### {{< rejected >}} Distinct constraint types +#### {{< rejected >}} Distinct constraint types When we first started drafting architecture diagrams, the train simulation API directly took a bunch of constraint types as an input. It brought up a number of issues: @@ -304,7 +305,7 @@ a bunch of constraint types as an input. It brought up a number of issues: We couldn't find clear benefits to dragging distinctions between constraint types deep into the implementation -### {{< rejected >}} Internal constraint types abstraction +#### {{< rejected >}} Internal constraint types abstraction We then realized that abstracting over constraint types during simulation had immense benefits: @@ -318,7 +319,7 @@ We decided the explore the possibility of keeping constraint types distinct in t - the public simulation API would still bear the complexity of dealing with many constraint types - there would be a need to incrementaly generate internal abstracted constraints to support the incremental API -### {{< adopted >}} External constraint types abstraction +#### {{< adopted >}} External constraint types abstraction We tried to improve over the previous proposal by moving the burden of converting many constraints into a common abstraction out of the simulation API. We found that doing so: @@ -327,7 +328,7 @@ We tried to improve over the previous proposal by moving the burden of convertin API only needs expansion if the expected behavior expected for this constraint isn't part of the API. -## Interpreting driving instructions +### Interpreting driving instructions As the train progresses through the simulation, it reacts according to driving instructions which depend on more than the bare train physics state (position, time, and speed): @@ -358,3 +359,4 @@ We quickly settled on adding a kind field, but had a lengthy discussion over how - {{< rejected >}} adding `source` metadata, which was rejected as it does not address the issue of upstream / downstream - {{< rejected >}} adding identifiers to instructions, and overriding specific instructions, which was rejected as it makes instruction generation and processing more complex - {{< adopted >}} adding some kind of priority / rank field, which was adopted +