An induct loop is defined either this way:

<detector id="<ID>" type="(induct_loop|E1)" lane="<LANE_ID>" pos="<POSITION_ON_LANE>"
   freq="<AGGREGATION_TIME>" [style="xml"] file="<OUTPUT_FILE>" [friendly_pos="x"]/>

or this way:

<e1-detector id="<ID>" lane="<LANE_ID>" pos="<POSITION_ON_LANE>"
   freq="<AGGREGATION_TIME>" [style="xml"] file="<OUTPUT_FILE>" [friendly_pos="x"]/>

The id is any string that let's you know which detector is meant. The type indicates that a induct loop shall be build, here. The attributes "lane" and "pos" describe on which lane and at which position on him the detector shall lay. As induct loop detectors may aggregate the values they collect, the freq-attribute describes this period. The style-parameter is obsolete by now as the earlier possibility to use either "xml" or "cvs"-output is now not supported, the values are stored in xml-files only. The file attribute tells the simulation to which file the detector shall write his results into. The file will be generated, does not have to exist earlier and will be overwritten if existing without any warning.

	Caution
	The folder the output file shall be generated in must exist.

Let's review the attributes:

Recent changes:

An induct loop is defined the following way:

<detector id="<ID>" type="(areal|lane_based|E2)" lane="<LANE_ID>"
   pos="<POSITION_ON_LANE>" length="<DETECTOR_LENGTH>" freq="<AGGREGATION_TIME>"
   [style="xml"] file="<OUTPUT_FILE>" [measures="<MEASURES>"] [time_treshold="<FLOAT>"]
   [speed_treshold="<FLOAT>"] [jam_treshold="<FLOAT>"] [keep_for="<FLOAT>"]/>

or:

<e2-detector id="<ID>" lane="<LANE_ID>" pos="<POSITION_ON_LANE>"
   length="<DETECTOR_LENGTH>" freq="<AGGREGATION_TIME>" [style="xml"]
   file="<OUTPUT_FILE>" [measures="<MEASURES>"] [time_treshold="<FLOAT>"]
   [speed_treshold="<FLOAT>"] [jam_treshold="<FLOAT>"] [keep_for="<FLOAT>"]/>

Most of the attributes have the same meaning as for induct loops. As an areal detector has a certain length, this length must be supplied as a further parameter. It may also be a negative number which lets the detector be extended upstream to the given beginning position. The type must be set to either "areal", "lane_based" or "E2" to let the simulation know what's desired to build. The optional parameter "cont" let's the detector continue over the current lane onto this lane's predecessors when the detector's length plus his position is larger than the place available on the lane. The attribute "measures" describes which values the detector shall compute. The optional values are described below.

	Caution
	The folder the output file shall be generated in must exist.

	Caution
	For detectors that span over more than a single edge, only the attribute QUEUE_LENGTH_AHEAD_OF_TRAFFIC_LIGHTS_IN_VEHICLES is defined all other may return strange values.

But there is also a further possibility to use E2-detectors. If you place them in front of a traffic light, you can use the traffic light to describe the intervals (aggregation) time instead of giving a fixed aggregation time. In this case, output will be generated every time the traffic light switches. To use this feature, simply replace the freq-attribute within the description of your detector by the id of the traffic light that should steer it (use the attribute "tl" to specify the id) :

<detector id="<ID>" type="[(areal|lane_based|E2)" lane="<LANE_ID>" \
   pos="<POSITION_ON_LANE>" length="<DETECTOR_LENGTH>" tl="<TL-ID>"
   freq="<AGGREGATION_TIME>" [style="xml"] file="<OUTPUT_FILE>"
   [measures="<MEASURES>"] [time_treshold="<FLOAT>"]
   [speed_treshold="<FLOAT>"] [jam_treshold="<FLOAT>"] [keep_for="<FLOAT>"]/>

or:

