MATSim Episim Example

This repository contains an example project for an epidemic simulation based on MATSim, provided by the Transport Systems Planning and Transport Telematics group of Technische Universität Berlin.

The internal code and core models can be found at https://github.com/matsim-org/matsim-episim-libs.

How to use Episim

The Maven build system is required to build the example project. This repository comes with a Maven wrapper script that can be used if Maven is not already installed on the pc.

In order to perform an epidemic simulation you first need a MATSim events file. To get started you can also use a provided event file from the OpenBerlin Scenario.

It is best to edit the scenarios with your IDE from the org.matsim.run package. In org.matsim.run.modules you can find example scenarios that you may adapt or use, to create your own configuration. To run them you can create a standalone jar file with:

./mvnw package

and run it with (where OpenBerlinScenario is the name of the scenario you want to run):

java -jar matsim-episim-example-1.0-SNAPSHOT.jar --modules org.matsim.episim.run.modules.OpenBerlinScenario

Generating mobility traces events file

If you have a MATSim scenario you can also create your own event file to be used for an epidemic simulation. All that is needed is the population and the event file of one iteration.

Run DownSampleScenario to extract the necessary information:

java -jar matsim-episim-example-1.0-SNAPSHOT.jar scenarioCreation downSample 0.1 \
    --population <Path to plans.xml> --events <Path to events.xml>

This example will write a 10% sample into output that can be used in the subsequent steps.

Batch Runs

The BatchRun class allows running one scenario many times with a different parametrization (possibly in parallel).

java -jar matsim-episim-example-1.0-SNAPSHOT.jar runParallel \
    --setup org.matsim.episim.run.batch.OpenBerlinBatch \
    --params org.matsim.episim.run.batch.OpenBerlinBatch$Params

The OpenBerlinBatch class shows how such a batch run can be defined. It is also possible prepare executable scripts for running the batch on a cluster:

java -jar matsim-episim-example-1.0-SNAPSHOT.jar createBattery \
    --setup org.matsim.episim.run.batch.OpenBerlinBatch \
    --params org.matsim.episim.run.batch.OpenBerlinBatch$Params

Licenses

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

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.

More information

For more information about the methodology and preliminary results, see our website at https://covid-sim.info/ .

For more information about MATSim, see here: https://www.matsim.org/.