Merge branch 'master' of https://git.lucasjavaudin.com/LucasJavaudin/metrosim

.gitignore

@@ -1,3 +1,6 @@
+# Custom
+gtfs/
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

docs/architecture/overview/general_architecture.rst

@@ -0,0 +1,36 @@
+General Architecture
+====================
+
+System Context
+--------------
+
+The following diagram shows how MetroSim is integrated in the Metropolis system.
+
+MetroSim is supposed to be installed on servers.
+Most users only interact with MetroSim through the web interface MetroWeb.
+
+Only developers can install, run and modify MetroSim directly from their computers.
+
+The present documentation is dedicated to the simulator MetroSim.
+
+.. uml:: metrosim_system_context.puml
+   :caption: Metrosim System Context
+   :width: 100 %
+   :align: center
+
+Container Diagram
+-----------------
+
+The following diagram shows that MetroSim can be divided in two main parts:
+
+- The Initializer that can run multiple scripts to, e.g., generate the population, pre-process the network, compute attractive public-transit paths.
+- The Simulator that iteratively computes and executes the choices of the agents. 
+
+The Input data required by MetroSim are written in CSV and JSON files.
+The Output data are also CSV and JSON files.
+The web interface can communicate with MetroSim by writing the Input files and reading the Output files.
+
+.. uml:: metrosim_container.puml
+   :caption: MetroSim Container Diagram
+   :width: 100 %
+   :align: center

docs/architecture/overview/metrosim_container.puml

@@ -10,7 +10,7 @@ System_Ext(metroweb, "MetroWeb", "Web-based user interface and Web API")
 System_Boundary(metrosim, "MetroSim") {
     Container(initializer, "Initializer", "Python", "Computes data needed by the simulator from raw input data")
     Container(simulator, "Simulator", "Python", "Iteratively simulates trips until convergence is reached")
-    ContainerDb(files, "I/O Files", "CSV", "Input and output files")
+    ContainerDb(files, "I/O Files", "CSV / JSON", "Input and output files")
 }
 
 Rel(initializer, files, "Reads raw input data, writes pre-processed data")

docs/architecture/overview/modes.rst

@@ -3,11 +3,11 @@ 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.
+- **Car (and trucks):** 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/origin_and_destination.rst

@@ -0,0 +1,91 @@
+Origin and Destination
+======================
+
+MetroSim takes as input the origin zone and destination zone of each agent.
+
+The origin / destination zones can either be:
+
+- x/y coordinates representing the center of the zone,
+- a polygon representing the boundaries of the zone.
+
+If the zones are defined by x/y coordinates, we can simulate the boundaries of the zones by using Voronoi diagrams.
+Alternatively, the boundaries could be set to a circle centered on the given x / y coordinates, with a given zone-specific radius.
+
+If the zones are defined by a polygon, we can compute the geometric center (or centroid) of this polygon.
+
+Origins and Destinations for Car
+--------------------------------
+
+For car trips, all vehicles are assumed to be leaving from (arriving at) the center point of the origin (destination) zone.
+
+To do so, a new node is added to the road-network graph, for each zone center point.
+These nodes are connected to the road-network graph using new edges, called "connectors".
+
+The connectors are either:
+
+- an input of the simulator (i.e., we know to which nodes the center points are connected and we know the characteristics of the edges connecting them),
+- automatically created for the :math:`n` closest nodes to the center point, where :math:`n` is an input parameter.
+
+.. note::
+
+   If the boundaries of the zones are given and if the simulator detects that one of the :math:`n` closest nodes to the center point is not in the zone, the simulator will warn the user.
+
+   If the boundaries of the zones are not given and if the simulator detects that a node is one of the :math:`n` closest nodes for two or more center points, the simulator will warn the user.
+
+If the connectors are automatically created, their travel time is set to a constant travel time, given as input.
+
+.. note::
+
+   Alternatively, the travel time of the connectors could depend on their length.
+   However, this would require computing a distance in meters between the center points and the connected nodes, which is not feasible without knowing the projection of the coordinates.
+
+.. note::
+
+   If the zones are so large that it is unrealistic to assume that all agents are leaving from the same point, the users can always divide each zone in :math:`k` subzones so that the agents in the same zone are now leaving from :math:`k` different points.
+
+.. note::
+
+   The running time of the simulator is roughly proportional to the number of unique destination points.
+   Therefore, an alternative way to model the origin / destination zones, without increasing the running time, would be to assume that the agents are leaving from a random node in the origin zone and are arriving at the center point of the destination zone.
+   This alternative model being asymmetric, it could produce strange results when simulating both the morning and evening commute.
+
+Origins and Destinations for Public-Transit
+-------------------------------------------
+
+In the public-transit network, there can be multiple main stations in each zone.
+With the same center point assumption as with cars, some main stations might never be taken as they are two far away from the center of the zone so agents will always board and alight from a closer station.
+Additionally, the running time of the simulator for public transit is proportional to the number of agents, independently of the number of unique origin / destination points, allowing for more fine-tuned assumptions.
+
+For each agent, the simulator needs only to know the constant travel-time between their origin / destination and the closest main stations.
+This can be done in multiple ways.
+
+The walking network is known
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When the walking network is known, the simulator can affect each agent randomly to one of the node of the walking network inside the origin / destination zone and compute travel times to the closest main stations, using mixed walking and secondary public-transit routing.
+
+Only walking travel-times are known
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When the walking network is not known, an alternative input is to tell the constant walking travel-time (or, similarly, secondary public-transit network travel-time) from :math:`k` points in the origin / destination zone to the closest main stations.
+Then, agents are randomly affected to one of the :math:`k` point in their origin and destination zone.
+The probability to be affected to one point in a zone is either uniform or proportional to a given value.
+
+Walking travel-times are unknown
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When neither the walking network nor the walking travel-times are known, the agents are randomly affected to one of the main stations in their origin and destination zone.
+Then, agents can only start their trip from their origin station and end their trip at their destination station, i.e., they cannot start their trip by walking to another station.
+The probability to be affected to one of the stations is either uniform or proportional to a given value.
+If a zone has no main station in it, then no public-transit trip can start / arrive at this zone.
+
+Intra-Zone Trips
+----------------
+
+Intra-zone trips are trips of agents whose destination is the same as their origin.
+
+For car trips, intra-zone trips would have a null travel-time so they are not simulated.
+For public-transit trips, intra-zone trips could be simulated as the actual origin point can be different from the actual destination point.
+However, the mode choice would be difficult to simulate in this case (what would be the utility of traveling by car?).
+
+Therefore, intra-zone trips are excluded from the simulator but the users can send as input the mode choice and travel times of agents with intra-zone trips so that these trips are included in the aggregated results.