<e2-detector id="<ID>" lane="<LANE_ID>" pos="<POSITION_ON_LANE>"
   length="<DETECTOR_LENGTH>"  tl="<TL-ID>" freq="<AGGREGATION_TIME>" [style="xml"]
   file="<OUTPUT_FILE>" [measures="<MEASURES>"] [time_treshold="<FLOAT>"]
   [speed_treshold="<FLOAT>"] [jam_treshold="<FLOAT>"] [keep_for="<FLOAT>"]/>

A further feature allows you to output values not for all switches of the traffic light the detector is attached to, but only when the light turns red for the assigned link (connection between the incoming and the outgoing lane). This should allow you to measure the maximum jam length in front of a red traffic light for this link. To switch on this feature, you have to add the name of the following lane: to="<LANE_ID>". The incoming lane is already given by the "lane"-attribute.

E2-detectors may compute many different measures and the user has the possibility to describe which measures he actually wants to be generated. The "measures"-attribute must contain the measures divided by a ' ' (blank) in the case he does not want to compute all parameters. Computing all parameters is the default case but may also be set using 'measures="ALL"' . The available measures are:

Again, the explicit list of available attributes:

And the optional ones:

The descriptions of E3-detectors have to include the set of entry- and the set of exit-cross-sections. Due to this, it is not possible to use a single tag to specify a detector. Instead, the description consists of the following parts:

The definition

<e3-detector id="e3_1" freq="300" file="./output/e3_1.xml">
   <det_entry lane="myEdge0_0" pos="0"/>
   <det_entry lane="myEdge0_1" pos="0"/>
   <det_exit lane="myEdge2_0" pos="0"/>
   <det_exit lane="myEdge2_1" pos="0"/>
</e3-detector>

will build an e3-detector starting at either lane 0 or 1 of the edge called "myEdge0" and end at the same lane of "myEdge2". All values will be computed as the default-value for measures is used and aggregated over a time of 300s. They will be written into the file "e3_1.xml" lying in the subfolder of the folder the configuration was read in/the program has been started within.

Most of the values have been discussed in the previous subchapters. The only thing that differs from e1/e2-detectors are the measures e3-detectors are able to compute. Possible values are:

As for e2-detectors, you can use the value "ALL" for the attribute measures to compute all values. This is also this attributes default value.

To force SUMO to generate edge-based state dumps, you have to use two command line options: a) --dump-basename <PATH_AND_FILE_PREFIX> describes where to write the dumps to and how the begin of the file name is, b) --dump-intervals <INTERVAL>[;<INTERVAL>]* describes over what time the values shall be collected and aggregated ("interval length"). Each aggregation interval is written into an own, single file. The file name is made up from the base name and the aggregation interval: <FILENAME> = <PATH_AND_FILE_PREFIX>_<INTERVAL>.xml. An example: --dump-basename=./output/lanedump --dump-intervals=300;600 will build two files: ./output/lanedump_300.xml and ./output/lanedump_600.xml. For edge-based state dumps, the output file will look like the following:

<netstats>
   <interval begin="<INTERVAL_BEGIN>" end="<INTERVAL_END>">
      <edge id="<EDGE_ID>" traveltime="<MEAN_TRAVEL_TIME>" \
                 nSamples="<VEHICLE_NUMBER>" \
                 density="<MEAN_DENSITY>" occupancy="<MEAN_OCCUPANCY>" \
                 noStops="<NUMBER_OF_HALTS>" speed="<MEAN_SPEED>"/>

      ... more edges ...

   </interval>

   ... further intervals ...

</netstats>

Please remark, that in contrary to the example above, for each edge, all values are reported in one line.

Examples:

Lane-dumps are generated analogous to edge-dumps using the options --lanedump-basename <PATH_AND_FILE_PREFIX> and --lanedump-intervals <INTERVAL>[;<INTERVAL>]*. The generated output looks like the following:

