1) Introduction

MATSim provides a toolbox to implement large-scale agent-based transport simulations. The toolbox consists of several modules that can be combined or used stand-alone. Modules can be replaced by own implementations to test single aspects of your own work. Currently, MATSim offers a toolbox for demand modeling, mobility-simulation, re-planning, a controller to iteratively run simulations as well as methods to analyze the output generated by the modules.

 

Prerequisites

A modern desktop or laptop computer with at least 1 GB RAM and 500 MB free disk space is required to follow the steps in this guide (find more information on MATSim system requirements here). Please make sure that the following software is installed on your computer:

• Operating system
  You can use the operating system of your own choice for which Java and Eclipse are available (e.g. Windows XP and above, Mac OS X, GNU/Linux). Make sure you have administrative rights for your computer. They might be required for the installation of a missing program or the modification of some computer setting.
• Web browser
  Make sure a web browser such as Mozilla Firefox is installled on your laptop.
• File archiver
  A program to handle file archives (*.zip, *.gz) is required. While such a tool is typically bundled with Mac OS X and GNU/Linux, it has to be manually installed for Windows. A recommended tool for Windows is 7-Zip.
• Java
  You will need at least the Java Runtime Environment (JRE) 6 or newer to run the examples and the Java Development Kit (JDK) 6 or newer to compile your own code that uses MATSim functionality. It is best to use the JDK from the beginning. Download and install the newest version of the "Java SE Development Kit" (JDK 6.0 Update xy) from java.sun.com.
• Eclipse
  This guide uses the Eclipse Integrated Development Environment (IDE) as an interface to the MATSim software, as well as as input and ouput files. Download and install Eclipse from eclipse.org. The package "Eclipse IDE for Java Developers" is sufficient for our needs.
• Google Earth
  MATSim is able to generate output in the format of *.kmz files which can be viewed with Google Earth. Download and install the latest version from earth.google.com.

Furthermore, an active internet connection is required to successfully run the examples in the subsequent sections.

Using MATSim with Eclipse

This  version of the tutorial matches the code in the MATSim Spring 2011 release. The version number is 0.3.x, with 'x' being the number of latest official bugfix release. Make sure always to use the latest bugfix release. For reasons of simplicity, we use the string "matsim-0.3.x" when the version number is referred to.

In order to access code and data, the Eclipse IDE is used instead of the command line. Take the following steps in order install MATSim in Eclipse.

• Download the current release (matsim-0.3.x.zip, replace x with the number of the bugfix release) from the sourceforge download page and save it on your desktop.
• Unzip the file. A folder (matsim-0.3.x) appears.
• Start Eclipse.
• Start a new Java Project: Click File -> New -> Java Project
• Deselect the "Use default location" checkbox
• For the "Location", choose the unzipped matsim-0.3.x folder.
• Make sure a JRE/JVM 6 is set in section JRE.
• Click Next.
• In the "Java Settings" dialogue, click the Libraries tab.
• Make MATSim source code visible in Eclipse:
  • In the JARs list, choose matsim-0.3.x-sources.jar and click Remove.
  • In the JARs list, choose matsim-0.3.x.jar and expand it.
  • Click Source attachment: (None), then click Edit....
  • Click Workspace....
  • Choose matsim-0.3.x/matsim-0.3.x-sources.jar, then click OK.
• Set the native Java-OpenGL library for the visualization used later in this guide:
  • In the JARs list, choose the JRE System Library and expand it.
  • Click Native library location: (None), and click Edit....
  • Click Workspace....
  • Depending on your operating system (OS) and your machine type (MACHINE), choose matsim-0.3.x/libs/jogl-1.1.1/jogl-1.1.1-OS-MACHINE/lib.
  • Click OK.
• Click Finish.

Congratulations! You have successfully installed MATSim for usage with Eclipse. The project can be found in the Package Explorer on the left side of the screen. You can now investigate the MATSim software project, e.g.

• read the release notes (README.txt, CHANGELOG.txt)
• conveniently browse the source code of MATSim (packages in Referenced Libraries - matsim-0.3.x.jar). For this, make sure that the package presentation is hierarchical: Click the small triangle at the top right of the Package Explorer, then choose Package presentation - Hierarchical.

