minotor 11.1.2 → 11.2.0

package/src/routing/rangeResult.ts

@@ -0,0 +1,292 @@
+import { StopId } from '../stops/stops.js';
+import { Duration, Time } from '../timetable/time.js';
+import { Result } from './result.js';
+import { Route } from './route.js';
+import { Arrival } from './state.js';
+
+/**
+ * A single departure-time iteration that produced at least one Pareto-optimal
+ * journey to this result's destination set.
+ */
+export type ParetoRun = {
+  /** Departure time from the origin (minutes from midnight) for this run. */
+  readonly departureTime: Time;
+  /** Full RAPTOR result for this departure time — use it to reconstruct routes. */
+  readonly result: Result;
+};
+
+/**
+ * An {@link Arrival} enriched with the travel duration from the origin.
+ *
+ * Returned by duration-based methods on {@link RangeResult} so callers
+ * receive both the absolute arrival time with transfer count *and* the total
+ * travel time that was optimized over.
+ */
+export type ArrivalWithDuration = Arrival & {
+  /** Total travel time from origin departure to stop arrival (minutes). */
+  readonly duration: Duration;
+};
+
+/**
+ * The result of a Range RAPTOR query.
+ *
+ * Contains the complete Pareto-optimal set of journeys for a resolved
+ * destination set.
+ *
+ * **Pareto dominance**: journey J1 dominates J2 iff
+ *   `τdep(J1) ≥ τdep(J2)  AND  τarr(J1) ≤ τarr(J2)`
+ * (with at least one strict inequality).
+ *
+ * Runs are ordered **latest-departure-first**: each successive run departs
+ * strictly earlier *and* arrives strictly earlier than the previous one,
+ * forming the classic staircase Pareto frontier.
+ *
+ * Destination handling is delegated to {@link Result}, which expands
+ * equivalent stops when reconstructing routes or looking up arrivals.
+ */
+export class RangeResult {
+  private readonly _runs: readonly ParetoRun[];
+  private readonly _destinations: ReadonlySet<StopId>;
+
+  constructor(runs: ParetoRun[], destinations: ReadonlySet<StopId>) {
+    this._runs = runs;
+    this._destinations = destinations;
+  }
+
+  /** The resolved destination stop IDs for this result. */
+  get destinations(): ReadonlySet<StopId> {
+    return this._destinations;
+  }
+
+  private normalizeTargets(to?: StopId | Set<StopId>): Set<StopId> {
+    if (to instanceof Set) return new Set(to);
+    if (to !== undefined) return new Set([to]);
+    return new Set(this._destinations);
+  }
+
+  /**
+   * Returns all non-dominated routes to this result's default destination set,
+   * ordered from the earliest departure to the latest departure.
+   *
+   * Each route in the list departs strictly earlier *and* arrives strictly
+   * earlier than its predecessor.
+   */
+  getRoutes(): Route[] {
+    const routes: Route[] = [];
+    for (const { result } of this._runs) {
+      const route = result.bestRoute();
+      if (route !== undefined) routes.push(route);
+    }
+    return routes.reverse();
+  }
+
+  /**
+   * The route that arrives **earliest** at the given stop(s) across all
+   * Pareto-optimal runs.
+   *
+   * When two runs achieve the same arrival time at the target, the one with
+   * the **later departure** is preferred — you wait at the origin rather than
+   * at a transit stop.
+   *
+   * Defaults to this result's own destination stop(s) when `to` is omitted.
+   *
+   * @param to Optional destination stop ID or set of stop IDs.
+   * @returns The reconstructed {@link Route} with the earliest arrival,
+   *          or `undefined` if the target is unreachable in every run.
+   */
+  bestRoute(to?: StopId | Set<StopId>): Route | undefined {
+    const targetStops = this.normalizeTargets(to);
+
+    let bestRun: ParetoRun | undefined;
+    let bestArrival: Time | undefined;
+
+    for (const run of this._runs) {
+      for (const stopId of targetStops) {
+        const arrival = run.result.arrivalAt(stopId);
+        if (arrival === undefined) continue;
+        if (bestArrival === undefined || arrival.arrival < bestArrival) {
+          bestArrival = arrival.arrival;
+          bestRun = run;
+        }
+      }
+    }
+
+    return bestRun?.result.bestRoute(targetStops);
+  }
+
+  /**
+   * The route with the **latest possible departure** from the origin among all
+   * Pareto-optimal journeys in the window.
+   *
+   * This is the journey that lets you leave the origin as late as possible.
+   * It does **not** necessarily achieve the earliest arrival — for that, use
+   * {@link bestRoute}. For the shortest travel duration, use
+   * {@link fastestRoute}.
+   *
+   * Defaults to this result's own destination stop(s) when `to` is omitted.
+   *
+   * @param to Optional destination stop ID or set of stop IDs.
+   * @returns The reconstructed {@link Route} with the latest departure,
+   *          or `undefined` if the target is unreachable in every run.
+   */
+  latestDepartureRoute(to?: StopId | Set<StopId>): Route | undefined {
+    const targetStops = this.normalizeTargets(to);
+    for (const { result } of this._runs) {
+      const route = result.bestRoute(targetStops);
+      if (route !== undefined) return route;
+    }
+    return undefined;
+  }
+
+  /**
+   * Reconstructs the **fastest** route to the given stop(s) — the journey with
+   * the shortest travel duration (arrival time − origin departure time) across
+   * all Pareto-optimal runs.
+   *
+   * Unlike {@link bestRoute}, which returns the route that departs as late as
+   * possible while still arriving early, this method minimizes total time
+   * spent traveling.
+   *
+   * Defaults to this result's own destination stop(s) when `to` is omitted.
+   *
+   * @param to Optional destination stop ID or set of stop IDs.
+   * @returns The reconstructed fastest {@link Route}, or `undefined` if the
+   *          target is unreachable in every run.
+   */
+  fastestRoute(to?: StopId | Set<StopId>): Route | undefined {
+    const targetStops = this.normalizeTargets(to);
+
+    let fastestRun: ParetoRun | undefined;
+    let shortestDuration = Infinity;
+
+    for (const run of this._runs) {
+      for (const stopId of targetStops) {
+        const arrival = run.result.arrivalAt(stopId);
+        if (arrival === undefined) continue;
+        const duration = arrival.arrival - run.departureTime;
+        if (duration < shortestDuration) {
+          shortestDuration = duration;
+          fastestRun = run;
+        }
+      }
+    }
+
+    return fastestRun?.result.bestRoute(targetStops);
+  }
+
+  /** Number of Pareto-optimal journeys found. */
+  get size(): number {
+    return this._runs.length;
+  }
+
+  /**
+   * Earliest achievable arrival at a stop across all Pareto-optimal runs.
+   *
+   * Useful for isochrone / accessibility analysis: given this result's
+   * departure-time frontier, how early can you reach stop `s` regardless of
+   * which specific trip you take?
+   *
+   * Equivalent stops are handled by {@link Result.arrivalAt}.
+   *
+   * @param stop         The target stop ID.
+   * @param maxTransfers Optional upper bound on the number of transfers.
+   */
+  earliestArrivalAt(stop: StopId, maxTransfers?: number): Arrival | undefined {
+    let best: Arrival | undefined;
+    for (const { result } of this._runs) {
+      const arrival = result.arrivalAt(stop, maxTransfers);
+      if (
+        arrival !== undefined &&
+        (best === undefined || arrival.arrival < best.arrival)
+      ) {
+        best = arrival;
+      }
+    }
+    return best;
+  }
+
+  /**
+   * Shortest travel duration to reach a stop across all Pareto-optimal runs.
+   *
+   * For each run, duration is measured from the run's origin departure time to
+   * the earliest arrival at `stop` within that run. The minimum across all
+   * runs is returned.
+   *
+   * Equivalent stops are handled by {@link Result.arrivalAt}.
+   *
+   * Duration is **not** monotone along the Pareto frontier — a run that
+   * departs later may still travel faster — so every run is checked. In
+   * practice the Pareto frontier is small, so this is O(runs).
+   *
+   * Returns `undefined` if `stop` is unreachable in every run.
+   *
+   * @param stop         The target stop ID.
+   * @param maxTransfers Optional upper bound on the number of transfers.
+   */
+  shortestDurationTo(
+    stop: StopId,
+    maxTransfers?: number,
+  ): ArrivalWithDuration | undefined {
+    let shortest: ArrivalWithDuration | undefined;
+    for (const { departureTime, result } of this._runs) {
+      const arrival = result.arrivalAt(stop, maxTransfers);
+      if (arrival === undefined) continue;
+      const duration = arrival.arrival - departureTime;
+      if (shortest === undefined || duration < shortest.duration) {
+        shortest = { ...arrival, duration };
+      }
+    }
+    return shortest;
+  }
+
+  /**
+   * Shortest travel duration to **every reachable stop** across all
+   * Pareto-optimal runs, as a single `Map<StopId, DurationArrival>`.
+   */
+  allShortestDurations(): Map<StopId, ArrivalWithDuration> {
+    const durations = new Map<StopId, ArrivalWithDuration>();
+    for (const { departureTime, result } of this._runs) {
+      for (const {
+        stop,
+        arrival,
+        legNumber,
+      } of result.routingState.arrivals()) {
+        const duration = arrival - departureTime;
+        const existing = durations.get(stop);
+        if (existing === undefined || duration < existing.duration) {
+          durations.set(stop, { arrival, legNumber, duration });
+        }
+      }
+    }
+    return durations;
+  }
+
+  /**
+   * Earliest achievable arrival at **every reachable stop** across all
+   * Pareto-optimal runs, as a single `Map<StopId, Arrival>`.
+   */
+  allEarliestArrivals(): Map<StopId, Arrival> {
+    const arrivals = new Map<StopId, Arrival>();
+    for (const { result } of this._runs) {
+      for (const {
+        stop,
+        arrival,
+        legNumber,
+      } of result.routingState.arrivals()) {
+        const existing = arrivals.get(stop);
+        if (existing === undefined || arrival < existing.arrival) {
+          arrivals.set(stop, { arrival, legNumber });
+        }
+      }
+    }
+    return arrivals;
+  }
+
+  /**
+   * Iterates over all Pareto-optimal `(departureTime, result)` pairs,
+   * ordered from the latest departure to the earliest departure.
+   */
+  [Symbol.iterator](): IterableIterator<ParetoRun> {
+    return this._runs[Symbol.iterator]() as IterableIterator<ParetoRun>;
+  }
+}

