node.mobility2 module

Module mobility2 contains node mobility for cars moving on a map. This module has the following features:

  • car following

  • number of lanes is 1 for all roads

  • all junctions must have traffic light control at the user simulation level

Every mobility instance for a vehicle is described by a route, which is a list of road segments. A route is an established mobility path for a vehicle to move from its initial location to the ending location. node.mobility2.RoutePath is the class describing a route. We also define the following:

  • road segment: a tuple (start_loc, end_loc, speed, street_id).

  • segment list: an ordered list of road segments forming a route.

  • _RoutePoint: an internal class describing a point on a route. It contains the location of the point, and segment index pointing to the segment in the segment list where this point is currently on. Each vehicle mobility records two route points, head and tail points of the vehicle.

One can visualize the relationship between route, road segments, and route points as:

         road_segment        vehicle ->
X------X--------------X--------[CAR>---------X-------X  <-- a route with 4
^                     ^        ^   ^         ^       ^       road segments
|                     |        |   |         |       |
initial           current      |   |    current     end of
location          startpoint   |   |    endpoint    mobility
                      tail_point   head_point

Note

  • Created by: CH Foh (2021)

  • Contributed by: …

class node.mobility2.RouteHandler(scenario, map)

Bases: object

This is the route handler to manage node movement on a given map, all nodes moving on the same map should use the same route handler. The handler is needed for node.mobility2.RoutePath.

To make sure a vehicle can follow another vehicle in front, it needs to find which other vehicles are potentially in front of itself. With hundreds of vehicles on the map, checking individual vehicle for their location to find one that is in front of a vehicle can be inefficiency. Here we use a lookup table to efficiently narrow down to those vehicles on the same street_id for the checking. This class handles the lookup and perform the search for the vehicle in front.

Parameters
scenariosim.scenario.BaseScenario subclass

The scenario that hosts this handler.

mapmap.mapinfo.MapInfo

The map to be used for the mobility.

Methods

get_next_route_id(head_point)

This method get the next route’s route_id Returns ——- : route_id

is_ready()

Test if the handler is ready for use.
__init__(scenario, map)

This is the constructor.

is_ready() → bool

Test if the handler is ready for use. The readiness of the handler mainly depends on the readiness of the map. If the handler is not ready, none of its methods will work properly. To improve execution efficiency, the user simulation should ensure the handler is ready which is a one-time check. Individual methods will not repeatedly check for readiness.

Returns
bool

It returns whether this instance is ready to use.

get_next_route_id(head_point)

This method get the next route’s route_id Returns ——- : route_id

class node.mobility2.RoutePath(handler, start_pin, end_pin, delay_start)

Bases: node.mobility.BaseMobility

This class provides a specification of a route for a node to move with other vehicles on the same route. The mobility observes lanes, junctions and the vehicles in front. The mobility algorithm implements a specific car-following model.

Note

The current version implemented the following of a vehicle in front assuming the road has one lane. Observing lanes and junctions will be next features to add.

Parameters
handlernode.mobility2.RouteHandler

The route handler which contains the map for the node to move on. The method assumes that the handler is ready for use. Otherwise, the method may throw a run-time error.

start_pinstr

The unique name of the starting location.

end_pinstr

The unique name of the ending location.

delay_startfloat

Apply a delay start to the mobility based on this input.

Methods

assign_speed(road_segment_index, speed)

Use this method to assign a speed for the node to move on a specific road segment.

get_dir()

See the base class for details.

get_displacement()

This method returns the displacement of the node in the last simulation time step.

get_loc()

Get the location of the node.

get_name()

Call this method to get the name of this class.

get_node()

Get the node that uses this mobility instance.

get_road_segment_list()

Get the establish route which is a list of tuples describing the road segments: (start_location,end_location,speed,street_id).

get_speed()

See the base class for details.

is_active()

This method returns whether the node on this route is active.

is_pause()

Check if the movement of the node is paused.

pause([pause_flag])

Apply a pause to the movement of the node, or resume the movement from a pause.

restart([delay_start])

Use this method to restart the mobility.

set_dir(direction)

The method in this class will not do anything, since the direction is calculated automatically based on the moving direction.

sim__do_move(time_step)

This method is used within the simulation engine, not for user simulation.
__init__(handler, start_pin, end_pin, delay_start)

This is the constructor.

get_road_segment_list()

Get the establish route which is a list of tuples describing the road segments: (start_location,end_location,speed,street_id). The speed is set to -1 initially for user simulation to fill in. A negative speed means the mobility engine will later replace it with some speed which can be a random or the maximum speed specified by the street_id.

Note

The user simulation should not modify the locations and street_id, but may specify a desired speed directly into the tuple or use the method assign_speed() to do so.

Returns
List of Tuples

It returns route or an empty list if no route is established. The route is a list of tuples: (start_location:sim.loc.LOC,end_location:sim.loc.LOC,

speed:float,street_id:int).

assign_speed(road_segment_index, speed)

Use this method to assign a speed for the node to move on a specific road segment.

Parameters
road_segment_indexint

The index of the road segment given in the road segment list.

speedfloat

The speed for the node to move on the road segment (in km/h).

get_name()

Call this method to get the name of this class.

Returns
str

This class returns “route”.

is_active()

This method returns whether the node on this route is active. the node is considered active if it has started to move (i.e. passed the delayed start) and yet to reach the final destination.

Returns
boolean

It returns whether the node on this route is active.

sim__do_move(time_step) → bool

This method is used within the simulation engine, not for user simulation. This method to used by the simulation engine to make this node to move over a time_step. See the base class for details.

Parameters
time_stepfloat

The time to move forward to (in seconds).

Returns
boolean

Whether the mobility has reached an end. It always returns False when the movement is paused.

get_speed()

See the base class for details.

get_loc() → sim.loc.ScreenXY

Get the location of the node. See the base class for details.

set_dir(direction)

The method in this class will not do anything, since the direction is calculated automatically based on the moving direction.

get_dir()

See the base class for details.

restart(delay_start=None)

Use this method to restart the mobility.