Public API

path4gmns.accessibility

path4gmns.accessibility.evaluate_accessibility(ui, single_mode=False, mode='auto', time_dependent=False, demand_period_id=0, output_dir='.')

perform accessibility evaluation for a target mode or more

Parameters

• ui – network object generated by pg.read_network()

• single_mode –

  True or False. Its default value is False. It will only affect the output to zone_accessibility.csv.

  If False, the accessibility evaluation will be conducted for all the modes defined in settings.yml. The number of accessible zones from each zone under each defined mode given a budget time (up to 240 minutes) will be outputted to zone_accessibility.csv.

  If True, the accessibility evaluation will be only conducted against the target mode. The number of accessible zones from each zone under the target mode given a budget time (up to 240 minutes) will be outputted to zone_accessibility.csv.

• mode – target mode with its default value as ‘auto’. It can be either agent type or its name. For example, ‘w’ and ‘walk’ are equivalent inputs.

• time_dependent –

  True or False. Its default value is False.

  If True, the accessibility will be evaluated using the period link free-flow travel time (i.e., VDF_fftt). In other words, the accessibility is time-dependent.

  If False, the accessibility will be evaluated using the link length and the free flow travel speed of each mode.

• demand_period_id –

  The sequence number of demand period listed in demand_periods in settings.yml. demand_period_id of the first demand_period is 0.

  Use it with time_dependent when there are multiple demand periods. Its default value is 0.

• output_dir – The directory path where zone_accessibility.csv and od_accessibility.csv are output. The default is the current working directory (CDW).

Returns

Return type

None

Note

The following files will be output.

zone_accessibility.csv

accessibility as the number of accessible zones from each zone for a target mode or any mode defined in settings.yml given a budget time (up to 240 minutes).

od_accessibility.csv:

accessibility between each OD pair in terms of free flow travel time.

path4gmns.accessibility.evaluate_equity(ui, single_mode=False, mode='auto', time_dependent=False, demand_period_id=0, time_budget=60, output_dir='.')

evaluate equity for each zone under a time budget

Parameters

• ui – network object generated by pg.read_network()

• single_mode –

  True or False. Its default value is False. It will only affect the output to zone_accessibility.csv.

  If False, the equity evaluation will be conducted for all the modes defined in settings.yml.

  If True, the equity evaluation will be only conducted against the target mode.

• mode – target mode with its default value as ‘auto’. It can be either agent type or its name. For example, ‘w’ and ‘walk’ are equivalent inputs.

• time_dependent –

  True or False. Its default value is False.

  If True, the accessibility will be evaluated using the period link free-flow travel time (i.e., VDF_fftt). In other words, the accessibility is time-dependent.

  If False, the accessibility will be evaluated using the link length and the free flow travel speed of each mode.

• demand_period_id –

  The sequence number of demand period listed in demand_periods in settings.yml. demand_period_id of the first demand_period is 0.

  Use it with time_dependent when there are multiple demand periods. Its default value is 0.

• time_budget – the amount of time to travel in minutes

• output_dir – The directory path where the evaluation result is output. The default is the current working directory (CDW).

Returns

Return type

None

Note

The following file will be output.

equity_str.csv

equity statistics including minimum accessibility (and the corresponding zone), maximum accessibility (and the corresponding zone), and mean accessibility for each bin_index. The accessible zones will be output as well.

str in the file name refers to the time budget. For example, the file name will be equity_60min.csv if the time budget is 60 min.

path4gmns.classes

class path4gmns.classes.UI(assignment)

an abstract class only with user interfaces

find_path_for_agents(mode='all')

DEPRECATED

find and set up shortest path for each agent

find_shortest_path(from_node_id, to_node_id, mode='all', seq_type='node')

return shortest path between from_node_id and to_node_id

Parameters

• from_node_id – the starting node id, which shall be a string

• to_node_id – the ending node id, which shall be a string

• seq_type – ‘node’ or ‘link’. You will get the shortest path in sequence of either node IDs or link IDs. The default is ‘node’.

• mode –

  the target transportation mode which is defined in settings.yml. It can be either agent type or its name. For example, ‘w’ and ‘walk’ are equivalent inputs.

  The default is ‘all’, which means that links are open to all modes.

Returns

the shortest path between from_node_id and to_node_id.

Return type

str

Note

