Make naming of stopTransferCost/stopBoardAlightCost consistent

Author: habrahamsson-skanetrafiken

docs/BuildConfiguration.md

@@ -744,7 +744,7 @@ but we want to calculate the transfers always from OSM data.
 Should there be some preference or aversion for transfers at stops that are part of a station.
 
 This parameter sets the generic level of preference. What is the actual cost can be changed
-with the `stopTransferCost` parameter in the router configuration.
+with the `stopBoardAlightDuringTransferCost` parameter in the router configuration.
 
 
 <h3 id="islandPruning_adaptivePruningDistance">adaptivePruningDistance</h3>
@@ -993,7 +993,7 @@ but we want to calculate the transfers always from OSM data.
 Should there be some preference or aversion for transfers at stops that are part of a station. Overrides the value specified in `gtfsDefaults`.
 
 This parameter sets the generic level of preference. What is the actual cost can be changed
-with the `stopTransferCost` parameter in the router configuration.
+with the `stopBoardAlightDuringTransferCost` parameter in the router configuration.
 
 
 <h3 id="tf_1_groupFilePattern">groupFilePattern</h3>

docs/RouteRequest.md

@@ -947,7 +947,7 @@ The wait time is used to prevent *back-travel*, the `backTravelWaitTimeFactor` i
 
 Add an extra board- and alight-cost for prioritized stops.
 
-A stopBoardAlightCosts is added to the generalized-cost during routing. But this cost
+A stopBoardAlightTransferCosts is added to the generalized-cost during routing. But this cost
 cannot be too high, because that would add extra cost to the transfer, and favor other
 alternative paths. But, when optimizing transfers, we do not have to take other paths
 into consideration and can *boost* the stop-priority-cost to allow transfers to

docs/RouterConfiguration.md

