uxsim.uxsim

UXsim: Macroscopic/mesoscopic traffic flow simulator in a network. This uxsim.py is the core of UXsim. It summarizes the classes and methods that are essential for the simulation.

Classes

Link(W, name, start_node, end_node, length)	Link in a network.
Node(W, name, x, y[, signal, signal_offset, ...])	Node in a network.
Route(W, links[, name, trust_input])	Class for a route that store concective links.
RouteChoice(W)	Class for computing shortest path for all vehicles.
Vehicle(W, orig, dest, departure_time[, ...])	Vehicle or platoon in a network.
World([name, deltan, reaction_time, ...])	World (i.e., simulation environment).

class uxsim.uxsim.Link(W, name, start_node, end_node, length, free_flow_speed=20, jam_density=0.2, jam_density_per_lane=None, number_of_lanes=1, merge_priority=1, signal_group=[0], capacity_out=None, capacity_in=None, eular_dx=None, attribute=None, user_attribute=None, user_function=None, auto_rename=False)

Link in a network.

Create a link

Parameters:

• W (object) – The world to which the link belongs.

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

• user_attribute (any, optional) – Additional (meta) attributes defined by users. Same functionality to attribute, but with more understandable name.

• user_function (func, optinal) – User-defined custom function that is automatically called when timestep is incremented (more precisely, when update() is called). It takes only one argument: the Link object itself. Example: The following code prints the current number of vehicles on the link at each timestep. If user_function=None (default), no functions will be executed. >>> def user_function(link): >>> print(len(link.vehicles)) >>> W = World(…) >>> W.addLink(“link”, “node1”, “node2, 1000, user_function=user_function) >>> … #define your scenario >>> W.exec_simulation()

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

speed

Average speed of traffic on the link.

Type:

float

density

Density of traffic on the link.

Type:

float

flow

Flow of traffic on the link.

Type:

float

num_vehicles

Number of vehicles on the link.

Type:

float

num_vehicles_queue

Number of slow vehicles (due to congestion) on the link.

Type:

float

free_flow_speed

Free flow speed of the link.

Type:

float

jam_density

Jam density of the link.

Type:

float

capacity_out

Capacity for outflow from the link.

Type:

float

capacity_in

Capacity for inflow to the link.

Type:

float

merge_priority

The priority of the link when merging at the downstream node.

Type:

float

Notes

Traffic Flow Model:

• The link model follows a multi-lane, single-pipe approach where FIFO is guaranteed per link and no lane changing occurs.

• Fundamental diagram parameters such as free_flow_speed, jam_density (or jam_density_per_lane), and number_of_lanes determine the link’s flow characteristics. Reaction time of drivers REACTION_TIME is a grobal parameter.

• Real-time link status for external reference is maintained with attributes speed, density, flow, num_vehicles, and num_vehicles_queue.

Traffic Flow Model Parameters:

• Their definition is illustrated as https://toruseo.jp/UXsim/docs/_images/fundamental_diagram.png

• If you are not familiar to the traffic flow theory, it is recommended that you adjust only free_flow_speed and number_of_lanes for the traffic flow model parameters, leaving the other parameters at their default values.

Capacity and Bottlenecks:

• The capacity_out and capacity_in parameters set the outflow and inflow capacities of the link. If not provided, the capacities are unlimited.

• These capacities can represent bottlenecks at the beginning or end of the link.

Connection to Node Model:

• At the downstream end of a sending link, vehicles in all lanes have the right to be sent out, but FIFO order is maintained.

• At the upstream end of a receiving link, all lanes can accept vehicles.

Parameter Adjustments:

• Some traffic flow model parameters like free_flow_speed, jam_density, capacity_out, capacity_in, and merge_priority can be altered during simulation to reflect changing conditions.

Details on Multi-lane model:

• Link model:

  • Multiple lanes with single-pipe model. FIFO is guaranteed per link. No lane changing.

  • Links have a lanes attribute representing the number of lanes.

  • Each vehicle has a lane attribute.

  • Each vehicle follows the leader vehicle in the same lane, i.e., the vehicle lanes steps ahead on the link.

• Node model:

  • Sending links:

    • Vehicles in all lanes at the downstream end of the link have the right to be sent out.

    • However, to ensure link FIFO, vehicles are tried to be sent out in the order they entered the link. If a vehicle cannot be accepted, the outflow from that link stops.

  • Receiving links:

    • All lanes at the upstream end of the link can accept vehicles.

Details on Fundamental diagram parameters (+: input, ++: alternative input):

