bmssp 0.15.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmssp",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Javascript package implementation of the bmssp algorithm.",
   "main": "index.mjs",
   "keywords": [
@@ -34,6 +34,7 @@
   ],
   "scripts": {
     "test": "NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules\" jest --coverage",
+    "bench": "node benchmarks/run.mjs",
     "lint": "npm run prettier && npm run eslint",
     "format": "npm run prettier:fix && npm run eslint:fix",
     "eslint": "eslint --max-warnings=0 .",
@@ -49,6 +50,6 @@
     "eslint-plugin-prettier": "^5.5.4",
     "globals": "^17.0.0",
     "jest": "^30.1.1",
-    "prettier": "3.8.3"
+    "prettier": "3.9.5"
   }
 }

package/src/blockList.mjs

@@ -0,0 +1,248 @@
+/**
+ * Block-based "partial-sort" structure D from Lemma 3.3 of the BMSSP paper
+ * ("Breaking the Sorting Barrier for Directed Single-Source Shortest Paths").
+ *
+ * Holds <key, value> pairs (vertex, distance estimate) semi-sorted: values
+ * are ordered BETWEEN blocks but unsorted WITHIN a block. That is enough to
+ * repeatedly pull the M smallest values as a batch (pull) and to cheaply
+ * add a batch of values known to be smaller than everything present
+ * (batchPrepend) — without paying for a full sort.
+ *
+ * Internal layout:
+ * - d1: blocks filled by insert(). Each block carries an upper bound on its
+ *   values; bounds are non-decreasing across blocks, and the last block
+ *   always has bound B so every value < B has a home.
+ * - d0: blocks filled by batchPrepend() only; they conceptually sit in front
+ *   of d1 (their values are smaller than everything inserted so far).
+ *
+ * The block-bound index is a plain array searched with binary search instead
+ * of the paper's balanced BST — same behavior, worse constants (issue #167).
+ */
+class BlockList {
+  /**
+   * Initialize the structure (Lemma 3.3 Initialize).
+   * @param {number} M - Block size / pull batch size, >= 1. At recursion level l this is 2^((l-1)·t).
+   * @param {number} B - Strict upper bound on every value ever stored (Infinity is allowed)
+   * @throws {Error} If M is not a number >= 1
+   */
+  constructor(M, B) {
+    if (typeof M !== "number" || Number.isNaN(M) || M < 1) {
+      throw new Error("M must be a number >= 1");
+    }
+    this.M = Math.floor(M);
+    this.B = B;
+    // d1 starts as a single empty block with upper bound B
+    this.d1 = [this.makeBlock(B)];
+    this.d0 = [];
+    // key -> block currently holding that key, for O(1) duplicate handling
+    this.locator = new Map();
+    this.count = 0;
+  }
+
+  // Internal: create an empty block with the given value upper bound
+  makeBlock(bound) {
+    return { bound, entries: new Map() };
+  }
+
+  // Number of pairs currently stored
+  get size() {
+    return this.count;
+  }
+
+  isEmpty() {
+    return this.count === 0;
+  }
+
+  /**
+   * Insert a pair (Lemma 3.3 Insert). If the key is already stored, the
+   * smallest value wins (the pair is replaced only when value is smaller).
+   * @param {*} key - Typically a node ID
+   * @param {number} value - Must be < B
+   * @throws {Error} If value >= B
+   */
+  insert(key, value) {
+    if (!(value < this.B)) {
+      throw new Error("value must be < B");
+    }
+    const holder = this.locator.get(key);
+    if (holder !== undefined) {
+      if (holder.entries.get(key) <= value) return;
+      this.removeKey(key, holder);
+    }
+    // Binary-search d1 for the first block whose bound covers the value
+    let lo = 0;
+    let hi = this.d1.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if (this.d1[mid].bound >= value) {
+        hi = mid;
+      } else {
+        lo = mid + 1;
+      }
+    }
+    const block = this.d1[lo];
+    block.entries.set(key, value);
+    this.locator.set(key, block);
+    this.count += 1;
+    if (block.entries.size > this.M) {
+      this.splitBlock(lo);
+    }
+  }
+
+  // Internal: split an overfull d1 block into two halves around its median
+  // value. The lower half gets bound = its own max value; the upper half
+  // keeps the original bound, so inter-block ordering is preserved.
+  // (The paper uses linear-time median selection; sorting is O(M log M) but
+  // simpler — acceptable for this correctness-first implementation.)
+  splitBlock(index) {
+    const block = this.d1[index];
+    const sorted = [...block.entries].sort((a, b) => a[1] - b[1]);
+    const half = sorted.length >> 1;
+    const lower = this.makeBlock(sorted[half - 1][1]);
+    for (let i = 0; i < half; i += 1) {
+      const [key, value] = sorted[i];
+      block.entries.delete(key);
+      lower.entries.set(key, value);
+      this.locator.set(key, lower);
+    }
+    this.d1.splice(index, 0, lower);
+  }
+
+  /**
+   * Insert a batch of pairs whose values are all smaller than every value
+   * currently stored (Lemma 3.3 BatchPrepend). On duplicate keys — within
+   * the batch or against the current contents — the smallest value wins.
+   * The caller is responsible for the "smaller than everything" contract;
+   * only the value < B bound is checked here.
+   * @param {Iterable<[*, number]>} pairs - [key, value] pairs, each value < B
+   * @throws {Error} If any value >= B
+   */
+  batchPrepend(pairs) {
+    // Dedupe the batch, keeping the smallest value per key
+    const best = new Map();
+    for (const [key, value] of pairs) {
+      if (!(value < this.B)) {
+        throw new Error("value must be < B");
+      }
+      const seen = best.get(key);
+      if (seen === undefined || value < seen) {
+        best.set(key, value);
+      }
+    }
+    // Resolve clashes with keys already stored (smallest value wins)
+    const fresh = [];
+    for (const [key, value] of best) {
+      const holder = this.locator.get(key);
+      if (holder !== undefined) {
+        if (holder.entries.get(key) <= value) continue;
+        this.removeKey(key, holder);
+      }
+      fresh.push([key, value]);
+    }
+    if (fresh.length === 0) return;
+    // One block if the batch fits, otherwise sorted chunks of <= ceil(M/2)
+    let chunks;
+    if (fresh.length <= this.M) {
+      chunks = [fresh];
+    } else {
+      fresh.sort((a, b) => a[1] - b[1]);
+      const chunkSize = Math.ceil(this.M / 2);
+      chunks = [];
+      for (let i = 0; i < fresh.length; i += chunkSize) {
+        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];
+      const block = this.makeBlock(-Infinity);
+      for (const [key, value] of chunk) {
+        block.entries.set(key, value);
+        this.locator.set(key, block);
+        if (value > block.bound) block.bound = value;
+        this.count += 1;
+      }
+      this.d0.unshift(block);
+    }
+  }
+
+  /**
+   * Remove and return the (at most) M smallest-valued keys plus a separating
+   * bound (Lemma 3.3 Pull). In Algorithm 3 this is `Bi, Si <- D.Pull()`:
+   * `keys` is Si and `bound` is Bi, satisfying
+   * max(pulled values) <= bound <= min(remaining values).
+   * When the pull drains the structure the bound is B.
+   * @returns {{ keys: Set<*>, bound: number }}
+   */
+  pull() {
+    if (this.count <= this.M) {
+      // Everything fits in one batch: drain the structure and reset it
+      const keys = new Set(this.locator.keys());
+      this.d0 = [];
+      this.d1 = [this.makeBlock(this.B)];
+      this.locator.clear();
+      this.count = 0;
+      return { keys, bound: this.B };
+    }
+    // Collect prefix blocks from each sequence until that side holds >= M
+    // candidate elements (or runs out). The M smallest overall are in there.
+    const candidates = [];
+    for (const seq of [this.d0, this.d1]) {
+      let collected = 0;
+      for (const block of seq) {
+        if (collected >= this.M) break;
+        for (const [key, value] of block.entries) {
+          candidates.push([key, value, block]);
+        }
+        collected += block.entries.size;
+      }
+    }
+    // Take the M smallest candidates out of the structure
+    candidates.sort((a, b) => a[1] - b[1]);
+    const keys = new Set();
+    for (let i = 0; i < this.M; i += 1) {
+      const [key, , block] = candidates[i];
+      keys.add(key);
+      this.removeKey(key, block);
+    }
+    // Separator = smallest value still stored. Thanks to the inter-block
+    // ordering it lives in the first non-empty block of d0 or d1.
+    let bound = Infinity;
+    for (const seq of [this.d0, this.d1]) {
+      const block = seq.find((b) => b.entries.size > 0);
+      if (block) {
+        for (const value of block.entries.values()) {
+          if (value < bound) bound = value;
+        }
+      }
+    }
+    return { keys, bound };
+  }
+
+  // Internal: remove a key from the block that holds it, dropping the block
+  // if it becomes empty (deletion cost amortizes into insertion, Lemma 3.3)
+  removeKey(key, block) {
+    block.entries.delete(key);
+    this.locator.delete(key);
+    this.count -= 1;
+    if (block.entries.size === 0) {
+      this.dropIfEmpty(block);
+    }
+  }
+
+  // Internal: physically remove an emptied block. The last d1 block (bound B)
+  // is kept even when empty so insert always finds a home for any value < B.
+  dropIfEmpty(block) {
+    const i0 = this.d0.indexOf(block);
+    if (i0 !== -1) {
+      this.d0.splice(i0, 1);
+      return;
+    }
+    const i1 = this.d1.indexOf(block);
+    if (i1 !== -1 && i1 < this.d1.length - 1) {
+      this.d1.splice(i1, 1);
+    }
+  }
+}
+
+export { BlockList };

