bmssp 0.19.0 → 1.0.1

package/README.md

@@ -15,9 +15,11 @@ first to beat Dijkstra's O(m + n·log n) bound on sparse directed graphs.
 
 ## Project status
 
-The project is built piece by piece against the paper, with every building block shipped,
-tested, and released individually. Current focus: milestone
-[`1.0.0` — first end-to-end functional BMSSP](https://github.com/Sirivasv/bmssp-js/milestones).
+**The algorithm is functional end-to-end as of `1.0.0`** 🎉 — `calculateShortestPaths()`
+computes distances via the paper's method (FindPivots → block list → recursive BMSSP with
+the bounded base case), validated node-by-node against a Dijkstra oracle, including on a
+real 2-million-node road network. The project was built piece by piece against the paper,
+with every building block shipped, tested, and released individually:
 
 | Building block (paper) | Where | Status |
 | --- | --- | --- |
@@ -27,12 +29,19 @@ tested, and released individually. Current focus: milestone
 | Indexed binary min-heap ([#41](https://github.com/Sirivasv/bmssp-js/issues/41)) | `src/heap.mjs` | ✅ done |
 | `BaseCase(B, S)` — Algorithm 2, bounded mini-Dijkstra ([#40](https://github.com/Sirivasv/bmssp-js/issues/40)) | `src/baseCase.mjs` | ✅ done |
 | `FindPivots(B, S)` — Algorithm 1, frontier shrinking ([#44](https://github.com/Sirivasv/bmssp-js/issues/44)) | `src/findPivots.mjs` | ✅ done |
-| `BMSSP(l, B, S)` — Algorithm 3, the main recursion ([#43](https://github.com/Sirivasv/bmssp-js/issues/43)) | — | 🔨 next up — the last piece |
-
-> **Honest note:** until [#43](https://github.com/Sirivasv/bmssp-js/issues/43) lands,
-> `calculateShortestPaths()` computes distances with the reference Dijkstra implementation.
-> The shipped BMSSP building blocks (block list, heap, base case, pivot finding) are fully
-> tested but not yet wired into the public entry point.
+| `BMSSP(l, B, S)` — Algorithm 3, the main recursion ([#43](https://github.com/Sirivasv/bmssp-js/issues/43)) | `src/bmssp.mjs` | ✅ done — **1.0.0** |
+
+> **Honest note:** the paper's win is asymptotic, and this repo optimizes for correctness
+> and readability, not raw speed. Measured head-to-head (algorithm time only, graph
+> loading excluded — see [benchmarks/HEAD-TO-HEAD.md](benchmarks/HEAD-TO-HEAD.md)):
+> Dijkstra still wins on wall-clock at every practical size, though the gap narrows as
+> sparse graphs grow (2.5× at 50k nodes → 1.57× at 2M). But in the paper's own metric —
+> **comparisons between path lengths** — BMSSP does **fewer comparisons than Dijkstra
+> from about n = 1M on sparse graphs** (0.91× at n = 2M), and the advantage grows with
+> size: the "sorting barrier" is measurably broken; what remains is JS constant factors.
+> Where inputs violate the paper's distinct-path-lengths assumption (e.g. zero-weight
+> edges), documented tie guards keep the results correct
+> ([#163](https://github.com/Sirivasv/bmssp-js/issues/163) tracks a principled tie-break).
 
 ## How it works (in two ideas)
 
@@ -44,7 +53,9 @@ tested, and released individually. Current focus: milestone
    ordered *between* blocks but unsorted *within* them — enough to repeatedly pull the next
    closest batch without paying the Θ(log n)-per-vertex "sorting barrier."
 
-The asymptotic win is theoretical (the crossover point is astronomically large); this repo
+The wall-clock crossover point is astronomically large, but the asymptotics are real: in
+measured comparison counts this implementation already beats Dijkstra past ~1M nodes on
+sparse graphs ([benchmarks/HEAD-TO-HEAD.md](benchmarks/HEAD-TO-HEAD.md)). This repo
 optimizes for a **correct, readable, well-tested** implementation, validated line-by-line
 against a Dijkstra oracle — not for raw speed.
 
@@ -101,17 +112,28 @@ npm run lint      # Prettier + ESLint
 npm run bench     # seeded micro-benchmarks (see benchmarks/README.md)
 ```
 
+The measured BMSSP-vs-Dijkstra head-to-head — wall-clock and comparison counts, with
+methodology — lives in [benchmarks/HEAD-TO-HEAD.md](benchmarks/HEAD-TO-HEAD.md)
+([#170](https://github.com/Sirivasv/bmssp-js/issues/170) tracks harness integration).
+
 The test suite's core contract: for every node, BMSSP's distances must equal the Dijkstra
-oracle's — including on `test/roadNet-CA.txt`, a real road network from SNAP.
+oracle's — including on `test/roadNet-CA.txt`, a real road network from SNAP. A seeded
+property/fuzz suite (`test/fuzz.test.mjs`) hammers that contract across eight graph shapes
+(sparse/dense random, grids, chains, stars, DAGs, disconnected forests, multigraphs),
+extreme weight regimes (all-zero, mixed zero/huge, exact floats), and direct multi-source
+bounded calls checked against per-source oracles. It runs in `npm test` by default; crank
+the volume with the `FUZZ_ROUNDS` multiplier (e.g. `FUZZ_ROUNDS=25 npm test -- test/fuzz.test.mjs`
+checks several thousand graphs in a few seconds). Failures always report the seed that
+produced them.
 
 ## Roadmap
 
-| Milestone | Theme |
-| --- | --- |
-| [`1.0.0`](https://github.com/Sirivasv/bmssp-js/milestones) | First end-to-end functional BMSSP (issues #40–#45) |
-| `1.1.0` | Correctness hardening — fuzz tests, edge cases, tie-breaking, input validation |
-| `1.2.0` | Performance & ergonomics — exact Lemma 3.3 asymptotics, path reconstruction, BMSSP-vs-Dijkstra benchmarks |
-| `2.0.0` | API generalization — public multi-source/bounded entry point, flexible inputs |
+| Milestone | Theme | Status |
+| --- | --- | --- |
+| [`1.0.0`](https://github.com/Sirivasv/bmssp-js/milestones) | First end-to-end functional BMSSP (issues #40–#45) | ✅ done |
+| `1.1.0` | Correctness hardening — fuzz tests, edge cases, tie-breaking, input validation | 🔨 current focus |
+| `1.2.0` | Performance & ergonomics — exact Lemma 3.3 asymptotics, path reconstruction, BMSSP-vs-Dijkstra benchmarks | planned |
+| `2.0.0` | API generalization — public multi-source/bounded entry point, flexible inputs | planned |
 
 Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the
 [`help wanted` / `good first issue` labels](https://github.com/Sirivasv/bmssp-js/issues).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmssp",
-  "version": "0.19.0",
+  "version": "1.0.1",
   "description": "Javascript package implementation of the bmssp algorithm.",
   "main": "index.mjs",
   "keywords": [

package/src/bmssp.mjs

@@ -1,4 +1,6 @@
-import { dijkstra } from "./dijkstra.mjs";
+import { baseCase } from "./baseCase.mjs";
+import { findPivots } from "./findPivots.mjs";
+import { BlockList } from "./blockList.mjs";
 
 class BMSSP {
   constructor(inputGraph) {
@@ -27,6 +29,9 @@ class BMSSP {
 
     // Initialize shortest paths map
     this.initializeShortestPaths();
+
+    // Derive the paper's k / t parameters and the top recursion level
+    this.deriveParameters();
   }
 
   // Method to (re)build the adjacency map from this.graph.
@@ -59,7 +64,162 @@ class BMSSP {
     }
   }
 
-  // Method to calculate shortest paths from startNode using Dijkstra
+  /**
+   * Derive the paper's parameters from n = |V| and store them on the
+   * instance:
+   * - k = max(1, ⌊(log₂ n)^(1/3)⌋) — Bellman-Ford rounds in FindPivots and
+   *   the BaseCase settle cap,
+   * - t = max(1, ⌊(log₂ n)^(2/3)⌋) — branching / level sizing,
+   * - topLevel = max(1, ⌈log₂ n / t⌉) — level of the top BMSSP call.
+   * Everything is clamped to >= 1 so tiny graphs stay out of degenerate
+   * regimes: correctness never depends on the asymptotics.
+   */
+  deriveParameters() {
+    const logn = Math.log2(Math.max(2, this.nodeIDs.size));
+    this.k = Math.max(1, Math.floor(logn ** (1 / 3)));
+    this.t = Math.max(1, Math.floor(logn ** (2 / 3)));
+    this.topLevel = Math.max(1, Math.ceil(logn / this.t));
+  }
+
+  /**
+   * BMSSP(l, B, S) — Algorithm 3 of "Breaking the Sorting Barrier for
+   * Directed Single-Source Shortest Paths": the main bounded multi-source
+   * recursion, wiring FindPivots (Algorithm 1), the Lemma 3.3 BlockList and
+   * BaseCase (Algorithm 2) together.
+   *
+   * Preconditions (the top-level call satisfies them trivially):
+   * - Every vertex in S is complete (this.shortestPaths holds its true
+   *   distance), and every incomplete vertex v with d(v) < B has a shortest
+   *   path through some complete vertex of S.
+   *
+   * Distance estimates live in this.shortestPaths (the paper's d̂[·]) and
+   * are relaxed in place at every level.
+   *
+   * Two outcomes (Lemma 3.1):
+   * - Successful execution: the block list emptied — bound === B and
+   *   vertices holds every v with d(v) < B reachable through S.
+   * - Partial execution: the k·2^(l·t) workload guard tripped — bound < B
+   *   and vertices holds exactly the v with d(v) < bound.
+   *   Every returned vertex is complete either way.
+   *
+   * @param {number} l - Recursion level; 0 delegates to baseCase
+   * @param {number} B - Strict upper bound on the distances in scope (Infinity is allowed)
+   * @param {Set<*>} S - Non-empty set of complete frontier sources
+   * @returns {{ bound: number, vertices: Set<*> }} The boundary B' <= B and
+   *   the set U of vertices completed below it
+   */
+  bmssp(l, B, S) {
+    const dHat = this.shortestPaths;
+    if (l === 0) {
+      return baseCase(B, S, dHat, this.adjacency, this.k);
+    }
+
+    // Shrink the frontier: only the pivots are worth recursing on, and W
+    // is a batch of already-completed vertices folded in at the end
+    const { pivots, W } = findPivots(B, S, dHat, this.adjacency, this.k);
+
+    // Seed the Lemma 3.3 block list with the pivots. lastBound tracks the
+    // paper's Bi': B when P is empty, min d̂ over P before the first pull,
+    // then the boundary returned by the latest recursive call.
+    // A pivot with d̂ >= B is out of scope at this level (only possible
+    // when equal path lengths violate Assumption 2.1 and a pull returned
+    // a key tied with its separator): skip it — the ancestor whose band
+    // covers its distance is responsible for it.
+    const D = new BlockList(2 ** ((l - 1) * this.t), B);
+    let lastBound = B;
+    for (const x of pivots) {
+      const dx = dHat.get(x);
+      if (dx < B) {
+        D.insert(x, dx);
+        if (dx < lastBound) lastBound = dx;
+      }
+    }
+
+    const U = new Set();
+    const workloadCap = this.k * 2 ** (l * this.t);
+
+    while (U.size < workloadCap && !D.isEmpty()) {
+      // Bi, Si <- D.Pull(): the next-closest small batch and its separator
+      const { keys: Si, bound: Bi } = D.pull();
+      let { bound: BiPrime, vertices: Ui } = this.bmssp(l - 1, Bi, Si);
+
+      if (Ui.size === 0) {
+        // Degenerate tie stall: the child settled only vertices tied
+        // exactly at its boundary (possible only through zero-weight
+        // paths, which violate the paper's Assumption 2.1 — see #163),
+        // so its strict d̂ < B' filter returned nothing and this batch
+        // would be re-pulled forever. Escape hatch: settle everything
+        // below Bi reachable through the batch with an uncapped bounded
+        // Dijkstra per member — correct, just not sublinear.
+        Ui = new Set();
+        for (const x of Si) {
+          const { vertices } = baseCase(
+            Bi,
+            new Set([x]),
+            dHat,
+            this.adjacency,
+            Math.max(1, this.nodeIDs.size),
+          );
+          for (const v of vertices) Ui.add(v);
+        }
+        BiPrime = Bi;
+      }
+
+      lastBound = BiPrime;
+      for (const v of Ui) U.add(v);
+
+      // Relax out of the newly-completed Ui, routing improved neighbors
+      // by distance band: [Bi, B) re-enters the block list, [Bi', Bi) is
+      // staged for a batch prepend (closer than the current batch's floor)
+      const K = [];
+      for (const u of Ui) {
+        const du = dHat.get(u);
+        for (const [v, weight] of this.adjacency.get(u) ?? []) {
+          const candidate = du + weight;
+          // Paper relaxation: d̂[u] + w(u,v) <= d̂[v] always updates d̂
+          if (candidate <= (dHat.get(v) ?? Infinity)) {
+            dHat.set(v, candidate);
+            // A vertex already completed at this level cannot strictly
+            // improve (non-negative weights), so an equal-sum relaxation
+            // — which the <= allows, e.g. via a zero-weight cycle — must
+            // not be re-queued (mirrors the baseCase settled guard)
+            if (U.has(v)) continue;
+            if (candidate >= Bi && candidate < B) {
+              D.insert(v, candidate);
+            } else if (candidate >= BiPrime && candidate < Bi) {
+              K.push([v, candidate]);
+            }
+          }
+        }
+      }
+      // Batch members the child did not complete (d̂ still in [Bi', Bi))
+      // go back in front of everything else. A member tied exactly at the
+      // separator (d̂ == Bi < B, an Assumption 2.1 violation) is still in
+      // scope at this level and re-enters through a regular insert.
+      for (const x of Si) {
+        if (U.has(x)) continue;
+        const dx = dHat.get(x);
+        if (dx >= BiPrime && dx < Bi) {
+          K.push([x, dx]);
+        } else if (dx === Bi && Bi < B) {
+          D.insert(x, dx);
+        }
+      }
+      if (K.length > 0) D.batchPrepend(K);
+    }
+
+    // B' <- min(last Bi', B); fold in the FindPivots batch below it
+    const bound = Math.min(lastBound, B);
+    for (const x of W) {
+      if (dHat.get(x) < bound) U.add(x);
+    }
+    return { bound, vertices: U };
+  }
+
+  // Method to calculate shortest paths from startNode via the BMSSP
+  // recursion (Algorithm 3). The top-level call BMSSP(topLevel, ∞, {start})
+  // is always a successful execution, so it completes every reachable
+  // vertex; unreachable ones keep their Infinity estimate.
   calculateShortestPaths(startNode) {
     // To clean the state before calculation
     this.initializeShortestPaths();
@@ -69,10 +229,9 @@ class BMSSP {
       throw new Error("Start node not found in the graph");
     }
 
-    const result = dijkstra(this.graph, this.nodeIDs, startNode);
-    result.forEach((distance, nodeId) => {
-      this.shortestPaths.set(nodeId, distance);
-    });
+    // The source is complete at distance 0; everything else is Infinity
+    this.shortestPaths.set(startNode, 0);
+    this.bmssp(this.topLevel, Infinity, new Set([startNode]));
   }
 }