@graphty/algorithms 1.1.0 → 1.3.1

package/src/algorithms/centrality/closeness.ts

@@ -1,5 +1,6 @@
 import type {Graph} from "../../core/graph.js";
 import type {NodeId} from "../../types/index.js";
+import {bfsDistancesOnly, bfsWeightedDistances} from "../traversal/bfs-variants.js";
 
 /**
  * Closeness centrality implementation
@@ -25,39 +26,21 @@ export interface ClosenessCentralityOptions {
      * Consider only nodes within this distance (default: undefined = all nodes)
      */
     cutoff?: number;
+    /**
+     * Whether to use optimized BFS implementation for large graphs
+     */
+    optimized?: boolean;
 }
 
 /**
- * Calculate closeness centrality for all nodes
- */
-export function closenessCentrality(
-    graph: Graph,
-    options: ClosenessCentralityOptions = {},
-): Record<string, number> {
-    const nodes = Array.from(graph.nodes()).map((node) => node.id);
-    const centrality: Record<string, number> = {};
-
-    for (const sourceNode of nodes) {
-        centrality[String(sourceNode)] = nodeClosenessCentrality(graph, sourceNode, options);
-    }
-
-    return centrality;
-}
-
-/**
- * Calculate closeness centrality for a specific node
+ * Calculate closeness centrality from distances
  */
