• Importing O/D Matrices

od2trips computes trip tables from O/D (origin/destination) matrices. od2trips assumes the matrix / the matrices to be coded as amounts of vehicles that drive from one district or traffic assignment zone (TAZ) to another within a certain time period. Because the generated trips must start and end at edges, od2trips requires a mapping of TAZ to edges. During conversion of VISUM networks with netconvert districts stored in the VISUM input file are parsed and stored within the generated SUMO network file. If you do not use VISUM as input, you must build a TAZ file by your own. The format is given in #Describing_the_TAZ below. You have to pass the file containing the TAZ definitions to od2trips using the --net-file <FILE> (--net <FILE> or -n <FILE> for short) option. TAZ can be created by drawing polygons in netedit and processing them with the tool Tools/District#edgesInDistricts.py.

All supported OD-formats are described in #Describing_the_Matrix_Cells below. You may either give a list of matrices to od2trips using the --od-matrix-files <FILE>[,<FILE>]* (-d <FILE>[,<FILE>]* for short) option followed by the list of files separated using a ','.

od2trips reads all matrices and generates 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 <FILE> (-o <FILE> for short). You can specify a vehicle type to be added to the trip definitions using --vtype <STRING>. Please remark that vehicles will have no type unless given in the O/D-matrices or defined using this option. The command line 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 <TIME> (-b <TIME>) and --end <TIME> (-e <TIME>), 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 be inserted into the network within a certain time period, od2trips has to compute the vehicle's explicit departure times. Normally, this is done by using a random time within the time interval a O/D-matrix cell describes. It still is possible to insert a cell's vehicles with an uniform time between their insertion. Use the option --spread.uniform to enable this.

You can scale the amounts stored in the O/D-matrices using the --scale <FLOAT> option which assumes a float as parameter. All read flows will be multiplied with this value, 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.

Describing the TAZ#

A traffic assignment zone (or traffic analysis zone), short TAZ is described by its id (an arbitrary name) and lists of source and destination edges.

Simple Definition#

If you do not want to distinguish between source and sink edges and give all edges the same probability you can use the following abbreviated form:

<tazs>
    <taz id="<TAZ_ID>" edges="<EDGE_ID> <EDGE_ID> ..."/>

    ... further traffic assignment zones (districts) ...

</tazs>

Differentiated Probabilities#

To distinguish the set of source and sink edges (or their probabilities respectively) use the following definition:

<tazs>
    <taz id="<TAZ_ID>">
      <tazSource id="<EDGE_ID>" weight="<PROBABILITY_TO_USE>"/>
      ... further source edges ...

      <tazSink id="<EDGE_ID>" weight="<PROBABILITY_TO_USE>"/>
      ... further destination edges ...
    </taz>

    ... further traffic assignment zones (districts) ...

</tazs>

A TAZ should have at least one source and one destination edge, each described by its id and use probability called weight herein. These edges are used to insert and remove vehicles into/from the network respectively. The probability sums of each the source and the destination lists are normalized after loading.

Creating TAZ files#

• TAZ definitions can be created directly in netedit
• TAZ definitions can be created by drawing polygons in netedit, then using the tool edgesInDistricts.py for converting polygons to TAZ.

Further Usage for TAZ#

• TAZ can be used with route input for duarouter
• TAZ can be used with trips and flows for SUMO.
• TAZ edges appear in the simulation as special edges with the IDs tazID-source and tazID-sink. This can be used when specifying vehicle routes via TraCI.

Optional Attributes#

Describing the Matrix Cells#

To understand how an O/D-matrix is stored, we should remind the meanings of the values stored herein. Each matrix describes a certain time period. The indices within the matrix are names of the origin/destination districts (normally they are equivalent, both lists are the same). The values stored within the matrix are amounts of vehicles driving from the according origin district to the according destination district within the described time period.

tazRelation format#

The tazRelation format defines the demand per OD pair in time slices for every a given vehicle type as follows:

<data xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://sumo.dlr.de/xsd/datamode_file.xsd">
    <interval id="car" begin="0" end="1:0:0">
      <tazRelation count="2000" from="1" to="2"/>
      <tazRelation count="500" from="1" to="3"/>
      ...
    </interval>
    <interval ...>
    ...
</data>

Files in tazRelation format can be created and modified with netedit. They can also be created from route and taz files with route2OD.py (reversing the action of od2trips).

For details on the types and units see the schema at https://sumo.dlr.de/xsd/datamode_file.xsd

PTV formats#

The formats used by PTV are described in the VISUM-documentation more detailed. All start with a line where the type of the O/D-matrix is given, appended to a '$'. The first following character tells in which format the table is stored. Then, further characters follow which describe which values are supplied additionally within the matrix. For further information we ask you to consult the documentation supported by PTV. Herein, only the supported variants are described.

The vehicle type information is used by od2trips by passing it to the generated vehicles. The type definition itself will not be generated, but the vehicle will have set the attribute type="<TYPE>". The time information are assumed to be in the form <HOURS>.<MINUTES>. Please note that the end is exclusive; for example, if

0.00 1.00

is given, the generated vehicles' depart times will be second 0 to second 3599.

The V format (VISUM/VISSIM)#

The V-format stores the O/D matrix by giving the number of districts (TAZ) first and then naming them. After this, for each of the named districts, a list of vehicle amounts that leave this district is given, sorted by the destination district names as given in the district name list. An example may look like this:

$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 2 Sum = 15
         4          5          6
