Package org.matsim.core.controler

The Controler is responsible for complete simulation runs, including the initialization of all required data, running the iterations and the replanning, analyses, etc.

Package Maintainer:

  • Marcel Rieser

Parameters:

  • outputDirectory
    Type and range: ...
    Default: ...
    Description: ...
  • firstIteration
    Type and range: integer >= 0
    Default: ...
    Description: ...
  • lastIteration
    Type and range: integer >=1000
    Default: ...
    Description: ...
  • routingAlgorithmType
    Type and range: ...
    Default: ...
    Description: ...
  • runId
    Type and range: String
    Default: ...
    Description: ...
  • enableLinkToLinkRouting
    Type and range: ...
    Default: ...
    Description: ...
  • eventsFileFormat
    Type and range: ...
    Default: ...
    Description: ...
  • writeEventsInterval
    Type and range: ...
    Default: ...
    Description: ...

Details

Conceptual Structure

The Controler has three main parts:

  • Execution – Mobility simulation
  • Scoring
  • Replanning
These three parts are repeated in a loop and build the iterations. By default, Scoring and Replanning refers to plans, but it could as well be done for facilities, traffic lights, etc.
The Controler offers several extension points, where additional functionality can be plugged in. These extension points are realized with Events and Listeners: Classes can implement one or more Listener Interfaces and can be registered with the Controler with addControlerListener(). The Controler sends Controler Events at the corresponding points during the run to the registered Listeners, at which point the Listeners can execute their own code.
Currently, the following Events (and corresponding Listeners) are available: 
 [The iteration loop of the Controler]

 +-----------+                +----------------+         +-----------+            +------------+
 |Startup (1)|-->(2)--->(3)-->|Execution/MobSim|-->(4)-->|Scoring (5)|-->(6)--+-->|Shutdown (8)|
 +-----------+       ^        +----------------+         +-----------+        |   +------------+
                     |                                                        v
                      \                    +--------------+                  /
                        ---------------<---|Replanning (7)|<----------(2)<---
                                           +--------------+
  • (1) Startup
  • (2) Iteration Starts
  • (3) Before Mobsim
  • (4) After Mobsim
  • (5) Scoring
  • (6) Iteration Ends
  • (7) Replanning
  • (8) Shutdown
All Events are issued when Controler.run() is called. When the Startup-Event is issued, the configuration as well as other data (plans, network, ...) are already loaded and initialized.

Best Practices

Using custom functionality

If you plan to write your own ControlerListener to provide additional functionality to MATSim, use the following class as a starting point for integrating your ControlerListener into the Controler: 
 import org.matsim.controler.Controler;
 import org.matsim.myfunctionality.MyFunctionality;

 class MyClass {
   public static void main(final String[] args) {
     Controler controler = new Controler(args);
     controler.addControlerListener(new MyFunctionality());
     controler.run();
   }
 }

Additional Configuration Parameters

If your additional functionality requires additional parameters in the configuration file, you can provide a custom Config-Group and load it in the constructor of your ControlerListener. When the configuration file will be parsed later, your config-group gets loaded with the settings from the file, and you can later on access the values. 
 class MyFunctionality implements StartupListener {
   final MyConfigGroup settings = new MyConfigGroup();

   public MyFunctionality(final Controler controler) {
     controler.getConfig().addModule("my_functionality", this.settings);
   }

   public void notifyStartup(final StartupEvent event) {
     int value = this.settings.getMyValue();
   }
 }