• free_flow_speed (m/s)+

• jam_density (veh/m/LINK)+

• jam_density_per_lane (veh/m/lane)++

• lanes, number_of_lane (lane)+

• tau: y-intercept of link FD (s/veh*LINK)

• REACTION_TIME, World.reaction_time (s/veh*lane)

• w (m/s)

• capacity (veh/s/LINK)

• capacity_per_lane (veh/s/lane)

• delta: minimum spacing (m/veh*LINK)

• delta_per_lane: minimum spacing in lane (m/veh*lane)

• q_star: capacity (veh/s/LINK)

• k_star: critical density (veh/s/LINK)

• capacity_in, capacity_out: bottleneck capacity at beginning/end of link (veh/s/LINK)+

• Node.flow_capacity: node flow capacity (veh/s/LINK-LIKE)+

actual_travel_time(t)

Get actual travel time of vehicle who enters this link on time t. Note that small error may occur due to fractional processing.

Parameters:

t (float) – Time in seconds.

Returns:

The actual travel time.

Return type:

float

arrival_count(t)

Get cumulative vehicle count of arrival to this link on time t

Parameters:

t (float) – Time in seconds.

Returns:

The cumulative arrival vehicle count.

Return type:

float

departure_count(t)

Get cumulative vehicle count of departure from this link on time t

Parameters:

t (float) – Time in seconds.

Returns:

The cumulative departure vehicle count.

Return type:

float

in_out_flow_constraint()

Link capacity updates.

init_after_tmax_fix()

Initalization before simulation execution.

instant_travel_time(t)

Get instantaneous travel time of this link on time t

Parameters:

t (float) – Time in seconds.

Returns:

The instantaneous travel time.

Return type:

float

set_traveltime_instant()

Compute instantaneous travel time.

update()

Make necessary updates when the timestep is incremented.

class uxsim.uxsim.Node(W, name, x, y, signal=[0], signal_offset=0, flow_capacity=None, auto_rename=False, number_of_lanes=None, attribute=None, user_attribute=None, user_function=None)

Node in a network.

Create a node

Parameters:

• W (object) – The world to which the node belongs.

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

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

• user_attribute (any, optional) – Additional (meta) attributes defined by users. Same functionality to attribute, but with more understandable name.

• user_function (func, optinal) – User-defined custom function that is automatically called when timestep is incremented (more precisely, when update() is called). It takes only one argument: the Node object itself. Example: The following code prints the current number of incoming vehicles to the node at each timestep. If user_function=None (default), no functions will be executed. >>> def user_function(node): >>> print(len(node.incoming_vehicles)) >>> W = World(…) >>> W.addNode(“node”, 0, 0, user_function=user_function) >>> … #define your scenario >>> W.exec_simulation()

signal_phase

The phase of current signal. Links that have the same signal_group have a green signal.

Type:

int

signal_t

The elapsed time since the current signal phase started. When it is larger than Link.signal[Link.signal_phase], the phase changes to the next one.

Type:

float

flow_capacity_update()

flow capacity updates.

generate()

Departs vehicles from the waiting queue.

Notes

If there are vehicles in the generation queue of the node, this method attempts to depart a vehicle to one of the outgoing links. The choice of the outgoing link is based on the vehicle’s route preference for each link. Once a vehicle is departed, it is removed from the generation queue, added to the list of vehicles on the chosen link, and its state is set to “run”.

signal_control()

Updates the signal timings for a traffic signal node.

transfer()

Transfers vehicles between links at the node.

Notes

This method handles the transfer of vehicles from one link to another at the node. A vehicle is eligible for transfer if: - The next link it intends to move to has space. - The vehicle has the right signal phase to proceed. - The current link has enough capacity to allow the vehicle to exit. - The node capacity is not exceeded.

update()

Make necessary updates when the timestep is incremented.

class uxsim.uxsim.Route(W, links, name='', trust_input=False)

Class for a route that store concective links.

Define a route.

links

List of links. The contents are Link objects.

Type:

list

links_name

List of name of links. The contents are str.

Type:

list

trust_input

True if you trust the links in order to reduce the computation cost by omitting verification.

Type:

bool

Examples

>>> route = Route(W, ["l1", "l2", "l3"])
... vehicle_object.links_prefer = route
This will enforce the vehicle to travel the route if the route covers the entire links between the OD nodes of the vehicle.

>>> route = Route(W, ["l1", "l2", "l3"])
... for link in route:
...     print(link)
This will print the links in the route.

actual_travel_time(t, return_details=False)

