Tutorials

We have prepared some tutorials which should help you getting started with MATSim.

The "General Tutorials" section provides the most in-depth tutorials.

Quickstart


(0) Download the release and unzip it.

 

(1) Go the the directory where you find matsim-*.jar .

 

(2) What follows here is really quite old.  For (1) and (2), you can now just click on the MATSim jar file.  What opens is what we call the MATSim GUI.  0.8.0 has some problems with the path names; 0.8.1 should work ...

Then type (if you opened the directory on explorer you need to open the command line and type the following command in there)

java -Xmx2000m -cp matsim-0.7.0.jar org.matsim.run.Controler examples/tutorial/config/example5-config.xml

This should produce a new output directory.  Meaning of the parameters:

  • -Xmx2000m : Increases the Java heap space to 2000MB of memory. If you have less memory, try smaller values, but the Java default is too small.
  • -cp matsim-0.7.0.jar : The jar file (Java library) which contains MATSim. The release number of the jar file you downloaded might be different from the one in this example (0.7.0), so make sure you type in a release number that corresponds to the version you downloaded.
  • org.matsim.run.Controler : The class where the main method for running "iterations" resides. 
  • examples/tutorial/config/example5-config.xml : The xml file that contains all of the configuration of the run.  The file can be edited.
Note: if you run the above "org.matsim.run.Controler" line again, you first need to erase the contents of the output directory.

 

(3) Now it is time to have a look at the output. 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 first iteration is located in output/ITERS/it.0/run0.0.events.xml.gz. This contains a lot of information that can be visualized. Now, when you start the visualizer (called Via, a free version is available for download), 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.

 

(4) The logfile, with the above example in output/example5/logfile.logcontains, between a lot of other information, also a dump of a 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 just 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.

MATSim example project

There is a matsim example project on github.  It allows to use all of the matsim main distribution as well as the contribs as maven-includes.  The setup allows both release versions and nightly snapshot version.  It is almost certainly the best way to go if you are somewhat familiar with maven and want to program against MATSim (i.e. use matsim as a library).

General Tutorials

Keeping a certain tutorial up to date has proven infeasible.  Two main problems are:

  • Different teachers/tutors have different styles, and thus have difficulties upgrading someone else's tutorial.
  • Different tutorials cover different parts of the material, and so the upgrade of "the" standard tutorial always was inconsistent between its different pieces.

We are now aiming for the following:

  • The standard intro reference is "The Book".
  • TU Berlin teaches a MATSim class during every summer term.  We plan to move the tutorial material of that class to the site here at the end of each term (i.e. around July/August of every year). The most current version is the 2016 course.

Additional material is available under matsim.org/javadoc --> main distribution --> tutorials.  That material may be a bit more difficult to find or read, but it has the advantage that it is inside the code repository and thus always compiling and in many cases even secured by a regression test.

2015: MATSim class at TU Berlin (matsim version 0.7.x)

N.B.! This tutorial is outdated! Please use it only, if you have to use MATSim 0.7.x for some reason!
Otherwise, use the 2016 tutorial!
 

This is a summary of tutorials of the MATSim class at TU Berlin which is held each year during the summer term. The tutorials provide a step-by-step installation and usage guide for creating your own scenario and policy cases. It does not always go too much into detail (as it is usually taught in a very responsive way in a classroom), so if you need more details about a certain topic, please also consult the MATSim book. All code snippets in this tutorial are direct links to the Github repository of Matsim release 0.7.0 (June 2015). It is not recommended to use any other MATSim version with this tutorial.

Access: The tutorial lies within TU Berlin's e-learning system ISIS but is open for guests.

==> Click here to get to the course. <==

To access as a guest, click "Als Gast" and accept the Terms&Conditions, just as in the following two pictures:

2016: MATSim class at TU Berlin (MATSim version 0.8.x)

This is a summary of tutorials of the MATSim class at TU Berlin which is held each year during the summer term. The tutorials provide a step-by-step installation and usage guide for creating your own scenario and policy cases. It does not always go too much into detail (as it is usually taught in a very responsive way in a classroom), so if you need more details about a certain topic, please also consult the MATSim book. All code snippets in this tutorial are direct links to the Github repository of Matsim release 0.8.0 (June 2016).

It is not recommended to use any other MATSim version with this tutorial.

Access: The tutorial lies within TU Berlin's e-learning system ISIS but is open for guests.

==> Click here to get to the course. <==

