tkchouaki commented 3 months ago

Intermodal DRT services.

This PR provides basic functionality for simulating intermodal DRT services where DRT serves as an access/egress mode for PT. This functionality is mainly enabled by a MultiModeFeederDrtModule that allows to define and simulate multiple intermodal drt modes. In this implementation, the intermodal routing is done heuristically by chosing closest PT stations from the origin and destination of the trip as access and egress stops. Whereas this feature is currently targeted for the combination between DRT and PT, some effort is already done here to be able to move towards a combination of PT and any other mode, and maybe later a combination of any main mode and any secondary mode for access and egress.

How to quickly use it

AdaptConfigForDrt

If your config file is already set to use DRT, you can skip to the next step. Otherwise, you need to first create a drt vehicles file. This can be done using the org.eqasim.core.simulation.modes.drt.utils.CreateDrtVehicles. Then you can run the org.eqasim.core.simulation.modes.drt.utils.AdaptConfigForDrt script introduced in #185 to generate a config file for DRT.
This scripts takes the following command line arguments:

input-config-path: (required) the path to base config file.
output-config-path: (required) the path to the resulting config file.
vehicles-paths: (required) a comma separated list of the paths of the drt vehicles files to use for the drt modes.
mode-names: (optional) a comma separated list of the names of the DRT modes to add to the configs. Default value is drt.
operational-schemes: (optional) a comma separated list of the operational schemes (door2door or stopbased or serivceAreaBased). Default value is door2door.
cost-models: a comma separated list of the names of the cost models to configure Eqasim to use in the estimation of the cost of drt trips. Default value is the ZeroCostModel.
estimators: a comma separated list of the names of the estimators to configure in eqasim to be used for the evaluation of trip alternatives using the new added drt modes. Default value is DrtUtilityEstimator.
qsim-endtime: the value by which the end time of the qsim module config will be replaced. Default value is 30:00:00.
mode-availability: if provided, will replace the modeAvailability in the DiscreteModeChoice config group.
configurator-class: the canonical name of a class extending the org.eqasim.core.simulation.EqasimConfigurator class. If provided, a configurator instance of this class will be used to load the input config file and handle potential extra config groups. Otherwise, the base EqasimConfigurator is used. Note that the class to use needs to be present in your classpath.

The comma separated list arguments are applied on the drt modes according to their respective order of appearence. However if one list contains only one element, that element will be applied on all the modes. Other configuration parameters to override at the end of the process can be supplied in the command line using the usual --config:module.param=value syntax.

AdaptConfigForFeederDrt

Then, use the org.eqasim.core.simulation.modes.feeder_drt.utils.AdaptConfigForFeederDrt script to further configure the config file obtained previously to support one or more feeder drt.

input-config-path: (required) the path to base config file containing the definitions of one or more DRT modes.
output-config-path: (required) the path to the resulting config file.
mode-names: a comma separated list of the names of the feeder drt modes to configure. Default value is feeder_drt
base-pt-modes: a comma separated list of the names of the main modes on which the feeder modes will rely to build the central segments. Default value is pt.
base-drt-modes: a comma separated list of the names of the access/egress drt modes on which the feeder modes will rely to build access and egress segments. Default value is drt.
access-egress-transit-stop-modes: a comma separated list of lists. Each inner list contains the transit modes (rail, tram...) that should be matched by transit stops where intermodality between pt and drt can happen. these modes are separated by a pipe | in the inner lists.
estimators: a comma separated list of the names of the estimators to configure in eqasim to be used for the evaluation of trip alternatives using the new added modes.
mode-availability: same function as the mode-availability argument detailed above.
configurator-class: same function as the configurator-class argument detailed above.

Same as above, the comma separated list arguments are applied on the drt modes according to their respective order of appearence. However if one list contains only one element, that element will be applied on all the modes. The script also add activityParams for the stage activities related to the new modes. Finally, this script adds to org.eqasim.core.simulation.modes.feeder_drt.mode_choice.constraints.FeederDrtConstraint into the configuration of the DiscreteModeChoice module.

XML config format

The MultiModeFeederDrt config can also be edited directly in the xml. Below an example:

