bmssp 0.15.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmssp",
-  "version": "0.15.0",
+  "version": "0.17.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) {

package/src/heap.mjs

@@ -0,0 +1,167 @@
+/**
+ * Array-backed indexed binary min-heap for the BMSSP base case (Algorithm 2
+ * of "Breaking the Sorting Barrier for Directed Single-Source Shortest
+ * Paths"). Holds <key, value> pairs (vertex, distance estimate) ordered by
+ * value and supports exactly the operations BaseCase(B, S) needs:
+ *
+ *   insert(key, value)      — add a key not currently stored
+ *   extractMin()            — remove and return the smallest-valued pair
+ *   decreaseKey(key, value) — lower the value of a stored key
+ *   has(key)                — membership test ("is v in H?")
+ *
+ * A position map (key -> array index) makes decreaseKey and has O(log n) /
+ * O(1), matching the paper's heap literally instead of the lazy
+ * duplicate-and-skip variant used inside src/dijkstra.mjs.
+ */
+class MinHeap {
+  constructor() {
+    // entries[i] = [key, value], heap-ordered by value
+    this.entries = [];
+    // key -> index of that key in entries, for O(1) membership / lookup
+    this.position = new Map();
+  }
+
+  // Number of pairs currently stored
+  get size() {
+    return this.entries.length;
+  }
+
+  isEmpty() {
+    return this.entries.length === 0;
+  }
+
+  has(key) {
+    return this.position.has(key);
+  }
+
+  /**
+   * Current value of a stored key, or undefined if the key is not present.
+   * @param {*} key - Typically a node ID
+   * @returns {number|undefined}
+   */
+  getValue(key) {
+    const index = this.position.get(key);
+    return index === undefined ? undefined : this.entries[index][1];
+  }
+
+  /**
+   * Smallest-valued pair without removing it.
+   * @returns {{ key: *, value: number }}
+   * @throws {Error} If the heap is empty
+   */
+  peekMin() {
+    if (this.entries.length === 0) {
+      throw new Error("heap is empty");
+    }
+    const [key, value] = this.entries[0];
+    return { key, value };
+  }
+
+  /**
+   * Add a pair for a key that is not currently stored (Algorithm 2 Insert).
+   * A key that was extracted earlier may be inserted again.
+   * @param {*} key - Typically a node ID
+   * @param {number} value - Priority; smaller comes out first
+   * @throws {Error} If the key is already stored, or value is not a number
+   */
+  insert(key, value) {
+    if (typeof value !== "number" || Number.isNaN(value)) {
+      throw new Error("value must be a number");
+    }
+    if (this.position.has(key)) {
+      throw new Error("key already in heap — use decreaseKey");
+    }
+    this.entries.push([key, value]);
+    this.position.set(key, this.entries.length - 1);
+    this.siftUp(this.entries.length - 1);
+  }
+
+  /**
+   * Lower the value of a stored key (Algorithm 2 DecreaseKey). A value that
+   * would not decrease the stored one is ignored — the smallest value wins,
+   * mirroring the `<=` edge relaxation which re-relaxes with equal sums.
+   * @param {*} key - Must be currently stored
+   * @param {number} value - New priority; applied only when smaller
+   * @throws {Error} If the key is not stored, or value is not a number
+   */
+  decreaseKey(key, value) {
+    if (typeof value !== "number" || Number.isNaN(value)) {
+      throw new Error("value must be a number");
+    }
+    const index = this.position.get(key);
+    if (index === undefined) {
+      throw new Error("key not in heap — use insert");
+    }
+    if (this.entries[index][1] <= value) return;
+    this.entries[index][1] = value;
+    this.siftUp(index);
+  }
+
+  /**
+   * Remove and return the smallest-valued pair (Algorithm 2 ExtractMin).
+   * @returns {{ key: *, value: number }}
+   * @throws {Error} If the heap is empty
+   */
+  extractMin() {
+    if (this.entries.length === 0) {
+      throw new Error("heap is empty");
+    }
+    const [key, value] = this.entries[0];
+    this.position.delete(key);
+    const last = this.entries.pop();
+    if (this.entries.length > 0) {
+      this.entries[0] = last;
+      this.position.set(last[0], 0);
+      this.siftDown(0);
+    }
+    return { key, value };
+  }
+
+  // Internal: swap two entries and keep the position map in sync
+  swap(i, j) {
+    const a = this.entries[i];
+    const b = this.entries[j];
+    this.entries[i] = b;
+    this.entries[j] = a;
+    this.position.set(b[0], i);
+    this.position.set(a[0], j);
+  }
+
+  // Internal: move the entry at index up until its parent is not larger
+  siftUp(index) {
+    let i = index;
+    while (i > 0) {
+      const parent = (i - 1) >> 1;
+      if (this.entries[parent][1] <= this.entries[i][1]) break;
+      this.swap(parent, i);
+      i = parent;
+    }
+  }
+
+  // Internal: move the entry at index down until no child is smaller
+  siftDown(index) {
+    let i = index;
+    for (;;) {
+      const left = 2 * i + 1;
+      const right = left + 1;
+      let smallest = i;
+      if (
+        left < this.entries.length &&
+        this.entries[left][1] < this.entries[smallest][1]
+      ) {
+        smallest = left;
+      }
+      if (
+        right < this.entries.length &&
+        this.entries[right][1] < this.entries[smallest][1]
+      ) {
+        smallest = right;
+      }
+      if (smallest === i) break;
+      this.swap(smallest, i);
+      i = smallest;
+    }
+  }
+}
+
+export { MinHeap };