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.

See:
Description

Class Summary

Controler	The Controler is responsible for complete simulation runs, including the initialization of all required data, running the iterations and the replanning, analyses, etc.
ControlerIO
ControlerListenerManager	Class encapsulating all behavior concerning the ControlerEvents/Listeners
MobsimFactoryRegister
MobsimRegistrar
SnapshotWriterFactoryRegister
SnapshotWriterRegistrar

Package org.matsim.core.controler Description

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();
   }
 }