Actual travel time for a (hypothetical) vehicle who start traveling this route on time t.

Parameters:

• t (float) – Time in seconds.

• return_details (bool) – True if you want travel time per link.

Returns:

• float – The actual travel time.

• list (if return_details is True) – List of travel time per link.

class uxsim.uxsim.RouteChoice(W)

Class for computing shortest path for all vehicles.

Create route choice computation object.

Parameters:

W (object) – The world to which this belongs.

homogeneous_DUO_update()

Update link preference of all homogeneous travelers based on DUO principle. Vectorized by Claude 3.5 Sonnet.

route_search_all(infty=inf, noise=0)

Compute the current shortest path based on instantaneous travel time.

Parameters:

• infty (float) – value representing infinity.

• noise (float) – very small noise to slightly randomize route choice. useful to eliminate strange results at an initial stage of simulation where many routes has identical travel time.

class uxsim.uxsim.Vehicle(W, orig, dest, departure_time, name=None, route_pref=None, route_choice_principle=None, mode='single_trip', links_prefer=[], links_avoid=[], trip_abort=1, departure_time_is_time_step=0, attribute=None, user_attribute=None, user_function=None, auto_rename=False)

Vehicle or platoon in a network.

Create a vehicle (more precisely, platoon)

Parameters:

• W (object) – The world to which the vehicle belongs.

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

• user_attribute (any, optional) – Additional (meta) attributes defined by users. Same functionality to attribute, but with more understandable name.

• user_function (func, optinal) – User-defined custom function that is automatically called when timestep is incremented (more precisely, when update() is called). It takes only one argument: the Vehicle object itself. Example: The following code prints the current speed of vehicle at each timestep. If user_function=None (default), no functions will be executed. >>> def user_function(veh): >>> print(veh.speed)) >>> W = World(…) >>> … #define your scenario >>> W.addVehicle(“orig”, “dest”, 100, user_function=user_function) >>> W.exec_simulation()

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

add_dest(dest, order=-1)

Add a destination to the vehicle’s destination list.

Parameters:

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

• order (int, optional) – The order of the destination in the list. Default is -1, which appends the destination to the end of the list.

add_dests(dests)

Add multiple destinations to the vehicle’s destination list.

Parameters:

dests (list of str | Node) – The list of destinations to be added.

carfollow()

Drive withing a link.

end_trip()

Procedure when the vehicle finishes its trip.

get_xy_coords(t=-1)

Get the x-y coordinates of the vehicle. If t is given, the position at time t is returned based on the logs.

Parameters:

t (int | float, optional) – Time in seconds. If it is -1, the latest position is returned.

record_log(enforce_log=0)

Record travel logs.

Parameters:

enforce_log (bool, optional) – Record log regardless of the logging interval, default is 0.

route_next_link_choice()

Select a next link from the current link.

route_pref_update(weight=1)

Updates the vehicle’s link preferences for route choice.

Parameters:

weight (float) – The weight for updating the link preferences based on the recent travel time. Should be in the range [0, 1], where 0 means the old preferences are fully retained and 1 means the preferences are completely updated. THIS IS DISABLED FOR NOW.

Notes

This method updates the link preferences used by the vehicle to select its route based on its current understanding of the system.

• If the vehicle’s route choice principle is “homogeneous_DUO”, it will update its preferences based on a global, homogenous dynamic user optimization (DUO) model.

• If the route choice principle is “heterogeneous_DUO”, it will update its preferences based on a heterogeneous DUO model, considering both its past preferences and the system’s current state. This is imcomplete feature. Not recommended.

The updated preferences guide the vehicle’s decisions in subsequent route choices.

set_links_avoid(links)

Set the links the vehicle avoids.

Parameters:

links (list of str) – The list of link names the vehicle avoids.

set_links_prefer(links)

Set the links the vehicle prefers.

Parameters:

links (list of str) – The list of link names the vehicle prefers.

traveled_route()

Returns the route this vehicle traveled.

update()

Updates the vehicle’s state and position.

Notes

This method updates the state and position of the vehicle based on its current situation.

• If the vehicle is at “home”, it checks if the current time matches its departure time. If so, the vehicle’s state is set to “wait” and it is added to the generation queue of its origin node.

• If the vehicle is in the “wait” state, it remains waiting at its departure node.

• If the vehicle is in the “run” state, it updates its speed and position. If the vehicle reaches the end of its current link, it either ends its trip if it has reached its destination, or requests a transfer to the next link.

• If the vehicle’s state is “end” or “abort”, no further actions are taken.

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

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