Install MATSim

Install

1. (optional but recommended) Fork matsim-example-project.
2. Clone matsim-example-project into local directory.
3. Import as Maven project into IDE. Maven will sort out the dependencies. No need to download the MATSim main repository. Sources are available.
   • IntelliJ: Import project → browse to directory → Maven → Next, Next, Next
   • Eclipse: Import … → … as Maven project → browse to directory → accept, accept, accept
4. Run MATSimGUI from the IDE.
   • An example config file is in scenarios/equil.
   • Press Run to run MATSim.
5. (optional but recommended) Run RunMATSim from the IDE.
6. (optional but recommended) Set up, for your forked repo, a continuous integration (CI) workflow. On the github website of your repo: Actions → New Workflow → More continuous integration workflows... → Java with Maven → Set up this workflow → Start commit → .... This will result in a file .github/workflows/maven.yml which triggers the automatic build after each commit. Detailed configuration of the workflow via this file is possible at a later point in time.

Notes

• Code examples are in matsim-code-examples on github. Also see there for examples of how to use extensions (package extensions).

• If you want/need to write your own extensions:

  1. Again, look at matsim-code-examples for examples.
  2. Look at ControlerDefaultsModule (in your IDE, source is retrieved by Maven) to see how MATSim is plugged together.

• You will not be able to modify the existing MATSim source code. This is an advantage, since it improves scientific reproducibility. If you feel the need to modify the existing MATSim source code, please use https://matsim.org/faq and we will try to help or implement missing extension points.

• You can generate a “clickable jar file” of your own code with mvn package. This could, for example, be passed on to students or clients for specific studies.

1. Download matsim-example-project and unzip it. There is an option “download zipfile”; no need to use git.
2. A clickable jar file is no longer provided, since they make the git repo too large. Instead, follow the instructions under “Building and Running it locally” at matsim-example-project.
3. As stated there, you will be able to double click on the generated MATSim jar file. What opens is what we call the MATSim GUI.
   • An example config file is in scenarios/equil.
   • Press Run to run MATSim.

The logfile contains, between a lot of other information, also a dump of the full matsim configuration. If there are interesting parameters, you could try to copy then into your own config file, modify them, and re-run.

In my (kn’s) view, one can actually get quite far in this way, i.e. by editing the config file. The main problem is how to obtain the network and in particular the so-called initial demand for your own scenario. If you can’t get that from somewhere else, it is probably better to go through the tutorial.

Latest Stable Release

Version 2024.0, released April 2024

• Download ZIP ca. 100 MB
• Older versions
• Even older versions (on sourceforge)

Development Version

This (= using a development version of MATSim via the GUI) is not recommended any longer. If you cannot work with a release, you should use the IDE and Maven.

(Pre-)Release

<repositories>
  <repository>
    <id>matsim</id>
    <name>MATSim Maven repository</name>
    <url>https://repo.matsim.org/repository/matsim/</url>
  </repository>
</repositories>
<dependencies>
  <dependency>
    <groupId>org.matsim</groupId>
    <artifactId>matsim</artifactId>
    <version>2024.0</version>
  </dependency>
</dependencies>

The example project on GitHub contains a valid pom.xml.

Extensions can be added in the same way; see the pom.xml in the code examples on GitHub

Automatic snapshot of development version

<repositories>
  <repository>
    <id>matsim</id>
    <name>MATSim Maven repository</name>
    <url>https://repo.matsim.org/repository/matsim/</url>
  </repository>
</repositories>
<dependencies>
  <dependency>
    <groupId>org.matsim</groupId>
    <artifactId>matsim</artifactId>
    <version>2025.0-SNAPSHOT</version>
  </dependency>
</dependencies>

These versions are typically less stable and don’t come with up-to-date documenation, but may contain new features.

When the simulation ran, many files were created in its output directory. Note that the GUI has a button to reach the output directory. One of the files is a so-called events file, typically generated for every 10th iteration. The events file for the zeroth iteration is located in .../ITERS/it.0/...0.events.xml.gz. This contains a lot of information that can be visualized.

The easiest way to visualize MATSim output is to use VIA. A free version, with a limit on the number of agents, is available for download. If you start VIA, you should see a large, black area. This is where the traffic will be visualized. On the left side of this area, you see a smaller area with 4 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 “+” 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 ‘+’ 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 ‘+’ 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.

SimWrapper

Another option for visualization is the free and open-source web app SimWrapper, online at simwrapper.github.io. SimWrapper can natively visualize MATSim output trips, carrier/freight/logistic systems, and public transport networks, and can also be used in combination with the open source matsim-r and matsim-python post-processing libraries to produce comprehensive output dashboards for traffic, emissions, noise, and more.

There is a matsim contrib which produces standard SimWrapper dashboards to get you started: you only need to add one line of code to your main function to produce a full-featured SimWrapper dashboards. Details are at github.com/matsim-org/matsim-libs/tree/master/contribs/simwrapper. Full documentation of the SimWrapper tool are online at simwrapper.github.io/docs.