Placement of sensors
====================

Sensors have been placed so that they "sorround" all switches; this
way we can at all times control entry and exit from all critical
sections.

Another way to see it is that sensors are placed *before* every
critical section, in such a way that every train has time to stop
*before* entering it. In our code, all sensors have a direction, with
which we can deduce what critical section the train is entering. (Or
rather, wether it is *entering* or *exiting* a critical section.)

Additionally, sensors have been placed in the stations, far enough
from the track terminus that they have time to stop.

Choice of critical sections
===========================

The critical sections have been chosen as seen in the figure below:

      +-----(S1)-------
      |         STATION
      |  +---S1--------
      |  | J1
      |  |/
      +--+------+---+
         +------+   |
                    C1
                    |
    +--+----P1---+--+
    |  +---(P2)--+
    C2
    |
    +-+-----(S2)-------
      |         STATION
      +------S2--------

A switch belongs to the critical section connected to its "single"
side, i.e. in this situation, the switch belongs to `C`:

             __D___
            /
    --C----+---E---

This is because to "reserve" a switch you must reserve one entry point
and one exit point; thus, the "single" side is *always* used.

The critical sections displayed with parantheses do not have any
semaphore associated with them, because the mutex is implicit whenever
the paralell track is reserved.

The choice of critical sections has otherwise been made so that
passing a switch is the same thing as moving into a new critical
section. This is because a piece of track with no switches can only
contain one train, in order to avoid collision.

The four-way crossing at the top of the map (`J1`) has its own critical
section, "on top of" `S1` and `(S1)` - you have to reserve it
separately when you need to pass through.

Choice of max speed
===================

The limiting factor when it comes to max speed is the braking distance
of the trains; we found (through empirical testing) that a maximum
speed of 22 was possible before the braking distance exceeded the
distance between sensor and switch and/or rail terminus.


Notes
-----

This document is written in Markdown.
