@graphty/algorithms 1.3.1 → 1.5.0

package/src/research/grsbm.ts

@@ -1,6 +1,6 @@
-import type {Graph} from "../core/graph.js";
-import type {NodeId} from "../types/index.js";
-import {SeededRandom} from "../utils/math-utilities.js";
+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
@@ -80,7 +80,6 @@ export interface ClusterExplanation {
  * community structure by tracking the reasoning behind each split.
  *
  * Based on: "Explainable Community Detection via Hierarchical Spectral Clustering" (2024)
- *
  * @param graph - Input graph to cluster
  * @param config - Configuration options
  * @returns Hierarchical clustering result with explanations
@@ -109,7 +108,7 @@ export function grsbm(graph: Graph, config: GRSBMConfig = {}): GRSBMResult {
 
     // 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 initialModularity = calculateModularity(graph, new Map([...rootMembers].map((id) => [id, 0])));
 
     const root: GRSBMCluster = {
         id: "root",
@@ -133,25 +132,18 @@ export function grsbm(graph: Graph, config: GRSBMConfig = {}): GRSBMResult {
         }
 
         // Check stopping criteria
-        if (currentCluster.depth >= maxDepth ||
-            currentCluster.members.size < minClusterSize * 2) {
+        if (currentCluster.depth >= maxDepth || currentCluster.members.size < minClusterSize * 2) {
             continue;
         }
 
         // Attempt spectral bisection
-        const bisectionResult = spectralBisection(
-            graph,
-            currentCluster,
-            numEigenvectors,
-            tolerance,
-            maxIterations,
-        );
+        const bisectionResult = spectralBisection(graph, currentCluster, numEigenvectors, tolerance, maxIterations);
 
         if (!bisectionResult) {
             continue; // Could not split this cluster
         }
 
-        const {leftMembers, rightMembers, spectralScore, keyNodes, spectralValues, reason} = bisectionResult;
+        const { leftMembers, rightMembers, spectralScore, keyNodes, spectralValues, reason } = bisectionResult;
 
         // Create child clusters
         const leftCluster: GRSBMCluster = {
@@ -183,7 +175,8 @@ export function grsbm(graph: Graph, config: GRSBMConfig = {}): GRSBMResult {
         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
+        if (modularityImprovement >= -0.01) {
+            // Small tolerance for neutral splits
             leftCluster.modularity = newModularity;
             rightCluster.modularity = newModularity;
 
@@ -245,11 +238,17 @@ export function grsbm(graph: Graph, config: GRSBMConfig = {}): GRSBMResult {
 
 /**
  * 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,
+    _numEigenvectors: number,
     tolerance: number,
     maxIterations: number,
 ): {
@@ -278,9 +277,7 @@ function spectralBisection(
     }
 
     // Find optimal split point
-    const sortedIndices = eigenvector
-        .map((value, index) => ({value, index}))
-        .sort((a, b) => a.value - b.value);
+    const sortedIndices = eigenvector.map((value, index) => ({ value, index })).sort((a, b) => a.value - b.value);
 
     let bestSplitIndex = Math.floor(n / 2);
     let bestModularity = -Infinity;
@@ -335,7 +332,7 @@ function spectralBisection(
 
     // 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 sortedValues = [...eigenvector].sort((a, b) => Math.abs(b) - Math.abs(a));
     const threshold = sortedValues[Math.floor(sortedValues.length * extremeThreshold)] ?? 0;
 
     const keyNodes: NodeId[] = [];
@@ -369,6 +366,9 @@ function spectralBisection(
 
 /**
  * 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;
@@ -383,7 +383,7 @@ function createLaplacianMatrix(graph: Graph, nodes: NodeId[]): number[][] {
     }
 
     // Initialize Laplacian matrix
-    const laplacian = Array.from({length: n}, () => new Array<number>(n).fill(0));
+    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);
@@ -420,6 +420,10 @@ function createLaplacianMatrix(graph: Graph, nodes: NodeId[]): number[][] {
 
 /**
  * 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;
@@ -443,7 +447,7 @@ function computeFiedlerVector(laplacian: number[][], tolerance: number, maxItera
     }
 
     // Normalize
-    const norm = Math.sqrt(vector.reduce((sum: number, val: number) => sum + (val * val), 0));
+    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];
@@ -494,7 +498,7 @@ function computeFiedlerVector(laplacian: number[][], tolerance: number, maxItera
         }
 
         // Normalize
-        const newNorm = Math.sqrt(newVector.reduce((sum, val) => sum + (val * val), 0));
+        const newNorm = Math.sqrt(newVector.reduce((sum, val) => sum + val * val, 0));
         if (newNorm < tolerance) {
             break; // Converged to zero vector
         }
@@ -528,6 +532,9 @@ function computeFiedlerVector(laplacian: number[][], tolerance: number, maxItera
 
 /**
  * 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;
@@ -577,4 +584,3 @@ function calculateModularity(graph: Graph, assignment: Map<NodeId, number>): num
 
     return modularity;
 }
-

package/src/research/index.ts

@@ -7,11 +7,11 @@
  */
 
 // Synergistic Deep Graph Clustering
-export {syncClustering, type SynCConfig, type SynCResult} from "./sync.js";
+export { syncClustering, type SynCConfig, type SynCResult } from "./sync.js";
 
 // TeraHAC - Hierarchical Agglomerative Clustering
-export {teraHAC, type TeraHACConfig, type TeraHACResult} from "./terahac.js";
-export {type ClusterNode as TeraHACClusterNode} from "./terahac.js";
+export { teraHAC, type TeraHACConfig, type TeraHACResult } from "./terahac.js";
+export { type ClusterNode as TeraHACClusterNode } from "./terahac.js";
 
 // GRSBM - Greedy Recursive Spectral Bisection with Modularity
-export {type ClusterExplanation, grsbm, type GRSBMCluster, type GRSBMConfig, type GRSBMResult} from "./grsbm.js";
+export { type ClusterExplanation, grsbm, type GRSBMCluster, type GRSBMConfig, type GRSBMResult } from "./grsbm.js";

package/src/research/sync.ts

@@ -1,6 +1,6 @@
-import type {Graph} from "../core/graph.js";
-import type {NodeId} from "../types/index.js";
-import {euclideanDistance, SeededRandom} from "../utils/math-utilities.js";
+import type { Graph } from "../core/graph.js";
+import type { NodeId } from "../types/index.js";
+import { euclideanDistance, SeededRandom } from "../utils/math-utilities.js";
 
 /**
  * Configuration options for the SynC (Synergistic Deep Graph Clustering) algorithm
@@ -44,20 +44,12 @@ export interface SynCResult {
  * embeddings and cluster assignments while preserving graph structure.
  *
  * Based on: "Synergistic Deep Graph Clustering" (arXiv:2406.15797, June 2024)
- *
  * @param graph - Input graph to cluster
  * @param config - Configuration options
  * @returns Clustering result with assignments and embeddings
  */
 export function syncClustering(graph: Graph, config: SynCConfig): SynCResult {
-    const {
-        numClusters,
-        maxIterations = 100,
-        tolerance = 1e-6,
-        seed = 42,
-        learningRate = 0.01,
-        lambda = 0.1,
-    } = config;
+    const { numClusters, maxIterations = 100, tolerance = 1e-6, seed = 42, learningRate = 0.01, lambda = 0.1 } = config;
 
     // Set random seed for reproducibility (save original)
     const originalRandom = Math.random;
@@ -78,7 +70,9 @@ export function syncClustering(graph: Graph, config: SynCConfig): SynCResult {
     }
 
     if (numClusters <= 0 || numClusters > nodeCount) {
-        throw new Error(`Invalid number of clusters: ${String(numClusters)}. Must be between 1 and ${String(nodeCount)}`);
+        throw new Error(
+            `Invalid number of clusters: ${String(numClusters)}. Must be between 1 and ${String(nodeCount)}`,
+        );
     }
 
     // Initialize node embeddings (simplified version using graph features)
@@ -184,6 +178,10 @@ export function syncClustering(graph: Graph, config: SynCConfig): SynCResult {
 
 /**
  * Initialize node embedding based on graph structure and features
+ * @param graph - The input graph
+ * @param nodeId - The node ID to initialize embedding for
+ * @param dim - The embedding dimension
+ * @returns The initialized embedding vector
  */
 function initializeNodeEmbedding(graph: Graph, nodeId: NodeId, dim: number): number[] {
     const embedding = new Array<number>(dim).fill(0);
@@ -194,7 +192,7 @@ function initializeNodeEmbedding(graph: Graph, nodeId: NodeId, dim: number): num
 
     // Initialize with small random values influenced by graph structure
     for (let i = 0; i < dim; i++) {
-        embedding[i] = ((Math.random() - 0.5) * 0.1) + (normalizedDegree * 0.1);
+        embedding[i] = (Math.random() - 0.5) * 0.1 + normalizedDegree * 0.1;
     }
 
     return embedding;
@@ -202,6 +200,9 @@ function initializeNodeEmbedding(graph: Graph, nodeId: NodeId, dim: number): num
 
 /**
  * Initialize cluster centers using k-means++ style initialization
+ * @param embeddings - Map of node IDs to embedding vectors
+ * @param numClusters - Number of cluster centers to initialize
+ * @returns Array of initialized cluster center vectors
  */
 function initializeClusterCenters(embeddings: Map<NodeId, number[]>, numClusters: number): number[][] {
     const embeddingArray = Array.from(embeddings.values());
@@ -210,7 +211,7 @@ function initializeClusterCenters(embeddings: Map<NodeId, number[]>, numClusters
     // Choose first center randomly
     const firstCenter = embeddingArray[Math.floor(Math.random() * embeddingArray.length)];
     if (firstCenter) {
-        centers.push([... firstCenter] as number[]);
+        centers.push([...firstCenter] as number[]);
     }
 
     // Choose remaining centers using k-means++ initialization
@@ -239,7 +240,7 @@ function initializeClusterCenters(embeddings: Map<NodeId, number[]>, numClusters
             if (randomValue <= 0) {
                 const newCenter = embeddingArray[i];
                 if (newCenter) {
-                    centers.push([... newCenter] as number[]);
+                    centers.push([...newCenter] as number[]);
                 }
 
                 break;
@@ -252,11 +253,16 @@ function initializeClusterCenters(embeddings: Map<NodeId, number[]>, numClusters
 
 /**
  * Update node embeddings using gradient descent
+ * @param graph - The input graph
+ * @param embeddings - Map of node IDs to embedding vectors
+ * @param _clusters - Map of node IDs to cluster assignments (reserved for future use)
+ * @param learningRate - Learning rate for gradient descent
+ * @param lambda - Regularization parameter
  */
 function updateEmbeddings(
     graph: Graph,
     embeddings: Map<NodeId, number[]>,
-    clusters: Map<NodeId, number>,
+    _clusters: Map<NodeId, number>,
     learningRate: number,
     lambda: number,
 ): void {
@@ -293,7 +299,7 @@ function updateEmbeddings(
                 const gradVal = gradient[i];
                 const diffVal = diff[i];
                 if (gradVal !== undefined && diffVal !== undefined) {
-                    gradient[i] = gradVal + (lambda * diffVal);
+                    gradient[i] = gradVal + lambda * diffVal;
                 }
             }
         }
@@ -303,7 +309,7 @@ function updateEmbeddings(
             const gradVal = gradient[i];
             const nodeVal = nodeEmbedding[i];
             if (gradVal !== undefined && nodeVal !== undefined) {
-                gradient[i] = gradVal + (lambda * nodeVal);
+                gradient[i] = gradVal + lambda * nodeVal;
             }
         }
     }
@@ -319,7 +325,7 @@ function updateEmbeddings(
             const embVal = embedding[i];
             const gradVal = gradient[i];
             if (embVal !== undefined && gradVal !== undefined) {
-                embedding[i] = embVal - (learningRate * gradVal);
+                embedding[i] = embVal - learningRate * gradVal;
             }
         }
     }
@@ -327,6 +333,10 @@ function updateEmbeddings(
 
 /**
  * Update cluster centers based on current assignments
+ * @param embeddings - Map of node IDs to embedding vectors
+ * @param clusters - Map of node IDs to cluster assignments
+ * @param clusterCenters - Array of cluster center vectors to update
+ * @param numClusters - Number of clusters
  */
 function updateClusterCenters(
     embeddings: Map<NodeId, number[]>,
@@ -335,8 +345,9 @@ function updateClusterCenters(
     numClusters: number,
 ): void {
     const dimensions = clusterCenters[0]?.length ?? 0;
-    const clusterSums: number[][] = Array.from({length: numClusters}, () =>
-        new Array(dimensions).fill(0) as number[],
+    const clusterSums: number[][] = Array.from(
+        { length: numClusters },
+        () => new Array(dimensions).fill(0) as number[],
     );
     const clusterCounts = new Array<number>(numClusters).fill(0);
 
@@ -382,6 +393,12 @@ function updateClusterCenters(
 
 /**
  * Calculate the total loss function
+ * @param graph - The input graph
+ * @param embeddings - Map of node IDs to embedding vectors
+ * @param clusters - Map of node IDs to cluster assignments
+ * @param clusterCenters - Array of cluster center vectors
+ * @param lambda - Regularization parameter
+ * @returns The total loss value
  */
 function calculateLoss(
     graph: Graph,
@@ -435,6 +452,5 @@ function calculateLoss(
         }
     }
 
-    return clusteringLoss + (lambda * reconstructionLoss) + (lambda * regularizationLoss);
+    return clusteringLoss + lambda * reconstructionLoss + lambda * regularizationLoss;
 }
-

package/src/research/terahac.ts

@@ -1,5 +1,5 @@
-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";
 
 /**
  * Configuration options for the TeraHAC (Hierarchical Agglomerative Clustering) algorithm
@@ -60,7 +60,6 @@ export interface TeraHACResult {
  *
  * Based on: "Scaling Hierarchical Agglomerative Clustering to Trillion-Edge Graphs"
  * Google Research 2024
- *
  * @param graph - Input graph to cluster
  * @param config - Configuration options
  * @returns Hierarchical clustering result
@@ -88,7 +87,9 @@ export function teraHAC(graph: Graph, config: TeraHACConfig = {}): TeraHACResult
     }
 
     if (nodeCount > maxNodes) {
-        onWarning(`Graph has ${String(nodeCount)} nodes, which exceeds maxNodes (${String(maxNodes)}). Performance may be degraded.`);
+        onWarning(
+            `Graph has ${String(nodeCount)} nodes, which exceeds maxNodes (${String(maxNodes)}). Performance may be degraded.`,
+        );
     }
 
     // Initialize each node as its own cluster
@@ -122,7 +123,7 @@ export function teraHAC(graph: Graph, config: TeraHACConfig = {}): TeraHACResult
     // Perform agglomerative clustering
     while (clusters.size > 1 && mergeCandidates.length > 0) {
         // Find closest pair of clusters
-        const {cluster1Id, cluster2Id, distance} = findClosestPair(mergeCandidates);
+        const { cluster1Id, cluster2Id, distance } = findClosestPair(mergeCandidates);
 
         // Check stopping criteria
         if (numClusters && clusters.size <= numClusters) {
@@ -142,7 +143,7 @@ export function teraHAC(graph: Graph, config: TeraHACConfig = {}): TeraHACResult
 
         // Create new merged cluster
         const newClusterId = (nextClusterId++).toString();
-        const mergedMembers = new Set([... cluster1.members, ... cluster2.members]);
+        const mergedMembers = new Set([...cluster1.members, ...cluster2.members]);
 
         const newCluster: ClusterNode = {
             id: newClusterId,
@@ -182,7 +183,7 @@ export function teraHAC(graph: Graph, config: TeraHACConfig = {}): TeraHACResult
 
                 const newRoot: ClusterNode = {
                     id: (nextClusterId++).toString(),
-                    members: new Set([... root.members, ... currentCluster.members]),
+                    members: new Set([...root.members, ...currentCluster.members]),
                     left: root,
                     right: currentCluster,
                     distance: Infinity,
@@ -216,10 +217,14 @@ export function teraHAC(graph: Graph, config: TeraHACConfig = {}): TeraHACResult
 
 /**
  * Calculate distance matrix between all pairs of nodes
+ * @param graph - The input graph
+ * @param nodes - Array of nodes to calculate distances between
+ * @param useGraphDistance - Whether to use graph-based shortest path distances
+ * @returns 2D distance matrix
  */
-function calculateDistanceMatrix(graph: Graph, nodes: {id: NodeId}[], useGraphDistance: boolean): number[][] {
+function calculateDistanceMatrix(graph: Graph, nodes: { id: NodeId }[], useGraphDistance: boolean): number[][] {
     const n = nodes.length;
-    const matrix: number[][] = Array.from({length: n}, () => new Array(n).fill(Infinity) as number[]);
+    const matrix: number[][] = Array.from({ length: n }, () => new Array(n).fill(Infinity) as number[]);
 
     if (useGraphDistance) {
         // Use graph-based distances (shortest path)
@@ -286,6 +291,9 @@ function calculateDistanceMatrix(graph: Graph, nodes: {id: NodeId}[], useGraphDi
 
 /**
  * BFS-based shortest path calculation from a source node
+ * @param graph - The input graph
+ * @param source - The source node ID
+ * @returns Map of node IDs to their distances from the source
  */
 function bfsShortestPaths(graph: Graph, source: NodeId): Map<NodeId, number> {
     const distances = new Map<NodeId, number>();
@@ -317,12 +325,15 @@ function bfsShortestPaths(graph: Graph, source: NodeId): Map<NodeId, number> {
 
 /**
  * Initialize merge candidates priority queue
+ * @param clusters - Map of cluster IDs to cluster nodes
+ * @param distanceMatrix - 2D distance matrix between nodes
+ * @returns Array of merge candidates sorted by distance
  */
 function initializeMergeCandidates(
     clusters: Map<string, ClusterNode>,
     distanceMatrix: number[][],
-): {cluster1Id: string, cluster2Id: string, distance: number}[] {
-    const candidates: {cluster1Id: string, cluster2Id: string, distance: number}[] = [];
+): { cluster1Id: string; cluster2Id: string; distance: number }[] {
+    const candidates: { cluster1Id: string; cluster2Id: string; distance: number }[] = [];
     const clusterIds = Array.from(clusters.keys());
 
     for (let i = 0; i < clusterIds.length; i++) {
@@ -355,10 +366,14 @@ function initializeMergeCandidates(
 
 /**
  * Find the closest pair of clusters
+ * @param mergeCandidates - Array of merge candidates
+ * @returns The closest cluster pair with their distance
  */
-function findClosestPair(
-    mergeCandidates: {cluster1Id: string, cluster2Id: string, distance: number}[],
-): {cluster1Id: string, cluster2Id: string, distance: number} {
+function findClosestPair(mergeCandidates: { cluster1Id: string; cluster2Id: string; distance: number }[]): {
+    cluster1Id: string;
+    cluster2Id: string;
+    distance: number;
+} {
     // Return the first (closest) valid candidate
     const candidate = mergeCandidates.shift();
     if (!candidate) {
@@ -370,9 +385,16 @@ function findClosestPair(
 
 /**
  * Update merge candidates after a merge operation
+ * @param mergeCandidates - Array of merge candidates to update
+ * @param oldCluster1Id - ID of first merged cluster
+ * @param oldCluster2Id - ID of second merged cluster
+ * @param newClusterId - ID of the newly created cluster
+ * @param clusters - Map of cluster IDs to cluster nodes
+ * @param distanceMatrix - 2D distance matrix between nodes
+ * @param linkage - Linkage criterion to use
  */
 function updateMergeCandidates(
-    mergeCandidates: {cluster1Id: string, cluster2Id: string, distance: number}[],
+    mergeCandidates: { cluster1Id: string; cluster2Id: string; distance: number }[],
     oldCluster1Id: string,
     oldCluster2Id: string,
     newClusterId: string,
@@ -387,8 +409,12 @@ function updateMergeCandidates(
             continue;
         }
 
-        if (candidate.cluster1Id === oldCluster1Id || candidate.cluster1Id === oldCluster2Id ||
-            candidate.cluster2Id === oldCluster1Id || candidate.cluster2Id === oldCluster2Id) {
+        if (
+            candidate.cluster1Id === oldCluster1Id ||
+            candidate.cluster1Id === oldCluster2Id ||
+            candidate.cluster2Id === oldCluster1Id ||
+            candidate.cluster2Id === oldCluster2Id
+        ) {
             mergeCandidates.splice(i, 1);
         }
     }
@@ -416,6 +442,11 @@ function updateMergeCandidates(
 
 /**
  * Calculate distance between two clusters based on linkage criterion
+ * @param cluster1 - First cluster
+ * @param cluster2 - Second cluster
+ * @param distanceMatrix - 2D distance matrix between nodes
+ * @param linkage - Linkage criterion (single, complete, average, ward)
+ * @returns The distance between the two clusters
  */
 function calculateClusterDistance(
     cluster1: ClusterNode,
@@ -451,14 +482,14 @@ function calculateClusterDistance(
     // Apply linkage criterion
     switch (linkage) {
         case "single":
-            return Math.min(... distances);
+            return Math.min(...distances);
         case "complete":
-            return Math.max(... distances);
+            return Math.max(...distances);
         case "average":
             return distances.reduce((sum, d) => sum + d, 0) / distances.length;
         case "ward":
             // Simplified Ward linkage (would need cluster centroids for full implementation)
-            return distances.reduce((sum, d) => sum + (d * d), 0) / distances.length;
+            return distances.reduce((sum, d) => sum + d * d, 0) / distances.length;
         default:
             return distances.reduce((sum, d) => sum + d, 0) / distances.length;
     }
@@ -466,6 +497,9 @@ function calculateClusterDistance(
 
 /**
  * Extract flat clustering from dendrogram
+ * @param dendrogram - The root of the dendrogram tree
+ * @param numClusters - The target number of clusters
+ * @returns Map of node IDs to cluster assignments
  */
 function extractFlatClustering(dendrogram: ClusterNode, numClusters: number): Map<NodeId, number> {
     const clusters = new Map<NodeId, number>();