@graphty/algorithms 1.0.1 → 1.1.0

package/src/algorithms/community/louvain.ts

@@ -0,0 +1,298 @@
+import {Graph} from "../../core/graph.js";
+import type {CommunityResult, LouvainOptions, NodeId} from "../../types/index.js";
+
+/**
+ * Louvain community detection algorithm
+ *
+ * Implements the Louvain method for community detection in graphs.
+ * Uses modularity optimization to find community structure.
+ *
+ * References:
+ * - Blondel, V. D., Guillaume, J. L., Lambiotte, R., & Lefebvre, E. (2008).
+ *   Fast unfolding of communities in large networks.
+ *   Journal of statistical mechanics: theory and experiment, 2008(10), P10008.
+ *
+ * @param graph - The input graph
+ * @param options - Algorithm options
+ * @returns Community detection result with communities, modularity, and iterations
+ */
+export function louvain(
+    graph: Graph,
+    options: LouvainOptions = {},
+): CommunityResult {
+    const resolution = options.resolution ?? 1.0;
+    const maxIterations = options.maxIterations ?? 100;
+    const tolerance = options.tolerance ?? 1e-6;
+
+    // Initialize: each node in its own community
+    const communities = initializeCommunities(graph);
+    let modularity = calculateModularity(graph, communities, resolution);
+    let iteration = 0;
+    let improved = true;
+
+    while (iteration < maxIterations && improved) {
+        // Phase 1: Local optimization
+        improved = louvainPhase1(graph, communities, resolution);
+
+        if (improved) {
+            const newModularity = calculateModularity(graph, communities, resolution);
+
+            // Check for convergence
+            if ((newModularity - modularity) < tolerance) {
+                break;
+            }
+
+            modularity = newModularity;
+            iteration++;
+        }
+    }
+
+    return {
+        communities: extractCommunities(communities),
+        modularity: calculateModularity(graph, communities, resolution),
+        iterations: iteration,
+    };
+}
+
+/**
+ * Initialize communities: each node in its own community
+ */
+function initializeCommunities(graph: Graph): Map<NodeId, number> {
+    const communities = new Map<NodeId, number>();
+    let communityId = 0;
+
+    for (const node of graph.nodes()) {
+        communities.set(node.id, communityId++);
+    }
+
+    return communities;
+}
+
+/**
+ * Phase 1 of Louvain algorithm: Local optimization
+ * For each node, try moving to neighboring communities and keep the move
+ * that provides the best modularity gain.
+ */
+function louvainPhase1(
+    graph: Graph,
+    communities: Map<NodeId, number>,
+    resolution: number,
+): boolean {
+    let globalImprovement = false;
+    let localImprovement = true;
+
+    while (localImprovement) {
+        localImprovement = false;
+
+        for (const node of graph.nodes()) {
+            const nodeId = node.id;
+            const currentCommunity = communities.get(nodeId);
+
+            if (currentCommunity === undefined) {
+                continue;
+            }
+
+            // Calculate current modularity contribution
+            const currentModularity = nodeModularityContribution(
+                graph, nodeId, currentCommunity, communities, resolution,
+            );
+
+            let bestCommunity = currentCommunity;
+            let bestModularity = currentModularity;
+
+            // Try moving to neighboring communities
+            const neighborCommunities = getNeighborCommunities(graph, nodeId, communities);
+
+            for (const neighborCommunity of neighborCommunities) {
+                if (neighborCommunity === currentCommunity) {
+                    continue;
+                }
+
+                const newModularity = nodeModularityContribution(
+                    graph, nodeId, neighborCommunity, communities, resolution,
+                );
+
+                if (newModularity > bestModularity) {
+                    bestModularity = newModularity;
+                    bestCommunity = neighborCommunity;
+                }
+            }
+
+            // Move node if improvement found
+            if (bestCommunity !== currentCommunity) {
+                communities.set(nodeId, bestCommunity);
+                localImprovement = true;
+                globalImprovement = true;
+            }
+        }
+    }
+
+    return globalImprovement;
+}
+
+/**
+ * Calculate modularity contribution of a node to a specific community
+ */
+function nodeModularityContribution(
+    graph: Graph,
+    nodeId: NodeId,
+    community: number,
+    communities: Map<NodeId, number>,
+    resolution: number,
+): number {
+    const totalEdgeWeight = getTotalEdgeWeight(graph);
+    if (totalEdgeWeight === 0) {
+        return 0;
+    }
+
+    let internalLinks = 0;
+    let nodeDegree = 0;
+    let communityDegree = 0;
+
+    // Calculate node's connections to the community
+    for (const neighbor of graph.neighbors(nodeId)) {
+        const edge = graph.getEdge(nodeId, neighbor);
+        const weight = edge?.weight ?? 1;
+        nodeDegree += weight;
+
+        if (communities.get(neighbor) === community) {
+            internalLinks += weight;
+        }
+    }
+
+    // Calculate total degree of the community (excluding the node if it's currently in it)
+    for (const [otherNodeId, otherCommunity] of communities) {
+        if (otherCommunity === community && otherNodeId !== nodeId) {
+            communityDegree += getNodeDegree(graph, otherNodeId);
+        }
+    }
+
+    // Modularity formula: Q = (1/2m) * Σ[A_ij - (k_i * k_j)/(2m)] * δ(c_i, c_j)
+    const modularityIncrease = (internalLinks - ((resolution * nodeDegree * communityDegree) / (2 * totalEdgeWeight))) / totalEdgeWeight;
+
+    return modularityIncrease;
+}
+
+/**
+ * Get communities of neighboring nodes
+ */
+function getNeighborCommunities(
+    graph: Graph,
+    nodeId: NodeId,
+    communities: Map<NodeId, number>,
+): Set<number> {
+    const neighborCommunities = new Set<number>();
+
+    for (const neighbor of graph.neighbors(nodeId)) {
+        const community = communities.get(neighbor);
+        if (community !== undefined) {
+            neighborCommunities.add(community);
+        }
+    }
+
+    return neighborCommunities;
+}
+
+/**
+ * Calculate total modularity of the current community assignment
+ */
+function calculateModularity(
+    graph: Graph,
+    communities: Map<NodeId, number>,
+    resolution: number,
+): number {
+    const totalEdgeWeight = getTotalEdgeWeight(graph);
+    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<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));
+            }
+        }
+    }
+
+    return modularity / (2 * totalEdgeWeight);
+}
+
+/**
+ * Extract final community structure
+ */
+function extractCommunities(communities: Map<NodeId, number>): NodeId[][] {
+    const communityMap = new Map<number, NodeId[]>();
+
+    for (const [nodeId, community] of communities) {
+        if (!communityMap.has(community)) {
+            communityMap.set(community, []);
+        }
+
+        const communityNodes = communityMap.get(community);
+        if (communityNodes) {
+            communityNodes.push(nodeId);
+        }
+    }
+
+    return Array.from(communityMap.values());
+}
+
+/**
+ * Calculate total edge weight in the graph
+ */
+function getTotalEdgeWeight(graph: Graph): number {
+    let totalWeight = 0;
+
+    for (const edge of graph.edges()) {
+        totalWeight += edge.weight ?? 1;
+    }
+
+    return totalWeight;
+}
+
+/**
+ * Get the total degree (sum of edge weights) for a node
+ */
+function getNodeDegree(graph: Graph, nodeId: NodeId): number {
+    let degree = 0;
+
+    for (const neighbor of graph.neighbors(nodeId)) {
+        const edge = graph.getEdge(nodeId, neighbor);
+        degree += edge?.weight ?? 1;
+    }
+
+    return degree;
+}

