MATSim lab - exercises

MATSim laboratory exercises

In this laboratory exercise you will learn the basics of a road traffic simulator. To prepare for the exercise you should read the syllabus.

In the first part you will use the user interface to run simulations with the given configuration files. You will learn how to read the output files of MATSim, and the calculated statistics. You will also process the output with the Via data visualization tool.

In the second part you will learn how to run MATSim from a program development environment. You will generate a network file from the database of Open Street Map, and prepare a population from program code.

Finally, in the third part you will learn how to use strategies and planning.

When answering questions always give explanations. Don't forget to indicate the source of the information (configuration file, output file, Via UI)!

Illustrate the solution of the exercises in the report with screenshots!

Attach the configuration files to the submitted report as a compressed archive!

 

0. Virtual environment

For the MATSim laboratory exercise we prepared a virtual machine. On the computers in the laboratory you need to select the MATSim boot option

In the virtual machine Java 11, MATSim 13.0, Via 22.1 and Eclipse 4.22 are installed.

The MATSim and Via programs, and the configuration files are available in the /home/matsim/Work directory.

Eclipse is installed in the /home/matsim/eclipse directory.

The programs can be started from the file manager by double clicking on the appropriate .jar file, or from a terminal with the java -jar [program].jar command.

The Via program can be used to visualize the results of a simulation run. Everybody needs their own license for Via, which can be obtained from the licenses site (choose the free license on the left). The name and organization fields are not important. The license.xml.zip is received in email, it needs to be downloaded into the VM, and when we first start Via, we need to supply this in the dialog, and click on the Close button.The laboratory syllabus contains a short introduction on how to use Via.

1. Introduction to MATSim

In the first part you will us the binary package of MATSim to learn the process of simulating a network.

1.1. Hello World!

Exercise

  1. Load config_01_01.xml into MATSim and run the simulation.
  2. Examine the configuration files and the structure of the output directory (the location of the output is set in the config file, and it also appears in the user interface of MATSim)!
  3. When answering the following questions, also specify in which file you found the information for the answer.

Questions

  1. How many users does the configuration model?
  2. How many iterations were run?
  3. What was the resulting score of the user?
  4. How much more time did the user spend at their office than planned?
  5. What was the distance travelled during this day?
  6. How much longer was the trip home than to the office? Why?
  7. Load the network and the results into Via (see the syllabus), and play back the daily events. What path did the user take? Why did they take this path?
  8. What happens if you try to run the simulation again?
  9. Make the simulation runnable again by resolving this issue, and increase the number of iteration to twenty! What error do you get when running the simulation?

1.2. Routing

Exercise

  1. Load and run config_01_02.xml!
  2. Examine the configuration files and the output files! Also use Via to check the movements of the user!
  3. Create an alternative network file called square_02_diagonal.xml. Add a two-way high speed (130km/h) road to the network between the square's corner node closest to the home and the one closest to the office (the simulator uses m/sec for speeds!). The length of the high speed road should be the physical length of the diagonal. Create a configuration named config_02_diagonal.xml that uses this alternative network.
  4. Run a simulation with this altered configuration!
  5. Change the length of the high speed road such that it is no longer beneficial to the user!

Questions

  1. What is the difference between this network topology and the one in the previous exercise? How does this affect the outcome of the simulation?
  2. How much does the high speed road increase the score of the daily plan of the user?
  3. What is the length above which the high speed road is no longer beneficial to the user?
  4. If instead of increasing the length of the high speed road, we would decrease the allowed speed, what is the speed under which it is no longer beneficial?

2. Programming with MATSim

So far we've been using MATSim as an application. In this part of the exercise you'll learn how to use MATSim as a program library. We'll need the following preparations first.

2.0. Preparations

Exercise

  1. Start the Eclipse development environment!
  2. The matsim project has already been created, and the Maven package manager has already downloaded the MATSim library along with its dependencies (these are specified in pom.xml). We only need to open and edit the appropriate source files.
  3. Start the MATSim GUI from Eclipse!
    Run > Run Configurations... > Java Application > New launch configuration
    Project: matsim, Main class: org.matsim.run.gui.Gui
  4. Run one of the configurations to see if it works!

2.1. Creating network file from an OSM map

Exercise

  1. Download a map segment from openstreetmap.org/export that contains the area surrounding the university (e.g. between Móricz square and the Danube). Use the Export option in the menu at the top. It is important not to export a map that is too small, there have to be alternative routes for the simulations later.
  2. Open the RunPNetworkGenerator class in the development environment. This class can use MATSim to convert the map in OSM format to a network that the simulator can use. By the way, this is the origin of this class.
  3. Adjust the osm field to the downloaded file, and the parameter of the write method of NetworkWriter to a good output directory. Keep the output file name as network.xml. Note that paths starting with a dot are relative to the current working directory, which can be anywhere in the Eclipse workspace, so it's best to avoid that.
  4. Run this program! Create a new run configuration in Eclipse, where the RunPNetworkGenerator class supplies the main method.
  5. Create a new population file, where a lone student goes to the university to study from morning until evening! Choose a location for home and work activities on the map generated from OSM. The necessary coordinates can be read in Via in the top right corner, if you import the network file.
  6. Create a new configuration for MATSim, where the map imported from OSM is the network, and the lone student created in step 5 is the population. Run this scenario and examine the output!

2.2. Creating population from code

In this exercise you'll use a program to generate the daily plans of the agents for the simulation.

Exercise

  1. Open the RunPCreateDrivingAgents class in the development environment. Using this class we can generate users in bulk. By the way, this is the origin of this class.
  2. Modify this class to create 499 users (this is the maximum number Via allows with the free license) with the default daily plan.
  3. The home and work locations can be anywhere on the map.
  4. Set the input and output directories to appropriate values. It's best to set the output to be a new empty directory.
  5. Run this scenario and examine the output.
  6. Run the scenario created at the end of 2.1 with this new population.

3. Simulations with multiple iterations

Now we learn the real strength of MATSim: the evolutionary model. The framework will use a strategy to optimize the day of the users through multiple iterations.

3.1. Simple evolution

Exercise

  1. Load and run the config_03_01.xml simulation!

Questions

  1. What evolutionary strategy is used in this configuration?
  2. What parameters are tuned by this evolutionary strategy?
  3. By how much did the utility (score) of the user improve during the iterations?
  4. How many iterations does it take to reach the optimum? Hint: you may have to increase the iteration count.
  5. What parameter did the simulator tweak to reach the optimum? Can you create the optimal daily plan by hand?

3.2. Utility function

Exercise

  1. Load and run the config_03_02.xml simulation!

Questions

  1. What evolutionary strategy is used in this configuration? How does it optimize the daily plan of the user?
  2. Explain the parameters used in the utility function!
  3. Examine how close the user's plan got to the optimal plan during the iterations!
  4. Create the optimal plan for the user, and run the simulation! What is the achieved utility?
  5. Give an estimation on how many iterations it would take to reach this optimum from the original plan, then measure the number of iterations. How did you calculate the estimate?

3.3. The best day

Return to the map of the university and the daily plan of the 499 students that you created in exercise 2.2.

Exercise

  1. Create a configuration file that uses different evolutionary strategies (see the syllabus)!
  2. Create a scoring for the utility function that represents the needs of the students!
  3. Run the simulation, check what the optimal plan is!
  4. If the simulations run too slow, you can decrease the number of students.

Questions

  1. What evolutionary strategies did you use?
  2. What is the resulting optimum?
  3. How many iterations did it take to reach the optimum?