@graphty/algorithms 1.8.1 → 2.0.1

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

@@ -69,15 +69,23 @@ export function getNeighborCommunities(graph: Graph, nodeId: 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)
@@ -89,46 +97,35 @@ export function calculateModularity(graph: Graph, communities: Map<NodeId, numbe
         return 0;
     }
 
-    let modularity = 0;
+    // Summed weighted degree of each community's nodes.
+    const degreeSum = new Map<number, number>();
+    for (const node of graph.nodes()) {
+        const community = communities.get(node.id);
+        if (community === undefined) {
+            continue;
+        }
 
-    // For undirected graphs, we need to be careful not to double-count edges
-    const countedEdges = new Set<string>();
-
-    // 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);
-            }
+        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<number, number>();
+    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;
 }

package/src/algorithms/shortest-path/bellman-ford.ts

@@ -42,6 +42,43 @@ export interface BellmanFordResult {
     negativeCycleNodes: NodeId[];
 }
 
+/**
+ * One relaxable arc: a direction an edge can actually be traversed in.
+ */
+interface Arc {
+    from: NodeId;
+    to: NodeId;
+    weight: number;
+}
+
+/**
+ * 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: Graph): Arc[] {
+    const arcs: Arc[] = [];
+    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
@@ -57,6 +94,7 @@ export function bellmanFord(graph: Graph, source: NodeId, options: BellmanFordOp
     const distances = new Map<NodeId, number>();
     const predecessors = new Map<NodeId, NodeId | null>();
     const nodes = Array.from(graph.nodes()).map((node) => node.id);
+    const arcs = relaxableArcs(graph);
 
     // Initialize distances
     for (const nodeId of nodes) {
@@ -68,10 +106,10 @@ export function bellmanFord(graph: Graph, source: NodeId, options: BellmanFordOp
     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);
@@ -102,10 +140,10 @@ export function bellmanFord(graph: Graph, source: NodeId, options: BellmanFordOp
     const negativeCycleNodes: NodeId[] = [];
     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);

package/src/errors.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 {
+    override 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(
+        readonly algorithm: string,
+        readonly iterations: number,
+        readonly tolerance: number,
+    ) {
+        super(
+            `${algorithm} did not converge in ${String(iterations)} iterations (tolerance ${String(tolerance)}); raise maxIterations or tolerance`,
+        );
+    }
+}

package/src/index.ts

@@ -37,6 +37,9 @@ export type {
     TraversalResult,
 } from "./types/index.js";
 
+// Error exports
+export { ConvergenceError } from "./errors.js";
+
 // Algorithm exports
 export * from "./algorithms/index.js";