SUMO - More on... Traffic Lights

This document is a part of SUMO - Simulation of Urban MObility. SUMO is an open source microscopic road traffic simulation. It can be found under http://sumo.sourceforge.net/.

This document fits to version 0.9.5. We will try to keep it up to date with the next versions.

Herein, we will describe how traffic lights are implemented and used within SUMO. This document has the following structure:

This document contains information for users who are interested how traffic light systems are implemented in SUMO and who need further information on how to define own tls programs. It is also meant for developers who want to extend SUMO.

At first, a description about how right-of-way rules are applied and how traffic lights work in SUMO is given.

Then, tls-algorithms already implemented in SUMO are described (TBD: incomplete).

Then, it is shown how one can implement own tls algorithms (TBD: incomplete).

Then it is described how right-of-way rules and tls-algorithms are loaded.

We close with some further information about how to deal with tls within SUMO. These information are mainly answers to questions posted by users.

Each lane (MSLane) beside dead ends has a list of at least one following lane. A link (MSLink) connects this following and the lane we regard. Basically, we consider two types of connections between lanes. In the first case, vehicles are able to pass the connection every time, without regarding other, possibly crossing traffic. Such connections may be found at highways or if the connection is a primary road and it is assured that the vehicle is able to pass this link without a collision. Such connections are called "priorised" connections. The other connections are called "unpriorised". They are found on minor roads and a vehicle passing them must decelerate in front of them, because it may have to stop to let other vehicles pass the junction first. Please regard, that a junction may consist of several connections (links) of different type.

If a vehicle approaches a link (MSLink), it lets the link know about it by calling void MSLink::setApproaching(MSVehicle *approaching). This is done in void MSVehicle::vsafeCriticalCont( SUMOReal boundVSafe ) as soon as a vehicle will have to decelerate to manage to stop in front of the link. Even if the vehicle is too near or too fast to decelerate in front of the link, the link will still be informed until the vehicle will finally pass it. By doing this, each link knows whether a vehicle is approaching or not and stores this vehicle in MSLink::myApproaching. In addition, the information about approaching a link is stored by the link into the MSLogicJunction::Request structure of the junction (MSRightOfWayJunction) it belongs to. After all vehicles have stored this information, MSRightOfWayJunction is able to compute which of the approaching vehicles will have to wait and which not using its MSJunctionLogic.

If you are confused about all these classes, the next diagram which shows how the hierarchy of SUMO junction classes, may help you.

	Note
	Remark that some of the classes are interfaces with only one implementation. It is possible, that this tree is a matter to change in the next time.

Figure 2.1. Junction classes within SUMO

In the next pass (but within the same simulation step), each of the vehicles is touched again, but by now it is known whether the vehicle is allowed to pass the junction using his link or not. If not, the vehicle will decelerate and stop in front of the link (or a vehicle in front of it, that is also waiting). If the link is "unpriorised", the vehicle will decelerate in front of it, even if it may pass it. If the link is "priorised" and the vehicle may pass, the vehicle will continue his drive without being hindered.

As we have seen, a MSLogicJunction gives way to the vehicles after the knowledge about all incoming vehicles has been set. We have seen that this information was stored in a structure named "MSLogicJunction::Request". This is simply a list of bits, a std::bitset<64>, where each bit represents the information whether a certain link is approached by a vehicle currently (it's then set to true otherwise it's false).

What traffic lights do is simply to mask off those requests which are approaching a currently red sign. By doing this, the response for these streams is also set to false which forces the approaching vehicles to stop in front of the junction. Furthermore, this method keeps the row-logic of the junction untouched, what allows to use it for letting vehicles moving left - in the part of the world that drives on the right sied, that means those streams which have to cross an enemy stream - wait until there is a gap in the enemy stream they can use to move over the junction.

Figure 2.2. TLS classes within SUMO