To access as a guest, click "Als Gast" and accept the Terms&Conditions, just as in the following two pictures:

MATSim book and user's guide

The MATSim book is a comprehensive introduction into MATSim.  Since books are a bit static, and software is dynamic, we provide an extract of some chapters as a user's guide. In contrast to the book, these chapters are regularly updated in conjunction with our annual MATSim class at TU Berlin, running from March until July every year.

Simulation of public transport

=================================================
The Transit Tutorial has moved to our Wiki.
=================================================

 

Requirements

For simulating public transport (pt) in MATSim, you need:

  • a network with links available to public transport vehicles
  • a file describing the available public transport vehicles
  • a file containing the public transport schedule
  • some specific settings in the configuration

In the following, those topics are described in more details. At the end of this tutorial, you find some example files that you can directly use to run a public transport simulation.

Network

Each link has a list of available transport modes. If no modes are specified, the simulation assumes that only "car" is allowed on such links. For public transport, you can add links with modes="train" or modes="bus", for example. It is also possible that links support more than one transport mode, e.g. modes="car,bus".

...
<links capperiod="1:00:00">
  <link id="1" from="1" to="2" length="1000.00" capacity="2000" freespeed="12" permlanes="1" modes="car" />
  <link id="101" from="101" to="102" length="1000.00" capacity="2000" freespeed="12" permlanes="1" modes="bus" />
  <link id="201" from="201" to="202" length="1000.00" capacity="2000" freespeed="12" permlanes="1" modes="train" />
  <link id="301" from="301" to="302" length="1000.00" capacity="2000" freespeed="12" permlanes="1" modes="bus,tram" />
  ...

Public Transport Vehicles

The description of pt vehicles can be split into two parts: In a first part, vehicle types have to be described, specifying how many passengers such a vehicle can transport (Note that the term "vehicle" can refer to multiple vehicles in reality, e.g. a train with several wagons should be specified as one long vehicle with a high number of seats). In the second part, actual vehicles have to listed. Each vehicle has an identifier and is of a previously specified vehicle type.

<vehicleType id="1">
  <description>Small Train</description>
  <capacity>
    <seats persons="50"/>
    <standingRoom persons="30"/>
  </capacity>
  <length meter="50.0"/>
</vehicleType>
<vehicle id="tr_1" type="1"/>
<vehicle id="tr_2" type="1"/> 

Public Transport Schedule

In the first part, the stop locations need to be defined, giving each a coordinate, an identifier and a reference to a link in the network. The stop can only be served by vehicles driving on that specified link.

<transitStops>
  <stopFacility id="1" x="1050" y="1050" linkRefId= "11"/>
  <stopFacility id="2" x="2050" y="2940" linkRefId= "24"/>
  ...

Optionally, one can also specify a name for the stop and if other vehicles are blocked when a pt vehicle is waiting at a stop. This last attribute is useful to model e.g. the difference of bus stops, where one bus stop has a bay, while at another stop, the bus has to stop on the actual road.

<transitStops>
  <stopFacility id="1" x="1050" y="1050" linkRefId= "11" name="2nd Street" isBlocking="true" />
  <stopFacility id="2" x="2050" y="2940" linkRefId= "24" name="Main station" isBlocking="false" />
  ...

After the stop locations, the different pt lines, their routes and schedules are described:

<transitLine id="Blue Line">
  <transitRoute id="1to3">
    <transportMode>train</transportMode>
    <routeProfile>
      <stop refId="1" departureOffset="00:00:00"/>
      <stop refId="2" arrivalOffset="00:03:20" departureOffset="00:04:00"/>
      <stop refId="3" arrivalOffset="00:07:20" departureOffset="00:10:00" awaitDeparture="true"/>
      ...
      <stop refId="n" arrivalOffset="00:28:00" />
    </routeProfile>
    <route>
      <link refId="11"/>
      <link refId="398"/>
      <link refId="24"/>
      ...
      <link refId="130"/>
    </route>
    <departures>
      <departure id="01" departureTime="06:00:00" vehicleRefId="tr_1" />
      <departure id="02" departureTime="06:15:00" vehicleRefId="tr_2" />
      ...
    </departures>
  </transitRoute>
</transitLine>

The transportMode describes on which links in the network this line runs.

