• TraCI
TraCI

Introduction to TraCI#

TraCI is the short term for "Traffic Control Interface". Giving access to a running road traffic simulation, it allows to retrieve values of simulated objects and to manipulate their behavior "on-line". If performance is an issue you should consider using libsumo instead. You can also start with TraCI and switch to libsumo later, since the function signatures are the same.

Using TraCI#

SUMO startup#

TraCI uses a TCP based client/server architecture to provide access to sumo. Thereby, sumo acts as server that is started with additional command-line options: --remote-port <INT> where <INT> is the port sumo will listen on for incoming connections.

When started with the --remote-port <INT> option, sumo only prepares the simulation and waits for all external applications to connect and take over the control. Please note, that the --end <TIME> option is ignored when sumo runs as a TraCI server, sumo runs until the client demands a simulation end.

When using sumo-gui as a server, the simulation must either be started by using the play button or by setting the option --start before TraCI commands will be processed.

Multiple clients#

The number of clients which can connect can be given as an additional option --num-clients <INT>, where 1 is the default. Please note that in multi client scenarios you must explicitly specify the execution order of the clients using the SetOrder-command.

Each client must specify a unique (but otherwise arbitrary) integer value and the client commands will be handled in the order from the lowest to the highest value within each simulation step.

The clients are automatically synchronized after every simulation step. This means, the simulation does not advance to the next step until all clients have called the 'simulationStep'' command. Also, the simulationStep command only returns control to the client after the simulation has advanced.

Caution

The simulation will only start once all clients have connected.

Protocol specification#

Please see the TraCI Protocol Specification (including Basic Flow, Messages, Data Types).

Shutdown#

When using TraCI, the --end option of sumo is ignored. Instead the simulation is closed by issuing the close command. To detect whether all route files have been exhausted and all vehicles have left the simulation, one can check whether the command getMinExpectedNumber returns 0. The simulation will end as soon as all clients have sent the close command.

It is also possible to reload the simulation with a new list of arguments by using the load-command.

TraCI Commands#

For the following APIs, the ID is equal to the ID defined in sumo's input files. Here, you find their general structure.

Value Retrieval#

State Changing#

Subscriptions#

Using SUMO as a library#

Normally, TraCI is used to couple multiple processes: A SUMO server process and one or more TraCI client processes. Alternatively, Libsumo can be used to embed SUMO as a library into the client process. This allows using the same method signatures as in the client libraries but avoids the overhead of socket communication. Libsumo supports generating client libraries using SWIG and can therefore be used with a large number of programming languages. C++, Java and Python bindings are included when downloading a sumo-build.

Example use#

Resources#

Interfaces by Programming Language#

  • Python: the python module traci allows to interact with sumo using Python (This library is part of the sumo source code and all releases, is tested daily and supports all TraCI commands). It is also available on PyPI and can thus be installed using pip install traci.
  • C++: libtraci is a client library that is part of the sumo-source tree. It is fully API-compatible with libsumo.
  • C++: The C++ TraCIAPI is a client library that is part of the sumo-source tree. (API coverage is good but this client is no longer updated. Please use libtraci instead.)
  • C++: The Veins project provides a middle-ware for coupling sumo with OMNET++. As part of the infrastructure it provides a C++ client library for the TraCI API (API completeness is a bit behind the python client).
  • .NET: TraCI.NET is a client library with good API coverage.
  • .NET: libtracics is an experimental SWIG generated binding to the original libtraci. It has full API coverage but is untested and needs to be generated by the user from the source.
  • Matlab TraCI4Matlab. The client is included as part of each SUMO release in <SUMO_HOME>/tools/contributed/traci4matlab Not all TraCI commands have been implemented. It is recommended to use the python client from inside Matlab instead.
  • Java: libtraci is a client library that is part of the sumo-source tree. It is fully API-compatible with libsumo and a SUMO release provides pro-compiled Java bindings (via SWIG).
  • Java: TraaS provides a client library that is part of the sumo-source tree (API coverage is large but this client is no longer updated. Use libtraci instead)
  • Others: Any language that is supported by SWIG can in principle use the bindings provided by libsumo or libtraci.

