@graphty/algorithms 2.1.1 → 2.2.0

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

@@ -1,6 +1,9 @@
-import { Graph } from "../../core/graph.js";
-import type { CommunityResult, ComponentResult, GirvanNewmanOptions, NodeId } from "../../types/index.js";
-import { connectedComponents } from "../components/connected.js";
+import type { Graph } from "../../core/graph.js";
+import { labelsToGroups } from "../../indexed/facade.js";
+import { girvanNewman as indexedGirvanNewman } from "../../indexed/girvan-newman.js";
+import { needsLegacyCode, toSnapshot } from "../../indexed/to-snapshot.js";
+import type { CommunityResult, GirvanNewmanOptions } from "../../types/index.js";
+import { girvanNewman as legacyGirvanNewman } from "./girvan-newman-legacy.js";
 
 /**
  * Girvan-Newman community detection algorithm
@@ -10,399 +13,46 @@ import { connectedComponents } from "../components/connected.js";
  * splits into disconnected components.
  *
  * This is a divisive hierarchical clustering algorithm that produces a
- * dendrogram of community structures.
+ * dendrogram of community structures. It delegates to `indexed.girvanNewman`; the result equals
+ * the pre-migration implementation in `girvan-newman-legacy.ts`.
  *
  * 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.
- * @param graph - The input graph
+ * @param graph - The input graph (must be undirected)
  * @param options - Algorithm options
  * @returns Array of community detection results representing the dendrogram
+ * @throws Error on a directed graph
  */
 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 = graph.clone();
