expand documentation

docs/architecture/overview/modes.rst

@@ -0,0 +1,13 @@
+Modes
+=====
+
+MetroSim is planned to be supporting the following modes:
+
+- Car: congestion on the road is explicitly modeled; vehicles can have different size (implying different impact on congestion) and free-flow speed (implying different travel-times); continuous departure-time choice.
+- Walk: travel time depends on constant (intra-day and inter-day) walking distances and individual-specific walking speed; continuous departure-time choice (constant from day-to-day).
+- Bicycle: travel time depends on constant (intra-day and inter-day) bicycle distances and individual-specific bicycle speed; continuous departure-time choice (constant from day-to-day).
+- Motorcycle: no impact on congestion; only partially impacted by congestion; different free-flow speed; continuous departure-time choice.
+- Public-transit (with right-of-way): fixed timetables; in-vehicle congestion is explicitly modeled; different types (e.g., light rail, bus, tramway) with different values of time.
+- Public-transit (without right-of-way): schedule depends on road congestion; in-vehicle congestion is explicitly modeled; different types (e.g., light rail, bus, tramway) with different values of time.
+
+Other modes that could be supported in the future: public-transit with imperfect timetables, inter-modality, autonomous vehicles, ride-sharing.

docs/architecture/overview/overview.rst

@@ -14,3 +14,4 @@ Overview
 .. toctree::
    
    routes
+   modes

docs/architecture/public_transit/public_transit.rst

@@ -0,0 +1,46 @@
+Public-Transit Modeling
+=======================
+
+Managing seats
+--------------
+
+In the within-day model:
+
+- Each vehicle has a given number of seats.
+- We keep track of the number of seats occupied at any time in the vehicle.
+- For each agent in a PT vehicle, we keep track of its status (sitting or standing).
+- When a PT vehicle reach a stop, (i) the number of available seats is computed, accounting for the seated agents who alighted, (ii) agents already on-board and standing can take the available seats, (iii) boarding agents can take the remaining seats (if any).
+- We keep track of the share of standing agents who got a seat and the share of agents boarding who got a seat, at each stop.
+
+In the pre-day model:
+
+- When boarding a new vehicle, the expected utility from the current stop to the next stop is the utility of being seated times the probability that boarding agents get a seat, plus the utility of standing (which can depends on the expected number of standing agents in the vehicle) times the probability that boarding agents do not get a seat.
+- The expected utility from the next stop to the subsequent one is the utility of being seated times the probability of having a seat (the probability of being seated at the previous stop time plus the probability that standing agents get a seat at this stop, conditional on not having a seat yet), plus the utility of standing times the probability of not having a seat.
+
+.. note:: Example
+   Consider an agent evaluating the utility of taking the sequence of stop A->B->C->D, of a specific line at a given departure-time.
+   Assume that the cost of standing is always 2 and the cost of being seated is 1.
+   Assume also that the probability that standing agents get a seat is always 80 % and the probability that boarding agents get a set is always 30 %.
+
+   The probability of being seated for the part A->B of the leg is 30 % (as the agent is boarding at A).
+   Then, the cost of the part A->B is 1 * 30 % + 2 * 70 % = 1.7.
+
+   The probability of being seated for the part B->C of the leg is 30 % (the probability of already being seated) + 80 % * 70 % (the probability of being seated conditional on not being seated already) = 86 %.
+   Then, the cost of the part B->C is 1 * 86 % + 2 * 14 % = 1.14.
+
+   The probability of being seated for the part C->D of the leg is 86 % (the probability of already being seated) + 80 % * 14 % (the probability of being seated conditional on not being seated already) = 97.2 %.
+   Then, the cost of the part C->D is 1 * 97.2 % + 2 * 2.8 % = 1.028.
+
+
+Denied boarding
+---------------
+
+In the within-day model:
+
+- If the vehicle an agent is about to board has an higher occupancy than expected, then the agent can choose to voluntarily not board it, by comparing his/her expected utility with his/her expected utility if he/she takes the next vehicle (for the same path).
+- Agents board a vehicle one-by-one. If a vehicle is full-to-capacity, then the next agents that wanted to board it have to choose between waiting for the same vehicle (for the same path) or taking another path.
+
+In the pre-day model:
+
+- When evaluating the utility of a path, the agents consider that they will always board the first vehicle (even if it is full-to-capacity).
+- Alternatively, we could consider that agents assume that they will board the next vehicle is the probability of taking the first one is smaller than a threshold.

docs/architecture/spillback/spillback.rst

@@ -0,0 +1,43 @@
+Queuing
+========
+
+Queuing Types
+--------------
+
+- Vertical queues: Congestion on one edge does not impact congestion on the other edges.
+- Horizontal queues with overtakes: Pending agents are impacting congestion on the edge they are coming from but overtake if possible (e.g., an agent who is turning left can overtake an agent waiting to turn right).
+  This is what is done in Metropolis 1.
+  Note that this is incompatible with a true bottleneck model.
+- Horizontal queues with blockage of upstream edges: Pending agents are blocking the edge they are coming from; no overtake if possible.
+  It is still possible to cross the intersection (if coming from another downstream edge not blocked and going to another upstream edge not full).
+  This is only compatible with a true bottleneck model.
+- Horizontal queues with full blockage: Pending agents are assumed to enter the intersection and to block all traffic going through it.
+
+.. warning::
+   There is another possible queuing type where overtake is only possible for agents turning right (when the front or left edge is full, for right-hand traffic).
+   This could be implemented at the intersection level.
+   To detect right- and left-turns an automatic process could be implemented by comparing the orientation of the downstream edges.
+
+.. warning::
+   For a more realistic model, we could assume that the upstream edge gets blocked only if it has one lane.
+   For more complex models (e.g., the edge is blocked if it has two lanes and someone is waiting to turn right and someone else is waiting to turn left), this could be implemented at the intersection level.
+
+Route Choice
+------------
+
+If route lookahead is enabled, agents observe the status of the downstream edges (full or not) and the number of vehicles in the queue, at any intersection.
+Then, the total expected travel time to destination for a downstream edge that is full depends on the expected waiting time for this edge.
+The expected waiting time is a function of the number of vehicles in the queue and the expected discharge rate of the edge.
+
+If route lookahead is disabled, route choice is based on the expected travel times of the edges, which are based on the travel times of the previous iterations, that include potential waiting times.
+
+Revisions
+---------
+
+When blocked at an intersection, waiting for an edge to be accessible, an agent can make a revision, i.e., he/she can choose to stop waiting and take another downstream edge.
+The timing of the revisions is based on the expected discharge rate of the edge, i.e., the rate at which vehicles are leaving the queue.
+
+At each revision, the predicted discharge rate of the edge is updated based on what was observed during the time spent waiting so far.
+
+.. warning::
+   TODO: Check if the timing of the revisions could be improved by accounting for the difference in travel time or travel utility between the route chosen and the second-best alternative (this is more difficult with stochastic route choice).

docs/index.rst

@@ -31,6 +31,8 @@ It is intended at developers willing to improve or extend it.
    /architecture/initializer
    /architecture/simulator/simulator
    /architecture/road_network/road_network
+   /architecture/spillback/spillback
+   /architecture/public_transit/public_transit
 
 .. toctree::
    :caption: References