A constraint is used to filter out trip or tour alternatives that do not make sense or are forbidden for some reason. The classic example is to forbid the car mode at a location where the vehicle has not been moved to. This is not a dynamic constraint, but can already be inferred when the mode chain is constructed since the origin and destination locations of each trip are known in advance.
The DMC extension contains a number of predefined constraints, but it is also possible to write custom ones. How to do that is explained in Customizing the model.
In the following the existing built-in constraints are described. While some of them have additional configuration options that can be defined in a parameterset, some don't. In any case, tour or trip constraints can be chosen in the main config group. If a trip-based model is used, the tripConstraints are considered, if a tour-based model is used, the tourConstraints are used. In each case a unlimited number of constraints, divided by commas, can be defined:
<module name="DiscreteModeChoice">
<!-- Defines a number of TripConstraint components that should be activated. Built-in choices: ... -->
<param name="tripConstraints" value="" />
<!-- Defines a number of TourConstraint components that should be activated. Built-in choices: ... -->
<param name="tripConstraints" value="" />
</module>Description: The FromTripBased tour constraint is a special constraint, because it does not perform any filtering itself. Instead, it will look up the tripConstraints from the main DMC configuration and used them on a trip-by-trip basis for each tour that needs to be evaluated. Only if the defined trip constraints pass for all trips in a tour, the tour is considered to be valid.
Level: Tour
Configuration:
No specific configuration availble. The tripConstraints attribute from the main DMC config group is used.
Description: The link attribute constraint makes it possible to allow or forbid certain modes if a specific link attribute at the origin or destination of the trip shows a specific value. If the requirement is chosen to be BOTH, both origin and destination must fulfill the condition. Alternatively, ORIGIN (only), DESTINATION (only) or ANY can be chosen, but it can also be required that NONE matches for the constraint to be fulfilled.
Level: Trip
Configuration:
<parameterset type="tripConstraint:LinkAttribute" >
<!-- Link attribute that will be considered for feasibility of the trip. -->
<param name="attributeName" value="null" />
<!-- Value that the link attributes should equal. -->
<param name="attributeValue" value="null" />
<!-- Modes for which the shapes will be considered. -->
<param name="constrainedModes" value="" />
<!-- Defines the criterion on when a trip with the constrained mode will be allowed: ORIGIN, DESTINATION, BOTH, ANY, NONE -->
<param name="requirement" value="BOTH" />
</parameterset>Description: The shape file constraint makes it possible to allow or forbid certain modes if the origin and/or destination coordinate of the trip is covered by a feature in a given shape file. If the requirement is chosen to be BOTH, both origin and destination must fulfill the condition. Alternatively, ORIGIN (only), DESTINATION (only) or ANY can be chosen, but it can also be required that NONE matches for the constraint to be fulfilled. The path is given relative to the configuration file.
Level: Trip
Configuration:
<parameterset type="tripConstraint:ShapeFile" >
<!-- Modes for which the shapes will be considered. -->
<param name="constrainedModes" value="" />
<!-- Path to a shape file, which should have the same projection as the network. -->
<param name="path" value="null" />
<!-- Defines the criterion on when a trip with the constrained mode will be allowed: ORIGIN, DESTINATION, BOTH, ANY, NONE -->
<param name="requirement" value="BOTH" />
</parameterset>Description: The SubtourMode constraint makes sure that only alternatives are considered that could have been generated by SubtourModeChoice. It is mainly used to create compatibility with existing MATSim simulations. There are two components to the logic of the constraint: First, historically, SubtourModeChoice did not consider multiple non-constrained modes on one sub-tour of a plan. For instance, it was not possible to walk from work to a restaurant and come back by public transport. This has changed since the option probaForRandomSingleTripMode has been added to SubtourModeChoice. Using this probability one can now demand that single legs which happen to be on a sub-tour of a non-constrained (not chain-based) mode can be replaced by other non-contstrained modes. This only happens if probaForRandomSingleTripMode > 0. Second, SubtourModeChoice considers the atomic sub-tours of a plan. For instance, a chain of locations like A -> B -> A -> B -> A can be covered by a chain of modes like [car, car, walk, walk], but never [car, pt, pt, car]. In principle, this is the same constraint: A tour with a constrained mode cannot be interrupted by any other mode.
Therefore, the SubtourMode costraint only relies on a list of "constrained modes". If one wants to replicate the behaviour of the "old" SubtourModeChoice, one needs to add all available modes as "constrained modes". If one wants to replicate the "new" behaviour, only the actual modes, which should also be constrained by a VehicleConstraint should be added.
- Replicate
probaForRandomSingleTripMode == 0.0(old) -> Add all available modes asconstrainedModes - Replicate
probaForRandomSingleTripMode > 0.0(new) -> Add only "chain based" modes asconstrainedModes
Level: Tour
Configuration:
<parameterset type="tourConstraint:SubtourMode" >
<!-- Modes for which the sub-tour behaviour should be replicated. If all available modes are put here, this equals to SubTourModeChoice with singleLegProbability == 0.0; if only the constrained modes are put here, it equals singleLegProbability > 0.0 -->
<param name="constrainedModes" value="" />
</parameterset>Description: This constraint makes sure that no public transit trips that only contain one transit_walk leg are accepted. Usually, there should be another alternative with an actual walk trip should be available. This is to ensure that no agent chooses the pt mode when, in fact, there is no sensible connection available.
Level: Trip
Configuration: No special configuration.
Description: The VehicleTourConstraint makes sure that agents have consistent mode chains in their plans. There are three slots that enforce the behaviour. The option restrictedModes contains a list of modes that can only be used if the respective vehicle has been moved to the new departure location before. Also it is required that the vehicle can only start at and must be brought back to a specified home location. The home location of an agent is not given per se, so it needs to be inferred. For that, see the HomeFinder component that can be configured independently.
Level: Tour
Configuration:
<parameterset type="tourConstraint:VehicleContinuity" >
<!-- Defines which modes must fulfill continuity constraints (can only be used where they have been brough to before) -->
<param name="restrictedModes" value="car" />
</parameterset>The trip-based version of the vehicle continuity constraint is configured the same way as the tour-based version. In general, the case is more tricky here, because enforcing a vehicle to arrive at home may mean also forbidding other modes (such as walking) for certain trips, because otherwise there is structurally no possibility to return the vehicle back home. In principle, these cases should be covered by the constraint, but it has not been tested thoroughly! Use at own risk, and we'd be happy to see some test cases for it.