@graphty/algorithms 1.1.0 → 1.2.0

package/dist/src/research/terahac.js

@@ -0,0 +1,375 @@
+/**
+ * TeraHAC - Hierarchical Agglomerative Clustering for Large Graphs
+ *
+ * This algorithm performs hierarchical clustering on graphs by iteratively
+ * merging the closest clusters. Optimized for scalability to handle large
+ * graphs efficiently.
+ *
+ * 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
+ */
+export function teraHAC(graph, config = {}) {
+    const { linkage = "average", numClusters, distanceThreshold, maxNodes = 10000, useGraphDistance = true, } = config;
+    const nodes = Array.from(graph.nodes());
+    const nodeCount = nodes.length;
+    if (nodeCount === 0) {
+        throw new Error("Cannot cluster empty graph");
+    }
+    if (nodeCount > maxNodes) {
+        console.warn(`Graph has ${String(nodeCount)} nodes, which exceeds maxNodes (${String(maxNodes)}). Performance may be degraded.`);
+    }
+    // Initialize each node as its own cluster
+    const clusters = new Map();
+    let nextClusterId = nodeCount;
+    for (let i = 0; i < nodeCount; i++) {
+        const node = nodes[i];
+        if (!node) {
+            continue;
+        }
+        const clusterId = i.toString();
+        clusters.set(clusterId, {
+            id: clusterId,
+            members: new Set([node.id]),
+            distance: 0,
+            size: 1,
+        });
+    }
+    // Calculate initial distance matrix
+    const distanceMatrix = calculateDistanceMatrix(graph, nodes, useGraphDistance);
+    const mergeDistances = [];
+    // Priority queue for efficient nearest neighbor finding
+    const mergeCandidates = initializeMergeCandidates(clusters, distanceMatrix);
+    let dendrogram;
+    // Perform agglomerative clustering
+    while (clusters.size > 1) {
+        // Find closest pair of clusters
+        const { cluster1Id, cluster2Id, distance } = findClosestPair(mergeCandidates);
+        // Check stopping criteria
+        if (numClusters && clusters.size <= numClusters) {
+            break;
+        }
+        if (distanceThreshold && distance > distanceThreshold) {
+            break;
+        }
+        // Get the two clusters to merge
+        const cluster1 = clusters.get(cluster1Id);
+        const cluster2 = clusters.get(cluster2Id);
+        if (!cluster1 || !cluster2) {
+            continue;
+        }
+        // Create new merged cluster
+        const newClusterId = (nextClusterId++).toString();
+        const mergedMembers = new Set([...cluster1.members, ...cluster2.members]);
+        const newCluster = {
+            id: newClusterId,
+            members: mergedMembers,
+            left: cluster1,
+            right: cluster2,
+            distance,
+            size: cluster1.size + cluster2.size,
+        };
+        // Remove old clusters
+        clusters.delete(cluster1Id);
+        clusters.delete(cluster2Id);
+        // Add new cluster
+        clusters.set(newClusterId, newCluster);
+        mergeDistances.push(distance);
+        // Update merge candidates
+        updateMergeCandidates(mergeCandidates, cluster1Id, cluster2Id, newClusterId, clusters, distanceMatrix, linkage);
+        dendrogram = newCluster;
+    }
+    // If we have multiple remaining clusters, create a virtual root
+    if (clusters.size > 1) {
+        const remainingClusters = Array.from(clusters.values());
+        let root = remainingClusters[0];
+        if (!root) {
+            dendrogram = undefined;
+        }
+        else {
+            for (let i = 1; i < remainingClusters.length; i++) {
+                const currentCluster = remainingClusters[i];
+                if (!currentCluster) {
+                    continue;
+                }
+                const newRoot = {
+                    id: (nextClusterId++).toString(),
+                    members: new Set([...root.members, ...currentCluster.members]),
+                    left: root,
+                    right: currentCluster,
+                    distance: Infinity,
+                    size: root.size + currentCluster.size,
+                };
+                root = newRoot;
+            }
+            dendrogram = root;
+        }
+        dendrogram = root;
+    }
+    dendrogram ?? (dendrogram = Array.from(clusters.values())[0]);
+    // Extract flat clustering
+    const finalNumClusters = numClusters ?? clusters.size;
+    const flatClusters = dendrogram ? extractFlatClustering(dendrogram, finalNumClusters) : new Map();
+    if (!dendrogram) {
+        throw new Error("Failed to create dendrogram");
+    }
+    return {
+        dendrogram,
+        clusters: flatClusters,
+        distances: mergeDistances,
+        numClusters: finalNumClusters,
+    };
+}
+/**
+ * Calculate distance matrix between all pairs of nodes
+ */
+function calculateDistanceMatrix(graph, nodes, useGraphDistance) {
+    const n = nodes.length;
+    const matrix = Array.from({ length: n }, () => new Array(n).fill(Infinity));
+    if (useGraphDistance) {
+        // Use graph-based distances (shortest path)
+        for (let i = 0; i < n; i++) {
+            const node = nodes[i];
+            if (!node) {
+                continue;
+            }
+            const distances = bfsShortestPaths(graph, node.id);
+            for (let j = 0; j < n; j++) {
+                if (i !== j) {
+                    const targetNode = nodes[j];
+                    if (targetNode && i < matrix.length && j < n) {
+                        const row = matrix[i];
+                        if (row && j < row.length) {
+                            const distance = distances.get(targetNode.id);
+                            row[j] = distance ?? Infinity;
+                        }
+                    }
+                }
+                else if (i < matrix.length) {
+                    const row = matrix[i];
+                    if (row && j < row.length) {
+                        row[j] = 0;
+                    }
+                }
+            }
+        }
+    }
+    else {
+        // Use simple edge-based distances
+        for (let i = 0; i < n; i++) {
+            for (let j = i + 1; j < n; j++) {
+                const node1 = nodes[i];
+                const node2 = nodes[j];
+                if (node1 && node2) {
+                    const hasEdge = graph.hasEdge(node1.id, node2.id);
+                    const distance = hasEdge ? 1 : 2; // Connected: 1, not connected: 2
+                    if (i < matrix.length) {
+                        const rowI = matrix[i];
+                        if (rowI && j < rowI.length) {
+                            rowI[j] = distance;
+                        }
+                    }
+                    if (j < matrix.length) {
+                        const rowJ = matrix[j];
+                        if (rowJ && i < rowJ.length) {
+                            rowJ[i] = distance;
+                        }
+                    }
+                }
+            }
+            if (i < matrix.length) {
+                const row = matrix[i];
+                if (row && i < row.length) {
+                    row[i] = 0;
+                }
+            }
+        }
+    }
+    return matrix;
+}
+/**
+ * BFS-based shortest path calculation from a source node
+ */
+function bfsShortestPaths(graph, source) {
+    const distances = new Map();
+    const queue = [[source, 0]];
+    const visited = new Set();
+    visited.add(source);
+    distances.set(source, 0);
+    while (queue.length > 0) {
+        const item = queue.shift();
+        if (!item) {
+            break;
+        }
+        const [current, distance] = item;
+        for (const neighbor of graph.neighbors(current)) {
+            if (!visited.has(neighbor)) {
+                visited.add(neighbor);
+                distances.set(neighbor, distance + 1);
+                queue.push([neighbor, distance + 1]);
+            }
+        }
+    }
+    return distances;
+}
+/**
+ * Initialize merge candidates priority queue
+ */
+function initializeMergeCandidates(clusters, distanceMatrix) {
+    const candidates = [];
+    const clusterIds = Array.from(clusters.keys());
+    for (let i = 0; i < clusterIds.length; i++) {
+        for (let j = i + 1; j < clusterIds.length; j++) {
+            const id1 = clusterIds[i];
+            const id2 = clusterIds[j];
+            if (!id1 || !id2) {
+                continue;
+            }
+            const row = distanceMatrix[parseInt(id1)];
+            if (!row) {
+                continue;
+            }
+            const distance = row[parseInt(id2)] ?? Infinity;
+            // Include all candidates, even disconnected ones (with finite but large distance)
+            candidates.push({
+                cluster1Id: id1,
+                cluster2Id: id2,
+                distance: distance === Infinity ? 100 : distance,
+            });
+        }
+    }
+    // Sort by distance (ascending)
+    candidates.sort((a, b) => a.distance - b.distance);
+    return candidates;
+}
+/**
+ * Find the closest pair of clusters
+ */
+function findClosestPair(mergeCandidates) {
+    // Return the first (closest) valid candidate
+    const candidate = mergeCandidates.shift();
+    if (!candidate) {
+        throw new Error("No merge candidates available");
+    }
+    return candidate;
+}
+/**
+ * Update merge candidates after a merge operation
+ */
+function updateMergeCandidates(mergeCandidates, oldCluster1Id, oldCluster2Id, newClusterId, clusters, distanceMatrix, linkage) {
+    // Remove candidates involving the merged clusters
+    for (let i = mergeCandidates.length - 1; i >= 0; i--) {
+        const candidate = mergeCandidates[i];
+        if (!candidate) {
+            continue;
+        }
+        if (candidate.cluster1Id === oldCluster1Id || candidate.cluster1Id === oldCluster2Id ||
+            candidate.cluster2Id === oldCluster1Id || candidate.cluster2Id === oldCluster2Id) {
+            mergeCandidates.splice(i, 1);
+        }
+    }
+    // Add new candidates for the merged cluster
+    const newCluster = clusters.get(newClusterId);
+    if (!newCluster) {
+        return;
+    }
+    for (const [clusterId, cluster] of clusters) {
+        if (clusterId !== newClusterId) {
+            const distance = calculateClusterDistance(newCluster, cluster, distanceMatrix, linkage);
+            mergeCandidates.push({
+                cluster1Id: newClusterId,
+                cluster2Id: clusterId,
+                distance: distance === Infinity ? 100 : distance,
+            });
+        }
+    }
+    // Re-sort candidates
+    mergeCandidates.sort((a, b) => a.distance - b.distance);
+}
+/**
+ * Calculate distance between two clusters based on linkage criterion
+ */
+function calculateClusterDistance(cluster1, cluster2, distanceMatrix, linkage) {
+    const members1 = Array.from(cluster1.members);
+    const members2 = Array.from(cluster2.members);
+    const distances = [];
+    // Calculate all pairwise distances between cluster members
+    for (const member1 of members1) {
+        for (const member2 of members2) {
+            const idx1 = parseInt(member1.toString());
+            const idx2 = parseInt(member2.toString());
+            if (idx1 < distanceMatrix.length && idx2 < distanceMatrix.length) {
+                const row = distanceMatrix[idx1];
+                if (row) {
+                    const distance = row[idx2];
+                    if (distance !== undefined) {
+                        distances.push(distance);
+                    }
+                }
+            }
+        }
+    }
+    if (distances.length === 0) {
+        return Infinity;
+    }
+    // Apply linkage criterion
+    switch (linkage) {
+        case "single":
+            return Math.min(...distances);
+        case "complete":
+            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;
+        default:
+            return distances.reduce((sum, d) => sum + d, 0) / distances.length;
+    }
+}
+/**
+ * Extract flat clustering from dendrogram
+ */
+function extractFlatClustering(dendrogram, numClusters) {
+    const clusters = new Map();
+    if (numClusters === 1) {
+        // Single cluster
+        const clusterId = 0;
+        for (const member of dendrogram.members) {
+            clusters.set(member, clusterId);
+        }
+        return clusters;
+    }
+    // Find clusters at the specified level
+    const clusterNodes = [];
+    const queue = [dendrogram];
+    while (queue.length > 0 && clusterNodes.length < numClusters) {
+        const current = queue.shift();
+        if (!current) {
+            break;
+        }
+        if (!current.left || !current.right || clusterNodes.length + queue.length + 1 >= numClusters) {
+            // This is a leaf or we need to keep this level
+            clusterNodes.push(current);
+        }
+        else {
+            // Continue decomposing
+            queue.push(current.left, current.right);
+        }
+    }
+    // Assign cluster IDs
+    for (let i = 0; i < clusterNodes.length; i++) {
+        const cluster = clusterNodes[i];
+        if (!cluster) {
+            continue;
+        }
+        for (const member of cluster.members) {
+            clusters.set(member, i);
+        }
+    }
+    return clusters;
+}
+//# sourceMappingURL=terahac.js.map

