The MATSim Open Template Scenario

This template was developed in 2023. We find it quite difficult to update because there are no regression tests. At VSP, we instead prefer to start from an existing more modern scenario. As of now (may'25), this is the matsim-lausitz scenario. So if you are at VSP, please do not start from this scenario-template, but talk with your collegues and/or to Kai Nagel. kai, gregorL, may'25

When using this template make sure to adapt it as needed:

• [ ] Rename Run-Class in src/main/java folder
• [ ] Modify config in input
• [ ] Update pom.xml
  • [ ] Name, description and version
  • [ ] Main class
• [ ] Makefile
• [ ] Update CITATION.cff (Authors and version)
• [ ] Modify calibration.py in src/main/python
• [ ] If you would like to chain jobs in SLURM, you can find the corresponding bash script for this functionality in src/main/sh
  • [ ] In this script, you can specify the number of chained jobs (max_nojob), which can be found at the top.
  • [ ] Then you'll have to define your job script. The current setup calls runCalib.sh, which in turn calls the calibrate.py script.
• [ ] Update README.md (This file)
  • [ ] Change Name and URLs
  • [ ] Check whether you are using Senozon data and change it according to your license agreement.
  • [ ] Badges
  • [ ] Remove this TODO list when done

About this project

This repository provides an open MATSim transport model for [name], provided by the Transport Systems Planning and Transport Telematics group of Technische Universität Berlin.

This scenario contains a 25pct sample of [name] and its surrounding area; road capacities are accordingly reduced. The scenario is calibrated taking into consideration the traffic counts, modal split and mode-specific trip distance distributions.

Licenses

The MATSim program code in this repository is distributed under the terms of the GNU Affero General Public License v3.0. The MATSim program code are files that reside in the src directory hierarchy and typically end with *.java.

The MATSim input population is licensed under the Creative Commons Attribution CC-BY-NC 3.0 DE License and was provided in its initial version by Senozon Deutschland GmbH.

The MATSim input files, output files, analysis data and visualizations are licensed under a Creative Commons Attribution 4.0 International License.
MATSim input files are those that are used as input to run MATSim. They often, but not always, have a header pointing to matsim.org. They typically reside in the scenarios directory hierarchy. MATSim output files, analysis data, and visualizations are files generated by MATSim runs, or by postprocessing. They typically reside in a directory hierarchy starting with output.

Other data files, in particular in original-input-data, have their own individual licenses that need to be individually clarified with the copyright holders.

Note

Handling of large files within git is not without problems (git lfs files are not included in the zip download; we have to pay; ...). In consequence, large files, both on the input and on the output side, reside at https://svn.vsp.tu-berlin.de/repos/public-svn/matsim/scenarios/countries/de/leipzig .

Run the MATSim Template scenario

The [name] scenario has a command line interface providing the following options:

It can be used by using either of these methods:

... using an IDE, e.g. Eclipse, IntelliJ - Alternative 1: use cloned/downloaded matsim-[name] repository

(Requires either cloning or downloading the repository.)

1. Set up the project in your IDE.
2. Make sure the project is configured as maven project.
3. Run the JAVA class src/main/java/org/matsim/run/RunTemplateScenario.java.
4. "Open" the output directory. You can drag files into VIA as was already done above.
5. Edit the config file or adjust the run class. Re-run MATSim.

... using a runnable jar file

(Requires either cloning or downloading the repository and java)

1. Open the cmd and go to your project directory
2. Build the scenario using mvnw package
3. There should be a file directly in the matsim-template directory with name approximately as matsim-template-1.0.jar.
4. Run this file from the command line using java -jar matsim-template-1.0.jar --help to see all possible options.
   1. For example, one can disable lanes or run the 25pct scenario using the available options
5. Start this scenario using the default config by running java -jar matsim-template-1.0.jar
6. "Open" the output directory. You can drag files into VIA as was already done above.