<netstats>
   <interval begin="<INTERVAL_BEGIN>" end="<INTERVAL_END>">
      <edge id="<EDGE_ID>">
         <lane id="<LANE_ID>" traveltime="<MEAN_TRAVEL_TIME>" \
                 nSamples="<VEHICLE_NUMBER>" \
                 density="<MEAN_DENSITY>" occupancy="<MEAN_OCCUPANCY>" \
                 noStops="<NUMBER_OF_HALTS>" speed="<MEAN_SPEED>"/>

         ... more lanes

      </edge>

      ... more edges ...

   </interval>

   ... further intervals ...

</netstats>

Please remark, that in contrary to the example above, for each edge, all values are reported in one line.

Examples:

Both the edge-dump and the lane-dump are computing the values the same way: every vehicle move - even those with v=0 - is recorded and saved during the interval. After the interval has passed, these values are written into the file after being normalised. In the case of the edge-dump the values are not only normalized by the number of the collected vehicle moves and the length of the lane, but also by the number of lanes of the edge.

The meanings of the written values are:

The interval end is the interval begin + aggregation time - 1, meaning that values were collected within these steps. If the simulation ends before the last interval is over, the interval will be prunned.

If you need only information about the network states during certain time periods, you may constraint generation of the dumps using the options --dump-begins <TIME>[;<TIME>]+ and --dump-ends <TIME>[;<TIME>]+. When at least one combination is given, dumps will be written only if an according begin/end-pair exists for the current time. This means, only those intervals will be saved for which dump-begins[x]<=INTERVAL_END and dump-ends[x]>=INTERVAL_BEGIN.

Of course, all dumps will cover the complete simulation if the options --dump-begins and --dump-ends are not set.

Examples:

To enable writing tls state information you have to add the following definition into one of your additional files: <timed_event type="SaveTLSStates" source="<TLS_ID>" dest="<OUTPUT_FILE>"/>. The attributes have herein the following meanings:

The output looks like this:

<tls-states>
   <tlsstate time="<SIM_STEP>" id="<TLS_ID>" subid="<TLS_SUBID>"><STATE></tlsstate>
   ... further states ...
</tls-states>

The state is saved in each simulation second. The state itself is coded as a list of the characters 'G', 'Y', and 'R', standing for "green", "yellow", and "red", respectively. Each character describes a link controlled by the traffic light. Only the state of the current program is saved (see also "Adding new Programs"). The attributes have the following meaning:

Missing:

Recent changes:

This output contains information about the green light phases of links (lane-to-lane connections). Each green light phase is describes by its begin, end and duration. An entry is written into the file as soon a green phase of a link ends. To enable writing tls switch information you have to add the following definition into one of your additional files: <timed_event type="SaveTLSSwitchTimes" source="<TLS_ID>" dest="<OUTPUT_FILE>"/>. The attributes have herein the following meanings:

The output looks like this:

<tls-switches>
   <tlsswitch tls="<JUNCTION_ID>" subid="<JUNCTION_SUB_ID>" \
      fromLane="<LINKS_SOURCE_LANE>" toLane="<LINK_DESTINATION_LANE>" \
      begin="<BEGIN_OF_GREEN_PHASE>" end="<END_OF_GREEN_PHASE>" \
      duration="<DURATION_OF_GREEN_PHASE>"/>
   ... further switch points ...
</tls-switches>

Each entry is written into a single line. The values have the following meanings:

Recent changes:

This output saves tls-states as the TLS States - output does but not every second but only at times the phases or the program (see also "Adding new Programs") change. The output is instantiated by adding the following definition into one of your additional files: <timed_event type="SaveTLSSwitchStates" source="<TLS_ID>" dest="<OUTPUT_FILE>"/>. The attributes have herein the following meanings:

The output looks like this:

<tls-switch-states>
   <tlsstate time="<SIM_STEP>" id="<TLS_ID>" subid="<TLS_SUBID>"><STATE></tlsstate>
   ... further states ...
</tls-switch-states>

Each entry is written into a single line. The values have the following meanings:

Recent changes:

You can place an emitter onto a lane by adding the following declaration to one of your additional-files:

<trigger id="<ID>" objecttype="emitter" pos="<POS>" objectid="<LANE_ID>" \
   [friendly_pos="x"] file="<DEFINITION_FILE>"/>

The fields have the following meanings:

An emitter needs further information to know when, how many and what kind of vehicles shall be emitted. All this information must be written into <DEFINITION_FILE>. The easiest way to describe vehicle emissions herein is to list all of them explicitely:

<triggeredsource>
   <emit id="veh1" time="0" vehtype="my_type" route="my_route" speed="13.9"/>
   <emit id="veh2" time="4" vehtype="my_type" route="my_route" speed="13.9"/>
   <emit id="veh3" time="8" vehtype="my_type" route="my_route" speed="13.9"/>
</triggeredsource>

Using such a definition only would raise error because we have named the vehicle types and the routes but did not define them. We can either define them within another additional file or within a route file but we have to ensure that they're loaded before the emission definition is (see "Using the Files in a correct Way" on loading order). Let's assume we have done it. In this case, using such a definition we would emit three vehicles, having the names "veh1", "veh2", and "veh3" as given within the id-field, all being of type "my_type". All vehicles use the same route, "my_route", and will start with a velocity of 0 at the simulation seconds 0, 4, and 8. To summarize, a vehicle emission within an Emitter definition is described as following: <emit [id="<VEHICLE_ID>"] [vehtype="<VEHICLE_TYPE>"] time="<EMISSION_TIME>" [route="<VEHICLE_ROUTE>"] [speed="<INITIAL_SPEED>"]/>. The meanings of these values are:

As you can see, several of the fields are marked as optional. If no id is given, the id will be constructed automatically. The vehicle will then have a name made up from the emitter's id followed by the time step the vehicle shall be emitted at and a running number, all divided by a '_' ("<EMITTER_ID>_<DEPART>_<RUNNING>"). Also, the emission speed is optional. If not given, the minimum of the maximum speed allowed on the lane and the vehicle's maximum velocity is used. If the emission time lies before the simulation begin, the vehicle will be discarded. The following sections describe how one can omit explicite attributes for vehicle type and route.

To avoid computing and assigning a vehicle type and a route to each vehicle emission definition explicitely, you can define a probability distribution by which routes/types are chosen from a set. For the routes, you can do this as shown in the next example:

<triggeredsource>
   <routedistelem id="my_route1" probability=".2"/>
   <routedistelem id="my_route2" probability=".8"/>

   <emit id="veh1" time="0" vehtype="my_type" speed="13.9"/>
   <emit id="veh2" time="4" vehtype="my_type" speed="13.9"/>
</triggeredsource>

Now, a random route is assigned to a vehicle, "my_route1" with a probability of .2, "my_route2" with a probability of .8. The probabilities are normed automatically, that means that you can also use numbers that do not sum to 1. Each occuring routedistelem will be added to the distribution (see also "Resetting the Distributions"). The meanings of the attributes of a routedistelem-element are:

Vehicle types may be assigned to vehicles from distributions, too:

<triggeredsource>
   <vtypedistelem id="my_type1" probability=".8"/>
   <vtypedistelem id="my_type2" probability=".8"/>

   <emit id="veh1" time="0" route="my_route" speed="13.9"/>
   <emit id="veh2" time="4" route="my_route" speed="13.9"/>
</triggeredsource>

In this example the probabilities for using one of the types are equal. The probabilities are normed automatically, that means that you can also use numbers that do not sum to 1. Each occuring vtypedistelem will be added to the distribution (see also "Resetting the Distributions"). The meanings of the attributes of a vtypedistelem-element are:

As said before, all occurences of vtypedistelem are stored into the same distribution. This also holds for the occurences of routedistelem. Now, one maybe wants to model different distributions over time. To allow this, you can add a "reset"-element to your description:

<triggeredsource>
   <vtypedistelem id="my_type1" probability=".5"/>
   <vtypedistelem id="my_type2" probability=".5"/>
   <routedistelem id="my_route1" probability=".2"/>
   <routedistelem id="my_route2" probability=".8"/>

   <emit time="10" speed="13.9"/>
   ... further vehicle emits ...
   <emit time="20" speed="13.9"/>

   <reset/>

   <vtypedistelem id="my_type3" probability=".5"/>
   <vtypedistelem id="my_type4" probability=".5"/>
   <routedistelem id="my_route3" probability=".2"/>
   <routedistelem id="my_route4" probability=".8"/>

   <emit time="30" speed="13.9"/>
   ... further vehicle emits ...
   <emit time="40" speed="13.9"/>

</triggeredsource>

This would force the emitter to reset all distributions after emitting the vehicle at time 20. While vehicles emitted within the times 10 and 20 would use the vehicle types "my_type1" and "my_type2" and routes "my_route1" and "my_route2", the vehicles emitted between time 30 and 40 - after the reset-element - would use the vehicle types "my_type3" and "my_type4" and the routes "my_route3" and "my_route4".

Instead of describing each vehicle emission explicitely, you can specify a flow to emit. In this case, vehicle type and routes distributions must be given:

<triggeredsource>
   <vtypedistelem id="my_type1" probability=".5"/>
   <vtypedistelem id="my_type2" probability=".5"/>
   <routedistelem id="my_route1" probability=".2"/>
   <routedistelem id="my_route2" probability=".8"/>

   <flow no="1800" end="10"/>
   <flow no="900" end="20"/>
</triggeredsource>

The meaning of the attributes of a flow-element are:

Since version 0.9.4 you may attach a new program to a tls after the network has been loaded. Defining a tls program is not that straightforward, yet. If you are definitely interested in this, we advice you to read the "SUMO - More on... Traffic Lights" document where the format is described. Basically, a tls program definition looks like this:

<tl-logic type="static">
   <key>0</key>
   <subkey>0</subkey>
   <phaseno>8</phaseno>
   <offset>0</offset>
   <phase duration="20" phase="0000111100001111" brake="1111110011111100" \
      yellow="0000000000000000"/>
   <phase duration="4" phase="0000110000001100" brake="1111111111111111" \
      yellow="0000001100000011"/>
   <phase duration="3" phase="0000110000001100" brake="1111001111110011" \
      yellow="0000000000000000"/>
   <phase duration="4" phase="0000000000000000" brake="1111111111111111" \
      yellow="0000110000001100"/>
   <phase duration="20" phase="1111000011110000" brake="1100111111001111" \
      yellow="0000000000000000"/>
   <phase duration="4" phase="1100000011000000" brake="1111111111111111" \
      yellow="0011000000110000"/>
   <phase duration="3" phase="1100000011000000" brake="0011111100111111" \
      yellow="0000000000000000"/>
   <phase duration="4" phase="0000000000000000" brake="1111111111111111" \
      yellow="1100000011000000"/>
</tl-logic>

After you have defined a tls program, you can add it to one of your additional files. You may load several programs for a single tls into the simulation. The program loaded as last will be used (unless not defined using a WAUT description, see below). Please remark, that all subkeys of your programs must differ if they describe the same tls.

Recent changes:

	Caution
	Please keep in mind that this feature is quite new and that du to this some things may not work as suspected and may get changed in the near future.

In the reality, a tls often uses different programs during a day and maybe also for weekdays and for the weekend days. Since version 0.9.4 you can define switch times between the programs using a WAUT (I am very sorry, but I do not know the English word for WAUT - this may be a matter of change).

Let's assume we would have a tls which knows four programs - two for weekdays and two for weekend days where from 22.00 till 6.00 the night plan shall be used and from 6.00 till 22.00 the day plan. We'll give these programs the names "weekday_night", "weekday_day", "weekend_night", "weekend_day". To describe the switch process, we have to describe the switch at first, assuming our simulation runs from monday 0.00 (second 0) to monday 0.00 (second 604800):