Next, we take a look at an example scenario.

2) Scenarios

Each scenario contains of at least a plans and a network file. As well as the later described configuration file these two are xml-files, which you may view and edit with a text editor of your choice.

 

The example scenario used in this tutorial is based on the so-called "equil scenario" originally documented in Raney and Nagel (2006).

Networks

Network files describe the networks of links and nodes of a city. Links may be streets or even other transportation links. Inspect the file

examples/equil/network.xml

to get a first idea of a basic network file. You will also notice that each node has a specific location given in coordinates.

Visualising a network

The pure xml file is of course not very comfortable to read. But you may also visualize it using OTFVis. To do so with the use of Eclipse,

• Navigate to Referenced Libraries - matsim-0.3.x.jar.
• Right-click on it, choose Run As - Java Application.
• In the topmost field, start typing "OTFVis". Executable classes with a name matching your input remain in the Matching items list below.
• Make sure OTFVis is selected in this list.
• Click OK.
• A file-open dialog appears. Select MATSim net or config file (*.xml).
• Navigate the network.xml file mentioned above in your matsim-0.3.x folder.

After a moment, you will see the network visualized. If the network is not visible or any other problem occurs, information about the problem can be found in the console output which is displayed at the bottom right of the Eclipse workspace. In this case, you may re-run the visualization by choosing Run - Run History - OTFVis.

Now you can also configure the visualizer further, e.g. by changing the colors of the links or by displaying their names. Read more about the usage options of OTFVis here and about technical issues here.

Plans

Plans are the essential counterparts of a network: They represent the population of a scenario. Have a look at the plans file for 100 agents of the equil scenario:

examples/equil/plans100.xml

Usually, you will however not create plans by writing into the actual plans files but will generate your demand by either using the API or your own code. More on demand generation and creating your own scenario is found in a separate tutorial.

A scenario may include additional input files that are referenced by other data. A configuration file collects all settings including file paths to the data files (network, population, …). The settings are separated into modules, which group related settings together.

The configuration file is read by the Controler, which will then run the simulation according to the settings outlined in the file. All configuration files referred to in this section are situated in the folder:

examples/tutorial/config/

A single iteration

Open the configuration file

examples/tutorial/config/example1-config.xml

in your favourite text editor. As you can see, the first modules (i.e. networks and plans) reference to the respective files describing them. The controler module describes where the output of the simulation will be written to and how many iterations will be run. In this case, only one iteration is run, as both first and last is set to 0. Finally, the config module planCalcScore lists the activity types that exist and how long they typically last.

Now, it's time to run your first simulation. For comfort, we have added a controler automatically reading this configuration. Run the controler in Eclipse:

• Navigate to Referenced Libraries - matsim-0.3.x.jar.
• Right-click on it, choose Run As - Java Application.
• In the topmost field, start typing "MyControler1". Again, executable classes with a name matching your input remain in the Matching items list below.
• Make sure MyControler1 - tutorial.config.example1mobsim is selected.
• Click OK.

If everything is set up correctly, you should see the message “regular shutdown completed.” shortly after the execution of the command. If it reads “unexpected shutdown completed”, an error or exception has happened. In this case, you will find more information in earlier lines of the log.

Now, check your matsim folder for a new directory named output: In the Package Explorer, navigate to the project root symbol labeled with the project name. Right-click on it and choose Refresh. The new output folder appears, with a single folder called example1 in it. There, you will find

• some basic statistics across iterations, e.g. aggregate score information in the file scorestats.txt,
• a logfile of the console output in logfile.log, and
• a folder named ITERS where MATSim writes the output files of the iterations.

In our case, the ITERS folder contains our only iteration it.0. This folder contains results of the specific iteration. The most important file is 0.events.xml.gz, which lists all events the agents pass. It also contains the plans file which shows the agents' plans in the current iteration. Furthermore, iteration-specific statistics may be located in this folder.

As for now, no visual output has been produced. For generating this, check out

examples/tutorial/config/example2-config.xml.