package/src/routing/rangeRouter.ts

@@ -0,0 +1,167 @@
+import { StopId } from '../stops/stops.js';
+import { StopsIndex } from '../stops/stopsIndex.js';
+import { Time } from '../timetable/time.js';
+import { Timetable } from '../timetable/timetable.js';
+import { AccessFinder } from './access.js';
+import { RangeQuery } from './query.js';
+import { ParetoRun, RangeResult } from './rangeResult.js';
+import { RangeRaptorState } from './rangeState.js';
+import { Raptor } from './raptor.js';
+import { Result } from './result.js';
+import { RoutingState, UNREACHED_TIME } from './state.js';
+
+export class RangeRouter {
+  private readonly timetable: Timetable;
+  private readonly stopsIndex: StopsIndex;
+  private readonly accessFinder: AccessFinder;
+  private readonly raptor: Raptor;
+
+  constructor(
+    timetable: Timetable,
+    stopsIndex: StopsIndex,
+    accessFinder: AccessFinder,
+    raptor: Raptor,
+  ) {
+    this.timetable = timetable;
+    this.stopsIndex = stopsIndex;
+    this.accessFinder = accessFinder;
+    this.raptor = raptor;
+  }
+
+  /**
+   * Range RAPTOR: finds all Pareto-optimal journeys within the departure-time
+   * window `[query.departureTime, query.lastDepartureTime]`.
+   *
+   * A journey is Pareto-optimal iff no journey departing no earlier arrives no
+   * later. Runs are ordered latest-departure-first in the returned result.
+   *
+   * @param query A {@link RangeQuery} with both `departureTime` and `lastDepartureTime` set.
+   * @returns A {@link RangeResult} exposing the full Pareto frontier.
+   */
+  rangeRoute(query: RangeQuery): RangeResult {
+    const { departureTime: earliest, lastDepartureTime: latest } = query;
+
+    const destinations = Array.from(query.to)
+      .flatMap((destination) => this.stopsIndex.equivalentStops(destination))
+      .map((destination) => destination.id);
+
+    const accessLegs = this.accessFinder.collectAccessPaths(
+      query.from,
+      query.options.minTransferTime,
+    );
+
+    const departureSlots = this.accessFinder.collectDepartureTimes(
+      accessLegs,
+      earliest,
+      latest,
+    );
+    if (departureSlots.length === 0) {
+      return new RangeResult([], new Set(destinations));
+    }
+
+    const maxRounds = query.options.maxTransfers + 1;
+
+    const rangeState = new RangeRaptorState(
+      maxRounds,
+      this.timetable.nbStops(),
+      latest,
+    );
+
+    const paretoRuns: ParetoRun[] = [];
+
+    const paretoDestBest = new Map<StopId, Time>();
+    for (const dest of destinations) {
+      paretoDestBest.set(dest, UNREACHED_TIME);
+    }
+
+    const trivialDests = new Set(
+      accessLegs
+        .map((leg) => leg.toStopId)
+        .filter((id) => destinations.includes(id)),
+    );
+    const trivialDestCovered = new Set<StopId>();
+
+    let routingState: RoutingState | null = null;
+
+    if (query.rangeOptions.optimizeBeyondLatestDeparture) {
+      routingState = new RoutingState(
+        latest + 1,
+        destinations,
+        accessLegs,
+        this.timetable.nbStops(),
+        maxRounds,
+      );
+      rangeState.setCurrentRun(routingState);
+      this.raptor.run(
+        {
+          ...query.options,
+          maxInitialWaitingTime: undefined,
+        },
+        rangeState,
+      );
+      for (const dest of destinations) {
+        const t = routingState.arrivalTime(dest);
+        if (t < (paretoDestBest.get(dest) ?? UNREACHED_TIME))
+          paretoDestBest.set(dest, t);
+      }
+    }
+
+    for (const { depTime, legs } of departureSlots) {
+      if (trivialDestCovered.size === destinations.length) break;
+
+      if (routingState === null) {
+        routingState = new RoutingState(
+          depTime,
+          destinations,
+          legs,
+          this.timetable.nbStops(),
+          maxRounds,
+        );
+      } else {
+        routingState.resetFor(depTime, legs);
+      }
+      rangeState.setCurrentRun(routingState);
+      this.raptor.run(
+        {
+          ...query.options,
+          maxInitialWaitingTime: 0,
+        },
+        rangeState,
+      );
+
+      let isParetoOptimal = false;
+      for (const dest of destinations) {
+        const arrival = routingState.arrivalTime(dest);
+        if (arrival >= (paretoDestBest.get(dest) ?? UNREACHED_TIME)) {
+          continue;
+        }
+
+        if (trivialDests.has(dest) && trivialDestCovered.has(dest)) {
+          paretoDestBest.set(dest, arrival);
+          continue;
+        }
+
+        paretoDestBest.set(dest, arrival);
+        if (trivialDests.has(dest)) {
+          trivialDestCovered.add(dest);
+        }
+        isParetoOptimal = true;
+      }
+
+      if (isParetoOptimal) {
+        paretoRuns.push({
+          departureTime: depTime,
+          result: new Result(
+            new Set(destinations),
+            routingState,
+            this.stopsIndex,
+            this.timetable,
+          ),
+        });
+        routingState = null;
+      }
+    }
+
+    return new RangeResult(paretoRuns, new Set(destinations));
+  }
+}

