Disim Highway Simulator/Creating the highway network

Explained Syntax

Constructing maps for Disim is quite intuitive and easy. As an example you can look at the files maps/default.map and maps/loop.txt.

Here is how it works. The map file should start will the following preamble:

$NAME,The map name
$LANE_WIDTH,3.5

This signals the name of the map and displayed lane width that your lanes have. The default lane width if this line is not present is 3.5 meters. You can then declare your highway segments in the direction of the traffic flow. Each segment starts with a mandatory line:

$SEGMENT,straight,X

to indicate a straight segment of X meters, or

$SEGMENT,circular,X,Y

to indicate a circular segment with a radius of X meters to the left-most lane and an angle span of Y degrees. If Y is positive the lane will turn to the right and if it is negative to the left.

Next, you can optionally indicate if your segment should contain entry lanes on the left or right:

$TYPE,entry,[left|right]

or exit lanes on the left or right:

$TYPE,exit,[left|right]

The second argument [left|right] is optional (right is the default).

You can then specify the speed limit on the segment:

$SPEED,X

where X is the speed limit in kilometer per hour.

It is then mandatory to declare the number of lanes to keep from the previous segment and the number of new lanes (for entry and exit segment) with:

$NUM_LANES,X,Y

where X is the number of lanes to keep and Y the number of new lanes. In some circumstances it might be useful to change the number of lanes from one segment to the other without having an entry or exit segment. In such an event you can declare the segment type to be none,[left|right] to be able to specify the lanes to be on the left or on the right of the previous segment, e.g.:

$TYPE,none,left
$NUM_LANES,2

This will continue the highway with 2 lanes on the left of the previous segment.

Finally if your segment is an entry segment, you can specify the entry rate of specific lanes with:

$LANE,X,Y

where X is the lane index (0 is the left-most lane, 1 would be the lane on the right of the left-most lane, ...) and Y is the entry rate in vehicles per hour.

Lanes can have different markings (such a broken white line or solid white line):

$LEFT_MARKING,X,Y,Z,[broken|solid]
$RIGHT_MARKING,X,Y,Z,[broken|solid]

where X is the lane index, Y is the starting position and Z the ending position.

Finally if you decide that you want to place a road sensor on this segment, you can declare a sensor named name with:

$DENSITY_SENSOR,name,X,Y,Z

to record traffic density (in vehicles per kilometer) with X being the lane index, Y the entry position of sensor and Z the exit position (if the segment is straight X is in meters, if it is circular X is in degrees). Or

$SPEED_SENSOR,name,X,Y

to record time mean speed data in kilometers per hour with Y being the position of the detector on the segment. Or

$FLOW_SENSOR,name,X,Y

to record the flow in vehicles per hour. The sensors average the data from the traffic every minute and dump this value in a log file (if the option --record is given to Disim).

You can also place actuators on the road such as a traffic light:

$TRAFFIC_LIGHT,name,X,Y

or a variable speed limit sign:

$SPEED_LIMIT,name,X,Y

Also, if you want to have a closed loop you can use

$CLOSE_THE_LOOP

at the end of the file to link the first segment with the last.

Syntax

Here is the complete syntax where square brackets [] indicate a mandatory option, curly braces {} indicate optional text, parenthesis () and the asterisk * group expressions together such that (x)* means that x can be repeat as many times as wanted.

$NAME,[name of the map]
{$LANE_WIDTH,[width of the lanes in meters]}

(
$SEGMENT,[straight/circular],[length/radius in m]{,[angle span in degrees, it can be negative]}
{$TYPE,[entry/exit/none]{,[left/right]}}
{$SPEED,[speed in km-h]}
$NUM_LANES,[number of kept lanes]{,[number of new entry/exit lanes]}
{$LANE,[lane id 0:left-most, 1, 2],[entry rate veh-hr]{,[name]}}
{$LEFT_MARKING,[lane id 0:left-most, 1, 2],[from position in m/degrees],[to position in m/rad],[broken/solid]}
{$RIGHT_MARKING,[lane id 0:left-most, 1, 2],[from position in m/degrees],[to position in m/rad],[broken/solid]}
{$DENSITY_SENSOR,[name],[lane id 0:left-most, 1, 2],[first loop detector position in m/degrees],[second loop detector position in m/degrees]{,[log/nolog]}}
{$SPEED_SENSOR,[name],[lane id 0:left-most, 1, 2],[loop detector position in m/degrees]{,[log/nolog]}}
{$FLOW_SENSOR,[name],[lane id 0:left-most, 1, 2],[loop detector position in m/degrees]{,[log/nolog]}}
{$TRAFFIC_LIGHT,[name],[lane id 0:left-most, 1, 2],[position in m/degrees]}
{$SPEED_LIMIT,[name],[lane id 0:left-most, 1, 2],[position in m/degrees]}
)*

{$CLOSE_THE_LOOP}

Currently, no verification are made when parsing the maps, hence Disim will very ungracefully quit when a bad map is given.

Example

We are going to construct the highway visible on the thumbnail on the right side:

An example of a highway in Disim

We observe that this highway is composed of 4 segments:

• A circular segment (top-left corner) with 2 lanes such that the left lane has a radius of 50 meters,
• A straight segment of 100 meters,
• Another circular segment with 3 lanes, the 3rd lane is an additional lane (not a new entry) and
• Another straight segment with 3 lanes.

We will call the map: An example

Let us start by the preamble:

$NAME,An example

Then let us add the first segment:

$SEGMENT,circular,50,90
$TYPE,entry,left
$NUM_LANES,0,2
$LANE,0,3000
$LANE,1,3000

This segment is circular with a radius of 50 meters and the angle span of the segment is 90 degrees. This segment, as it is the first of our highway, is an entry creating 2 lanes. Both lanes have an entry rate of 3000 vehicles per hour.

The second segment is a simple continuation of the previous one:

$SEGMENT,straight,100
$NUM_LANES,2

The segment is straight and has a length of 100 meters. It has 2 lanes.

The third segment is a little more complicated. It has 3 lanes such that the 3rd lane (the new lane) is on the right of the previous segment (or rather than its left-most lane is attached to the left side of the previous segment):

$SEGMENT,circular,50,-180
$TYPE,none,left
$NUM_LANES,3

It is a circular segment with a radius of 50 meters and an angle span of 180 degrees turning to the left side (hence the negative sign). It's left-most lane is the continuation of the left-most lane of the previous segment (try to use $TYPE,none,right to test) and it has 3 lanes.

The last segment is a simple 3 lane segment continuing the previous segment and being an exit of the highway:

$SEGMENT,straight,100
$TYPE,exit
$NUM_LANES,0,3

Its type is exit and the number of lanes kept to continue after the exit is 0 and the number of lanes exiting is 3.

The final map file example.map looks like this:

$NAME,An example

$SEGMENT,circular,50,90
$TYPE,entry,left
$SPEED,120
$NUM_LANES,0,2
$LANE,0,3000
$LANE,1,3000

$SEGMENT,straight,100
$NUM_LANES,2

$SEGMENT,circular,50,-180
$TYPE,none,left
$NUM_LANES,3

$SEGMENT,straight,100
$TYPE,exit
$NUM_LANES,0,3

What's next?

In the next section, we are going to see how one can create a new car behavior.