General Introduction to SUMO Simulation

This is a hands-on practical crash course for learning how to use SUMO to simulate traffic in a urban environment.

Previous Task - Download and install SUMO for your operational system

This tutorial assumes you already have sumo installed in your machine. If for some reason this is not the case, please download SUMO and install SUMO according to the following instructions.

Task 1 - Download the Instructional Material

Download the following instructional material (use the user and password given by your instructor.):

• Ricardo R. Gudwin - Urban Traffic Simulation with SUMO - A Roadmap for the Beginners.  Technical Report - DCA-FEEC-UNICAMP
• Zipped file with additional instructional materials

Task 2 - Running an Example Simulation

Unzip the instructional materials file and go to the sumoExamples/simpleT directory in a shell.

If you are using Linux or MacOS, execute the simpleT.sh bash script. If you are in Windows, run:

sumo-gui -c simpleT.sumocfg

in a command shell. You should see the following screen appearing, if everything went right.

Press <CTRL-G> to swith off Game Mode. The windows should change to the following one, showing many more options:

From this windows, you might gain more options for controlling the simulation. You can stop the simulation by pressing the red button, and after that you can start again or proceed the simulation step by step. Try to find the buttons to command these options. Stop the simulation and come back to the shell.

Examine the many files in the simpleT directory and try to identify the role of each one:

-rw-rw-r-- 1 rgudwin rgudwin    526 ago 29  2016 simpleT.gui.xml
-rw------- 1 rgudwin rgudwin  13794 nov 22 19:09 simpleT.net.xml
-rw-r--r-- 1 rgudwin rgudwin 310096 nov 22 20:10 simpleT.out.xml
-rw-rw-r-- 1 rgudwin rgudwin 349878 fev 13  2014 simpleT.rou.xml
-rwxrwxrwx 1 rgudwin rgudwin     41 ago 29  2016 simpleT.sh
-rw-rw-r-- 1 rgudwin rgudwin    697 ago 29  2016 simpleT.sumocfg

Take a look on the contents of each file, just to see how they encode information. Particularly, take a look of simpleT.sumocfg, which is the configuration file for the simulation. Observe how the other files are referenced in this file. Try to guess the importance of each parameter in the configuration file. After that, take a look on the simpleT.out.xml file. This file holds the results of the simulation. It will be generated after a simulation is concluded or stopped, and will be bigger depending on the amount of simulation time you allowed it to run. At the beginning of this file, there is copy of the simpleT.sumocfg file, just to alert on what conditions the results where obtained. After that, there comes a sequence of lines with a series of statistics, which where collected during the simulation. You might try to guess the meaning of each of them. Probably you will complain to have to get this information from an XML file. You might have a better view transforming this file into a CSV file and opening it into a spreadsheet software, like Excel or Libreoffice Calc. In order to do that, first find where is the tools directory, with the SUMO tools, in your file system. It might be something like /usr/lib/sumo/tools/ if you are in Linux. The tools directory looks like this:

drwxr-xr-x 26 root root  4096 nov 22 18:42 .
drwxr-xr-x  4 root root  4096 out 11 18:54 ..
drwxr-xr-x  2 root root  4096 nov 22 18:42 assign
drwxr-xr-x  2 root root  4096 nov 22 18:42 build
drwxr-xr-x  9 root root  4096 out 11 18:54 contributed
-rwxr-xr-x  1 root root  9263 nov 22 18:28 createVehTypeDistribution.py
drwxr-xr-x  2 root root  4096 nov 22 18:42 detector
drwxr-xr-x  2 root root  4096 nov 22 18:42 district
-rwxr-xr-x  1 root root  2915 nov 22 18:28 districts2poly.py
-rwxr-xr-x  1 root root  9375 nov 22 18:28 edgesInDistricts.py
drwxr-xr-x  2 root root  4096 nov 22 18:42 emissions
-rwxr-xr-x  1 root root  9000 nov 22 18:28 extractTest.py
drwxr-xr-x 12 root root  4096 nov 22 18:42 game
-rwxr-xr-x  1 root root  4668 nov 22 18:28 generateBidiDistricts.py
drwxr-xr-x  6 root root  4096 nov 22 18:42 import
-rwxr-xr-x  1 root root  7449 nov 22 18:28 launcher.py
drwxr-xr-x  2 root root  4096 nov 22 18:42 lib
drwxr-xr-x  2 root root  4096 nov 22 18:42 net
-rwxr-xr-x  1 root root  5435 nov 22 18:28 osmBuild.py
-rwxr-xr-x  1 root root  5141 nov 22 18:28 osmGet.py
-rwxr-xr-x  1 root root 15287 nov 22 18:28 osmWebWizard.py
drwxr-xr-x  2 root root  4096 nov 22 18:42 output
-rwxr-xr-x  1 root root  4344 nov 22 18:28 pedestrianFlow.py
drwxr-xr-x  7 root root  4096 out 11 18:54 projects
-rwxr-xr-x  1 root root  6087 nov 22 18:28 ptlines2flows.py
drwxr-xr-x  2 root root  4096 nov 22 18:42 purgatory
-rwxr-xr-x  1 root root 20731 nov 22 18:28 randomTrips.py
drwxr-xr-x  2 root root  4096 nov 22 18:42 route
-rwxr-xr-x  1 root root  2178 nov 22 18:28 route2sel.py
-rwxr-xr-x  1 root root  4595 nov 22 18:28 route2trips.py
drwxr-xr-x  2 root root  4096 nov 22 18:42 shapes
-rwxr-xr-x  1 root root  3914 nov 22 18:28 showDepartsAndArrivalsPerEdge.py
drwxr-xr-x  2 root root  4096 nov 22 18:42 simpla
drwxr-xr-x 10 root root  4096 nov 22 18:42 sumolib
drwxr-xr-x  2 root root  4096 nov 22 18:42 tls
-rwxr-xr-x  1 root root 13235 nov 22 18:28 tlsCoordinator.py
-rwxr-xr-x  1 root root 16389 nov 22 18:28 tlsCycleAdaptation.py
-rwxr-xr-x  1 root root 11847 nov 22 18:28 traceExporter.py
drwxr-xr-x  3 root root  4096 nov 22 18:42 traci
drwxr-xr-x  2 root root  4096 nov 22 18:42 trigger
drwxr-xr-x  2 root root  4096 nov 22 18:42 turn-defs
drwxr-xr-x  2 root root  4096 nov 22 18:42 visualization
drwxr-xr-x  3 root root  4096 nov 22 18:42 webWizard
drwxr-xr-x  2 root root  4096 nov 22 18:42 xml
In this case, inside the xml directory, there is a script in python called xml2csv.py, which transforms xml files into csv files. In MacOS, there is a command sumo-xml2csv, which is just a link to this python script. If you find the script, apply it to the simpleT.out.xml file and try to open the simpleT.out.csv which is generated by the script. You might see something like:

