@graphty/algorithms 1.8.0 → 2.0.0

package/dist/src/algorithms/community/modularity-utils.d.ts

@@ -37,15 +37,23 @@ export declare function getNeighborCommunities(graph: Graph, nodeId: NodeId, com
  * Calculate modularity of a partition
  *
  * Modularity measures the quality of a community partition. It compares the
- * number of edges within communities to what would be expected in a random graph.
+ * weight of the edges inside communities to what would be expected in a random graph
+ * with the same degrees.
  *
- * Formula: Q = (1/2m) * Σ[A_ij - γ(k_i * k_j)/(2m)] * δ(c_i, c_j)
+ * Formula: Q = sum over communities c of [ w_in(c)/m - gamma * (K_c / 2m)^2 ]
  * where:
- * - m = total edge weight
- * - A_ij = adjacency matrix entry (edge weight between i and j)
- * - k_i, k_j = degrees of nodes i and j
- * - γ = resolution parameter (higher values favor smaller communities)
- * - δ = Kronecker delta (1 if same community, 0 otherwise)
+ * - m = total edge weight, each undirected edge counted once
+ * - w_in(c) = summed weight of the edges with both endpoints inside community c
+ * - K_c = summed weighted degree of community c's nodes
+ * - gamma = resolution parameter (higher values favor smaller communities)
+ *
+ * This is the per-community form of Q = (1/2m) * sum_ij [A_ij - gamma * k_i * k_j / (2m)] over the
+ * pairs in the same community.
+ * The double sum runs over every PAIR of nodes inside a community, so collecting the null-model
+ * term only where an edge exists leaves the penalty far too small and rewards coarseness: the
+ * single-community partition, whose modularity is 0 by definition, would otherwise outscore every
+ * real split. The form below visits each community once and each edge once, so it counts every
+ * pair exactly once without a pass over the whole adjacency matrix.
  * @param graph - The input graph
  * @param communities - Map from node IDs to community IDs
  * @param resolution - Resolution parameter (default: 1.0)

package/dist/src/algorithms/community/modularity-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"modularity-utils.d.ts","sourceRoot":"","sources":["../../../../src/algorithms/community/modularity-utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAEnD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAQvD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CASlE;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAWlH;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU,SAAM,GAAG,MAAM,CAgD5G"}
+{"version":3,"file":"modularity-utils.d.ts","sourceRoot":"","sources":["../../../../src/algorithms/community/modularity-utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAEnD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAQvD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CASlE;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAWlH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU,SAAM,GAAG,MAAM,CAqC5G"}

package/dist/src/algorithms/community/modularity-utils.js

@@ -52,15 +52,23 @@ export function getNeighborCommunities(graph, nodeId, communities) {
  * Calculate modularity of a partition
  *
  * Modularity measures the quality of a community partition. It compares the
- * number of edges within communities to what would be expected in a random graph.
+ * weight of the edges inside communities to what would be expected in a random graph
+ * with the same degrees.
  *
- * Formula: Q = (1/2m) * Σ[A_ij - γ(k_i * k_j)/(2m)] * δ(c_i, c_j)
+ * Formula: Q = sum over communities c of [ w_in(c)/m - gamma * (K_c / 2m)^2 ]
  * where:
- * - m = total edge weight
- * - A_ij = adjacency matrix entry (edge weight between i and j)
- * - k_i, k_j = degrees of nodes i and j
- * - γ = resolution parameter (higher values favor smaller communities)
- * - δ = Kronecker delta (1 if same community, 0 otherwise)
+ * - m = total edge weight, each undirected edge counted once
+ * - w_in(c) = summed weight of the edges with both endpoints inside community c
+ * - K_c = summed weighted degree of community c's nodes
+ * - gamma = resolution parameter (higher values favor smaller communities)
+ *
+ * This is the per-community form of Q = (1/2m) * sum_ij [A_ij - gamma * k_i * k_j / (2m)] over the
+ * pairs in the same community.
+ * The double sum runs over every PAIR of nodes inside a community, so collecting the null-model
+ * term only where an edge exists leaves the penalty far too small and rewards coarseness: the
+ * single-community partition, whose modularity is 0 by definition, would otherwise outscore every
+ * real split. The form below visits each community once and each edge once, so it counts every
+ * pair exactly once without a pass over the whole adjacency matrix.
  * @param graph - The input graph
  * @param communities - Map from node IDs to community IDs
  * @param resolution - Resolution parameter (default: 1.0)
@@ -71,38 +79,30 @@ export function calculateModularity(graph, communities, resolution = 1.0) {
     if (totalEdgeWeight === 0) {
         return 0;
     }
-    let modularity = 0;
-    // For undirected graphs, we need to be careful not to double-count edges
-    const countedEdges = new Set();
-    // Calculate modularity: Q = (1/2m) * Σ[A_ij - γ(k_i * k_j)/(2m)] * δ(c_i, c_j)
-    for (const nodeI of graph.nodes()) {
-        for (const nodeJ of graph.nodes()) {
-            // Skip if already counted this pair in undirected graph
-            if (!graph.isDirected) {
-                const nodeIStr = String(nodeI.id);
-                const nodeJStr = String(nodeJ.id);
-                const edgeKey = nodeIStr <= nodeJStr ? `${nodeIStr}-${nodeJStr}` : `${nodeJStr}-${nodeIStr}`;
-                if (countedEdges.has(edgeKey)) {
-                    continue;
-                }
-                countedEdges.add(edgeKey);
-            }
-            if (communities.get(nodeI.id) === communities.get(nodeJ.id)) {
-                const edge = graph.getEdge(nodeI.id, nodeJ.id);
-                const reverseEdge = !graph.isDirected ? graph.getEdge(nodeJ.id, nodeI.id) : null;
-                let edgeWeight = 0;
-                if (edge) {
-                    edgeWeight += edge.weight ?? 1;
-                }
-                if (reverseEdge && nodeI.id !== nodeJ.id) {
-                    edgeWeight += reverseEdge.weight ?? 1;
-                }
-                const degreeI = getNodeDegree(graph, nodeI.id);
-                const degreeJ = getNodeDegree(graph, nodeJ.id);
-                modularity += edgeWeight - (resolution * degreeI * degreeJ) / (2 * totalEdgeWeight);
-            }
+    // Summed weighted degree of each community's nodes.
+    const degreeSum = new Map();
+    for (const node of graph.nodes()) {
+        const community = communities.get(node.id);
+        if (community === undefined) {
+            continue;
         }
+        degreeSum.set(community, (degreeSum.get(community) ?? 0) + getNodeDegree(graph, node.id));
+    }
+    // Summed weight of the edges that stay inside a community.
+    const internalWeight = new Map();
+    for (const edge of graph.edges()) {
+        const communityI = communities.get(edge.source);
+        const communityJ = communities.get(edge.target);
+        if (communityI === undefined || communityI !== communityJ) {
+            continue;
+        }
+        internalWeight.set(communityI, (internalWeight.get(communityI) ?? 0) + (edge.weight ?? 1));
+    }
+    let modularity = 0;
+    for (const [community, degrees] of degreeSum) {
+        const share = degrees / (2 * totalEdgeWeight);
+        modularity += (internalWeight.get(community) ?? 0) / totalEdgeWeight - resolution * share * share;
     }
-    return modularity / (2 * totalEdgeWeight);
+    return modularity;
 }
 //# sourceMappingURL=modularity-utils.js.map

package/dist/src/algorithms/community/modularity-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"modularity-utils.js","sourceRoot":"","sources":["../../../../src/algorithms/community/modularity-utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"modularity-utils.js","sourceRoot":"","sources":["../../../../src/algorithms/community/modularity-utils.ts"],"names":[],"mappings":"AAQA;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAY;IAC3C,IAAI,WAAW,GAAG,CAAC,CAAC;IAEpB,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;QAC/B,WAAW,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,OAAO,WAAW,CAAC;AACvB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,KAAY,EAAE,MAAc;IACtD,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC7C,MAAM,IAAI,IAAI,EAAE,MAAM,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAY,EAAE,MAAc,EAAE,WAAgC;IACjG,MAAM,mBAAmB,GAAG,IAAI,GAAG,EAAU,CAAC;IAE9C,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7C,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC1B,mBAAmB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACvC,CAAC;IACL,CAAC;IAED,OAAO,mBAAmB,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAY,EAAE,WAAgC,EAAE,UAAU,GAAG,GAAG;IAChG,MAAM,eAAe,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAClD,IAAI,eAAe,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,CAAC,CAAC;IACb,CAAC;IAED,oDAAoD;IACpD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;QAC/B,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC3C,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC1B,SAAS;QACb,CAAC;QAED,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,GAAG,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9F,CAAC;IAED,2DAA2D;IAC3D,MAAM,cAAc,GAAG,IAAI,GAAG,EAAkB,CAAC;IACjD,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;QAC/B,MAAM,UAAU,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAChD,MAAM,UAAU,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAEhD,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,UAAU,EAAE,CAAC;YACxD,SAAS;QACb,CAAC;QAED,cAAc,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC;IAC/F,CAAC;IAED,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,IAAI,SAAS,EAAE,CAAC;QAC3C,MAAM,KAAK,GAAG,OAAO,GAAG,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC;QAC9C,UAAU,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,GAAG,eAAe,GAAG,UAAU,GAAG,KAAK,GAAG,KAAK,CAAC;IACtG,CAAC;IAED,OAAO,UAAU,CAAC;AACtB,CAAC"}

package/dist/src/algorithms/shortest-path/bellman-ford.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bellman-ford.d.ts","sourceRoot":"","sources":["../../../../src/algorithms/shortest-path/bellman-ford.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAGvE;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAC9B;;OAEG;IACH,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;OAEG;IACH,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC;;OAEG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;OAEG;IACH,kBAAkB,EAAE,MAAM,EAAE,CAAC;CAChC;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,iBAAiB,CA6E7G;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CA6BvG;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CA4BtD"}
+{"version":3,"file":"bellman-ford.d.ts","sourceRoot":"","sources":["../../../../src/algorithms/shortest-path/bellman-ford.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAGvE;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAC9B;;OAEG;IACH,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;OAEG;IACH,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC;;OAEG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;OAEG;IACH,kBAAkB,EAAE,MAAM,EAAE,CAAC;CAChC;AAuCD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,iBAAiB,CA8E7G;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CA6BvG;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CA4BtD"}

package/dist/src/algorithms/shortest-path/bellman-ford.js

@@ -1,4 +1,30 @@
 import { reconstructPath } from "../../utils/graph-utilities.js";
+/**
+ * Expand the graph's edges into the arcs Bellman-Ford may relax.
+ *
+ * A directed graph yields one arc per edge. An UNDIRECTED graph yields two, because
+ * `graph.edges()` reports each undirected edge once, arbitrarily oriented from one of its
+ * endpoints. Relaxing only that orientation makes every edge one-way and leaves most of an
+ * undirected graph unreachable from the source -- the distances come back as Infinity for
+ * nodes that are plainly connected.
+ *
+ * Note that expanding is not merely a convenience: on an undirected graph a single
+ * negative-weight edge IS a negative cycle, since it can be traversed back and forth forever.
+ * Producing both arcs is what lets the cycle check below report that correctly.
+ * @param graph - The graph whose edges are being expanded.
+ * @returns Every arc that may be relaxed, in edge order.
+ */
+function relaxableArcs(graph) {
+    const arcs = [];
+    for (const edge of graph.edges()) {
+        const weight = edge.weight ?? 1;
+        arcs.push({ from: edge.source, to: edge.target, weight });
+        if (!graph.isDirected) {
+            arcs.push({ from: edge.target, to: edge.source, weight });
+        }
+    }
+    return arcs;
+}
 /**
  * Find shortest paths from source using Bellman-Ford algorithm
  * @param graph - The graph to search
@@ -13,6 +39,7 @@ export function bellmanFord(graph, source, options = {}) {
     const distances = new Map();
     const predecessors = new Map();
     const nodes = Array.from(graph.nodes()).map((node) => node.id);
+    const arcs = relaxableArcs(graph);
     // Initialize distances
     for (const nodeId of nodes) {
         distances.set(nodeId, nodeId === source ? 0 : Infinity);
@@ -21,10 +48,10 @@ export function bellmanFord(graph, source, options = {}) {
     // Relax edges |V| - 1 times
     for (let i = 0; i < nodes.length - 1; i++) {
         let updated = false;
-        for (const edge of Array.from(graph.edges())) {
-            const u = edge.source;
-            const v = edge.target;
-            const weight = edge.weight ?? 1;
+        for (const arc of arcs) {
+            const u = arc.from;
+            const v = arc.to;
+            const { weight } = arc;
             const distanceU = distances.get(u);
             const distanceV = distances.get(v);
             if (distanceU !== undefined && distanceV !== undefined && distanceU !== Infinity) {
@@ -48,10 +75,10 @@ export function bellmanFord(graph, source, options = {}) {
     // Check for negative cycles
     const negativeCycleNodes = [];
     let hasNegativeCycle = false;
-    for (const edge of graph.edges()) {
-        const u = edge.source;
-        const v = edge.target;
-        const weight = edge.weight ?? 1;
+    for (const arc of arcs) {
+        const u = arc.from;
+        const v = arc.to;
+        const { weight } = arc;
         const distanceU = distances.get(u);
         const distanceV = distances.get(v);
         if (distanceU !== undefined && distanceV !== undefined && distanceU !== Infinity) {

package/dist/src/algorithms/shortest-path/bellman-ford.js.map

@@ -1 +1 @@
-{"version":3,"file":"bellman-ford.js","sourceRoot":"","sources":["../../../../src/algorithms/shortest-path/bellman-ford.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bellman-ford.js","sourceRoot":"","sources":["../../../../src/algorithms/shortest-path/bellman-ford.ts"],"names":[],"mappings":"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"}

package/dist/src/errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Thrown when an iterative algorithm reaches its iteration cap before meeting its tolerance.
+ *
+ * The scores it had reached are not returned: an unconverged vector is not the answer, and
+ * returning it in silence would pass it off as one. networkx makes the same choice with
+ * `PowerIterationFailedConvergence`. Raise `maxIterations`, or loosen `tolerance`, and call again.
+ */
+export declare class ConvergenceError extends Error {
+    readonly algorithm: string;
+    readonly iterations: number;
+    readonly tolerance: number;
+    readonly name = "ConvergenceError";
+    /**
+     * Builds the error and its message.
+     * @param algorithm - The function that gave up, e.g. `"eigenvectorCentrality"`
+     * @param iterations - The passes it ran, which is its `maxIterations`
+     * @param tolerance - The tolerance it did not meet
+     */
+    constructor(algorithm: string, iterations: number, tolerance: number);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IAUnC,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM;IAX9B,SAAkB,IAAI,sBAAsB;IAE5C;;;;;OAKG;gBAEU,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM;CAMjC"}

package/dist/src/errors.js

@@ -0,0 +1,23 @@
+/**
+ * Thrown when an iterative algorithm reaches its iteration cap before meeting its tolerance.
+ *
+ * The scores it had reached are not returned: an unconverged vector is not the answer, and
+ * returning it in silence would pass it off as one. networkx makes the same choice with
+ * `PowerIterationFailedConvergence`. Raise `maxIterations`, or loosen `tolerance`, and call again.
+ */
+export class ConvergenceError extends Error {
+    /**
+     * Builds the error and its message.
+     * @param algorithm - The function that gave up, e.g. `"eigenvectorCentrality"`
+     * @param iterations - The passes it ran, which is its `maxIterations`
+     * @param tolerance - The tolerance it did not meet
+     */
+    constructor(algorithm, iterations, tolerance) {
+        super(`${algorithm} did not converge in ${String(iterations)} iterations (tolerance ${String(tolerance)}); raise maxIterations or tolerance`);
+        this.algorithm = algorithm;
+        this.iterations = iterations;
+        this.tolerance = tolerance;
+        this.name = "ConvergenceError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAGvC;;;;;OAKG;IACH,YACa,SAAiB,EACjB,UAAkB,EAClB,SAAiB;QAE1B,KAAK,CACD,GAAG,SAAS,wBAAwB,MAAM,CAAC,UAAU,CAAC,0BAA0B,MAAM,CAAC,SAAS,CAAC,qCAAqC,CACzI,CAAC;QANO,cAAS,GAAT,SAAS,CAAQ;QACjB,eAAU,GAAV,UAAU,CAAQ;QAClB,cAAS,GAAT,SAAS,CAAQ;QAXZ,SAAI,GAAG,kBAAkB,CAAC;IAgB5C,CAAC;CACJ"}

package/dist/src/index.d.ts

@@ -7,6 +7,7 @@
  */
 export { Graph } from "./core/graph.js";
 export type { BellmanFordResult, CentralityOptions, CentralityResult, CommunityResult, ComponentResult, DijkstraOptions, Edge, FloydWarshallResult, GirvanNewmanOptions, GraphConfig, LouvainOptions, MSTResult, Node, NodeId, PageRankOptions, ShortestPathResult, TraversalOptions, TraversalResult, } from "./types/index.js";
+export { ConvergenceError } from "./errors.js";
 export * from "./algorithms/index.js";
 export * from "./research/index.js";
 export * from "./data-structures/index.js";

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAGxC,YAAY,EACR,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,eAAe,EACf,IAAI,EACJ,mBAAmB,EACnB,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,SAAS,EACT,IAAI,EACJ,MAAM,EAON,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,GAClB,MAAM,kBAAkB,CAAC;AAG1B,cAAc,uBAAuB,CAAC;AAGtC,cAAc,qBAAqB,CAAC;AAGpC,cAAc,4BAA4B,CAAC;AAG3C,cAAc,sBAAsB,CAAC;AAKrC,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAC;AAG9C,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAItD,YAAY,EACR,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,EACd,qBAAqB,EACrB,6BAA6B,EAC7B,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,cAAc,EACd,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,GACjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,YAAY,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAC5E,YAAY,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACrE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE9D,YAAY,EACR,eAAe,IAAI,sBAAsB,EACzC,cAAc,IAAI,qBAAqB,GAC1C,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAGxC,YAAY,EACR,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,eAAe,EACf,IAAI,EACJ,mBAAmB,EACnB,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,SAAS,EACT,IAAI,EACJ,MAAM,EAON,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,GAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,cAAc,uBAAuB,CAAC;AAGtC,cAAc,qBAAqB,CAAC;AAGpC,cAAc,4BAA4B,CAAC;AAG3C,cAAc,sBAAsB,CAAC;AAKrC,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAC;AAG9C,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAItD,YAAY,EACR,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,EACd,qBAAqB,EACrB,6BAA6B,EAC7B,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,cAAc,EACd,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,GACjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,YAAY,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAC5E,YAAY,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACrE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE9D,YAAY,EACR,eAAe,IAAI,sBAAsB,EACzC,cAAc,IAAI,qBAAqB,GAC1C,MAAM,uBAAuB,CAAC"}

package/dist/src/index.js

@@ -7,6 +7,8 @@
  */
 // Core exports
 export { Graph } from "./core/graph.js";
+// Error exports
+export { ConvergenceError } from "./errors.js";
 // Algorithm exports
 export * from "./algorithms/index.js";
 // Research algorithms exports (Priority 4)

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAe;AACf,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AA8BxC,oBAAoB;AACpB,cAAc,uBAAuB,CAAC;AAEtC,2CAA2C;AAC3C,cAAc,qBAAqB,CAAC;AAEpC,yBAAyB;AACzB,cAAc,4BAA4B,CAAC;AAE3C,8BAA8B;AAC9B,cAAc,sBAAsB,CAAC;AAErC,sGAAsG;AACtG,qGAAqG;AACrG,0GAA0G;AAC1G,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAC;AAE9C,6DAA6D;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAsBtD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAYvD,iDAAiD;AACjD,+DAA+D"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAe;AACf,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AA8BxC,gBAAgB;AAChB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,oBAAoB;AACpB,cAAc,uBAAuB,CAAC;AAEtC,2CAA2C;AAC3C,cAAc,qBAAqB,CAAC;AAEpC,yBAAyB;AACzB,cAAc,4BAA4B,CAAC;AAE3C,8BAA8B;AAC9B,cAAc,sBAAsB,CAAC;AAErC,sGAAsG;AACtG,qGAAqG;AACrG,0GAA0G;AAC1G,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAC;AAE9C,6DAA6D;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAsBtD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAYvD,iDAAiD;AACjD,+DAA+D"}