"Modules"

Modules are loosely defined by their corresponding entry in the config file. 

They are also sorted in the same sequence (which is done by the machine, not by content).

Note that individual config options are often explained inside the config section of the log file.

Config file modules that just define files/directories are, as a tendency, not explained here.

Note that strategy modules (such as ReRoute, Planomat) are described in a separate section.

Maintainers are mentioned as far as possible, but they are not responsible for answering arbitrary service requests.

"controler" (indispensable)

Maintenance and Questions

Marcel Rieser, senozon AG (rieser_at_senozon.com)

Javadoc

www.matsim.org/javadoc/org/matsim/core/controler/package-summary.html

Config Parameters

www.matsim.org/javadoc/org/matsim/core/controler/package-summary.html#controler_parameters

In Brief

Central module to run matsim.  Specifies, for example, the number of iterations.

Notes

See here for some instructions how to use an external executable as mobsim.

"counts". Status: works for vsp and ivt

Maintenance and Questions:

A. Horni, IVT (horni_at_IVT.baug.ethz.ch)

Javadoc:

www.matsim.org/javadoc/org/matsim/counts/package-summary.html

Config Parameters

www.matsim.org/javadoc/org/matsim/counts/package-summary.html#counts_parameters

In Brief:

MATSim can compare the simulated traffic volumes to traffic counts from the real world. Counts is the module that allows to

  • read some external file with traffic flow counts
  • compare them automatically to the counts generated inside the matsim simulation
  • submit the result to a kmz file which can be displayed inside google earth

There is a feature to re-scale the counts before comparison (for example if you are running the simulations with a 10% sample).

Comparison Data

Prepare a file containing the real-world traffic counts. The file, e.g. named counts.xml, must follow the xml-format defined in counts_v1.xsd. An example of such a file can be found in MATSim at examples/equil/counts100.xml.

The file contains the following information:

  • For each link in the network for which traffic count information is available, a count-element must exist. The count-element specifies the link it refers to in its attribute loc_id. In addition, an optional cs_id can be stored that may, for example, refer to the original id of the counting station (for tracking back the origin of the data).
  • In each count-element, 1 to 24 volume-elements can appear. Each volume-element contains the measured traffic count (attribute "val") for an hour of the day (attribute "h", numbered from 1 to 24; 1 = 00:00-00:59, 2 = 01:00-01:59, etc). It is not necessary that traffic counts are available for all 24 hours of a day.

Enabling Comparison in Configuration File

Add the following lines to your configuration file:

<module name="counts">
  <param name="inputCountsFile" value="/path/to/counts.xml" />
  <param name="outputformat" value="txt,html,kml" />
</module>

The comparison is automatically generated every 10th iteration. Generated output is located in the output-directory of the iteration (usually something like output/ITERS/it.10/).

Configuring the Counts Comparison

The counts-module offers the following config-parameters:

  • <param name="outputformat" value="txt,html,kml" />
    The output format specifies in which format the comparison results are written to disk. It can be any combination of txt, html and kml. Multiple formats can be specified separated by commas. txt writes simple text-tables containing the values to a file. It is most useful to create custom graphs, e.g. in Excel. html creates a directory containing several html files, allowing to browse the results interactively. kml creates a file to be displayed in Google Earth. This last option only works if the correct coordinate system is set.
  • <param name="countsScaleFactor" value="1.0" />
    If you only simulate a sample of your population, the simulated traffic volumes are likely lower than the real-world traffic counts. In order to allow useful comparison, one can specify a factor by which the simulated traffic volumes are multiplied. For example, if you simulate a 25% sample of your full population, specify a countsScaleFactor  of 4.
  • <param name="distanceFilterCenterNode" value="2386" />
    <param name="distanceFiler" value="30000.0" />
    If the traffic counts cover a larger area than the area being simulated, the traffic counts outside your area will result in a bad comparison. Instead of removing the traffic counts from the counts.xml, you can specify a filter to only include some traffic counts from the file in the comparison. To activate the filter, specify the id of a node that acts as the center of a circle. The circle has the radius specified in "distanceFilter", the unit being the same unit as the length of links (i.e. usually meters).

 

