01 - Introduction

The configuration file serves the users as the primary interface to configure a MATSim run. The configuration file contains different modules, some of which are mandatory, such as network, plans and controler. There exist lots of additional modules and you can browse at matsim.org to find their documentation.

 In the next chapter we will learn, how to perform simple calibration in MATSim.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

02 - Using some of the config options for calibration

After learning, how to start a simple MATSim run one needs to get into the habit, to run MATSim again and again. For example the different shares of transportation modes (car, bike, public transport, etc.) need to be calibrated.

To exemply how typically parameters in MATSim are calibrated, we look at an example where we have a hypothethical 10% population sample given and we do not have the resouces to create and run a 100% scenario (e.g. the machine has not enough RAM). To do so, the network needs to be calibrated to the popluation sample size. In the network file, each link has a length and a capacity (among other characteristics). The length defines the storage capacity of the road (how many cars have space on the road during a congestion). For all links a capperiod (capacity period) is defined, which is a time duration. The flow capacity of a road (named capacity in the network file),  defines how many cars can pass the road during the capacity period. E.g. if the capperiod is set to "01:00:00" and the capacity of a certain road is set to 3600, this means that 3600 cars can pass the road in one hour at maximum.

• Try it out yourself: Look at the mentioparameters in the network file located at "examples/equil/network.xml"

In order to match a 10% population to a network, the network needs to be scaled down, so that it maches the population. There are two parameters available in MATSim, which can be used to perform this scaling: storageCapacityFactor and flowCapacityFactor (referred to as scaling factors from hereon). In theory, when using a 10% population both these scaling factors need to be set to 0.1. But in practice, this looks different and often the storageCapacityFactor needs to be set much higher than prescribed in theory. Furthermore, it also depends on the micro-simulation being used. By default the "QueueSim" simulation is being used, and the default values for both scaling factors are set to 1.

• Try it out by changing the configuration parameters:
  
  • Open the configuration file "examples/tutorial/config/example1-config.xml". If you think, that the configuration file has been changed sense its download, you can download its original version from here.
  • Inorder to use a larger population (2000 agents), change the value of the parameter "inputPlansFile" to "examples/equil/plans2000.xml.gz".

  • Add the strategy module with the following settings (also see here):

  	<module name="strategy">
  		<param name="maxAgentPlanMemorySize" value="5" /> <!-- 0 means unlimited -->
  
  		<param name="ModuleProbability_1" value="0.9" />
  		<param name="Module_1" value="ChangeExpBeta" />
  
  		<param name="ModuleProbability_2" value="0.1" />
  		<param name="Module_2" value="ReRoute_Dijkstra" />
  
  		<param name="ModuleProbability_3" value="0.1" />
  		<param name="Module_3" value="TimeAllocationMutator" />
  	</module>

  • Change the value of "lastIteration" to 10 in the configuration file
  • Run MyControler1
  • Now change the value of the parameter "outputDirectory" to "./output/example1_2"
  • Then set both scaling factors to 0.1 as shown below (by adding the "simulation" module)


 	<module name="simulation">
		<param name="flowCapacityFactor" value="0.1"   />
		<param name="storageCapacityFactor" value="0.1"   />
	</module>

• Now run MyControler1 again. In order to observe the difference in output of the two runs after changing the scaling factors, compare the following two leg histogram files "output/example1/ITERS/it.10/10.legHistogram_all.png" and"output/example1_2/ITERS/it.10/10.legHistogram_all.png".

In order to calibrate, many runs with dozens of iterations will need to be performed. In order to improve performance and as such save time, we can perform the following steps:

• One way to improve performance is by turning off outputs, which are not nessecary for this excercise. For example the events file should not be written out after each iteration (located at "output/example1/ITERS/it.xx/xx.events.xml") . To do so, add the following line in the "controler" module (within the config file):

	<param name="writeEventsInterval" value="0" />

• Furthermore, for this excercise a different (and faster) micro-simulation can be used by changing the module name from "simulation" to "JDEQSim". A documentation of this micro-simulation called JDEQSim is found here.
• Change the values of both scaling factors to 1.0.
• Change the value of the parameter "outputDirectory" to "./output/example1"
• Change the value of "lastIteration" to 50 in the configuration file
• Run MyControler1
• You can see how the score in MATSim develops over 50 iterations, by looking at the following output file "output/example1/scorestats.png"

Now you are ready to start with the calibration excercise (see next chapter).

 

 

03 - Exercise 1

Before starting this excercise, the configruation file in "examples/tutorial/config/example1-config.xml" should be prepared as described in the previous chapter. The configuration file should look as in this example file.

The goal of this excercise is to find calibrated values for the "storageCapacitiyFactor" and "flowCapacityFactor" such that, after calibration the leg histogram in the 50th iteration (located at "output/example1/ITERS/it.50/50.legHistogram_all.png") looks similar to the following figure.

Hints:

• The calibrated "storageCapacitiyFactor" is between 0.5 and 1.0 and the "flowCapacityFactor" between 0 and 0.5.
• Tryout changing the scaling factors separatly to find out what effect they have.
• When you have found the calibarted factors, als look at the score file located at "output/example1/scorestats.png"

 

 

 

04 - Exercise 2

In this excercise, you will find out the effects of changing the probabilities of the different strategies in the "strategy" module (within the configuration file located at "examples/tutorial/config/example1-config.xml"). The duration of completing the steps described in this excercise, depends mostly only on the speed of your computer (although the questions at the end need some thought).

• Change the values of both scaling factors to 0.2.
• Run MyControler1 (for 50 iterations)
• Now change the value of the parameter "outputDirectory" to "./output/example1_4"
• Set the value of the paramter "ModuleProbability_3" to "0.001"
• Run MyControler1 (for 50 iterations)
• Now change the value of the parameter "outputDirectory" to "./output/example1_5"
• Set the value of the paramter "ModuleProbability_3" to "0.1"
• Set the value of the paramter "ModuleProbability_2" to "0.001"
• Change the value of "lastIteration" to 200 in the configuration file
• Run MyControler1 (for 200 iterations)
• Compare the scores of the both runs (found in "output/example1/scorestats.png", "output/example1_4/scorestats.png" and "output/example1_5/scorestats.png").

• Compare also the leg histograms (between the runs and also the different iterations of the last run).

What do you observe? What can we learn from this?