uxsim.World

class uxsim.World(name='', deltan=5, reaction_time=1, duo_update_time=600, duo_update_weight=0.5, duo_noise=0.01, eular_dt=120, eular_dx=100, random_seed=None, print_mode=1, save_mode=1, show_mode=0, route_choice_principle='homogeneous_DUO', route_choice_update_gradual=False, show_progress=1, show_progress_deltat=600, tmax=None, vehicle_logging_timestep_interval=1, instantaneous_TT_timestep_interval=5, hard_deterministic_mode=False, meta_data={}, user_attribute=None, user_function=None)

World (i.e., simulation environment). A World object is consistently referred to as W in this code.

Create a World.

Parameters:

• name (str, optional) – The name of the world, default is an empty string.

• deltan (int, optional) – The platoon size, default is 5 vehicles.

• reaction_time (float, optional) – The reaction time, default is 1 second. This is also related to simulation time step width.

• duo_update_time (float, optional) – The time interval for route choice update, default is 600 seconds.

• duo_update_weight (float, optional) – The update weight for route choice, default is 0.5.

• duo_noise (float, optional) – The noise in route choice, default is 0.01.

• route_choice_update_gradual (bool, optional) – Whether to update route choice ratio gradually or not. True is recommended. Default is False for backward compatibility.

• eular_dt (float, optional) – The time aggregation size for eularian traffic state computation, default is 120.

• random_seed (int or None, optional) – The random seed, default is None.

• print_mode (int, optional) – The print mode, whether print the simulation progress or not. Default is 1 (enabled).

• save_mode (int, optional) – The save mode,. whether save the simulation results or not. Default is 1 (enabled).

• show_mode (int, optional) – The show mode, whether show the matplotlib visualization results or not. Default is 0 (disabled).

• route_choice_principle (str, optional) – The route choice principle, default is “homogeneous_DUO”.

• show_progress (int, optional) – Whether show network progress, default is 1 (enabled).

• show_progress_deltat (float, optional) – The time interval for showing network progress, default is 600 seconds.

• tmax (float or None, optional) – The simulation duration, default is None (automatically determined).

• vehicle_logging_timestep_interval (int, optional) – The interval for logging vehicle data, default is 1. Logging is off if set to -1. Setting large intervel (2 or more) or turn off the logging makes the simulation significantly faster in large-scale scenarios without loosing simulation internal accuracy, but outputed vehicle trajecotry and other related data will become inaccurate.

• vehicle_logging_timestep_interval – The interval for logging vehicle data, default is 1. Logging is off if set to -1. Setting large intervel (2 or more) or turn off the logging makes the simulation significantly faster in large-scale scenarios without loosing simulation internal accuracy, but outputed vehicle trajecotry and other related data will become inaccurate.

• instantaneous_TT_timestep_interval (int, optional) – The interval for computing instantaneous travel time of each link. Default is 5. If it is longer than the DUO update timestep interval, it is substituted by DUO update timestep interval to maintain reasonable route choice behavior.

• hard_deterministic_mode (bool, optional) – If True, the simulation will not use any random variables. At a merging node, a link with higher merge_priority will be always prioritized, and vehicles always choose the shortest path. This may be useful for analysis that need strict predictability. Be aware that the simulation results will be significantly different from ones with hard_deterministic_mode=False.

• meta_data (dict, optinal) – Meta data for simulation scenario. Can store arbitrary data, such as licences and simulation explanation.

• user_attribute (any, optinal) – Optinonal meta attributes that can be freely defined by a user.

• user_function (func, optinal) – User-defined custom function that is automatically called when timestep is incremented (more precisely, just before timesptep is incremented). It takes only one argument: the World object itself. Example: The following code prints the current simulation time at each timestep. If user_function=None (default), no functions will be executed. >>> def user_function(W): >>> print(W.TIME) >>> W = World(user_function=user_function) >>> … #define your scenario >>> W.exec_simulation()

Notes

A World object must be defined firstly to initiate simulation.

__init__(name='', deltan=5, reaction_time=1, duo_update_time=600, duo_update_weight=0.5, duo_noise=0.01, eular_dt=120, eular_dx=100, random_seed=None, print_mode=1, save_mode=1, show_mode=0, route_choice_principle='homogeneous_DUO', route_choice_update_gradual=False, show_progress=1, show_progress_deltat=600, tmax=None, vehicle_logging_timestep_interval=1, instantaneous_TT_timestep_interval=5, hard_deterministic_mode=False, meta_data={}, user_attribute=None, user_function=None)

