There are three possibilities to describe own routes. The most trivial one is to do this by hand. The first way to make more vehicle trips more automatically is the usage of trip definitions, the second one the usage of flow descriptions. Trip definitions describe the movement of a single vehicle giving the departure time, and both the origin and the destination edges via their id. Flow descriptions use these values too, but instead of describing only one vehicle, the description is used for a defined number of vehicles to be emitted within a described interval. Due to this, instead of the departure time, the period's begin and end times must be supplied and the number of vehicles to emit within this interval.

We will describe both data types less briefly, now.

<routes>
   <vtype id="type1" accel="0.8" decel="4.5" sigma="0.5" length="5" maxspeed="70"/>
</routes>

<routes>
   <vtype id="type1" accel="0.8" decel="4.5" sigma="0.5" length="5" maxspeed="70"/>

   <vehicle id="0" type="type1" depart="0" color="1,0,0">
      <route>beg middle end rend</route>
   </vehicle>

</routes>

<routes>
   <vtype id="type1" accel="0.8" decel="4.5" sigma="0.5" length="5" maxspeed="70"/>

   <route id="route0" multi_ref="x" color="1,1,0">beg middle end rend</route>

   <vehicle id="0" type="type1" route="route0" depart="0" color="1,0,0"/>
   <vehicle id="1" type="type1" route="route0" depart="0" color="0,1,0"/>

</routes>

duarouter --trip-defs=<TRIP_DEFS> --net=<SUMO_NET> \
   --output-file=MySUMORoutes.rou.xml -b <UINT> -e <UINT>

<flow id="0" from="edge0" to="edge1" begin="0" end="3600" no="100"/>

<interval begin="0" end="3600">
   <flow id="0" from="edge0" to="edge1" no="100"/>
</interval>

duarouter --flow-defs=<FLOW_DEFS> --net=<SUMO_NET> \
   --output-file=MySUMORoutes.rou.xml -b <UINT> -e <UINT>

duarouter --flow-defs=<FLOW_DEFS> --trip-defs=<TRIP_DEFS> --net=<SUMO_NET> \
   --output-file=MySUMORoutes.rou.xml -b <UINT> -e <UINT>

Random routes are the easiest, but also the most inaccurate way to feed your network with vehicle movements. Using the following call ro DUAROUTER:

duarouter --net=<SUMO_NET> -R <FLOAT> --output-file=MySUMORoutes.rou.xml \
   -b <UINT> -e <UINT>

or the same for the JTRROUTER:

jtrrouter --net=<SUMO_NET> -R <FLOAT> --output-file=MySUMORoutes.rou.xml \
   -b <UINT> -e <UINT>

you will generate random routes for the time interval given by -b(egin) and -e(nd). In each time step as many vehicles will be emitted into the network as given by the value of -R (--random-per-second). You can also supply values smaller than one. In this case, a single vehicle will be emitted each 1/<-R> step. Example: -R 0.25 generates a route description, which, when loaded, forces the simulation to emit a single vehicle each fourth time step. It is also possible to use this parameter in combination with other route definitions, for example supplying some fix routes and additionally generate random routes.

Random routes are not the best way to generate routes. Take a look at the network displayed below. This network has two rural and many minor roads. Random routes are by now spread all over the network and each road is chosen to be the starting or the ending without respecting his function. Due to this, the network is filled over with cars, coming from and approaching directions, the normal traffic is not taking - the normal traffic would concentrate on rural roads.

Figure 5.2. A network where the usage of random routes causes an improper behaviour due to the mixture of rural and minor roads

There is also another problem with random routes: Often, the route starts in the opposite direction of the destination - on the wrong side of the road. This yields in a large amount of vehicles that want to turn back using the first possibility. This is of course also not common in the real world, especially not in areas as the one shown above. To avoid this, we remove the first and the last edge from the route per default when generating random routes. !!! revalidate this!!!

Options:

The JTRROUTER is a routing applications which uses flows and turning percentages at junctions as input. The following parameter must be supplied: the network to route the vehicles through, the description of the turning ratios for the junctions (defaults may be used for this, too), and the descriptions of the flows.

A call may look like this:

