uxsim.Utilities.Utilities

Submodule for general utilities. This contains functions that are not essential for simulation but useful to specific analysis.

Functions

construct_time_space_network(W[, dt, ...])	Construct a time-space network (TSN) that includes the time-dependent shortest path infomation.
enumerate_k_random_routes(W, k)	Enumerate k random routes between all node pairs in a network.
enumerate_k_shortest_routes(W, source, target)	Enumerate the k shortest routes between two nodes in a network.
enumerate_k_shortest_routes_on_t(W, source, ...)	Enumerate the k shortest routes between two nodes in a network.
estimate_congestion_externality_link(W, link, t)	Estimate externality caused by a hypothetical vehicle traveling the link in the world.
estimate_congestion_externality_route(W, ...)	Estimate externality caused by a hypothetical vehicle traveling the route in the world.
generate_grid_network(W, imax, jmax, **kwargs)	Generate a grid network with imax x jmax nodes.
get_shortest_path_distance_between_all_nodes(W)	Get the shortest distances (in meters) between all node pairs based on link lengths
get_shortest_path_instantaneous_travel_time_between_all_nodes(W)	Get the shortest instantaneous travel time (in seconds) between all node pairs based on the current instantaneous travel time of each link.
get_shortest_path_instantaneous_travel_time_between_all_nodes_on_t(W, t)	Get the shortest instantaneous travel time (in seconds) between all node pairs based on the instantaneous travel time of each link near time t (based on the route choice update interval).

uxsim.Utilities.Utilities.construct_time_space_network(W, dt=None, from_origin_only=True)

Construct a time-space network (TSN) that includes the time-dependent shortest path infomation.

Parameters:

• W (World) – The World object.

• dt (int, optional) – The time interval to construct the TSN. Default is None, which sets to the simulation timestep.

• from_origin_only (bool, optional) – Whether to compute the shortest path from the origin only. Default is True

Notes

In the default setting, W.TSN_paths contains time-dependent shortest paths from the origin nodes to all nodes, for all departure time. The time-dependent link cost is based on the actual travel time. For example, W.TSN_paths[“orig_node_name”, 0] contains the shortest path from the node “orig_node_name” with departure time 0. W.TSN_paths[“orig_node_name”, 0][“dest_node_name”, “end”] contains the shortest path from the node “orig_node_name” to “dest_node_name” with departure time 0. The travel time between these nodes on this time can be obtained by W.TSN_costs[“orig_node_name”, 0][“dest_node_name”, “end”].

Not efficient for large networks.

uxsim.Utilities.Utilities.enumerate_k_random_routes(W, k)

Enumerate k random routes between all node pairs in a network. The shortest path with free flow travel time is always included. This is much faster than enumerate_k_shortest_routes and could be useful for a plausible choice set generation for route choice problems.

Parameters:

• W (World) – The world object containing the network.

• k (int) – The number of random routes to enumerate.

Returns:

dict_routes – A dictionary of k random routes. The key is a tuple of the origin and destination nodes. The value is a list of link names.

Return type:

dict

uxsim.Utilities.Utilities.enumerate_k_shortest_routes(W, source, target, k=1, cost_function=<function <lambda>>, print_stats=0, return_cost=False)

Enumerate the k shortest routes between two nodes in a network. By default, enumerate_k_shortest_routes(W, “O”, “D”) returns the shortest path from node “O” to “D” based on the free-flow travel time.

Parameters:

• W (World) – The world object containing the network.

• source (str | Node) – The source node.

• target (str | Node) – The target node.

• k (int) – The number of shortest routes to enumerate. Default is 1.

• cost_function (function) – A link cost function to compute shortest path. The argument is Link object. Default is the free-flow travel time, lambda l: l.length/l.u.

• print_stats (bool) – Print the statistics of the paths.

• return_cost (bool) – Return the cost of the paths.

Returns:

• routes (list) – A list of k shortest routes. Each route is a list of link names.

• costs (list) – A list of costs of the routes if return_cost is True.

uxsim.Utilities.Utilities.enumerate_k_shortest_routes_on_t(W, source, target, t, k=1, cost_function=<function <lambda>>, print_stats=0, return_cost=False)

