Using MATSim for Switzerland

General remarks

This is material that was in the tutorial "Learning MATSim in 3 days".  We moved it to here, but did not check the content.

A. Horni: Shortly, there will be a working paper describing the usage of MATSim for Switzerland., 02.05.2011

Some data sources

• Microcensus (BfS): www.bfs.admin.ch/bfs/portal/de/index/themen/11/07/01/02/01.html
• Census (BfS): www.bfs.admin.ch/bfs/portal/en/index/infothek/erhebungen__quellen/blank/blank/vz/uebersicht.html
• ASTRA traffic counts: www.astra.admin.ch/verkehrsdaten/00299/00303/index.html
• Business census (BfS): www.bfs.admin.ch/bfs/portal/en/index/infothek/erhebungen__quellen/blank/blank/bz/01.html
• Border crossing traffic (IVT, BfS): www.bfs.admin.ch/bfs/portal/de/index/themen/11/07/04/blank/01/01.html

Using MATSim for Vancouver

There are many different ways to start a new MATSim scenario.  This is just one of them.  Ideally, they would be documented somewhere.  At this point, there is just this pointer to an (incomplete) Vancouver scenario.

All relevant info (not a lot) is now in src/playground/duncan .

No efforts have been made to include public transit.

Using MATSim from Urbansim (for the PSRC region)

Check out the opus source tree from www.urbansim.org .  (The source tree is the tree containing directories such as opus_core or opus_gui.)

In this source tree, there should be a directory opus_matsim .

There is documentation in opus_matsim/docs .

ReRoute. Status: nearly indispensable

Maintainer: Marcel Rieser

All routes of a plan are recomputed.

The module is called by inserting the following lines into the "strategy" module:

<module name="strategy" >
	<param name="ModuleProbability_XXX" value="0.1" />
	<param name="Module_XXX" value="ReRoute" />
                ...
</module>

The corresponding configuration module unfortunately has a different name:

<module name="planscalcroute" >
	<param name="beelineDistanceFactor" value="1.3" />
	<param name="bikeSpeed" value="4.166666666666667" />
	<param name="ptSpeedFactor" value="2.0" />
	<param name="undefinedModeSpeed" value="13.88888888888889" />
	<param name="walkSpeed" value="0.8333333333333333" />
</module>

This works pretty reliably for car. 

It also works for other modes, as "pseudo"-mode, in the following way:

• Travel times for these other modes are not obtained from true routing on the corresponding network, but by some estimates.  These are configured by the parameters above, but no guarantee that they work consistently.
• The mobsim will not execute such routes on the network, but "teleport" them.
• The scoring works quite normally, since it just takes the time from leg start to leg end by mode.

It is possible to route such legs on the network, by using a different router. 

It is not possible to "physically" execute a leg in the mobsim if it has not been routed before.  That is, the capability of the router needs to be >= the capability of the mobsim.  (Makes sense, if one thinks about it.)

TimeAllocationMutator. Status: works for vsp and ivt

Simple module that shifts activity end times randomly.  ("Good" time shifts will be selected through the matsim plans selection mechanism.)