What we furthermore need to know is how a traffic light is forces to switch its phases and how the links get informed about this. When being instantiated, the tls adds an event to SUMO's event handler (MSEventHandler). This is done within the MSTrafficLightLogic-constructor, a class from which all tls algorithms are derived (see above). This event, being a MSTrafficLightLogic::SwitchCommand executes the following steps:

SUMOTime execute() {
   // get the current phase index
   size_t step1 = myTLLogic->getStepNo();
   // try to switch, get next duration
   SUMOTime next = myTLLogic->trySwitch();
   // get the phase index after possible switch
   size_t step2 = myTLLogic->getStepNo();
   // has the phase changed?
   if(step1!=step2) {
      // yes -> do some further actions (see below)
      myTLLogic->onSwitch();
      // inform the links about current state
      myTLLogic->setLinkPriorities();
   }
   // return period after which the tls shall be tried to switch again
   return next;
}

Let's review it. At first, we remember the state of the tls before trying to switch it in the variable step1. This "state" is simply the index of the current tls phase. Then, we try to switch the tls using trySwitch() and gain the period to the next try which we save in next. After this, we check whether the tls has really changed by asking for its current step. If the step before and the step after trying to switch the tls are not the same, the tls has switched. We then inform the links about it using the MSTrafficLightLogic::setLinkPriorities function. The call to onSwitch should not bother you, herein. It is not a part of the tls-steering, but used to inform connected structures about the phase change. By now, only assigned detectors may be informed and their assignment is done separately from the tls-implementations. The comparison between the step before and after trying to switch is needed, as maybe the tls decides not to switch, yet, although the phases duration is over (TBD: add a description of agentbased tls). After all has been done, we return the period to wait until we again try to switch the tls. If you want, your implementation of "trySwitch" may always return 1 in order to check the tls each simulation step.

So the whole procedure of bringing a vehicle save over a junctions is as following:

What is the meaning of the sixth step? Imagine what shall happen with vehicles driving over yellow. They should stop, but if they are too near to the junction, one has to let them through. Also, they have to be taken into account if an enemy stream exists. In this case, they maybe have to make vehicles on this stream wait. To achieve this, at first only red links are set to false. This is given as input to the junction's row-logics and that lets all vehicles having red wait, vehicles which have yellow may be able to pass the junction. Then, vehicles having yellow are set to false which lets them try to stop in front of the tls.

This tls-type simply obtains the list of phases from the description and switches between the cycles after each cycle's period is over. We have seen that the tls algorithm is stored in trySwitch(). What a simple traffic light's implementation does is the following:

SUMOTime
MSSimpleTrafficLightLogic::trySwitch()
{
    // increment the index
    myStep++;
    // if the last phase was reached ...
    if(myStep==myPhases.size()) {
        // ... set the index to the first phase
        myStep = 0;
    }
    // return offset to the next switch
    assert(myPhases.size()>myStep);
    return myPhases[myStep]->duration;
}

That means that we simply rotate our index over the phases and return each phase's duration as the time that has to pass before the traffic light is switched one step further.

This tls-type simply obtains the list of phases from the description and switches between the cycles after each cycle's period is over. We have seen that the tls algorithm is stored in trySwitch(). What a simple traffic light's implementation does is the following:

SUMOTime
MSSimpleTrafficLightLogic::trySwitch()
{
    // increment the index
    myStep++;
    // if the last phase was reached ...
    if(myStep==myPhases.size()) {
        // ... set the index to the first phase
        myStep = 0;
    }
    // return offset to the next switch
    assert(myPhases.size()>myStep);
    return myPhases[myStep]->duration;
}

That means that we simply rotate our index over the phases and return each phase's duration as the time that has to pass before the traffic light is switched one step further.

An instance of NLHandler is used to parse the XML-descriptions of the network and of the tls-logics contained herein. All elements related to traffic lights and junctions at all are delegated to an instance of NLJunctionControlBuilder (from version 0.9.0 on). Herein, the whole description is stored temporarily until the complete description has been read. Then, as the closing tl-logic tag occures, the tls logic is build in accordace to the read type.