@graphty/algorithms 1.2.0 → 1.4.2

package/src/algorithms/centrality/pagerank.ts

@@ -1,5 +1,6 @@
-import type {Graph} from "../../core/graph.js";
-import type {NodeId} from "../../types/index.js";
+import type { Graph } from "../../core/graph.js";
+import type { NodeId } from "../../types/index.js";
+import { SimpleDeltaPageRank } from "./delta-pagerank-simple.js";
 
 /**
  * PageRank algorithm implementation
@@ -36,6 +37,12 @@ export interface PageRankOptions {
      * Weight attribute for weighted PageRank (default: null = unweighted)
      */
     weight?: string;
+    /**
+     * Use delta-based optimization for faster convergence.
+     * Defaults to true for graphs with >100 nodes, false for smaller graphs.
+     * Set explicitly to override automatic heuristic.
+     */
+    useDelta?: boolean;
 }
 
 /**
@@ -58,11 +65,22 @@ export interface PageRankResult {
 
 /**
  * Calculate PageRank for all nodes in the graph
+ *
+ * Uses delta-based optimization by default for improved performance on larger graphs.
+ * Automatically falls back to standard algorithm for very small graphs.
+ *
+ * The delta-based approach provides significant speedup for:
+ * - Incremental updates after graph modifications
+ * - Graphs with localized changes
+ * - Early convergence detection per vertex
+ *
+ * For initial computation on small-medium graphs, standard algorithm may be faster
+ * due to lower overhead.
+ * @param graph - The directed input graph to analyze
+ * @param options - Algorithm configuration options
+ * @returns PageRank result containing ranks, iteration count, and convergence status
  */
