bmssp 1.1.0 → 1.1.1

package/README.md

@@ -34,15 +34,25 @@ with every building block shipped, tested, and released individually:
 | Shortest-path reconstruction ([#169](https://github.com/Sirivasv/bmssp-js/issues/169)) | `BMSSP.reconstructPath()` | ✅ done |
 | Constructor input validation ([#165](https://github.com/Sirivasv/bmssp-js/issues/165)) | `BMSSP` constructor | ✅ done |
 | Opt-in constant-degree transform, in/out-degree ≤ 2 ([#164](https://github.com/Sirivasv/bmssp-js/issues/164)) | `constantDegreeTransform()` | ✅ done |
+| BMSSP-vs-Dijkstra head-to-head in the benchmark harness ([#170](https://github.com/Sirivasv/bmssp-js/issues/170)) | `npm run bench` / `npm run bench:counts` | ✅ done |
+| Performance-cliff investigation; quadratic `BatchPrepend` fixed ([#182](https://github.com/Sirivasv/bmssp-js/issues/182)) | `src/blockList.mjs` | ✅ done — **1.1.1** |
 
 > **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)):
+> loading excluded — rerun it yourself with `npm run bench`; methodology and the deep
+> 1.0.0 record in [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.
+> from about n = 1M on sparse graphs** (`npm run bench:counts` measures the ratio falling
+> 1.20× at 50k → 1.03× at 200k → 0.98× at 1M; 0.91× at 2M in the record), and the
+> advantage grows with size: the "sorting barrier" is measurably broken; what remains is
+> JS constant factors. The two performance cliffs found in the 1.0.0 measurements were
+> run down in [#182](https://github.com/Sirivasv/bmssp-js/issues/182): the star-graph
+> blowup was a quadratic in `BatchPrepend`'s bookkeeping — fixed in `1.1.1` (500k-node
+> star: 61 s → ~3 s) — and the recursion-level step is an inherent, measured ~+24% per
+> extra level (see the addendum in
+> [benchmarks/HEAD-TO-HEAD.md](benchmarks/HEAD-TO-HEAD.md)).
 > Where inputs violate the paper's distinct-path-lengths assumption (e.g. zero-weight
 > edges), a principled deterministic tie-break
 > ([#163](https://github.com/Sirivasv/bmssp-js/issues/163)) realizes that assumption in
@@ -145,14 +155,17 @@ Other image versions are on [Docker Hub](https://hub.docker.com/r/sirivasv/bmssp
 
 ```bash
 npm install
-npm test          # Jest suite — every graph seeded, every failure reproducible (~3 s)
-npm run lint      # Prettier + ESLint
-npm run bench     # seeded micro-benchmarks (see benchmarks/README.md)
+npm test              # Jest suite — every graph seeded, every failure reproducible (~7 s)
+npm run lint          # Prettier + ESLint
+npm run bench         # BMSSP-vs-Dijkstra head-to-head per graph shape, outputs verified
+npm run bench:counts  # …plus comparison-count tables (the paper's own cost metric)
 ```
 
-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 benchmark harness runs the measured BMSSP-vs-Dijkstra head-to-head on every
+`npm run bench` ([#170](https://github.com/Sirivasv/bmssp-js/issues/170)); methodology,
+the deep 1.0.0 record (up to n = 4M) and the "when to use which" guidance live in
+[benchmarks/HEAD-TO-HEAD.md](benchmarks/HEAD-TO-HEAD.md) and
+[benchmarks/README.md](benchmarks/README.md).
 
 The test suite's core contract: for every node, BMSSP's distances must equal the Dijkstra
 oracle's. A seeded property/fuzz suite (`test/fuzz.test.mjs`) hammers that contract across

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmssp",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Javascript package implementation of the bmssp algorithm.",
   "main": "index.mjs",
   "keywords": [
@@ -35,6 +35,7 @@
   "scripts": {
     "test": "NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules\" jest --coverage",
     "bench": "node benchmarks/run.mjs",
+    "bench:counts": "node benchmarks/run.mjs --counts",
     "lint": "npm run prettier && npm run eslint",
     "format": "npm run prettier:fix && npm run eslint:fix",
     "eslint": "eslint --max-warnings=0 .",

package/src/blockList.mjs

@@ -156,9 +156,13 @@ class BlockList {
         chunks.push(fresh.slice(i, i + chunkSize));
       }
     }
-    // Prepend in reverse chunk order so the smallest chunk lands at the front
-    for (let c = chunks.length - 1; c >= 0; c -= 1) {
-      const chunk = chunks[c];
+    // Materialize the chunks as blocks (ascending, so chunk 0 — the smallest
+    // values — ends up frontmost) and prepend them all in one concat. A
+    // per-chunk unshift here re-shifts the whole d0 array every time: with a
+    // small M the chunk count approaches |L| and the loop turns quadratic —
+    // the #182 star-graph blowup (~n single-entry chunks at M = 1).
+    const blocks = [];
+    for (const chunk of chunks) {
       // Seed the block bound with the first value, then max-update — avoids
       // needing a -Infinity sentinel that a custom comparator can't order
       const block = this.makeBlock(chunk[0][1]);
@@ -168,8 +172,9 @@ class BlockList {
         if (this.compare(value, block.bound) > 0) block.bound = value;
         this.count += 1;
       }
-      this.d0.unshift(block);
+      blocks.push(block);
     }
+    this.d0 = blocks.concat(this.d0);
   }
 
   /**

package/src/tieBreak.mjs

@@ -42,6 +42,28 @@
 // source's own label never loses an equal-(length, hops) comparison.
 const NO_PRED = -Infinity;
 
+// Running count of compareKeys calls — the paper's cost metric ("comparisons
+// between path lengths"). Every BMSSP-side comparison funnels through
+// compareKeys (the heap and BlockList receive it as their comparator, and
+// baseCase/findPivots/bmssp call it directly), so this one counter covers the
+// whole algorithm. The benchmark harness (#170) reads it to measure the
+// sorting barrier; one unconditional increment keeps the hot path branch-free.
+let comparisonCount = 0;
+
+/** Reset the compareKeys call counter to zero (benchmark instrumentation). */
+function resetComparisonCount() {
+  comparisonCount = 0;
+}
+
+/**
+ * Number of compareKeys calls since the last reset (benchmark
+ * instrumentation).
+ * @returns {number}
+ */
+function getComparisonCount() {
+  return comparisonCount;
+}
+
 /**
  * Lexicographic comparison of two composite keys.
  * @param {[number, number, *]} a - [length, hops, id]
@@ -49,6 +71,7 @@ const NO_PRED = -Infinity;
  * @returns {number} Negative when a < b, positive when a > b, 0 when equal
  */
 function compareKeys(a, b) {
+  comparisonCount += 1;
   if (a[0] !== b[0]) return a[0] < b[0] ? -1 : 1;
   if (a[1] !== b[1]) return a[1] < b[1] ? -1 : 1;
   if (a[2] !== b[2]) return a[2] < b[2] ? -1 : 1;
@@ -139,4 +162,13 @@ function relaxEdge(u, v, weight, dHat, ties, bound) {
   return { key: [length, hopCount, v], improved: true };
 }
 
-export { compareKeys, toBound, makeTies, orderKey, relaxEdge, NO_PRED };
+export {
+  compareKeys,
+  toBound,
+  makeTies,
+  orderKey,
+  relaxEdge,
+  NO_PRED,
+  resetComparisonCount,
+  getComparisonCount,
+};