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.

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)[source]

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)[source]

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)[source]

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)[source]

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.generate_grid_network(W, imax, jmax, **kwargs)[source]

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)[source]

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)[source]

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)[source]

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