<module name="multiModeFeederDrtModule" >
  <!-- Whether or not to perform the analysis for feeder drt services. If set to true, will follow the analysis interval specified in the configuration of the eqasim module -->
  <param name="performAnalysis" value="true" />
  <parameterset type="feederDrt" >
    <!-- The name of the drt mode to use for access and egress segments -->
    <param name="accessEgressModeName" value="drt_for_feeder_b" />
    <!-- Mode which will be handled by PassengerEngine and VrpOptimizer (passengers'/customers' perspective) -->
    <param name="mode" value="feeder_b" />
    <!-- The name by which the pt mode is known to the agents. Most usually pt -->
    <param name="ptModeName" value="pt" />
    <parameterset type="accessEgressStopSelector" >
        <parameterset type="closestAccessEgressStopSelector" >
        <!-- Comma separated list of PT transit modes (rail, bus...) where intermodality can happen, leave empty to allow intermodality everywhere -->
        <param name="accessEgressTransitStopModes" value="rail,tram,subway" />
        <!-- A regex that if matches with the from facility id (resp to facility id) will result in an access (resp egress) drt leg not being constructed. Leave empty to consider access and egress segments at all times -->
        <param name="skipAccessAndEgressAtFacilities" value="outside" />
        </parameterset>
    </parameterset>
  </parameterset>
  <parameterset type="feederDrt" >
    <param name="accessEgressModeName" value="drt_for_feeder_a" />
    <param name="mode" value="feeder_a" />
    <param name="ptModeName" value="pt" />
    <parameterset type="accessEgressStopSelector" >
        <parameterset type="closestAccessEgressStopSelector" >
        <!-- Comma separated list of PT transit modes (rail, bus...) where intermodality can happen, leave empty to allow intermodality everywhere -->
        <param name="accessEgressTransitStopModes" value="rail,tram,subway" />
        <!-- A regex that if matches with the from facility id (resp to facility id) will result in an access (resp egress) drt leg not being constructed. Leave empty to consider access and egress segments at all times -->
        <param name="skipAccessAndEgressAtFacilities" value="outside" />
        </parameterset>
    </parameterset>
  </parameterset>
</module>

The example above defines two intermodal feeder drt services relying on two separate drt modes for access and egress. Both allowing intermodality at transit stops located on rail, tram and subway pt routes. Whereas adding this to your xml config is enough to make the routing and simulation of feeder modes possible. Further configuration of eqasim is needed to fully support these modes in the mode choice. This is what the AdaptConfigForFeederDrt script is for.

Implementation details

The developments related to this feature are primarily added in the org.eqasim.core.simulation.modes.feeder_drt package.

Simulation and routing side

This feature is primarily allowed by the MultiModeFeederDrtModule which is inspired by the MultiModeDrtModule of the drt contrib. Each Feeder Drt mode is set-up by a FeederDrtModeModule which adds a FeederDrtRoutingModule responsible of computing routes.

During initialization, the FeederDrtRoutingModule identifies all the possible access and egress stations from the transit schedule using its related accessEgressTransitStopModes parameter.
Then, when calculating routes, closest stops to the origin and destination are respectively identified as access and egress facilities. A first DRT segment is built from the origin to the access stop using the DRT router. Then a PT segment from the access to the egress stop is built using the PT router. Then another DRT segment from the egress stop to the origin. However, if the DRT router fails to calculate one of the access and egress segments, the PT route is prolonged to either start from the origin or end at the destination of the trip. The final trip then contains either 1, 2 or 3 segments, so possibly no DRT segment at all. The plan elements generated by the router is a concatenation of the plan elements generated by the DRT and PT routers for each segment separated by interaction activities. These activities are equipped with a previousSegmentType attribute (instance of the FeederDrtRoutingModule.FeederDrtTripSegmentType enum) that specifies whether the previous segment is a PT segment (MAIN) or a DRT segment (DRT). Important: A special case is when an intermodal route is to be calculated from or to and outside facility. We assume that the rest of the chain before or after that facility consists in a PT trip. Se we do not insert a DRT trip in order to keep that continuity. The intermodal route will then consist of at most two segments.

Analysis

A FeederDrtAnalysisModule is implemented in the analysis package allowing to generate eqasim_feeder_drt_trips.csv file containing the details of trips performed with an intermodal drt mode. This module is used only if the performAnalysis of the MultiModeFeederDrt config is set to true. In which case the the frequency of analysis follows the one defined for other eqasim analyses in the eqasim.analysisInterval. The run.RunFeederDrtPassengerAnalysis allows to perform the analysis from simulation outputs.

Mode choice integration

This PR comes with a FeederConstraint that ensures that the route of a feeder drt alternative contains at least one PT and one DRT leg as this is not ensured by the router. Morevoer, a basic utility estimator for feeder drt modes is proposed here (DefaultFeederDrtUtilityEstimator). It simply treats the segments as a sequence of trips and delegates the evaluation of each segment to the utility estimator of its related mode (PT or DRT) and sums the values. This requires the estimators to be defined properly in the config.

You will still need to modify your mode availability for the new modes to be considered in the mode choice. If you just want to enable them for all agents, you can wrap your existing ModeAvailability object under the org.eqasim.core.simulation.modes.feeder_drt.mode_choice.FeederDrtModeAvailabilityWrapper, this will add all feeder modes declared under the MultiModeFeederDrt config as well as the drt modes under the multiModeDrt config that are not covered by a feeder mode.

sebhoerl commented 3 months ago

Really nice, looks good! :) Maybe it is time to provide some more documentation. Could you change the part

To cut out smaller parts of existing simulations check out how to use this repository to create simulation cut-outs.

In the main README.md to

Additional topics:

How to cut out smaller parts of existing simulations

How to run a simulation with on-demand mobility services (door-to-door and transit feeder)

with the respective links. And for the second point you can put a new file in docs.