MATSim: an agent-based toolbox for large-scale transport simulation

A toolbox of replaceable parts, not a simulation application

MATSim provides a toolbox to run and implement large-scale agent-based transport simulations. The description in the README says the toolbox consists of several modules which can be combined or used stand-alone, and that modules can be replaced by own implementations to test single aspects of your own work.

That last clause is the one that matters for adoption. This is not an application you configure and run. It is a set of parts where the point is that you can swap one out. A planning team that wants to change how the simulation represents driver behaviour, or how it costs a trip, or how it assigns modes, does that by writing their own implementation of a module and plugging it in, not by editing a configuration file.

The scope of the toolbox as described covers demand modelling, agent-based mobility simulation, which the README calls traffic flow simulation, re-planning, a controller to iteratively run simulations, and methods to analyze the output generated by the modules.

Those five pieces are the standard structure of an agent-based transport model, and the controller is the part that makes it iterative rather than one-shot. Because a simulation that lets agents replan does not settle after a single pass, you need a loop that runs the simulation, lets agents adjust, and runs it again, with the iteration converging towards a state where nobody wants to change their plans. That loop is what the controller module provides, and it is the difference between a toy and something you can use to compare policy options.

The audience is a transport planner, a researcher or a consultancy team with a model to build, not a city asking for an answer. The topics back this up: agent-based, agent-based-model, agent-based-simulation, matsim, simulation and transportation-planning. The project website is www.matsim.org, the primary language is Java, and the default branch is main.

The repository layout: one core module and a long tail of contribs

The top-level entries describe the structure of the project, and they describe the relationship between the core and everything else.

The matsim/ directory is the core module. The contribs/ directory holds the extensions, and the README says the full list of available extensions can be found in the contribs folder. There are also examples/ with a scenarios/ directory, a src/ directory, its own pom.xml and a .externalToolBuilders/ directory, plus code-examples/ and benchmark/ at the root.

That examples/ and code-examples/ split is worth understanding. The examples directory carries scenarios, which in this domain means the input files that describe a place and the agents moving through it, the population, the network and the configuration, together with the Java code that starts the simulation. The code-examples repository is referenced separately in the README as where code examples live, and there is a separate matsim-example-project repository with a complete pom.xml, which is the intended starting point for your own project rather than forking the toolbox.

The benchmark/ directory at the root is a separate concern again, and it points at the performance side of the project. A transport simulation of a metropolitan region with millions of agents is a serious computation, and the fact that there is a benchmark directory suggests the project treats performance as something to track rather than to hope for.

The build tooling is Maven, with a single pom.xml at the root, and there is a Makefile whose header comment states plainly that it is not a makefile to compile matsim, but instead performs certain maintenance helper tasks. That is an unusual and honest arrangement. The targets include hybridsim, which builds the examples, the core and two contribs in turn, a release target, matsim-quick and a quick target that runs a full clean install with a set of skip flags, and a QUICK variable that carries those flags:

quick:
	mvn clean install ${QUICK}

The flags themselves are the point of that target. They skip the tests, skip the javadoc, skip the source assembly and skip the assembly packaging, and they run offline, which is what you want when you want the artefacts fast rather than the checks.

Building with Maven, and installing only the core

The build instructions in the README are short, and they include one warning that saves time.

The warning is about the directory. Build by running the command from this directory, not any sub-directory. That is a detail people hit exactly once, usually by cd-ing into the module they are working on, and then wondering why the reactor behaves oddly.

The full build is a single Maven goal:

mvn package -DskipTests

And if you only want the core, the README gives a narrower command:

mvn install --also-make --projects matsim

That second one is the more interesting of the two. The core module is what most people actually need, since it carries the simulation engine and the machinery the other modules build on, and installing just it means your own project pulls in one artefact rather than the whole family. The also-make flag ensures the dependencies of the selected project are built too, so you do not end up with a broken local repository.