-export function pageRank(
-    graph: Graph,
-    options: PageRankOptions = {},
-): PageRankResult {
+export function pageRank(graph: Graph, options: PageRankOptions = {}): PageRankResult {
     const {
         dampingFactor = 0.85,
         maxIterations = 100,
@@ -84,7 +102,50 @@ export function pageRank(
     const n = nodes.length;
 
     if (n === 0) {
-        return {ranks: {}, iterations: 0, converged: true};
+        return { ranks: {}, iterations: 0, converged: true };
+    }
+
+    // Use delta-based optimization by default for larger graphs
+    // Only disable if explicitly requested or graph is very small (overhead dominates)
+    const shouldUseDelta = options.useDelta !== false && n > 100;
+
+    if (shouldUseDelta) {
+        // Use optimized delta-based implementation
+
+        const deltaOptions: {
+            dampingFactor: number;
+            tolerance: number;
+            maxIterations: number;
+            personalization?: Map<NodeId, number>;
+            weight?: string;
+        } = {
+            dampingFactor,
+            tolerance,
+            maxIterations,
+        };
+
+        if (personalization) {
+            deltaOptions.personalization = personalization;
+        }
+
+        if (weight) {
+            deltaOptions.weight = weight;
+        }
+
+        const deltaPageRank = new SimpleDeltaPageRank(graph);
+        const deltaRanks = deltaPageRank.compute(deltaOptions);
+
+        // Convert to string-keyed record
+        const result: Record<string, number> = {};
+        for (const [nodeId, rank] of deltaRanks) {
+            result[String(nodeId)] = rank;
+        }
+
+        return {
+            ranks: result,
+            iterations: maxIterations, // For now, assume we used all iterations
+            converged: true,
+        };
     }
 
     // Initialize PageRank values
@@ -160,7 +221,7 @@ export function pageRank(
         }
 
         if (danglingSum > 0) {
-            const danglingContribution = dampingFactor * danglingSum / n;
+            const danglingContribution = (dampingFactor * danglingSum) / n;
             for (const nodeId of nodes) {
                 const currentRank = newRanks.get(nodeId) ?? 0;
                 if (personalVector) {
@@ -223,12 +284,21 @@ export function pageRank(
 
 /**
  * Calculate Personalized PageRank for a specific set of source nodes
+ * @param graph - The directed input graph to analyze
+ * @param personalNodes - Nodes to personalize the PageRank towards
+ * @param options - Algorithm configuration options
+ * @returns PageRank result containing ranks, iteration count, and convergence status
  */
 export function personalizedPageRank(
     graph: Graph,
     personalNodes: NodeId[],
     options: Omit<PageRankOptions, "personalization"> = {},
 ): PageRankResult {
+    // Handle empty personal nodes by falling back to standard PageRank
+    if (personalNodes.length === 0) {
+        return pageRank(graph, options);
+    }
+
     const nodes = Array.from(graph.nodes()).map((node) => node.id);
     const personalization = new Map<NodeId, number>();
 
@@ -248,35 +318,39 @@ export function personalizedPageRank(
     }
 
     return pageRank(graph, {
-        ... options,
+        ...options,
         personalization,
     });
 }
 
 /**
  * Calculate PageRank centrality (normalized PageRank scores)
+ * @param graph - The directed input graph to analyze
+ * @param options - Algorithm configuration options
+ * @returns PageRank scores for each node keyed by node ID
  */
-export function pageRankCentrality(
-    graph: Graph,
-    options: PageRankOptions = {},
-): Record<string, number> {
+export function pageRankCentrality(graph: Graph, options: PageRankOptions = {}): Record<string, number> {
     const result = pageRank(graph, options);
     return result.ranks;
 }
 
 /**
  * Get the top-k nodes by PageRank score
+ * @param graph - The directed input graph to analyze
+ * @param k - Number of top nodes to return
+ * @param options - Algorithm configuration options
+ * @returns Array of top-k nodes with their PageRank scores, sorted descending
  */
 export function topPageRankNodes(
     graph: Graph,
     k: number,
     options: PageRankOptions = {},
-): {node: NodeId, rank: number}[] {
+): { node: NodeId; rank: number }[] {
     const result = pageRank(graph, options);
 
-    const nodeRanks: {node: NodeId, rank: number}[] = [];
+    const nodeRanks: { node: NodeId; rank: number }[] = [];
     for (const [nodeStr, rank] of Object.entries(result.ranks)) {
-        nodeRanks.push({node: nodeStr as NodeId, rank});
+        nodeRanks.push({ node: nodeStr as NodeId, rank });
     }
 
     // Sort by rank in descending order
@@ -287,6 +361,7 @@ export function topPageRankNodes(
 
 /**
  * Normalize ranks so they sum to 1
+ * @param ranks - The ranks map to normalize in place
  */
 function normalizeRanks(ranks: Map<NodeId, number>): void {
     let sum = 0;

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

@@ -1,6 +1,6 @@
-import {Graph} from "../../core/graph.js";
-import type {CommunityResult, ComponentResult, GirvanNewmanOptions, NodeId} from "../../types/index.js";
-import {connectedComponents} from "../components/connected.js";
+import { Graph } from "../../core/graph.js";
+import type { CommunityResult, ComponentResult, GirvanNewmanOptions, NodeId } from "../../types/index.js";
+import { connectedComponents } from "../components/connected.js";
 
 /**
  * Girvan-Newman community detection algorithm
@@ -14,22 +14,20 @@ import {connectedComponents} from "../components/connected.js";
  *
  * References:
  * - Girvan, M., & Newman, M. E. J. (2002). Community structure in social
- *   and biological networks. Proceedings of the National Academy of Sciences,
- *   99(12), 7821-7826.
- *
+ * and biological networks. Proceedings of the National Academy of Sciences,
+ * 99(12), 7821-7826.
  * @param graph - The input graph
  * @param options - Algorithm options
  * @returns Array of community detection results representing the dendrogram
  */
-export function girvanNewman(
-    graph: Graph,
-    options: GirvanNewmanOptions = {},
-): CommunityResult[] {
-    const {maxCommunities} = options;
+export function girvanNewman(graph: Graph, options: GirvanNewmanOptions = {}): CommunityResult[] {
+    const { maxCommunities } = options;
     const minCommunitySize = options.minCommunitySize ?? 1;
+    const maxIterations = options.maxIterations ?? 100; // Prevent infinite loops
 
     const dendrogram: CommunityResult[] = [];
-    const workingGraph = cloneGraph(graph);
+    const workingGraph = graph.clone();
+    let iterations = 0;
 
     // Initial state: one large component
     let components = getConnectedComponentsResult(workingGraph);
@@ -38,7 +36,8 @@ export function girvanNewman(
         modularity: calculateModularity(graph, components.componentMap),
     });
 
-    while (Array.from(workingGraph.edges()).length > 0) {
+    while (Array.from(workingGraph.edges()).length > 0 && iterations < maxIterations) {
+        iterations++;
         // Calculate edge betweenness centrality
         const edgeBetweenness = calculateEdgeBetweenness(workingGraph);
 
@@ -47,20 +46,20 @@ export function girvanNewman(
         }
 
         // Find edges with maximum betweenness
-        const maxBetweenness = Math.max(... edgeBetweenness.values());
-        const edgesToRemove: {source: NodeId, target: NodeId}[] = [];
+        const maxBetweenness = Math.max(...edgeBetweenness.values());
+        const edgesToRemove: { source: NodeId; target: NodeId }[] = [];
 
         for (const [edgeKey, centrality] of edgeBetweenness) {
             if (Math.abs(centrality - maxBetweenness) < 1e-10) {
                 const [source, target] = edgeKey.split("|");
                 if (source && target) {
-                    edgesToRemove.push({source, target});
+                    edgesToRemove.push({ source, target });
                 }
             }
         }
 
         // Remove edges with highest betweenness
-        for (const {source, target} of edgesToRemove) {
+        for (const { source, target } of edgesToRemove) {
             workingGraph.removeEdge(source, target);
         }
 
@@ -68,9 +67,7 @@ export function girvanNewman(
         components = getConnectedComponentsResult(workingGraph);
 
         // Filter communities by minimum size
-        const validCommunities = components.components.filter(
-            (community) => community.length >= minCommunitySize,
-        );
+        const validCommunities = components.components.filter((community) => community.length >= minCommunitySize);
 
         // Calculate modularity for the new community structure
         const modularity = calculateModularity(graph, components.componentMap);
@@ -99,6 +96,8 @@ export function girvanNewman(
  *
  * Edge betweenness is the fraction of shortest paths that pass through the edge.
  * We adapt node betweenness centrality calculation to work with edges.
+ * @param graph - The input graph to analyze
+ * @returns Map of edge keys to their betweenness centrality values
  */
 function calculateEdgeBetweenness(graph: Graph): Map<string, number> {
     const edgeBetweenness = new Map<string, number>();
@@ -114,7 +113,7 @@ function calculateEdgeBetweenness(graph: Graph): Map<string, number> {
         const source = sourceNode.id;
 
         // Run BFS to find all shortest paths from source
-        const {distances, predecessors, pathCounts} = findAllShortestPaths(graph, source);
+        const { distances, predecessors, pathCounts } = findAllShortestPaths(graph, source);
 
         // Calculate dependency for each node and accumulate edge betweenness
         const dependency = new Map<NodeId, number>();
@@ -187,9 +186,15 @@ function calculateEdgeBetweenness(graph: Graph): Map<string, number> {
 }
 
 /**
- * Find all shortest paths from a source node using BFS
+ * Find all shortest paths from a source node using optimized BFS
+ * @param graph - The input graph to search
+ * @param source - The source node to compute shortest paths from
+ * @returns Object containing distances, predecessors, and path counts
  */
-function findAllShortestPaths(graph: Graph, source: NodeId): {
+function findAllShortestPaths(
+    graph: Graph,
+    source: NodeId,
+): {
     distances: Map<NodeId, number>;
     predecessors: Map<NodeId, NodeId[]>;
     pathCounts: Map<NodeId, number>;
@@ -198,39 +203,43 @@ function findAllShortestPaths(graph: Graph, source: NodeId): {
     const predecessors = new Map<NodeId, NodeId[]>();
     const pathCounts = new Map<NodeId, number>();
     const queue: NodeId[] = [];
+    const visited = new Set<NodeId>();
 
-    // Initialize
-    for (const node of graph.nodes()) {
-        distances.set(node.id, Infinity);
-        predecessors.set(node.id, []);
-        pathCounts.set(node.id, 0);
-    }
-
+    // Only initialize for reachable nodes
     distances.set(source, 0);
+    predecessors.set(source, []);
     pathCounts.set(source, 1);
     queue.push(source);
 
-    // BFS
-    while (queue.length > 0) {
-        const current = queue.shift();
-        if (current === undefined) {
-            break;
+    // Optimized BFS with early termination
+    let queueIndex = 0;
+    while (queueIndex < queue.length) {
+        const current = queue[queueIndex++];
+        if (!current) {
+            continue;
+        }
+
+        if (visited.has(current)) {
+            continue;
         }
 
+        visited.add(current);
+
         const currentDistance = distances.get(current);
         if (currentDistance === undefined) {
             continue;
         }
 
         for (const neighbor of graph.neighbors(current)) {
-            const edge = graph.getEdge(current, neighbor);
-            const edgeWeight = edge?.weight ?? 1;
-            const newDistance = currentDistance + edgeWeight;
-            const neighborDistance = distances.get(neighbor);
-            if (neighborDistance === undefined) {
+            // Skip if already processed
+            if (visited.has(neighbor)) {
                 continue;
             }
 
+            const edgeWeight = 1; // Unweighted for community detection
+            const newDistance = currentDistance + edgeWeight;
+            const neighborDistance = distances.get(neighbor) ?? Infinity;
+
             if (newDistance < neighborDistance) {
                 // Found shorter path
                 distances.set(neighbor, newDistance);
@@ -241,25 +250,28 @@ function findAllShortestPaths(graph: Graph, source: NodeId): {
                 }
 
                 queue.push(neighbor);
-            } else if (Math.abs(newDistance - neighborDistance) < 1e-10) {
+            } else if (newDistance === neighborDistance) {
                 // Found alternative shortest path
                 const neighborPredecessors = predecessors.get(neighbor);
-                const neighborPathCount = pathCounts.get(neighbor);
-                const currentPathCount = pathCounts.get(current);
-
-                if (neighborPredecessors && neighborPathCount !== undefined && currentPathCount !== undefined) {
+                if (neighborPredecessors) {
                     neighborPredecessors.push(current);
-                    pathCounts.set(neighbor, neighborPathCount + currentPathCount);
+                    const currentPathCount = pathCounts.get(current);
+                    if (currentPathCount !== undefined) {
+                        pathCounts.set(neighbor, (pathCounts.get(neighbor) ?? 0) + currentPathCount);
+                    }
                 }
             }
         }
     }
 
-    return {distances, predecessors, pathCounts};
+    return { distances, predecessors, pathCounts };
 }
 
 /**
  * Generate a consistent edge key for undirected graphs
+ * @param source - The source node ID
+ * @param target - The target node ID
+ * @returns A consistent string key for the edge (ordered alphabetically)
  */
 function getEdgeKey(source: NodeId, target: NodeId): string {
     // For undirected graphs, ensure consistent ordering
@@ -274,31 +286,39 @@ function getEdgeKey(source: NodeId, target: NodeId): string {
 }
 
 /**
- * Calculate modularity for a given community structure
+ * Calculate modularity for a given community structure - optimized version
+ * @param graph - The original graph
+ * @param communityMap - Map from node IDs to community indices
+ * @returns The modularity score of the partition
  */
-function calculateModularity(
-    graph: Graph,
-    communityMap: Map<NodeId, number>,
-): number {
+function calculateModularity(graph: Graph, communityMap: Map<NodeId, number>): number {
     const totalEdgeWeight = getTotalEdgeWeight(graph);
     if (totalEdgeWeight === 0) {
         return 0;
     }
 
     let modularity = 0;
+    const degrees = new Map<NodeId, number>();
 
-    // 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()) {
-            if (communityMap.get(nodeI.id) === communityMap.get(nodeJ.id)) {
-                const edge = graph.getEdge(nodeI.id, nodeJ.id);
-                const edgeWeight = edge?.weight ?? 0;
-
-                const degreeI = getNodeDegree(graph, nodeI.id);
-                const degreeJ = getNodeDegree(graph, nodeJ.id);
+    // Pre-calculate all degrees
+    for (const node of graph.nodes()) {
+        degrees.set(node.id, getNodeDegree(graph, node.id));
+    }
 
-                modularity += edgeWeight - ((degreeI * degreeJ) / (2 * totalEdgeWeight));
+    // Only iterate over existing edges
+    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);
         }
     }
 
@@ -307,6 +327,8 @@ function calculateModularity(
 
 /**
  * Calculate total edge weight in the graph
+ * @param graph - The input graph
+ * @returns Total sum of all edge weights
  */
 function getTotalEdgeWeight(graph: Graph): number {
     let totalWeight = 0;
@@ -320,6 +342,9 @@ function getTotalEdgeWeight(graph: Graph): number {
 
 /**
  * Get the total degree (sum of edge weights) for a node
+ * @param graph - The input graph
+ * @param nodeId - The node ID to compute degree for
+ * @returns The weighted degree of the node
  */
 function getNodeDegree(graph: Graph, nodeId: NodeId): number {
     let degree = 0;
@@ -334,6 +359,8 @@ function getNodeDegree(graph: Graph, nodeId: NodeId): number {
 
 /**
  * Convert connected components result to ComponentResult format
+ * @param graph - The input graph
+ * @returns Object containing components array and node-to-component map
  */
 function getConnectedComponentsResult(graph: Graph): ComponentResult {
     const components = connectedComponents(graph);
@@ -345,28 +372,5 @@ function getConnectedComponentsResult(graph: Graph): ComponentResult {
         });
     });
 
-    return {components, componentMap};
-}
-
-/**
- * Create a deep clone of the graph
- */
-function cloneGraph(graph: Graph): Graph {
-    const clone = new Graph({
-        directed: graph.isDirected,
-        allowSelfLoops: true,
-        allowParallelEdges: false,
-    });
-
-    // Add all nodes
-    for (const node of graph.nodes()) {
-        clone.addNode(node.id, node.data);
-    }
-
-    // Add all edges
-    for (const edge of graph.edges()) {
-        clone.addEdge(edge.source, edge.target, edge.weight, edge.data);
-    }
-
-    return clone;
+    return { components, componentMap };
 }

package/src/algorithms/community/index.ts

@@ -6,8 +6,9 @@
  * than with the rest of the network.
  */
 
-export {girvanNewman} from "./girvan-newman.js";
-export {labelPropagation, labelPropagationAsync, labelPropagationSemiSupervised} from "./label-propagation.js";
-export {leiden} from "./leiden.js";
-export {louvain} from "./louvain.js";
-
+export { girvanNewman } from "./girvan-newman.js";
+export type { LabelPropagationOptions, LabelPropagationResult } from "./label-propagation.js";
+export { labelPropagation, labelPropagationAsync, labelPropagationSemiSupervised } from "./label-propagation.js";
+export type { LeidenOptions, LeidenResult } from "./leiden.js";
+export { leiden } from "./leiden.js";
+export { louvain } from "./louvain.js";