# Disim Highway Simulator/Tutorial
## Scenario

In this tutorial, we are going to analyze the effect of different ramp-metering schemes on the highway traffic. We are going to concentrate on the interstate I-210 W highway between the Myrtle off-ramp and the last of Balwin's on-ramps. This section of highway is visible on Google Maps.
In particular, we are going to study the ALINEA algorithm and a combination of ALINEA with a queue constraint proportional controller.
The rest of this section is separated into the problem statement, the construction of the map, the car controller, the infrastructure controller (here the ramp-metering controller) and the visualization of the results.

## Problem Statement

We will focus our study on a specific highway segment (namely the interstate I-210W between Myrtle and Baldwin). A highway segment is composed of N$_r$ on-ramps labeled R$_1$,...,R$_{Nr}$ and Ne exit off-ramps labeled E$_1$,...,E$_{Ne}$. Each on-ramp R$_i$ has a ramp meter allowing a maximal rate of r$_i$(t) vehicles per hour to enter the mainline of the highway at time t. Vehicles can queue on the on-ramp, the number of vehicles waiting to enter the highway is denoted by q$_i$(t). To implement efficient ramp metering algorithms, loops detector are placed before the entry on the mainline. These loop detectors aggregate vehicle information and can measure the flow of vehicles on the mainline f$_i$(t), the density of vehicles k$_i$(t) and the average speed of those vehicles v$_i$(t). Each off-ramp E$_j$ is caraterized by a split ratio s$_j$(t) which is the ratio of the number of vehicles exiting the highway over the number of vehicles on the mainline before the exit. The figure on the right summarizes this problem statement.
Furthermore, throughout this tutorial, we have focused on the interstate I-210W between the Myrtle on-ramp until the last of Baldwin’s on-ramp. The map of this area is visible on Google Maps. This section is composed of 4 lanes (excluding a High Occupancy Vehicle (HOV) lane), 6 on- ramps and 4 off-ramps. The entry flow and speed of the vehicles on the mainline are calibrated using the Performance Measurement Systems (PeMS) data available freely on https://pems.eecs.berkeley.edu for the 6th of April 2011. To simplify our discussions, all on-ramps experience the same flow of vehicles and is equal to the PeMS flow at the Myrtle on-ramp on the 6th of April 2011. All simulation will take place between 6 a.m. and noon. This data is visible on the right.

## Map

Let us have at an excerpt of the actual map file. The complete map file can be found in the maps folder of the Disim distribution under the name I-210W.map.
As you can observe the syntax is pretty simple and is a sequence of keywords (starting with the dollar sign $) followed by arguments that define the keyword. The above excerpt has been well commented. Please have a look as it contains anything that you might ever need. In the next section, we will develop the driver model.

## Car Behavior

Disim is distributed with a standard driver model: the Intelligent Driver Model (IDM) of Helbing [1] combined with the Minimizing Overall Braking decelerations Induced by Lane changes (MOBIL) model of Treiber [2]. The IDM is a longitudinal model that set the acceleration depending only the leading vehicle and the MOBIL model looks at the 5 current neighbors (leading, leading on the left lane, trailing on the left, leading on the right and trailing on the right). The current implementation of Disim only allows the car controller to access information about the 6 direct neighbors if they are within a given radius of 100 meters. Please do not hesitate to drop me line on Sourceforge if you have other needs or feel free to modify the core source code (as it is hopefully well documented under Doxygen).
Let us dive into the code of the car controller. We have purposefully omitted part of the original file which you can find under the scripts/car folder in the Disim distribution (IDM_MOBIL.lua).
This script was made using LUA (http://www.lua.org/manual/5.1/manual.html): Lua is an extension programming language designed to support general procedural programming with data description facilities. It also offers good support for object-oriented programming, functional programming, and data-driven programming. Lua is intended to be used as a powerful, light-weight scripting language for any program that needs one. Lua is implemented as a library, written in clean C (that is, in the common subset of ANSI C and C++).
Users that are interested in testing their own controller should learn Lua and read the Disim API page available on this website. Additionally, if you do not wish to create your own controller, you can use the IDM_MOBIL controller as is (or modify the constants in the init function).
[1] D. Helbing, A. Hennecke, V. Shvetsov, M. Treiber, Micro- and macro- simulation of freeway traffic, Mathematical and Computer Modelling, 2002, Vol. 35, pp. 517–547. [2] M. Treiber, D. Helbing, Realistische Mikrosimulation von Strassenverkehr mit einem einfachen Modell, Symposium of Simulationstechnik ASIM, 2002, pp. 514–520.

## Infrastructure Control

The infrastructure controller (much like the car controller for cars) is in charge to modify and act on the environment in function of the current time of day and the measurements done by the sensors placed on the road. The following controller first reads PeMS data files and update the flows and speeds of vehicles entering the highway. Note that this piece of code is very general, as it first looks through all entries of the highway and tries to find corresponding PeMS data file with the corresponding name. Then for all entries, it automatically adjusts the flow of vehicles. Additionally this script also manages the rampmeters depending on the density sensors placed the on-ramps.
The actual file can be found in the Disim distribution under scripts/control. As you can see, you can control a fair amount of actuators in the highway and this allows you to implement very complex strategies starting with ALINEA up to coordination of rampmeters. Feel free to use and modify the above code for your research as long as you cite Disim in your work.

## Running the Simulation

At this point, all the piece are in place to start Disim, simply open a terminal and type:
Disim will start the simulation and open the graphical interface for you to see if everything runs smoothly. If you are happy, you can close disim and start gathering data with the following commands:
The command prompt will again appear when the simulation is finished. You can now explore the logs folder to see if the sensors you wanted to log are there.

## Gathering Data

Start up Octave/Matlab and go in the Disim scripts/matlab folder to start plotting your data. You should be able to generate plots like the ones on the right side.
They show the density versus the flow of vehicles at Huntington on the mainline. As we can observe without any control the density of vehicles is free to increase on the mainline and thus yields major slowdowns and create jams. With ALINEA, the diagram successfully stays in the free flow section and no jam is experienced, this comes at the cost of reaching up to 8 minutes of queuing time (as seen on Figure 13(c)). Upon the introduction of a 2-minutes queue constraint, slowdowns are experienced but jams are avoided as we stay mainly below 80 vehicles per kilometer (compared to 110 vehicles per kilometers without any control strategy). Figure 13(c) clearly shows that the maximal queuing time does not exceed 2 minutes. Finally the coordinated approach leads to similar results than the ALINEA control whilst staying within the queue constraint. It is clear that a trade-off between queuing time and travel time exists, but the introduction of our coordinated strategy not only improves the travel time by a factor two (see Figure 13(a)), but also solve the equity problem where all vehicles entering the highway experience the same delay.

## Conclusion

This concludes our tutorial. Please do enjoy Disim and contribute to its development. There are no others like Disim and we hope to have bootstrapped a piece a software valuable to traffic engineers. Thank you for downloading Disim!