The quick target in the Makefile is the third option, and it differs from both by skipping the slow parts. A full package build for a codebase this size will spend a noticeable amount of time on javadoc, test execution and assembly, and if you are iterating on a scenario rather than on the code, you do not want that in the loop.

The README does not state a Java version, a Maven version, or a memory requirement, which are the three things you would want to know before kicking off the first build on a large project. Those details are presumably in the CONTRIBUTING.md file or on the project website, and they are the first thing to check.

The tools the build expects also matter in practice. The .externalToolBuilders/ directory in the examples module tells you that the example scenarios need external software prepared for them, and if you are going to run the shipped scenarios rather than your own, that directory is where you find out what has to be installed.

Where the artefacts come from: releases, pull request builds, weekly builds, snapshots

Binaries for MATSim are published to repo.matsim.org, and the README is specific that this includes releases, which also come in PR-based and weekly flavours, and snapshots.

That is a richer publication model than a single release stream, and for a research codebase it makes sense. The annual releases are the ones you cite and pin, and the README records them as 2024.0 (MATSim 2024 Spring), 2025.0 (MATSim 2025 Spring) and 2026.0 (MATSim 2026 Spring), the last tagged on 2026-04-10. The naming convention encodes the year and the season rather than a semantic version, which tells you the project has an annual, scheduled release rhythm rather than continuous versioning.

The pull request based releases and the weekly releases serve a different purpose. They mean you can depend on a build that contains a specific change, and that a specific branch state is continuously available, without waiting for the spring release. For a group collaborating on a scenario or an extension, that is the difference between testing a pull request and waiting months for it to be in a tag.

Snapshots, in the usual Maven sense, are the moving edge of the build. They are the thing to use when you want the newest code and accept that it is newest.

The continuous integration configuration in the repository mirrors this. There are badges for a deploy on pull request merge, a weekly deploy, a full integration build described as a daily release-like build, a weekly code coverage run for the matsim module only, and a Codecov badge scoped to the same module. The split between the full integration run and the module-only coverage run is a sensible cost control: the expensive, everything-must-pass check runs on a daily cadence, while the per-module coverage instrumentation is run more often but only for the core.

There is also a .gitlab-ci.yml in the root, so the project is built on both hosted CI systems, and a Makefile release target that goes through a specific playground project and a release profile, which is a hint about how the release artefacts are actually assembled.

Starting your own model from the example project

The README points at a repository for getting started with your own project, including a complete pom.xml, at matsim-example-project, and a separate repository of code examples. The distinction between them is the one to get right when you begin.

The example project is a project, with a build file and a structure you copy. The code examples are snippets that show how to do a specific thing with the API. One is a starting point, the other is a reference, and mixing them up is a common way to spend a day.

The structure of the examples/ directory in this repository shows what a MATSim project looks like in practice. There are scenarios/, which hold the data and configuration for a simulation, src/ for the Java that starts it, and a .externalToolBuilders/ directory that prepares external tools the scenarios need. The presence of scenarios/ separate from src/ is the design decision worth internalising: your model is a directory of files, and the Java code is thin by comparison.

That arrangement is what makes MATSim iterable. A transport scenario is a large collection of data, the population, the network, the vehicle definitions, the activity plans, and the configuration, and iterating on it means editing data, not recompiling. The Java side is the machinery that loads those files and runs the simulation.

For a new user, the path the documentation implies is to take the example project, run a shipped scenario to see the engine work, then replace the data with your own place and your own population. The FAQ at matsim.org/faq is pointed to from the README as the place to look for answers, and the issue tracker lives at matsim.org/issuetracker, so the project runs a public support channel alongside the code.

One caution belongs here. The data format for scenarios is not something the README documents, so expect to spend time reading the example scenarios and the extensions in contribs/ to work out what a valid input looks like. That is normal for this kind of codebase and it is the main reason the example project exists.