Enumerate the k shortest routes between two nodes in a network. By default, enumerate_k_shortest_routes_on_t(W, “O”, “D”, t=t) returns the shortest path from node “O” to “D” based on instantanious travel time on time t.

Parameters:

• W (World) – The world object containing the network.

• source (str | Node) – The source node.

• target (str | Node) – The target node.

• t (float) – The time point to compute shortest routes.

• k (int) – The number of shortest routes to enumerate. Default is 1.

• cost_function (function) – A link cost function to compute shortest path. The argument is Link object and time t. Default is the instantaneous travel time, lambda l, t: l.instant_travel_time(t).

• print_stats (bool) – Print the statistics of the paths.

• return_cost (bool) – Return the cost of the paths.

Returns:

• routes (list) – A list of k shortest routes. Each route is a list of link names.

• costs (list) – A list of costs of the routes if return_cost is True.

uxsim.Utilities.Utilities.estimate_congestion_externality_link(W, link, t)

Estimate externality caused by a hypothetical vehicle traveling the link in the world. Subfunction for estimate_congestion_externality_route.

Parameters:

• W (World) – The World object.

• link (str | Link) – Link object or link name.

• t (float) – The departure time of the hypothetical vehicle.

uxsim.Utilities.Utilities.estimate_congestion_externality_route(W, route, t)

Estimate externality caused by a hypothetical vehicle traveling the route in the world.

Specifically, it estimates the total travel time that would be achieved if the vehicle did not exist and then calculates the difference. This estimation is based on a simple queuing model for each link of the route that the vehicle passes through. Does not fully capture queue spilovers.

Parameters:

• W (World) – The World object.

• route (Route) – Route object.

• t (float) – The departure time of the hypothetical vehicle.

uxsim.Utilities.Utilities.generate_grid_network(W, imax, jmax, **kwargs)

Generate a grid network with imax x jmax nodes.

Parameters:

• W (World) – The world object to which the network will be added.

• imax (int) – The number of nodes in the x direction.

• jmax (int) – The number of nodes in the y direction.

• **kwargs (dict) – Additional keyword arguments to be passed to the addLink function.

uxsim.Utilities.Utilities.get_shortest_path_distance_between_all_nodes(W, return_matrix=False)

Get the shortest distances (in meters) between all node pairs based on link lengths

Parameters:

• W (World) – The World object.

• return_matrix (bool, optional) – Whether to return the distance matrix as a numpy array. Default is False.

Returns:

Returns a dictionary of distances between nodes whose key is node pair if return_matrix is False. Returns a numpy array of distances between nodes whose index is node.id pair if return_matrix is True.

Return type:

dict or numpy array

uxsim.Utilities.Utilities.get_shortest_path_instantaneous_travel_time_between_all_nodes(W, return_matrix=False)

Get the shortest instantaneous travel time (in seconds) between all node pairs based on the current instantaneous travel time of each link.

Parameters:

• W (World) – The World object.

• return_matrix (bool, optional) – Whether to return the distance matrix as a numpy array. Default is False.

Returns:

Returns a dictionary of distances between nodes whose key is node pair if return_matrix is False. Returns a numpy array of distances between nodes whose index is node.id pair if return_matrix is True.

Return type:

dict or numpy array

uxsim.Utilities.Utilities.get_shortest_path_instantaneous_travel_time_between_all_nodes_on_t(W, t, return_time=False, return_matrix=False)

Get the shortest instantaneous travel time (in seconds) between all node pairs based on the instantaneous travel time of each link near time t (based on the route choice update interval).

Parameters:

• W (World) – The World object.

• t (float) – The time point to compute shortest travel time.

• return_time (bool, optional) – Whether to return the actual time of computing shortest path cost. Default is False.

• return_matrix (bool, optional) – Whether to return the distance matrix as a numpy array. Default is False.

Returns:

Returns a dictionary of distances between nodes whose key is node pair if return_matrix is False and return_time is False. Returns a numpy array of distances between nodes whose index is node.id pair if return_matrix is True and return_time is False. Returns a tuple of the abode distances and the actual time of computing shortest path cost if return_time is True.

Return type:

dict or numpy array or tuple