@graphty/algorithms 2.0.3 → 2.0.5

package/README.md

@@ -110,8 +110,8 @@ class Graph {
 ```typescript
 interface GraphConfig {
     directed: boolean; // Default: false
-    allowSelfLoops: boolean; // Default: false
-    allowParallelEdges: boolean; // Default: false
+    allowSelfLoops: boolean; // Default: true
+    allowParallelEdges: boolean; // Default: false. When true, re-adding a pair replaces its edge (one edge per pair)
 }
 ```
 

package/dist/algorithms.js

@@ -85,7 +85,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 };
@@ -107,7 +108,9 @@ class Graph {
         }
       }
     }
-    this.edgeCount++;
+    if (!replacing) {
+      this.edgeCount++;
+    }
     this.mutations++;
   }
   /**
@@ -352,6 +355,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 = {};
@@ -5253,7 +5273,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;
@@ -5262,7 +5282,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;
@@ -5550,6 +5576,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");
     }
@@ -5562,20 +5590,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()) {
@@ -5583,8 +5623,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) {
@@ -5596,7 +5635,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()) {
@@ -5622,7 +5660,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) {
@@ -5638,33 +5676,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;
   }
@@ -5685,6 +5711,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()) {
@@ -5709,8 +5737,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) {
@@ -5787,9 +5814,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;
   }
@@ -5832,6 +5861,9 @@ function pageRank$1(graph, options = {}) {
       tolerance,
       maxIterations
     };
+    if (initialRanks) {
+      deltaOptions.initialRanks = initialRanks;
+    }
     if (personalization) {
       deltaOptions.personalization = personalization;
     }
@@ -5846,9 +5878,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();
@@ -5950,7 +5981,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
   };
 }
@@ -10122,7 +10154,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)) {
@@ -10300,7 +10332,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)) {
@@ -11604,6 +11636,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);
@@ -11611,12 +11659,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];
@@ -11627,13 +11670,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];
@@ -11811,6 +11848,7 @@ export {
   DirectionOptimizedBFS,
   Graph,
   GraphBitSet,
+  PathWalkError,
   PriorityDeltaPageRank,
   PriorityQueue,
   UnionFind,