MATSim Data format (XML)

In this section of the manual we discuss the MATSim XML network and public transport format. The MATSim writer requires a PLANit network/zoning (and optionally a service network and routed services) memory model as input to be able to persist in MATSim XML format.

More general - and specific - information on MATSim can be found on their website: www.matsim.org. MATSim has no official user manual, but a good starting point is a book that has bundled a number of (white) papers on this open-source agent based platform, see User guide.

MATSim Basics

MATSim is a Java based open-source traffic simulator that uses agents for its vehicles. It is multi-modal and has various extensions that can be added to the core functionality.Its data format for its network and public transport schedule is straightforward and somewhat simplified compared to PLANit’s features, making it possible to convert any PLANit network to a MATSim network without loss of information (on the MATSim side).

MATSim and PLANit

Any PLANit network/zoning memory model can be converted into a MATSim network/transit (schedule) using the available writers (network/intermodal).

Examples on how to perform a network conversion from PLANit or another input format to MATSim are provided in the respective PLANit-Python and PLANit-Java reference sections of this manual.

MATSim and PLANit Road network

The MATSim network output is based on [http://www.matsim.org/files/dtd/network_v2.dtd]. PLANit can create MATSim network files based on its own macroscopic network representation.

MATSim Improved Geometry generation

MATSim links only carry two geolocations - for both extreme nodes - but it lacks any shaping internally. In larger networks and for longer links visualisation of MATSim networks is therefore somewhat confusing and chaotic because the shape of the road is largely lost. To overcome this problem the VIA visualiser (that supports MATSim) has defined an additional data format that provides the internal geometry of all MATSim links. This format can be found here: https://docs.simunto.com/via/layers/network.html

The MATSim writer has a feature to support the persistence of such detailed geometry alongside the MATSim network. This makes visualising networks (in VIA) much nicer. It is recommended to switch this on via the settings when relevant.

MATSim and Public transport

The MATSim writer supports public transport output, namely the stop facilities and (optionally) their transit schedule. Depending on what is available in the network and how the writer is configured. Public transport output for Matsim is based on http://www.matsim.org/files/dtd/transitSchedule_v2.dtd.

Currently, two possible approaches for supporting public transport conversions are included:

1. Export network + stop facilities, but not public transport services
2. same as 1) only now also generate a services schedule

Option 1) is available when the underlying PLANit network hs no services available but it does have information on Public transport infrastructure, e.g., when for example a network is parsed from OSM which does have information on poles and platforms but not so much on services. In that case the user can opt to generate supporting travel times by enabling the option for the MatrixBasedRouter support

To generate a MATSim pt schedule, PLANit needs to have a fully serviced network available, meaning both a service network and routed services need to be present for this to work. The MATSim writer can then produce a full transit schedule bar any transit fleet information as this is something that it not present in PLANit and will need to be generated separately.

MATSim MatrixBasedRouter support

There is an option to output the stop facilities in a simplified form via a CSV file. This enables you to use the MATSim matrix based (pt) router (see MATSim example). This is a simplified form of multi-modal assignment where public transport is included as a teleported mode rather than a simulated one, using the travel times between the stops of this CSV. If not explicit travel time matrix for this CSV stop file is created, then MATSim will generate one itself.

By default, generating the stops CSV file for this router is enabled. So, whenever any public transport infrastructure is persisted/converted, this file is created (unless it is explicitly switched off, or a schedule is being produced)