bmssp 0.16.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmssp",
-  "version": "0.16.0",
+  "version": "0.18.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/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 };