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

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

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.

enforce_route(route[, set_avoid])

Enforce the vehicle to use the specified route.

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([include_arrival_time, ...])

Returns the route this vehicle traveled.

update()

Updates the vehicle's state and position.

add_dest(dest, order=-1)[source]

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

Add multiple destinations to the vehicle’s destination list.

Parameters:

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

carfollow()[source]

Drive withing a link.

end_trip()[source]

Procedure when the vehicle finishes its trip.

enforce_route(route, set_avoid=False)[source]

Enforce the vehicle to use the specified route. The route should connect the origin to the destination. TODO: add consistency check

Parameters:
  • route (List of Link) – The route for this vehicle.

  • set_avoid (bool) – If True, the vehicle only travel the links in route argument. This is very strict. If the route is not consistent (e.g., the route does not completely connect between the origin and the destination), it will raise an exception.

get_xy_coords(t=-1)[source]

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

Record travel logs.

Parameters:

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

Select a next link from the current link.

route_pref_update(weight=1)[source]

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 the links the vehicle avoids.

Parameters:

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

Set the links the vehicle prefers.

Parameters:

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

traveled_route(include_arrival_time=True, include_departure_time=False)[source]

Returns the route this vehicle traveled.

Parameters:
  • include_arrival_time (bool) – If true, return the arrival time to the destination as well. -1 means it did not reach the destination.

  • include_departure_time (bool) – If true, return the departure time from the origin as well. It will be different from the entering time to the first link if there are congestion (i.e., the vehicle need to enter the network).

Returns:

  • Route – The route this vehicle traveled.

  • list – The time at which the vehicle entered each link. If include_arrival_time is true, the last element is the time the vehicle reached the destination. If include_departure_time is true, the first element is the time the vehicle departed from the origin. This complexity is actually due to a design failure in the past. These options are added to keep the backward compatibility.

update()[source]

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.