bmssp 0.17.0 → 0.19.0

package/README.md

@@ -1,64 +1,125 @@
 # 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 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).
+
+| 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)) | — | 🔨 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.
+
+## 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 |
+| --- | --- |
+| [`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 |
+
+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.17.0",
+  "version": "0.19.0",
   "description": "Javascript package implementation of the bmssp algorithm.",
   "main": "index.mjs",
   "keywords": [

package/src/baseCase.mjs

@@ -0,0 +1,94 @@
+import { MinHeap } from "./heap.mjs";
+
+/**
+ * BaseCase(B, S) — Algorithm 2 of "Breaking the Sorting Barrier for Directed
+ * Single-Source Shortest Paths". The level-0 case of the BMSSP recursion: a
+ * mini Dijkstra from the single complete source x in S, bounded above by B,
+ * that stops after settling k + 1 vertices.
+ *
+ * Preconditions (guaranteed by the caller, Algorithm 3):
+ * - S is a singleton {x} and x is complete (dHat holds its true distance).
+ * - Every incomplete vertex v with d(v) < B has a shortest path through x.
+ *
+ * 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.
+ *
+ * Two outcomes:
+ * - Full success (fewer than k + 1 vertices exist under B): every vertex
+ *   with d(v) < B is settled and returned, with bound === B.
+ * - Partial (the k + 1 cap was hit): bound = the largest settled distance
+ *   B' <= B, and only the strictly-closer vertices (d̂ < B') are returned.
+ *   Every returned vertex is complete either way.
+ *
+ * @param {number} B - Strict upper bound on the distances to settle (Infinity is allowed)
+ * @param {Set<*>|Iterable<*>} S - Singleton set holding the complete source x
+ * @param {Map<*, number>} dHat - Global distance estimates d̂[·], updated in place
+ * @param {Map<*, Array<[*, number]>>} adjacency - nodeId -> outgoing [to, weight] edges
+ * @param {number} k - Settle cap parameter, >= 1 (floored); the paper's ⌊log^(1/3) n⌋
+ * @returns {{ bound: number, vertices: Set<*> }} The boundary B' <= B and the
+ *   set U of vertices settled below it
+ * @throws {Error} If k is not a number >= 1, S is not a singleton, or the
+ *   source has no finite distance estimate
+ */
+function baseCase(B, S, dHat, adjacency, k) {
+  if (typeof k !== "number" || Number.isNaN(k) || k < 1) {
+    throw new Error("k must be a number >= 1");
+  }
+  const cap = Math.floor(k);
+  const sources = [...S];
+  if (sources.length !== 1) {
+    throw new Error("S must contain exactly one source node");
+  }
+  const [x] = sources;
+  const sourceDistance = dHat.get(x);
+  if (typeof sourceDistance !== "number" || !Number.isFinite(sourceDistance)) {
+    throw new Error("the source must have a finite distance estimate");
+  }
+
+  // U0 in the paper: the vertices settled by this call, seeded with x
+  const settled = new Set([x]);
+  const heap = new MinHeap();
+  heap.insert(x, sourceDistance);
+
+  while (!heap.isEmpty() && settled.size < cap + 1) {
+    const { key: u, value: du } = heap.extractMin();
+    settled.add(u);
+    for (const [v, weight] of adjacency.get(u) ?? []) {
+      const candidate = du + weight;
+      // Paper relaxation: d̂[u] + w(u,v) <= d̂[v], and below the bound B
+      if (candidate <= (dHat.get(v) ?? Infinity) && candidate < B) {
+        dHat.set(v, candidate);
+        // With non-negative weights a vertex settled in this call cannot
+        // strictly improve, so an equal-sum relaxation (which the <= allows,
+        // e.g. via a zero-weight cycle) must not re-enter the heap.
+        if (settled.has(v)) continue;
+        if (heap.has(v)) {
+          heap.decreaseKey(v, candidate);
+        } else {
+          heap.insert(v, candidate);
+        }
+      }
+    }
+  }
+
+  if (settled.size <= cap) {
+    // Exhausted before the cap: everything under B is settled (B' = B)
+    return { bound: B, vertices: settled };
+  }
+
+  // Hit the k + 1 cap: report B' = the largest settled distance and return
+  // only the vertices strictly below it
+  let boundary = -Infinity;
+  for (const v of settled) {
+    const distance = dHat.get(v);
+    if (distance > boundary) boundary = distance;
+  }
+  const vertices = new Set();
+  for (const v of settled) {
+    if (dHat.get(v) < boundary) vertices.add(v);
+  }
+  return { bound: boundary, vertices };
+}
+
+export { baseCase };

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 };