Create a World.

Parameters:

• name (str, optional) – The name of the world, default is an empty string.

• deltan (int, optional) – The platoon size, default is 5 vehicles.

• reaction_time (float, optional) – The reaction time, default is 1 second. This is also related to simulation time step width.

• duo_update_time (float, optional) – The time interval for route choice update, default is 600 seconds.

• duo_update_weight (float, optional) – The update weight for route choice, default is 0.5.

• duo_noise (float, optional) – The noise in route choice, default is 0.01.

• route_choice_update_gradual (bool, optional) – Whether to update route choice ratio gradually or not. True is recommended. Default is False for backward compatibility.

• eular_dt (float, optional) – The time aggregation size for eularian traffic state computation, default is 120.

• random_seed (int or None, optional) – The random seed, default is None.

• print_mode (int, optional) – The print mode, whether print the simulation progress or not. Default is 1 (enabled).

• save_mode (int, optional) – The save mode,. whether save the simulation results or not. Default is 1 (enabled).

• show_mode (int, optional) – The show mode, whether show the matplotlib visualization results or not. Default is 0 (disabled).

• route_choice_principle (str, optional) – The route choice principle, default is “homogeneous_DUO”.

• show_progress (int, optional) – Whether show network progress, default is 1 (enabled).

• show_progress_deltat (float, optional) – The time interval for showing network progress, default is 600 seconds.

• tmax (float or None, optional) – The simulation duration, default is None (automatically determined).

• vehicle_logging_timestep_interval (int, optional) – The interval for logging vehicle data, default is 1. Logging is off if set to -1. Setting large intervel (2 or more) or turn off the logging makes the simulation significantly faster in large-scale scenarios without loosing simulation internal accuracy, but outputed vehicle trajecotry and other related data will become inaccurate.

• vehicle_logging_timestep_interval – The interval for logging vehicle data, default is 1. Logging is off if set to -1. Setting large intervel (2 or more) or turn off the logging makes the simulation significantly faster in large-scale scenarios without loosing simulation internal accuracy, but outputed vehicle trajecotry and other related data will become inaccurate.

• instantaneous_TT_timestep_interval (int, optional) – The interval for computing instantaneous travel time of each link. Default is 5. If it is longer than the DUO update timestep interval, it is substituted by DUO update timestep interval to maintain reasonable route choice behavior.

• hard_deterministic_mode (bool, optional) – If True, the simulation will not use any random variables. At a merging node, a link with higher merge_priority will be always prioritized, and vehicles always choose the shortest path. This may be useful for analysis that need strict predictability. Be aware that the simulation results will be significantly different from ones with hard_deterministic_mode=False.

• meta_data (dict, optinal) – Meta data for simulation scenario. Can store arbitrary data, such as licences and simulation explanation.

• user_attribute (any, optinal) – Optinonal meta attributes that can be freely defined by a user.

• user_function (func, optinal) – User-defined custom function that is automatically called when timestep is incremented (more precisely, just before timesptep is incremented). It takes only one argument: the World object itself. Example: The following code prints the current simulation time at each timestep. If user_function=None (default), no functions will be executed. >>> def user_function(W): >>> print(W.TIME) >>> W = World(user_function=user_function) >>> … #define your scenario >>> W.exec_simulation()

Notes

A World object must be defined firstly to initiate simulation.

Methods