package/src/algorithms/components/connected.ts

@@ -26,7 +26,7 @@ export function connectedComponents(graph: Graph): NodeId[][] {
     const unionFind = new UnionFind(nodes);
 
     // Union connected nodes
-    for (const edge of graph.edges()) {
+    for (const edge of Array.from(graph.edges())) {
         unionFind.union(edge.source, edge.target);
     }
 
@@ -44,7 +44,7 @@ export function connectedComponentsDFS(graph: Graph): NodeId[][] {
     const visited = new Set<NodeId>();
     const components: NodeId[][] = [];
 
-    for (const node of graph.nodes()) {
+    for (const node of Array.from(graph.nodes())) {
         if (!visited.has(node.id)) {
             const component: NodeId[] = [];
             dfsComponent(graph, node.id, visited, component);
@@ -67,7 +67,7 @@ function dfsComponent(
     visited.add(nodeId);
     component.push(nodeId);
 
-    for (const neighbor of graph.neighbors(nodeId)) {
+    for (const neighbor of Array.from(graph.neighbors(nodeId))) {
         if (!visited.has(neighbor)) {
             dfsComponent(graph, neighbor, visited, component);
         }
@@ -148,7 +148,7 @@ export function stronglyConnectedComponents(graph: Graph): NodeId[][] {
         onStack.add(nodeId);
 
         // Consider successors
-        for (const neighbor of graph.neighbors(nodeId)) {
+        for (const neighbor of Array.from(graph.neighbors(nodeId))) {
             if (!indices.has(neighbor)) {
                 // Successor has not yet been visited; recurse on it
                 tarjanSCC(neighbor);
@@ -226,7 +226,7 @@ export function weaklyConnectedComponents(graph: Graph): NodeId[][] {
     const unionFind = new UnionFind(nodes);
 
     // Union nodes connected by edges (ignore direction)
-    for (const edge of graph.edges()) {
+    for (const edge of Array.from(graph.edges())) {
         unionFind.union(edge.source, edge.target);
     }
 
@@ -275,13 +275,13 @@ export function condensationGraph(graph: Graph): {
     // Add edges between components
     const addedEdges = new Set<string>();
 
-    for (const edge of graph.edges()) {
+    for (const edge of Array.from(graph.edges())) {
         const sourceComponent = componentMap.get(edge.source);
         const targetComponent = componentMap.get(edge.target);
 
         if (sourceComponent !== undefined && targetComponent !== undefined &&
             sourceComponent !== targetComponent) {
-            const edgeKey = `${sourceComponent}-${targetComponent}`;
+            const edgeKey = `${String(sourceComponent)}-${String(targetComponent)}`;
 
             if (!addedEdges.has(edgeKey)) {
                 condensedGraph.addEdge(sourceComponent, targetComponent);

package/src/algorithms/index.ts

@@ -13,3 +13,24 @@ export * from "./centrality/index.js";
 
 // Connected components algorithms
 export * from "./components/index.js";
+
+// Minimum spanning tree algorithms
+export * from "./mst/index.js";
+
+// Community detection algorithms
+export * from "./community/index.js";
+
+// Pathfinding algorithms
+export * from "../pathfinding/index.js";
+
+// Flow algorithms
+export * from "../flow/index.js";
+
+// Clustering algorithms
+export * from "../clustering/index.js";
+
+// Matching algorithms
+export * from "./matching/index.js";
+
+// Link prediction algorithms
+export * from "../link-prediction/index.js";

package/src/algorithms/matching/bipartite.ts

@@ -0,0 +1,179 @@
+import type {Graph} from "../../core/graph.js";
+import type {NodeId} from "../../types/index.js";
+
+/**
+ * Maximum Bipartite Matching implementation using Hopcroft-Karp algorithm
+ *
+ * Finds the maximum matching in a bipartite graph. A matching is a set of edges
+ * without common vertices. Maximum matching has the largest possible number of edges.
+ *
+ * Time complexity: O(√V × E)
+ * Space complexity: O(V)
+ */
+
+export interface BipartiteMatchingResult {
+    matching: Map<NodeId, NodeId>; // Maps left nodes to right nodes
+    size: number; // Number of matched pairs
+}
+
+export interface BipartiteMatchingOptions {
+    leftNodes?: Set<NodeId>; // Optional: specify left partition
+    rightNodes?: Set<NodeId>; // Optional: specify right partition
+}
+
+/**
+ * Find maximum matching in a bipartite graph using augmenting path algorithm
+ * (simplified implementation that's more reliable than Hopcroft-Karp for this context)
+ */
+export function maximumBipartiteMatching(
+    graph: Graph,
+    options: BipartiteMatchingOptions = {},
+): BipartiteMatchingResult {
+    // If partitions not provided, try to infer them
+    let {leftNodes, rightNodes} = options;
+
+    if (!leftNodes || !rightNodes) {
+        const partition = bipartitePartition(graph);
+        if (!partition) {
+            throw new Error("Graph is not bipartite");
+        }
+
+        leftNodes = partition.left;
+        rightNodes = partition.right;
+    }
+
+    const matching = new Map<NodeId, NodeId>();
+    const matchRight = new Map<NodeId, NodeId>(); // Right to left matching
+
+    // Find augmenting paths using DFS
+    const visited = new Set<NodeId>();
+
+    const dfs = (u: NodeId): boolean => {
+        const neighbors = Array.from(graph.neighbors(u));
+
+        for (const v of neighbors) {
+            if (!rightNodes.has(v) || visited.has(v)) {
+                continue;
+            }
+
+            visited.add(v);
+
+            // If v is unmatched or we can find augmenting path from match of v
+            const matchedNode = matchRight.get(v);
+            if (!matchRight.has(v) || (matchedNode !== undefined && dfs(matchedNode))) {
+                matching.set(u, v);
+                matchRight.set(v, u);
+                return true;
+            }
+        }
+        return false;
+    };
+
+    // Try to find augmenting path for each left node
+    let matchingSize = 0;
+    for (const u of leftNodes) {
+        visited.clear();
+        if (dfs(u)) {
+            matchingSize++;
+        }
+    }
+
+    return {
+        matching,
+        size: matchingSize,
+    };
+}
+
+/**
+ * Check if graph is bipartite and return the partition
+ */
+export function bipartitePartition(graph: Graph): {left: Set<NodeId>, right: Set<NodeId>} | null {
+    const color = new Map<NodeId, boolean>();
+    const left = new Set<NodeId>();
+    const right = new Set<NodeId>();
+
+    const nodes = Array.from(graph.nodes());
+
+    for (const startNode of nodes) {
+        if (color.has(startNode.id)) {
+            continue;
+        }
+
+        // BFS to color the component
+        const queue = [startNode.id];
+        color.set(startNode.id, true);
+        left.add(startNode.id);
+
+        while (queue.length > 0) {
+            const u = queue.shift();
+            if (u === undefined) {
+                continue;
+            }
+
+            const uColor = color.get(u);
+            if (uColor === undefined) {
+                continue;
+            }
+
+            const neighbors = Array.from(graph.neighbors(u));
+            for (const v of neighbors) {
+                if (!color.has(v)) {
+                    color.set(v, !uColor);
+                    if (!uColor) {
+                        left.add(v);
+                    } else {
+                        right.add(v);
+                    }
+
+                    queue.push(v);
+                } else if (color.get(v) === uColor) {
+                    // Same color as neighbor - not bipartite
+                    return null;
+                }
+            }
+        }
+    }
+
+    return {left, right};
+}
+
+/**
+ * Simple greedy bipartite matching algorithm
+ * Useful for comparison or when Hopcroft-Karp is overkill
+ */
+export function greedyBipartiteMatching(
+    graph: Graph,
+    options: BipartiteMatchingOptions = {},
+): BipartiteMatchingResult {
+    let {leftNodes, rightNodes} = options;
+
+    if (!leftNodes || !rightNodes) {
+        const partition = bipartitePartition(graph);
+        if (!partition) {
+            throw new Error("Graph is not bipartite");
+        }
+
+        leftNodes = partition.left;
+        rightNodes = partition.right;
+    }
+
+    const matching = new Map<NodeId, NodeId>();
+    const matched = new Set<NodeId>();
+
+    for (const u of leftNodes) {
+        const neighbors = Array.from(graph.neighbors(u));
+
+        for (const v of neighbors) {
+            if (rightNodes.has(v) && !matched.has(v)) {
+                matching.set(u, v);
+                matched.add(v);
+                break;
+            }
+        }
+    }
+
+    return {
+        matching,
+        size: matching.size,
+    };
+}

package/src/algorithms/matching/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Graph matching algorithms
+ */
+
+export type {BipartiteMatchingOptions, BipartiteMatchingResult} from "./bipartite.js";
+export {bipartitePartition, greedyBipartiteMatching, maximumBipartiteMatching} from "./bipartite.js";
+export type {IsomorphismOptions, IsomorphismResult} from "./isomorphism.js";
+export {findAllIsomorphisms, isGraphIsomorphic} from "./isomorphism.js";