jtrrouter --flow-defs=<FLOW_DEFS> --turns=<TURN_DEFINITIONS> --net=<SUMO_NET> \
   --output-file=MySUMORoutes.rou.xml -b <UINT> -e <UINT>

The definitions of the flow look like the ones for the DUAROUTER with just a single difference: as it is not known where the vehicle will leave the network as the route it uses is randomly computed, the destination parameter has no meaning for jtr-routing and so may be left off. A vehicle leaves the network as soon as it comes to a sink edge. As not all networks have sink edges set, one can support a list of edges to be declared as sinks using --sinks <EDGE_ID>[;<EDGE_ID>]*.

To describe the turn definitions, one has to build a further file. Within this file, for each interval and each edge the list of percentages to use a certain follower is to be given. An example:

<turn-defs>
   <interval begin="0" end="3600">
      <fromedge id="myEdge0">
         <toedge id="myEdge1" probability="0.2"/>
         <toedge id="myEdge2" probability="0.7"/>
         <toedge id="myEdge3" probability="0.1"/>
      </fromedge>

      ... any other edges ...

   </interval>

   ... some further intervals ...

</turn-defs>

The snippet defines that vehicles coming at the end of edge "myEdge0" within the time interval between 0s and 3600s will choose the edge "myEdge1" with a probability of 20%, "myEdge2" with a probability of 70% and "myEdge3" with a probability of 10%. The specification of such information is of course quite extensive and so the JTRROUTER is also able to read the turning ratios from a cvs file. The same information as above may be coded the following way:

begin;end;from;to;split
0;3600;myEdge0;myEdge1;0.2
0;3600;myEdge0;myEdge2;0.7
0;3600;myEdge0;myEdge3;0.1

	Caution
	Do not forget to give the order of the attributes in the first line of the file.

Another possibility to save time on preparing the description is to use default values. The parameter --turn-defaults (-T) <TURN_DEFAULTS> can be used to describe the default ratios that will be used for all junctions for all time steps. <TURN_DEFAULTS> is a list of doubles, separated by a ';'. To achieve the same behaviour as in the example above, use --turn-defaults=20;70;10. The values will be applied to an edge's following edges beginning at the right edge (20%) and ending at the leftmost edge (10%). As the number of possible followers changes for different edges, the values are resampled for edges which number of following edges differs from the number of given turning probability defaults. Given --turn-defaults=20;70;10 a vehicle using an edge that has two followers would use the follower to the right with 55% probability, the one to the left with 45%.

As theoretically a route may get infinitely long when a vehicle is forced to take always the same direction, it is possible to limit the route's size using max-edges-factor. This factor, multiplied with the number of the used network's edges is the maximum number of edges a route may have. With the default of 2.0, a route may contain twice as many edges as the network has. Any route longer than this size will be marked as invalid. We assume that for each network this number has to be chosen again.

The following options are accepted by JTRROUTER:

Recent changes:

Examples:

Several examples may be found in <SUMO_DIST>/data/examples/jtrrouter/.

OD2TRIPS computes trips tables from O/D (origin/destination) matrices. OD2TRIPS assumes the matrix/matrices to be coded as amounts of vehicles that drive from one district to another within a certain time period. Because the generated trips must start and end at edges, OD2TRIPS requires a mapping of districts to edges. During conversion of VISUM networks - the base of the OD2TRIPS development - districts stored in the VISUM input file are parsed and stored within the outputted SUMO network file. If you do not use VISUM as input, you must build a districts file by your own. The format is given in "Describing the Districts", one of the next subchapters. You have to pass the file containing the district definitions to OD2TRIPS using the --net-file (--net or -n for short) option.

Because OD2TRIPS was used only to import data stored in VISUM/VISION formats, it assumes O/D to be stored in one of the VISUM formats. Not all VISUM formats are supported, by now only two, namely the "VMR" and the "OR" format. If you do not own matrices stored in these formats, you still have three possibilities: a) convert them into one of the supported formats, b) write your own reader for OD2TRIPS, or c) convert them into flow definitions and then give them to DUAROUTER (see Chapter "Using Flow Definitions"). Both supported formats are described in "Describing the Matrix Cells", one of the next subchapters. You may either give a list of matrices to OD2TRIPS using the --od-files (--od or -d for short) option followed by the list of files separated using a ';', or - when importing routes from a Vissim simulation - using --vissim <VISSIM_SIMULATION_FILE> to read the matrices referred in this simulation file.