The routeProfile describes the stops this route serves, while the route itself describes the series of links in the network the pt driver has to drive along. Note that the complete route, i.e. all links the vehicle drives along, must be listed in the route, and not only the ones where stops are located. All the specified stops should occur along this route in the specified order.  Details:

  • departureOffset and arrivalOffset refer to departureTime in "departures".
    E.g. arrivalOffset="00:03:20" means an arrival at "06:00:00"+"00:03:20", i.e. at "06:03:20".  Or at "06:15:00"+"00:03:20", i.e. at "06:18:20".
    E.g. departureOffset="00:04:00" means departures at "06:04:00" and "06:19:00".
    The resulting arrival and departure times are both used in the pt router: The departure time is the latest time to arrive at the stop, the arrival time is the scheduled arrival time at the destination. If the arrival time is not known, the departure time is used.
  • departureOffset is required for all stops except the last one
  • arrivalOffset is optional for all stops except the last one
  • awaitDeparture specifies that a transit driver should wait until the scheduled departure time if it is early at the stop. This is useful to ensure connections at larger stops.

The departures list the time, when a vehicle departs at the first specified stop. It also specifies, with which vehicle (defined in the file previously mentioned) the route is served.

Configuration [partially deprecated]

[The following is somewhat deprecated; see the config file in tutorial files for an up-to-date version.  Or you may have to look in your version of the code.]

In the configuration, you have to enable the simulation of public transport:

<module name="scenario">
  <param name="useTransit" value="true" />
  <param name="useVehicles" value="true" />
</module>

[This is now now longer necessary.  But see below in the "transit" config section.]

You have to use a mobility simulation that support public transport, currently this is only the so-called "QSim".

<module name="qsim">
  <param name="startTime" value="00:00:00" />
  <param name="endTime" value="30:00:00" />
</module>

It is strongly advised that you specify an end time for the simulation. Sometimes, if agents are too late, they arrive at pt stops way after the last bus/train/... departed and will thus wait at the station forever, and the simulation will also run forever.

The controler should write files in xml-format, as only this format supports the additional pt events:

<module name="controler">
  <param name="eventsFileFormat" value="xml" />
</module>

[This is not wrong but it is now also the default.]

If you want the agents to perform mode choice, add the mode choice replanning module:

<module name="strategy">
  <param name="ModuleProbability_*" value="0.1" />
  <param name="Module_*" value="ChangeLegMode" />
</module>

[Depending on your version of the code, this may be "ChangeTripMode" instead.  And if you are using the config v2 format, the syntax is somewhat different.]

This replanning module needs additional configuration:

<module name="changeLegMode">
  <param name="modes" value="car,pt" />
</module>

[Depending on your version of the code, this may be "changeMode" instead.]

Last but not least, you have to specify the paths to the additional pt-related input files:

<module name="transit">
  <param name="transitScheduleFile" value="transitschedule.xml" />
  <param name="vehiclesFile" value="transitVehicles.xml" />
  <param name="transitModes" value="pt" />
  <param name="useTransit" value="true" />
</module>

Demand / Population

If you enabled mode choice in the configuration, the agents will automatically start exploring the public transport services with the iterations in MATSim. Alternatively, you can also assign the mode "pt" (instead of "car") to agents' legs to tell the agents to use the public transport in the simulation.

Events

The pt simulation generates additional events related to the public transport:

  • TransitDriverStarts: This contains information about which driver departs at what time, specifying the transit vehicles the driver steers and along which line and route
  • VehicleArrivesAtFacilityVehicleDepartsAtFacility: contains information when a transit vehicle arrives and departs at a stop facility
  • PersonEntersVehiclePersonLeavesVehicle: contains information about passengers entering and leaving transit vehicles

These events allow you to build your own analyses, e.g. the number of passengers entering and leaving per stop facility, the average load of transit vehicles, etc.

The following figure shows the produced events for a single transit trip with two different line switches. On the left, you find events produced by the three transit lines and on the right the events of the person-agent.

click to enlarge

Example

The following steps allow you to run the provided example simulation:

  • Download the latest MATSim release
  • Unzip the release
  • Create a directory with the name "pt-tutorial" within the release-directory. The directory "pt-tutorial" should be on the same level as the "matsim-0.7.0.jar" or the "libs" directory included in the release.
  • Download the tutorial files and store them all inside the "pt-tutorial" directory
  • start a simulation with:
    java -Xmx512m -cp matsim-0.7.0.jar org.matsim.run.Controler pt-tutorial/config.xml
  • output will be generated into output/pt-tutorial, so make sure the output-directory exists (create it if missing) and is empty.