"evacuation"(-ivt). Status: ??

Evacuation code used by IVT; please note that IVT and VSP use different evacuation codes.

Maintained by C. Dobler.

I (kn) don't know how this works

"evacuation"(-vsp). Status: works if you know what you are doing

(Note that VSP and IVT use different evacuation packages.)

Maintenance and Questions

G. Lämmel, TU Berlin

Javadoc

http://www.matsim.org/javadoc/org/matsim/evacuation/package-summary.html

Config Parameters

http://www.matsim.org/javadoc/org/matsim/evacuation/package-summary.html#evacuation_parameters

In Brief

I (kn) can't say how this works.  There is, at this point, neither documentation nor funding.

"facilities". Status: "user" version work in progress

Maintainer: Andreas Horni

One may, or may not, use a separate file that contains "facilities" – essentially some kind of land use information.

The prototype for this is fairly old.  But the final design is somewhat different, and has not been fully executed.  So I (kn) do not know if this can currently be used as a non-developer.

"global". Status: indispensable

"Maintainer": Marcel Rieser

"Global" information. Arguably should be merged with "controler" section.

"households". Status: probably ready but nowhere used

Maintainer: Christoph Dobler

An option to read a households file into matsim.

I (kn) don't know the exact status.

"JDEQSim". Status: works for ivt

Maintainer: Rashid Waraich

Overview

JDEQSim (Java Deterministic Event Driven Queue Based Simulation) has the following properties and features:

  • it is based on a discrete event simulation model
  • traffic simulation is based on a queue model for streets (FIFO: first in first out)
  • deadlock prevention is achieved by squeezing vehicles
  • gaps generated at front of queue propagate backwards with a speed called 'gapTravelSpeed' resulting in a more realistic traffic model

Usage

Insert a new module called 'JDEQSim' into the config XML file. All parameters are optional and have default values (shown below), never the less it could be helpful to know their meaning and physical units.

	<module name="JDEQSim">
		<param name="endTime" value="00:00:00"   />
		<param name="flowCapacityFactor" value="1.0"   />
		<param name="storageCapacityFactor" value="1.0"   />
		<param name="minimumInFlowCapacity" value="1800"   />
		<param name="carSize" value="7.5"   />
		<param name="gapTravelSpeed" value="15.0"   />
		<param name="squeezeTime" value="1800"   />
	</module>
The mobsim type now also needs to be defined in the controler section of the config file.  See comments in config dumps in logfiles.

The 'endTime' defines the time of the last event of the simulation. If it is set to '00:00:00', no end time is defined and the simulation will stop, when the last event of the simulation has been processed. The (scaling) parameters  'flowCapacityFactor' and 'storageCapacityFactor' can be used as with mobSim and have no unit. The 'minimumInFlowCapacity' defines for all roads the minimum number of cars, which could enter the road per hour, for the congestion less case. The 'carSize' parameter allows to set the size of a car in meters. The 'gapTravelSpeed' parameter defines the speed of gaps in [m/s]. Finally the 'squeezeTime' is used for deadlock prevention and defines, how long a car should wait at maximum for entering the next road before deadlock prevention is turned on (unit: seconds).

The 'minimumInFlowCapacity' is a parameter, which was not published in the C++ DEQSim, but only used interally and was hardcoded to the value 1800 vehicles per hour. This value was estimated from literature assuming that independently from the speed limit of a road the minimum interval between two vehicles is 2 seconds (inverse of 1800 vehicles per hour). This factor does not need to be changed, when the 'flowCapacityFactor' is changed, as the scaling is automatically done internally. The reason for publishing this factor is to make it possible for users to adapt this factor, if they want to use a different minium inflow capacity based on their model estimations.

