@graphty/algorithms 2.0.3 → 2.0.5

package/dist/algorithms.standalone.js

@@ -84,7 +84,8 @@ class Graph {
     if (!this.config.allowSelfLoops && source === target) {
       throw new Error("Self-loops are not allowed in this graph");
     }
-    if (!this.config.allowParallelEdges && this.hasEdge(source, target)) {
+    const replacing = this.hasEdge(source, target);
+    if (!this.config.allowParallelEdges && replacing) {
       throw new Error("Parallel edges are not allowed in this graph");
     }
     const edge = { source, target, weight, data };
@@ -106,7 +107,9 @@ class Graph {
         }
       }
     }
-    this.edgeCount++;
+    if (!replacing) {
+      this.edgeCount++;
+    }
     this.mutations++;
   }
   /**
@@ -351,6 +354,23 @@ class ConvergenceError extends Error {
     this.name = "ConvergenceError";
   }
 }
+class PathWalkError extends Error {
+  /**
+   * Builds the error and its message.
+   * @param source - The search's source node index
+   * @param target - The node index the walk started from
+   * @param reason - `"gap"` or `"cycle"`, as above
+   */
+  constructor(source, target, reason) {
+    super(
+      `cannot walk the shortest path from node ${String(source)} to node ${String(target)}: the predecessor array has a ${reason}`
+    );
+    this.source = source;
+    this.target = target;
+    this.reason = reason;
+    this.name = "PathWalkError";
+  }
+}
 var lib = {};
 var SparseTypedFastBitSet = {};
 var utils = {};
