3. Getting Started: Running the Simulation for the First Time

3.1. Introducing the Input Components

You will hear in more detail about the input components in Lesson 4. Thus, only a brief overview is given here. Often these files are handled in MATSim in the compressed format gzip with the extension ".gz".

Network (network.xml)

The network file gives information about the transport infrastructure. A MATSim network contains links and nodes each with its specific attributes such as the node coordinates or the link capacity.

Plans / Population (plans.xml)

Plans represent the population and the demand of a scenario. Usually, you will not create plans by writing into the actual plans files but will generate your demand by either using the API or your own code. You will hear more on population demand generation in Lesson 4.

Configuration file (config.xml)

The controler needs one argument and that is the configuration file. As long as you do not write code, the configuration file is your way to adapt the behavior of MATSim.

Additional input:

During this tutorial you will use facilities (facilities.xml.gz) and count data (counts.xml). Facilities are an optional part of MATSim. They can roughly be interpreted as buildings. Count data is one of the most important sources for validation as obviously they are associated to a small measurement error, in contrary to e.g., survey data.

3.2. Starting the Simulation for the First Time

Now it is time to run the simulation. There are some example scenarios which can be started without modifiying anything in MATSim. You might want to look at them later. But we are continuing with setting up our own java project already here.

Create your own java project:

• Click File -> New -> Java Project
• Name it for example myProject
• Click Next
• We have to reference MATSim here, such that the you can access the MATSim functions from your project
  • In Java Settings click the tab Libraries
  • Click Add JARs ...
  • Select the matsim-0.5.x folder
  • In this folder select the jar file matsim-0.5.x.jar
  • Click OK twice
  • Click Finish

Create your own controler:

• Now create an input and an output folder in your project
• Right-click your project and click New -> Folder
• Go to Folder name and enter input
• Repeat this to create an output folder
• Now create a new class in your project:
  • Create a new package in our project
    • Right-click on the src folder in myProject and click New -> Package
    • Give it the name tutorial
    • Click Finish
    • Right-click on this newly created package and click New -> Class
    • In the New Java Class dialog that appears now enter the name MyFirstControler
    • Under Which method stubs would you like to create? select public static void main(String[] args)
    • Press the button Finish
    • Open this class if it has not yet opened automatically.
    • Enter the following code into the main method. Enter the code just below public static void main(String[] args) {

Config config = ConfigUtils.loadConfig("input/config.xml");
Controler controler = new Controler(config);
// controler.setOverwriteFiles(true);
controler.run();

• Most probably you will see red lines under the word Controler. There is an option to instruct Eclipse to organize the imports automatically. If you see red lines this option is deactivated in your configuration. For the moment just move the mouse over the word Controler. A dialog appears which suggests some quickfixes. Double-click on the (first) entry Import 'Controler' (org.matsim.core.controler)
• Save the file and the red lines should have gone.
• if you are not familiar with programming you can download the controler here. If you have used a different package path than suggested above you need to adapt the package path in the source file!

Copy the input files to your project:

• Download the plans file (plans.xml.gz), the network file (network.xml),  the facilities file (facilities.xml.gz) and the config file (config.xml) and copy them to the input folder.  You may have to refresh the Eclipse view afterwards (right-click your project and click Refresh).
• Please download the files by doing a right-click and then save as. Do not open the xml files in the browser for copying them into a text editor! Browsers usually add some characters for better visualization, which produce erros during xml parsing in MATSim.

Run the simulation:

• Click on your project in the Package Explorer. This is not really necessary but it helps Ecplise to make a more helpful autocompletion.
• Then go to the Eclipse menu Run and click Run Configurations...
• Select Java Application in the left box and press the New button
• Name the new launch configuration for example myFirstControler
• Under Project enter myProject if it is not yet autofilled
• Click the Search... button to choose the Main class
• Type MyFirstControler and click OK
• Now wee need to tell the controler where the config file is stored: Go to the Arguments tab and type under Program arguments the path to the config file, i.e., input/config.xml
• Click Apply
• Make sure the process will have enough memory available to run: add -mx700m in VM arguments.
• Click Run
• You have just started your first MATSim run using your own controler! We will extend the functionality of this controler in Lesson 7.
• If in the end the message S H U T D O W N   ---   regular shutdown completed appears everything went fine.

If you want to rerun the scenario again, you have to clean the output folder. For safety reasons MATSim does not overwrite files in the output folder and exits if files are in there. For small sceanrios this looks incomfortable but imagine that you accidentally overwrite a run that took a few days. You will be grateful to MATSim that it refuses to overwrite this work. If it gets on your nerves at the moment just open the MyFirstControler and remove the comment in front of controler.setOverwriteFiles(true); If you don't know how comments work in Java please check the Section  2.2.3.

3.3. A First Look Into the Configuration File

Your simulation finished after 1 iteration. As you have learned earlier, MATSim is based on the principle of evolution. Clearly, no evolutionary process is able to find an optimum in only one iteration, not even a local one. Hence, try to increase the number of iterations to 10. Open the configuration file and try it!

Has it worked out? Yes? Great! But where are the counts? Download the counts file (counts.xml) and copy it to the input folder. Now, open the configuration file again and try to add the traffic counts. You need the set the path to the counts input file. Additionally, you need to set the counts scale factor correctly. Please note, that we are using a 1% sample in this example. So the scale factor is 100. Illogical? Yes at first sight. But we are actually scaling the simulated values and not the counted values although that factor is given in the counts section of the configuration file.

3.4. Start the Visualizer

Now it is time to have a look at the visualizer. When the simulation ran, many files were created in its output directory. One of the files is a so-called events file, typically generated for every 10th iteration. The events file for the first iteration is located in output/ITERS/it.0/run0.0.events.xml.gz. This contains a lot of information that can be visualized. Now, when you start the visualizer, you should see a large, black area. This is where the traffic will be visualized. On the right side of this area, you see a smaller area with 5 icons on the top ("Controls"). Click the first icon ("Data Sources"). Now you can either drag and drop files into this section (e.g. a network.xml, or events.xml.gz), or click the green "+" at the bottom to select a file to be added. Use either option to add first network.xml to the list of available data and then events.xml.gz. Now the visualizer knows about our data, and we can tell it how to visualize it.

Next, click on the second icon ("Layers") in the "Controls" section. Initially, you will see only the background layer listed. Click on the green '+' to select the data you want to have displayed. It should already suggest to visualize the network with the loaded network.xml, so just click "Add". After a short moment, the network should be shown in the visualization area. Click the green '+' again, but this time choose "Vehicles" as layer type. The events.xml.gz file will be already pre-selected. Click on "Add". As any layer depending on the events, a  "Load Data" button will appear at the bottom of the layer tag. Click it to extract the vehicles' positions from the events.

Zoom in to the Zurich area, and change the time with the slider below the visualization area to see how the vehicles move around.