@graphty/algorithms 1.0.1 → 1.1.0

package/src/clustering/spectral.ts

@@ -0,0 +1,545 @@
+import type {Graph} from "../core/graph.js";
+import type {NodeId} from "../types/index.js";
+
+/**
+ * Spectral Clustering implementation
+ *
+ * Uses eigenvalues and eigenvectors of the graph Laplacian matrix to perform clustering.
+ * Particularly effective for finding non-convex clusters and communities in graphs.
+ *
+ * Time complexity: O(V³) for eigendecomposition
+ * Space complexity: O(V²)
+ */
+
+export interface SpectralClusteringOptions {
+    k: number; // Number of clusters to find
+    laplacianType?: "unnormalized" | "normalized" | "randomWalk"; // Type of Laplacian
+    maxIterations?: number; // Max iterations for k-means (default: 100)
+    tolerance?: number; // Convergence tolerance (default: 1e-4)
+}
+
+export interface SpectralClusteringResult {
+    communities: NodeId[][];
+    clusterAssignments: Map<NodeId, number>;
+    eigenvalues?: number[];
+    eigenvectors?: number[][];
+}
+
+/**
+ * Perform spectral clustering on a graph
+ */
+export function spectralClustering(
+    graph: Graph,
+    options: SpectralClusteringOptions,
+): SpectralClusteringResult {
+    const {
+        k,
+        laplacianType = "normalized",
+        maxIterations = 100,
+    } = options;
+
+    const nodes = Array.from(graph.nodes());
+    const nodeIds = nodes.map((node) => node.id);
+    const n = nodeIds.length;
+
+    if (k >= n) {
+        // Return each node as its own cluster
+        const communities: NodeId[][] = nodeIds.map((id) => [id]);
+        const clusterAssignments = new Map<NodeId, number>();
+        nodeIds.forEach((id, index) => clusterAssignments.set(id, index));
+        return {communities, clusterAssignments};
+    }
+
+    // Build adjacency matrix
+    const adjacencyMatrix = buildAdjacencyMatrix(graph, nodeIds);
+
+    // Build Laplacian matrix
+    const laplacianMatrix = buildLaplacianMatrix(adjacencyMatrix, laplacianType);
+
+    // Find k smallest eigenvectors
+    const eigenResult = findSmallestEigenvectors(laplacianMatrix, k);
+
+    // Normalize the eigenvector matrix row-wise (for normalized spectral clustering)
+    if (laplacianType === "normalized") {
+        normalizeRows(eigenResult.eigenvectors);
+    }
+
+    // Perform k-means clustering on the eigenvectors
+    const kmeans = kMeansClustering(eigenResult.eigenvectors, k, maxIterations);
+
+    // Build communities
+    const communities: NodeId[][] = Array.from({length: k}, () => []);
+    const clusterAssignments = new Map<NodeId, number>();
+
+    for (let i = 0; i < nodeIds.length; i++) {
+        const clusterId = kmeans.assignments[i] ?? 0;
+        const nodeId = nodeIds[i];
+        if (!nodeId) {
+            continue;
+        }
+
+        // Ensure clusterId is valid
+        if (clusterId >= 0 && clusterId < k) {
+            const community = communities[clusterId];
+            if (community) {
+                community.push(nodeId);
+            }
+
+            clusterAssignments.set(nodeId, clusterId);
+        } else {
+            // Assign to first cluster if invalid
+            const firstCommunity = communities[0];
+            if (firstCommunity) {
+                firstCommunity.push(nodeId);
+            }
+
+            clusterAssignments.set(nodeId, 0);
+        }
+    }
+
+    // Filter out empty communities
+    const nonEmptyCommunities = communities.filter((community) => community.length > 0);
+
+    return {
+        communities: nonEmptyCommunities,
+        clusterAssignments,
+        eigenvalues: eigenResult.eigenvalues,
+        eigenvectors: eigenResult.eigenvectors,
+    };
+}
+
+/**
+ * Build adjacency matrix from graph
+ */
+function buildAdjacencyMatrix(graph: Graph, nodeIds: NodeId[]): number[][] {
+    const n = nodeIds.length;
+    const matrix: number[][] = Array.from({length: n}, () => Array(n).fill(0) as number[]);
+    const nodeToIndex = new Map<NodeId, number>();
+
+    nodeIds.forEach((id, index) => nodeToIndex.set(id, index));
+
+    for (let i = 0; i < n; i++) {
+        const nodeId = nodeIds[i];
+        if (!nodeId) {
+            continue;
+        }
+
+        const neighbors = graph.neighbors(nodeId);
+
+        for (const neighbor of neighbors) {
+            const j = nodeToIndex.get(neighbor);
+            if (j !== undefined) {
+                const edge = graph.getEdge(nodeId, neighbor);
+                const weight = edge?.weight ?? 1;
+                const matrixRow = matrix[i];
+                if (matrixRow) {
+                    matrixRow[j] = weight;
+                }
+
+                if (!graph.isDirected) {
+                    const matrixRowJ = matrix[j];
+                    if (matrixRowJ) {
+                        matrixRowJ[i] = weight;
+                    }
+                }
+            }
+        }
+    }
+
+    return matrix;
+}
+
+/**
+ * Build Laplacian matrix from adjacency matrix
+ */
+function buildLaplacianMatrix(adjacency: number[][], type: string): number[][] {
+    const n = adjacency.length;
+    const laplacian: number[][] = Array.from({length: n}, () => Array(n).fill(0) as number[]);
+
+    // Calculate degree matrix
+    const degrees = Array(n).fill(0) as number[];
+    for (let i = 0; i < n; i++) {
+        for (let j = 0; j < n; j++) {
+            const adjacencyRow = adjacency[i];
+            const adjacencyVal = adjacencyRow ? adjacencyRow[j] : 0;
+            if (adjacencyVal !== undefined) {
+                const degreeVal = degrees[i];
+                if (degreeVal !== undefined) {
+                    degrees[i] = degreeVal + adjacencyVal;
+                }
+            }
+        }
+    }
+
+    if (type === "unnormalized") {
+        // L = D - A
+        for (let i = 0; i < n; i++) {
+            for (let j = 0; j < n; j++) {
+                if (i === j) {
+                    const laplacianRow = laplacian[i];
+                    const degreeVal = degrees[i];
+                    if (laplacianRow && degreeVal !== undefined) {
+                        laplacianRow[j] = degreeVal;
+                    }
+                } else {
+                    const adjacencyRow = adjacency[i];
+                    const laplacianRow = laplacian[i];
+                    if (adjacencyRow && laplacianRow) {
+                        const adjacencyVal = adjacencyRow[j];
+                        laplacianRow[j] = adjacencyVal !== undefined ? -adjacencyVal : 0;
+                    }
+                }
+            }
+        }
+    } else if (type === "normalized") {
+        // L_sym = D^(-1/2) * L * D^(-1/2)
+        for (let i = 0; i < n; i++) {
+            for (let j = 0; j < n; j++) {
+                if (i === j) {
+                    const di = degrees[i];
+                    const laplacianRow = laplacian[i];
+                    if (laplacianRow) {
+                        laplacianRow[j] = di !== undefined && di > 0 ? 1 : 0;
+                    }
+                } else {
+                    const adjacencyRow = adjacency[i];
+                    if (!adjacencyRow) {
+                        continue;
+                    }
+
+                    const adjacencyVal = adjacencyRow[j];
+                    const di = degrees[i];
+                    const dj = degrees[j];
+                    if (adjacencyVal !== undefined && adjacencyVal > 0 && di !== undefined && dj !== undefined && di > 0 && dj > 0) {
+                        const laplacianRow = laplacian[i];
+                        if (laplacianRow) {
+                            laplacianRow[j] = -adjacencyVal / Math.sqrt(di * dj);
+                        }
+                    }
+                }
+            }
+        }
+    } else if (type === "randomWalk") {
+        // L_rw = D^(-1) * L
+        for (let i = 0; i < n; i++) {
+            for (let j = 0; j < n; j++) {
+                if (i === j) {
+                    const di = degrees[i];
+                    const laplacianRow = laplacian[i];
+                    if (laplacianRow) {
+                        laplacianRow[j] = di !== undefined && di > 0 ? 1 : 0;
+                    }
+                } else {
+                    const adjacencyRow = adjacency[i];
+                    if (!adjacencyRow) {
+                        continue;
+                    }
+
+                    const adjacencyVal = adjacencyRow[j];
+                    const di = degrees[i];
+                    if (adjacencyVal !== undefined && adjacencyVal > 0 && di !== undefined && di > 0) {
+                        const laplacianRow = laplacian[i];
+                        if (laplacianRow) {
+                            laplacianRow[j] = -adjacencyVal / di;
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    return laplacian;
+}
+
+/**
+ * Find k smallest eigenvectors using simplified eigendecomposition
+ * This is a simplified implementation - in practice, you'd use LAPACK or similar
+ */
+function findSmallestEigenvectors(matrix: number[][], k: number): {
+    eigenvalues: number[];
+    eigenvectors: number[][];
+} {
+    const n = matrix.length;
+
+    if (n === 0 || k === 0) {
+        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);
+        }
+
+        return {eigenvalues, eigenvectors};
+    }
+
+    // For larger matrices, use power iteration to find dominant eigenvectors
+    // This is still simplified but better than random
+    const eigenvectors: number[][] = [];
+    const eigenvalues: number[] = [];
+    const maxIterations = 50;
+
+    for (let eigIdx = 0; eigIdx < k; eigIdx++) {
+        // Initialize random vector
+        let vector = Array(n).fill(0).map(() => Math.random() - 0.5);
+
+        // Orthogonalize against previous eigenvectors
+        for (let j = 0; j < eigIdx; j++) {
+            const ejVector = eigenvectors[j];
+            if (!ejVector) {
+                continue;
+            }
+
+            const dot = vector.reduce((sum, val, idx) => sum + (val * (ejVector[idx] ?? 0)), 0);
+            vector = vector.map((val, idx) => val - (dot * (ejVector[idx] ?? 0)));
+        }
+
+        // Power iteration
+        for (let iter = 0; iter < maxIterations; iter++) {
+            // Multiply by matrix
+            const newVector = Array(n).fill(0) as number[];
+            for (let i = 0; i < n; i++) {
+                for (let j = 0; j < n; j++) {
+                    const matrixRow = matrix[i];
+                    const vecVal = vector[j];
+                    const matrixVal = matrixRow?.[j];
+                    if (matrixVal !== undefined && vecVal !== undefined) {
+                        const nvVal = newVector[i];
+                        if (nvVal !== undefined) {
+                            newVector[i] = nvVal + (matrixVal * vecVal);
+                        }
+                    }
+                }
+            }
+
+            // Orthogonalize against previous eigenvectors
+            for (let j = 0; j < eigIdx; j++) {
+                const ejVector = eigenvectors[j];
+                if (!ejVector) {
+                    continue;
+                }
+
+                const dot = newVector.reduce((sum, val, idx) => sum + (val * (ejVector[idx] ?? 0)), 0);
+                for (let i = 0; i < n; i++) {
+                    const ejVal = ejVector[i];
+                    if (ejVal !== undefined) {
+                        const nvVal = newVector[i];
+                        if (nvVal !== undefined) {
+                            newVector[i] = nvVal - (dot * ejVal);
+                        }
+                    }
+                }
+            }
+
+            // Normalize
+            const norm = Math.sqrt(newVector.reduce((sum, val) => sum + ((val * val)), 0));
+            if (norm > 1e-10) {
+                vector = newVector.map((val) => val / norm);
+            } else {
+                break;
+            }
+        }
+
+        // Calculate eigenvalue (Rayleigh quotient)
+        let eigenvalue = 0;
+        const Av = Array(n).fill(0) as number[];
+        for (let i = 0; i < n; i++) {
+            for (let j = 0; j < n; j++) {
+                const matrixRow = matrix[i];
+                const vecVal = vector[j];
+                const matrixVal = matrixRow?.[j];
+                if (matrixVal !== undefined && vecVal !== undefined) {
+                    const avVal = Av[i];
+                    if (avVal !== undefined) {
+                        Av[i] = avVal + (matrixVal * vecVal);
+                    }
+                }
+            }
+        }
+        eigenvalue = vector.reduce((sum, val, idx) => {
+            const avVal = Av[idx];
+            return sum + (val * (avVal ?? 0));
+        }, 0);
+
+        eigenvectors.push(vector);
+        eigenvalues.push(eigenvalue);
+    }
+
+    return {eigenvalues, eigenvectors};
+}
+
+/**
+ * Normalize matrix rows to unit length
+ */
+function normalizeRows(matrix: number[][]): void {
+    for (const row of matrix) {
+        const norm = Math.sqrt(row.reduce((sum, val) => sum + (val * val), 0));
+        if (norm > 0) {
+            for (let j = 0; j < row.length; j++) {
+                const val = row[j];
+                if (val !== undefined) {
+                    row[j] = val / norm;
+                }
+            }
+        }
+    }
+}
+
+/**
+ * K-means clustering algorithm
+ */
+function kMeansClustering(
+    data: number[][],
+    k: number,
+    maxIterations: number,
+): {assignments: number[], centroids: number[][]} {
+    const n = data.length;
+    const d = data[0]?.length ?? 0;
+
+    // Handle edge cases
+    if (n === 0 || k === 0) {
+        return {assignments: [], centroids: []};
+    }
+
+    if (k >= n) {
+        // Each point is its own cluster
+        return {
+            assignments: Array.from({length: n}, (_, i) => i),
+            centroids: data.slice(0, n),
+        };
+    }
+
+    // Initialize centroids by selecting random data points
+    const centroids: number[][] = [];
+    const selectedIndices = new Set<number>();
+
+    while (centroids.length < k && selectedIndices.size < n) {
+        const idx = Math.floor(Math.random() * n);
+        if (!selectedIndices.has(idx) && data[idx]) {
+            selectedIndices.add(idx);
+            centroids.push([... data[idx]]);
+        }
+    }
+
+    // Fill remaining centroids with random values if needed
+    while (centroids.length < k) {
+        const centroid = Array(d).fill(0) as number[];
+        for (let j = 0; j < d; j++) {
+            centroid[j] = Math.random() - 0.5;
+        }
+        centroids.push(centroid);
+    }
+
+    const assignments = Array(n).fill(0) as number[];
+    let oldAssignments = Array(n).fill(-1) as number[];
+
+    for (let iteration = 0; iteration < maxIterations; iteration++) {
+        // Assign points to closest centroids
+        for (let i = 0; i < n; i++) {
+            let minDistance = Number.POSITIVE_INFINITY;
+            let bestCluster = 0;
+
+            for (let j = 0; j < k; j++) {
+                const dataPoint = data[i];
+                const centroid = centroids[j];
+                if (!dataPoint || !centroid) {
+                    continue;
+                }
+
+                const distance = euclideanDistance(dataPoint, centroid);
+                if (distance < minDistance) {
+                    minDistance = distance;
+                    bestCluster = j;
+                }
+            }
+
+            assignments[i] = bestCluster;
+        }
+
+        // Check for convergence
+        let changed = false;
+        for (let i = 0; i < n; i++) {
+            if (assignments[i] !== oldAssignments[i]) {
+                changed = true;
+                break;
+            }
+        }
+
+        if (!changed) {
+            break;
+        }
+
+        oldAssignments = [... assignments];
+
+        // Update centroids
+        const counts = Array(k).fill(0) as number[];
+        const sums: number[][] = Array.from({length: k}, () => Array(d).fill(0) as number[]);
+
+        for (let i = 0; i < n; i++) {
+            const cluster = assignments[i] ?? 0;
+            const dataPoint = data[i];
+            if (!dataPoint) {
+                continue;
+            }
+
+            const sumsCluster = sums[cluster];
+            if (sumsCluster !== undefined) {
+                const countVal = counts[cluster];
+                if (countVal !== undefined) {
+                    counts[cluster] = countVal + 1;
+                }
+
+                for (let j = 0; j < d; j++) {
+                    const dpVal = dataPoint[j];
+                    if (dpVal !== undefined) {
+                        const sumVal = sumsCluster[j];
+                        if (sumVal !== undefined) {
+                            sumsCluster[j] = sumVal + dpVal;
+                        }
+                    }
+                }
+            }
+        }
+
+        for (let i = 0; i < k; i++) {
+            const countVal = counts[i];
+            if (countVal !== undefined && countVal > 0) {
+                const sumsRow = sums[i];
+                const centroidsRow = centroids[i];
+                if (sumsRow !== undefined && centroidsRow !== undefined) {
+                    for (let j = 0; j < d; j++) {
+                        const sumVal = sumsRow[j];
+                        if (sumVal !== undefined) {
+                            const countVal = counts[i];
+                            if (countVal !== undefined) {
+                                centroidsRow[j] = sumVal / countVal;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    return {assignments, centroids};
+}
+
+/**
+ * Calculate Euclidean distance between two vectors
+ */
+function euclideanDistance(a: number[], b: number[]): number {
+    let sum = 0;
+    for (let i = 0; i < a.length; i++) {
+        const diff = (a[i] ?? 0) - (b[i] ?? 0);
+        sum += diff * diff;
+    }
+    return Math.sqrt(sum);
+}

package/src/core/graph.ts

@@ -51,7 +51,7 @@ export class Graph {
         // Remove all edges connected to this node
         const outgoingEdges = this.adjacencyList.get(id);
         if (outgoingEdges) {
-            for (const targetId of outgoingEdges.keys()) {
+            for (const targetId of Array.from(outgoingEdges.keys())) {
                 this.removeEdge(id, targetId);
             }
         }
@@ -59,13 +59,13 @@ export class Graph {
         if (this.config.directed) {
             const incomingEdges = this.incomingEdges.get(id);
             if (incomingEdges) {
-                for (const sourceId of incomingEdges.keys()) {
+                for (const sourceId of Array.from(incomingEdges.keys())) {
                     this.removeEdge(sourceId, id);
                 }
             }
         } else {
             // For undirected graphs, also remove edges where this node is the target
-            for (const [nodeId, edges] of this.adjacencyList) {
+            for (const [nodeId, edges] of Array.from(this.adjacencyList)) {
                 if (edges.has(id)) {
                     this.removeEdge(nodeId, id);
                 }
@@ -222,7 +222,7 @@ export class Graph {
      * Get all edges in the graph
      */
     *edges(): IterableIterator<Edge> {
-        for (const [source, edges] of this.adjacencyList) {
+        for (const [source, edges] of Array.from(this.adjacencyList)) {
             for (const edge of edges.values()) {
                 // For undirected graphs, only yield each edge once
                 if (!this.config.directed && source > edge.target) {
@@ -300,12 +300,12 @@ export class Graph {
         const cloned = new Graph(this.config);
 
         // Copy nodes
-        for (const node of this.nodeMap.values()) {
+        for (const node of Array.from(this.nodeMap.values())) {
             cloned.addNode(node.id, node.data ? {... node.data} : undefined);
         }
 
         // Copy edges
-        for (const edge of this.edges()) {
+        for (const edge of Array.from(this.edges())) {
             cloned.addEdge(
                 edge.source,
                 edge.target,
@@ -323,4 +323,32 @@ export class Graph {
     getConfig(): GraphConfig {
         return {... this.config};
     }
+
+    /**
+     * Clear all nodes and edges from the graph
+     */
+    clear(): void {
+        this.nodeMap.clear();
+        this.adjacencyList.clear();
+        this.incomingEdges.clear();
+        this.edgeCount = 0;
+    }
+
+    /**
+     * Get the number of unique edges in the graph
+     * For undirected graphs, each edge is counted once
+     */
+    get uniqueEdgeCount(): number {
+        if (this.config.directed) {
+            return this.edgeCount;
+        }
+
+        // For undirected graphs, we need to count each edge only once
+        let count = 0;
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        for (const _edge of Array.from(this.edges())) {
+            count++;
+        }
+        return count;
+    }
 }

package/src/data-structures/union-find.ts

@@ -103,7 +103,7 @@ export class UnionFind {
         const root = this.find(element);
         const component: NodeId[] = [];
 
-        for (const [node] of this.parent) {
+        for (const [node] of Array.from(this.parent)) {
             if (this.find(node) === root) {
                 component.push(node);
             }
@@ -118,7 +118,7 @@ export class UnionFind {
     getAllComponents(): NodeId[][] {
         const componentMap = new Map<NodeId, NodeId[]>();
 
-        for (const [node] of this.parent) {
+        for (const [node] of Array.from(this.parent)) {
             const root = this.find(node);
 
             if (!componentMap.has(root)) {