-export function nodeClosenessCentrality(
-    graph: Graph,
-    node: NodeId,
-    options: ClosenessCentralityOptions = {},
+function calculateClosenessFromDistances(
+    distances: Map<NodeId, number>,
+    sourceNode: NodeId,
+    totalNodes: number,
+    options: ClosenessCentralityOptions,
 ): number {
-    if (!graph.hasNode(node)) {
-        throw new Error(`Node ${String(node)} not found in graph`);
-    }
-
-    const distances = singleSourceShortestPathLengths(graph, node, options.cutoff);
-
     if (distances.size <= 1) {
         return 0; // No other nodes reachable
     }
@@ -66,18 +49,23 @@ export function nodeClosenessCentrality(
 
     if (options.harmonic) {
         // Harmonic centrality: sum of reciprocals of distances
-        for (const [targetNode, distance] of Array.from(distances)) {
-            if (targetNode !== node && distance > 0) {
+        for (const [targetNode, distance] of distances) {
+            if (targetNode !== sourceNode && distance > 0 && distance < Infinity) {
                 centrality += 1 / distance;
             }
         }
+
+        // Normalization for harmonic centrality
+        if (options.normalized && totalNodes > 1) {
+            centrality = centrality / (totalNodes - 1);
+        }
     } else {
         // Standard closeness: reciprocal of sum of distances
         let totalDistance = 0;
         let reachableNodes = 0;
 
-        for (const [targetNode, distance] of Array.from(distances)) {
-            if (targetNode !== node) {
+        for (const [targetNode, distance] of distances) {
+            if (targetNode !== sourceNode && distance < Infinity) {
                 totalDistance += distance;
                 reachableNodes++;
             }
@@ -87,70 +75,70 @@ export function nodeClosenessCentrality(
             centrality = 1 / totalDistance;
 
             // Wasserman and Faust normalization for disconnected graphs
-            if (options.normalized) {
-                const n = Array.from(graph.nodes()).length;
-                centrality = centrality * reachableNodes / (n - 1);
+            if (options.normalized && totalNodes > 1) {
+                centrality = centrality * reachableNodes / (totalNodes - 1);
             }
         }
     }
 
-    // Normalization for harmonic centrality
-    if (options.harmonic && options.normalized) {
-        const n = Array.from(graph.nodes()).length;
-        if (n > 1) {
-            centrality = centrality / (n - 1);
-        }
-    }
-
     return centrality;
 }
 
 /**
- * Single-source shortest path lengths using BFS (for unweighted graphs)
+ * Calculate closeness centrality for all nodes in the graph
+ *
+ * Closeness centrality measures how close a node is to all other nodes
+ * in the graph. It is the reciprocal of the sum of the shortest path
+ * distances to all other reachable nodes.
+ *
+ * @param graph - The input graph
+ * @param options - Algorithm options
+ * @returns Centrality scores for each node
+ *
+ * @example
+ * ```typescript
+ * const graph = new Graph();
+ * graph.addEdge("A", "B");
+ * graph.addEdge("B", "C");
+ *
+ * const centrality = closenessCentrality(graph);
+ * // { A: 0.5, B: 1.0, C: 0.5 }
+ * ```
+ *
+ * Time Complexity: O(V * (V + E)) for unweighted graphs
+ * Space Complexity: O(V)
  */
-function singleSourceShortestPathLengths(
+export function closenessCentrality(
     graph: Graph,
-    source: NodeId,
-    cutoff?: number,
-): Map<NodeId, number> {
-    const distances = new Map<NodeId, number>();
-    const visited = new Set<NodeId>();
-    const queue: {node: NodeId, distance: number}[] = [];
-
-    // Initialize
-    queue.push({node: source, distance: 0});
-    visited.add(source);
-    distances.set(source, 0);
-
-    while (queue.length > 0) {
-        const current = queue.shift();
-        if (!current) {
-            break;
-        }
-
-        // Skip if beyond cutoff
-        if (cutoff !== undefined && current.distance >= cutoff) {
-            continue;
-        }
+    options: ClosenessCentralityOptions = {},
+): Record<string, number> {
+    const nodes = Array.from(graph.nodes()).map((node) => node.id);
+    const centrality: Record<string, number> = {};
 
-        // Explore neighbors
-        for (const neighbor of Array.from(graph.neighbors(current.node))) {
-            if (!visited.has(neighbor)) {
-                const newDistance = current.distance + 1;
+    for (const sourceNode of nodes) {
+        centrality[String(sourceNode)] = nodeClosenessCentrality(graph, sourceNode, options);
+    }
 
-                // Skip if beyond cutoff
-                if (cutoff !== undefined && newDistance > cutoff) {
-                    continue;
-                }
+    return centrality;
+}
 
-                visited.add(neighbor);
-                distances.set(neighbor, newDistance);
-                queue.push({node: neighbor, distance: newDistance});
-            }
-        }
+/**
+ * Calculate closeness centrality for a specific node
+ */
+export function nodeClosenessCentrality(
+    graph: Graph,
+    node: NodeId,
+    options: ClosenessCentralityOptions = {},
+): number {
+    if (!graph.hasNode(node)) {
+        throw new Error(`Node ${String(node)} not found in graph`);
     }
 
-    return distances;
+    // Use optimized BFS variant for unweighted graphs
+    const distances = bfsDistancesOnly(graph, node, options.cutoff, options.optimized !== undefined ? {optimized: options.optimized} : {});
+    const totalNodes = graph.nodeCount;
+
+    return calculateClosenessFromDistances(distances, node, totalNodes, options);
 }
 
 /**
@@ -182,115 +170,9 @@ export function nodeWeightedClosenessCentrality(
         throw new Error(`Node ${String(node)} not found in graph`);
     }
 
-    const distances = dijkstraDistances(graph, node, options.cutoff);
-
-    if (distances.size <= 1) {
-        return 0; // No other nodes reachable
-    }
-
-    let centrality = 0;
-
-    if (options.harmonic) {
-        // Harmonic centrality: sum of reciprocals of distances
-        for (const [targetNode, distance] of Array.from(distances)) {
-            if (targetNode !== node && distance > 0 && distance < Infinity) {
-                centrality += 1 / distance;
-            }
-        }
-    } else {
-        // Standard closeness: reciprocal of sum of distances
-        let totalDistance = 0;
-        let reachableNodes = 0;
-
-        for (const [targetNode, distance] of Array.from(distances)) {
-            if (targetNode !== node && distance < Infinity) {
-                totalDistance += distance;
-                reachableNodes++;
-            }
-        }
-
-        if (totalDistance > 0) {
-            centrality = 1 / totalDistance;
-
-            // Wasserman and Faust normalization for disconnected graphs
-            if (options.normalized) {
-                const n = Array.from(graph.nodes()).length;
-                centrality = centrality * reachableNodes / (n - 1);
-            }
-        }
-    }
-
-    // Normalization for harmonic centrality
-    if (options.harmonic && options.normalized) {
-        const n = Array.from(graph.nodes()).length;
-        if (n > 1) {
-            centrality = centrality / (n - 1);
-        }
-    }
-
-    return centrality;
-}
-
-/**
- * Single-source shortest path distances using Dijkstra's algorithm
- */
-function dijkstraDistances(
-    graph: Graph,
-    source: NodeId,
-    cutoff?: number,
-): Map<NodeId, number> {
-    const distances = new Map<NodeId, number>();
-    const visited = new Set<NodeId>();
-    const pq: {node: NodeId, distance: number}[] = [];
-
-    // Initialize distances
-    for (const node of Array.from(graph.nodes())) {
-        distances.set(node.id, node.id === source ? 0 : Infinity);
-    }
-
-    pq.push({node: source, distance: 0});
-
-    while (pq.length > 0) {
-        // Simple priority queue (could be optimized with a proper heap)
-        pq.sort((a, b) => a.distance - b.distance);
-        const current = pq.shift();
-
-        if (!current || visited.has(current.node)) {
-            continue;
-        }
-
-        visited.add(current.node);
-
-        // Skip if beyond cutoff
-        if (cutoff !== undefined && current.distance > cutoff) {
-            continue;
-        }
-
-        // Explore neighbors
-        for (const neighbor of Array.from(graph.neighbors(current.node))) {
-            if (visited.has(neighbor)) {
-                continue;
-            }
-
-            const edge = graph.getEdge(current.node, neighbor);
-            if (!edge) {
-                continue;
-            }
-
-            const edgeWeight = edge.weight ?? 1;
-            const tentativeDistance = current.distance + edgeWeight;
-            const currentDistance = distances.get(neighbor) ?? Infinity;
-
-            if (tentativeDistance < currentDistance) {
-                distances.set(neighbor, tentativeDistance);
-
-                // Skip if beyond cutoff
-                if (cutoff === undefined || tentativeDistance <= cutoff) {
-                    pq.push({node: neighbor, distance: tentativeDistance});
-                }
-            }
-        }
-    }
+    // Use optimized weighted BFS variant (simplified Dijkstra)
+    const distances = bfsWeightedDistances(graph, node, options.cutoff, options.optimized !== undefined ? {optimized: options.optimized} : {});
+    const totalNodes = graph.nodeCount;
 
-    return distances;
+    return calculateClosenessFromDistances(distances, node, totalNodes, options);
 }

package/src/algorithms/centrality/degree.ts

@@ -18,10 +18,10 @@ export function degreeCentrality(
     const centrality: CentralityResult = {};
     const {nodeCount} = graph;
 
-    // Calculate normalization factor
-    const maxPossibleDegree = graph.isDirected ? nodeCount - 1 : nodeCount - 1;
+    // Calculate normalization factor (same for both directed and undirected graphs)
+    const maxPossibleDegree = nodeCount - 1;
 
-    for (const node of Array.from(graph.nodes())) {
+    for (const node of graph.nodes()) {
         let degree: number;
 
         if (graph.isDirected && options.mode) {

package/src/algorithms/centrality/delta-pagerank-simple.ts

@@ -0,0 +1,366 @@
+import type {Graph} from "../../core/graph.js";
+import type {NodeId} from "../../types/index.js";
+
+/**
+ * Simplified Delta-based PageRank that matches the standard algorithm
+ * but only processes active nodes for efficiency.
+ *
+ * Key optimization: Supports incremental updates when graph structure changes,
+ * avoiding full recomputation from scratch.
+ */
+export class SimpleDeltaPageRank {
+    private graph: Graph;
+    private nodeCount: number;
+    private previousScores: Map<NodeId, number> | null = null;
+
+    constructor(graph: Graph) {
+        if (!graph.isDirected) {
+            throw new Error("PageRank requires a directed graph");
+        }
+
+        this.graph = graph;
+        this.nodeCount = graph.nodeCount;
+    }
+
+    public compute(options: {
+        dampingFactor?: number;
+        tolerance?: number;
+        maxIterations?: number;
+        personalization?: Map<NodeId, number>;
+        weight?: string;
+    } = {}): Map<NodeId, number> {
+        const {
+            dampingFactor = 0.85,
+            tolerance = 1e-6,
+            maxIterations = 100,
+            personalization,
+            weight,
+        } = options;
+
+        if (this.nodeCount === 0) {
+            return new Map();
+        }
+
+        // Initialize scores
+        const scores = new Map<NodeId, number>();
+        const newScores = new Map<NodeId, number>();
+
+        for (const node of this.graph.nodes()) {
+            scores.set(node.id, 1.0 / this.nodeCount);
+        }
+
+        // Precompute out-degrees and weights
+        const outWeights = new Map<NodeId, number>();
+        const danglingNodes = new Set<NodeId>();
+
+        for (const node of this.graph.nodes()) {
+            let totalWeight = 0;
+            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;
+            }
+
+            outWeights.set(node.id, totalWeight);
+            if (outDegree === 0) {
+                danglingNodes.add(node.id);
+            }
+        }
+
+        // Normalize personalization vector if provided
+        let personalVector: Map<NodeId, number> | null = null;
+        if (personalization) {
+            personalVector = new Map(personalization);
+            this.normalizeMap(personalVector);
+        }
+
+        // Power iteration with active node tracking
+        let activeNodes = new Set<NodeId>(scores.keys());
+        let iteration = 0;
+
+        for (iteration = 0; iteration < maxIterations; iteration++) {
+            // Initialize new scores
+            for (const nodeId of scores.keys()) {
+                if (personalVector) {
+                    newScores.set(nodeId, (1 - dampingFactor) * (personalVector.get(nodeId) ?? 0));
+                } else {
+                    newScores.set(nodeId, (1 - dampingFactor) / this.nodeCount);
+                }
+            }
+
+            // Handle dangling nodes
+            let danglingSum = 0;
+            for (const danglingNode of danglingNodes) {
+                danglingSum += scores.get(danglingNode) ?? 0;
+            }
+
+            if (danglingSum > 0) {
+                const danglingContribution = dampingFactor * danglingSum / this.nodeCount;
+                for (const nodeId of scores.keys()) {
+                    const current = newScores.get(nodeId) ?? 0;
+                    if (personalVector) {
+                        const personalContrib = danglingContribution * (personalVector.get(nodeId) ?? 0);
+                        newScores.set(nodeId, current + personalContrib);
+                    } else {
+                        newScores.set(nodeId, current + danglingContribution);
+                    }
+                }
+            }
+
+            // Propagate rank from active nodes only
+            for (const nodeId of activeNodes) {
+                const currentRank = scores.get(nodeId) ?? 0;
+                const nodeOutWeight = outWeights.get(nodeId) ?? 0;
+
+                if (nodeOutWeight > 0) {
+                    for (const neighbor of Array.from(this.graph.neighbors(nodeId))) {
+                        let edgeWeight = 1;
+                        if (weight) {
+                            const edge = this.graph.getEdge(nodeId, neighbor);
+                            edgeWeight = edge?.weight ?? 1;
+                        }
+
+                        const contribution = dampingFactor * currentRank * (edgeWeight / nodeOutWeight);
+                        const neighborRank = newScores.get(neighbor) ?? 0;
+                        newScores.set(neighbor, neighborRank + contribution);
+                    }
+                }
+            }
+
+            // Check convergence and identify active nodes
+            const nextActive = new Set<NodeId>();
+            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);
+
+                // Mark as active if change is significant
+                if (diff > tolerance / 10) {
+                    nextActive.add(nodeId);
+                    // Also mark neighbors as potentially active
+                    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);
+                    }
+                }
+            }
+
+            // Swap score maps
+            scores.clear();
+            for (const [k, v] of newScores) {
+                scores.set(k, v);
+            }
+            newScores.clear();
+
+            activeNodes = nextActive;
+
+            if (maxDiff < tolerance) {
+                break;
+            }
+        }
+
+        // Store scores for potential incremental updates
+        this.previousScores = new Map(scores);
+
+        return scores;
+    }
+
+    /**
+     * Perform incremental update after graph modification.
+     * This is where delta-based approach provides significant speedup.
+     *
+     * @param modifiedNodes Set of nodes that were modified (edges added/removed)
+     * @param options Computation options
+     * @returns Updated PageRank scores
+     */
+    public update(
+        modifiedNodes: Set<NodeId>,
+        options: {
+            dampingFactor?: number;
+            tolerance?: number;
+            maxIterations?: number;
+            personalization?: Map<NodeId, number>;
+            weight?: string;
+        } = {},
+    ): Map<NodeId, number> {
+        if (!this.previousScores) {
+            // No previous computation, do full compute
+            return this.compute(options);
+        }
+
+        const {
+            dampingFactor = 0.85,
+            tolerance = 1e-6,
+            maxIterations = 100,
+            personalization,
+            weight,
+        } = options;
+
+        // Initialize scores from previous computation
+        const scores = new Map(this.previousScores);
+        const newScores = new Map<NodeId, number>();
+
+        // Ensure all current nodes are included
+        for (const node of this.graph.nodes()) {
+            if (!scores.has(node.id)) {
+                scores.set(node.id, 1.0 / this.nodeCount);
+            }
+        }
+
+        // Start with only modified nodes and their neighbors as active
+        let activeNodes = new Set<NodeId>();
+        for (const nodeId of modifiedNodes) {
+            activeNodes.add(nodeId);
+            // Add incoming neighbors
+            for (const neighbor of Array.from(this.graph.inNeighbors(nodeId))) {
+                activeNodes.add(neighbor);
+            }
+            // Add outgoing neighbors
+            for (const neighbor of Array.from(this.graph.neighbors(nodeId))) {
+                activeNodes.add(neighbor);
+            }
+        }
+
+        // Recompute out-weights for modified nodes
+        const outWeights = new Map<NodeId, number>();
+        const danglingNodes = new Set<NodeId>();
+
+        for (const node of this.graph.nodes()) {
+            let totalWeight = 0;
+            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;
+            }
+
+            outWeights.set(node.id, totalWeight);
+            if (outDegree === 0) {
+                danglingNodes.add(node.id);
+            }
+        }
+
+        // Normalize personalization vector if provided
+        let personalVector: Map<NodeId, number> | null = null;
+        if (personalization) {
+            personalVector = new Map(personalization);
+            this.normalizeMap(personalVector);
+        }
+
+        // Run limited iterations focusing on active nodes
+        let iteration = 0;
+
+        for (iteration = 0; iteration < maxIterations && activeNodes.size > 0; iteration++) {
+            // Initialize new scores
+            for (const nodeId of scores.keys()) {
+                if (personalVector) {
+                    newScores.set(nodeId, (1 - dampingFactor) * (personalVector.get(nodeId) ?? 0));
+                } else {
+                    newScores.set(nodeId, (1 - dampingFactor) / this.nodeCount);
+                }
+            }
+
+            // Handle dangling nodes
+            let danglingSum = 0;
+            for (const danglingNode of danglingNodes) {
+                danglingSum += scores.get(danglingNode) ?? 0;
+            }
+
+            if (danglingSum > 0) {
+                const danglingContribution = dampingFactor * danglingSum / this.nodeCount;
+                for (const nodeId of scores.keys()) {
+                    const current = newScores.get(nodeId) ?? 0;
+                    if (personalVector) {
+                        const personalContrib = danglingContribution * (personalVector.get(nodeId) ?? 0);
+                        newScores.set(nodeId, current + personalContrib);
+                    } else {
+                        newScores.set(nodeId, current + danglingContribution);
+                    }
+                }
+            }
+
+            // Propagate rank from ALL nodes (not just active)
+            // This ensures correctness
+            for (const nodeId of scores.keys()) {
+                const currentRank = scores.get(nodeId) ?? 0;
+                const nodeOutWeight = outWeights.get(nodeId) ?? 0;
+
+                if (nodeOutWeight > 0) {
+                    for (const neighbor of Array.from(this.graph.neighbors(nodeId))) {
+                        let edgeWeight = 1;
+                        if (weight) {
+                            const edge = this.graph.getEdge(nodeId, neighbor);
+                            edgeWeight = edge?.weight ?? 1;
+                        }
+
+                        const contribution = dampingFactor * currentRank * (edgeWeight / nodeOutWeight);
+                        const neighborRank = newScores.get(neighbor) ?? 0;
+                        newScores.set(neighbor, neighborRank + contribution);
+                    }
+                }
+            }
+
+            // Check convergence only for active nodes
+            const nextActive = new Set<NodeId>();
+            let maxDiff = 0;
+
+            for (const nodeId of activeNodes) {
+                const oldRank = scores.get(nodeId) ?? 0;
+                const newRank = newScores.get(nodeId) ?? 0;
+                const diff = Math.abs(newRank - oldRank);
+                maxDiff = Math.max(maxDiff, diff);
+
+                // Mark as active if change is significant
+                if (diff > tolerance / 10) {
+                    nextActive.add(nodeId);
+                    // Also mark neighbors as potentially active
+                    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);
+                    }
+                }
+            }
+
+            // Swap score maps
+            scores.clear();
+            for (const [k, v] of newScores) {
+                scores.set(k, v);
+            }
+            newScores.clear();
+
+            activeNodes = nextActive;
+
+            if (maxDiff < tolerance) {
+                break;
+            }
+        }
+
+        // Store scores for future incremental updates
+        this.previousScores = new Map(scores);
+
+        return scores;
+    }
+
+    private normalizeMap(map: Map<NodeId, number>): void {
+        let sum = 0;
+        for (const value of map.values()) {
+            sum += value;
+        }
+
+        if (sum > 0) {
+            for (const [key, value] of Array.from(map)) {
+                map.set(key, value / sum);
+            }
+        }
+    }
+}