@@ -61,7 +61,7 @@ A full list of them can be found in the [RouteRequest](RouteRequest.md).
 |       [minWindow](#transit_dynamicSearchWindow_minWindow)                                 |       `duration`      | The constant minimum duration for a raptor-search-window.                                             | *Optional* | `"PT40M"`     |  2.2  |
 |       [stepMinutes](#transit_dynamicSearchWindow_stepMinutes)                             |       `integer`       | Used to set the steps the search-window is rounded to.                                                | *Optional* | `10`          |  2.1  |
 |    [pagingSearchWindowAdjustments](#transit_pagingSearchWindowAdjustments)                |      `duration[]`     | The provided array of durations is used to increase the search-window for the next/previous page.     | *Optional* |               |   na  |
-|    [stopTransferCost](#transit_stopTransferCost)                                          | `enum map of integer` | Use this to set a stop transfer cost for the given transfer priority                                  | *Optional* |               |  2.0  |
+|    [stopBoardAlightDuringTransferCost](#transit_stopBoardAlightDuringTransferCost)        | `enum map of integer` | Costs for boarding and alighting during transfers at stops with a given transfer priority.            | *Optional* |               |  2.0  |
 |    [transferCacheRequests](#transit_transferCacheRequests)                                |       `object[]`      | Routing requests to use for pre-filling the stop-to-stop transfer cache.                              | *Optional* |               |  2.3  |
 | transmodelApi                                                                             |        `object`       | Configuration for the Transmodel GraphQL API.                                                         | *Optional* |               |  2.1  |
 |    [hideFeedId](#transmodelApi_hideFeedId)                                                |       `boolean`       | Hide the FeedId in all API output, and add it to input.                                               | *Optional* | `false`       |   na  |
@@ -358,19 +358,21 @@ previous page cursor. See JavaDoc for [TransitTuningParameters#pagingSearchWindo
 for more info."
 
 
-<h3 id="transit_stopTransferCost">stopTransferCost</h3>
+<h3 id="transit_stopBoardAlightDuringTransferCost">stopBoardAlightDuringTransferCost</h3>
 
 **Since version:** `2.0` ∙ **Type:** `enum map of integer` ∙ **Cardinality:** `Optional`   
 **Path:** /transit   
 **Enum keys:** `discouraged` | `allowed` | `recommended` | `preferred`
 
-Use this to set a stop transfer cost for the given transfer priority
+Costs for boarding and alighting during transfers at stops with a given transfer priority.
 
-The cost is applied to boarding and alighting at all stops. All stops have a transfer cost priority
-set, the default is `allowed`. The `stopTransferCost` parameter is optional, but if listed all
+This cost is applied **both to boarding and alighting** at stops during transfers. All stops have a transfer cost priority
+set, the default is `allowed`. The `stopBoardAlightDuringTransferCost` parameter is optional, but if listed all
 values must be set.
 
-If not set the `stopTransferCost` is ignored. This is only available for NeTEx imported Stops.
+When a transfer occurs at the same stop, the cost will be applied twice since the cost is both for boarding and alighting,
+
+If not set the `stopBoardAlightDuringTransferCost` is ignored. This is only available for NeTEx imported Stops.
 
 The cost is a scalar, but is equivalent to the felt cost of riding a transit trip for 1 second.
 
@@ -382,7 +384,7 @@ The cost is a scalar, but is equivalent to the felt cost of riding a transit tri
 | `preferred`   | The best place to do transfers. Should be set to `0`(zero).                                   | int  |
 
 Use values in a range from `0` to `100 000`. **All key/value pairs are required if the
-`stopTransferCost` is listed.**
+`stopBoardAlightDuringTransferCost` is listed.**
 
 
 <h3 id="transit_transferCacheRequests">transferCacheRequests</h3>
@@ -608,7 +610,7 @@ Used to group requests when monitoring OTP.
       "minWindow" : "1h",
       "maxWindow" : "5h"
     },
-    "stopTransferCost" : {
+    "stopBoardAlightDuringTransferCost" : {
       "DISCOURAGED" : 1500,
       "ALLOWED" : 75,
       "RECOMMENDED" : 30,

docs/examples/entur/router-config.json

@@ -91,7 +91,7 @@
       "minWindow" : "1h",
       "maxWindow" : "5h"
     },
-    "stopTransferCost" : {
+    "stopBoardAlightDuringTransferCost" : {
       "DISCOURAGED" : 1500,
       "ALLOWED" : 75,
       "RECOMMENDED" : 30,

docs/examples/skanetrafiken/router-config.json

@@ -15,7 +15,7 @@
       "24h",
       "0h"
     ],
-    "stopTransferCost": {
+    "stopBoardAlightDuringTransferCost": {
       "DISCOURAGED": 3000,
       "ALLOWED": 150,
       "RECOMMENDED": 60,

src/main/java/org/opentripplanner/model/Timetable.java

@@ -61,6 +61,7 @@ public class Timetable implements Serializable {
 
   private final List<FrequencyEntry> frequencyEntries = new ArrayList<>();
 
+  @Nullable
   private final LocalDate serviceDate;
 
   /** Construct an empty Timetable. */

src/main/java/org/opentripplanner/routing/algorithm/raptoradapter/router/TransitRouter.java

@@ -146,7 +146,7 @@ private TransitRouterResult route() {
         requestTransitDataProvider.stopNameResolver(),
         serverContext.transitService().getTransferService(),
         requestTransitDataProvider,
-        transitLayer.getStopBoardAlightCosts(),
+        transitLayer.getStopBoardAlightTransferCosts(),
         request.preferences().transfer().optimization(),
         raptorRequest.multiCriteria()
       );

src/main/java/org/opentripplanner/routing/algorithm/raptoradapter/transit/TransitLayer.java

@@ -48,7 +48,11 @@ public class TransitLayer {
 
   private final TransferIndexGenerator transferIndexGenerator;
 
-  private final int[] stopBoardAlightCosts;
+  /**
+   * @see #getStopBoardAlightTransferCosts()
+   */
+  @Nullable
+  private final int[] stopBoardAlightTransferCosts;
 
   /**
    * Makes a shallow copy of the TransitLayer, except for the tripPatternsForDate, where a shallow
@@ -65,7 +69,7 @@ public TransitLayer(TransitLayer transitLayer) {
       transitLayer.transferCache,
       transitLayer.constrainedTransfers,
       transitLayer.transferIndexGenerator,
-      transitLayer.stopBoardAlightCosts
+      transitLayer.stopBoardAlightTransferCosts
     );
   }
 
@@ -78,7 +82,7 @@ public TransitLayer(
     RaptorRequestTransferCache transferCache,
     ConstrainedTransfersForPatterns constrainedTransfers,
     TransferIndexGenerator transferIndexGenerator,
-    int[] stopBoardAlightCosts
+    @Nullable int[] stopBoardAlightTransferCosts
   ) {
     this.tripPatternsRunningOnDate = new HashMap<>(tripPatternsRunningOnDate);
     this.transfersByStopIndex = transfersByStopIndex;
@@ -88,7 +92,7 @@ public TransitLayer(
     this.transferCache = transferCache;
     this.constrainedTransfers = constrainedTransfers;
     this.transferIndexGenerator = transferIndexGenerator;
-    this.stopBoardAlightCosts = stopBoardAlightCosts;
+    this.stopBoardAlightTransferCosts = stopBoardAlightTransferCosts;
   }
 
   @Nullable
@@ -166,8 +170,13 @@ public TransferIndexGenerator getTransferIndexGenerator() {
     return transferIndexGenerator;
   }
 
-  public int[] getStopBoardAlightCosts() {
-    return stopBoardAlightCosts;
+  /**
+   * Costs for both boarding and alighting at a given stop during transfer. Note that this is in
+   * raptor centi-second units.
+   */
+  @Nullable
+  public int[] getStopBoardAlightTransferCosts() {
+    return stopBoardAlightTransferCosts;
   }
 
   /**

src/main/java/org/opentripplanner/routing/algorithm/raptoradapter/transit/TransitTuningParameters.java

@@ -13,7 +13,7 @@ public interface TransitTuningParameters {
    * These tuning parameters are typically used in unit tests. The values are:
    * <pre>
    * enableStopTransferPriority : true
-   * stopTransferCost : {
+   * stopBoardAlightDuringTransferCost : {
    *   DISCOURAGED:  3600  (equivalent of 1 hour penalty)
    *   ALLOWED:        60  (60 seconds penalty)
    *   RECOMMENDED:    20  (20 seconds penalty)
@@ -28,7 +28,7 @@ public boolean enableStopTransferPriority() {
     }
 
     @Override
-    public Integer stopTransferCost(StopTransferPriority key) {
+    public Integer stopBoardAlightDuringTransferCost(StopTransferPriority key) {
       switch (key) {
         case DISCOURAGED:
           return 3600;
@@ -70,10 +70,11 @@ public List<RouteRequest> transferCacheRequests() {
   boolean enableStopTransferPriority();
 
   /**
-   * The stop transfer cost for the given {@link StopTransferPriority}. The cost applied to boarding
-   * and alighting all stops with the given priority.
+   * The stop board alight transfer cost for the given {@link StopTransferPriority}. The cost
+   * applied during transfers to <b>both boarding and alighting</b> of stops with the given
+   * priority.
    */
-  Integer stopTransferCost(StopTransferPriority key);
+  Integer stopBoardAlightDuringTransferCost(StopTransferPriority key);
 
   /**
    * The maximum number of transfer RouteRequests for which the pre-calculated transfers should be

src/main/java/org/opentripplanner/routing/algorithm/raptoradapter/transit/cost/CostCalculatorFactory.java

@@ -1,16 +1,17 @@
 package org.opentripplanner.routing.algorithm.raptoradapter.transit.cost;
 
+import javax.annotation.Nullable;
 import org.opentripplanner.raptor.spi.RaptorCostCalculator;
 
 public class CostCalculatorFactory {
 
   public static <T extends DefaultTripSchedule> RaptorCostCalculator<T> createCostCalculator(
     GeneralizedCostParameters generalizedCostParameters,
-    int[] stopBoardAlightCosts
+    @Nullable int[] stopBoardAlightTransferCosts
   ) {
     RaptorCostCalculator<T> calculator = new DefaultCostCalculator<>(
       generalizedCostParameters,
-      stopBoardAlightCosts
+      stopBoardAlightTransferCosts
     );
 
     if (generalizedCostParameters.wheelchairEnabled()) {

src/main/java/org/opentripplanner/routing/algorithm/raptoradapter/transit/cost/DefaultCostCalculator.java

@@ -19,22 +19,28 @@ public final class DefaultCostCalculator<T extends DefaultTripSchedule>
   private final int boardAndTransferCost;
   private final int waitFactor;
   private final FactorStrategy transitFactors;
-  private final int[] stopTransferCost;
+
+  /**
+   * Costs for boarding and alighting at a given stop during transfer.
+   * See TransitLayer.getStopBoardAlightTransferCosts()
+   */
+  @Nullable
+  private final int[] stopBoardAlightTransferCosts;
 
   /**
    * Cost unit: SECONDS - The unit for all input parameters are in the OTP TRANSIT model cost unit
    * (in Raptor the unit for cost is centi-seconds).
    *
-   * @param stopTransferCost Unit centi-seconds. This parameter is used "as-is" and not transformed
-   *                      into the Raptor cast unit to avoid the transformation for each request.
-   *                      Use {@code null} to ignore stop cost.
+   * @param stopBoardAlightTransferCosts Unit centi-seconds. This parameter is used "as-is" and not
+   *                      transformed into the Raptor cast unit to avoid the transformation for each
+   *                      request. Use {@code null} to ignore stop cost.
    */
   public DefaultCostCalculator(
     int boardCost,
     int transferCost,
     double waitReluctanceFactor,
     @Nullable double[] transitReluctanceFactors,
-    @Nullable int[] stopTransferCost
+    @Nullable int[] stopBoardAlightTransferCosts
   ) {
     this.boardCostOnly = RaptorCostConverter.toRaptorCost(boardCost);
     this.transferCostOnly = RaptorCostConverter.toRaptorCost(transferCost);
@@ -46,16 +52,19 @@ public DefaultCostCalculator(
         ? new SingleValueFactorStrategy(GeneralizedCostParameters.DEFAULT_TRANSIT_RELUCTANCE)
         : new IndexBasedFactorStrategy(transitReluctanceFactors);
 
-    this.stopTransferCost = stopTransferCost;
+    this.stopBoardAlightTransferCosts = stopBoardAlightTransferCosts;
   }
 
-  public DefaultCostCalculator(GeneralizedCostParameters params, int[] stopTransferCost) {
+  public DefaultCostCalculator(
+    GeneralizedCostParameters params,
+    @Nullable int[] stopBoardAlightTransferCosts
+  ) {
     this(
       params.boardCost(),
       params.transferCost(),
       params.waitReluctanceFactor(),
       params.transitReluctanceFactors(),
-      stopTransferCost
+      stopBoardAlightTransferCosts
     );
   }
 
@@ -108,8 +117,8 @@ public int transitArrivalCost(
 
     // Add transfer cost on all alighting events.
     // If it turns out to be the last one this cost will be removed during costEgress phase.
-    if (stopTransferCost != null) {
-      cost += stopTransferCost[toStop];
+    if (stopBoardAlightTransferCosts != null) {
+      cost += stopBoardAlightTransferCosts[toStop];
     }
 
     return cost;
@@ -134,20 +143,22 @@ public int calculateRemainingMinCost(int minTravelTime, int minNumTransfers, int
       // Remove cost that was added during alighting similar as we do in the costEgress() method
       int fixedCost = transitFactors.minFactor() * minTravelTime;
 
-      return stopTransferCost == null ? fixedCost : fixedCost - stopTransferCost[fromStop];
+      return stopBoardAlightTransferCosts == null
+        ? fixedCost
+        : fixedCost - stopBoardAlightTransferCosts[fromStop];
     }
   }
 
   @Override
   public int costEgress(RaptorAccessEgress egress) {
     if (egress.hasRides()) {
       return egress.c1() + transferCostOnly;
-    } else if (stopTransferCost != null) {
+    } else if (stopBoardAlightTransferCosts != null) {
       // Remove cost that was added during alighting.
       // We do not want to add this cost on last alighting since it should only be applied on transfers
       // It has to be done here because during alighting we do not know yet if it will be
       // a transfer or not.
-      return egress.c1() - stopTransferCost[egress.stop()];
+      return egress.c1() - stopBoardAlightTransferCosts[egress.stop()];
     } else {
       return egress.c1();
     }
@@ -171,8 +182,8 @@ public int boardingCostRegularTransfer(
     cost += firstBoarding ? boardCostOnly : boardAndTransferCost;
 
     // If it's first boarding event then it is not a transfer
-    if (stopTransferCost != null && !firstBoarding) {
-      cost += stopTransferCost[boardStop];
+    if (stopBoardAlightTransferCosts != null && !firstBoarding) {
+      cost += stopBoardAlightTransferCosts[boardStop];
     }
     return cost;
   }
@@ -210,8 +221,9 @@ private int boardingCostConstrainedTransfer(
       // For a guaranteed transfer we skip board- and transfer-cost
       final int boardWaitTime = boardTime - prevArrivalTime;
 
-      // StopTransferCost is NOT added to the cost here. This is because a trip-to-trip constrained transfer take
-      // precedence over stop-to-stop transfer priority (NeTEx station transfer priority).
+      // StopBoardAlightTransferCost is NOT added to the cost here. This is because a trip-to-trip
+      // constrained transfer take precedence over stop-to-stop transfer priority (NeTEx station
+      // transfer priority).
       return waitFactor * boardWaitTime;
     }
 

src/main/java/org/opentripplanner/routing/algorithm/raptoradapter/transit/mappers/TransitLayerMapper.java

@@ -13,6 +13,7 @@
 import java.util.Map;
 import java.util.Set;
 import java.util.stream.Collectors;
+import javax.annotation.Nullable;
 import org.opentripplanner.framework.application.OTPFeature;
 import org.opentripplanner.model.Timetable;
 import org.opentripplanner.routing.algorithm.raptoradapter.transit.Transfer;
@@ -103,7 +104,7 @@ private TransitLayer map(TransitTuningParameters tuningParameters) {
       transferCache,
       constrainedTransfers,
       transferIndexGenerator,
-      createStopTransferCosts(stopModel, tuningParameters)
+      createStopBoardAlightTransferCosts(stopModel, tuningParameters)
     );
   }
 
@@ -179,19 +180,23 @@ private HashMap<LocalDate, List<TripPatternForDate>> keyByRunningPeriodDates(
   }
 
   /**
-   * Create static board/alight cost for Raptor to include for each stop.
+   * Create static board/alight cost for Raptor to apply during transfer
    */
-  static int[] createStopTransferCosts(StopModel stops, TransitTuningParameters tuningParams) {
+  @Nullable
+  static int[] createStopBoardAlightTransferCosts(
+    StopModel stops,
+    TransitTuningParameters tuningParams
+  ) {
     if (!tuningParams.enableStopTransferPriority()) {
       return null;
     }
-    int[] stopTransferCosts = new int[stops.stopIndexSize()];
+    int[] stopBoardAlightTransferCosts = new int[stops.stopIndexSize()];
 
     for (int i = 0; i < stops.stopIndexSize(); ++i) {
       StopTransferPriority priority = stops.stopByIndex(i).getPriority();
-      int domainCost = tuningParams.stopTransferCost(priority);
-      stopTransferCosts[i] = RaptorCostConverter.toRaptorCost(domainCost);
+      int domainCost = tuningParams.stopBoardAlightDuringTransferCost(priority);
+      stopBoardAlightTransferCosts[i] = RaptorCostConverter.toRaptorCost(domainCost);
     }
-    return stopTransferCosts;
+    return stopBoardAlightTransferCosts;
   }
 }

src/main/java/org/opentripplanner/routing/algorithm/raptoradapter/transit/request/RaptorRoutingRequestTransitData.java

@@ -104,7 +104,7 @@ public RaptorRoutingRequestTransitData(
     this.generalizedCostCalculator =
       CostCalculatorFactory.createCostCalculator(
         mcCostParams,
-        transitLayer.getStopBoardAlightCosts()
+        transitLayer.getStopBoardAlightTransferCosts()
       );
 
     this.slackProvider =