* District 2 Sum = 24
         7          8          9

The 'M' in the type name indicates that a vehicle type is used, the "R" that the values shall be rounded randomly. The second information is not processed by od2trips what means that you can parse both V-, VR-, VMR, and VM-matrices. Please remark that both the names list and the lists containing the amounts are written in a way that no more than 10 fields are stored in the same line. Each of the entries they contain seem to be left-aligned to a boundary of 11 characters (possibly 10 for the name and one space character). Both constraints are not mandatory for the importer used in od2trips.

The O-format (VISUM/VISSIM)#

The O-format instead simply lists each origin and each destination together with the amount in one line (please remark that we currently ignore the string after the ';' that occurs after the type identifier "$OR" in the first line):

$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

• The first line is a format specifier that must be included verbatim.
• The lines starting with '*' are comments and can be omitted
• The second non-comment line determines the time range given as HOUR.MINUTE HOUR.MINUTE
• The third line is a global scaling factor for the number of vehicles for each cell
• All other lines describe matrix cells in the form FROM TO NUMVEHICLES

The Amitran format#

The Amitran format defines the demand per OD pair in time slices for every vehicle type as follows:

<demand xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://sumo.dlr.de/xsd/amitran/od.xsd">
   <actorConfig id="0">
       <timeSlice duration="86400000" startTime="0">
           <odPair amount="100" destination="2" origin="1"/>
       </timeSlice>
   </actorConfig>
</demand>

For details on the types and units see the schema at https://sumo.dlr.de/xsd/amitran/od.xsd

Splitting large Matrices#

od2trips allows splitting matrices which define a long time period into smaller parts which contain definite percentages of the whole. There are two ways of defining the amounts the matrix shall be split into. In both cases, the probabilities are automatically normed.

Free Range Definitions#

The first possibility is to use the option --timeline directly. In this case, it should be followed by a list of times and probabilities, separated by ','. Each time and probability field is made up of two values, an integer time being the simulation time in seconds and a floating point number describing the probability. These two values are separated using a ':'. At least two values must be supplied making the definition of a timeline in this case being describable by the following BNF-formula:

 <TIME>:<AMOUNT>[,<TIME>:<AMOUNT>]+

In this case, the matrix will be split into (fields-1) parts and each part will have the amount described by the integral within the field. (This means the amount specified after the last time entry will be discarded.)

Daily Time Lines#

The second case is rather common in transportation science. It allows to split the matrix into 24 subparts - this means the number of fields is fixed to 24 - allowing to spread an O/D-matrix over a day describing it by hours. To use this, give additionally the option --timeline.day-in-hours to od2trips. It the assumes the values from the --timeline - option being a list of 24 floats, divided by ',', each describing the probability of inserting a vehicle within the according hour.

Some common daily time lines from Germany may be retrieved from: Schmidt, Gerhard; Thomas, Bernd: Hochrechnungsfaktoren für manuelle und automatische Kurzzeitzählungen im Innerortsbereich. Hrsg.: Bundesministerium für Verkehr, Abteilung Straßenbau: Forschung Straßenbau und Straßenverkehrstechnik. Heft 732, Bonn-Bad Godesberg, 1996

Applicability of generic Time Lines

So, in dependence to the week day and the type of traffic, one could assume using the following time-lines:

One may note, that no time lines are given for passenger trips on Mondays.

The time lines as such are given below, they can be directly copied into the command line

Generic Time Lines

Remarks:

• All time lines describe the hourly percentage of the complete traffic
• values are normalized to 100% (so they don't need to add up to any specific value)
• It is not possible to derive time-lines for all week days

The time lines describe how the traffic (100%) spreads over the whole day. In order to have proper demands for week-end days, one can scale down the week day traffic. The same reference as above gives the following scaling factors at page 31.

Daily time-line scale factors

One may note that this information is several years old. Additionally, no information about the type of vehicles is given.

A 24h time line a given O/D-matrix shall be split by may be given to od2trips using the following options: --timeline.day-in-hours --timeline <TIME_LINE> where <TIME_LINE> is a list of 24 percentages as given above. The amount of traffic defined within the O/D-matrix may be scaled via --scale <SCALE>. Example call to od2trips:

od2trips -n <NET> -d <MATRIX> -o <OUTPUT> --scale <SKALIERUNG> \
   --timeline.day-in-hours --timeline <TIME_LINE>

Generated traffic modes#

By default od2trips generates vehicular traffic. Different types of traffic (passenger cars, trucks,...) can be created by using the option --vtype and --prefix (the latter is needed so that different types use distinct vehicle ids).

By setting one of the options --pedestrians or --persontrips, other modes can be generated.

Combining trips from multiple calls#

Sometimes it is necessary to call od2trips multiple times to generated all the traffic for a given scenario:

• to model different vehicle types which differ in their demand levels
• to model time-varying demand that is heterogeneous between the OD-pairs (and therefore cannot be modelled by applying a time-line)

In this case the option --prefix <STRING> must be used with a distinct value for each call to od2trips in order to make avoid duplicate trip ids.

Dealing with broken Data#

od2trips behaves here as following:

incomplete districts

• missing origin OR destination district: error
• missing origin AND destination district: warning

incomplete connections

• missing connection to an origin OR a destination district: error
• missing connection to an origin AND a destination district: error

This part of SUMO was developed, reworked, or extended within the project "AMITRAN", co-funded by the European Commission within the Seventh Framework Programme.