__init__([name, deltan, reaction_time, ...])	Create a World.
addLink(*args, **kwargs)	add a link to world
addNode(*args, **kwargs)	add a node to world
addVehicle(*args[, direct_call])	add a vehicle to world
adddemand(orig, dest, t_start, t_end[, ...])	Generate vehicles by specifying time-dependent origin-destination demand.
adddemand_area2area(x_orig, y_orig, ...[, ...])	Generate vehicles by specifying time-dependent origin-destination demand by specifying circular areas.
adddemand_nodes2nodes(origs, dests, t_start, ...)	Generate vehicles by specifying time-dependent origin-destination demand by specifying origin area (i.e., list of nodes) and destination one.
adddemand_point2point(x_orig, y_orig, ...[, ...])	Generate vehicles by specifying time-dependent origin-destination demand using coordinates.
check_simulation_ongoing()	Check whether the simulation is has not reached its final time.
copy()	Copy the World object.
exec_simulation([until_t, duration_t])	Execute the main loop of the simulation.
finalize_scenario([tmax])	Finalizes the settings and preparations for the simulation scenario execution.
generate_Links_from_csv(fname)	Generate links in the network from a CSV file.
generate_Nodes_from_csv(fname)	Generate nodes in the network from a CSV file.
generate_demand_from_csv(fname)	Generate demand in the network from a CSV file.
get_link(link)	Get a Link instance by name or object.
get_nearest_node(x, y)	Get the nearest node to the given coordinates.
get_node(node)	Get a Node instance by name or object.
get_nodes_in_area(x, y, r)	Get the nodes in the area defined by the center coordinates and radius.
load_scenario(fname[, network, demand])	Load a scenario from a file.
load_scenario_from_csv(fname_node, ...[, tmax])	Load a scenario from CSV files.
on_time(time)	Check if the current time step is close to the specified time.
save(fname)	Save the World object.
save_scenario(fname[, network, demand])	Save the scenario (Node, Link, demand) to a file.
show_network([width, left_handed, figsize, ...])	Visualizes the entire transportation network shape.
simulation_terminated()	Postprocessing after simulation finished

addLink(*args, **kwargs)

add a link to world

Parameters:

• name (str) – The name of the link.

• start_node (str | Node) – The name of the start node of the link.

• end_node (str | Node) – The name of the end node of the link.

• length (float) – The length of the link.

• free_flow_speed (float, optional) – The free flow speed on the link, default is 20.

• jam_density (float, optional) – The jam density on the link, default is 0.2. If jam_density_per_lane is specified, this value is ignored.

• jam_density_per_lane (float, optional) – The jam density per lane on the link. If specified, it overrides the jam_density value.

• number_of_lanes (int, optional) – The number of lanes on the link, default is 1.

• merge_priority (float, optional) – The priority of the link when merging at the downstream node, default is 1.

• signal_group (int or list, optional) – The signal group(s) to which the link belongs, default is 0. If signal_group is int, say 0, it becomes green if end_node.signal_phase is 0. If signal_group is list, say [0,1], it becomes green if the end_node.signal_phase is 0 or 1.

• capacity_out (float, optional) – The capacity out of the link, default is calculated based on other parameters.

• capacity_in (float, optional) – The capacity into the link, default is calculated based on other parameters.

• eular_dx (float, optional) – The space aggregation size for link traffic state computation, default is 1/10 of link length or free flow distance per simulation step, whichever is larger.

• attribute (any, optional) – Additional (meta) attributes defined by users.

• auto_rename (bool, optional) – Whether to automatically rename the link if the name is already used. Default is False (raise an exception).

Returns:

the added Link object.

Return type:

object

Notes

This function acts as a wrapper for creating a Link object and adding it to the network. It passes all given arguments and keyword arguments to the Link class initialization.

addNode(*args, **kwargs)

add a node to world

Parameters:

• name (str) – The name of the node.

• x (float) – The x-coordinate of the node (for visualization purposes).

• y (float) – The y-coordinate of the node (for visualization purposes).

• signal (list of int, optional) – A list representing the signal at the node. Default is [0], representing no signal. If a signal is present, the list contains the green times for each group. For example, `signal`=[60, 10, 50, 5] means that this signal has 4 phases, and green time for the 1st group is 60 s.

• signal_offset (float, optional) – The offset of the signal. Default is 0.

• flow_capacity (float, optional) – The maximum flow capacity of the node. Default is None, meaning infinite capacity.

• auto_rename (bool, optional) – Whether to automatically rename the node if the name is already used. Default is False.

• number_of_lanes (int, optional) – The number of lanes that can be green simultaniously at the node. Default is None.

Returns:

the added Node object.

Return type:

object

Notes

This function acts as a wrapper for creating a Node object and adding it to the network. It passes all given arguments and keyword arguments to the Node class initialization.

addVehicle(*args, direct_call=True, **kwargs)

add a vehicle to world

Parameters:

• orig (str | Node) – The origin node.

• dest (str | Node) – The destination node.

• departure_time (int) – The departure time of the vehicle.

• name (str, optional) – The name of the vehicle, default is the id of the vehicle.

• route_pref (dict, optional) – The preference weights for links, default is 0 for all links.

• route_choice_principle (str, optional) – The route choice principle of the vehicle, default is the network’s route choice principle.

