Package org.matsim.core.controler

Packages
package	corelisteners
package	events
package	listener

Classes
class	AbstractController
class	AbstractModule
interface	AllowsConfiguration
class	Controler
class	ControlerDefaults
class	ControlerDefaultsModule
interface	ControlerI
interface	ControlerListenerManager
class	ControlerListenerManagerImpl
class	ControlerUtils
interface	Controller
class	ControllerUtils
class	DefaultPrepareForSimModule
class	ExplodedConfigModule
class	Injector
interface	IterationCounter
class	MatsimRuntimeModifications
interface	MatsimServices
class	MatsimServicesImpl
class	NewControler
class	NewControlerModule
class	OutputDirectoryHierarchy
class	OutputDirectoryLogging
interface	PersonPrepareForSimAlgorithm
interface	PrepareForMobsim
class	PrepareForMobsimImpl
interface	PrepareForSim
class	PrepareForSimImpl
class	PrepareForSimUtils
class	ReplayEvents
class	TerminateAtFixedIterationNumber
interface	TerminationCriterion
class	XY2LinksForFacilities

Detailed 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:

• <font color="blue">outputDirectory</font>
  Type and range: ...
  Default: ...
  Description: ...
• <font color="blue">firstIteration</font>
  Type and range: integer >= 0
  Default: ...
  Description: ...
• <font color="blue">lastIteration</font>
  Type and range: integer >=1000
  Default: ...
  Description: ...
• <font color="blue">routingAlgorithmType</font>
  Type and range: ...
  Default: ...
  Description: ...
• <font color="blue">runId</font>
  Type and range: String
  Default: ...
  Description: ...
• <font color="blue">enableLinkToLinkRouting</font>
  Type and range: ...
  Default: ...
  Description: ...
• <font color="blue">eventsFileFormat</font>
  Type and range: ...
  Default: ...
  Description: ...
• <font color="blue">writeEventsInterval</font>
  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 org.matsim.core.controler.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();
  }
}