Exceptions will be thrown if either of from_node_id and and to_node_id is not valid node IDs.

get_accessible_links(source_node_id, time_budget, mode='auto', time_dependent=False, demand_period_id=0)

get the accessible links from a node given mode and time budget

Parameters

• source_node_id – the starting node id for evaluation, which shall be string

• time_budget – the amount of time to travel in minutes

• mode –

  the target transportation mode which is defined in settings.yml. It can be either agent type or its name. For example, ‘w’ and ‘walk’ are equivalent inputs.

  The default is ‘auto’.

Returns

the number of links that can be accessible from source_node_id given time_budget and mode, and the link list

Return type

int

get_accessible_nodes(source_node_id, time_budget, mode='auto', time_dependent=False, demand_period_id=0)

get the accessible nodes from a node given mode and time budget

Parameters

• source_node_id – the starting node id for evaluation, which shall be string

• time_budget – the amount of time to travel in minutes

• mode –

  the target transportation mode which is defined in settings.yml. It can be either agent type or its name. For example, ‘w’ and ‘walk’ are equivalent inputs. Its default value is ‘a’ (i.e., mode auto).

  The default is ‘auto’.

• time_dependent –

  True or False. Its default value is False.

  If True, the accessibility will be evaluated using the period link free-flow travel time (i.e., VDF_fftt). In other words, the accessibility is time-dependent.

  If False, the accessibility will be evaluated using the link length and the free flow travel speed of each mode.

• demand_period_id –

  The sequence number of demand period listed in demand_periods in settings.yml. demand_period_id of the first demand_period is 0.

  Use it with time_dependent when there are multiple demand periods. Its default value is 0.

Returns

the number of nodes that can be accessible from source_node_id given time_budget and mode, and the node list

Return type

int

get_agent_dest_node_id(agent_id)

return the destination node id of an agent

get_agent_link_path(agent_id)

return the sequence of link IDs along the agent path

get_agent_node_path(agent_id)

return the sequence of node IDs along the agent path

get_agent_orig_node_id(agent_id)

return the origin node id of an agent

get_column_vec(at, dp, orig_zone_id, dest_zone_id)

get all columns between two zones given agent type and demand period

caller is responsible for checking if (at, dp, orig_zone_id, dest_zone_id) is in column pool

path4gmns.colgen

path4gmns.colgen.perform_column_generation(column_gen_num, column_update_num, ui)

perform network assignment using the selected assignment mode

Warning

Only Path/Column-based User Equilibrium (UE) is implemented in Python. If you need other assignment modes or dynamic traffic assignment (DTA), please use perform_network_assignment_DTALite()

Parameters

• column_gen_num – number of iterations to be performed on generating column pool column pool

• column_update_num – number of iterations to be performed on optimizing column pool

• ui – network object generated by pg.read_network()

Returns

Return type

None

Note

You will need to call output_columns() and output_link_performance() to get the assignment results, i.e., paths/columns (in agent.csv) and assigned volumes and other link attributes on each link (in l ink_performance.csv)

path4gmns.colgen.perform_network_assignment(assignment_mode, column_gen_num, column_update_num, ui)

DEPRECATED Column Generation API

Keep it here as legacy support for existing users who already get used to it

path4gmns.dtaapi

path4gmns.dtaapi.perform_network_assignment_DTALite(assignment_mode, column_gen_num, column_update_num)

DEPRECATED Python interface to call DTALite (precompiled as shared library)

perform network assignment using the selected assignment mode

Warning

MAKE SURE TO BACKUP route_assignment.csv and link_performance.csv if you have called perform_network_assignment() before. Otherwise, they will be overwritten by results generated by DTALite.

Parameters

• assignment_mode –

  0: Link-based UE, only generates link performance file without agent path file

  1: Path-based UE, generates link performance file and agent path file

  2: UE + dynamic traffic assignment (DTA), generates link performance file and agent path file

  3: ODME

• column_gen_num – number of iterations to be performed before on generating column pool

• column_update_iter – number of iterations to be performed on optimizing column pool

Returns

Return type

None

Note

The output will depend on the selected assignment_mode.

Link-based UE: link_performance.csv

Path-based UE: route_assignment.csv and link_performance.csv

UE + DTA: route_assignment.csv and link_performance.csv

route_assignment.csv: paths/columns

link_performance.csv: assigned volumes and other link attributes on each link