You will notice the roughly same config as above, but there is also a module called simulation. The comments in the file will explain you the usage of them. Another prepared controler exists for this config file. Proceed as above, but this time use

MyControler2 - tutorial.config.example2vis

Note: It may be that you encounter an out of memory error (check the console output). In ths case, you will need to increase the memory Java is allowed to use. Use at least 512MB here:

• From the menu, choose Run - Run Configurations... 
• In the list of run configurations on the left side, choose Java Application - MyControler2.
• Select the Arguments tab.
• In the text field labeled VM arguments, type "-Xmx512M".
• Click Run.

You will see the OTF-Visualizer that we have previously used to display a network. Press the play button and you will see the agents moving from home to work.

The results are stored in the folder output/example2. Additionally to the standard results files, there is a file called 0.googleearth.kmz in the ITERS/it.0 folder. This file can be opened with Google Earth. You may see the agents on their way somewhere in the Atlantic ocean.

3) Running iterations

Iterations

If you want to run more than one iteration check out the

example-config5.xml

which runs 10 iterations. You will also notice the more advanced scoring as well as a new strategy-module. This contains some rerouting strategies with their corresponding probability. Run the corresponding controler

MyControler5 - tutorial.config.example5iterations

as described for the other controlers before. After the iterations have finished ("regular shutdown completed."), refresh the output folder again. The last example has generated ten iterations, which you may view by starting the OTFVis and selecting the appropriate mvi-File in each directory. The last iteration results in a state that is closer to a steady state than the first iteration.

• Re-run OTFVis by selecting Run - Run History - OTFVis
• As the file format, make sure OTFVis movie file (*.mvi) is selected.
• Navigate to output/example5/ITERS/it.10/10.otfvis.mvi in your matsim-0.3.x folder and click Open. The OTFVis starts.
• Click the play button to visualize the traffic along the timeline, and modify the layout via the File - Preferences menu.

Usually, in each iteration a certain percentage of the agents receives a new plan, which is set by the replanning module (see next section). This is repeated several times until the last iteration (“day to day” replanning). The agents that change their plans are randomly varied each time. As each agent simulates an individual, their knowledge is private and they do not know, what the “other agents are planning”. The agents are able to fall back to earlier routes travelled and is hence able to “learn”, so the best solution is eventually found.

Modifying the Re-Planning

The setup of the replanning modules in the previous example can already be used to simulate larger scenarios. Open the config file of the previous example, examples/tutorial/config/example5-config.xml, and move to the "strategy" config module.

• The TimeAllocationMutator varies, as the name suggests, the time of day when the agents leave, depending on their plans.
• ReRoute_Dijkstra generates new shortest paths based on a time-dependent Dijkstra algorithm. For both the TimeAllocationMutator and the ReRoute_Dijkstra, refer to the initial paper by Raney and Nagel (2006).
• ChangeExpBeta is a selection strategy which selects an existing activity plan for the next iteration, and approximates the simulation to a logit model. The reason for this selector is elaborated in Nagel and Flötteröd (2009).

Modify the following settings in the "strategy" config module:

• ModuleProbability_1 to a lower value, e.g. 0.1
• ModuleProbability_2 to a higher value, e.g. 0.9.

Run the simulation again and look at some consecutive iterations in the visualizer. What effect can you observe?

Trip based iterations

Finally, have a look at

examples/tutorial/config/example5trip-config.xml.

This file has a somewhat different Scoring part which will result in iterations which are solely based on the previous trips. Run this configuration with the prepared controler named MyControler5Trips.

4) Running your own configurations

In the previous steps, the path to the configuration file used by each MyControler* was hard-coded. However, running your own configuration is very simple: Just pass the path to your config file as the single argument to the Controler.

• Create a copy of example5-config.xml in the same folder. Name the copy example5-config-2000agents.xml
• Open the new config file.
  • In the plans module, change the value of the parameter inputPlansFile to:
"./examples/equil/plans2000.xml.gz"
    This tells the controler to use a different initial plans file with 2000 agents provided in the official release.
  • In the controler module, change the value of the parameter outputDirectory to:
    "./output/example5-2000agents"
  • In the module controler, increase the value of the parameter lastIteration from 10 to 50. The learning procedure will have progressed substantially after 50 iterations.
  • In the simulation module, set the snapshotFormat to "" (remove otfvis). The memory-consuming production of OTFVis mvi files will now not be performed during the iterative simulation.
