@graphty/algorithms 2.1.1 → 2.2.0

package/src/research/grsbm.ts

@@ -1,76 +1,27 @@
-import type { Graph } from "../core/graph.js";
-import type { NodeId } from "../types/index.js";
-import { SeededRandom } from "../utils/math-utilities.js";
-
 /**
- * Configuration options for the GRSBM (Greedy Recursive Spectral Bisection) algorithm
+ * GRSBM (Greedy Recursive Spectral Bisection with Modularity) over a legacy `Graph`. `grsbm`
+ * delegates to `indexed.grsbm` over an unweighted snapshot of the graph, counting edges as the old
+ * code did, and rebuilds the cluster tree, labels and explanations; the result equals the
+ * pre-migration implementation in `grsbm-legacy.ts` exactly. A graph with a self-loop keeps the old
+ * code: the port counts a self-loop twice in the degree, the old code once. Unlike the old code the
+ * port never replaces `Math.random`.
  */
-export interface GRSBMConfig {
-    /** Maximum depth of recursive bisection */
-    maxDepth?: number;
-    /** Minimum cluster size to continue splitting */
-    minClusterSize?: number;
-    /** Number of eigenvectors to use for spectral embedding */
-    numEigenvectors?: number;
-    /** Convergence tolerance for eigenvalue computation */
-    tolerance?: number;
-    /** Maximum number of power iterations for eigenvalue computation */
-    maxIterations?: number;
-    /** Random seed for reproducibility */
-    seed?: number;
-}
 
-/**
- * Represents a cluster in the hierarchical structure
- */
-export interface GRSBMCluster {
-    /** Unique identifier for this cluster */
-    id: string;
-    /** Node IDs in this cluster */
-    members: Set<NodeId>;
-    /** Left child cluster (if split) */
-    left?: GRSBMCluster;
-    /** Right child cluster (if split) */
-    right?: GRSBMCluster;
-    /** Modularity score of this cluster */
-    modularity: number;
-    /** Depth in the hierarchy */
-    depth: number;
-    /** Spectral embedding quality score */
-    spectralScore: number;
-}
+import { INVALID_INDEX } from "@graphty/graph-format";
 
-/**
- * Result of the GRSBM clustering algorithm
- */
-export interface GRSBMResult {
-    /** Root of the cluster hierarchy */
-    root: GRSBMCluster;
-    /** Flat clustering at leaf level */
-    clusters: Map<NodeId, number>;
-    /** Number of final clusters */
-    numClusters: number;
-    /** Modularity scores for each level */
-    modularityScores: number[];
-    /** Explanation of the clustering structure */
-    explanation: ClusterExplanation[];
-}
+import type { Graph } from "../core/graph.js";
+import { grsbm as indexedGrsbm } from "../indexed/grsbm.js";
+import { toTopologySnapshot } from "../indexed/to-snapshot.js";
+import type { NodeId } from "../types/index.js";
+import {
+    type ClusterExplanation,
+    grsbm as legacyGrsbm,
+    type GRSBMCluster,
+    type GRSBMConfig,
+    type GRSBMResult,
+} from "./grsbm-legacy.js";
 