-    let iterations = 0;
-
-    // Initial state: one large component
-    let components = getConnectedComponentsResult(workingGraph);
-    dendrogram.push({
-        communities: components.components.filter((community) => community.length >= minCommunitySize),
-        modularity: calculateModularity(graph, components.componentMap),
-    });
-
-    while (Array.from(workingGraph.edges()).length > 0 && iterations < maxIterations) {
-        iterations++;
-        // Calculate edge betweenness centrality
-        const { betweenness: edgeBetweenness, edgeEndpoints } = calculateEdgeBetweenness(workingGraph);
-
-        if (edgeBetweenness.size === 0) {
-            break;
-        }
-
-        // Find edges with maximum betweenness
-        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) {
-                // Use original edge endpoints to preserve node ID types (number vs string)
-                const endpoints = edgeEndpoints.get(edgeKey);
-                if (endpoints) {
-                    edgesToRemove.push(endpoints);
-                }
-            }
-        }
-
-        // Remove edges with highest betweenness
-        for (const { source, target } of edgesToRemove) {
-            workingGraph.removeEdge(source, target);
-        }
-
-        // Find new connected components (communities)
-        components = getConnectedComponentsResult(workingGraph);
-
-        // Filter communities by minimum size
-        const validCommunities = components.components.filter((community) => community.length >= minCommunitySize);
-
-        // Calculate modularity for the new community structure
-        const modularity = calculateModularity(graph, components.componentMap);
-
-        dendrogram.push({
-            communities: validCommunities,
-            modularity,
-        });
-
-        // Stop if desired number of communities reached
-        if (maxCommunities && validCommunities.length >= maxCommunities) {
-            break;
-        }
-
-        // Stop if no more meaningful communities can be formed
-        if (validCommunities.length === workingGraph.nodeCount) {
-            break;
-        }
-    }
-
-    return dendrogram;
-}
-
-/**
- * Edge betweenness result containing centrality values and original edge endpoints
- */
-interface EdgeBetweennessResult {
-    betweenness: Map<string, number>;
-    edgeEndpoints: Map<string, { source: NodeId; target: NodeId }>;
-}
-
-/**
- * Calculate edge betweenness centrality for all edges in the graph
- *
- * 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 Object with betweenness map and edge endpoints map (preserving original ID types)
- */
-function calculateEdgeBetweenness(graph: Graph): EdgeBetweennessResult {
-    const edgeBetweenness = new Map<string, number>();
-    const edgeEndpoints = new Map<string, { source: NodeId; target: NodeId }>();
-
-    // Initialize all edges with 0 betweenness and store original endpoints
-    for (const edge of graph.edges()) {
-        const edgeKey = getEdgeKey(edge.source, edge.target);
-        edgeBetweenness.set(edgeKey, 0);
-        edgeEndpoints.set(edgeKey, { source: edge.source, target: edge.target });
-    }
-
-    // For each node as source, calculate shortest paths and accumulate edge betweenness
-    for (const sourceNode of graph.nodes()) {
-        const source = sourceNode.id;
-
-        // Run BFS to find all shortest paths from source
-        const { distances, predecessors, pathCounts } = findAllShortestPaths(graph, source);
-
-        // Calculate dependency for each node and accumulate edge betweenness
-        const dependency = new Map<NodeId, number>();
-
-        // Initialize dependency
-        for (const node of graph.nodes()) {
-            dependency.set(node.id, 0);
-        }
-
-        // Process nodes in order of decreasing distance
-        const sortedNodes = Array.from(distances.keys())
-            .filter((node) => {
-                const distance = distances.get(node);
-                return distance !== undefined && distance < Infinity;
-            })
-            .sort((a, b) => {
-                const distanceA = distances.get(a);
-                const distanceB = distances.get(b);
-                if (distanceA === undefined || distanceB === undefined) {
-                    return 0;
-                }
-
-                return distanceB - distanceA;
-            });
-
-        for (const node of sortedNodes) {
-            if (node === source) {
-                continue;
-            }
-
-            const nodeDependency = dependency.get(node);
-            const nodePathCount = pathCounts.get(node);
-
-            if (nodeDependency === undefined || nodePathCount === undefined) {
-                continue;
-            }
-
-            // Distribute dependency to predecessors
-            const nodePredecessors = predecessors.get(node) ?? [];
-            for (const predecessor of nodePredecessors) {
-                const predPathCount = pathCounts.get(predecessor);
-                if (predPathCount === undefined) {
-                    continue;
-                }
-
-                const edgeDependency = (predPathCount / nodePathCount) * (1 + nodeDependency);
-
-                // Update predecessor dependency
-                const currentDependency = dependency.get(predecessor);
-                if (currentDependency !== undefined) {
-                    dependency.set(predecessor, currentDependency + edgeDependency);
-                }
-
-                // Update edge betweenness
-                const edgeKey = getEdgeKey(predecessor, node);
-                const currentBetweenness = edgeBetweenness.get(edgeKey) ?? 0;
-                edgeBetweenness.set(edgeKey, currentBetweenness + edgeDependency);
-            }
-        }
+    // A directed graph throws from the old code's component step. A self-loop counts once in the
+    // old modularity's node degree and twice in the port's; ids spelled alike share the old code's
+    // edge keys.
+    if (graph.isDirected || needsLegacyCode(graph)) {
+        return legacyGirvanNewman(graph, options);
     }
-
-    // Normalize: divide by 2 for undirected graphs (each edge counted twice)
-    if (!graph.isDirected) {
-        for (const [edgeKey, betweenness] of edgeBetweenness) {
-            edgeBetweenness.set(edgeKey, betweenness / 2);
-        }
+    const s = toSnapshot(graph);
+    if (s.flags.hasSelfLoops) {
+        return legacyGirvanNewman(graph, options);
     }
-
-    return { betweenness: edgeBetweenness, edgeEndpoints };
-}
-
-/**
- * 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,
-): {
-    distances: Map<NodeId, number>;
-    predecessors: Map<NodeId, NodeId[]>;
-    pathCounts: Map<NodeId, number>;
-} {
-    const distances = new Map<NodeId, number>();
-    const predecessors = new Map<NodeId, NodeId[]>();
-    const pathCounts = new Map<NodeId, number>();
-    const queue: NodeId[] = [];
-    const visited = new Set<NodeId>();
-
-    // Only initialize for reachable nodes
-    distances.set(source, 0);
-    predecessors.set(source, []);
-    pathCounts.set(source, 1);
-    queue.push(source);
-
-    // Optimized BFS with early termination
-    let queueIndex = 0;
-    while (queueIndex < queue.length) {
-        const current = queue[queueIndex++];
-        if (current === undefined) {
-            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)) {
-            // 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);
-                predecessors.set(neighbor, [current]);
-                const currentPathCount = pathCounts.get(current);
-                if (currentPathCount !== undefined) {
-                    pathCounts.set(neighbor, currentPathCount);
-                }
-
-                queue.push(neighbor);
-            } else if (newDistance === neighborDistance) {
-                // Found alternative shortest path
-                const neighborPredecessors = predecessors.get(neighbor);
-                if (neighborPredecessors) {
-                    neighborPredecessors.push(current);
-                    const currentPathCount = pathCounts.get(current);
-                    if (currentPathCount !== undefined) {
-                        pathCounts.set(neighbor, (pathCounts.get(neighbor) ?? 0) + currentPathCount);
-                    }
-                }
-            }
-        }
-    }
-
-    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
-    const sourceStr = String(source);
-    const targetStr = String(target);
-
-    if (sourceStr <= targetStr) {
-        return `${sourceStr}|${targetStr}`;
-    }
-
-    return `${targetStr}|${sourceStr}`;
-}
-
-/**
- * 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
- */
-function calculateModularity(graph: Graph, communityMap: Map<NodeId, number>): number {
-    const totalEdgeWeight = getTotalEdgeWeight(graph);
-    if (totalEdgeWeight === 0) {
-        return 0;
-    }
-
-    // Summed weighted degree of each community's nodes.
-    const degreeSum = new Map<number, number>();
-    for (const node of graph.nodes()) {
-        const community = communityMap.get(node.id);
-        if (community === undefined) {
-            continue;
-        }
-
-        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 = communityMap.get(edge.source);
-        const communityJ = communityMap.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 - share * share;
-    }
-
-    return modularity;
-}
-
-/**
- * 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;
-
-    for (const edge of graph.edges()) {
-        totalWeight += edge.weight ?? 1;
-    }
-
-    return totalWeight;
-}
-
-/**
- * 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;
-
-    for (const neighbor of graph.neighbors(nodeId)) {
-        const edge = graph.getEdge(nodeId, neighbor);
-        degree += edge?.weight ?? 1;
-    }
-
-    return degree;
-}
-
-/**
- * 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);
-    const componentMap = new Map<NodeId, number>();
-
-    components.forEach((component, index) => {
-        component.forEach((nodeId) => {
-            componentMap.set(nodeId, index);
-        });
+    const minCommunitySize = options.minCommunitySize ?? 1;
+    let { maxCommunities, maxIterations } = options;
+    // The old code stopped after the first round on any truthy maxCommunities it had reached, which
+    // a negative one always has; the port ignores a count below 1.
+    if (maxCommunities !== undefined && maxCommunities < 0) {
+        maxCommunities = undefined;
+        maxIterations = Math.min(maxIterations ?? 100, 1);
+    }
+    const r = indexedGirvanNewman(s, { maxCommunities, minCommunitySize, maxIterations });
+    return r.levels.map((labels, i) => {
+        let count = 0;
+        for (const label of labels) {
+            count = Math.max(count, label + 1);
+        }
+        return {
+            communities: labelsToGroups(s.ids, labels, count).filter((c) => c.length >= minCommunitySize),
+            modularity: r.modularity[i],
+        };
     });
-
-    return { components, componentMap };
 }

package/src/algorithms/community/label-propagation.ts

@@ -10,6 +10,8 @@
  */
 
 import type { Graph } from "../../core/graph.js";
+import { labelPropagation as indexedLabelPropagation } from "../../indexed/label-propagation.js";
+import { toSnapshot } from "../../indexed/to-snapshot.js";
 import { graphToMap } from "../../utils/graph-converters.js";
 import { SeededRandom, shuffle } from "../../utils/math-utilities.js";
 
@@ -24,130 +26,6 @@ export interface LabelPropagationResult {
     converged: boolean;
 }
 
-/**
- * Internal implementation of Label Propagation Algorithm
- * @param graph - Map representation of the graph (node to neighbors with weights)
- * @param options - Algorithm configuration options
- * @returns Community assignments, iteration count, and convergence status
- */
-function labelPropagationImpl(
-    graph: Map<string, Map<string, number>>,
-    options: LabelPropagationOptions = {},
-): LabelPropagationResult {
-    const { maxIterations = 100, randomSeed = 42 } = options;
-
-    if (graph.size === 0) {
-        return {
-            communities: new Map(),
-            iterations: 0,
-            converged: true,
-        };
-    }
-
-    // Initialize random number generator
-    const random = SeededRandom.createGenerator(randomSeed);
-
-    // Initialize labels - each node gets its own label
-    const labels = new Map<string, number>();
-    const nodes = Array.from(graph.keys());
-    nodes.forEach((node, i) => labels.set(node, i));
-
-    let iterations = 0;
-    let converged = false;
-
-    // Main loop
-    while (iterations < maxIterations && !converged) {
-        iterations++;
-        converged = true;
-
-        // Create random order for node updates
-        const nodeOrder = [...nodes];
-        shuffle(nodeOrder, random);
-
-        // Update each node's label
-        for (const node of nodeOrder) {
-            const neighbors = graph.get(node);
-            if (!neighbors || neighbors.size === 0) {
-                continue;
-            }
-
-            // Count label frequencies among neighbors
-            const labelCounts = new Map<number, number>();
-            let maxCount = 0;
-            const candidateLabels: number[] = [];
-
-            for (const [neighbor, weight] of neighbors) {
-                const neighborLabel = labels.get(neighbor);
-                if (neighborLabel === undefined) {
-                    continue;
-                }
-
-                const count = (labelCounts.get(neighborLabel) ?? 0) + weight;
-                labelCounts.set(neighborLabel, count);
-
-                if (count > maxCount) {
-                    maxCount = count;
-                    candidateLabels.length = 0;
-                    candidateLabels.push(neighborLabel);
-                } else if (count === maxCount) {
-                    candidateLabels.push(neighborLabel);
-                }
-            }
-
-            // Choose label (break ties randomly)
-            const currentLabel = labels.get(node);
-            if (currentLabel === undefined) {
-                continue;
-            }
-
-            let newLabel = currentLabel;
-
-            if (candidateLabels.length > 0) {
-                // Include current label if it has max count
-                if (labelCounts.get(currentLabel) === maxCount) {
-                    candidateLabels.push(currentLabel);
-                }
-
-                // Random selection from candidates
-                const index = Math.floor(random() * candidateLabels.length);
-                const selectedLabel = candidateLabels[index];
-                if (selectedLabel !== undefined) {
-                    newLabel = selectedLabel;
-                }
-            }
-
-            // Update label if changed
-            if (newLabel !== currentLabel) {
-                labels.set(node, newLabel);
-                converged = false;
-            }
-        }
-    }
-
-    // Renumber communities consecutively
-    const uniqueLabels = new Set(labels.values());
-    const labelMap = new Map<number, number>();
-    let communityId = 0;
-
-    for (const label of uniqueLabels) {
-        labelMap.set(label, communityId++);
-    }
-
-    const communities = new Map<string, number>();
-    for (const [node, label] of labels) {
-        const mappedLabel = labelMap.get(label);
-        if (mappedLabel !== undefined) {
-            communities.set(node, mappedLabel);
-        }
-    }
-
-    return {
-        communities,
-        iterations,
-        converged,
-    };
-}
-
 /**
  * Internal implementation of Asynchronous Label Propagation
  * Updates all nodes simultaneously (can lead to oscillations)
@@ -366,19 +244,32 @@ function labelPropagationSemiSupervisedImpl(
 }
 
 /**
- * Label Propagation Algorithm
- * Each node adopts the most frequent label among its neighbors
- * @param graph - Undirected graph (can be weighted)
+ * Label Propagation Algorithm (fast label propagation: a seeded work queue of nodes whose label
+ * may no longer be dominant). Each node adopts the label with the largest summed edge weight among
+ * its neighbours, ties drawn uniformly; on a directed graph in- and out-neighbours both vote, and a
+ * self-loop does not vote. Communities are numbered in order of first appearance in node order.
+ * @param graph - The graph (can be weighted)
  * @param options - Algorithm options
- * @returns Community assignments
+ * @returns Community assignments keyed by `String(id)`
+ * @throws RangeError when an edge weight is negative, NaN or infinite
  *
- * Time Complexity: O(m) per iteration, typically O(km) for k iterations
- * Space Complexity: O(n)
+ * Time Complexity: O(m) per full pass, at most maxIterations passes
+ * Space Complexity: O(n + m)
  */
 export function labelPropagation(graph: Graph, options: LabelPropagationOptions = {}): LabelPropagationResult {
-    // Convert Graph to Map representation
-    const graphMap = graphToMap(graph);
-    return labelPropagationImpl(graphMap, options);
+    const s = toSnapshot(graph);
+    const n = s.nodeCount;
+    // This function always took any number: its loop ran while iterations < maxIterations, and any
+    // seed started a stream. The port wants integers, so round here the way that loop counted.
+    const max = options.maxIterations ?? 100;
+    const cap = max > 0 ? Math.min(Math.ceil(max), Math.floor(Number.MAX_SAFE_INTEGER / Math.max(n, 1))) : 0;
+    const seed = options.randomSeed ?? 42;
+    const { labels, iterations, converged } = indexedLabelPropagation(s, {
+        maxIterations: cap,
+        randomSeed: Number.isFinite(seed) ? Math.floor(seed) : 0,
+    });
+    // With no pass run on a non-empty graph, nothing was checked, so nothing converged.
+    return { communities: s.ids.toStringMap(labels), iterations, converged: converged && (cap > 0 || n === 0) };
 }
 
 /**