docs/architecture/overview/overview.rst

@@ -1,17 +1,9 @@
 Overview
 ========
 
-.. uml:: metrosim_system_context.puml
-   :caption: Metrosim System Context
-   :width: 100 %
-   :align: center
-
-.. uml:: metrosim_container.puml
-   :caption: MetroSim Container Diagram
-   :width: 100 %
-   :align: center
-
 .. toctree::
    
-   routes
+   general_architecture
    modes
+   road_network
+   origin_and_destination

docs/architecture/overview/road_network.rst

@@ -27,17 +27,60 @@ speed
 length
    The length of the edge (in kilometers).
 
-capacity
-   The capacity of the road (whose meaning depend on the congestion function).
-
 congestion_function
-   A function that yields the average speed on the road, given the characteristics of the road and the current number of vehicles.
+   A function that yields the average speed on the road, given the characteristics of the road and the current number of vehicles (see below).
+
+param1, param2, param3
+   Set of parameters whose meaning depend on the congestion function.
 
 
 Congestion Function
 ^^^^^^^^^^^^^^^^^^^
 
-TO BE DISCUSSED
+The congestion function gives the travel time of an edge given its characteristics and the history of its flows since the beginning of the simulation.
+The following congestion functions are supported.
+
+Free-flow
+~~~~~~~~~
+
+The travel time of the edge is not impacted by the flows of vehicles that take it.
+
+.. math::
+
+   {tt} = \text{length} / \text{speed}
+
+Basic Bottleneck
+~~~~~~~~~~~~~~~~
+
+The speed of the edge follows of speed-flow function which simulates a bottleneck.
+
+.. math::
+
+   {tt} = \left\{
+      \begin{array}{ll}
+         \text{length} / \text{speed} & \text{if}\ \text{flow} \leq \text{lanes} \cdot s \cdot \text{length} / \text{speed} \\
+         \text{flow} / (\text{lanes} \cdot s) & \text{otherwise}
+      \end{array}
+   \right.
+
+where :math:`\text{flow}` is the current number of vehicles on the edge and :math:`s` (= param1) is the capacity of the edge in number of vehicles per kilometer per lane per hour.
+
+Bureau of Public Roads Function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To be done.
+
+True Bottleneck with Vertical Queue
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The travel time on the edge depends on the parameter :math:`s` (= param1) which represents the capacity of the edge in number of vehicles per lane per hour.
+The vehicles run at free-flow speed until the end of the edge where they form a vertical queue.
+Every :math:`3600 / (\text{lanes} \cdot s)` seconds, the first vehicle in the queue can leave the edge.
+
+True Bottleneck with Horizontal Queue
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To be done.
 
 
 Dynamic Attributes
@@ -77,18 +120,15 @@ Input Values
 
 In MetroSim, each node must have the following attributes.
 
-upstream_edges
-   A list of edges whose target node is this node.
-
-downstream_edges
-   A list of edges whose source node is this node.
+x, y
+   Coordinates of the node.
 
 priority_function
    A function that yields the time taken to cross the intersection, in any direction, given the queue of vehicles at the intersection.
    
 
-Priority Function
-^^^^^^^^^^^^^^^^^
+Priority Function (Work-in-Progress)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The priority function is called in two situations:
 

docs/getting-started/glossary.rst

@@ -1,4 +1,4 @@
 Glossary
 ========
 
-To be completed
+To be done

docs/getting-started/installation.rst

@@ -1,4 +1,4 @@
 Installation
 ============
 
-To be completed
+To be done

docs/getting-started/introduction.rst

@@ -1,4 +1,4 @@
 Introduction
 ============
 
-To be completed
+To be done.

docs/getting-started/quickstart.rst

@@ -1,4 +1,4 @@
 Quickstart
 ==========
 
-To be completed
+To be done

docs/index.rst

@@ -30,7 +30,6 @@ It is intended at developers willing to improve or extend it.
    /architecture/overview/overview
    /architecture/initializer
    /architecture/simulator/simulator
-   /architecture/road_network/road_network
    /architecture/spillback/spillback
    /architecture/public_transit/public_transit