uxsim.Utilities.Utilities

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

Functions

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.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