standalone_mode_choice.md

Running the Discrete Mode Choice Model as a standalone without an iterative simulation

Sometimes it can be interesting to run the mode choice model in standalone for the whole population without the iterative simulation process. This functionality is enabled by the org.eqasim.core.standalone_mode_choice package and the org.eqasim.core.standalone_mode_choice.RunStandaloneModeChoice class is its entry point. The class can be executed from the command line and it requires one parameter:

• config-path: a path to a MATSim config file The mode choice is performed via a StandaloneModeChoice module which is configurable via a config group defined by the org.eqasim.core.standalone_mode_choice.StandaloneModeChoiceConfigGroup class.

  The StandaloneModeChoiceConfigGroup can be included in the supplied config file. If it is not provided, one with the default settings is added and these settings can be set via the commandline using the config: prefix. Below the list of supported parameters:

  • outputDirectory: The directory in which the resulting plans will as well as the logfiles be written
  • removePersonsWithNoValidAlternatives: if set to true, persons with no valid alternative for at least one tour or trip will be removed in the resulting population

More parameters can be supplied via the command line:

• write-input-csv-trips: if specified, writes out the base trips and pt legs into a csv file called input_trips.csv and input_pt_legs.csv before performing the mode choice
• write-output-csv-trips: writes out the trips resulting from the mode choice, as well as pt legs, into csv files called output_trips.csv and output_pt_legs.csv in addition to the plans file
• travel-times-factors-path: if provided, should point out to a csv file specifying the congestion levels on the network during the day as factors by which the free speed is divided. The file in question is a csv with a header timeUpperBound;travelTimeFactor in which the timeUpperBound should be ordered incrementally.
• recorded-travel-times-path: mutually exclusive with the travel-times-factors-path. Points to a RecordedTravelTime file generated by a previous eqasim simulation. If neither a travel-times-factors-path nor a travel-times-factors-path is provided, the mode choice will assume a road network without any congestion.
• eqasim-configurator-class: The full name of a class extending the org.eqasim.core.simulation.EqasimConfigurator class, the provided configurator class will be instantiated and used to:
  • Detect optional config groups using the org.eqasim.core.simulation.EqasimConfigurator#addOptionalConfigGroups(Config) method
  • Configure the scenario using the org.eqasim.core.simulation.EqasimConfigurator#configureScenario(Scenario) before loading
  • Adjust the scenario using the org.eqasim.core.simulation.EqasimConfigurator#adjustScenario(Scenario) after loading
• mode-choice-configurator-class: The full name of a class the extending the org.eqasim.core.standalone_mode_choice.StandaloneModeChoiceConfigurator class. Since the EqasimConfigurator objects are usually used to configure the controller with all modules necessary for a full simulation, some of these modules might cause problems during a standalone mode choice. This is why you should implement a StandaloneModeChoice configurator and override the StandaloneModeChoiceConfigurator#getSpecificModeChoiceModules() to return only the modules necessary for mode choice.
• simulate-after: the full name of a class that can be used to run a one-iteration simulation after the mode choice. The provided class should be be runnable (having a static main(String[] args) that expect a config-path argument as well as arguments prefixed with 'config:' that can be used to override configuration elements.

In order to fully use it in your own use case, you need to implement a class extending the StandaloneModeChoiceModule class, your extension must have a constructor that matches the signature of the constructor present in the base class (taking a Config and a CommandLine as parameters). Then, override the getSpecificModeChoiceModules to return the modules necessary to configure the mode choice model only.

Note: Using travel times recorded by the VDFModule

If your scenario has been simulated before using the VDF functionality and want to use the travel times recorded by the VDFModule (usually in a vdf.bin file), you need to call the RunStandaloneModeCHoice with a config file where the eqasim:vdf module is configured with the inputFile pointing to the file you want to use. Moreover, you must not pass travel-times-factors-path or recorded-travel-times-path arguments.

For more details, you can check how this functionality is used in org.eqasim.TestSimulationPipeline#TestPipeline() and in org.eqasim.ile_de_france.TestCorisica#testCorsicaPipeline().