SUMOR

sumor is a very early-stage package for the R Project for Stastical Computing developed to enable access to a small subset of the Simulation of Urban Mobility (SUMO) API.

The focus of the package is to simplify the usage, configuration, and execution of the variety of moving parts necessary to build a simulation with SUMO.

Installation

1. Make sure sumo is installed and you're aware of the location of the home path, i.e. sumo with nothing else should return something similar to:

SUMO Version 0.25.0
Copyright (C) 2001-2015 DLR and contributors; http://sumo.dlr.de
License GPLv3+: GNU GPL Version 3 or later http://gnu.org/licenses/gpl.html
Use --help to get the list of options.

2. Install the release version of devtools from CRAN with install.packages("devtools")
3. Install sumor with:

devtools::install_github("https://github.com/wsu-wacs/sumor")

4. Configure the variables needed from Step (1):

## Load library, set SUMO home path 
suppressMessages({ library("sumor", quietly = T) })
Sys.setenv(SUMO_HOME="/opt/local/share/sumo")
  
## Create temporary directory to store all the intermediate data files (optional)
if (!dir.exists("./tmp")){ dir.create("./tmp") }
Sys.setenv(SUMO_TMP=paste0(getwd(),"/tmp/"))

Usage

SUMO is a microscopic, space-continuous road traffic simulation. SUMO simulations require-as-input and produce-as-output numerous varieties of XML or similar-format files on disk. The information within these files fundamentally control how SUMO simulations are configured. The sumor package contains several easy to use functions that allow configuring, running, monitoring, and fine-tuning SUMO simulations based on these files.

Getting started: Simulating traffic with OpenStreetMap

For simplicity, the package is entirely designed around the Reference Class design in R. To access the SUMO API, simply create a new reference object of type 'sumo':

  sumo_net <- sumo$new()

All of the functionality related to the given SUMO object is accessed through the '$' operator.

The next step is to specify a source SUMO network for simulation. Although its possible to build a network from scratch with SUMO, for larger projects working with complex geographical areas, importing map data from an external source is much easier. You can download OpenStreetMap (OSM) data for use with SUMO using the getOSM method by passing an sp bounding box. For example, suppose you want to make a new SUMO traffic simulation around Columbus, OH. A bounding box can be selected easily with klokantech.com and used with the sumor package like so:

## (Selected from http://boundingbox.klokantech.com)
columbus_bbox <- sp::bbox(matrix(c(-83.024733,39.995205,-83.006923,40.005429), ncol=2, byrow = T)) 
sumo_net$getOSM(columbus_bbox, file = "columbus.osm")

This will download the OSM data into the directory pre-defined by SUMO_TMP, or a temporary directory if the path variable isn't defined. The next step is to convert the OSM data into a usable SUMO road network suitable for simulation using NETCONVERT

sumo_net$netconvert(urban = T, pedestrian = T, polygons = T)

The parameters to netconvert control the use of the default conversion typemap.

There are hundreds of parameters that to tweak that change how traffic is generated. The following generates an hour of random traffic, where at most n = 1 car arrives with probability p = 0.5 every second.

## Generate trips and routes (s seconds * m minutes * h hours)
sumo_net$randomTrips(start = 0, end = 60 * 60 * 1, n = 1, p = 2)

To view the simulation itself through the SUMO-GUI, simply call the viewSimulation method:

sumo_net$viewSimulation() 

You can also extract information from the simulation between any given set of time points. For example, retrieving the vehicle spatial coordinates for the first half and hour of the simulation can be done throught the 'getVehiclePositions' member function:

vehicle_wgs84 <- sumo_net$getVehiclePositions(start = 0, end = lubridate::dhours(0.5))

Further information

The entire sumor package in encapsulated in reference class methods implemented as part of the sumo class definition, sumo.R. To get an index of all of the methods implemented by the package, use:

package?sumor

Prequisite knowledge

Knowledge of how to manually create a simulation with SUMO is useful, but not required.

sumor imports the de-facto standard package for handling spatial data, sp, and has many often returns objects within the sp family of classes.

Contributing

Pull requests or functionality requests are more than welcome. Adding functionality is as simple as adding a new method to the reference class, along with some simple documentation, e.g.

#' @title My method 
#' @name my_method
#' @description Does something...
sumo$methods(my_method= function(...)
	...
})