@@ -5252,7 +5272,7 @@ class PriorityDeltaPageRank {
   }
 }
 function eigenvectorCentrality(graph, options = {}) {
-  const { maxIterations = 100, tolerance = 1e-6, normalized = true, startVector } = options;
+  const { maxIterations = 100, tolerance = 1e-6, normalized = true, startVector, mode = "in" } = options;
   const nodeIds = Array.from(graph.nodes(), (node) => node.id);
   const keys = nodeIds.map((id) => id.toString());
   const n = keys.length;
@@ -5261,7 +5281,13 @@ function eigenvectorCentrality(graph, options = {}) {
     return centrality;
   }
   const index2 = new Map(keys.map((key, i) => [key, i]));
-  const adjacency = nodeIds.map((id) => Array.from(graph.neighbors(id), (m) => index2.get(m.toString()) ?? 0));
+  const feeders = (id) => {
+    if (!graph.isDirected || mode === "out") {
+      return graph.neighbors(id);
+    }
+    return mode === "in" ? graph.inNeighbors(id) : /* @__PURE__ */ new Set([...graph.inNeighbors(id), ...graph.neighbors(id)]);
+  };
+  const adjacency = nodeIds.map((id) => Array.from(feeders(id), (m) => index2.get(m.toString()) ?? 0));
   if (isNilpotent(adjacency)) {
     for (const key of keys) {
       centrality[key] = 0;
@@ -5549,6 +5575,8 @@ class SimpleDeltaPageRank {
    */
   constructor(graph) {
     this.previousScores = null;
+    this.iterations = 0;
+    this.converged = false;
     if (!graph.isDirected) {
       throw new Error("PageRank requires a directed graph");
     }
@@ -5561,20 +5589,32 @@ class SimpleDeltaPageRank {
    * @param options.dampingFactor - Probability of following a link (default: 0.85)
    * @param options.tolerance - Convergence tolerance threshold (default: 1e-6)
    * @param options.maxIterations - Maximum number of iterations (default: 100)
+   * @param options.initialRanks - Starting scores (missing nodes start at 1/n; normalized to sum 1)
    * @param options.personalization - Personalization vector for Personalized PageRank
    * @param options.weight - Edge attribute name for weighted PageRank
-   * @returns Map of node IDs to their PageRank scores
+   * @returns Map of node IDs to their PageRank scores; `iterations` and `converged` describe the run
    */
   compute(options = {}) {
-    const { dampingFactor = 0.85, tolerance = 1e-6, maxIterations = 100, personalization, weight } = options;
+    const {
+      dampingFactor = 0.85,
+      tolerance = 1e-6,
+      maxIterations = 100,
+      initialRanks,
+      personalization,
+      weight
+    } = options;
+    this.iterations = 0;
+    this.converged = false;
     if (this.nodeCount === 0) {
+      this.converged = true;
       return /* @__PURE__ */ new Map();
     }
     const scores = /* @__PURE__ */ new Map();
     const newScores = /* @__PURE__ */ new Map();
     for (const node of this.graph.nodes()) {
-      scores.set(node.id, 1 / this.nodeCount);
+      scores.set(node.id, initialRanks?.get(node.id) ?? 1 / this.nodeCount);
     }
+    this.normalizeMap(scores);
     const outWeights = /* @__PURE__ */ new Map();
     const danglingNodes = /* @__PURE__ */ new Set();
     for (const node of this.graph.nodes()) {
@@ -5582,8 +5622,7 @@ class SimpleDeltaPageRank {
       let outDegree = 0;
       for (const neighbor of Array.from(this.graph.neighbors(node.id))) {
         outDegree++;
-        const edge = this.graph.getEdge(node.id, neighbor);
-        totalWeight += edge?.weight ?? 1;
+        totalWeight += weight ? this.graph.getEdge(node.id, neighbor)?.weight ?? 1 : 1;
       }
       outWeights.set(node.id, totalWeight);
       if (outDegree === 0) {
@@ -5595,7 +5634,6 @@ class SimpleDeltaPageRank {
       personalVector = new Map(personalization);
       this.normalizeMap(personalVector);
     }
-    let activeNodes = new Set(scores.keys());
     let iteration = 0;
     for (iteration = 0; iteration < maxIterations; iteration++) {
       for (const nodeId of scores.keys()) {
@@ -5621,7 +5659,7 @@ class SimpleDeltaPageRank {
           }
         }
       }
-      for (const nodeId of activeNodes) {
+      for (const nodeId of scores.keys()) {
         const currentRank = scores.get(nodeId) ?? 0;
         const nodeOutWeight = outWeights.get(nodeId) ?? 0;
         if (nodeOutWeight > 0) {
@@ -5637,33 +5675,21 @@ class SimpleDeltaPageRank {
           }
         }
       }
-      const nextActive = /* @__PURE__ */ new Set();
       let maxDiff = 0;
       for (const nodeId of scores.keys()) {
-        const oldRank = scores.get(nodeId) ?? 0;
-        const newRank = newScores.get(nodeId) ?? 0;
-        const diff = Math.abs(newRank - oldRank);
-        maxDiff = Math.max(maxDiff, diff);
-        if (diff > tolerance / 10) {
-          nextActive.add(nodeId);
-          for (const neighbor of Array.from(this.graph.neighbors(nodeId))) {
-            nextActive.add(neighbor);
-          }
-          for (const neighbor of Array.from(this.graph.inNeighbors(nodeId))) {
-            nextActive.add(neighbor);
-          }
-        }
+        maxDiff = Math.max(maxDiff, Math.abs((newScores.get(nodeId) ?? 0) - (scores.get(nodeId) ?? 0)));
       }
       scores.clear();
       for (const [k, v] of newScores) {
         scores.set(k, v);
       }
       newScores.clear();
-      activeNodes = nextActive;
       if (maxDiff < tolerance) {
+        this.converged = true;
         break;
       }
     }
+    this.iterations = this.converged ? iteration + 1 : iteration;
     this.previousScores = new Map(scores);
     return scores;
   }
@@ -5684,6 +5710,8 @@ class SimpleDeltaPageRank {
       return this.compute(options);
     }
     const { dampingFactor = 0.85, tolerance = 1e-6, maxIterations = 100, personalization, weight } = options;
+    this.iterations = 0;
+    this.converged = false;
     const scores = new Map(this.previousScores);
     const newScores = /* @__PURE__ */ new Map();
     for (const node of this.graph.nodes()) {
@@ -5708,8 +5736,7 @@ class SimpleDeltaPageRank {
       let outDegree = 0;
       for (const neighbor of Array.from(this.graph.neighbors(node.id))) {
         outDegree++;
-        const edge = this.graph.getEdge(node.id, neighbor);
-        totalWeight += edge?.weight ?? 1;
+        totalWeight += weight ? this.graph.getEdge(node.id, neighbor)?.weight ?? 1 : 1;
       }
       outWeights.set(node.id, totalWeight);
       if (outDegree === 0) {
@@ -5786,9 +5813,11 @@ class SimpleDeltaPageRank {
       newScores.clear();
       activeNodes = nextActive;
       if (maxDiff < tolerance) {
+        this.converged = true;
         break;
       }
     }
+    this.iterations = this.converged ? iteration + 1 : iteration;
     this.previousScores = new Map(scores);
     return scores;
   }
@@ -5831,6 +5860,9 @@ function pageRank$1(graph, options = {}) {
       tolerance,
       maxIterations
     };
+    if (initialRanks) {
+      deltaOptions.initialRanks = initialRanks;
+    }
     if (personalization) {
       deltaOptions.personalization = personalization;
     }
@@ -5845,9 +5877,8 @@ function pageRank$1(graph, options = {}) {
     }
     return {
       ranks: result2,
-      iterations: maxIterations,
-      // For now, assume we used all iterations
-      converged: true
+      iterations: deltaPageRank.iterations,
+      converged: deltaPageRank.converged
     };
   }
   let ranks = /* @__PURE__ */ new Map();
@@ -5949,7 +5980,8 @@ function pageRank$1(graph, options = {}) {
   }
   return {
     ranks: result,
-    iterations: iteration + 1,
+    // The loop breaks before incrementing on convergence, and leaves at maxIterations otherwise.
+    iterations: converged ? iteration + 1 : iteration,
     converged
   };
 }
@@ -10121,7 +10153,7 @@ function adamicAdarPrediction(graph, options = {}) {
     for (let j = i + 1; j < nodes.length; j++) {
       const source = nodes[i];
       const target = nodes[j];
-      if (!source || !target) {
+      if (source === void 0 || target === void 0) {
         continue;
       }
       if (!includeExisting && graph.hasEdge(source, target)) {
@@ -10299,7 +10331,7 @@ function commonNeighborsPrediction(graph, options = {}) {
     for (let j = i + 1; j < nodes.length; j++) {
       const source = nodes[i];
       const target = nodes[j];
-      if (!source || !target) {
+      if (source === void 0 || target === void 0) {
         continue;
       }
       if (!includeExisting && graph.hasEdge(source, target)) {
@@ -18444,7 +18476,7 @@ function checkUniqueColumn(table, column) {
     throw err;
   }
 }
-const WIRE_PRODUCER = `@graphty/graph-format@${"dba15b94127d"}`;
+const WIRE_PRODUCER = `@graphty/graph-format@${"0f6f0f1500bd"}`;
 const SCALAR_VIEWS = /* @__PURE__ */ new Set(["totalWeight", "symmetric"]);
 const encoder = new TextEncoder();
 function assertLittleEndianHost(littleEndian = IS_LITTLE_ENDIAN) {
@@ -22192,7 +22224,9 @@ class GraphBuilder {
     return this.staging.edgeBound;
   }
   /**
-   * Increments on every topology or weight mutation; column writes and freeze() do not count.
+   * Increments on every change that makes the next freeze() differ (topology, weights, cell and
+   * column writes, declarations, graph values, meta, extension tables, record and graph merges);
+   * freeze() itself does not count.
    * @returns the count
    */
   get mutationCount() {
@@ -22751,6 +22785,7 @@ class GraphBuilder {
       buildGraphColumn(name, value, patch);
     }
     this.graphValues.set(name, { decl: patch, value });
+    this.mutated();
   }
   /**
    * Merge fields into the graph metadata (design section 5.9); undefined fields are left alone,
@@ -22760,6 +22795,7 @@ class GraphBuilder {
   setMeta(meta) {
     this.check();
     this.metaValue = resolveGraphMeta$1(this.metaValue, meta);
+    this.mutated();
   }
   /**
    * Create an extension table (design section 5.10).
@@ -22786,6 +22822,7 @@ class GraphBuilder {
       columns.push(column);
     }
     staging.extensions.push({ name, columns, rowCount: 0 });
+    this.mutated();
     return staging.extensions.length - 1;
   }
   /**
@@ -22814,6 +22851,7 @@ class GraphBuilder {
       target.columns[i].write(row, checked[i]);
     }
     target.rowCount = row + 1;
+    this.mutated();
     return row;
   }
   /**
@@ -22977,6 +23015,7 @@ class GraphBuilder {
     for (const [name, table] of snapshot.extensions) {
       this.appendExtension(name, table, refs);
     }
+    this.mutated();
   }
   // ---------------------------------------------------------------- output and lifecycle
   /**
@@ -23387,6 +23426,7 @@ class GraphBuilder {
       return existing;
     }
     const columns = this.columnsOf(domain);
+    this.mutated();
     return this.pushColumn(columns, new StagingColumn(meta, false));
   }
   /**
@@ -23623,6 +23663,7 @@ class GraphBuilder {
     if (widened !== null) {
       this.widenings.push({ column: target.meta.name, domain, from: widened.from, to: widened.to });
     }
+    this.mutated();
   }
   /**
    * Replace or create a column from a typed array (setNodeColumn / setEdgeColumn).
@@ -23649,6 +23690,7 @@ class GraphBuilder {
     } else {
       this.pushColumn(columns, column);
     }
+    this.mutated();
   }
   extensionOf(handle) {
     const { extensions } = this.staging;
@@ -24202,6 +24244,22 @@ class IndexedMinHeap {
     this.slot[node] = at;
   }
 }
+function walkBack(g, predArc, source, target) {
+  const arcs = [];
+  let node = target;
+  while (node !== source) {
+    if (arcs.length >= g.nodeCount - 1) {
+      throw new PathWalkError(source, target, "cycle");
+    }
+    const arc = predArc[node];
+    if (!(arc < g.arcCount)) {
+      throw new PathWalkError(source, target, "gap");
+    }
+    arcs.push(arc);
+    node = arcSourceIn(g.rowPtr, arc);
+  }
+  return arcs;
+}
 function walkPredArcs(g, predArc, source, target) {
   if (target === source) {
     return Uint32Array.of(source);
@@ -24209,12 +24267,7 @@ function walkPredArcs(g, predArc, source, target) {
   if (predArc[target] === INVALID_INDEX) {
     return new Uint32Array(0);
   }
-  const reversed = [target];
-  let node = target;
-  while (node !== source) {
-    node = arcSourceIn(g.rowPtr, predArc[node]);
-    reversed.push(node);
-  }
+  const reversed = [target, ...walkBack(g, predArc, source, target).map((arc) => arcSourceIn(g.rowPtr, arc))];
   const out = new Uint32Array(reversed.length);
   for (let i = 0; i < reversed.length; i++) {
     out[i] = reversed[reversed.length - 1 - i];
@@ -24225,13 +24278,7 @@ function walkPredEdges(g, predArc, source, target) {
   if (target === source || predArc[target] === INVALID_INDEX) {
     return new Uint32Array(0);
   }
-  const reversed = [];
-  let node = target;
-  while (node !== source) {
-    const arc = predArc[node];
-    reversed.push(g.arcToEdge[arc]);
-    node = arcSourceIn(g.rowPtr, arc);
-  }
+  const reversed = walkBack(g, predArc, source, target).map((arc) => g.arcToEdge[arc]);
   const out = new Uint32Array(reversed.length);
   for (let i = 0; i < reversed.length; i++) {
     out[i] = reversed[reversed.length - 1 - i];
@@ -24409,6 +24456,7 @@ export {
   DirectionOptimizedBFS,
   Graph,
   GraphBitSet,
+  PathWalkError,
   PriorityDeltaPageRank,
   PriorityQueue,
   UnionFind,