bmssp 1.2.0 → 2.0.0

package/src/findPivots.mjs

@@ -1,7 +1,6 @@
 import {
   compareKeyParts,
   toBound,
-  makeTies,
   relaxEdge,
   RELAX_LOST,
 } from "./tieBreak.mjs";
@@ -15,17 +14,19 @@ import {
  * 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 vertex in S is complete (labels.dist 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. Relaxation is canonical (#163, src/tieBreak.mjs):
- * d̂, hops and preds move together under the composite [length, hops, id]
- * order, and an exact-equality result re-admits a vertex to W through its
- * one canonical label-setter (the paper's `≤` made deterministic). The `< B`
- * test only gates membership in W; d̂ updates are not gated.
+ * Since #205 the engine works on dense vertex indices: S holds indices, the
+ * graph is the class's CSR bundle, and the labels are the shared typed
+ * arrays (see tieBreak's makeLabels) — updated in place, exactly like the
+ * paper's global d̂[·], so improvements made here are visible to the levels
+ * above. Relaxation is canonical (#163): dist, hops and preds move together
+ * under the composite [length, hops, index] order, and an exact-equality
+ * result re-admits a vertex to W through its one canonical label-setter (the
+ * paper's `≤` made deterministic). The `< B` test only gates membership in
+ * W; label updates are not gated.
  *
  * The paper's tight-edge forest falls out of the canonical labels: each
  * vertex of W \ S hangs off its recorded canonical predecessor, which is
@@ -44,19 +45,20 @@ import {
  *
  * @param {number|[number, number, *]} B - Strict upper bound gating membership
  *   in W: a number (Infinity is allowed) or a composite bound
- * @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 {Set<number>|Iterable<number>} S - Non-empty set of complete frontier
+ *   source indices
+ * @param {{ dist: Float64Array, hops: Uint32Array, preds: Int32Array }} labels
+ *   - Engine label state (d̂[·] and tie-break labels), updated in place
+ * @param {{ offsets: Uint32Array, targets: Uint32Array, weights: Float64Array }} csr
+ *   - The graph in CSR layout over dense indices
  * @param {number} k - Relaxation rounds / tree-size threshold, >= 1 (floored);
  *   the paper's ⌊log^(1/3) n⌋
- * @param {{ hops: Map<*, number>, preds: Map<*, *> }} [ties] - Canonical
- *   tie-break labels updated alongside dHat; fresh throwaway maps by default
- * @returns {{ pivots: Set<*>, W: Set<*> }} The pivot subset of S and the set W
- *   of vertices touched below B (W always contains S)
+ * @returns {{ pivots: Set<number>, W: Set<number> }} The pivot subset of S and
+ *   the set W of vertex indices 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, ties = makeTies()) {
+function findPivots(B, S, labels, csr, k) {
   if (typeof k !== "number" || Number.isNaN(k) || k < 1) {
     throw new Error("k must be a number >= 1");
   }
@@ -66,12 +68,12 @@ function findPivots(B, S, dHat, adjacency, k, ties = makeTies()) {
     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)) {
+    if (!Number.isFinite(labels.dist[x])) {
       throw new Error("every source must have a finite distance estimate");
     }
   }
   const boundKey = toBound(B);
+  const { offsets, targets, weights } = csr;
 
   // W accumulates everything relaxed below B; layer is the paper's W_{i-1}
   const sourceSet = new Set(sources);
@@ -81,20 +83,17 @@ function findPivots(B, S, dHat, adjacency, k, ties = makeTies()) {
   for (let i = 1; i <= rounds; i += 1) {
     const nextLayer = new Set();
     for (const u of layer) {
-      const edges = adjacency.get(u);
-      if (edges === undefined) continue;
-      for (let j = 0; j < edges.length; j += 1) {
-        const edge = edges[j];
-        const v = edge[0];
-        // Canonical relaxation: d̂ updates are not gated by B (paper), and
-        // both improvements and exact canonical equality admit v to the
+      for (let e = offsets[u]; e < offsets[u + 1]; e += 1) {
+        const v = targets[e];
+        // Canonical relaxation: label updates are not gated by B (paper),
+        // and both improvements and exact canonical equality admit v to the
         // next layer when its key is below B. Non-lost ⇒ v's stored label
         // is the candidate, so the W gate compares the unpacked stored
         // components — no key allocation (#168).
-        const result = relaxEdge(u, v, edge[1], dHat, ties);
+        const result = relaxEdge(u, v, weights[e], labels);
         if (
           result !== RELAX_LOST &&
-          compareKeyParts(dHat.get(v), ties.hops.get(v) ?? 0, v, boundKey) < 0
+          compareKeyParts(labels.dist[v], labels.hops[v], v, boundKey) < 0
         ) {
           nextLayer.add(v);
         }
@@ -114,7 +113,7 @@ function findPivots(B, S, dHat, adjacency, k, ties = makeTies()) {
   const children = new Map();
   for (const v of W) {
     if (sourceSet.has(v)) continue;
-    const parent = ties.preds.get(v);
+    const parent = labels.preds[v];
     if (!children.has(parent)) children.set(parent, []);
     children.get(parent).push(v);
   }

package/src/graph.mjs

@@ -0,0 +1,174 @@
+// #172 — typed / flexible graph inputs.
+//
+// A small builder (`Graph`) plus a normalizer (`normalizeGraphInput`) that
+// lets the BMSSP constructor accept several input shapes and reduce them to
+// one canonical internal form: `{ edges: [[from, to, weight], ...],
+// vertices: [id, ...] }`.
+//
+// `vertices` carries the EXPLICIT vertex universe — every node the caller
+// declared, including isolated ones with no incident edges. Edge endpoints
+// are still folded in by the BMSSP constructor, so an empty `vertices`
+// (the plain edge-list form) reproduces the pre-#172 "infer nodes from
+// edges" behavior exactly.
+//
+// Node-ID semantics are unchanged from earlier versions: IDs are finite
+// numbers. Value validation (finite IDs, finite non-negative weights) with
+// the "Edge at index N" messages stays in the BMSSP constructor so there is
+// a single source of truth; the pieces here validate only what they must to
+// build a well-formed normalized shape (and the builder validates eagerly at
+// the call site for a friendlier failure).
+
+/**
+ * A tiny mutable graph builder. Declare vertices (including isolated ones)
+ * and directed weighted edges, then hand the instance straight to
+ * `new BMSSP(graph)`.
+ *
+ * All mutators return `this`, so calls chain:
+ * `new Graph().addEdge(0, 1, 50).addEdge(1, 2, 75).addVertex(9)`.
+ *
+ * Node IDs must be finite numbers and weights finite and non-negative — the
+ * same contract the edge-array form has always enforced.
+ */
+class Graph {
+  constructor() {
+    // Declared vertex universe (numbers). addEdge folds in its endpoints too.
+    this._vertices = new Set();
+    // Declared directed edges as [from, to, weight] triples.
+    this._edges = [];
+  }
+
+  /**
+   * Declare a vertex. Safe to call for a node that already exists (idempotent)
+   * and the only way to introduce an isolated vertex (one with no edges).
+   * @param {number} id finite node ID
+   * @returns {Graph} this
+   */
+  addVertex(id) {
+    if (!Number.isFinite(id)) {
+      throw new Error("Graph.addVertex: node id must be a finite number");
+    }
+    this._vertices.add(id);
+    return this;
+  }
+
+  /**
+   * Add a directed edge `from -> to` of the given weight. Both endpoints are
+   * declared automatically.
+   * @param {number} from finite source node ID
+   * @param {number} to finite target node ID
+   * @param {number} weight finite, non-negative edge weight
+   * @returns {Graph} this
+   */
+  addEdge(from, to, weight) {
+    if (!Number.isFinite(from) || !Number.isFinite(to)) {
+      throw new Error("Graph.addEdge: node ids must be finite numbers");
+    }
+    if (!Number.isFinite(weight) || weight < 0) {
+      throw new Error(
+        "Graph.addEdge: weight must be a finite, non-negative number",
+      );
+    }
+    this._vertices.add(from);
+    this._vertices.add(to);
+    this._edges.push([from, to, weight]);
+    return this;
+  }
+
+  /** @param {number} id @returns {boolean} whether the vertex is declared */
+  hasVertex(id) {
+    return this._vertices.has(id);
+  }
+
+  /** @returns {number} number of declared vertices */
+  get vertexCount() {
+    return this._vertices.size;
+  }
+
+  /** @returns {number} number of declared edges */
+  get edgeCount() {
+    return this._edges.length;
+  }
+
+  /**
+   * The canonical normalized form the BMSSP constructor consumes. Returns
+   * fresh copies so later mutation of this builder cannot affect a graph
+   * already constructed from it.
+   * @returns {{ edges: number[][], vertices: number[] }}
+   */
+  toNormalized() {
+    return {
+      edges: this._edges.map((edge) => [...edge]),
+      vertices: [...this._vertices],
+    };
+  }
+}
+
+function isIterable(value) {
+  return value != null && typeof value[Symbol.iterator] === "function";
+}
+
+/**
+ * Reduce an adjacency form to `{ edges, vertices }`. Each entry maps a source
+ * node to an iterable of `[to, weight]` pairs; the source is always declared
+ * (so a node with an empty/absent neighbor list becomes an isolated vertex).
+ * When `coerceKeys` is set (plain-object form, whose keys are strings), the
+ * source key is converted to a number — finiteness is then checked by the
+ * BMSSP constructor's vertex validation.
+ */
+function adjacencyToNormalized(entries, coerceKeys) {
+  const edges = [];
+  const vertices = [];
+  for (const [rawFrom, neighbors] of entries) {
+    const from = coerceKeys ? Number(rawFrom) : rawFrom;
+    vertices.push(from);
+    if (neighbors == null) continue;
+    if (!isIterable(neighbors)) {
+      throw new Error(
+        `Adjacency list for node ${rawFrom} must be an iterable of [to, weight]`,
+      );
+    }
+    for (const pair of neighbors) {
+      if (!Array.isArray(pair) || pair.length !== 2) {
+        throw new Error(
+          `Adjacency entry for node ${rawFrom} must be [to, weight]`,
+        );
+      }
+      edges.push([from, pair[0], pair[1]]);
+    }
+  }
+  return { edges, vertices };
+}
+
+/**
+ * Normalize any accepted graph input into `{ edges, vertices }`:
+ * - a `Graph` builder instance,
+ * - an edge array `[[from, to, weight], ...]` (vertices inferred from edges),
+ * - an adjacency `Map<from, Iterable<[to, weight]>>`, or
+ * - a plain adjacency object `{ from: [[to, weight], ...] }` (numeric-string
+ *   keys, coerced to numbers).
+ *
+ * Only structural checks live here; per-edge value validation stays in the
+ * BMSSP constructor so its "Edge at index N" messages remain the single
+ * source of truth.
+ * @param {*} input
+ * @returns {{ edges: number[][], vertices: number[] }}
+ */
+function normalizeGraphInput(input) {
+  if (input instanceof Graph) {
+    return input.toNormalized();
+  }
+  if (Array.isArray(input)) {
+    return { edges: input, vertices: [] };
+  }
+  if (input instanceof Map) {
+    return adjacencyToNormalized(input.entries(), false);
+  }
+  if (input !== null && typeof input === "object") {
+    return adjacencyToNormalized(Object.entries(input), true);
+  }
+  throw new Error(
+    "Input graph must be an edge array, an adjacency map/object, or a Graph instance",
+  );
+}
+
+export { Graph, normalizeGraphInput };

package/src/tieBreak.mjs

@@ -38,9 +38,11 @@
  * source is a hop-0 root) and "no predecessor" (which never loses a tie).
  */
 
-// Sentinel predecessor for sources: compares below every real id, so a
-// source's own label never loses an equal-(length, hops) comparison.
-const NO_PRED = -Infinity;
+// Sentinel predecessor for sources: compares below every real vertex index,
+// so a source's own label never loses an equal-(length, hops) comparison.
+// Since #205 the engine works on dense vertex indices (>= 0), so -1 is a
+// valid sentinel AND fits the Int32Array holding the predecessors.
+const NO_PRED = -1;
 
 // Running count of compareKeys calls — the paper's cost metric ("comparisons
 // between path lengths"). Every BMSSP-side comparison funnels through
@@ -110,7 +112,9 @@ function toBound(B) {
 }
 
 /**
- * Bundle (or create) the tie-break label maps that accompany d̂.
+ * Bundle (or create) the tie-break label maps that accompany d̂ at the PUBLIC
+ * boundary (the BMSSP class mirrors the engine's arrays into these Maps,
+ * keyed by original node ids).
  * @param {Map<*, number>} [hops] - Canonical path edge counts
  * @param {Map<*, *>} [preds] - Canonical predecessor of each vertex
  * @returns {{ hops: Map<*, number>, preds: Map<*, *> }}
@@ -119,6 +123,31 @@ function makeTies(hops = new Map(), preds = new Map()) {
   return { hops, preds };
 }
 
+/**
+ * Allocate the engine's label state for n vertices (#205): d̂, hops and
+ * canonical predecessors as typed arrays over dense vertex indices.
+ * Unlabeled vertices read as distance Infinity, hop 0, no predecessor —
+ * the same defaults the pre-#205 Maps gave via `?? Infinity` / `?? 0`.
+ * @param {number} n - Vertex count
+ * @returns {{ dist: Float64Array, hops: Uint32Array, preds: Int32Array }}
+ */
+function makeLabels(n) {
+  const dist = new Float64Array(n).fill(Infinity);
+  const hops = new Uint32Array(n);
+  const preds = new Int32Array(n).fill(NO_PRED);
+  return { dist, hops, preds };
+}
+
+/**
+ * The frontier-ordering key of vertex index v under the engine labels.
+ * @param {number} v - Dense vertex index
+ * @param {{ dist: Float64Array, hops: Uint32Array }} labels
+ * @returns {[number, number, number]} [dist[v], hops[v], v]
+ */
+function labelKey(v, labels) {
+  return [labels.dist[v], labels.hops[v], v];
+}
+
 /**
  * The frontier-ordering key of a vertex under its current labels.
  * @param {*} v - Vertex id
@@ -155,11 +184,16 @@ function orderKey(v, dHat, ties) {
  * with orderKey(v, dHat, ties) — only on the rare paths that enqueue v,
  * instead of on every attempt.
  *
- * @param {*} u - Edge tail (its labels are read)
- * @param {*} v - Edge head (its labels may be updated)
+ * Since #205 the labels live in typed arrays over dense vertex indices
+ * (see makeLabels); u and v are indices, and index order equals original-id
+ * order (the BMSSP class assigns indices by sorted id), so the canonical
+ * choices are identical to the pre-#205 Map engine's.
+ *
+ * @param {number} u - Edge tail index (its labels are read)
+ * @param {number} v - Edge head index (its labels may be updated)
  * @param {number} weight - Edge weight, >= 0
- * @param {Map<*, number>} dHat - Distance estimates d̂[·], updated in place
- * @param {{ hops: Map<*, number>, preds: Map<*, *> }} ties - Updated in place
+ * @param {{ dist: Float64Array, hops: Uint32Array, preds: Int32Array }} labels
+ *   - Engine label state, updated in place
  * @param {[number, number, *]} [bound] - Optional gate: skip (no d̂ update)
  *   unless the resulting order key would be strictly below this bound
  * @returns {number} RELAX_IMPROVED when the labels were updated,
@@ -167,34 +201,34 @@ function orderKey(v, dHat, ties) {
  *   (the re-enqueue signal), RELAX_LOST when the candidate loses or the
  *   bound gates it (labels untouched)
  */
-function relaxEdge(u, v, weight, dHat, ties, bound) {
-  const length = dHat.get(u) + weight;
-  const hopCount = (ties.hops.get(u) ?? 0) + 1;
+function relaxEdge(u, v, weight, labels, bound) {
+  const length = labels.dist[u] + weight;
+  const hopCount = labels.hops[u] + 1;
   if (bound !== undefined && compareKeyParts(length, hopCount, v, bound) >= 0) {
     return RELAX_LOST;
   }
   // Candidate path key [length, hopCount, u] vs. v's current path key
-  // [d̂[v], hops[v], preds[v] ?? NO_PRED] — compareKeys inlined on the
-  // unpacked components (one counted comparison, no arrays)
+  // [dist[v], hops[v], preds[v]] — compareKeys inlined on the unpacked
+  // components (one counted comparison, no arrays)
   comparisonCount += 1;
   let cmp;
-  const currentLength = dHat.get(v) ?? Infinity;
+  const currentLength = labels.dist[v];
   if (length !== currentLength) {
     cmp = length < currentLength ? -1 : 1;
   } else {
-    const currentHops = ties.hops.get(v) ?? 0;
+    const currentHops = labels.hops[v];
     if (hopCount !== currentHops) {
       cmp = hopCount < currentHops ? -1 : 1;
     } else {
-      const currentPred = ties.preds.has(v) ? ties.preds.get(v) : NO_PRED;
+      const currentPred = labels.preds[v];
       cmp = u !== currentPred ? (u < currentPred ? -1 : 1) : 0;
     }
   }
   if (cmp > 0) return RELAX_LOST;
   if (cmp === 0) return RELAX_EQUAL;
-  dHat.set(v, length);
-  ties.hops.set(v, hopCount);
-  ties.preds.set(v, u);
+  labels.dist[v] = length;
+  labels.hops[v] = hopCount;
+  labels.preds[v] = u;
   return RELAX_IMPROVED;
 }
 
@@ -209,7 +243,9 @@ export {
   compareKeyParts,
   toBound,
   makeTies,
+  makeLabels,
   orderKey,
+  labelKey,
   relaxEdge,
   NO_PRED,
   RELAX_LOST,