package/dist/src/research/terahac.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terahac.js","sourceRoot":"","sources":["../../../src/research/terahac.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/algorithms",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Graph algorithms library for browser environments implemented in TypeScript",
   "author": "Adam Powers <apowers@ato.ms>",
   "main": "dist/algorithms.js",
@@ -35,10 +35,18 @@
     "typecheck": "tsc --noEmit",
     "prepare": "husky",
     "build": "tsc",
+    "build:bundle": "node scripts/build-bundle.js",
+    "build:all": "npm run build && npm run build:bundle",
+    "build:gh-pages": "npm run build:bundle && node scripts/build-gh-pages.js",
     "build:watch": "tsc --watch",
     "dev": "tsc --watch",
+    "examples": "node examples/run-all-examples.js",
+    "examples:run": "node examples/run-all-examples.js",
+    "examples:html": "npm run build:bundle && vite",
+    "serve": "npm run build:bundle && vite",
     "commit": "cz",
-    "ready:commit": "npm run build && npm run lint && npm run test:all"
+    "ready:commit": "npm run build && npm run lint && npm run test:all",
+    "watch": "tsc --watch"
   },
   "repository": {
     "type": "git",
@@ -97,6 +105,7 @@
     "tsx": "^4.20.3",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.34.1",
+    "vite": "^7.0.5",
     "vitest": "^3.2.4"
   }
 }