V2X simulation#

TraCI allows to use sumo in combination with communication network simulators for simulating vehicular communication. See Topics/V2X for a list of available solutions.

Other Resources#

  • sumo's TraCI Server is a part of the plain distribution. The source code is located in the folder src/traci-server.

References#

  • Axel Wegener, Michal Piorkowski, Maxim Raya, Horst Hellbrück, Stefan Fischer and Jean-Pierre Hubaux. TraCI: An Interface for Coupling Road Traffic and Network Simulators. Proceedings of the 11th Communications and Networking Simulation Symposium, April 2008. Available at ACM Digital Library
  • Axel Wegener, Horst Hellbrück, Christian Wewetzer and Andreas Lübke: VANET Simulation Environment with Feedback Loop and its Application to Traffic Light Assistance. Proceedings of the 3rd IEEE Workshop on Automotive Networking and Applications, New Orleans, LA, USA, 2008. Available at IEEEXplore

Performance#

Using TraCI slows down the simulation speed. The amount of slow-down depends on many factors:

  • number of TraCI function calls per simulation step
  • types of TraCI functions being called (some being more expensive than others)
  • computation within the TraCI script
  • client language

Note

Please always consider using libsumo if performance is important. While it is much faster in general, not all optimizations mentioned below are applicable to libsumo as well. Especially subscriptions might even turn out to be slower.

Examples#

As an example use-case consider retrieving the x,y position of each vehicle during every simulation step (using the python client):

while traci.simulation.getMinExpectedNumber() > 0:
    for veh_id in traci.vehicle.getIDList():
         position = traci.vehicle.getPosition(veh_id)
    traci.simulationStep()
  • This script is able to process about 25000 vehicles per second.
  • The same value retrieval can also be sped up to 50000 vehicles per second by using subscriptions:
while traci.simulation.getMinExpectedNumber() > 0:
    for veh_id in traci.simulation.getDepartedIDList():
        traci.vehicle.subscribe(veh_id, [traci.constants.VAR_POSITION])
    positions = traci.vehicle.getAllSubscriptionResults()
    traci.simulationStep()

When using this script on the Bologna scenario (9000 vehicles, 5000 simulation steps) the following running times were recorded:

  • without TraCI 8s
  • plain position retrieval 90s
  • retrieval using subscriptions 42s

The C++ client performance is higher:

  • plain position retrieval 80s
  • retrieval using subscriptions 28s

Current and Future Development#

Historically TraCI used a different (single byte) command ID for every domain (induction loops, vehicle etc.) where the more significant half of the byte denotes the command (get, set, subscribe, ...) and the lesser significant the domain itself. To allow more than the 16 domains resulting from this split, the most significant bit (which was unused until version 1.7.0 because there were only 7 commands) is now used for the domain as well (and only three for the command). This allows for 28 domains because four general commands (like SIMSTEP) block some available combinations. Currently there are only four possible domains left.

Furthermore after the invention of libsumo some parts of the TraCI interface are so generic that it may be not so hard to invent a wrapper with Apache Kafka or Google protocol buffers which could in the long run replace the need for all the byte fiddling and the different hand crafted clients.

Troubleshooting#

Output files are not closed.#

This problem occurs if the client tries to access the output while the simulation is still closing down. This can be solved by letting the client wait for the simulation to shut down. The bug report was #524

Obsolete APIs#

There used to be two "generations" of TraCI commands. The first one mainly uses an internal mapping between the string-typed IDs used in sumo and an external representation of these which is int-based. The mapping was done internally (within TraCI). The second "generation", the current one uses string-IDs equal to those sumo reads. If you are bound to the first generation API (for instance if you want to use TraNS) you can only use sumo up to version 0.12.3. See FAQ about obtaining an old version.