-/**
- * Explanation for a cluster split decision
- */
-export interface ClusterExplanation {
-    /** Cluster that was split */
-    clusterId: string;
-    /** Reason for the split */
-    reason: string;
-    /** Modularity improvement from the split */
-    modularityImprovement: number;
-    /** Key nodes that influenced the split */
-    keyNodes: NodeId[];
-    /** Spectral embedding values */
-    spectralValues: number[];
-}
+export type { ClusterExplanation, GRSBMCluster, GRSBMConfig, GRSBMResult } from "./grsbm-legacy.js";
 
 /**
  * GRSBM - Greedy Recursive Spectral Bisection with Modularity
@@ -85,502 +36,72 @@ export interface ClusterExplanation {
  * @returns Hierarchical clustering result with explanations
  */
 export function grsbm(graph: Graph, config: GRSBMConfig = {}): GRSBMResult {
-    const {
-        maxDepth = 10,
-        minClusterSize = 2, // Reduced default to allow more splits
-        numEigenvectors = 2,
-        tolerance = 1e-6,
-        maxIterations = 100,
-        seed = 42,
-    } = config;
-
-    // Set random seed for reproducibility
-    const rng = SeededRandom.createGenerator(seed);
-    const originalRandom = Math.random;
-    Math.random = rng;
-
-    const nodes = Array.from(graph.nodes());
-    const nodeCount = nodes.length;
-
-    if (nodeCount === 0) {
-        throw new Error("Cannot cluster empty graph");
-    }
-
-    // Initialize root cluster with all nodes
-    const rootMembers = new Set(nodes.map((node) => node.id));
-    const initialModularity = calculateModularity(graph, new Map([...rootMembers].map((id) => [id, 0])));
-
-    const root: GRSBMCluster = {
-        id: "root",
-        members: rootMembers,
-        modularity: initialModularity,
-        depth: 0,
-        spectralScore: 0,
-    };
-
-    const explanations: ClusterExplanation[] = [];
-    const modularityScores: number[] = [initialModularity];
-
-    // Perform recursive bisection
-    const clusterQueue: GRSBMCluster[] = [root];
-    let nextClusterId = 1;
-
-    while (clusterQueue.length > 0) {
-        const currentCluster = clusterQueue.shift();
-        if (!currentCluster) {
-            continue;
-        }
-
-        // Check stopping criteria
-        if (currentCluster.depth >= maxDepth || currentCluster.members.size < minClusterSize * 2) {
-            continue;
-        }
-
-        // Attempt spectral bisection
-        const bisectionResult = spectralBisection(graph, currentCluster, numEigenvectors, tolerance, maxIterations);
-
-        if (!bisectionResult) {
-            continue; // Could not split this cluster
-        }
-
-        const { leftMembers, rightMembers, spectralScore, keyNodes, spectralValues, reason } = bisectionResult;
-
-        // Create child clusters
-        const leftCluster: GRSBMCluster = {
-            id: `cluster_${String(nextClusterId++)}`,
-            members: leftMembers,
-            modularity: 0, // Will be calculated below
-            depth: currentCluster.depth + 1,
-            spectralScore,
+    const s = toTopologySnapshot(graph);
+    if (s.selfLoopCount > 0) {
+        return legacyGrsbm(graph, config);
+    }
+    // numEigenvectors was never read by the old code either.
+    const { maxDepth, minClusterSize, tolerance, maxIterations, seed } = config;
+    const r = indexedGrsbm(s, { maxDepth, minClusterSize, tolerance, maxIterations, seed, weighted: false });
+    const idOf = (i: number): NodeId => s.ids.idOf(i);
+    const name = (serial: number): string => (serial === 0 ? "root" : `cluster_${String(serial)}`);
+
+    const build = (c: number): GRSBMCluster => {
+        const cluster = r.clusters[c];
+        const out: GRSBMCluster = {
+            id: name(cluster.serial),
+            members: new Set(Array.from(cluster.members, idOf)),
+            modularity: cluster.modularity,
+            depth: cluster.depth,
+            spectralScore: cluster.spectralScore,
         };
-
-        const rightCluster: GRSBMCluster = {
-            id: `cluster_${String(nextClusterId++)}`,
-            members: rightMembers,
-            modularity: 0, // Will be calculated below
-            depth: currentCluster.depth + 1,
-            spectralScore,
-        };
-
-        // Calculate modularity improvement
-        const newAssignment = new Map<NodeId, number>();
-        for (const nodeId of leftMembers) {
-            newAssignment.set(nodeId, 0);
-        }
-        for (const nodeId of rightMembers) {
-            newAssignment.set(nodeId, 1);
-        }
-
-        const newModularity = calculateModularity(graph, newAssignment);
-        const modularityImprovement = newModularity - currentCluster.modularity;
-
-        // Only split if modularity improves or is neutral (allow small splits)
-        if (modularityImprovement >= -0.01) {
-            // Small tolerance for neutral splits
-            leftCluster.modularity = newModularity;
-            rightCluster.modularity = newModularity;
-
-            currentCluster.left = leftCluster;
-            currentCluster.right = rightCluster;
-
-            // Add explanation
-            explanations.push({
-                clusterId: currentCluster.id,
-                reason,
-                modularityImprovement,
-                keyNodes,
-                spectralValues,
-            });
-
-            modularityScores.push(newModularity);
-
-            // Add children to queue for further processing
-            clusterQueue.push(leftCluster, rightCluster);
+        if (cluster.left !== INVALID_INDEX) {
+            out.left = build(cluster.left);
+            out.right = build(cluster.right);
         }
-    }
+        return out;
+    };
 
-    // Extract flat clustering from leaf nodes
+    // The old labels number the leaves left to right, an emptied leaf included.
     const clusters = new Map<NodeId, number>();
-    let clusterId = 0;
-
-    function assignClusterIds(cluster: GRSBMCluster): void {
-        if (!cluster.left && !cluster.right) {
-            // Leaf node
-            for (const nodeId of cluster.members) {
-                clusters.set(nodeId, clusterId);
+    let leaves = 0;
+    const walk = (c: number): void => {
+        const cluster = r.clusters[c];
+        if (cluster.left === INVALID_INDEX) {
+            for (const i of cluster.members) {
+                clusters.set(idOf(i), leaves);
             }
-            clusterId++;
+            leaves++;
         } else {
-            // Internal node - traverse children
-            if (cluster.left) {
-                assignClusterIds(cluster.left);
-            }
-
-            if (cluster.right) {
-                assignClusterIds(cluster.right);
-            }
+            walk(cluster.left);
+            walk(cluster.right);
         }
-    }
-
-    assignClusterIds(root);
-
-    // Restore original random function
-    Math.random = originalRandom;
-
-    return {
-        root,
-        clusters,
-        numClusters: clusterId,
-        modularityScores,
-        explanation: explanations,
     };
-}
-
-/**
- * Perform spectral bisection on a cluster
- * @param graph - The input graph
- * @param cluster - The cluster to bisect
- * @param _numEigenvectors - Number of eigenvectors to compute (reserved for future use)
- * @param tolerance - Convergence tolerance
- * @param maxIterations - Maximum number of iterations
- * @returns Bisection result with left/right members, scores, and explanation, or null if bisection failed
- */
-function spectralBisection(
-    graph: Graph,
-    cluster: GRSBMCluster,
-    _numEigenvectors: number,
-    tolerance: number,
-    maxIterations: number,
-): {
-    leftMembers: Set<NodeId>;
-    rightMembers: Set<NodeId>;
-    spectralScore: number;
-    keyNodes: NodeId[];
-    spectralValues: number[];
-    reason: string;
-} | null {
-    const members = Array.from(cluster.members);
-    const n = members.length;
-
-    if (n < 4) {
-        return null; // Too small to split meaningfully
-    }
-
-    // Create subgraph Laplacian matrix
-    const laplacian = createLaplacianMatrix(graph, members);
-
-    // Compute the second smallest eigenvector (Fiedler vector)
-    const eigenvector = computeFiedlerVector(laplacian, tolerance, maxIterations);
-
-    if (!eigenvector) {
-        return null; // Could not compute eigenvector
-    }
-
-    // Find optimal split point
-    const sortedIndices = eigenvector.map((value, index) => ({ value, index })).sort((a, b) => a.value - b.value);
-
-    let bestSplitIndex = Math.floor(n / 2);
-    let bestModularity = -Infinity;
-
-    // Try different split points
-    for (let splitIndex = Math.floor(n * 0.2); splitIndex <= Math.floor(n * 0.8); splitIndex++) {
-        const leftIndices = sortedIndices.slice(0, splitIndex).map((item) => item.index);
-        const rightIndices = sortedIndices.slice(splitIndex).map((item) => item.index);
-
-        const assignment = new Map<NodeId, number>();
-        for (const idx of leftIndices) {
-            const nodeId = members[idx];
-            if (nodeId !== undefined) {
-                assignment.set(nodeId, 0);
-            }
-        }
-        for (const idx of rightIndices) {
-            const nodeId = members[idx];
-            if (nodeId !== undefined) {
-                assignment.set(nodeId, 1);
-            }
-        }
-
-        const modularity = calculateModularity(graph, assignment);
-
-        if (modularity > bestModularity) {
-            bestModularity = modularity;
-            bestSplitIndex = splitIndex;
-        }
-    }
-
-    // Create final split
-    const leftIndices = sortedIndices.slice(0, bestSplitIndex).map((item) => item.index);
-    const rightIndices = sortedIndices.slice(bestSplitIndex).map((item) => item.index);
-
-    const leftMembers = new Set<NodeId>();
-    const rightMembers = new Set<NodeId>();
-
-    for (const idx of leftIndices) {
-        const nodeId = members[idx];
-        if (nodeId !== undefined) {
-            leftMembers.add(nodeId);
-        }
-    }
-
-    for (const idx of rightIndices) {
-        const nodeId = members[idx];
-        if (nodeId !== undefined) {
-            rightMembers.add(nodeId);
-        }
-    }
-
-    // Identify key nodes (those with extreme spectral values)
-    const extremeThreshold = 0.1;
-    const sortedValues = [...eigenvector].sort((a, b) => Math.abs(b) - Math.abs(a));
-    const threshold = sortedValues[Math.floor(sortedValues.length * extremeThreshold)] ?? 0;
-
-    const keyNodes: NodeId[] = [];
-    for (let i = 0; i < eigenvector.length; i++) {
-        const eigenValue = eigenvector[i];
-        if (eigenValue !== undefined && Math.abs(eigenValue) >= Math.abs(threshold)) {
-            const nodeId = members[i];
-            if (nodeId !== undefined) {
-                keyNodes.push(nodeId);
-            }
-        }
-    }
-
-    // Calculate spectral score (based on eigenvalue gap)
-    const firstValue = sortedValues[0] ?? 0;
-    const lastValue = sortedValues[sortedValues.length - 1] ?? 0;
-    const spectralScore = Math.abs(firstValue - lastValue);
-
-    // Generate explanation
-    const reason = `Spectral bisection based on Fiedler vector with modularity ${bestModularity.toFixed(3)}. Split creates clusters of sizes ${String(leftMembers.size)} and ${String(rightMembers.size)}.`;
+    walk(0);
+
+    const explanation: ClusterExplanation[] = r.clusters.flatMap((cluster) => {
+        const { split } = cluster;
+        if (split === null) {
+            return [];
+        }
+        const left = r.clusters[cluster.left];
+        const right = r.clusters[cluster.right];
+        return [
+            {
+                clusterId: name(cluster.serial),
+                reason: `Spectral bisection based on Fiedler vector with modularity ${split.bisectionModularity.toFixed(3)}. Split creates clusters of sizes ${String(left.members.length)} and ${String(right.members.length)}.`,
+                modularityImprovement: split.improvement,
+                keyNodes: Array.from(split.keyNodes, idOf),
+                spectralValues: Array.from(split.spectralValues),
+            },
+        ];
+    });
 
     return {
-        leftMembers,
-        rightMembers,
-        spectralScore,
-        keyNodes: keyNodes.slice(0, 5), // Top 5 key nodes
-        spectralValues: eigenvector,
-        reason,
+        root: build(0),
+        clusters,
+        numClusters: leaves,
+        modularityScores: Array.from(r.modularityScores),
+        explanation,
     };
 }
-
-/**
- * Create Laplacian matrix for a subgraph
- * @param graph - The input graph
- * @param nodes - The nodes to include in the subgraph
- * @returns The Laplacian matrix as a 2D array
- */
-function createLaplacianMatrix(graph: Graph, nodes: NodeId[]): number[][] {
-    const n = nodes.length;
-    const nodeIndex = new Map<NodeId, number>();
-
-    // Create node index mapping
-    for (let i = 0; i < n; i++) {
-        const node = nodes[i];
-        if (node !== undefined) {
-            nodeIndex.set(node, i);
-        }
-    }
-
-    // Initialize Laplacian matrix
-    const laplacian = Array.from({ length: n }, () => new Array<number>(n).fill(0));
-
-    // Fill adjacency part and calculate degrees
-    const degrees = new Array<number>(n).fill(0);
-
-    for (let i = 0; i < n; i++) {
-        const nodeId = nodes[i];
-        if (nodeId === undefined) {
-            continue;
-        }
-
-        for (const neighbor of graph.neighbors(nodeId)) {
-            const neighborIdx = nodeIndex.get(neighbor);
-            if (neighborIdx !== undefined && i < laplacian.length && i < degrees.length) {
-                const row = laplacian[i];
-                if (row) {
-                    row[neighborIdx] = -1;
-                    degrees[i] = (degrees[i] ?? 0) + 1;
-                }
-            }
-        }
-    }
-
-    // Set diagonal (degree) values
-    for (let i = 0; i < n; i++) {
-        const row = laplacian[i];
-        const degree = degrees[i];
-        if (row && degree !== undefined) {
-            row[i] = degree;
-        }
-    }
-
-    return laplacian;
-}
-
-/**
- * Compute the Fiedler vector (second smallest eigenvector) using power iteration
- * @param laplacian - The Laplacian matrix
- * @param tolerance - Convergence tolerance
- * @param maxIterations - Maximum number of iterations
- * @returns The Fiedler vector, or null if computation failed
- */
-function computeFiedlerVector(laplacian: number[][], tolerance: number, maxIterations: number): number[] | null {
-    const n = laplacian.length;
-    if (n < 2) {
-        return null;
-    }
-
-    // Initialize random vector orthogonal to the all-ones vector
-    let vector = new Array<number>(n).fill(0);
-    for (let i = 0; i < n; i++) {
-        vector[i] = Math.random() - 0.5;
-    }
-
-    // Make orthogonal to all-ones vector
-    const mean = vector.reduce((sum: number, val: number) => sum + val, 0) / n;
-    for (let i = 0; i < n; i++) {
-        const val = vector[i];
-        if (val !== undefined) {
-            vector[i] = val - mean;
-        }
-    }
-
-    // Normalize
-    const norm = Math.sqrt(vector.reduce((sum: number, val: number) => sum + val * val, 0));
-    if (norm > 0) {
-        for (let i = 0; i < n; i++) {
-            const val = vector[i];
-            if (val !== undefined) {
-                vector[i] = val / norm;
-            }
-        }
-    }
-
-    // Power iteration with deflation for second smallest eigenvalue
-    for (let iter = 0; iter < maxIterations; iter++) {
-        const newVector = new Array<number>(n).fill(0);
-
-        // Matrix-vector multiplication: newVector = L * vector
-        for (let i = 0; i < n; i++) {
-            let sum = 0;
-            const row = laplacian[i];
-            if (row) {
-                for (let j = 0; j < n; j++) {
-                    const matrixVal = row[j];
-                    const vectorVal = vector[j];
-                    if (matrixVal !== undefined && vectorVal !== undefined) {
-                        sum += matrixVal * vectorVal;
-                    }
-                }
-            }
-
-            newVector[i] = sum;
-        }
-
-        // For smallest eigenvalue, we actually want inverse iteration
-        // This is simplified - in practice would solve (L - shift*I)x = vector
-        // For now, use power iteration on -L (approximately)
-        for (let i = 0; i < n; i++) {
-            const val = newVector[i];
-            if (val !== undefined) {
-                newVector[i] = -val;
-            }
-        }
-
-        // Orthogonalize against all-ones vector
-        const newMean = newVector.reduce((sum, val) => sum + val, 0) / n;
-        for (let i = 0; i < n; i++) {
-            const val = newVector[i];
-            if (val !== undefined) {
-                newVector[i] = val - newMean;
-            }
-        }
-
-        // Normalize
-        const newNorm = Math.sqrt(newVector.reduce((sum, val) => sum + val * val, 0));
-        if (newNorm < tolerance) {
-            break; // Converged to zero vector
-        }
-
-        for (let i = 0; i < n; i++) {
-            const val = newVector[i];
-            if (val !== undefined) {
-                newVector[i] = val / newNorm;
-            }
-        }
-
-        // Check convergence
-        let diff = 0;
-        for (let i = 0; i < n; i++) {
-            const newVal = newVector[i];
-            const oldVal = vector[i];
-            if (newVal !== undefined && oldVal !== undefined) {
-                diff += Math.abs(newVal - oldVal);
-            }
-        }
-
-        vector = newVector;
-
-        if (diff < tolerance) {
-            break;
-        }
-    }
-
-    return vector;
-}
-
-/**
- * Calculate modularity of a graph partitioning
- * @param graph - The input graph
- * @param assignment - Map from node ID to community ID
- * @returns The modularity score
- */
-function calculateModularity(graph: Graph, assignment: Map<NodeId, number>): number {
-    const totalEdges = graph.uniqueEdgeCount;
-    if (totalEdges === 0) {
-        return 0;
-    }
-
-    let modularity = 0;
-    const communities = new Map<number, Set<NodeId>>();
-
-    // Group nodes by community
-    for (const [nodeId, communityId] of assignment) {
-        if (!communities.has(communityId)) {
-            communities.set(communityId, new Set());
-        }
-
-        const community = communities.get(communityId);
-        if (community) {
-            community.add(nodeId);
-        }
-    }
-
-    // Calculate modularity for each community
-    for (const [, members] of communities) {
-        let internalEdges = 0;
-        let totalDegree = 0;
-
-        for (const nodeId of members) {
-            const nodeDegree = graph.degree(nodeId);
-            totalDegree += nodeDegree;
-
-            // Count internal edges
-            for (const neighbor of graph.neighbors(nodeId)) {
-                if (members.has(neighbor)) {
-                    internalEdges++;
-                }
-            }
-        }
-
-        // Each edge is counted twice in undirected graphs
-        internalEdges /= 2;
-
-        // Modularity contribution for this community
-        const expectedEdges = (totalDegree * totalDegree) / (4 * totalEdges);
-        modularity += (internalEdges - expectedEdges) / totalEdges;
-    }
-
-    return modularity;
-}