OD2TRIPS reads all matrices and generates trip definitions as described in "Using Trip Definitions". The generated trip definitions are numbered starting at zero. You can also add a prefix to the generated trip definition names using --prefix <STRING>. As usual, they are written to the output file named using the --output-file option (--output or -o for short). OD2TRIPS colors the trip definitions. To remove this feature, use --no-color. You can specify a vehicle type to be added to the trip definitions using --vtype followed by the type name. Please remark that vehicles will have no type unless not given in the O/D-matrices or defined using this option. This option overrides type names given in the O/D-matrices. The type itself will not be generated. Vehicles will be generated for the time period between --begin (-b) and --end (-e), having 0 and 86400 as default values, respectively. The meaning is the simulation step in seconds, as usual.

Because each O/D-matrix cell describes the amount of vehicles to emit within a certain time period, OD2TRIPS has to compute the vehicle's explicite departure times. Normally, this is done by using a random time within the time interval the O/D-matrix cell is defined for. It still is possible to emit a cell's vehicles with an uniform time between their emissions. Use the option --spread.uniform to enable this.

You can scale the amounts stored in the O/D-matrices using the --scale option which assumes a float as parameter. All read flows will be multiplied with this values, the default is 1. When importing O/D-matrices that cover a whole day, you maybe want to apply a curve which resembles the spread of the trip begins found in reality. Please read the subchapter "Splitting large matrices" on this.

Figure 5.3. Building trips from the OD-matrix

Specific options:

Examples: None yet.

Recent changes:

<districts>
   <district id="<DISTRICT_ID>">
      <dsource id="<EDGE_ID>" weight="<PROBABILITY_TO_USE>"/>
      ... further source edges ...

      <dsink id="<EDGE_ID>" weight="<PROBABILITY_TO_USE>"/>
      ... further destination edges ...
   </district>

   ... further districts ...

</districts>

$VMR
* vehicle type
4
* From-Time  To-Time
7.00 8.00
* Factor
1.00
*
* some
* additional
* comments
* District number
3
* names:
         1          2          3
*
* District 1 Sum = 6
         1          2          3
* District 1 Sum = 15
         4          5          6
* District 1 Sum = 24
         7          8          9 

$OR;D2
* From-Time  To-Time
7.00 8.00
* Factor
1.00
* some
* additional
* comments
         1          1       1.00
         1          2       2.00
         1          3       3.00
         2          1       4.00
         2          2       5.00
         2          3       6.00
         3          1       7.00
         3          2       8.00
         3          3       9.00

Although originally ARTEMIS-routes are stored within an OD-matrix, the import within SUMO is done using the DUAROUTER program.

This is basically done this way:

duarouter --artemis=<ARTEMIS_FOLDER> --net=<SUMO_NET> \
  --output-file=MySUMORoutes.rou.xml -b <UINT> -e <UINT>

Remind that you have to specify the begin and the end of the simulation. This is quite inconsequent, as our mechanisms would allow import of repeatable routes, too. This is just not yet implemented.

Known problems:

One of the main concepts of FastLane is the Dynamic User Assignment by Christian Gawron. As this mechanism is based on single vehicle routes, those are given for a FastLane simulation. The router module has only to convert routes from the FastLane- into the SUMO-representation. Do this using the following command:

duarouter --cell=<CELL_FILE_NAME(NO_EXTENSION)> --net=<SUMO_NET> \
   --output-file=MySUMORoutes.rou.xml -b <UINT> -e <UINT>

If you are familiar with FastLane, you may have noticed that you have only to supply one file name while FastLane uses two files to describe the routes: one "*.driver" and one "*.rinfo" file. As both files have the same name and only the extension differs, you have to give the name without the extension. So if your files have the names "foo.driver" and "foo.rinfo", write --cell=foo.

FastLane stores routes within a very large file what makes the process quite slow. If you want to speed it up for the future, you can tell SUMO-ROUTER to save some temporary files using --save-cell-rindex. A further file named "<CELL_FILE_NAME>.rindex" will be generated. It speeds up the processing by a factor of ten or so.

