Contributed/SUMOPy

generated on 2016-11-01 01:15:31.609057 from the wiki page for Contributed/SUMOPy for SUMO 0.28.0

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.

Introduction

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.

Installation

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 SUMOHOME/tools/contributed.

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)
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.

Windows

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-2.8.12.1-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

Linux

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 python-wxgtk2.8:

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

Getting started!

Running SUMOPy

Start the script sumopy_gui.py by double-clicking on it in your browser. If this fails, use the command-line accessory change directory to

SUMOHOME/tools/contributed/sumopy

and run sumopy with

python sumopy_gui.py

If all required packages are installed correctly, you should see the main window, 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

SUMOHOME/tools/contributed/sumopy/testscenario

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

SUMOHOME/tools/contributed/sumopy/testscenario

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.

The options Name| and 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 Scenario>New....

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.

Navigating the Network

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:

Action	Key-Mouse
Zoom in/Out	Hold down `<CTRL>` + `<Wheel>`
Panning	Hold down `<CTRL>` + `<SHIFT>` + `<Button-Left>`

Running a simulation

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.

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.

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.

Viewing results

The results can be viewed in table format and graphically.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 Simulation>Results| menu.

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:

Simulation>Results>Open ...

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 plot.

Launching SUMOPy

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 commend 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.[sec_demand]).

Importing nets and facilities

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 ...

Note: the information on buildings (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. If this occurs, simply “clean” the 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^[1].

landuse>maps>download...

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 Neteditor

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 nodes all edges entering a node are “cut back” to a certain radius. This measure may facilitate the verification of connections between lanes at junctions.

Simulation processes

This section addresses some particular simulation issues.

Simulating Sublanes

With sublanes is new feature of SUMO since 2015. Sublanes renders 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

scenario.demand.vtypes

and set the lanechange model model to SL2015|^[2]. Then run the simulation with