package/src/bmssp.mjs

@@ -8,6 +8,10 @@ class BMSSP {
     this.nodeIDs = new Set();
     // Map to store shortest paths
     this.shortestPaths = new Map();
+    // Adjacency map: nodeId -> array of [to, weight] outgoing edges.
+    // Lets the algorithm fetch a node's edges in O(1) instead of scanning
+    // the whole edge list on every lookup.
+    this.adjacency = new Map();
 
     for (let edge of inputGraph) {
       // Create a deep copy of each edge array
@@ -18,10 +22,36 @@ class BMSSP {
       this.nodeIDs.add(edge[1]);
     }
 
+    // Build the adjacency map from the copied edges
+    this.buildAdjacency();
+
     // Initialize shortest paths map
     this.initializeShortestPaths();
   }
 
+  // Method to (re)build the adjacency map from this.graph.
+  // Every node ID gets an entry (an empty array for nodes with no
+  // outgoing edges) so callers can rely on .get(node) returning an array.
+  buildAdjacency() {
+    this.adjacency = new Map();
+
+    // Ensure every known node has an (initially empty) neighbor list
+    for (let nodeId of this.nodeIDs) {
+      this.adjacency.set(nodeId, []);
+    }
+
+    // Group outgoing edges by their source node
+    for (let [from, to, weight] of this.graph) {
+      this.adjacency.get(from).push([to, weight]);
+    }
+  }
+
+  // Return the outgoing edges of a node as an array of [to, weight].
+  // Unknown nodes return an empty array.
+  getEdges(nodeId) {
+    return this.adjacency.get(nodeId) ?? [];
+  }
+
   // Method to initialize the shortest paths map
   initializeShortestPaths() {
     for (let nodeId of this.nodeIDs) {