As FastLane is portable, you may encounter files generated on a Windows-machine. Those files give some strange warnings, something that should not happen if you supply the right net. To avoid them, use the --intel-cell switch to tell DUAROUTER it has to turn the byte order.

You can also decide whether the best, not the last route a driver took shall be used: set the switch --no-last-cell for this.

See "Using OD2TRIPS" for information about how to import O/D-matrices in ptv format.

"dua-iterate.pl" helps you to perform the computation of a dynamic user assignment. The script needs at least two parameter: the path to the folder where your SUMO-binaries are located and the number of iteration steps to perform. When started with these two options, the script computes the given number of dua-steps. As input two files have to be located in the same folder as the script: a SUMO-network named "net.net.xml" and a set of trip definitions named "trips.trips.xml". if you want to start with another routes definition, you have to change this within the script's source code.

Within each iteration step, the script generates a configuration file for the DUAROUTER and starts DUAROUTER with this configuration file. Then, a configuration file for SUMO is built and SUMO ist started. Both configuration files are competely defined within the script itself. As default, for each time step, SUMO will generate three dump files with edge-dumps aggregated over 150, 300, and 900s, an emissions and a trip information output. The names of these outputs are numbered over the iteration steps. If you want to change the outputs, you also have to take a look into the script, but you should not disable the edge-based dump for aggregation over 900s, because this is read by the DUAROUTER in the next iteration steps in order to compute the DUA.

When started with a third parameter, the second parameter given will be interpreted as the start iteration step and the third as the end iteration step.

This useful script is located in <SUMO_DIST>/tools/dua_tools/.

Synopsis:

dua-iterate.pl <PATH_TO_SUMO_BINARIES> [[<BEGIN_ITERATION_STEP>]] <END_ITERATION_STEP>

printProgress.pl

The idea behind the DFROUTER assumes that a network is completely covered by detectors, meaning that all off- and on-ramps have an induction loop placed on them. Such an information whether an induction loop is a pure source or sink or whether it is placed between such is but not given initially. It must be computed. To do this, the DFROUTER needs the underlying network as well as a list of detector definitions where each describes the position of an induction loop. The network, being a previously build SUMO-network, is supplied to the DFROUTER as usually using the ( --net-file | --net | -n ) <SUMO_NET_FILE> - option, the list of induction loops using --detector-files (or --detectors or -d for short) <DETECTOR_FILE>[;<DETECTOR_FILE>]+. A detector file should look as following:

<detectors>
   <detector_definition id="<DETECTOR_ID>" lane="<LANE_ID>" pos="<POS>"/>
... further detectors ...
</detectors>

This means that each detector is initially described using its id, a lane it is placed on, and a position on the lane. To be exact:

Given a network and the list of detectors, DFROUTER assigns types to detectors (TBD: add a reference) and saves the so extended list into a file if the option --detectors-output <DETECTOR_OUTPUT_FILE> is given. This list looks like the input described above except that an aditional attribute is given for each detector, "type", which may have one of the following values: "source", "sink", "between", and "discarded". You can also generate a list of points of interests (POIs) which can be read by GUISIM where each POI represents a detector and is colored by the detector type: green for source detectors, red for sink detectors, blue for in-between detectors, and black for discarded detectors. To force DFROUTER to do this, use --detectors-poi-output <POI_FILENAME>.

When wished, if for example other parameters chage, the extended <DETECTOR_OUTPUT_FILE> can be fed back again into DFROUTER instead of the previous <DETECTOR_FILE>. In this case the detector types do not have to be computed again. To force DFROUTER to recompute the types though, use --revalidate-detectors.

Specific options:

Now that we do know where vehicles enter and where they leave the network, we may compute routes for each of the pairs. The DFROUTER is told to build and save routes using --routes-output <ROUTE_OUTPUT_FILE> where <ROUTE_OUTPUT_FILE> is the name of the file the computed routes shall be written to. The generated file only contains routes, no vehicle type definitions and no vehicles. In later runs, you can omit the routes computation by supplying previously generated routes using --routes-input (or -r) <ROUTE_FILE>. Again, as during the computation of the detector types, you can force DFROUTER to recompute the routes even if suppling them using --revalidate-routes.

