minotor 11.1.2 → 11.2.0

package/src/routing/raptor.ts

@@ -0,0 +1,416 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+import { StopId } from '../stops/stops.js';
+import {
+  NOT_AVAILABLE,
+  Route,
+  StopRouteIndex,
+  TripRouteIndex,
+} from '../timetable/route.js';
+import { Duration, DURATION_ZERO, Time } from '../timetable/time.js';
+import { Timetable, TripStop } from '../timetable/timetable.js';
+import { QueryOptions } from './query.js';
+import { RoutingEdge, TransferEdge, VehicleEdge } from './state.js';
+
+/**
+ * Common interface for all variants of RAPTOR routing.
+ */
+export interface IRaptorState {
+  /** Origin stop IDs for this run. */
+  readonly origins: StopId[];
+
+  /** Per-round routing graph; `graph[round][stop]` is the best edge used to reach `stop`. */
+  readonly graph: (RoutingEdge | undefined)[][];
+
+  /** Per-run earliest arrival at a stop. Used for boarding decisions. */
+  arrivalTime(stop: StopId): Time;
+
+  /**
+   * Tightest known upper bound on the arrival time at `stop` in `round`.
+   */
+  improvementBound(round: number, stop: StopId): Time;
+
+  /**
+   * Best known arrival time at any destination.
+   */
+  readonly destinationBest: Time;
+
+  /** Returns `true` if `stop` is one of the query's destination stops. */
+  isDestination(stop: StopId): boolean;
+
+  /**
+   * Records a new arrival at `stop`, updating all relevant state.
+   *
+   * In Range RAPTOR mode this also updates the cross-run shared labels.
+   */
+  updateArrival(stop: StopId, time: Time, round: number): void;
+
+  /**
+   * Propagates labels from round `k-1` into round `k` before routes are scanned.
+   * No-op in standard RAPTOR mode.
+   */
+  initRound(round: number): void;
+}
+
+type TripContinuation = TripStop & {
+  previousEdge: VehicleEdge;
+};
+
+type Round = number;
+
+/**
+ * Encapsulates the core RAPTOR algorithm, operating on a {@link Timetable} and
+ * an {@link IRaptorState} provided by the caller.
+ *
+ * @see https://www.microsoft.com/en-us/research/wp-content/uploads/2012/01/raptor_alenex.pdf
+ */
+export class Raptor {
+  private readonly timetable: Timetable;
+
+  constructor(timetable: Timetable) {
+    this.timetable = timetable;
+  }
+
+  run(options: QueryOptions, state: IRaptorState): void {
+    const markedStops = new Set<StopId>(state.origins);
+
+    for (let round = 1; round <= options.maxTransfers + 1; round++) {
+      state.initRound(round);
+
+      const edgesAtCurrentRound = state.graph[round]!;
+      const reachableRoutes = this.timetable.findReachableRoutes(
+        markedStops,
+        options.transportModes,
+      );
+      markedStops.clear();
+
+      for (const [route, hopOnStopIndex] of reachableRoutes) {
+        for (const stop of this.scanRoute(
+          route,
+          hopOnStopIndex,
+          round,
+          state,
+          options,
+        )) {
+          markedStops.add(stop);
+        }
+      }
+
+      let continuations = this.findTripContinuations(
+        markedStops,
+        edgesAtCurrentRound,
+      );
+      const stopsFromContinuations = new Set<StopId>();
+      while (continuations.length > 0) {
+        stopsFromContinuations.clear();
+        for (const continuation of continuations) {
+          const route = this.timetable.getRoute(continuation.routeId)!;
+          for (const stop of this.scanRouteContinuation(
+            route,
+            continuation.stopIndex,
+            round,
+            state,
+            continuation,
+          )) {
+            stopsFromContinuations.add(stop);
+            markedStops.add(stop);
+          }
+        }
+        continuations = this.findTripContinuations(
+          stopsFromContinuations,
+          edgesAtCurrentRound,
+        );
+      }
+
+      for (const stop of this.considerTransfers(
+        options,
+        round,
+        markedStops,
+        state,
+      )) {
+        markedStops.add(stop);
+      }
+
+      if (markedStops.size === 0) break;
+    }
+  }
+
+  /**
+   * Finds trip continuations for the given marked stops and edges at the current round.
+   * @param markedStops The set of marked stops.
+   * @param edgesAtCurrentRound The array of edges at the current round, indexed by stop ID.
+   * @returns An array of trip continuations.
+   */
+  private findTripContinuations(
+    markedStops: Set<StopId>,
+    edgesAtCurrentRound: (RoutingEdge | undefined)[],
+  ): TripContinuation[] {
+    const continuations: TripContinuation[] = [];
+    for (const stopId of markedStops) {
+      const arrival = edgesAtCurrentRound[stopId];
+      if (!arrival || !('routeId' in arrival)) continue;
+
+      const continuousTrips = this.timetable.getContinuousTrips(
+        arrival.hopOffStopIndex,
+        arrival.routeId,
+        arrival.tripIndex,
+      );
+      for (const trip of continuousTrips) {
+        continuations.push({
+          routeId: trip.routeId,
+          stopIndex: trip.stopIndex,
+          tripIndex: trip.tripIndex,
+          previousEdge: arrival,
+        });
+      }
+    }
+    return continuations;
+  }
+
+  /**
+   * Scans a route for an in-seat trip continuation.
+   *
+   * The boarded trip and entry stop are fixed, so there is no need to probe for
+   * earlier boardings.
+   *
+   * @param route The route to scan
+   * @param hopOnStopIndex The stop index where the continuation begins
+   * @param round The current RAPTOR round
+   * @param routingState Current routing state
+   * @param tripContinuation The in-seat continuation descriptor
+   * @param shared Optional shared state for Range RAPTOR mode
+   */
+  private scanRouteContinuation(
+    route: Route,
+    hopOnStopIndex: StopRouteIndex,
+    round: Round,
+    state: IRaptorState,
+    tripContinuation: TripContinuation,
+  ): Set<StopId> {
+    const newlyMarkedStops = new Set<StopId>();
+    const edgesAtCurrentRound = state.graph[round]!;
+
+    const nbStops = route.getNbStops();
+    const routeId = route.id;
+    const tripIndex = tripContinuation.tripIndex;
+    const tripStopOffset = route.tripStopOffset(tripIndex);
+    const previousEdge = tripContinuation.previousEdge;
+
+    for (
+      let currentStopIndex = hopOnStopIndex;
+      currentStopIndex < nbStops;
+      currentStopIndex++
+    ) {
+      const currentStop: StopId = route.stops[currentStopIndex]!;
+      const arrivalTime = route.arrivalAtOffset(
+        currentStopIndex,
+        tripStopOffset,
+      );
+      const dropOffType = route.dropOffTypeAtOffset(
+        currentStopIndex,
+        tripStopOffset,
+      );
+
+      if (
+        dropOffType !== NOT_AVAILABLE &&
+        arrivalTime < state.improvementBound(round, currentStop) &&
+        arrivalTime < state.destinationBest
+      ) {
+        edgesAtCurrentRound[currentStop] = {
+          routeId,
+          stopIndex: hopOnStopIndex,
+          tripIndex,
+          arrival: arrivalTime,
+          hopOffStopIndex: currentStopIndex,
+          continuationOf: previousEdge,
+        };
+        state.updateArrival(currentStop, arrivalTime, round);
+        newlyMarkedStops.add(currentStop);
+      }
+    }
+    return newlyMarkedStops;
+  }
+
+  /**
+   * Scans a route using the standard RAPTOR boarding logic.
+   *
+   * Iterates through all stops from the hop-on point, maintaining the current
+   * best trip and improving arrival times when possible. At each marked stop it
+   * also checks whether an earlier (or first) trip can be boarded, upgrading the
+   * active trip when one is found.
+   *
+   * @param route The route to scan
+   * @param hopOnStopIndex The stop index where passengers can first board
+   * @param round The current RAPTOR round
+   * @param state Current routing state
+   * @param options Query options (minTransferTime, etc.)
+   */
+  private scanRoute(
+    route: Route,
+    hopOnStopIndex: StopRouteIndex,
+    round: Round,
+    state: IRaptorState,
+    options: QueryOptions,
+  ): Set<StopId> {
+    const newlyMarkedStops = new Set<StopId>();
+    const edgesAtCurrentRound = state.graph[round]!;
+    const edgesAtPreviousRound = state.graph[round - 1]!;
+
+    const nbStops = route.getNbStops();
+    const routeId = route.id;
+    let activeTripIndex: TripRouteIndex | undefined;
+    let activeTripBoardStopIndex = hopOnStopIndex;
+    // tripStopOffset = activeTripIndex * nbStops, precomputed when the trip changes.
+    let activeTripStopOffset = 0;
+
+    for (
+      let currentStopIndex = hopOnStopIndex;
+      currentStopIndex < nbStops;
+      currentStopIndex++
+    ) {
+      const currentStop: StopId = route.stops[currentStopIndex]!;
+
+      // If on a trip, check whether alighting here improves the global best.
+      if (activeTripIndex !== undefined) {
+        const arrivalTime = route.arrivalAtOffset(
+          currentStopIndex,
+          activeTripStopOffset,
+        );
+        const dropOffType = route.dropOffTypeAtOffset(
+          currentStopIndex,
+          activeTripStopOffset,
+        );
+
+        if (
+          dropOffType !== NOT_AVAILABLE &&
+          arrivalTime < state.improvementBound(round, currentStop) &&
+          arrivalTime < state.destinationBest
+        ) {
+          edgesAtCurrentRound[currentStop] = {
+            routeId,
+            stopIndex: activeTripBoardStopIndex,
+            tripIndex: activeTripIndex,
+            arrival: arrivalTime,
+            hopOffStopIndex: currentStopIndex,
+          };
+          state.updateArrival(currentStop, arrivalTime, round);
+          newlyMarkedStops.add(currentStop);
+        }
+      }
+
+      // Check whether we can board an earlier (or first) trip at this stop.
+      const previousEdge = edgesAtPreviousRound[currentStop];
+      const earliestArrivalOnPreviousRound = previousEdge?.arrival;
+      if (
+        earliestArrivalOnPreviousRound !== undefined &&
+        (activeTripIndex === undefined ||
+          earliestArrivalOnPreviousRound <=
+            route.departureAtOffset(currentStopIndex, activeTripStopOffset))
+      ) {
+        const earliestTrip = route.findEarliestTrip(
+          currentStopIndex,
+          earliestArrivalOnPreviousRound,
+          activeTripIndex,
+        );
+        if (earliestTrip === undefined) {
+          continue;
+        }
+
+        const fromTripStop =
+          previousEdge && 'routeId' in previousEdge
+            ? {
+                stopIndex: previousEdge.hopOffStopIndex,
+                routeId: previousEdge.routeId,
+                tripIndex: previousEdge.tripIndex,
+              }
+            : undefined;
+        const firstBoardableTrip = this.timetable.findFirstBoardableTrip(
+          currentStopIndex,
+          route,
+          earliestTrip,
+          earliestArrivalOnPreviousRound,
+          activeTripIndex,
+          fromTripStop,
+          options.minTransferTime,
+        );
+
+        if (firstBoardableTrip !== undefined) {
+          // At round 1, enforce maxInitialWaitingTime: skip boarding if the
+          // traveler would have to wait longer than the allowed threshold at
+          // the first boarding stop.
+          const exceedsInitialWait =
+            round === 1 &&
+            options.maxInitialWaitingTime !== undefined &&
+            route.departureFrom(currentStopIndex, firstBoardableTrip) -
+              earliestArrivalOnPreviousRound >
+              options.maxInitialWaitingTime;
+
+          if (!exceedsInitialWait) {
+            activeTripIndex = firstBoardableTrip;
+            activeTripBoardStopIndex = currentStopIndex;
+            activeTripStopOffset = route.tripStopOffset(firstBoardableTrip);
+          }
+        }
+      }
+    }
+    return newlyMarkedStops;
+  }
+
+  /**
+   * Processes all currently marked stops to find available transfers
+   * and determines if using these transfers would result in earlier arrival times
+   * at destination stops. It handles different transfer types including in-seat
+   * transfers and walking transfers with appropriate minimum transfer times.
+   *
+   * @param options  Query options (minTransferTime, etc.)
+   * @param round The current round number in the RAPTOR algorithm
+   * @param markedStops The set of currently marked stops
+   * @param state Current routing state
+   */
+  private considerTransfers(
+    options: QueryOptions,
+    round: number,
+    markedStops: Set<StopId>,
+    state: IRaptorState,
+  ): Set<StopId> {
+    const newlyMarkedStops = new Set<StopId>();
+    const arrivalsAtCurrentRound = state.graph[round]!;
+    for (const stop of markedStops) {
+      const currentArrival = arrivalsAtCurrentRound[stop];
+      // Skip transfers if the last leg was also a transfer
+      if (!currentArrival || 'type' in currentArrival) continue;
+      const transfers = this.timetable.getTransfers(stop);
+      for (const transfer of transfers) {
+        let transferTime: Duration;
+        if (transfer.minTransferTime) {
+          transferTime = transfer.minTransferTime;
+        } else if (transfer.type === 'IN_SEAT') {
+          transferTime = DURATION_ZERO;
+        } else {
+          transferTime = options.minTransferTime;
+        }
+        const arrivalAfterTransfer = currentArrival.arrival + transferTime;
+
+        if (
+          arrivalAfterTransfer <
+            state.improvementBound(round, transfer.destination) &&
+          arrivalAfterTransfer < state.destinationBest
+        ) {
+          arrivalsAtCurrentRound[transfer.destination] = {
+            arrival: arrivalAfterTransfer,
+            from: stop,
+            to: transfer.destination,
+            minTransferTime: transferTime || undefined,
+            type: transfer.type,
+          } as TransferEdge;
+          state.updateArrival(
+            transfer.destination,
+            arrivalAfterTransfer,
+            round,
+          );
+          newlyMarkedStops.add(transfer.destination);
+        }
+      }
+    }
+    return newlyMarkedStops;
+  }
+}

