SUMO
Simulation of Urban MObility

- Home
- Download
- Documentation
- Wiki
- Trac
- Blog
- Contact
- SF-Project

# Demand/Activity-based Demand Generation

ActivityGen generates demand from a description of the population in the net. To do so, it uses a simple activity-based traffic model. It supports the activities work, school, and free time and the conveyances walking, bike, car, and bus. Cars may have their start or stop location outside the map.

## Typical Command Line

    activitygen --net-file <NET> --stat-file <STATISTICS> --output-file <ROUTES> --random

<NET> is a map in form of a SUMO net file, <STATISTICS> contains the description of the population (described below), and <ROUTES> is the generated SUMO routes file (the demand).

You can give ActivityGen a first try with the following example.

## Example

While activitygen has been developed mainly to generate traffic demand for larger networks, this example features the small network shown in the image on the right. Download the files activitygen-example.net.xml and activitygen-example.stat.xml to follow this example.

To run this example, use the following commands:

    activitygen --net-file activitygen-example.net.xml \
                --stat-file activitygen-example.stat.xml \
                --output-file activitygen-example.tmp.rou.xml \
                --random

    duarouter --net-file activitygen-example.net.xml \
              --route-files activitygen-example.tmp.rou.xml \
              --output-file activitygen-example.rou.xml \
              --remove-loops --ignore-errors --repair

    sumo --net-file activitygen-example.net.xml \
         --route-files activitygen-example.rou.xml

The first command generates the net file from the node and edge description. The second command generates the routes file (the demand) from a description of the population in the stat file. The generated routes are incomplete though. This will be changed in the coming weeks, but it allows you to choose the router you want for linking departure and destination edges. To use the SUMO's standard Dijkstra algorithm, you need to repair the route file executing the third command. Finally, you can run a traffic simulation with the SUMO main executable.

## The Statistics File

### General information

First of all we need general information over the city.

    <city>
        <general
            inhabitants="1000"
            households="500"
            childrenAgeLimit="18"
            retirementAgeLimit="65"
            carRate="0.58"
            unemploymentRate="0.05"
            footDistanceLimit="350"
            incomingTraffic="200"
            outgoingTraffic="50"
        />
    </city>

The meanings of all these attributes are described in the following table:

Attribute Name | Value Type | Description
--- | --- | ---
inhabitants | Integer | Total number of inhabitants
households | Integer | Total number of households (must be between 0.5 and 1 times the number of adults of the city)
childrenAgeLimit | Integer | Age under which people are children. This is the first year of adulthood
retirementAgeLimit | Integer | Age under which people can have children home and work
carRate | Float[0;1] | Probability for an adult to own a car
unemploymentRate | Float[0;1] | Probability for an adult in age of work to be unemployed
footDistanceLimit | Float | Maximum distance one would go by foot instead of another transportation mean.
incomingTraffic | Integer | Number of people coming everyday into the city for they work
outgoingTraffic | Integer[0,inhabitants] | Number of inhabitants working outside the city

### Parameters

These entries are different from the general information element in what they describe. They depend much more of the special context or state of the city (events, behaviour of the population...). They can also be useful for optimization: the mean speed can be observed afterwards; all values can be changed in order to meet validation criteria on the traffic.

    <city>
        <general ... />
        <parameters
            carPreference="0.50"
            meanTimePerKmInCity="360"
            freeTimeActivityRate="0.15"
            uniformRandomTraffic="0.20"
            departureVariation="120"
        />
    </city>

The meanings of all these attributes are described in the following table:

Attribute Name | Value Type | Description
--- | --- | ---
carPreference | Float[0;1] | Probability that an adult prefers to take his car instead of a public transportation mean (when both available); default: 0.
meanTimePerKmInCity | Integer(sec) | Estimation of the time needed to drive one kilometer (bird's eye) on the map; default: 360s.
freeTimeActivityRate | Float[0;1] | Probability that a given household, a given day, has a free time activity using a car; default: 0.15.
uniformRandomTraffic | Float[0;0.999] | Proportion of the random traffic demand in the whole traffic demand; default: 0.
departureVariation | Float(sec) | Variance of the normal distribution introduced for slight variations in departure time (human natural variation in relation to schedules); default: 0.

### Population's Age Brackets

In order to distribute the population among households and in the city coherently, we need a precise age distribution of this population.

    <city>
        <general ... />
        <parameters ... />

        <population>
            <bracket beginAge="0" endAge"4" peopleNbr="1745" />
             ...
            <bracket beginAge="66" endAge"90" peopleNbr="978" />
        </population>

    </city>

Follows the description of all bracket attributes.

Attribute Name | Value Type | Description
--- | --- | ---
beginAge | Integer | Beginning age of the interval (incl.). If this is not the first bracket, this age is greater or equal to the previous bracket's ending age
endAge | Integer | End age of the interval (excl.). This age is greater to the current bracket's Beginning age
peopleNbr | Integer | Number of people in the interval age of the bracket ([beginAge,endAge)). This is an relative value, it will be normalized with the number of inhabitants of the city

### Work Hours

We need to specify the opening and closing hours of all city's work positions.

    <city>
        <general ... />
        <parameters ... />
        <population> <bracket ... /> ... </population>

        <workHours>
            <opening hour="30600" proportion="0.30" />
             ...
            <closing hour="43200" proportion="0.20" />
             ...
        </workHours>

    </city>

Here are descriptions of all attributes of opening and closing elements:

Attribute Name | Value Type | Description
--- | --- | ---
hour | Integer(sec) | Possible beginning or ending time of work.
proportion | Float | Proportion of work positions having this time as a beginning (resp. end) hour. It's a relative value: the probability of occurrence is computed by normalizing all opening (resp. closing) proportion values by one.

### Population and Work Position Distribution

Now, we have to specify the density of people and work in each street of the city. (by street I meant edges which are even more precise)

    <city>
        <general ... />
        <parameters ... />
        <population> <bracket ... /> ... </population>
        <workHours> <opening ... /> ... <closing ... /> ... </workHours>

        <streets>
            <street edge="abc123" population="2.5" workPosition="10.0" />
             ...
        </streets>

    </city>

Here are the corresponding attribute descriptions:

Attribute Name | Value Type | Description
--- | --- | ---
edge | String | Edge's id
population | Float | Number of people per meter street. Relative value (normalized with the total number of inhabitants)
workPosition | Float | Number of work positions per meter street. Relative value (normalized with the total number of city's work demand)

### City Gates

In order to generate incoming and outgoing traffic, we need to specify gates to the city. Every gate will generate the same number of incoming (resp. outgoing) cars (the total number divided by the number of gates).

    <city>
        <general ... />
        <parameters ... />
        <population> <bracket ... /> ... </population>
        <workHours> <opening ... /> ... <closing ... /> ... </workHours>
        <streets> <street ... /> ... </streets>

        <cityGates>
            <entrance edge="abc123" pos="243.67" incoming="1.5" outgoing="2.2"/>
            <entrance edge="abc234" pos="0.00" incoming="1.0" outgoing="0.5"/>
             ...
        </cityGates>

    </city>

The corresponding attribute descriptions:

Attribute Name | Value Type | Description
--- | --- | ---
edge | String | Edge's id
pos | Float (m) | Exact position in the street (edge), in meters, from the beginning of the given edge (the maximum value is the length of the edge)
incoming | Float | Proportion of the incoming vehicles, coming through this gate (relatively to the incoming values of the other gates)
outgoing | Float | Proportion of the outgoing vehicles, leaving the city through this gate (relatively to the outgoing values of the other gates)

### Schools

Children don't go to work but to school. The particularity of schools is that they are exactly positioned and receive many pupils every day.

    <city>
        <general ... />
        <parameters ... />
        <population> <bracket ... /> ... </population>
        <workHours> <opening ... /> ... <closing ... /> ... </workHours>
        <streets> <street ... /> ... </streets>
        <cityGates> <entrance ... /> ... </cityGates>

        <schools>
            <school edge="123abc" pos="23.0" beginAge="12" endAge="18" capacity="400" opening="32400" closing="64800" />
             ...
        </schools>

    </city>

The corresponding attribute descriptions:

Attribute Name | Value Type | Description
--- | --- | ---
edge | String | Edge's id
pos | Float (m) | Exact position in the street (edge), in meters, from the beginning of the given edge (the maximum value is the length of the edge)
beginAge | Integer | Age of the youngest pupils of the school (lower bound, included in the bracket of acceptance)
endAge | Integer | Age of children not accepted in the school any more (higher bound, excluded from the bracket of acceptance)
capacity | Integer | Maximum number of pupils accepted
opening | Integer (sec) | Time of class beginning (school time)
closing | Integer (sec) | Time of class ending (home time)

### Bus Lines

People have a public bus line system to their disposition. This public transportation system is described by stations, different bus lines having their corresponding station for both directions and schedules.

    <city>
        <general ... />
        <parameters ... />
        <population> <bracket ... /> ... </population>
        <workHours> <opening ... /> ... <closing ... /> ... </workHours>
        <streets> <street ... /> ... </streets>
        <cityGates> <entrance ... /> ... </cityGates>
        <schools> <school ... /> ... </schools>

        <busStations>
            <busStation id="1" edge="abc123" pos="456" />
            <busStation id="2" edge="123cba" pos="324" />
             ...
        </busStations>

        <busLines>
            <busLine id="601" maxTripDuration="3000">
                <stations>
                    <station refId="1" />
                     ...
                </stations>
                <revStations>
                    <station refId="2" />
                     ...
                </revStations>
                <frequencies>
                    <frequency begin="10000" end="25000" rate="1500" />
                     ...
                </frequencies>
            </busLine>
        </busLines>

    </city>

The corresponding attribute descriptions of all elements:

Attribute Name | Value Type | Description
--- | --- | ---
id | String | Bus line's id
maxTripDuration | Integer (sec) | Maximum time needed for a bus to do the end-to-end trip.
refId | Integer | Reference to the id of the chosen station (refers to a busStation object's id)
begin | Integer (sec) | Time of the beginning of a new frequency
end | Integer (sec) | End time of the frequency
rate | Integer (sec) | Time between two buses, this is the inverse of the mathematical frequency. This bus rate is performed between the beginning and end values described above

### Final Aspect

Here is a complete example of a stat file:

    <city>
        <general inhabitants="45774" households="28200" childrenAgeLimit="18" retirementAgeLimit="65" carRate="0.58"
            unemploymentRate="0.05" footDistanceLimit="500" incomingTraffic="1500" outgoingTraffic="3000" />

        <parameters carPreference="0.50" meanTimePerKmInCity="360" freeTimeActivityRate="0.15"
            uniformRandomTraffic="0.20" departureVariation="120" />

        <population>
            <bracket beginAge="0" endAge="30" peopleNbr="1765" />
            <bracket beginAge="30" endAge="75" peopleNbr="1290" />
        </population>

        <workHours>
            <opening hour="30600" proportion="0.30" />
            <opening hour="32400" proportion="0.70" />
            <closing hour="43200" proportion="0.20" />
            <closing hour="63000" proportion="0.20" />
            <closing hour="64800" proportion="0.60" />
        </workHours>

        <streets>
            <street edge="-2779#2" population="4.0" workPosition="2.0" />
            <street edge="-2776#0" population="3.5" workPosition="2.5" />
            <street edge="-2950#15" population="1.3" workPosition="0" />
        </streets>

        <cityGates>
            <entrance edge="-2950#15" pos="0.0" />
        </cityGates>

        <schools>
            <school edge="-2779#2" pos="23" beginAge="12" endAge="18" capacity="400" opening="32400" closing="64800" />
            <school edge="-2779#2" pos="23" beginAge="3" endAge="12" capacity="150" opening="30600" closing="64800" />
            <school edge="-2776#0" pos="765" beginAge="0" endAge="6" capacity="245" opening="32400" closing="61200" />
        </schools>

        <busStations>
            <busStation id="1" edge="-2779#2" pos="456" />
            <busStation id="2" edge="-2776#0" pos="324" />
            <busStation id="3" edge="-2950#15" pos="233" />
        </busStations>

        <busLines>
            <busLine id="601" maxTripDuration="3000">
                <stations>
                    <station refId="2" />
                    <station refId="1" />
                </stations>
                <revStations>
                    <station refId="1" />
                    <station refId="2" />
                </revStations>
                <frequencies>
                    <frequency begin="21600" end="64800" rate="1200" />
                    <frequency begin="64800" end="84600" rate="1800" />
                </frequencies>
            </busLine>
        </busLines>
    </city>

## Activities

ActivityGen takes into account two groups of activities, which are considered as most traffic-relevant: Work And School and Free Time. The activities within each group follow the same statistical rules.

### Work and School Activities

This aggregate of activities contains the following activities:

1. Going to work for adults (not retired), and
2. Going to school for children.

That implies trips from home to work and the return trip for the drivers.

### Free Time Activities

This aggregate of activities contains the following activities:

1. Going out during the day (for retired or unemployed people)
2. Going out in the evening (for all people who finished their work activity not too late)
3. Going out late in the evening or in the night (for not retired adults having no children)

This activity is supposed to cover all car uses for:

- Going out see friends
- Doing sport
- Visiting family
- Party

## Transportation Means

The population is distributed according to the statistics into households located in streets. People are likely to use different means of transportation in relation to their location, the availability of the different means and their destination. Three kind of Means are used in ActivityGen:

- Feet or bike
- Buses
- Cars

All of them have their own possibilities and availability characteristics:

### Feet or Bike

Trips by foot are available only for very short distances. But in this case, the person is very likely to go by foot. The bike isn't really used (buses and cars are preferred), it is supposed to serve in cases where none of the three means (Feet, buses and cars) are not available

### Buses

Bus stations are located in the city corresponding to the real bus line network given in input (statistical data over the city). Someone enough close to a bus station and whose destination is enough close to another bus station is eligible for the public transportation means.

### Cars

Householders having one or more cars can drive (not children) or be accompanied (escorted) by another adult who needs a car too. Children can only be accompanied (to school for example). Some households have no car, in this case they have to live enough close to a bus station. In the case of having a destination far from any bus station, they can go by foot or ride a bike. But this case doesn't generated any motorized vehicle traffic.

This page was last modified on 24 August 2012, at 12:12.