You might turn this information into a graphic, using some desirable statistics, like e.g the meanWaitingTime. Other statistics might be generated, if properly configured in the configuration file.

Task 3 - Editing a Topology File

In the next task, let's take a look on the simpleT.net.xml topology file. Let's open it with netedit. In a command shell, call netedit simpleT.net.xml. The result will be something like this:

Using netedit, you can change many features in the topology. In our case, let's change the phases of the traffic lights. If you payed attention during the simulation, you might have noticed that cars coming from the right sometimes turn left in the junction while the horizontal traffic is flowing. This might appear odd for some people. Let's understand what is happening.

First of all, change the editor to Traffic Light mode. You can do this selecting: Edit -> Traffic Light mode. You will see that the window slightly changes, and the traffic lights are shown:

Clicking now on the traffic lights, and zoom in, and it will show the phase map:

Take a look on the strange dark green conversion from the flow coming from the right to left. This is what is called a "Green-minor" in SUMO convention. In some countries, it is allowd to cross a flow like this, if there is no traffic coming from the opposite direction. In other countries this is forbidden to do that. Observe the "Phases" box in the left. This shows an encoded version of all the phases in this traffic light, and the times of each phase. Let's change this "Green-minor" to a "Red" situation, to forbid this kind of conversion. Click on the right mouse button and choose "Red" instead of "Green-minor". Check all the phases, if there is another situation like that and correct them. Also, change the time of phase 3 to 10 seconds, because now cars will not be allowed to make this conversion in phase 1, and they need more time for doing that in phase 3. Before saving, pay attention of a "Modifications" control, which is hidden, and where you needs to press "Save", before saving the whole network. Otherwise the system will not save your modification (this is tricky ... after that close the application and open it again to check if your change was saved). 

Save the network file and restart the simulation, paying attention if the cars are following the new traffic lights rules.

Task 4 - Importing a Topology from OpenStreetMaps

Now let's propose a small challenge ... using the information on the Roadmap for the Beginners, session 3.2.4, let's try to import the topology of a true town, using OpenStreetMaps.

Choose a town where there is a chance that traffic lights information is available, and select a small portion of it in OpenStreetMaps, and follow the instructions to import it into SUMO.

After doing this, open the chosenTown.net.xml generated file using netedit and check if the traffic light information is available.

Task 5 - Creating a New Traffic Pattern

Now, let's create a new traffic pattern. First of all, locate the randomTrips.py script, so we are able to use it. We will use the randomTrips.py script to generate the traffic. Change <heaviness> to a number between 0.1 and 1.0 for changing the heaviness of the traffic (0.1 means a heavier traffic, 1.0 means a lighter traffic).

randomTrips.py -n simpleT.net.xml -e 50 -L -p <heaviness> -s 1000 --fringe-factor 10 -r simpleT.rou.xml

Observe this is not the only way of generating this traffic pattern. You might use first randomTrips.py to generate a trip file and then use duarouter to generate the route file. This might be necessary if additional parameters are desired while calling duarouter to generate the routes. Check the following page for additional information on how using randomTrips.py  to create traffic. Using the script, generate random traffic with different traffic loads and run their simulations. Discover the meaning of the used keys on the script.