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.