sumolib is a set of python modules for working with sumo networks, simulation output and other simulation artifacts. For a detailed list of available functions see the pydoc generated documentation. You can browse the code here.

importing sumolib in a script#

To use the library, the <SUMO_HOME>/tools directory must be on the python load path. This is typically done with a stanza like this:

 import os, sys
 if 'SUMO_HOME' in os.environ:
     tools = os.path.join(os.environ['SUMO_HOME'], 'tools')
     sys.exit("please declare environment variable 'SUMO_HOME'")

usage examples#

import a network and retrieve nodes and edges#

 # import the library
 import sumolib
 # parse the net
 net ='')
 # retrieve the coordinate of a node based on its ID
 print net.getNode('myNodeID').getCoord()
 # retrieve the successor node ID of an edge
 nextNodeID = net.getEdge('myEdgeID').getToNode().getID()

compute the average and median edge speed in a plain xml edge file#

 # compute the average length
 speedSum = 0.0
 edgeCount = 0
 for edge in sumolib.output.parse('myNet.edg.xml', ['edge']):
     speedSum += float(edge.speed)
     edgeCount += 1
 avgSpeed = speedSum / edgeCount
 # compute the median length using the [Statistics]( module
 edgeStats = sumolib.miscutils.Statistics("edge speeds")
 for edge in sumolib.output.parse('myNet.edg.xml', ['edge']):
 avgSpeed = edgeStats.median()


Attribute speed is optional in user-generated .edg.xml files but will always be included if that file was written by NETCONVERT or NETEDIT.

locate nearby edges based on the geo-coordinate#

 # (requires module [pyproj]( to be installed)
 # for larger networks [rtree]( is also strongly recommended
 radius = 0.1
 x, y = net.convertLonLatXY(lon, lat)
 edges = net.getNeighboringEdges(x, y, radius)
 # pick the closest edge
 if len(edges) > 0:
   distancesAndEdges = sorted([(dist, edge) for edge, dist in edges])
   dist, closestEdge = distancesAndEdges[0]

parse all edges in a route file#

 for route in sumolib.output.parse_fast("myRoutes.rou.xml", 'route', ['edges']):
     edge_ids = route.edges.split()
     # do something with the vector of edge ids

coordinate transformations#

 net ='')
 # network coordinates (lower left network corner is at x=0, y=0)
 x, y = net.convertLonLat2XY(lon, lat)
 lon, lat = net.convertXY2LonLat(x, y)
 # raw UTM coordinates
 x, y = net.convertLonLat2XY(lon, lat, True)
 lon, lat = net.convertXY2LonLat(x, y, True)
 # lane/offset coordinates
 x,y = sumolib.geomhelper.positionAtShapeOffset(net.getLane(laneID).getShape(), lanePos)
 lane = net.getNeighboringLanes .... (see above)
 lanePos, dist = sumolib.geomhelper.polygonOffsetAndDistanceToPoint((x,y), lane.getShape())

see also TraCI/Interfacing_TraCI_from_Python#coordinate_transformations

Further Examples#

The files in the test subfolders of <SUMO_HOME>/tests/tools/sumolib provide additional examplse for sumolib use.