bmssp 0.18.0 → 1.0.0

package/README.md

@@ -1,64 +1,130 @@
 # BMSSP: Bounded Multi-Source Shortest Paths
+
 [![codecov](https://codecov.io/gh/sirivasv/bmssp-js/branch/main/graph/badge.svg)](https://codecov.io/gh/sirivasv/bmssp-js)
 [![npm version](https://img.shields.io/npm/v/bmssp.svg)](https://www.npmjs.com/package/bmssp)
 [![Docker Image Version](https://img.shields.io/docker/v/sirivasv/bmssp-js?label=docker&sort=semver)](https://hub.docker.com/r/sirivasv/bmssp-js)
 [![GitHub Repo stars](https://img.shields.io/github/stars/sirivasv/bmssp-js?style=social)](https://github.com/sirivasv/bmssp-js/stargazers)
 
-This repository provides a community-driven JavaScript implementation of the Tsinghua Single Source Shortest Paths algorithm, based on the paper ["Breaking the Sorting Barrier for Directed Single-Source Shortest Paths"](https://dl.acm.org/doi/10.1145/3717823.3718179) by Duan Ran et al. from Tsinghua University.
-
-BMSSP stands for Bounded Multi-Source Shortest Paths.
-
-## Project Overview
-
-- **Language:** JavaScript (ES Modules)
-- **Goal:** Provide an easy-to-use, modern implementation of the algorithm, published to [npmjs.com](https://www.npmjs.com/).
-- **Reference:** For more on ES modules, see the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules).
-
+A community-driven JavaScript (ES Modules) implementation of the Tsinghua single-source
+shortest-paths algorithm from the paper
+["Breaking the Sorting Barrier for Directed Single-Source Shortest Paths"](https://dl.acm.org/doi/10.1145/3717823.3718179)
+(Duan, Mao, Mao, Shu, Yin — 2025): a deterministic **O(m·log^(2/3) n)** SSSP algorithm, the
+first to beat Dijkstra's O(m + n·log n) bound on sparse directed graphs.
+
+**BMSSP** stands for **B**ounded **M**ulti-**S**ource **S**hortest **P**aths.
+
+## Project status
+
+**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 |
+| --- | --- | --- |
+| Reference Dijkstra oracle (ground truth for tests) | `src/dijkstra.mjs` | ✅ done |
+| O(1) adjacency map for edge relaxation ([#45](https://github.com/Sirivasv/bmssp-js/issues/45)) | `BMSSP` constructor | ✅ done |
+| Lemma 3.3 block-based partial-sort structure `D` ([#42](https://github.com/Sirivasv/bmssp-js/issues/42)) | `src/blockList.mjs` | ✅ done |
+| 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)) | `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. On the full California road network (~2 M nodes, ~5.5 M
+> edges) this implementation currently runs about 2× slower than its own reference
+> Dijkstra — consistent with published experimental studies of the algorithm. 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)
+
+1. **Shrink the frontier with pivots.** Instead of keeping every frontier vertex in a
+   priority queue like Dijkstra, run `k` rounds of Bellman-Ford-style relaxation and recurse
+   only on the "pivots" — roots of large shortest-path trees. Only ~1/k of the frontier
+   needs the expensive treatment.
+2. **Partial sorting instead of a heap.** A block-based structure keeps batches of vertices
+   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
+optimizes for a **correct, readable, well-tested** implementation, validated line-by-line
+against a Dijkstra oracle — not for raw speed.
 
 ## Installation
 
-To install this package, you can use npm:
-
 ```bash
 npm install bmssp
 ```
 
 ## Usage
 
-To use this package, you can import it in your JavaScript code as follows:
+The package is ESM-only (`.mjs`). Graphs are arrays of `[from, to, weight]` edges with
+numeric node IDs and non-negative weights:
 
 ```javascript
-// This is a WIP example
 import { BMSSP } from "bmssp";
 
-const myBMSSP = new BMSSP([
+const graph = new BMSSP([
   [0, 1, 50],
   [1, 2, 75],
   [0, 2, 25],
 ]);
 
-console.log(myBMSSP.graph);
+graph.calculateShortestPaths(0);
+console.log(graph.shortestPaths); // Map(3) { 0 => 0, 1 => 50, 2 => 25 }
 ```
 
-The file must use ECMAScript modules (ESM) syntax and have the `.mjs` file extension. Go to the `examples` directory for more usage examples.
+A reference `dijkstra` implementation is also exported. See the `examples/` directory for
+more.
 
-### Using the docker image
+### Using the Docker image
 
-You can also use the published docker image and run the example:
+Run the bundled example:
 
 ```bash
 docker run -it sirivasv/bmssp-js:latest
 ```
 
-Or your tests in a pre-configured environment (replace `folder-mytest/` with your tests folder and `index.mjs` with your test file):
+Or run your own tests in a pre-configured environment (replace `folder-mytest/` with your
+tests folder and `index.mjs` with your test file):
 
 ```bash
 docker run -it -v ./folder-mytest/:/bmssp-js/folder-mytest/ sirivasv/bmssp-js:latest node /bmssp-js/folder-mytest/index.mjs
 ```
 
-Other versions of the docker image can be found on [Docker Hub](https://hub.docker.com/r/sirivasv/bmssp-js/tags).
+Other image versions are on [Docker Hub](https://hub.docker.com/r/sirivasv/bmssp-js/tags).
+
+## Development
+
+```bash
+npm install
+npm test          # Jest suite, incl. BMSSP-vs-Dijkstra equivalence on a real road network
+npm run lint      # Prettier + ESLint
+npm run bench     # seeded micro-benchmarks (see benchmarks/README.md)
+```
+
+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.
+
+## Roadmap
+
+| 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).
+
+## Other implementations on GitHub
 
-### Other Implementations in GitHub
+<https://github.com/search?q=bmssp&type=repositories>
 
-https://github.com/search?q=bmssp&type=repositories
+## License
 
+[MPL-2.0](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmssp",
-  "version": "0.18.0",
+  "version": "1.0.0",
   "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]));
   }
 }
 

package/src/findPivots.mjs

@@ -0,0 +1,113 @@
+/**
+ * FindPivots(B, S) — Algorithm 1 of "Breaking the Sorting Barrier for Directed
+ * Single-Source Shortest Paths". Shrinks the frontier S: runs k rounds of
+ * Bellman-Ford-style relaxation out of S, collecting every vertex relaxed
+ * below B into W, then identifies the pivots — the vertices of S that root a
+ * large (>= k vertices) tree in the forest of tight shortest-path edges. Only
+ * the pivots need to be carried into the deeper BMSSP recursion.
+ *
+ * Preconditions (guaranteed by the caller, Algorithm 3):
+ * - Every vertex in S is complete (dHat holds its true distance).
+ * - Every incomplete vertex v with d(v) < B has a shortest path through some
+ *   complete vertex in S.
+ *
+ * Distance estimates are read from and written into dHat in place — exactly
+ * like the paper's global d̂[·] labels, so improvements made here are visible
+ * to the levels above. The `<=` relaxation updates d̂ unconditionally; the
+ * `< B` test only gates membership in W.
+ *
+ * Two outcomes:
+ * - Early exit (|W| grows past k·|S|): the frontier is already small relative
+ *   to W, so every vertex of S is a pivot.
+ * - Forest case (k rounds complete with |W| <= k·|S|): pivots are the S-roots
+ *   of tight-edge trees with >= k vertices. Equal-length paths can make the
+ *   tight-edge graph a DAG (see #163); each vertex is assigned at most one
+ *   parent deterministically (first tight edge in W iteration order) so tree
+ *   sizes are well-defined. Guarantees |pivots| <= |W| / k either way.
+ *
+ * @param {number} B - Strict upper bound gating membership in W (Infinity is allowed)
+ * @param {Set<*>|Iterable<*>} S - Non-empty set of complete frontier sources
+ * @param {Map<*, number>} dHat - Global distance estimates d̂[·], updated in place
+ * @param {Map<*, Array<[*, number]>>} adjacency - nodeId -> outgoing [to, weight] edges
+ * @param {number} k - Relaxation rounds / tree-size threshold, >= 1 (floored);
+ *   the paper's ⌊log^(1/3) n⌋
+ * @returns {{ pivots: Set<*>, W: Set<*> }} The pivot subset of S and the set W
+ *   of vertices touched below B (W always contains S)
+ * @throws {Error} If k is not a number >= 1, S is empty, or any source has no
+ *   finite distance estimate
+ */
+function findPivots(B, S, dHat, adjacency, k) {
+  if (typeof k !== "number" || Number.isNaN(k) || k < 1) {
+    throw new Error("k must be a number >= 1");
+  }
+  const rounds = Math.floor(k);
+  const sources = [...S];
+  if (sources.length === 0) {
+    throw new Error("S must contain at least one source node");
+  }
+  for (const x of sources) {
+    const distance = dHat.get(x);
+    if (typeof distance !== "number" || !Number.isFinite(distance)) {
+      throw new Error("every source must have a finite distance estimate");
+    }
+  }
+
+  // W accumulates everything relaxed below B; layer is the paper's W_{i-1}
+  const W = new Set(sources);
+  let layer = new Set(sources);
+
+  for (let i = 1; i <= rounds; i += 1) {
+    const nextLayer = new Set();
+    for (const u of layer) {
+      for (const [v, weight] of adjacency.get(u) ?? []) {
+        const candidate = dHat.get(u) + weight;
+        // Paper relaxation: <= always updates d̂; < B gates the W membership
+        if (candidate <= (dHat.get(v) ?? Infinity)) {
+          dHat.set(v, candidate);
+          if (candidate < B) nextLayer.add(v);
+        }
+      }
+    }
+    for (const v of nextLayer) W.add(v);
+    layer = nextLayer;
+    if (W.size > rounds * sources.length) {
+      // Frontier already small relative to W: every source is a pivot
+      return { pivots: new Set(sources), W };
+    }
+  }
+
+  // Forest F of tight edges inside W. Each vertex takes at most one parent,
+  // chosen deterministically, so tree sizes stay well-defined even when ties
+  // make F a DAG. Vertices on tight cycles (zero-weight cycles) all end up
+  // with parents, so they belong to no root's tree.
+  const children = new Map();
+  const hasParent = new Set();
+  for (const u of W) {
+    const du = dHat.get(u);
+    for (const [v, weight] of adjacency.get(u) ?? []) {
+      if (v === u || !W.has(v) || hasParent.has(v)) continue;
+      if (dHat.get(v) === du + weight) {
+        hasParent.add(v);
+        if (!children.has(u)) children.set(u, []);
+        children.get(u).push(v);
+      }
+    }
+  }
+
+  // Pivots: sources that root a tight-edge tree with >= k vertices
+  const pivots = new Set();
+  for (const x of sources) {
+    if (hasParent.has(x)) continue;
+    let size = 0;
+    const stack = [x];
+    while (stack.length > 0) {
+      const u = stack.pop();
+      size += 1;
+      for (const child of children.get(u) ?? []) stack.push(child);
+    }
+    if (size >= rounds) pivots.add(x);
+  }
+  return { pivots, W };
+}
+
+export { findPivots };