Hints

  • If the module 'JDEQSim' is present all parameters from module 'simulation' are ignored. [[Given that the type of the mobsim now needs to be specified in the controler section of the config file, this works differently now.  kai, apr'11]]
  • You might consider turning on the module 'parallelEventHandling' when using JDEQSim, as often JDEQSim can make much better use of this module than QueueSim (as JDEQSim is faster).
  • Use the the following controller for running the java DEQSim micro-simulation: org.matsim.controler.Controler (and not org.matsim.mobsim.cppdeqsim.DEQSimControler, which is used for C++ DEQSim)
  • If you are getting lots of breakdowns, consider using smaller squeezeTime (e.g. 10 seconds or lower)

Requirements for the Plans XML File

  • For each person the 'end_time' of the first act must be defined ('dur' is ignored).
  • For the other acts of a person either 'dur' or 'end_time' needs to be defined
  • If both 'dur' and 'end_time' are defined, then only the one which occurs earlier is considered

Details of the Model

Difference between MobSim and JDEQSim

  • QueueSim uses a simulation approach called 'fixed-increment time advance' instead of 'next-event time advance', which makes it much slower than JDEQSim for high resolution networks.
  • JDEQSim allows squeezing of vehicles to resolve possible deadlocks. Deadlock prevention in QueueSim is (traditionally) dealt with by removing vehicles from the network or squeezing.
  • JDEQSim models gap travel times more realistically than QueueSim, where this feature is missing.

 

Further Reading

This implementation is based on the micro-simulation described in the following paper:

Charypar, D., K. Nagel and K.W. Axhausen (2007) An event-driven queue-based microsimulation of traffic flow, Transportation Research Record, 2003, 35-40.Order here.

Some Java specific implementation aspects and performance tests of JDEQSim and parallelEventHandling are described in the following paper:

Waraich, R.,  D. Charypar, M. Balmer and K.W. Axhausen (2009) Performance improvements for large scale traffic simulation in MATSim, paper presented at the 9th Swiss Transport Research Conference, Ascona, September 2009. Download from here.

 

 

 

 

 

 

 

 

"network" (time dependent). Status: works for vsp

Maintenance: G. Lämmel, VSP

MATSim provides the opportunity to model time dependent aspects of the network explicitly. For each link in the network basic parameters (i.e. freespeed, number of lanes and flow capacity) can be varied over the time. So it is possible to model accidents or the like. One particular area for this technique is the modeling of evacuation scenarios.
In the case of an evacuation simulation the network has time dependent attributes. For instance, large-scale inundations or conflagrations do not cover all the endangered area at once.
In MATSim this time varying aspects are modeled as network change events. A network change event modifies parameters of links in the network at predefined time steps. The network change events have to be provided in a XML file to MATSim.

A sample network change event XML file  could look like:

<?xml version="1.0" encoding="UTF-8"?>
<networkChangeEvents xmlns="http://www.matsim.org/files/dtd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.matsim.org/files/dtd http://www.matsim.org/files/dtd/networkChangeEvents.xsd">
  <networkChangeEvent startTime="03:06:00">
        <link refId="12487"/>
        <link refId="12489"/>
        <link refId="12491"/>
        <freespeed type="absolute" value="0.0"/>
  </networkChangeEvent>
</networkChangeEvents>

This change event would set the freespeed of the links 12487, 12489, 12491 to 0 m/s at 03:06 am (all values have to be provided in SI units). These values are valid until the next network change event (if there is any) changes the freespeed of link 12487, 12489, 12491 again. In this example the freespeed would be set to an absolute value. It is also possible to take the old freespeed value and multiply it by a factor. For dividing the old freespeed value by 2, the corresponding line of the network change event XML file would look like:
            <freespeed type="scaleFactor" value="0.5"/>
Besides changing the freespeed, one could also change the number of lanes:
            <lane type="absolute" value="2.0"/>
Or the flow capacity:
            <flowCapacity type="absolute" value="0.0"/>

To make use of the network change events one has to define it in the MATSim config file. Therefore the following two lines have to be added in the network section of the config file:
<param name="timeVariantNetwork" value="true" />
<param name="inputChangeEventsFile" value="path_to_ change_events_file" />

Now one has just to start the controller with this config file and the network change events will be applied automatically.

It seems that the ``absolute'' version of this module was never tested (and may not work) with freespeeds other than zero.  kai, oct'10

 

"parallelEventHandling". Status: works for ivt and vsp

Maintainer: Rashid Waraich

see details here.

 

"planCalcScore". Status: nearly indispensible

Maintainer: Marcel Rieser

This module contains the definitions for the utility function.

Some help for it should be in the tutorials.

There is also some description in the "scoring function" section of the documentation.

"qsim" (parallel version). Status: looks promising

Responsible: C. Dobler, IVT

Analysis of performance and structure of (non parallel) QueueSim shows:

  • Simulation of movement on links and over nodes is most time consuming.
  • Within a timestep actions on nodes and links can be simulated on parallel threads with low additional synchronization effort.

The parallel QueueSim is based on the existing QueueSim and can be used by just adding a new parameter to a scenario configuration file (see below).

First performance measurements show promising results.

Working paper will be published in Q2 2010.

 

The config option presumably is:

<module name="qsim">
   ...
   <param name="numberOfThreads" value="5"/>
</module>

Any number of threads larger than one triggers the use of the parallel version. (??)

"qsim". Status: works but is not very transparent

If you do not put a "qsim" section into the config file, the system will use the default "simulation" (look there).

"qsim" is what we use for new features such as public transit or signalsystems.  "New features" implies "unstable".  Use only if you have to.

Also see www.matsim.org/javadoc/org/matsim/ptproject/qsim/package-summary.html

Some calibration hints, especially when the main mode is not "car"

The (exit) flow capacity of a link is:

capacity_value_of_link / capacity_period_of network * flow_capacity_factor

where

  • the capacity value of the link is given by the link entry in the network file
  • the capacity period of the network is given at the beginning of the "links" section in the network file.  Normally set to one hour
  • the flow capacity factor is given in the qsim config group

The storage capacity of a link is:

(length_of_link * number_of_lanes_of_link / effective_cell_size) * storage_capacity_factor

where

  • the length of the link is given by the link entry in the network file
  • the number of lanes of the link is given by the link entry in the network file
  • the effective cell size is given at the beginning of the "links" section in the network file.  Normally set to 7.5m
  • the storage capacity factor is given in the qsim config group
  • There is also an effective lane width, also at the beginning of the "links" section in the network file, normally set to 3.75m.  See below for its use.

This is most useful if you have something else than cars, for example pedestrians.  Let us assume an effective lane with of 0.4m and an effective cell size also of 0.4m.  This would lead to a maximum density of 0.4*0.4=0.16persons/m^2, not totally unrealistic.

If, now, a link has an area of 200m^2 and a length of 50m, then it would obtain

number_of_lanes = area / length / effective_lane_width = 200 / 50 / 0.4 = 10

Note that, in the end, the lane width is not used by the dynamics; all the meaning is subsumed in the number of lanes.  The storage capacity comes out as

storage_capacity = number_of_lanes * length / effective_cell_size

in the above example

= 10 * 50 / 0.4 = 1250 .

This is, naturally, the same as dividing the 200m^2 of the link by the 0.16persons/m^2.

The effective lane width might be used by the visualization (unclear if this is the case).

"signalsystems". Status: works for vsp

Maintainer: Dominik Grether

The signal systems module provides functionality to simulate traffic lights with MATSim. It is recommended to use a nightly build that is younger than 04-19-2011, i.e. revision 15081.

The starting point of the documentation is

Note that there are links to continuative documentation at the bottom of the package-summary.html www page.

Nightly builds younger than 04-21-2011 contain a tutorial that shows you how to set up a traffic light scenario. The network and traffic light configuration of the turorial is shown in the slides attached to this page. The network and code can be found in the folder tutorial/unsupported/example90TrafficLights in the nightly build. The code examples are divided into several classes:

  • CreateSimpleTrafficSignalScenario.java: Uses traffic signals without lanes and creates the traffic lights at nodes 3, 4, 7 and 8.
  • CreateTrafficSignalScenarioWithLanes.java: Uses traffic signals with lanes and creates the traffic lights at nodes 2 and 5.

 

Publications using this module:

This documentation is missing an explanation of the "lanes" option.  Please ask if you need this (separate "lanes" for separate turning movements).

 

"simulation". Status: should work

This was essentially the production of the queue simulation until Nov/2010. The "qsim" was then forked out for further development. Unfortunately, this fork was done somewhat too late, so "simulation" is not exactly the stable version that was used over many years, but something that is already somewhat modified, and was not used very much after that.  (Please let us know if you have problems.)

Note that you will get a "simulation" section in the log file even if you have selected a different mobsim (such as qsim or jdqsim).

There used to be an option to start an external mobsim.  This still seems to be there but the syntax is a bit awkward:

<module name="controler" >
   ...
   <param name="mobsim" value="null" />
</module>
<module name="simulation" >
   <param name="externalExe" value="<path-to-executable>" />
</module>

I.e. you need to specify that you are not using the (queue)Simulation, but then set a parameter inside the (queue)Simulation config block.

"strategy". Status: indispensable

Maintainer: Marcel Rieser ("core")

See here.

"transit" (public transport). Status: works

A public transport system is simulated and integrated on a fine scale with both the traffic simulation and the behavior of the artificial population.

Agents who use transit determine a route to their destination based on the transit schedule. Transit vehicles are moved on the road network in accordance with the traffic flow model, i.e. they may get stuck in congestion and fail to keep their schedule. Agents getting on and off transit vehicles cause realistic delays.

A transport mode decision model is implemented which allows agents to switch their choice of driving a car or using transit based on the relative utility of the two modes. The disutility of travel time, which this model takes into account, is based on actual travel times taken from the simulation.

See the tutorial.  This requires quite some additional input.

Reference

M. Rieser, K. Nagel; Combined agent-based simulation of private car traffic and transit; IATBR 2009

"travelTimeCalculator". Status: nearly indispensable

Maintainer: Marcel Rieser ("core")

"router" and "travelTimeCalculator" are separate in matsim, so that they can be configured separately.  They refer to each other, though.

"vehicles". Status: probably reads the file correctly, but does nothing else

Maintainer: Michael Zilske (within limits of DFG/MUC project; possibly pt project)

"vspExperimental". Status: not meant for general use

This section defines switches that are used at VSP or when collaborating with VSP.  There are experimental and may we withdrawn without notice.

vsp defaults

I (kn) am in the process of defining some defaults that everybody at VSP should be using.  These can be switched on by:

<module name="vspExperimental" >
   <param name="vspDefaultsCheckingLevel" value="abort" />
   ...
</module>

This will make the code abort when these defaults are violated.

The number of vsp defaults will grow over time.  This may have the effect that some config file that used to be working for you in the past may not work any more after an svn update.  I will try to communicate such changes, but will sometimes fail to do so.  In any case, if you encounter an abort because of a vsp defaults violation, please

  • check what is causing the problem, and
  • enter the relevant config setting into all config files that you use.

If you think that you cannot live with these settings, please talk to me.

Since those settings involve all aspects of matsim, they may often be irrelevant to you.  Please set them anyways.

"withinday". Status: not ready

Maintainer: Christoph Dobler

There is no "withinday" section in the config file, so there shouldn't be an entry here. It is here for historical reasons.  Instead look here (note that this is in the "developer" section of the documentation, i.e. if you are not in the sourceforge playground, you will not get code that is stable from one matsim build to the next).

0 deprecated modules

Deprecated Modules

"world"

Dismantler: Michael Zilske

This was an attempt to integrate GIS functionality into matsim.

Has been superceeded by calls to geotools.  Please use geotools functionality.  Look under the demand generation tutorials for getting some ideas.

World also provides datastructures to assign facilities to links, and links to zones, etc. This functionality is mostly used in initial demand modelling, but is not very straight-forwardly implemented. Should be replaced in the future with some kind of "mappig manager" to manage the mappings between different MATSim objects, like facilities, links, etc.