The maximum extent of the shifts can be configured; see the config section of the log file.  It is, as of now (may'10), not possible to add a comment to that parameter.

The usage of the module is configured in the "strategy" section.

ChangeLegMode. Status: works

Maintainer: Michael Zilske

This replanning module randomly picks one of the plans of a person and changes its mode of transport. By default, the supported modes are driving a car and using public transport. Only one mode of transport per plan is supported. For using different modes for sub-tours on a single day see the "SubtourModeChoice" module.

The replanning module is configured like this, where the value parameter lists the modes of transport from which the module randomly chooses: 

<module name="changeLegMode">
   <param name="modes" value="car,pt" />
</module>

Add the module to the replanning strategy like this:

<param name="Module_X" value="ChangeLegMode" />
<param name="ModuleProbability_X" value="0.1" />

Replace the 'X' with the number you assign to this module. For some more details on the syntax of this section, see here.

By default, the simulation will handle legs with modes different from "car" by using a delayed teleportation. If another behavior is requested (e.g. detailed simulation of public transport), this needs to be manually configured for the simulation.

Reference

M. Rieser, D. Grether, K. Nagel; Adding mode choice to a multi-agent transport simulation; TRB'09 

LocationChoice. Status: ready

Maintenance and Questions

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

Javadoc

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

Config Parameters

www.matsim.org/javadoc/org/matsim/locationchoice/package-summary.html#locationchoice_parameters

Status

Ready

In Brief

MATSim provides destination choice based on three different basic concepts. First, random search can be applied. Second, local search implemented in the time geography framework is available [1]. Third, the most recent module ist best response and includes random error terms to make MATSim fully compatible with discrete choice theory [2]. The authors recommend to use this recent module in general. Random search should be utilized for algorithmic comparative investigations only.

The time geography module provides the possibility to take into account spatial competition in the activity location infrastructure (see Figure 3). It is planned-after a thorough calibration-to integrate spatial competition in the best response version.

Estimation of a MATSim destination choice utility function for Switzerland is in development [3].

Calling the Location Choice Strategy

The strategy module in the config file needs to be extended as follows:

<module name="strategy">
    ...
    <param name="ModuleProbability_X" value="0.0 < double <=1.0" />
    <param name="Module_X" value="LocationChoice" />
    ...
</module> 

I. Random Search

Due to slow convergence, this approach is only useful for very small scenarios.

II. Local Search With Time Geography

The MATSim local search destination choice module is based on Hägerstrand's time geography. That is, in every replanning step locations are chosen within the region restrained by travel time budgets as defined by the time allocation module (see Figure 1 and Figure 2). Within this region the choice is performed based on the MATSim utility function.

In more detail, the following procedure is iteratively applied. An approximate choice set of locations is built to begin with, where the constructing of this set is initially based on an initial global travel speed assumption (recursionTravelSpeed). After tentatively choosing one location from this approximate set, the actual accessibility in terms of travel time is checked. If the location is not accessible it is rejected, the initial travel time is adapted according to the recursionTravelSpeedChange parameter in the configuration file and a next trial is started. After a certain number of failed trials to find an accessible location (maxRecursions), the choice is made from the universal choice set.

The parameters recursionTravelSpeed, recursionTravelSpeedChange and maxRecursions are explained in Section Parameters

III. Best Response Including Random Error Terms

The parameters scaleEpsShopping and scaleEpsLeisure correspond to f_Shopping and f_Leisure in [2]. probChoiceSetSize is Φ. epsilonDistribution, tt_approximationLevel, maxDistanceEpsilon, and probChoiceExponent are explained in in Section Parameters.

The parameters scaleEpsShopping and scaleEpsLeisure can be calibrated, based on e.g., travel distance distributions as described in [2].

Spatial Competition: Facility Load Penalty Computation

Similar to route and time choice being influenced by the competition in transport infrastructure it can be expected that competition in activities infrastructure has an effect on destination choice. Consequently, the utility of performing an activity is dependend on the actual load of the activities infrastructure at least for some activities such as e.g., grocery shopping (e.g.; searching for a parking space or waiting time at cash points etc.). In MATSim spatial competition is taken into account, which has shown to reduce the number of implausibly overcrowded locations (see Figure 3 below).

The score for perfoming an activity is calculated as follows:

score  = (1- fp) * score_without_penalty

fp = Max(0.5, fcrf)

fcrf = restraintFcnFactor * [(facility load) / (facility capacity)] ^{^} restraintFcnExp

The parameters restraintFcnFactor and restraintFcnExp are explained in the section Parameters

Literature

[1] Horni, A., D.M. Scott, M. Balmer and K.W. Axhausen (2009) Location choice modeling for shopping and leisure activities with MATSim: Combining micro-simulation and time geography, Transportation Research Record, 2135, 87-95.

[2] Horni, A., K. Nagel and K.W. Axhausen (2011) High-Resolution Destination Choice in Agent-Based Demand Models, Arbeitsberichte Verkehrs- und Raumplanung, 682, IVT, ETH Zürich, Zürich.

[3] Horni, A., D. Charypar and K.W. Axhausen (2011) Empirically approaching destination choice set formation, paper presented at the 90^th Annual Meeting of the Transportation Research Board, Washington, D.C., January 2011.

Figures

Figure 1:

Figure 2:

Figure 3:

Planomat. Status: works for ivt

Maintenance

For questions, please contact:

Konrad Meister
IVT, ETH Zurich
email: meister (at) ivt.baug.ethz.ch

Description

The planomat is a stochastic best-reply replanning module for the activity durations and the departure times, as well as the mode choice on subtour level. On the one hand, this module replaces a simple random mutation module for departure times (the Time allocation mutator) with a genetic algorithm (GA) for daily plan optimization. This leads to a convergence of the MATSim learning framework within several dozens of iterations, independent of the departure times and activity durations in the initial demand (Meister et al., 2006). The choice of a GA makes it possible to include more plan variables into the optimization procedure. Currently it is possible to modify the mode of each subtour of the activity plan is varied besides the time information (unpublished, experiments documented in Meister, 2008). The mode choice set for each subtour may include modes whose travel times/costs can be estimated from events (typically "car") or directly from a routing algorithm, when events are not available, or the transport mode is not dynamic (typically "pt", "bike", "walk").

The optimal timing of the daily activity plan depends mainly on the travel times which the agents expects for a given leg. Just like in the router, and for reasons of simplicity, a travel time approximation based on global knowledge is assumed. The travel time will be estimated for the route that is given in the activity plan, which remains unchanged. For the “virtual” assessment of other modes of a given leg, the free-speed route for the respective mode is determined. The actual travel time on this route may still be time-dependent, as for the mode "car" in the application presented here.

The planomat replanning module was used in a large-scale study of agent-based travel demand optimization (Balmer et al., 2010).

Usage in MATSim

In order to use the planomat as a replanning module, activate it in the strategy section of the config xml file:

<module name="strategy">
  ...
  <param name="ModuleProbability_n" value="0.1" />
  <param name="Module_n" value="Planomat" />
  ...
</module>

• Replace n with the consecutive number of replanning/selection modules in the strategy section.

Without further settings, only time information (departure times, activity durations) will be modified and optimized. This is the default behavior, leg mode information will not be touched. In order to switch on mode choice optimization on the subtour-level, indicate the mode choice set in a separate config section with the name planomat:

<module name="planomat">
  ...
  <param name="possibleModes" value="car,pt" />
  ...
</module>

• The transport mode identifiers are determined by the MATSim API.
• The resulting plan will contain legs only with modes from the specified choice set. Any leg mode information that was previously present is deleted. For example, when the initial demand contained legs with mode "bike", this mode will not be present in the plan after it was processed by the planomat replanning module with the above setting.
• The same transport mode will be chosen for every leg of a subtour. See the algorithm for subtour identification here. Note that, up to now, mode choice does not interact between subtours. This might generate physically unfeasible mode chains (imagine a car leg from a location where the vehicle is not available). An algorithm for feasible mode chain analysis has been implemented (see here), but not yet integrated with the processing of the mode choice set.

The behavior of the planomat module can be controlled with several other configuration parameters. For example, set the maximum number of GA generations to a lower value of 10 than the default value of 100:

<module name="planomat">
  ...
  <param name="jgapMaxGenerations" value="10" />
  ...
</module>

For additional config parameters, their respective default values and the possible value ranges, please refer to the code at org.matsim.core.config.groups.PlanomatConfigGroup.class.

References

see hyperlinks in description.
 

SubtourModeChoice. Status: probably works

Maintainer: Michael Zilske

In contrast to "ChangeLegMode", which changes all legs of a plan to a different mode, this module changes the modes of sub-tours separately.

For example, somebody might take the car to work, walk to lunch and back, and take the car back home.

 "chainBasedModes" means modes where a vehicle (car, bicycle, ...) is parked and in consequence needs to be picked up again.

	<module name="subtourModeChoice" >
		<param name="chainBasedModes" value="car, bike" />
		<param name="modes" value="car, bike, pt, walk" />
	</module>

 The module is called by inserting the following lines into the "strategy" module:

	<module name="strategy" >
		<param name="ModuleProbability_XXX" value="0.1" />
		<param name="Module_XXX" value="SubtourModeChoice" />
                ...
        </module>

For modes other than car, travel time and travel distance are computed according to some heuristics, which are configured in the router.

"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 '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 9^th 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.

"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).

"roadpricing". Status: works for vsp

Maintainer: Michael Zilske

The roadpricing module provides functionality to simulate different road-pricing scenarios in MATSim.

Documentation can be found at:

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

Publications using this module:

• https://svn.vsp.tu-berlin.de/repos/public-svn/publications/vspwp/2007/07-14/
• https://svn.vsp.tu-berlin.de/repos/public-svn/publications/vspwp/2008/08-01/
• https://svn.vsp.tu-berlin.de/repos/public-svn/publications/vspwp/2008/08-08/
• https://svn.vsp.tu-berlin.de/repos/public-svn/publications/vspwp/2010/10-03/

"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

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

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:

• https://svn.vsp.tu-berlin.de/repos/public-svn/publications/vspwp/2008/08-24/
• https://svn.vsp.tu-berlin.de/repos/public-svn/publications/vspwp/2011/11-12/
• https://svn.vsp.tu-berlin.de/repos/public-svn/publications/vspwp/2011/11-08/

"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

Calibration of the scoring function

Simplified version

The simplified version assumes that all activities operate near their typical duration.  In that case (see here), one can approximate the marginal utility of activity duration (i.e. the marginal utility if the sum of all activities is extended by that amount of time) by beta_perf .

Now let us consider the typical changes (of the Vickrey scenario).  Note that in the Vickrey scenario, the meaning of the marginal utility of arriving earlier means the marginal contribution assuming that the travel time remains the same.  We will assume that activities are ended by the endtime attribute, not by the duration attribute.

Travel takes longer (by amount deltaTtime)

In that situation, the activity that follows the trip is cut short by deltaTtime.  We thus have the following (linearized) modifications of the utility:

• Travel takes longer by deltaTtime; the utility change is beta_travel * deltaTtime .  Note that beta_travel typically is negative.
• The following activity is shortened by deltaTtime; the (linearized) utility change is - beta_perf * deltaTtime .  beta_perf is typically positive, so the contribution is negative.

Overall: The (linearized) utility change caused by longer travel is

( - beta_perf + beta_travel ) * deltaTtime

Traveller increases arriving early (by amount deltaEtime)

In that situation, the traveller will "do nothing" between the arrival and the opening time of the activity.  That is, the amount of time that the traveller is doing nothing is now increased by deltaTtime.  Consistent with the meaning of the Vickrey parameter "marginal utility of arriving early", we assume that the travel time is the same compared to the later arrival. This means that the preceeding activity was cut shorter by deltaTtime.  We thus have the following (linearized) modifications of the utility:

• The preceeding activity is shortened by deltaTtime; the (linearized) utility change is - beta_perf * deltaEtime .  beta_perf is typically positive, so the contribution is negative.

There are no other contributions, since the time between the arrival and the opening time prodices neither positive nor negative utility contributions.  Overall: The (linearized) utility change caused by arriving early is

( - beta_perf ) * deltaEtime

Traveller increases arriving late (by amount deltaLtime)

In this situation, we have the following (linearized) modifications of the utility:

• The preceeding activity is extended by deltaLtime; the (linearized) utility change is beta_perf * deltaLtime .  beta_perf is typically positive, so the contribution is positive.
• The following activity is shortened by deltaLtime; the (linearized) utility change is - beta_perf * deltaLtime .  beta_perf is typically positive, so the contribution is negative (and exactly cancels the previous contribution).
• Arriving late is increased by deltaLtime; the (exact) utility change is beta_late * deltaLtime .  beta_late is typically negative, so the contribution is negative.

Overall: The (linearized) utility change caused by increasing the amount of arriving late is

beta_late * deltaLtime

Overall

Overall, calibration of the Charypar-Nagel scoring function is best done as follows:

• Run a survey and estimate logit models that include penalties for travelling (by mode), schedule delay early, and schedule delay late.
• The marginal utility of schedule delay early from the logit model, multiplied by minus one, results in the MATSim beta_perf.  Since the marginal utility of schedule delay early is typically negative, beta_perf is thus typically positive.  This is the marginal opportunity cost of time.  A useful interpretation is that this is the difference between "leisure" and "doing nothing".
• The marginal utility of travelling from the logit model, plus beta_perf, results in the MATSim beta_trav (by mode).  That is, the MATSim beta_trav is an additional utility offset when compared to doing nothing.  Since driving can well be seen as more positive than doing nothing (e.g. because of making phone calls, listening to music, enjoying to drive), the MATSim beta_trav can well be positive.
  (Note that this has still nothing to do with "positive values of travel time", e.g. by Susan Handy.  Those positive values imply that the additional utility offset over-compensates the marginal opportunity cost of time.  In other words, "time spent driving home" is (to an extent) seen more positive than "being at home".)
• The marginal utility of being late from the logit model results in the MATSim beta_late.
• Note that you also need reasonable values for opening time, latest arrival time, and closing time, in order to achieve that the schedule delay cost mechanics works in MATSim.  This is quite clear if you think about it; nevertheless, it has been forgotten uncountable times (in particular in studies that start from trips, not from full daily plans).

Without schedule delay

If you intend to run MATSim without time adaptation (TimeAllocationMutator), these things are not that critical.  In that situation, you just need to make sure that - beta_perf + beta_trav matches your marginal utility of travel time differences.  An easy way in our view is:

• Set beta_car to zero (i.e. assume that driving is as good or bad as doing nothing).
• Set beta_perf to the estimated marginal utility of travel time savings (make sure you get the sign right; beta_perf should be positive).
• Set (say) beta_pt to your estimated marginal utility of travel time savings (should be positive) minus the MATSim beta_perf.  The result may be positive (implying that spending time using the mode is better than doing nothing) or negative (implying that spending time using the mode is worse than doing nothing).

Note that even without time adaptation, beta_late may still have an influence if you have set the latest arrival times for some activities.

Full version

"Full version" would imply that we could calibrate the MATSim parameters also for situations where the actual activity durations are far from their "typical" values.  This could happen for two reaons:

• There are too many activities that need to be squeezed into a day.  A possible interpretation would be that beta_perf corresponds to the marginal utility of additional leisure time on, say, sundays, but the weekday activites cannot be shifted to sundays.
• There are too many activities that need to be squeezed into certain time periods, say between day care opening and closing, or into typical business hours.

Both of these interpretations make sense (in my view) and should be investigated for MATSim.  Presumably, there is already general research; it would then be necessary to bring that research and the MATSim formulation together.

Interpretation of the logarithmic "utility of performing"

The so-called "Charypar-Nagel scoring function" is used in many MATSim studies.  It is called that way because there is an ancient paper where this scoring function was introduced.

It uses a logarithmic utility of time for activities: U = beta * t_x * ln(x/t_0) .  I sometimes call t_x the "typical duration".

The first derivative of U is beta at the typical duration:

• dU/dx = beta * t_x / x

• dU/dx(x=t_x) = beta

Interpretation: marginal utility of duration at "typical duration" is indep of activity type. (*)

The second derivative of U at the typical duration is

• d^2U/dx^2 = - beta * t_x / x^2

• d^2U/dx^2(x=t_x) = - beta / t_x

An important consequence of this is that there is no separate free parameter to calibrate the curvature (= 2nd derivative) at the typical duration: beta needs to be the same across all activities, and t_x is given by (*).

A second consequence is that t_0 is largely irrelevant.  It shifts the function up and down, i.e. it determines how much you lose if you drop an activity completely.

In the original paper (and in most of MATSim), t_0 is set to t_x * exp(-10h/t_x) .  This has the (intended) consequence that all activities have the same utility contribution at their typical duration:

U = beta * t_x * ln( x / t_x / exp(-10h/t_x) ) = beta * t_x * [ ln( x/t_x ) + 10h/t_x ]

which is, at x=t_x:    = beta * t_x * [ 0 + 10h/t_x ] = beta * 10h .  With our usual beta = 6Eu/h, this results in 60Eu per activity.

The slope at U=0, i.e. at x=t_0, is

(beta * t_x / t_x) * exp( 10h/t_x) = beta * exp( 10h/t_x )

which decreases with increasing t_x.  This means that activities with larger typical duration are easier to drop completely.

In the end, this makes sense: Since the additional score of any activity is the same, the score per time is smallest for activities with long typical durations.  Therefore, it makes sense to drop them first. 

But practically, this is probably not desired behavior, since it would first drop the home activity from a daily plan.

Overall, therefore: In my opinion, the current utility function does not work for activity dropping.

An alternative, never tested since activity dropping was never tested with this utl fct, would to to recognize that U'(t_0) = beta * t_x / t_0 , i.e. increasing slope with decreasing t_0.  That is, high priority activities should have t_0 such that t_x/t_0 is large (large slope = hard to drop).  Activities of the same priority should have t_0 such that t_x/t_0 is the same between those activities.  Overall, something like

weight \propto t_x/t_0

or

t_0 \propto t_x/weight

where large weight implies a large importance of the activity.

This was, as said, never tried, since activity dropping was never systematically tried.  It also does not fix the problem, discussed later, that different activities might have different resistance against making them shorter; since this is U'', this is  -beta/t_x with the above utl fct: activities are shortened proportional to their typical duration.

To make matters worse, there is currently the convention that negative values of U are set to zero.  This is done since we need useable values for negative durations (since they may happen at the "stitching together" of the last to the first activity of a day), and if we give those a "very negative" score, then the utl at t=0 cannot be even smaller than this.

This has, however, the unfortunate consequence that the "drift direction" of the adaptive algorithm, once an activity duration has gone below t_0, goes to zero duration.

Outlook: What would we want for our next generation utl function?  Some wishes from my perspective:

• Curvature at typical duration can be calibrated
• Slope at U=0 can be calibrated
• Utl function extends in meaningful way to negative durations (this would fix the arbitrary handling that we currently employ)

In my view, a polynomial of second degree would be worth trying. As usual, there are several ways to set this up.  One way is to expand around the typical duration:

U(t_x + eps) = U(t_x) + eps * U'(t_x) + eps^2 * U''(t_x)/2

or

U(x) = U(t_x) + (x-t_x) * U'(t_x) + (x-t_x)^2 * U''(t_x)/2

with t_x = typical duration, U'(t_x) = beta = marg utl at typ dur, U''(t_x) = curvature at typ dur ("priority"), and U(t_x) = "base value of act" (which could be something like beta*t_x ).

Another way (having the parabola going through (0,0)) would be

U(x) = - a x ( x - c ) = - a x^2 + a c x

U'(x) = - 2 a x + a c

prio = U'(x=0) = a c , i.e. c = prio/a .

beta = U'(x=t_x) = - 2 a t_x + prio, i.e. a = (prio - beta)/2t_x

There is other work (e.g. by Joh) that should be looked at.

Choice set --> "plan set" of an agent

Choice set --> "plan set" of an agent

Comments: During MATSim iterations, agent accumulate plans.  This can be interpreted as building a choice set over time.  A problem is that the process that generates the choice set at this point is not systematic.

Possible future developments: Once it has been made explicit that "plans generation" means "choice set generation", the terminology may be made standard.

Choice set generation --> Time mutation/re-route/... ; "innovation"

Choice set generation --> Time mutation/re-route/... ; "innovation"

Comments: As said above, the set of MATSim plans can be seen as this agent's choice set.  MATSim generates new plans "on-the-fly", i.e. while the simulation is running.  We sometimes call this "innovation", since agents create new plans (= add entries to the choice set), rather than choosing between existing plans.

Choice set generation, choice --> plan selection, replanning

choice set generation, choice --> plan selection, replanning

It seems as if replanning is only used in Matsim for "generating a new plan alternative" but not for "selecting an existing alternative". It took me some time and some misunderstandings with Yu to figure this out. It appears more plausible to me to phrase it as "replanning = {choice, choice set generation/update}". Gunnar

The above needs to be discussed; in my understanding replanning indeed includes choice.  Kai

Convergence --> learning rate

Convergence --> learning rate

Scores in matsim are computed as score_new = (1-alpha) * score_old + alpha * score_sim, where score_sim is the score that is obtained from the execution of the plans (= network loading).

Mu (logit model scaling factor) --> beta_brain

mu (logit model scaling factor) --> beta_brain

Matsim scoring function = beta_brain * \sum_i beta_i * attribute_i

Typical formulation = \mu * \sum_i ...

For estimation, \mu and the \beta_i are not independently identifiable. For simulation, they are hence somewhat arbitrary. Since this is arbitrary anyway, beta_brain should be at least set to one and not to two. The re-labeling into "mu" would not only be more consistent with common language, it would also avoid the "brain"-notion, which I find irritating. Gunnar

I agree.  "beta_brain" and "2" are there for historical reasons, and api changes are always difficult.  Kai

Multinomial logit --> ExpBetaPlanSelector

Multinomial logit --> ExpBetaPlanSelector

Comments:

• The main problem is that one needs to keep in mind how the choice set is constructed (see above).
• In most simulations, we use ExpBetaPlanChanger instead, which is a Metropolis Monte Carlo variant of making multinomial logit draws

Possible future developments: None of this is ideal, since, after the introduction of a policy, it is not clear which behavioral switches are due to the policy, and which are due to sampling.  In theory, one should have unbiased samples before and after the introduction of the policy, but at this point this is not implemented and it is also computationally considerably more expensive than what is done now.

Network loading --> mobsim, mobility simulation, physical simulation

network loading --> mobsim, mobility simulation, physical simulation

Comments: The standard terminology has the "network loading" on the "supply side".  In my (KN's) view, the "simulation of the physical system" is not the supply side, but what in economics is called "technology".  This can for example be seen in the fact that "lane changing" is part of the mobsim, but this is, in my view, not a "supply side" aspect.

Possible future developments: May switch to "network loading" if there is agreement that this is a better name.

Stationary --> relaxed

stationary --> relaxed

Comments: "stationary" means that the probability distribution does not shift any more.  However, as long as "innovation" is still switched in on MATSim (new routes, new times, ...), the result is not truly stationary.  Thus we avoid the word.  If innovation is switched off, the result is indeed a statinary process, but limited to the set of plans that every agent has at that point in time.

Possible future developments: not clear.  Minimally, publications should be precise.

Configuration:

<module name="strategy" >
	<!-- iteration after which module will be disabled.  most useful for ``innovative'' strategies (new routes, new times, ...) -->
	<param name="ModuleDisableAfterIteration_1" value="null" />
	<param name="ModuleDisableAfterIteration_2" value="950" />

	<!-- probability that a strategy is applied to a given person.  despite its name, this really is a ``weight'' -->
	<param name="ModuleProbability_1" value="0.9" />
	<param name="ModuleProbability_2" value="0.1" />

	<!-- name of strategy (if not full class name, resolved in StrategyManagerConfigLoader) -->
	<param name="Module_1" value="ChangeExpBeta" />
	<param name="Module_2" value="ReRoute" />

	<!-- maximum number of plans per agent.  ``0'' means ``infinity''.  Currently (2010), ``5'' is a good number -->
	<param name="maxAgentPlanMemorySize" value="4" />
</module>

 The above means:

• StrategyModule "ReRoute" (= innovative Module, produces plans with new routes) is switched off after iteration 950.
• StrategyModule "ChangeExpBeta" (= non-innovative Module, switches between existing plans) is never switched off.
• If an agent ever ends up with more than 4 plans, plans are deleted until she is back to 4 plans.  (Deletion goes via a "PlanSelectorForRemoval", which affects the choice set, and thus more thought needs to go into this.  Currently, the plan with the worst score is removed.)

Utility <--> score

utility <--> score

At least when using random utility models (such as multinomial logit aka ExpBeta...), the score has the same function as the deterministic utility.