Environment API¶

In order to test an intersection control algorithm in a new environment (for example a different simulation environment than the provided SUMO environment, or a physical environment using physical vehicles), subclasses of intersection_control.core.environment.Environment, intersection_control.core.environment.VehicleHandler and intersection_control.core.environment.IntersectionHandler will need to be created, and the following methods will need to be implemented.

Any intersection control algorithm will interface with the environment in which it operates through this API.

class Environment¶

abstract clear()¶: Removes all vehicles from the environment

abstract get_added_vehicles() → List[str]¶

Returns a list of the vehicles added to the environment in the last time step

In a simulation environment, a vehicle demand generator may be adding vehicles to the environment at certain entry points. This method allows the user know about these new vehicles entering the environment

Returns: List of vehicle IDs added to the environment

abstract get_current_time() → float¶

Returns the current time in the environment in seconds

Returns: The current time in seconds

abstract get_removed_vehicles() → List[str]¶

Returns a list of the vehicles removed from the environment in last time step

In a simulation environment, this may be, for example, because the vehicle has completed its trip.

Returns: List of vehicle IDs removed from the environment

abstract property intersections: intersection_control.core.environment.intersection_handler.IntersectionHandler¶: Any environment interactions related to intersections should be performed through the intersection handler, accessible through this intersections property

abstract step()¶

Performs a single step in the environment

In a simulated environment, this should advance the simulation by a single time step, and in a real-time environment, this could either introduce a time delay - in order to tune the sampling frequency, or simply do nothing

abstract property vehicles: intersection_control.core.environment.vehicle_handler.VehicleHandler¶: Any environment interactions related to vehicles should be performed through the vehicle handler, accessible through this vehicles property

class IntersectionHandler¶

abstract get_height(intersection_id: str) → float¶

Return the height of the given intersection in metres

Parameters: intersection_id (str) – The id of the intersection you want the height of
Returns: The height of the given intersection in metres

abstract get_ids() → List[str]¶: Return the ids of all intersections in the environment

abstract get_position(intersection_id: str) → Tuple[float, float]¶

Return the position of the centre of the given intersection

Parameters: intersection_id (str) – The id of the intersection you want the position of
Returns: (x,y) the position of the centre of the given intersection in the environment’s coordinate space

abstract get_trajectories(intersection_id: str) → Dict[str, intersection_control.core.environment.intersection_handler.Trajectory]¶

Return all the possible trajectories through the given intersection

Parameters: intersection_id (str) – The id of the intersection you want the trajectories for
Returns: A dictionary mapping trajectory ids to trajectories

abstract get_width(intersection_id: str) → float¶

Return the width of the given intersection in metres

Parameters: intersection_id (str) – The id of the intersection you want the width of
Returns: The width of the given intersection in metres

abstract set_traffic_light_phase(intersection_id: str, phase: Tuple[Set[str], Set[str], Set[str]])¶

Set the traffic lights at the given intersection to the phase described by phase

Parameters

intersection_id (str) –
phase (Tuple[Set[str], Set[str], Set[str]]) – A tuple of length 3: (Green, Yellow, Red) where each of Green, Yellow and Red are sets of trajectory IDs such that all the trajectories in Red will be shown a red light, and the same for Yellow and Green

class Trajectory¶

Class to represent a trajectory through an intersection

A trajectory has a speed limit, and can be moved along. Different environments may implement trajectories in different ways, and this API should cater to most all of them

class VehicleHandler¶

abstract approaching(vehicle_id: str) → Optional[str]¶

Returns the id of the intersection the given vehicle is approaching, or None if it is not approaching an intersection

Param: str vehicle_id: The ID of the vehicle we are interested in
Returns: Either the ID of the intersection being approached, or None

abstract departing(vehicle_id: str) → Optional[str]¶

Returns the id of the intersection the given vehicle is departing, or None if it is not departing an intersection

Param: str vehicle_id: The ID of the vehicle we are interested in
Returns: Either the ID of the intersection being departed, or None

abstract get_acceleration(vehicle_id: str) → float¶

Returns the current acceleration of the given vehicle

Parameters: vehicle_id (str) – The ID of the vehicle we want the acceleration of
Returns: The acceleration of the vehicle in m/s^2

abstract get_direction(vehicle_id: str) → float¶

Returns the direction the given vehicle is currently facing in radians

The positive horizontal axis is taken to have a direction of 0, and the angle increases as the vehicle rotates clockwise like so:

      pi/2
       ^
       |
pi <---+---> 0
       |
       v
    -pi/2

Parameters: vehicle_id (str) – The ID of the vehicle we want to get the heading of
Returns: The direction of the vehicle in radians

abstract get_driving_distance(vehicle_id: str) → float¶

Returns the driving distance of the vehicle to the end of the current edge/road

Parameters: vehicle_id (str) – The ID of the vehicle we are interested in
Returns: The driving distance in metres

abstract get_ids() → List[str]¶

Returns a list of all vehicle IDs currently in the environment

Returns: List of vehicle IDs

abstract get_length(vehicle_id: str) → float¶

Returns the length of the given vehicle

Parameters: vehicle_id (str) – The ID of the vehicle we are interested in
Returns: Length of the vehicle in metres

abstract get_max_acceleration(vehicle_id: str) → float¶

Returns the maximum acceleration possibility of the given vehicle

Parameters: vehicle_id (str) – The ID of the vehicle we want the maximum acceleration of
Returns: The maximum acceleration of the vehicle in m/s^2

abstract get_max_deceleration(vehicle_id: str) → float¶

Returns the maximum deceleration possibility of the given vehicle

Parameters: vehicle_id (str) – The ID of the vehicle we want the maximum deceleration of
Returns: The maximum deceleration of the vehicle in m/s^2

abstract get_position(vehicle_id: str) → Tuple[float, float]¶

Returns the current position of the given vehicle

Parameters: vehicle_id (str) – The ID of the vehicle we are interested in
Returns: The (x,y) position of the vehicle

abstract get_speed(vehicle_id: str) → float¶

Returns the current speed of the given vehicle

Parameters: vehicle_id (str) – The ID of the vehicle we are interested in
Returns: The speed in metres/second

abstract get_speed_limit(vehicle_id: str) → float¶

Returns the maximum speed the given vehicle should be travelling at

This will usually be determined by the speed limit of the road the vehicle is currently on

abstract get_trajectory(vehicle_id: str) → str¶

Returns the ID of the trajectory the vehicle is planning to take through the next intersection

Parameters: vehicle_id (str) – The ID of the vehicle we are interested in
Returns: Trajectory ID

abstract get_width(vehicle_id: str) → float¶

Returns the width of the given vehicle

Parameters: vehicle_id (str) – The ID of the vehicle we are interested in
Returns: Width of the vehicle in metres

abstract in_intersection(vehicle_id: str) → bool¶

Returns True iff the given vehicle is currently inside an intersection

Parameters: vehicle_id (str) – The ID of the vehicle we are interested in
Returns: True iff the given vehicle is currently inside an intersection

abstract set_desired_speed(vehicle_id: str, to: float)¶

Sets the desired speed of the given vehicle

Special case when to is set to -1: The vehicle’s speed will return to a “default”, controlled by the environment - e.g. in SUMO this means the vehicle’s speed will be controlled by the default car-following models

Parameters

vehicle_id (str) – The ID of the vehicle you would like to change the desired speed of
to (float) – The speed (in m/s) you would like the desired speed to be set to. If set to -1, the vehicle’s speed will be controlled by the environment.