package/src/clustering/spectral.ts

@@ -59,13 +59,27 @@ export function spectralClustering(
     // Find k smallest eigenvectors
     const eigenResult = findSmallestEigenvectors(laplacianMatrix, k);
 
-    // Normalize the eigenvector matrix row-wise (for normalized spectral clustering)
+    // Perform k-means clustering on the eigenvectors
+    // For spectral clustering, we need to transpose the eigenvector matrix
+    // Each row should be a data point (node) with features from the eigenvectors
+    const dataPoints: number[][] = [];
+    for (let i = 0; i < nodeIds.length; i++) {
+        const point: number[] = [];
+        for (let j = 0; j < k; j++) {
+            const eigenvector = eigenResult.eigenvectors[j];
+            if (eigenvector) {
+                point.push(eigenvector[i] ?? 0);
+            }
+        }
+        dataPoints.push(point);
+    }
+
+    // Normalize the data points row-wise (for normalized spectral clustering)
     if (laplacianType === "normalized") {
-        normalizeRows(eigenResult.eigenvectors);
+        normalizeRows(dataPoints);
     }
 
-    // Perform k-means clustering on the eigenvectors
-    const kmeans = kMeansClustering(eigenResult.eigenvectors, k, maxIterations);
+    const kmeans = kMeansClustering(dataPoints, k, maxIterations);
 
     // Build communities
     const communities: NodeId[][] = Array.from({length: k}, () => []);
@@ -265,32 +279,34 @@ function findSmallestEigenvectors(matrix: number[][], k: number): {
         return {eigenvalues: [], eigenvectors: []};
     }
 
-    // For small matrices or when k >= n, use a simplified approach
-    if (n <= 3 || k >= n) {
-        // Create identity-like eigenvectors for simplicity
-        const eigenvectors: number[][] = [];
-        const eigenvalues: number[] = [];
-
-        for (let i = 0; i < Math.min(k, n); i++) {
-            const vector = Array(n).fill(0) as number[];
-            vector[i] = 1;
-            eigenvectors.push(vector);
-            eigenvalues.push(i);
-        }
+    // For very small matrices, use the full power iteration approach
+    // Remove the simplified approach that was causing issues
+    if (k >= n) {
+        // If k >= n, we still need proper eigenvectors, not identity
+        // Fall through to the power iteration below
+    }
 
-        return {eigenvalues, eigenvectors};
+    // For spectral clustering, we need proper eigenvectors
+    // Special handling for small k values which are common in clustering
+    if (k <= 3 && n > k) {
+        return computeSmallestEigenvectorsSimple(matrix, k, n);
     }
 
-    // For larger matrices, use power iteration to find dominant eigenvectors
-    // This is still simplified but better than random
+    // For larger k, use power iteration
     const eigenvectors: number[][] = [];
     const eigenvalues: number[] = [];
-    const maxIterations = 50;
+    const maxIterations = 100;
 
     for (let eigIdx = 0; eigIdx < k; eigIdx++) {
         // Initialize random vector
         let vector = Array(n).fill(0).map(() => Math.random() - 0.5);
 
+        // Normalize initial vector
+        const initNorm = Math.sqrt(vector.reduce((sum, val) => sum + (val * val), 0));
+        if (initNorm > 0) {
+            vector = vector.map((val) => val / initNorm);
+        }
+
         // Orthogonalize against previous eigenvectors
         for (let j = 0; j < eigIdx; j++) {
             const ejVector = eigenvectors[j];
@@ -543,3 +559,114 @@ function euclideanDistance(a: number[], b: number[]): number {
     }
     return Math.sqrt(sum);
 }
+
+/**
+ * Compute smallest eigenvectors for small k (optimized for k=2, k=3)
+ */
+function computeSmallestEigenvectorsSimple(matrix: number[][], k: number, n: number): {
+    eigenvalues: number[];
+    eigenvectors: number[][];
+} {
+    const eigenvectors: number[][] = [];
+    const eigenvalues: number[] = [];
+
+    // First eigenvector is constant (corresponds to eigenvalue 0 for connected graph)
+    const firstVector = Array(n).fill(1 / Math.sqrt(n)) as number[];
+    eigenvectors.push(firstVector);
+    eigenvalues.push(0);
+
+    // For k >= 2, compute the Fiedler vector (second smallest eigenvector)
+    if (k >= 2) {
+        // Use power iteration on I - L/lambda_max to find second smallest
+        const maxEig = 2; // For normalized Laplacian, max eigenvalue <= 2
+        let vector = Array(n).fill(0).map(() => Math.random() - 0.5);
+
+        // Make orthogonal to first eigenvector
+        const dot1 = vector.reduce((sum, val) => sum + (val / Math.sqrt(n)), 0);
+        vector = vector.map((val) => val - (dot1 / Math.sqrt(n)));
+
+        // Power iteration on shifted matrix
+        for (let iter = 0; iter < 100; iter++) {
+            // Compute (I - L/maxEig) * v
+            const newVector = Array(n).fill(0) as number[];
+
+            // Identity part
+            for (let i = 0; i < n; i++) {
+                newVector[i] = vector[i] ?? 0;
+            }
+
+            // Subtract L * v / maxEig
+            for (let i = 0; i < n; i++) {
+                for (let j = 0; j < n; j++) {
+                    const matrixVal = matrix[i]?.[j] ?? 0;
+                    const vecVal = vector[j] ?? 0;
+                    newVector[i] = (newVector[i] ?? 0) - ((matrixVal * vecVal) / maxEig);
+                }
+            }
+
+            // Orthogonalize against first eigenvector
+            const dot = newVector.reduce((sum, val) => sum + (val / Math.sqrt(n)), 0);
+            for (let i = 0; i < n; i++) {
+                newVector[i] = (newVector[i] ?? 0) - (dot / Math.sqrt(n));
+            }
+
+            // Normalize
+            const norm = Math.sqrt(newVector.reduce((sum, val) => sum + (val * val), 0));
+            if (norm > 1e-10) {
+                vector = newVector.map((val) => val / norm);
+            }
+        }
+
+        eigenvectors.push(vector);
+        eigenvalues.push(0.1); // Approximate
+    }
+
+    // For k = 3, add another eigenvector
+    if (k >= 3) {
+        let vector = Array(n).fill(0).map(() => Math.random() - 0.5);
+
+        // Orthogonalize against previous eigenvectors
+        for (const prev of eigenvectors) {
+            const dot = vector.reduce((sum, val, idx) => sum + (val * (prev[idx] ?? 0)), 0);
+            vector = vector.map((val, idx) => val - (dot * (prev[idx] ?? 0)));
+        }
+
+        // Similar power iteration
+        for (let iter = 0; iter < 50; iter++) {
+            const newVector = Array(n).fill(0) as number[];
+
+            // Identity part
+            for (let i = 0; i < n; i++) {
+                newVector[i] = vector[i] ?? 0;
+            }
+
+            // Subtract L * v / 2
+            for (let i = 0; i < n; i++) {
+                for (let j = 0; j < n; j++) {
+                    const matrixVal = matrix[i]?.[j] ?? 0;
+                    const vecVal = vector[j] ?? 0;
+                    newVector[i] = (newVector[i] ?? 0) - ((matrixVal * vecVal) / 2);
+                }
+            }
+
+            // Orthogonalize
+            for (const prev of eigenvectors) {
+                const dot = newVector.reduce((sum, val, idx) => sum + (val * (prev[idx] ?? 0)), 0);
+                for (let i = 0; i < n; i++) {
+                    newVector[i] = (newVector[i] ?? 0) - (dot * (prev[i] ?? 0));
+                }
+            }
+
+            // Normalize
+            const norm = Math.sqrt(newVector.reduce((sum, val) => sum + (val * val), 0));
+            if (norm > 1e-10) {
+                vector = newVector.map((val) => val / norm);
+            }
+        }
+
+        eigenvectors.push(vector);
+        eigenvalues.push(0.2); // Approximate
+    }
+
+    return {eigenvalues: eigenvalues.slice(0, k), eigenvectors: eigenvectors.slice(0, k)};
+}

package/src/index.ts

@@ -33,5 +33,8 @@ export type {
 // Algorithm exports
 export * from "./algorithms/index.js";
 
+// Research algorithms exports (Priority 4)
+export * from "./research/index.js";
+
 // Data structure exports
 export * from "./data-structures/index.js";