feat: documentation section dedicated to standalone mode choice

README.md

@@ -22,6 +22,7 @@ respective repositories.
 Additional topics:
 - How to [cut out smaller parts of existing simulations](docs/cutting.md).
 - How to [run a simulation with on-demand mobility services](docs/on_demand_mobility.md) (as a main mode and as a transit feeder).
+- How to [run the discrete mode choice model as a standalone](docs/standalone_mode_choice.md)
 
 ## Main reference
 

docs/standalone_mode_choice.md

@@ -0,0 +1,30 @@
+# 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.
+
+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()`.