Introducing MC: An Open-Source Tool for Configuring MATSim

Why we built it, and how it enables really big — but still useful — simulations.

Fred is the Technical Lead at Arup’s City Modelling Lab, where he is working on implementing really big — but still useful — simulations.

MATSim configs

We (City Modelling Lab) use MATSim to run simulations. MATSim is a large and long-lived project and as such has a few quirks and awkward interfaces. One of these is the MATSim config(uration). A MATSim config contains all the choices we make about how the simulation should run, including how vehicles and agents should behave within the simulation. MATSim configs use an xml structure, composed of modules, parameter sets, nested parameter sets and parameters.

Because of their size and complexity, building a MATSim config from scratch is hard. Even when modifying an existing config, we used to make a lot of mistakes. Sometimes simple syntax errors that we’d catch reasonably early. But often more nuanced bugs that would painfully emerge later in our pipeline. Worst of all we’d individually and collectively repeat these errors. So, we set about building something to help make and validate these configs. Enter MC.

MC

Under the hood, MC uses a python dictionary representation of a config. After loading a config or starting a new config, this exposes some handy methods such as python dictionary like getting and setting.

import mc
empty_config = mc.build.Config()
empty_config['global']['coordinateSystem'] = “EPSG:27700”
empty_config.write(PATH)
config =  mc.build.Config(PATH)
print(config['global']['coordinateSystem'])
> “EPSG:27700”

That’s nice but how does it help? Well in short, MC won’t let you make common mistakes:

empty_config = build.Config()
empty_config['typo']['coordinateSystem'] = 'EPSG:27700'
> KeyError: "key:'typo' not found in modules"

This is the underlying mechanic of MC. For more everyday use MC provides a command line interface (CLI) with a few handy commands such as `print`, `diff` and `debug`. You can read about these in more detail in the documentation here.

Orchestrations

Several years pass and things have changed. We make slightly less errors with our configs. But we are now running loads more simulations and having to edit a config each time.

An example pain point is if we want to run a batch of 25 simulations at the same time, maybe to test 5 different costs (very low, low, medium, high, very_high) for travel by bus and 5 different costs (very low, low, medium, high, very_high) for travel by train. Using cloud infrastructure, we can now spin up 25 big simulations on 25 big computers no problem, but someone still needs to manually set up 25 matsim configs, each with their unique costs of using the bus and train.

In this case MC allows us to send concise commands to the cloud and our state machines that modify our configs as required. The above scenario is now orchestrated with the following “batch” config:

{
  “very_cheap_bus_very_expensive_train_scenario”: {
    “modeParams:bus/monetaryDistanceRate”: “-0.001”,
    “modeParams:train/monetaryDistanceRate”: “-0.005”
  },
  “cheap_bus_very_expensive_train_scenario”: {
    “modeParams:bus/monetaryDistanceRate”: “-0.002”,
    “modeParams:train/monetaryDistanceRate”: “-0.005”
  },
... # etc
}

Under the hood MC is using a config.find() method, such that we can send more concise commands to find and then change specific parameters or groups of parameters within an existing config. The find method allows control over which modules, paramer-sets and parameters should be considered.

We can now programatically create new configs based on some meta configuration or logic. Perhaps as part of a random search algorithm for example:

def mutate_config(
    path,
    find = "monetaryDistanceRate",
    candidates = [1,2,3,4]
):
    config = build.Config(path)
    for param in config.find(find):
        param.value = str(random.choice(candidates))
    config.write(path)

… and usefully the underlying MC mechanics still try to stop us doing anything too stupid.

Final Thoughts

MC is now the glue that makes a lot of our cloud orchestrations convenient and in some cases possible, allowing us to more easily and more reliably spin up loads of simulations, using lots of compute. Ultimately MC will support programmatic changes to configurations, for example supporting automatic calibration of simulations via massive parameter space explorations. The long term aim of this is to build and calibrate really big MATSim simulations really fast and really easily.

So was this sensible?

Perhaps not — stepping back — we built a tool to help us use another tool by manipulating configuration files. Some of our functionality might better have been added to MATSim directly. But perhaps other bits shouldn’t and as our requirements become more complex this increasingly becomes the case.

Worst case is that MC helps people from a python background get working with MATSim which is a Java project with a steep learning curve (“just read The Book” they say). We hope that by sharing MC — we might ease a few learning curves.

If you do (or don’t) like MC, if you wish it did something better or something new, you can raise issues via the Github repo or contact us at citymodelling@arup.com.