Route choice: public transit and private - smart-fm/simmobility-prod GitHub Wiki

A SimMobility agent who wants to travel from one location to another has to decide on the route that he is going to take before starting the trip. The process of selecting a path from an origin to a destination (OD) from a bunch of available path options is known as route choice. The set of paths between an OD pair is known as the pathset for that OD.

Route choice that is done before the start of the trip is known as pre-trip route-choice. Sometimes, route selection happens en-route as well. For example, route choice may be required when there is information en-route about severe traffic congestion along the way or when there is a service disruption along an MRT line or if there is some traffic diversion along a road in the path chosen during pre-trip route choice.

The mode chosen for a trip plays an important role in the way route choice is done. Agents with trips on private modes like car, motorcycle etc., need to think in terms of road-network links and travel times along different roads when they choose a route; whereas agents with trips on public transit modes like buses and metro trains need to consider factors such as accessibility of public transit stops, frequency of service etc. in addition to the travel times. Consequently, there are fundamental differences between private route choice and public transit route choice. The discrete choice (path-size logit) models developed for trips with public transit and private modes are different from each other.

Pathset of an origin-destination (OD) pair is simply a set of paths leading from the origin to the destination. Pathset for the trip OD must be available before any route choice can be done in withinday simulations. Typically, pathsets are generated for every OD in the demand before executing withinday and supply. The procedure to generate pathsets is explained in detail in the [pathset generation] (https://github.com/smart-fm/simmobility-prod/wiki/Pathset-generation#pathset-generation-steps) document.

The generated pathsets are kept in the routechoice schema of simmobility database. Public transit paths and private traffic paths have very different formats and are kept in separate tables. These pathset tables need to be passed into withinday simulations of both mid-term and short-term. When a person agent wants to travel from origin A to destination B, the pathset for the (A,B) OD pair is loaded from one of private or public transit pathset tables based on the mode chosen by the agent for that trip. The agent then gets to do his route-choice. He chooses one path from among the alternatives available in the pathset.

Both private and public transit route choice models are coded within lua scripts. There are different lua scripts for private and public transit route choice models. Short and mid-term withinday simulators interface with these scripts. Keeping the route choice models in lua scripts allows users to experiment and play with the models without having to recompile SimMobility. The only constraint is to keep the interface intact.

When an agent wants to do route choice, he fetches the pathset for his OD pair and passes the details of each path in the pathset through the lua interface to the appropriate lua model and invokes the corresponding route choice function implemented within the lua script.
###Private route choice For private modes like car, motorcycle etc., a path is simply a sequence of links in the [road network] (https://github.com/smart-fm/simmobility-prod/wiki/SimMobility-road-network) leading from the origin node to the destination node. Each record of the private pathset table contains a comma-separated list of link ids. After choosing a path from a pathset, an agent just has to look up the link ids from the road-network to realize the path.

The default private route choice model is written in pvtrc.lua file. This lua file exposes a function named choose_PVT_path() as a global function. This function is invoked by agents in withinday simulations to choose a path from the pathset for an OD pair. That said, any custom lua script provided for private route choice must expose a global function named choose_PVT_path() and accept the same arguments as the original function in pvtrc.lua. Refer to the [private route choice model] (https://github.com/smart-fm/simmobility-prod/wiki/Private-Traffic-Route-Choice) document for more details of the model. ###PT route choice NOTE: Public transit features are not yet fully implemented in short-term. Therefore, PT route choice does not take place in short-term simulations. However, the plan is to share the same models for routechoice between short and mid-term.

For public transit (PT) modes, a path is a sequence of trip legs involving an access leg to a PT stop, a journey by a specific PT line from that stop to another specific destination PT stop, zero or more transfers and PT trips on other PT lines, and finally an egress leg from the last PT stop to the destination node. Unlike the paths for private modes, a PT path does not specify links in the road network. It only specifies a sequence of edges in the PT graph built solely for the purpose of PT route choice.

A short description of the PT graph and steps to build it can be found [here] (https://github.com/smart-fm/simmobility-prod/wiki/Public-transit-graph-generation). In the PT graph, all bus stops, train stops and SimMobility nodes (from the road network) are vertices. Roughly speaking, there is a directed edge between two PT stop vertices of the graph if there is a PT line (bus or train line) serving the from-vertex and then eventually the to-vertex. There is a directed edge between a SimMobility node vertex to a PT stop vertex (and vice versa) if the distance between the node and the stop is walkable. Walk is the only mode of access and egress that is supported as of now. Each record of the public transit pathset table contains a comma-separated list of edges in the PT graph leading from the origin node to the destination node. To realize a path, an agent has to look up those edge ids in the edges of the PT graph. For more details about PT routechoice modelling, refer [here] (https://github.com/smart-fm/simmobility-prod/wiki/Public-Route-Choice-modeling).

The vertices and edges of the PT graph are stored as tables in the routechoice schema of simmobility database alongside the pathset tables. These tables are loaded into memory and the edge ids are looked up whenever required during the simulation.

The default PT route choice model is implemented in the ptrc.lua file. This file exposes a choose_PT_path() global function which is invoked by SimMobility agents who want to do PT route choice. Any custom model provided instead of the default must expose this function for the agents to invoke. ####Rail-transit network In the PT graph, the edges corresponding to train travel are (too) strongly connected. There is a direct edge from each origin station to every station that is reachable from the origin station through any number of train lines and transfers. The graph does not differentiate between different train lines like it does for bus lines. Consequently, if the path chosen by an agent includes such a train edge, we can only identify the boarding station and the alighting station of the edge. There is no way to identify the transfer stations of the train trip. These transfer stations are required to correctly model boarding and alighting in each of the train lines simulated in withinday.

In order to solve this problem, there is yet another graph, namely the rail-transit graph which is a simple graph model of the simulated rail network. In this graph every train station is a vertex and every consecutive pair of stations connected by a train line is connected by a directed edge. All SimMobility agents are assumed to take the shortest path from the boarding train station to the alighting station. After selecting a path by PT route choice, if the path involves a train edge, we simply search for the shortest path between the origin and destination stations determined from the edge. The transfer points are then identified from this shortest path.

This rail-transit graph is also kept in a table in the routechoice schema of the simmobility database. At the start of each simulation run, this table is loaded into memory and the rail-network graph is constructed.

The select queries to load pathsets from the pathset tables, PT graph, rail transit graph and ERP information for cost computation are written into postgresql functions (stored procedures). The names of these postgres functions are specified in the simrun_MidTerm.xml and simrun_ShortTerm.xml config files respectively for mid-term and short-term as shown in the sample below.

    <proc_map id="withinday" format="aimsun">
        ...
        ...
        <mapping name="pvt_pathset" procedure="get_pvt_pathset"/>
        <mapping name="pt_vertices" procedure="get_pt_map_vertices()"/>
        <mapping name="pt_edges" procedure="get_pt_map_edges()"/>
        <mapping name="pt_pathset" procedure="get_pt_pathset"/>
        <mapping name="rail_transit_edges" procedure="get_rail_transit_edges()"/>
        <mapping name="erp_gantry_zone" procedure="get_erp_gantry_zone()"/>
        <mapping name="erp_section" procedure="get_erp_section()"/>
        <mapping name="erp_surcharge" procedure="get_erp_surcharge()"/>

        ...
        ...
    </proc_map>

If you want to know which private pathset table you are using, for example, check in the file above the name of the SQL procedure mapped with the name pvt_pathset, open an SQL utility (like pdAdmin), open the SQL procedure from that utility. You will see there the name of the private pathset table you are using.

The path to the route choice model scripts are specified in the same simrun_MidTerm.xml file as follows.

        ...
        ...
        <!-- lua scripts used in withinday -->
        <model_scripts path="scripts/lua/mid/behavior-models/" format="lua">
             <script name="logit" file="logit.lua"/> <!-- code for multinomial and nested logit models-->
             <script name="pvtrc" file="pvtrc.lua"/> <!--private traffic route choice-->
             <script name="ptrc" file="ptrc.lua"/> <!--public transit route choice-->
             ...
        </model_scripts>

In the model_scripts tag, ensure that the path attribute points to the folder containing the lua models and that the format is set to lua. Also ensure the script tag specifies the correct file names for the logit, pvtrc and ptrc models.