Normally, only routes starting at source detectors and ending at sink detectors are computed. Using the option --routes-for-all you can force DFROUTER to also build routes that start at in-between detectors. The option --all-end-follower will make the routes not end at the edge the source detector is placed on, but on all edges that follow this edge (TBD: recheck this). --keep-unfound-ends will also keep those routes where a sink detector could not be found for what may be the case if the network is not completely covered with induction loops.

Specific options:

The next step is to use the computed routes and flow amounts from the real-world detectors to compute flows across the modelled network. The flows are given to DFROUTER using --detector-flow-files (or --detflows, -f for short) <DETECTOR_FLOWS>[;<DETECTOR_FLOWS>]+. They are assumed to be stored in CSV-format using ';' as dividing character. The file should look as following:

Detector;Time;qPKW;qLKW;vPKW;vLKW
myDet1;0;10;2;100;80
... further entries ...

This means the first time has to name the entries (columns). Their order is not of importance, but at least the following columns must be included:

These are not quite the values to be found in induction loop output. We had to constrain the <DETECTOR_FLOWS> files this way because DFROUTER is meant to read very many of such definitions and to do this as fast as possible. Because even this scheme was too slow for some purposes, flow amounts can also be marked as more valid using the option --fast-flows. If set, DFROUTER assumes that there is no header line and that the values are separated using spaces. In this case, the columns must be in the order time, detector name, qPKW, qLKW, vPKW, and vLKW.

Because in some cases one reads detector flow definitions starting at a certain time but wants his simulation begin at another, it is possible to add a time offset using --time-offset <TIME_OFFSET> which is subtracted from the read times. <TIME_OFFSET> is meant to be an int representing seconds.

(TBD: verify: how long is the time period, are speeds given in m/s, is qPKW/qLKW right, does qPKW/qLKW describe the amount within this period or within one hour)

Specific options:

Recent changes

If flow definitions were supplied, we can let the DFROUTER save the computed vehicles together with their routes. Because vehicles will be emitted at the source detectors which are placed at certain positions of the networks' lanes, emitters (see "Emitter") are used to insert those vehicles into the network. You can force the DFROUTER to generate such emitters using --emitters-output <EMITTER_OUTPUT_FILE>. This file will contain emitter declarations for each of the source detectors. If no value is given, emitters will not be written. Accompanying, there will be emitter definitions written named "emitter_<DETECTOR_ID>.def.xml" where <DETECTOR_ID> is the id of the according source detector. These definitions are called within the <EMITTER_OUTPUT_FILE> and contain vehicles which depart the emitter in accordance to the read flows and have routes computed using the flows.

As some approaches use a speed limit to avoid open-end boundary problems (TBD add a reference), the DFROUTER can generate a list of speed triggers (see "Variable Speed Signs (VSS)") placed on the positions of sink detectors. The name to save the declaration of these speed triggers into is given using the option --speed-trigger-output <VSS_OUTPUT_FILE>. The according speed trigger definitions will be written into files named "vss_<DETECTOR_ID>.def.xml" where <DETECTOR_ID> is the name of the according sink detector.

In order not to end vehicle routes on off-ramps, it is possible to place rerouters (see "Rerouter") at the positions of the sink detectors, too. Giving the option --end-reroute-output <REROUTER_OUTPUT_FILE> will generate a list of rerouter declarations. Please remark that in this case, no rerouter definitions are written, because the DFROUTER has no further information about possible routes beyond the area covered by the detectors.

It's quite nice to have the possibility to check whether the simulation does what one wants. To validate whether the same flows are found within the simulation as within the reality, the option --validation-output <SUMO_DETECTORS_OUTPUT> may be helpful. It generates a list of detector definitions (E1/induct loops, see "E1-Detectors (Induct Loops)") placed at the positions of sink and in-between detectors. Their output will be saved into files named "validation_det_<DETECTOR_ID>.xml" and should be easily comparable to the detector flows previously fed to the router. The option --validation-output.add-sources will let DFROUTER also build E1-detectors for source detectors which are place 1m behind the real-life detector's position.

(TBD: check whether everything is placed into the proper directory; check what's about PKWs/LKWs)