• mode (str, optional) – The mode of the vehicle. Available options are “single_trip” and “taxi”, default is “single_trip”. “single_trip”: The vehicle makes a single trip from the origin to the destination. “taxi”: The vehicle serves multiple trips by specifying sequence of destinations. The destination list Vehicle.dest_list can be dynamically updated externaly.

• links_prefer (list of str, optional) – The names of the links the vehicle prefers, default is empty list.

• links_avoid (list of str, optional) – The names of the links the vehicle avoids, default is empty list.

• trip_abort (int, optional) – Whether to abort the trip if a dead end is reached, default is 1.

• attribute (any, optinonal) – Additional (meta) attributes defined by users.

• auto_rename (bool, optional) – Whether to automatically rename the vehicle if the name is already used. Default is False.

Returns:

the added Vehicle object.

Return type:

object

Notes

This function acts as a wrapper for creating a Vehicle object and adding it to the network. It passes all given arguments and keyword arguments to the Vehicle class initialization.

adddemand(orig, dest, t_start, t_end, flow=-1, volume=-1, attribute=None, direct_call=True)

Generate vehicles by specifying time-dependent origin-destination demand.

Parameters:

• orig (str | Node) – The name or object of the origin node.

• dest (str | Node) – The name or object of the destination node.

• t_start (float) – The start time for the demand in seconds.

• t_end (float) – The end time for the demand in seconds.

• flow (float, optional) – The flow rate from the origin to the destination in vehicles per second.

• volume (float, optional) – The demand volume from the origin to the destination. If volume is specified, the flow is ignored.

• attribute (any, optinonal) – Additional (meta) attributes defined by users.

adddemand_area2area(x_orig, y_orig, radious_orig, x_dest, y_dest, radious_dest, t_start, t_end, flow=-1, volume=-1, attribute=None, direct_call=True)

Generate vehicles by specifying time-dependent origin-destination demand by specifying circular areas.

Parameters:

• x_orig (float) – The x-coordinate of the center of the origin area.

• y_orig (float) – The y-coordinate of the center of the origin area.

• radious_orig (float) – The radious of the origin area. Note that too large radious may generate too sparse demand that is rounded to zero.

• x_dest (float) – The x-coordinate of the center of the destination area.

• y_dest (float) – The y-coordinate of the center of the destination area.

• radious_dest (float) – The radious of the destination area.

• t_start (float) – The start time for the demand in seconds.

• t_end (float) – The end time for the demand in seconds.

• flow (float, optional) – The flow rate from the origin to the destination in vehicles per second.

• volume (float, optional) – The demand volume from the origin to the destination. If volume is specified, the flow is ignored.

• attribute (any, optinonal) – Additional (meta) attributes defined by users.

adddemand_nodes2nodes(origs, dests, t_start, t_end, flow=-1, volume=-1, attribute=None)

Generate vehicles by specifying time-dependent origin-destination demand by specifying origin area (i.e., list of nodes) and destination one.

Parameters:

• origs (list) – The list of origin nodes. The items can be Node objects or names of Nodes.

• dests (list) – The list of destination nodes. The items can be Node objects or names of Nodes.

• t_start (float) – The start time for the demand in seconds.

• t_end (float) – The end time for the demand in seconds.

• flow (float, optional) – The flow rate from the origin to the destination in vehicles per second.

• volume (float, optional) – The demand volume from the origin to the destination. If volume is specified, the flow is ignored.

• attribute (any, optinonal) – Additional (meta) attributes defined by users.

adddemand_point2point(x_orig, y_orig, x_dest, y_dest, t_start, t_end, flow=-1, volume=-1, attribute=None, direct_call=True)

Generate vehicles by specifying time-dependent origin-destination demand using coordinates.

Parameters:

• x_orig (float) – The x-coordinate of the origin.

• y_orig (float) – The y-coordinate of the origin.

• x_dest (float) – The x-coordinate of the destination.

• y_dest (float) – The y-coordinate of the destination.

• t_start (float) – The start time for the demand in seconds.

• t_end (float) – The end time for the demand in seconds.

• flow (float, optional) – The flow rate from the origin to the destination in vehicles per second.

• volume (float, optional) – The demand volume from the origin to the destination. If volume is specified, the flow is ignored.

• attribute (any, optinonal) – Additional (meta) attributes defined by users.

check_simulation_ongoing()

Check whether the simulation is has not reached its final time.

Returns:

Returns 1 if the simulation is ongoing and has not reached its final time.

Return type:

int

copy()

Copy the World object.

Returns:

The copied World object.