Where MATSim is the wrong tool

The first limitation is that the hardest part of the work is not in the toolbox. MATSim gives you a simulation engine, a controller and analysis methods, and it does not give you a demand model for your city, a road network, a synthetic population, or calibrated parameters. The quality of a MATSim result is a function of the demand model that feeds it, and a badly specified model produces confidently wrong answers. If your problem is to predict travel demand rather than to test a policy against a demand model you already have, this is the wrong level of abstraction.

The second is that it is a research codebase with a research footprint. The Java build, the Maven multi-module layout, the contribs/ directory of extensions maintained by different people, and the annual spring release naming all point to a project run by academics with academic time. That is a strength for the method and for the community, and a weakness if you need a commercial support contract or a predictable quarterly release.

The third is that the licence is not identified in the project record. The repository is described as having a licence that cannot be classified, and the visible top-level entries do not include a licence file, only a README, a Makefile, a CONTRIBUTING.md and the code. For an academic project that ships into consultancy work and public sector contracts, that is a question to answer before you build on it, and the project website is where the answer lives.

The fourth is the computational cost, which the presence of a benchmark/ directory hints at. A metropolitan simulation with a large synthetic population and an iterative replanning loop is not a laptop task. The README does not give memory or runtime guidance, and the CI configuration distinguishes a full integration run from module-only runs, which is the same message stated differently.

The fifth is scope. MATSim simulates transport. It is not a land use model, not a traffic microsimulation, not a discrete event simulation of an airport, and it does not do anything with freight or land use dynamics beyond what the extensions provide. If you need those, the contribs list is where you find out whether somebody has written one.

An annual release rhythm and a wide extension surface

The maintenance picture is straightforward. The repository is not archived and the last push was on 2026-10-19, days before this review, so the code is being worked on.

The release rhythm is annual and seasonal, with 2024.0 in April 2024, 2025.0 in April 2025 and 2026.0 in April 2026, each labelled as the spring release for that year. A year is a long time in software terms, but for a research platform where the method evolves slowly and the model code changes on a community cadence, it is a coherent choice, and the weekly and pull request builds exist to cover the gap between annual tags.

The repository is a Maven multi-module build with the core in matsim/ and everything else under contribs/, which is where the community contribution lands. The topics list includes the usual simulation vocabulary, and the presence of a benchmark/ directory, a codecov.yml and separate workflows for integration, coverage and deployment says the project takes its engineering seriously even though the release cadence is slow.

The main structural risk for a user is the one that comes with the extension model. If you build a serious model on MATSim, you will be relying on some extensions in contribs/, and those are maintained at whatever pace their authors choose. The annual tag gives you a stable core, but the extension set is the part that moves under you, which is an argument for pinning the whole dependency set and for checking the extension list before committing to a modelling approach.

On balance, MATSim is a good fit for a team with a transport question, the modelling skill to specify demand, and the patience to work with a research tool. It is a poor fit for a team that wants a planning answer next quarter with no modelling work of its own. The entry points the README gives are the right ones: the example project to start from, the FAQ for the conceptual questions, the issue tracker for the specific ones, and repo.matsim.org for the artefacts.

Editorial conclusion

Adopt MATSim if you need to test transport policy scenarios at metropolitan scale with agent-based dynamics and you are prepared to model demand and calibrate it, because the toolbox gives you the simulation engine and the analysis methods but not the data. Do not adopt it as a turnkey planning product, and do not expect it to produce credible results without calibration work, since the outputs reflect the demand model you supply. Verify first that the modules you need exist in the contribs list, that you can consume the artefacts from repo.matsim.org, and that the licence question is settled, because the licence is not identified in the project record, the releases are annual spring versions with the newest being 2026.0 from 2026-04-10, and the last push was on 2026-10-19.

Frequently asked questions

Official sources

1. Issues
2. matsim-org/matsim-libs on GitHub
3. README
4. Releases