This document describes the capabilities and basic usage of the software SUMOPy. SUMOPy is intended to expand the user-base of the traffic micro-simulator SUMO by providing a user-friendly, yet flexible simulation suite. There is an extended and better printable version of this page including demand modeling and pictures at <SUMO_HOME>/tools/contributed/sumopy/sumopy_userman_v01_contrib.pdf. Further slightly outdated publications related to SUMOPy can be found at the University of Bologna and in the proceedings of the SUMO2013.
A further scope of SUMOPy is to manage the huge amount of data necessary to run complex multi-modal simulations. This includes different demand generation models as well as a large range of modes, such as road transport, public transport, and bicycles. In the future also modes like self-driving cars and Personal Rapid Transit (PRT) will be supported.
SUMOPy consists of a GUI interface, network editor as well as a simple to use scripting language which facilitates the use of SUMO.
- 1 Introduction
- 2 Installation
- 3 The graphical user interface
- 3.1 Getting started!
- 3.2 Launching SUMOPy
- 3.3 Importing and Editing networks
- 3.4 Demand modeling
- 3.5 Simulation processes
SUMO rapidly developed into a flexible and powerful open-source micro-simulator for multi-modal urban traffic networks . The features and the number of tools provided are constantly increasing, making simulations ever more realistic. However, the different functionalities consist at the present state of a large number of binaries and scripts that act upon a large number of files, containing information on the network, the vehicles, districts, trips routes, configurations, and many other parameters. Scripts (mostly written in Python), binaries and data files exist in a dispersed manner. In practice, a master script is necessary to hold all processes and data together in order run a simulation of a specific scenario in a controlled way. This approach is extremely flexible, but it can become very time consuming and error prone to find the various tools, combine their input and output and generate the various configuration files. Furthermore, it reduces the user-base of SUMO to those familiar with scripting and command line interfaces. Instead, SUMO has the potential to become a multi-disciplinary simulation platform if it becomes more accessible to disciplines and competences.Scripts (mostly written in Python), binaries and data files exist in a dispersed manner.
This problem has been recognized and different graphical user interfaces have been developed. The traffic modeller (also named traffic generator) is a tool written in Java which helps to manage files, to configure simulations and to evaluate and visualize results.
SUMOPy is written entirely in the object-oriented script language Python, it uses wxWindows with PyOPENGL as GUI interface and NumPy for fast numerical array-type calculations. It is similar to the traffic generator in that it simplifies the use of SUMO through a GUI. But SUMOPy is more than just a GUI, it is a suite that allows to access SUMO tools and binaries in a simple unified fashion. The distinguishing features are:
- SUMOPy has Python instances that can make direct use of tools already available as Python code.
- SUMOPy has a Python command line interface that allows direct and interactive manipulation of SUMOPy instances.
- SUMOPy provides a library that greatly simplifies the scripting.
SUMOPy is a directory with python scripts. It is sufficient to unzip the latest version and copy it in a directory of your choice. Since SUMO-0.28, SUMOPy is inside the SUMO distribution and located in
However, SUMOPy makes extensive use of Python packages which need to be installed before. The required packages to be installed are:
- Python 2.7
- numpy-1.10 or newer
- wxPython2.8 or wxPython2.9 (wxPython3.x is currently not properly working with PyOpenGL-3.0.x)
The following packages are optional:
- matplotlib-1.4 or newer, for high quality graphical output in different file formats.
- PIL-1.1.7 or newer and basemap-1.0 (or pyproj) for downloading backround maps from mapservers.
The exact choice of package-versions and installation methods depend on the operating system. Below we give short recommendations regarding the choice of packages for different operating systems. In general, the 32-bit version is preferred as there are more pre-compiled packages available, but this may change over time.
For Windows, as required packages the following are recommended:
python-2.7.12.msi (32-bit or x86 preferred) numpy-1.10.0-win32-superpack-python2.7.exe wxPython2.8-win32-unicode-220.127.116.11-py27.exe PyOpenGL-3.0.2.win32.exe
Optionally, install these:
matplotlib-1.4.3-cp27-none-win32.whl basemap-1.0.8-cp27-none-win32.whl PIL-1.1.7.win32-py2.7.exe
Python 2.7 comes with most Linux operating systems. All required additional packages are available in repositories:
python-numpy python-wxgtk2.8 python-opengl python-imaging python-matplotlib python-mpltoolkits.basemap
However, often Python 3.x is installed along the older version and may be the default Python interpreter. So make sure you run the sumopy scripts with Python 2.7
Another issue may be
python-wxgtk2.8 in repositories of more recent distributions, as for example Ubuntu-16.04. In this case, do the following safe operation to install
echo "deb http://archive.ubuntu.com/ubuntu wily main universe"| sudo tee /etc/apt/sources.list.d/wily-copies.list sudo apt install python-wxgtk2.8 sudo rm /etc/apt/sources.list.d/wily-copies.list sudo apt update
The graphical user interface
Start the script
sumopy_gui.py by double-clicking on it in your browser. If this fails, use a command-line application, change directory to
and run sumopy with
If all required packages are installed correctly, you should see the main window as shown here, but initially with an empty network. The object browser shows initially the main object of SUMOPy: the scenario, which contains all other information.
Opening/creating a scenario
There is a test scenario in the SUMOPy distribution which is located in
The quickest way to obtain results from a simulation is to import already existing
xml-files. In case the following SUMO network, poly and route files
demo.net.xml demo.poly.xml demo.rou.xml
are located in directory
then a new scenario can be created by importing these files into SUMOPy at ones: from the main menu, choose
Scenario>Create from xml... and insert the scenario Shortname, and Workdir in the form as shown here.
Description are free text fields. After pressing the
Run button, network, buildings and routes will be imported. In case the trip file
demo.trip.xml exists, it will also be imported.
In the same way it is possible to crate an empty scenario under menu
Browsing the scenario
The object browser allows to navigate through all information of a scenario. To a certain extend, it is possible to modify data. The most important information are:
- The network with edges, nodes, traffic light systems etc.
- The landuse, containing also the building information from the .poly| file as well as background maps (see later how to import them).
- The demand holds information on available vehicles types, trips and routes.
The network can be examined with the network editor. The initial editing tool allows to click on the different network elements and retrieve the respective information in the object browser.
With the zoom-buttons (+,-) located below the network editor, different zoom levels can be obtained The 1:1 button zooms the network to fit approximately the boundaries of the window. Next to the zoom button is a button which pops up a menu when pressed. From this menu, the network elements to be drawn can be selected or un-selected.
The following mouse-key combination allow to navigate the network:
|Zoom in/Out||Hold down |
|Panning||Hold down |
Simulating the scenario
From the main menu select:
Simulation>Sumo>export routes and simulate...
With this process, the current trips and routes in
demand.trips will be automatically exported to a SUMO
.rou file. Choose the desired simulation settings from the SUMO pop-up dialog, as shown in Fig. here.
The simulation parameters are self-explaining, just hover with the mouse over the parameter name. The default parameters are typically suitable to run a first simulation. Select one of the output options in order to obtain specific simulation results. Regarding outputs, the
Output Sampling Time for the different outputs may be of interest. If you observe in the simulations that vehicles get blocked at junctions for no obvious reason, then it is possible to resolve conflicts by setting the
Teleport to a positive time (i.e. 10s).
After pressing the
run button, the SUMO-GUI interface pops up, ready for simulation, as shown Fig. here.
Adjust delay time and press the Start button. At the end of the simulation, confirm OK and close the SUMO-GUI window. Simulation results are now imported into SUMOPy and are ready to be examined, visualized and exported in various formats.
The results can be viewed in table format and graphically, see here.
In the object browse, the results per trip and the results per edge can be viewed. Both, trip and edge oriented result-table can be exported in CSV format, see the
Results are not saved when saving the scenario. Instead the results must be saved separately using
Simulation>Results>Save as ...
At any time, results can be reopened with the scenario with which they have been produced, using:
In case the
Matplotlib package is installed you can generate plots in various formats, choosing menu
Simulation>Results>Plot with matplotlib. The pop-up dialog helps to configure the graphical details of the matplotlib plot.
From the matplotlib figure window, the graphical results can be exported in different file formats (PNG, PDF, JPEG, etc.),
an example PNG file is shown below.
As explained above, networks can be created from SUMO XML files, or a binary file can be loaded. Both operations can be performed from the command line.
Loading a binary scenario at start
A previously saved, binary scenario with filename scenario.obj| can be loaded into SUMOPy at start using the commandline
python sumopy-gui.py workdir/scenario.obj|
Importing SUMO XML files at start
An initial import of existing SUMO XML files with rootname scenario| and located in directory workdir| can be accomplished with
python sumopy-gui.py scenario workdir|
Importing and Editing networks
- if needed, the network should be modified before moving on to demand modeling (see Sec.[secdemand]).
Importing nets and buldings
Networks can be import from a SUMO net.xml file with
network>import>from sumo net.xml ...
Networks can be converted and imported from a previously downloaded OSM file, calling a wizard with:
network>import>from osm.xml ...
Different types of buildings, parks, car parking, leisure areas, etc (in SUMOPy called called “facilities”) are a property of the landuse object and can be extracted and imported from an OSM file with menu item
landuse>facilities>import from osm...
Sometimes special characters in the XML file are offending the python XML parser, leading to errors during import. If this occurs, simply “clean” the respective OSM file with
landuse>facilities>clean osm file...
prior to importing it.
Editing with SUMO’s Netedit
The recommended way to edit the network is via netedit|, which is provided with SUMO from version 0.25. SUMO’s netedit| can be called by choosing the menu
Network>Edit with netedit
netedit| will be fired up with the network ready to be edited. The use of netedit| is documented here: http://sumo.dlr.de/wiki/NETEDIT. After editing, the network must be saved within netedit| be pressing
<CTRL>-s or with File>save|. Then netedit| can be closed and the modified network will be reimported into SUMOPy.
Editing with SUMO’s Netedit on background maps
There is a possibility to edit the network with netedit| on background maps. Currently these are Google Satellite maps. Before editing with background maps, the maps must be downloaded for the given network area. This is accomplished by a wizard which can be called selecting the menu item.
The wizard helps to download the squared tiles which cover the network area. The resolution can be defined by setting the tile width (and height) in meters. The tile size in pixel is maximum 1280 (using the Google Map server). The resolution is then tile size/tile width in pixel per meter.
it is highly recommended to press the Apply| Button prior to downloading the maps. This will calculate the number of tiles which are going to be downloaded. This is important to know, because Google maps prevent IPs from downloading too many maps of an area. Therefore do not exceed about 300 tiles! Note further that, dependent on the performance of your computer, netedit| may run into problems to handle too large map areas.
After the maps are downloaded, netedit| can be called with
Network>Edit with netedit on map
in order to edit the SUMO network on a map.
Editing with SUMOPy Networkeditor
The SUMOPy internal net-editor provides currently some limited capability to edit the network
- The geometry of edges and buildings can be manipulated: Activate the Move| tool to move or the Stretch| to change vertexes.
- With the menu
Network>Clean nodesall edges entering a node are “cut back” to a certain radius. This measure may facilitate the verification of connections between lanes at junctions.
In the framework of SUMO, demand generation means essentially the generation of traffic participants (persons and/or different types of vehicles ) and the generation of a route for each traffic participant. It is recommeded to start with demand generation only after the network has been edited. In any case it is good practice to save a scenario with the network only (without demand info).
All available vehicle types can be browsed and modified under:
Note that each vehicle type belongs to a vehicle class, also called modes.
The different demand generation methods, as described below, will generate trips and routes, which can be browsed in
In fact, the different demand generation methods could also be used in combination.
Zone to zone demand flows
We first explain the general concept of Zone to zone demand generation before we describe how to procede with SUMOPy.
- Zone definition: Definition of Zones, in SUMO also called “Traffic Assignment Zones” (TAZ). A TAZ defines the area where participants depart (zone of origin) or arrive (zone of destination). A TAZ does typically contain several network edges.
- Zone-to-Zone flow definition: Definition the number of trips between each zone of origin and a zone of destination (= OD-flow). This structure is widely known as the Origin-to Destination matrix OD Matrix. OD-flows are defined.
- for different time intervals of the day.
- for different transport mode.
- Trip generation: Each OD-flow is disaggregated into a discrete number of individual trips, departing at different edges (and edge positions) within the zone of origin, and at different time instances within the specified time interval; and arriving at different edges (and edge positions) within the zone of destination.
- Routing: A route is computed for each individual trip, connecting the edge within the zone of origin, with the edge within the zone of destination.
These steps can be performed with SUMOPy as follows.
From the SUMOPy network manipulation tools, select the
Add zone tool.
After giving the zone a name  a polygon can be drawn on the network with a series of
<Button-Left> - clicks. Complete the zone with a final
<Double-Button-Left> - click. A
<Double-Button-Right> - click will aboard the current zone drawing. Currently, zones must be convex, otherwise edge detection problems occur.
Only edges which are located entirely inside a zone are considered part of a zone. Only edges inside a zone are considered for departure or arrival of vehicles in the respective zone. After creating the zones you can identify all edges in each zone by selecting the menu item
Landuse>Zones>Identify zone edges
It is possible to see all zone edges and and change zone names by using the information tool and by clicking on the green zone border. Zones are accessible under
scenario.demand.zones. Zones can also be deleted with the
Delete tool of the network editor.
Zone-to-Zone flows can be added by selecting the menu item
Demand>Zone-to-zone demand>Add zone-to-zone flows
An “Add OD flow wizard” will pop up as shown in Fig. below.
With this wizard, specify the time interval (in entire seconds) and the transport mode. On the menu of the wizard select
Edit>Add OD-flow to table.
Then a new row will appear in the table. Enter the zones of origin and destination and the respective number of trips between them.
Instead of entering the OD flows manually, the wizard offers also the possible to import OD-flows from a CSV file. Select from the wizard menu:
File>Import CSV ...
and choose a CSV file from the file-dialog window. The CSV file must have the following format:
<zone name origin 1>, <zone name destination 1>,<trip number 1> <zone name origin 2>, <zone name destination 2>,<trip number 2> ...
Once the OD flows are all entered, press
Save flows. The scale factor can be used to multiply all entered trips with a constant (default is 1) wwhile saving. The demand flows are now saved to SUMOPy and can be browsed and modified under
Generate trips from OD flows by selecting menu item
Demand>Zone-to-zone demand>Generate trips from flows
The generated trips can be browsed and modified under
Perform a shortest path routing for each trip by selecting
Demand>Trips and router>Trips to routes with shortest path
The generated route can be browsed under
With this method, SUMO’s duarouter is used to perform the routing. Note that each trip is now linked to a route (see ID route column in trips). If there is no route then the edge in the zone of origin is probably not connected to the edge in the zone of destination . The router does not route pedestrians, but this is not necessary as their exact route will be determined during simulation.
The scenario is now ready to be simulated by selecting
Simulation>Sumo>export routes and simulate...
Proceed as described in Sec. #Simulating the scenario.
A test file for OD demand is located in
Trip generation with turnflows allows to model traffic flows in a precise way, for simple, possibly loop-free networks with few internal traffic generation. The general idea is to generate trips and routes for individual vehicles based on road traffic counts. These traffic counts can be performed at junctions. Ideally, the traffic counts should be performed simultaneously at all relevant junctions. However, some edge flows can be derived from other edge flows considering flow preservation lows at nodes.
Basically two types of flows are needed in order to reconstruct the routes in a predefined study area:
- The generating flows FG[a] on all edges a that enter the study area. 
- The turn flows FT[a1,a2] for all flows between links a1 and a2 at nodes with more than one exiting edge.
The choice of traffic flows that need to be counted is illustrated by an example network:
Neglecting all traffic generated within the study area, the following flows need to be counted:
- The generating flows FG, FG are entering the network.
- The turn flows F[8,9], F[8,2] at node 6 and F[12,4], F[12,7] at node 3. All other nodes have only one exiting edge.
Once the necessary flows are counted for all considered transport modes and time intervals, the trips and routes of all vehicles can be generated with a special router, called JTRouter.
With SUMOPY the route generation with SUMOPY works as follows: First import flows and turnflows from a CSV file by selecting the menu item
The import turnflows dialog will pop up, as shown below.
This dialog is similar to the OD-flow wizard explained in Sec. #Zone to zone demand flows and allows to import traffic counts, and associate them with a time interval and a transport mode.
Turnflow File to be imported contains the traffic counts of both flow types, generating flows and turnflows. The turnflow file has the following format:
<ID1>, <count 1>, <ID11>, <count 11>, <ID12>, <count 12>, ... <ID2>, <count 2>, <ID21>, <count 21>, <ID22>, <count 22>, ... ...
This notation has the following meaning:
<IDa> means the SUMO edge ID of edge a, where edge a is the edge entering a node.
<IDab> means the SUMO edge ID of edge ab, where edge ab is the edge outgoing from the node which edge a enters.
<count a> means the number of vehicles leaving edge a, in case the edge is generating flows, otherwise this count is zero.
<count ab> means the number of vehicles from edge a turning into edge b.
All counts in this file refer to the mode and time interval specified in the dialog box.
The turnflow file for the example network shown above, could look like this:
3, 1000 12, 800, 4, 200, 7, 600 8, 0, 9, 800, 2, 400
In this case, the generating flows FG=1000, F=800 and the turn flows FT[8,9] = 800, FT[8,2] = 400 and FT[12,4] = 200, FT[12,7] = 500 for a specific mode and time interval.
Hint: In order to quickly compile the turnflow file, open a text editor and the SUMOPy window next to each other. In the SUMOPy network editor, un-select lanes, connections and crossings by clicking on the button next to the zoom buttons below the network canvas. Then select the info tool (if not already active) and click on the edges you consider for the turnflow file. The respective edge will be highlighted and you can see all edge attributes in the object browser, as shown below:
From there, copy the SOMO edge ID and paste it into your turnflow text file.
Optionally define destination zones: Within the turnflow demand model destination zones define edges where vehicle routes end. This may be necessary in order to prevent vehicles of making a loop on the network outside the study area and reentering the study area. Destination zones for turnflows are created in the same way as Traffic assignment Zones in section #Zone to zone demand flows.
Generate directly route from flows and turn-flows information by selecting menu item
Demand>Turnflows>Turnflows to routes
This process is using SUMO’s JTROUTER and will generate both trips and routes. The scenario is now ready to be simulated by selecting
Simulation>Sumo>export routes and simulate...
Proceed as described in Sec. #Simulating the scenario.
A test file for turnflows is located in
This section addresses some particular simulation issues.
Sublanes is a new feature in SUMO since 2015. The simulation with Sublanes render traffic flows on roads more realistic. With sublanes, several vehicles can share side-by-side the same lane given there is enough room. For example a car can pass a bicycle on the same lane if the total lane width is larger than the bike width plus car width.
For sublane simulation with SUMOPy, simply browse to
and set the lanechange model model to SL2015. Note that SUMOPy applies the same lanechange model to all vehicle types. Then run the simulation with
Simulation>Sumo>export routes and simulate...
Note that on the SUMO dialog, the sublane width is now positive (1m by default). This value (which can be changed) determines how many sublanes can stay within one lane. For example a 3m wide lane can have 3 sublane of 1m but only 2 sublane of width 1.5m.
The lanechange behavior with sublanes can be tweaked for each vehicle type with the sublane parameters in
- In SUMOPy Maps are managed by the landuse object
- Of course in a traffic scenario we have usually more than one participant of each type
- zone names can added/modified later via browser
- there can be several reasons for this, usually the destination edge is in access-restricted areas, or there are one-way roads, impeding access. Actually this should not happen too often, as the disaggregation algorithm should verify accessibility
- In addition, traffic flows can also be generated on edges within the study area, but in practice it is difficult to measure those flows because one would need to spot and count only departing vehicles along the roads of the study area. However, for some particular edges with many departing vehicles this may be necessary to do.