Return type:

World object

exec_simulation(until_t=None, duration_t=None)

Execute the main loop of the simulation.

Parameters:

• until_t (float or None, optional) – The time until the simulation is to be executed in seconds. If both until_t and duration_t are None, the simulation is executed until the end. Default is None.

• duration_t (float or None, optional) – The duration for which the simulation is to be executed in seconds. If both until_t and duration_t are None, the simulation is executed until the end. Default is None.

Returns:

Returns 1 if the simulation is finished, 0 otherwise.

Return type:

int

Notes

The function executes the main simulation loop that update links, nodes, and vehicles for each time step. It also performs route search and updates the route preference for vehicles at specified intervals. The simulation is executed until the end time is reached or until the maximum simulation time is exceeded. The nodes, links, and vehicles must be defined before calling this function.

finalize_scenario(tmax=None)

Finalizes the settings and preparations for the simulation scenario execution.

Parameters:

tmax (float, optional) – The maximum simulation time. If not provided, it will be determined based on the departure times of the vehicles.

Notes

This function automatically called by exec_simulation() if it has not been called manually.

generate_Links_from_csv(fname)

Generate links in the network from a CSV file.

Parameters:

fname (str) – The file name of the CSV file containing link data.

generate_Nodes_from_csv(fname)

Generate nodes in the network from a CSV file.

Parameters:

fname (str) – The file name of the CSV file containing node data.

generate_demand_from_csv(fname)

Generate demand in the network from a CSV file.

Parameters:

fname (str) – The file name of the CSV file containing demand data.

get_link(link)

Get a Link instance by name or object.

Parameters:

link (str or Link object) – The name of the link or the Link object itself.

Returns:

The found Link object.

Return type:

Link object

get_nearest_node(x, y)

Get the nearest node to the given coordinates.

Parameters:

• x (float) – The x-coordinate.

• y (float) – The y-coordinate.

Returns:

The nearest Node object.

Return type:

object

get_node(node)

Get a Node instance by name or object.

Parameters:

node (str or Node object) – The name of the node or the Node object itself.

Returns:

The found Node object.

Return type:

Node object

get_nodes_in_area(x, y, r)

Get the nodes in the area defined by the center coordinates and radius.

Parameters:

• x (float) – The x-coordinate of the center.

• y (float) – The y-coordinate of the center.

• r (float) – The radius of the area.

Returns:

A list of Node objects in the area.

Return type:

list

load_scenario(fname, network=True, demand=True)

Load a scenario from a file.

Parameters:

• fname (str) – The file name to load the scenario.

• network (bool, optional) – Whether to load the network data, default is True.

• demand (bool, optional) – Whether to load the demand data, default is True.

load_scenario_from_csv(fname_node, fname_link, fname_demand, tmax=None)

Load a scenario from CSV files.

Parameters:

• fname_node (str) – The file name of the CSV file containing node data.

• fname_link (str) – The file name of the CSV file containing link data.

• fname_demand (str) – The file name of the CSV file containing demand data.

• tmax (float or None, optional) – The maximum simulation time in seconds, default is None.

on_time(time)

Check if the current time step is close to the specified time.

Parameters:

time (float) – The specified time in seconds.

Returns:

Returns True if the current time step is close to the specified time, False otherwise.

Return type:

bool

save(fname)

Save the World object.

Notes

The World object is saved as a pickle file.

save_scenario(fname, network=True, demand=True)

Save the scenario (Node, Link, demand) to a file.

Parameters:

• fname (str) – The file name to save the scenario.

• network (bool, optional) – Whether to save the network (Node, Link) data, default is True.

• demand (bool, optional) – Whether to save the demand (adddemand, etc.) data, default is True.

show_network(width=1, left_handed=1, figsize=(6, 6), network_font_size=10, node_size=6)

Visualizes the entire transportation network shape.

Parameters:

• W (Network) – The transportation network object.

• width (int, optional) – The width of the links in the visualization. Default is 1.

• left_handed (int, optional) – Determines the direction of the links. If 1, the links drawn with left-handed traffic rule. If 0, the links are right-handed. Default is 1.

• figsize (tuple, optional) – The size of the figure in inches. Default is (6, 6).

• network_font_size (int, optional) – The font size of the node and link labels. If 0, no labels will be displayed. Default is 10.

• node_size (int, optional) – The size of the nodes in the visualization. Default is 6.

simulation_terminated()

Postprocessing after simulation finished