@graphty/algorithms 1.8.1 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/algorithms",
-  "version": "1.8.1",
+  "version": "2.0.0",
   "description": "Graph algorithms library for browser environments implemented in TypeScript",
   "author": "Adam Powers <apowers@ato.ms>",
   "main": "dist/algorithms.js",
@@ -107,7 +107,7 @@
     "coverage:shard:default": "COVERAGE_DIR=.coverage-parts/default vitest run --project=default --coverage",
     "coverage:shard:browser": "COVERAGE_DIR=.coverage-parts/browser vitest run --project=browser --coverage",
     "coverage:fast": "vitest run --project=default --coverage",
-    "coverage:preview": "npx serve coverage -p 9051",
+    "coverage:preview": "npx serve coverage -p ${PORT:?start it through servherd, which sets PORT}",
     "test:browser": "vitest --project=browser",
     "test:all": "vitest run --project=default --project=browser",
     "test:performance": "tsx test/helpers/run-performance-regression.ts",
@@ -130,18 +130,18 @@
     "dev": "tsc --watch",
     "examples": "node examples/run-all-examples.js",
     "examples:run": "node examples/run-all-examples.js",
-    "examples:html": "npm run build:bundle && vite",
-    "serve": "npm run build:bundle && vite",
+    "examples:html": "npm run build:bundle && vite --port ${PORT:?start it through servherd, which sets PORT} --strictPort",
+    "serve": "npm run build:bundle && vite --port ${PORT:?start it through servherd, which sets PORT} --strictPort",
     "commit": "cz",
     "ready:commit": "npm run build && npm run lint && npm run test:all",
     "watch": "tsc --watch",
     "docs:api": "typedoc && node scripts/sanitize-api-docs.js",
     "docs:api:watch": "typedoc --watch",
-    "docs:dev": "vitepress dev docs",
+    "docs:dev": "vitepress dev docs --port ${PORT:?start it through servherd, which sets PORT} --strictPort",
     "docs:watch": "npm run docs:api && (npm run docs:api:watch & npm run docs:dev & wait)",
     "docs:build": "npm run docs:api && vitepress build docs",
-    "docs:preview": "vitepress preview docs",
-    "storybook": ". ../.env 2>/dev/null; storybook dev -p ${PORT:-6006} --host ${HOST:-localhost} ${HTTPS_CERT_PATH:+--https --ssl-cert $HTTPS_CERT_PATH --ssl-key $HTTPS_KEY_PATH} --no-open",
+    "docs:preview": "vitepress preview docs --port ${PORT:?start it through servherd, which sets PORT}",
+    "storybook": "storybook dev -p ${PORT:?start it through servherd, which sets PORT} --host ${HOST:-localhost} ${HTTPS_CERT_PATH:+--https --ssl-cert $HTTPS_CERT_PATH --ssl-key $HTTPS_KEY_PATH} --no-open",
     "build-storybook": "storybook build"
   }
 }

package/src/algorithms/centrality/eigenvector.ts

@@ -1,4 +1,5 @@
 import type { Graph } from "../../core/graph.js";