path4gmns.dtaapi.run_DTALite()

Python interface to call the latest DTALite

This version of DTALite includes all-new Logbook, enhanced scenario handling, improved I/O functionality, and so on.

Its source code can be found at https://github.com/asu-trans-ai-lab/DTALite.

Parameters

None –

Returns

Return type

None

Note

It is compatible with the classic DTALite and the corresponding data sets from https://github.com/jdlph/Path4GMNS/tree/dev/data.

Additional data set can be found at https://github.com/asu-trans-ai-lab/DTALite/tree/main/data.

Please run the script calling this API using system terminal rather than Python console for proper logging.

path4gmns.simulation

path4gmns.simulation.perform_simple_simulation(ui, loading_profile='uniform')

perform simple traffic simulation using point queue model

Warning

The underlying routing decision is made through find_path_for_agents(), which must be called before this function.

Parameters

• ui – network object generated by pg.read_network()

• loading_profile –

  demand loading profile, i.e., how agents are loaded to network with respect to their departure times. Three loading profiles are supported, which are uniform, random, and constant.

  With uniform loading profile, agents will be uniformly distributed between [simulation start time, simulation start time + simulation duration).

  With random loading profile, the departure time of each agent is randomly set up between [simulation start time, simulation start time + simulation duration).

  With constant loading profile, the departure times of all agents are the same, which are simulation start time.

Returns

Return type

None

Note

You will need to call output_agent_trajectory() to get the simulation results, i.e., trajectory of each agent (in trajectory.csv).

path4gmns.utils

path4gmns.utils.read_network(length_unit='mile', speed_unit='mph', load_demand=False, input_dir='.')

path4gmns.utils.read_zones(ui, input_dir='.', filename='zone.csv')

read zone.csv to set up zones

path4gmns.utils.load_demand(ui, agent_type_str='a', demand_period_str='AM', input_dir='.', filename='demand.csv')

load demand for an agent type and a demand period

this is an user interface while read_demand() is intended for internal use.

path4gmns.utils.load_columns(ui, input_dir='.')

path4gmns.utils.output_link_performance(ui, output_dir='.')

path4gmns.utils.output_agent_paths(ui, output_geometry=True, output_dir='.')

output unique agent path

use it with find_path_for_agents() (which has been DEPRECATED)

path4gmns.utils.output_zones(ui, output_dir='.')

path4gmns.utils.output_synthesized_demand(ui, output_dir='.')

path4gmns.utils.download_sample_data_sets()

download sample data sets from the Github repo

the following data sets will be downloaded: ASU, Braess Paradox, Chicago Sketch, Lima Network, Sioux Falls, and Two Corridors.

path4gmns.utils.download_sample_setting_file()

download the sample settings.yml from the Github repo

path4gmns.zonesyn

path4gmns.zonesyn.network_to_zones(ui, grid_dimension=8, max_bin=5, total_demand=10000, time_budget=120, mode='auto')

synthesize zones and OD demand given a network

Parameters

• ui – network object generated by pg.read_network().

• grid_dimension – positive integer. If its value is d, a total of d * d zones will be synthesized.

• max_bin – positive integer. The maximum number of bin_idex generated for synthesized zones.

• total_demand –

  The total demand or the total number of trips to be allocated to the OD demand matrix. it should be a positive integer.

  The allocated demand to each zone is proportional to the number of its activity nodes. Given an origin zone, its production volume will be proportionally allocated to each connected destination zone. Gravity Model is NOT in use.

  note that the summation of demand over each OD pair is roughly the same as total_demand due to rounding errors.

• time_budget – the amount of time to travel in minutes, which is used to cut off the demand allocation. If the minimum travel time between an OD pair under a specific mode is greater than time_budget, we consider that the two zones are not connected and no demand will be allocated between them.

• mode –

  target mode with its default value as ‘auto’. It can be either agent type or its name. For example, ‘w’ and ‘walk’ are equivalent inputs.

  It is used along with time_budget to check if the minimum travel time under the given mode exceeds the time budget or not.

Returns

Return type

None

Note

The following files will be output.

zone.csv.csv

synthesized zones including zone id, activity nodes, coordinates of its centroid, it boundaries (as a grid or rectangle), production volume, and attraction volume.

zone_id will be an integer starting from one.

syn_demand.csv

synthesized demand between each connected OD pair (within a time budget).