package/src/routing/result.ts

@@ -3,9 +3,9 @@ import { SourceStopId, StopId } from '../stops/stops.js';
 import { StopsIndex } from '../stops/stopsIndex.js';
 import { RawPickUpDropOffType } from '../timetable/route.js';
 import { Time } from '../timetable/time.js';
-import { Query } from './query.js';
-import { Leg, Route, Transfer, VehicleLeg } from './route.js';
+import { Access, Leg, Route, Transfer, VehicleLeg } from './route.js';
 import { Arrival, RoutingState, TransferEdge, VehicleEdge } from './router.js';
+import { AccessEdge } from './state.js';
 
 /**
  * Details about the pickup and drop-off modalities at each stop in each trip of a route.
@@ -42,26 +42,49 @@ const toPickupDropOffType = (
 };
 
 export class Result {
-  private readonly query: Query;
+  private readonly destinations: ReadonlySet<StopId>;
   public readonly routingState: RoutingState;
   public readonly stopsIndex: StopsIndex;
   public readonly timetable: Timetable;
 
   constructor(
-    query: Query,
+    destinations: ReadonlySet<StopId>,
     routingState: RoutingState,
     stopsIndex: StopsIndex,
     timetable: Timetable,
   ) {
-    this.query = query;
+    this.destinations = destinations;
     this.routingState = routingState;
     this.stopsIndex = stopsIndex;
     this.timetable = timetable;
   }
 
+  /**
+   * Expands a target stop or stop set to all equivalent concrete stop IDs.
+   *
+   * When `to` is omitted, defaults to the resolved destinations stored on this
+   * result.
+   *
+   * Equivalent stops are expanded here so destination handling has a single
+   * source of truth shared by route reconstruction and arrival lookups.
+   */
+  private expandDestinations(to?: StopId | Set<StopId>): Set<StopId> {
+    const targets: Iterable<StopId> =
+      to instanceof Set ? to : to !== undefined ? [to] : this.destinations;
+
+    const expanded = new Set<StopId>();
+    for (const target of targets) {
+      for (const equivalentStop of this.stopsIndex.equivalentStops(target)) {
+        expanded.add(equivalentStop.id);
+      }
+    }
+    return expanded;
+  }
+
   /**
    * Reconstructs the best route to a stop by SourceStopId.
-   * (to any stop reachable in less time / transfers than the destination(s) of the query)
+   * (to any stop reachable in less time / transfers than this result's
+   * destination set)
    *
    * @param to The destination stop by SourceStopId.
    * @returns a route to the destination stop if it exists.
@@ -83,33 +106,30 @@ export class Result {
 
   /**
    * Reconstructs the best route to a stop.
-   * (to any stop reachable in less time / transfers than the destination(s) of the query)
+   * (to any stop reachable in less time / transfers than this result's
+   * destination set)
    *
-   * @param to The destination stop. Defaults to the destination of the original query.
+   * @param to The destination stop. Defaults to this result's resolved
+   *   destinations.
    * @returns a route to the destination stop if it exists.
    */
   bestRoute(to?: StopId | Set<StopId>): Route | undefined {
-    const destinationIterable: Iterable<StopId> =
-      to instanceof Set ? to : to ? [to] : this.query.to;
+    const destinationStops = this.expandDestinations(to);
 
     // Find the fastest-reached destination across all equivalent stops.
     let fastestDestination: StopId | undefined = undefined;
     let fastestArrivalTime: Time | undefined = undefined;
     let fastestLegNumber: number | undefined = undefined;
-    for (const sourceDestination of destinationIterable) {
-      const equivalentStops =
-        this.stopsIndex.equivalentStops(sourceDestination);
-      for (const destination of equivalentStops) {
-        const arrivalData = this.routingState.getArrival(destination.id);
-        if (
-          arrivalData !== undefined &&
-          (fastestArrivalTime === undefined ||
-            arrivalData.arrival < fastestArrivalTime)
-        ) {
-          fastestDestination = destination.id;
-          fastestArrivalTime = arrivalData.arrival;
-          fastestLegNumber = arrivalData.legNumber;
-        }
+    for (const destination of destinationStops) {
+      const arrivalData = this.routingState.getArrival(destination);
+      if (
+        arrivalData !== undefined &&
+        (fastestArrivalTime === undefined ||
+          arrivalData.arrival < fastestArrivalTime)
+      ) {
+        fastestDestination = destination;
+        fastestArrivalTime = arrivalData.arrival;
+        fastestLegNumber = arrivalData.legNumber;
       }
     }
     if (fastestDestination === undefined || fastestLegNumber === undefined) {
@@ -121,9 +141,11 @@ export class Result {
     let currentStop = fastestDestination;
     let round = fastestLegNumber;
     let previousVehicleEdge: VehicleEdge | undefined;
-    while (round > 0) {
+
+    while (round >= 0) {
       const edge = this.routingState.graph[round]?.[currentStop];
       if (!edge) {
+        if (round === 0) break;
         throw new Error(
           `No edge arriving at stop ${currentStop} at round ${round}`,
         );
@@ -175,6 +197,9 @@ export class Result {
       } else if ('type' in edge) {
         leg = this.buildTransferLeg(edge);
         previousVehicleEdge = undefined;
+      } else if ('duration' in edge) {
+        leg = this.buildAccessLeg(edge);
+        previousVehicleEdge = undefined;
       } else {
         break;
       }
@@ -250,6 +275,22 @@ export class Result {
     };
   }
 
+  /**
+   * Builds a transfer leg from a transfer edge.
+   *
+   * @param edge Transfer edge representing a walking connection between stops
+   * @returns A transfer leg with from/to stops and transfer details
+   */
+  private buildAccessLeg(edge: AccessEdge): Access {
+    return {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      from: this.stopsIndex.findStopById(edge.from)!,
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      to: this.stopsIndex.findStopById(edge.to)!,
+      duration: edge.duration,
+    };
+  }
+
   /**
    * Builds a guaranteed transfer leg between two consecutive vehicle legs.
    *
@@ -278,7 +319,8 @@ export class Result {
   }
 
   /**
-   * Returns the arrival time at any stop reachable in less time / transfers than the destination(s) of the query)
+   * Returns the arrival time at any stop reachable in less time / transfers
+   * than this result's destination set.
    *
    * @param stop The target stop for which to return the arrival time.
    * @param maxTransfers The optional maximum number of transfers allowed.

package/src/routing/route.ts

@@ -1,4 +1,4 @@
-import { Stop, StopId } from '../stops/stops.js';
+import { Stop } from '../stops/stops.js';
 import {
   Duration,
   DURATION_ZERO,
@@ -9,21 +9,6 @@ import {
 } from '../timetable/time.js';
 import { ServiceRouteInfo, TransferType } from '../timetable/timetable.js';
 
-export type JsonLeg = {
-  from: StopId;
-  to: StopId;
-} & (
-  | {
-      departure: string;
-      arrival: string;
-      route: ServiceRouteInfo;
-    }
-  | {
-      type: TransferType;
-      minTransferTime?: number;
-    }
-);
-
 export type PickUpDropOffType =
   | 'REGULAR'
   | 'NOT_AVAILABLE'
@@ -35,6 +20,10 @@ export type BaseLeg = {
   to: Stop;
 };
 
+export type Access = BaseLeg & {
+  duration: Duration;
+};
+
 export type Transfer = BaseLeg & {
   minTransferTime?: Duration;
   type: TransferType;
@@ -48,7 +37,7 @@ export type VehicleLeg = BaseLeg & {
   dropOffType: PickUpDropOffType;
 };
 
-export type Leg = Transfer | VehicleLeg;
+export type Leg = Transfer | Access | VehicleLeg;
 
 /**
  * Represents a resolved route consisting of multiple legs,
@@ -68,15 +57,15 @@ export class Route {
    * @throws If no vehicle leg is found in the route.
    */
   departureTime(): Time {
-    let cumulativeTransferTime: Duration = DURATION_ZERO;
+    let cumulativeAccessTime: Duration = DURATION_ZERO;
     for (let i = 0; i < this.legs.length; i++) {
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
       const leg = this.legs[i]!;
       if ('departureTime' in leg) {
-        return leg.departureTime - cumulativeTransferTime;
+        return leg.departureTime - cumulativeAccessTime;
       }
-      if ('minTransferTime' in leg && leg.minTransferTime) {
-        cumulativeTransferTime += leg.minTransferTime;
+      if ('duration' in leg && leg.duration) {
+        cumulativeAccessTime += leg.duration;
       }
     }
     throw new Error('No vehicle leg found in route');
@@ -132,6 +121,10 @@ export class Route {
           'type' in leg && !('route' in leg)
             ? `Transfer: ${leg.type}${leg.minTransferTime ? `, Minimum Transfer Time: ${durationToString(leg.minTransferTime)}` : ''}`
             : '';
+        const accessDetails =
+          'duration' in leg
+            ? `Access duration: ${durationToString(leg.duration)}`
+            : '';
         const travelDetails =
           'route' in leg && 'departureTime' in leg && 'arrivalTime' in leg
             ? `Route: ${leg.route.type} ${leg.route.name}, Departure: ${timeToString(leg.departureTime)}, Arrival: ${timeToString(leg.arrivalTime)}`
@@ -142,6 +135,7 @@ export class Route {
           `  ${fromStop}`,
           `  ${toStop}`,
           transferDetails ? `  ${transferDetails}` : '',
+          accessDetails ? `  ${accessDetails}` : '',
           travelDetails ? `  ${travelDetails}` : '',
         ]
           .filter((line) => line.trim() !== '')
@@ -149,36 +143,4 @@ export class Route {
       })
       .join('\n');
   }
-
-  /**
-   * Generates a concise JSON representation of the route.
-   * This is particularly useful for generating regression tests
-   * to verify the correctness of route calculations.
-   *
-   * @returns A JSON representation of the route.
-   */
-  asJson(): JsonLeg[] {
-    const jsonLegs: JsonLeg[] = this.legs.map((leg: Leg) => {
-      if ('route' in leg) {
-        return {
-          from: leg.from.id,
-          to: leg.to.id,
-          departure: timeToString(leg.departureTime),
-          arrival: timeToString(leg.arrivalTime),
-          route: leg.route,
-        };
-      } else {
-        return {
-          from: leg.from.id,
-          to: leg.to.id,
-          type: leg.type,
-          ...(leg.minTransferTime !== undefined && {
-            minTransferTime: leg.minTransferTime,
-          }),
-        };
-      }
-    });
-
-    return jsonLegs;
-  }
 }