+import { ConvergenceError } from "../../errors.js";
 import type { CentralityOptions, CentralityResult } from "../../types/index.js";
 
 /**
@@ -9,137 +10,155 @@ import type { CentralityOptions, CentralityResult } from "../../types/index.js";
  * that themselves have high eigenvector centrality.
  *
  * Time complexity: O(V + E) per iteration
- * Space complexity: O(V)
+ * Space complexity: O(V + E)
  */
 
 export interface EigenvectorCentralityOptions extends CentralityOptions {
     maxIterations?: number; // Maximum iterations (default: 100)
-    tolerance?: number; // Convergence tolerance (default: 1e-6)
+    tolerance?: number; // Convergence tolerance per node (default: 1e-6)
     startVector?: Map<string, number>; // Initial vector (optional)
 }
 
 /**
  * Calculate eigenvector centrality for all nodes in the graph.
- * Uses the power iteration method to find the dominant eigenvector.
+ *
+ * Iterates x <- (A + I) x, as networkx does. Shifting by the identity raises every eigenvalue by
+ * one and leaves the eigenvectors alone, so the largest eigenvalue becomes the only one of largest
+ * magnitude -- even on a bipartite graph, whose spectrum holds both +lambda and -lambda and makes
+ * unshifted power iteration oscillate forever. The run stops when the L1 change summed over all
+ * nodes falls below `n * tolerance`, networkx's test.
+ *
+ * A node is fed by `graph.neighbors`, i.e. by its out-neighbours on a directed graph. When the
+ * graph has no cycle along that relation (no edges, or a directed acyclic graph) the adjacency
+ * matrix is nilpotent, its only eigenvalue is 0, and every score is exactly 0.
  * @param graph - The graph to compute eigenvector centrality on
  * @param options - Configuration options for the computation
  * @returns Object mapping node IDs to their eigenvector centrality scores
+ * @throws {ConvergenceError} When `maxIterations` passes do not meet `tolerance`, as networkx
+ *   raises `PowerIterationFailedConvergence`. Raise `maxIterations` or `tolerance` and call again.
  */
 export function eigenvectorCentrality(graph: Graph, options: EigenvectorCentralityOptions = {}): CentralityResult {
     const { maxIterations = 100, tolerance = 1e-6, normalized = true, startVector } = options;
 
+    const nodeIds = Array.from(graph.nodes(), (node) => node.id);
+    const keys = nodeIds.map((id) => id.toString());
+    const n = keys.length;
     const centrality: CentralityResult = {};
-    const nodes = Array.from(graph.nodes());
-    const nodeIds = nodes.map((node) => node.id);
 
-    if (nodeIds.length === 0) {
+    if (n === 0) {
         return centrality;
     }
 
-    // Initialize the eigenvector
-    let currentVector = new Map<string, number>();
-    let previousVector = new Map<string, number>();
+    const index = new Map(keys.map((key, i) => [key, i]));
+    const adjacency = nodeIds.map((id) => Array.from(graph.neighbors(id), (m) => index.get(m.toString()) ?? 0));
 
-    if (startVector) {
-        // Use provided start vector
-        for (const nodeId of nodeIds) {
-            const key = nodeId.toString();
-            currentVector.set(key, startVector.get(key) ?? 1.0 / Math.sqrt(nodeIds.length));
-        }
-    } else {
-        // Initialize with uniform distribution
-        const initialValue = 1.0 / Math.sqrt(nodeIds.length);
-        for (const nodeId of nodeIds) {
-            currentVector.set(nodeId.toString(), initialValue);
+    if (isNilpotent(adjacency)) {
+        for (const key of keys) {
+            centrality[key] = 0;
         }
+        return centrality;
     }
 
-    // Power iteration
-    for (let iteration = 0; iteration < maxIterations; iteration++) {
-        previousVector = new Map(currentVector);
-        currentVector = new Map();
-
-        // Update each node's centrality based on neighbors
-        for (const nodeId of nodeIds) {
-            let sum = 0;
-            const neighbors = Array.from(graph.neighbors(nodeId));
-
-            for (const neighbor of neighbors) {
-                const neighborKey = neighbor.toString();
-                const prevValue = previousVector.get(neighborKey);
-                sum += prevValue ?? 0;
-            }
-
-            currentVector.set(nodeId.toString(), sum);
-        }
-
-        // Normalize the vector
-        let norm = 0;
-        for (const value of Array.from(currentVector.values())) {
-            norm += value * value;
-        }
-        norm = Math.sqrt(norm);
-
-        if (norm === 0) {
-            // Graph has no edges or is disconnected
-            for (const nodeId of nodeIds) {
-                centrality[nodeId.toString()] = 0;
+    // A node with nothing feeding it scores exactly 0 once the largest eigenvalue is positive,
+    // so it starts there and (A + I) keeps it there.
+    let x = new Float64Array(n);
+    for (let i = 0; i < n; i++) {
+        x[i] = adjacency[i]?.length ? (startVector?.get(keys[i] ?? "") ?? 1) : 0;
+    }
+    scaleToUnitLength(x);
+
+    let next = new Float64Array(n);
+    let converged = false;
+    for (let iteration = 0; iteration < maxIterations && !converged; iteration++) {
+        for (let i = 0; i < n; i++) {
+            let sum = x[i] ?? 0;
+            for (const j of adjacency[i] ?? []) {
+                sum += x[j] ?? 0;
             }
-            return centrality;
-        }
-
-        // Normalize the vector
-        for (const [nodeId, value] of Array.from(currentVector)) {
-            currentVector.set(nodeId, value / norm);
+            next[i] = sum;
         }
+        scaleToUnitLength(next);
 
-        // Check for convergence
-        let maxDiff = 0;
-        for (const [nodeId, value] of Array.from(currentVector)) {
-            const prevValue = previousVector.get(nodeId) ?? 0;
-            const diff = Math.abs(value - prevValue);
-            maxDiff = Math.max(maxDiff, diff);
-        }
-
-        if (maxDiff < tolerance) {
-            break;
+        let change = 0;
+        for (let i = 0; i < n; i++) {
+            change += Math.abs((next[i] ?? 0) - (x[i] ?? 0));
         }
+        [x, next] = [next, x];
+        converged = change < n * tolerance;
+    }
+    if (!converged) {
+        throw new ConvergenceError("eigenvectorCentrality", maxIterations, tolerance);
     }
 
-    // Prepare results
-    for (const [nodeId, value] of Array.from(currentVector)) {
-        centrality[nodeId] = value;
+    for (let i = 0; i < n; i++) {
+        centrality[keys[i] ?? ""] = x[i] ?? 0;
     }
 
     // Additional normalization if requested (normalize to [0,1] range)
     if (normalized) {
         let maxValue = 0;
         let minValue = Number.POSITIVE_INFINITY;
-
-        for (const value of Object.values(centrality)) {
+        for (const value of x) {
             maxValue = Math.max(maxValue, value);
             minValue = Math.min(minValue, value);
         }
-
         const range = maxValue - minValue;
-        if (range > 0) {
-            for (const nodeId of Object.keys(centrality)) {
-                const centralityValue = centrality[nodeId];
-                if (centralityValue !== undefined) {
-                    centrality[nodeId] = (centralityValue - minValue) / range;
-                }
-            }
-        } else {
-            // All values are the same, set to 1
-            for (const nodeId of Object.keys(centrality)) {
-                centrality[nodeId] = maxValue > 0 ? 1 : 0;
-            }
+        // All scores equal: 1 each, or 0 each when there is nothing to score.
+        const flat = maxValue > 0 ? 1 : 0;
+        for (const key of keys) {
+            centrality[key] = range > 0 ? ((centrality[key] ?? 0) - minValue) / range : flat;
         }
     }
 
     return centrality;
 }
 
+/**
+ * Whether the relation has no cycle (Kahn's algorithm), which makes its adjacency matrix nilpotent.
+ * @param adjacency - Each node's neighbour indices
+ * @returns True when every node can be peeled off in topological order
+ */
+function isNilpotent(adjacency: number[][]): boolean {
+    const inDegree = new Int32Array(adjacency.length);
+    for (const targets of adjacency) {
+        for (const j of targets) {
+            inDegree[j] = (inDegree[j] ?? 0) + 1;
+        }
+    }
+    const queue: number[] = [];
+    inDegree.forEach((degree, i) => {
+        if (degree === 0) {
+            queue.push(i);
+        }
+    });
+    for (let head = 0; head < queue.length; head++) {
+        for (const j of adjacency[queue[head] ?? 0] ?? []) {
+            inDegree[j] = (inDegree[j] ?? 0) - 1;
+            if (inDegree[j] === 0) {
+                queue.push(j);
+            }
+        }
+    }
+    return queue.length === adjacency.length;
+}
+
+/**
+ * Scale a vector in place to unit Euclidean length (a zero vector is left alone).
+ * @param v - The vector to scale
+ */
+function scaleToUnitLength(v: Float64Array): void {
+    let norm = 0;
+    for (const value of v) {
+        norm += value * value;
+    }
+    norm = Math.sqrt(norm);
+    if (norm > 0) {
+        for (let i = 0; i < v.length; i++) {
+            v[i] = (v[i] ?? 0) / norm;
+        }
+    }
+}
+
 /**
  * Calculate eigenvector centrality for a specific node.
  * @param graph - The graph to compute eigenvector centrality on

package/src/algorithms/community/girvan-newman.ts

@@ -297,7 +297,23 @@ function getEdgeKey(source: NodeId, target: NodeId): string {
 }
 
 /**
- * Calculate modularity for a given community structure - optimized version
+ * Calculate modularity for a given community structure
+ *
+ * Newman's Q, written per community:
+ *
+ *     Q = sum over communities c of [ w_in(c) / m - ( K_c / (2m) )^2 ]
+ *
+ * where m is the total edge weight with each undirected edge counted once, w_in(c) is the summed
+ * weight of the edges with both endpoints inside c, and K_c is the summed weighted degree of c's
+ * nodes.
+ *
+ * WHY NOT A SUM OVER EDGES. The textbook double sum runs over every ordered PAIR of nodes inside
+ * a community, not only over the pairs an edge happens to join. Collecting the null-model term
+ * only where an edge exists leaves the penalty far too small, and the shortfall grows with
+ * community size -- so the uncut whole graph, whose modularity is 0 by definition, outscores
+ * every real cut and a caller reading the dendrogram the standard way is handed one community
+ * containing everything. The per-community form above counts every pair exactly once and still
+ * costs one pass over the edges rather than a pass over every pair.
  * @param graph - The original graph
  * @param communityMap - Map from node IDs to community indices
  * @returns The modularity score of the partition
@@ -308,32 +324,37 @@ function calculateModularity(graph: Graph, communityMap: Map<NodeId, number>): n
         return 0;
     }
 
-    let modularity = 0;
-    const degrees = new Map<NodeId, number>();
-
-    // Pre-calculate all degrees
+    // Summed weighted degree of each community's nodes.
+    const degreeSum = new Map<number, number>();
     for (const node of graph.nodes()) {
-        degrees.set(node.id, getNodeDegree(graph, node.id));
+        const community = communityMap.get(node.id);
+        if (community === undefined) {
+            continue;
+        }
+
+        degreeSum.set(community, (degreeSum.get(community) ?? 0) + getNodeDegree(graph, node.id));
     }
 
-    // Only iterate over existing edges
+    // Summed weight of the edges that stay inside a community.
+    const internalWeight = new Map<number, number>();
     for (const edge of graph.edges()) {
         const communityI = communityMap.get(edge.source);
         const communityJ = communityMap.get(edge.target);
 
-        if (communityI === communityJ) {
-            const edgeWeight = edge.weight ?? 1;
-            const degreeI = degrees.get(edge.source);
-            const degreeJ = degrees.get(edge.target);
-            if (degreeI === undefined || degreeJ === undefined) {
-                continue;
-            }
-
-            modularity += edgeWeight - (degreeI * degreeJ) / (2 * totalEdgeWeight);
+        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 - share * share;
     }
 
-    return modularity / (2 * totalEdgeWeight);
+    return modularity;
 }
 
 /**