Disim Highway Simulator/Introduction

Starting Disim

To start Disim, open a Terminal and type:

disim

Depending on your installation, you may have to navigate to the Disim folder and start it with:

./disim

If you have compiled Disim with graphical support, a window such as the one on the right should appear. If you didn't want graphical support, you can skip this section and go the command-line options.

Graphical Interface

The graphical interface enables you to navigate through the map using the mouse:

Left button: changes the orientation of the camera,
Right button: translates the camera horizontally,
Middle button (or both left and right buttons): zooms in-and-out of the map,
Wheel: zooms in-and-out of the map,
SHIFT + any button: makes the same action but faster.

It allows you to click on any element of the map using CTRL to obtain information about this element:

CTRL + Left button: selects and display information about the clicked element (this is currently under-supported).

There are several menus located at the top of the window:

File
- Open: opens a file selection window where one can choose which map to load into the simulator. The simulation will restart at time zero on the new map. The other options are left untouched.
- Reload: reopens the current map and restarts the simulation.
- Exit: quits the simulator.
Action
- Pause: stops the time. The duration of a time-step is reduced to zero but cars continue to act. This option is very useful to debug a car behavior as we will see in the tutorial section of this documentation.
- Fast: runs the simulation as fast as possible by setting the time-step duration to a fixed value (by default 64 ms).
- No display: does the same as fast, but stops the 3D display.
- Slower: instead of running in real-time, you may want to run at a lower rate. This options slows down time.
- Faster: same as slower but accelerates time instead.
- ~~Get info: this menu is currently not supported.~~
View
- Follow car: fixes the camera as to follow a vehicle running on the road network.
- Previous car: follows the previous car.
- Next car: follows the next car.
- Show grid: displays a decameteric grid on the map. Each cell of that grid is a 10 by 10 meters square.
- Show real world: displays a nice looking landscape.
- Show skybox: displays a background image.
- Draw shadows: shows the shadows of the vehicles.
Weather
Rain and fog effect in Disim
- Rain: changes the weather to rain. It effectively reduces the acceleration and sight capabilities of each vehicle.
- Fog: changes the weather to foggy. It effectively reduces the sight capabilities of each vehicle.
Controller
- Load script: allows one to choose a LUA script to control the behavior of each vehicle.
- Reload: reloads the LUA script. This is useful when one wants to change the script live as we will see in the tutorial section of this documentation.
- Unload: unloads the script and falls back on a dummy C/C++ controller.

Command-line Options

Disim offers many command-line options. All options that can be activated through the graphical interface have a command-line counterpart. Typing disim --help in a terminal displays all available options:

./disim --help
Disim 1.0a

Simulates a complete highway traffic.

Usage: Disim [OPTIONS]...

  -h, --help               Print help and exit
  -V, --version            Print version and exit
      --log[=STRING]       Log file  (default=`logs/log.txt')
      --record             Whether to record data
  -v, --verbose-level=INT  Verbose level  (default=`4')
  -m, --map=STRING         Map file  (default=`./maps/default.map')
  -d, --duration=INT       Duration of the experiment in seconds  (default=`0')
      --fast               Whether to start the simulation in fast mode  
      --pause              Whether to start the simulation in pause mode  
      --nogui              Whether to display the GUI  (default=`1')
      --density=INT        Initial density of cars at startup in veh/km (default=`0')
      --truck=DOUBLE       Proportion of trucks at all times  (default=`0.1')
      --weather=STRING     The weather conditions. Either nice, rain, fog or rain+fog
      --time-step=DOUBLE   The largest time-step in seconds  (default=`0.064')
      --lua=STRING         The LUA script to be executed as the car controller
      --luacontrol=STRING  The LUA script to be executed as the infrastructure controller
      --ncpu=INT           The number of cores on your computer  (default=`0')

log: specifies a log file where the simulator can record what is happening. What is recorded in this log file is depended on verbose-level chosen.
record: turns recording on. All the road sensors will start recording data and saving this data in the logs folder under the their name. We will see this in more details in the tutorial section.
verbose-level: specifies the verbosity of the simulator, the higher the more verbose.
map: specifies which map to load into the simulator.
duration: specifies in seconds the duration of the simulation. Disim automatically quits when the duration reaches the one specified. A duration of 0 seconds means that the simulation should never stop.
fast: turns on the no display option at startup.
pause: puts the simulation in pause at startup.
nogui: this is probably the most important option. It allows to run the simulation without the graphical interface, hence Disim doesn't need a display server to run and can run on a dedicated server.
density: specifies in vehicles per kilometer the initial density of cars present on the highway.
truck: specifies the proportion of trucks running on the highway.
weather: specifies the weather condition. It can either be "nice", "rain", "fog" or "rain+fog"
time-step: specifies in seconds the minimal time-step. The higher this value is, the faster the simulation becomes (in fast and nogui mode), but the lower it is, the more faithful the simulation becomes. By default it is 64 ms, but know that 500 ms yields fairly good results.
lua: specifies the LUA script to run to control the vehicles. See the section on scripting or the tutorial for more details.
luacontrol: specifies the LUA script to run to control the infrastructure.
ncpu: specifies the number of extra threads to spawn when simulating the vehicles. This number should roughly be equal to the number of cpu cores on the computer running Disim. This option effectively parallelizes the workload on the different processor available on the computer and can potentially make the simulation faster.

Here is an example of command that runs the simulator without the graphical interface during an hour on the road network described by the my_highway.map file and records the data from the sensors placed on the highway:

./disim --nogui --record --map="./maps/my_highway.map" --duration=3600

The next command will start Disim with the car behavior scripted in my_script.lua and set the proportion of trucks to 50%:

./disim --truck=0.5 --lua="./scripts/my_script.lua"

The next commands will display the effective running time of Disim using the ncpu and time-step options on a one-hour simulation.

time ./disim --lua="scripts/my_script.lua" --nogui --duration=3600 --time-step=0.064 --ncpu=0
real	9m49.858s

time ./disim --lua="scripts/my_script.lua" --nogui --duration=3600 --time-step=0.064 --ncpu=6
real	4m55.867s (Gain: 2x)

time ./disim --lua="scripts/my_script.lua" --nogui --duration=3600 --time-step=0.5 --ncpu=0
real	1m16.503s (Gain: 7.75x)

time ./disim --lua="scripts/my_script.lua" --nogui --duration=3600 --time-step=0.5 --ncpu=6
real	0m37.891s (Gain: 15.9x)

What is next?

The next section will explain how one can create its own highway network.