uxsim.Vehicle

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

__init__(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)

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.

Methods

__init__(W, orig, dest, departure_time[, ...])	Create a vehicle (more precisely, platoon)
add_dest(dest[, order])	Add a destination to the vehicle's destination list.
add_dests(dests)	Add multiple destinations to the vehicle's destination list.
carfollow()	Drive withing a link.
end_trip()	Procedure when the vehicle finishes its trip.
get_xy_coords([t])	Get the x-y coordinates of the vehicle.
record_log([enforce_log])	Record travel logs.
route_next_link_choice()	Select a next link from the current link.
route_pref_update([weight])	Updates the vehicle's link preferences for route choice.
set_links_avoid(links)	Set the links the vehicle avoids.
set_links_prefer(links)	Set the links the vehicle prefers.
traveled_route()	Returns the route this vehicle traveled.
update()	Updates the vehicle's state and position.

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.