package/src/routing/rangeState.ts

@@ -0,0 +1,150 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+import { StopId } from '../stops/stops.js';
+import { Time } from '../timetable/time.js';
+import type { IRaptorState } from './raptor.js';
+import { RoutingEdge, RoutingState, UNREACHED_TIME } from './state.js';
+
+/**
+ * RAPTOR state for Range RAPTOR mode, implementing {@link IRaptorState}.
+ *
+ * Holds both the cross-run shared labels (carried over from one departure-time
+ * iteration to the next, latest → earliest) and a reference to the current
+ * per-iteration {@link RoutingState} (swapped via {@link setCurrentRun}).
+ *
+ * Concretely, `roundLabels[k][p]` is the best known arrival at stop `p` using
+ * at most `k` transit legs, across **all departure times tried so far**.
+ *
+ * @see https://www.microsoft.com/en-us/research/wp-content/uploads/2012/01/raptor_alenex.pdf
+ */
+export class RangeRaptorState implements IRaptorState {
+  /**
+   * `roundLabels[k]` is a flat `Uint16Array` of size `nbStops`.
+   * `roundLabels[k][p]` = best arrival time (minutes from midnight) at stop `p`
+   * in round `k`, across all departure-time iterations processed so far.
+   * Pre-filled with `UNREACHED_TIME`; updated in-place as better arrivals are found.
+   */
+  readonly roundLabels: Uint16Array[];
+
+  /**
+   * The latest departure time of the range query.
+   */
+  readonly latestDeparture: Time;
+
+  /**
+   * Global best arrival at any destination stop across all runs and rounds.
+   * Used for destination-pruning inside scan methods so that routes that cannot
+   * beat the already-known best are skipped early.
+   */
+  private _destinationBest: Time = UNREACHED_TIME;
+
+  /**
+   * Sparse change-tracking for `initRound`.
+   *
+   * `changedInRound[k]` is the list of stops whose round-k label was improved
+   * (via `tryImprove`) since the last call to `initRound(k + 1)`.  When
+   * `initRound(k + 1)` runs, it only visits these stops instead of scanning
+   * all `nbStops` entries, reducing the work from O(nbStops × rounds ×
+   * departureTimes) to O(changedStops × rounds × departureTimes).
+   *
+   * Duplicates are allowed and harmless — a stop that appears twice merely
+   * receives a redundant (no-op) min-update on the second visit.  The list is
+   * cleared inside `initRound` immediately after processing.
+   */
+  private readonly changedInRound: StopId[][];
+
+  private currentRun!: RoutingState;
+
+  constructor(maxRounds: number, nbStops: number, latestDeparture: Time) {
+    this.latestDeparture = latestDeparture;
+    // maxRounds + 2: index 0 = origin/walk legs, indices 1…maxRounds+1 = transit rounds
+    this.roundLabels = Array.from({ length: maxRounds + 2 }, () =>
+      new Uint16Array(nbStops).fill(UNREACHED_TIME),
+    );
+    this.changedInRound = Array.from({ length: maxRounds + 2 }, () => []);
+  }
+
+  /**
+   * Swaps in a fresh {@link RoutingState} for the next departure-time iteration
+   * and seeds the shared round-0 labels from its access arrivals.
+   *
+   * Must be called before every `runRaptor` invocation.
+   */
+  setCurrentRun(routingState: RoutingState): void {
+    this.currentRun = routingState;
+    // Propagate round-0 access arrivals into the shared labels so that
+    // initRound(1) can tighten round-1 pruning bounds correctly.
+    const round0 = routingState.graph[0]!;
+    for (const stop of routingState.origins) {
+      const edge = round0[stop];
+      if (!edge) continue;
+      this.updateArrival(stop, edge.arrival, 0);
+    }
+  }
+
+  get origins(): StopId[] {
+    return this.currentRun.origins;
+  }
+
+  get graph(): (RoutingEdge | undefined)[][] {
+    return this.currentRun.graph;
+  }
+
+  arrivalTime(stop: StopId): Time {
+    return this.currentRun.arrivalTime(stop);
+  }
+
+  /**
+   * Uses the cross-run shared label for `round`, which is always at least as
+   * tight as the per-run arrival and therefore provides stronger pruning.
+   */
+  improvementBound(round: number, stop: StopId): Time {
+    return this.roundLabels[round]![stop]!;
+  }
+
+  /**
+   * Global best arrival at any destination across all departure-time iterations.
+   * Always at least as tight as the per-run `destinationBest`.
+   */
+  get destinationBest(): Time {
+    return this._destinationBest;
+  }
+
+  isDestination(stop: StopId): boolean {
+    return this.currentRun.isDestination(stop);
+  }
+
+  /** Updates both the per-run state and the cross-run shared labels. */
+  updateArrival(stop: StopId, time: Time, round: number): void {
+    this.currentRun.updateArrival(stop, time, round);
+    if (time < this.roundLabels[round]![stop]!) {
+      this.roundLabels[round]![stop] = time;
+      this.changedInRound[round]!.push(stop);
+      if (this.currentRun.isDestination(stop) && time < this._destinationBest) {
+        this._destinationBest = time;
+      }
+    }
+  }
+
+  /**
+   * initialized round `k` from round `k-1`: τk(p) ← min(τk(p), τk-1(p)).
+   *
+   * Must be called at the very start of each RAPTOR round before routes are
+   * scanned.  After this call, `roundLabels[k][p]` is the minimum arrival at
+   * stop `p` achievable with **at most** k transit legs from any departure time
+   * tried so far — which is exactly the tightest valid pruning bound for round k.
+   */
+  initRound(round: number): void {
+    const changed = this.changedInRound[round - 1]!;
+    if (changed.length === 0) return;
+
+    const prev = this.roundLabels[round - 1]!;
+    const curr = this.roundLabels[round]!;
+    for (let i = 0; i < changed.length; i++) {
+      const stop = changed[i]!;
+      if (prev[stop]! < curr[stop]!) {
+        curr[stop] = prev[stop]!;
+      }
+    }
+    changed.length = 0;
+  }
+}