<WAUT refTime="0" id="myWAUT" startProg="weekday_night">
   <wautSwitch time="21600" to="weekday_day"/>    <!-- monday, 6.00 -->
   <wautSwitch time="79200" to="weekday_night"/>  <!-- monday, 22.00 -->
   <wautSwitch time="108000" to="weekday_day"/>   <!-- tuesday, 6.00 -->
... further weekdays ...
   <wautSwitch time="453600" to="weekend_day"/>   <!-- saturday, 6.00 -->
... the weekend days ...
</WAUT>

The fields in WAUT have the following meanings:

and the fields in wautSwitch:

Of course, programs with the used names must be defined before this definition is read. Also, the time must be sorted.

Additionally, we have to define which tls shall be switched by the WAUT. This is done as following:

<wautJunction wautID="myWAUT" junctionID="RCAS" [procedure="Stretch"] [synchron="t"]/>

Here, the attributes have the following meaning:

You may assign several tls to a single WAUT. YOu may also assign several WAUTs to a single junction in theory, but this is not done in reality. The switching procedures are currently under development.

Recent changes:

	Caution
	Please keep in mind that this feature is quite new and that du to this some things may not work as suspected and may get changed in the near future.

A "closing_reroute" forces the rerouter to close the edge <EDGE_ID>. Vehicles which normally would pass this edge will get a new route as soon as they reach one of the edges given in the objectid-attribute of the rerouter's declaration. A definition may look like this:

<rerouter>
   <interval begin="<BEGIN_TIME>" end="<END_TIME>"/>
      <closing_reroute id="<EDGE_ID>"/>
   </interval>

   ... further intervals ...

</rerouter>

The attributes used within such definitions are:

A "dest_prob_reroute" forces the rerouter to assign a new route to vehicles which pass one of the edges defined in the objectid-attribute of the rerouter's declaration. A new route destination is used, defined by the name of a new destination in the according element:

<rerouter>
   <interval begin="<BEGIN_TIME>" end="<END_TIME>"/>
      <dest_prob_reroute id="<EDGE_ID1>" probability="<PROBABILITY1>"/>
      <dest_prob_reroute id="<EDGE_ID2>" probability="<PROBABILITY2>"/>
   </interval>

   ... further intervals ...

</rerouter>

The route is computed automatically using the Dijkstra-algorithm and starting at the edge the vehicle is located at and ending at the new destination.

The attributes used within such definitions are:

A "route_prob_reroute" forces the rerouter to assign a new route to vehicles which pass one of the edges defined in the objectid-attribute of the rerouter's declaration. In this case, the id of a complete route shall be supplied instead of a new destination:

<rerouter>
   <interval begin="<BEGIN_TIME>" end="<END_TIME>"/>
      <route_prob_reroute id="<ROUTE_ID1>" probability="<PROBABILITY1>"/>
      <route_prob_reroute id="<ROUTE_ID2>" probability="<PROBABILITY2>"/>
   </interval>

   ... further intervals ...

</rerouter>

The attributes used within such definitions are:

A vehicle class is made up of two parts. The first part describes to what kind of an authority the vehicle belongs. The next table shows what kind of authorities are defined currently:

The second part describes the kind of the vehicle. Currently possible values are shown within the next table:

Please remark that both the authority descriptions and kind descriptions are only names, no model is stored behind them. By defining a vehicle type as "pedestrian" you will not get a person walking within the simulation - currently pedestrian are not modeled anyway. These values simply name possible types of vehicles found on a network to allow closing/opening lanes or edges for them currently.

Roads/lanes are normally marked to allow/disallow a certain vehicle class while building the network using NETCONVERT. This process is described in chapter "Defining allowed Vehicle Types".

You can assign a vehicle class to a vehicle by extending this vehicle's vehicle type. Assume you want to set a vehicle as being of the class "bus". A vehicle type definition could look like this:

    <vtype id="BUS" accel="2.6" decel="4.5" sigma="0.5" length="15" maxspeed="70"
            color="1,1,0" vclass="public_bus"/>