• Run your new configuration:
  • In the menu, select Run - Run Configurations... (or Run - Open Run Dialog...).
  • In the list on the left side, select Java Application.
  • Click the blank sheet/plus symbol in the left upper corner (New launch configuration).
  • In the Main class dialog, click Search....
  • Start typing "Controler". Make sure to select Controler - org.matsim.run from the Matching items list, and click OK.
  • In the Name: field, type a descriptive name for this run, e.g. "Controler - 2000 agents".
  • Click the Arguments tab.
  • In the Program arguments text field, paste the following text:
    examples/tutorial/config/example5-config-2000agents.xml
  • Click Run. Wait for the 50 iterations to finish successfully.
• Now let's manually generate the OTFVis visualization of the results of the last iteration:
  • In the menu, select Run - Run Configurations... (or Run - Open Run Dialog...).
  • In the list on the left side, select Java Application - OTFVis. If this item is not available, generate a new launch configuration as described above, choosing OTFVis as the main class.
  • Click the copy symbol on top of the list of the left side.
  • In the Name: field, type "OTFVis - convert".
  • Click the Arguments tab.
  • In the Program arguments text field, paste the following text:
    -convert output/example5-2000agents/ITERS/it.50/50.events.xml.gz examples/equil/network.xml output/example5-2000agents/ITERS/it.50/50.otfvis.mvi 60
  • In the VM arguments tab, paste the following text:
    -Xmx512M
  • Click Run.
• Run OTFVis as before, opening the file output/example5-2000agents/ITERS/it.50/50.otfvis.mvi in order to visuallize the result of iteration 50.
• Generate mvi files also for the results of other iterations, e.g. every 10th iteration, and compare them to each other.

5) Basic analysis

This step describes the basic output data MATSim produces by default for further traffic data analysis.

 

If you look into the root folder of your output directory, you will find a chart displaying the scores of each iteration. The scores can easily be modified in the config-File (see above), so you will be able to see the improvements of each iteration without too much effort. The data displayed is also shown in a corresponding text file. There is also a similar chart showing the travel distances travelled.

Events

Events are very simple information information units which are generated by the mobility simulation. Open the events-file

output/*/ITERS/it.0/0.events.xml

(you may need to unzip it first) in Eclipse and look at the possible events. You may want to filter out the events of one single agent to get a better understanding of the events. You can use the events-file for further, custom analysis of the simulation.

Further there are also some charts covering the number of legs depending on the time of day.

6) What's next?

Congratulations! You have just run your first MATSim scenarios. Depending on your interest, you might continue with one of the following options:

• Run your own scenario
  If you plan to do that, you need a network and a description of a population. Have a look at the provided example files to get a better understanding of the file formats.  The creation of the population can be based on a variety of data (census, commuter matrices, …), whatever is available. The page “Building a new Scenario”  gives further information about that topic.
• Generate custom analyses
  Read more in the Events Programming tutorials.
• Generate custom simulations
  Read more in the Controler Programming tutorials.
• Read about MATSim
  See the reference list at the end of this page.
• Stay up-to-date about MATSim
  by subscribing to one or more of our mailing lists.

If you wish access to different/more recent versions of the MATSim software then just the official release, consider the two following options:

• Use a nightly build.
• Directly access the SVN repository at Sourceforge, as described here.

References

The following publications have been cited in this tutorial and are preferred entry points to reading about MATSim.

Nagel, K. and G. Flötteröd (2009) Agent-based traffic assignment: Going from trips to behavioral travelers, paper presented at the 12th International Conference on Travel Behaviour Research (IATBR), Jaipur, December 2009.

Raney, B. and K. Nagel (2006) An improved framework for large-scale multi-agent simulations of travel behavior, in P. Rietveld, B. Jourquin and K. Westin (eds.) Towards better performing European Transportation Systems, 305–347, Routledge, London.

See also a fairly comprehensive list of publications related to MATSim here.

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?