@graphty/algorithms 1.1.0 → 1.3.1

package/dist/src/research/sync.js

@@ -0,0 +1,316 @@
+import { euclideanDistance, SeededRandom } from "../utils/math-utilities.js";
+/**
+ * Synergistic Deep Graph Clustering (SynC) Algorithm
+ *
+ * This algorithm combines representation learning with structure augmentation
+ * for improved clustering performance on graphs. It jointly optimizes node
+ * 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, 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;
+    const rng = SeededRandom.createGenerator(seed);
+    Math.random = rng;
+    const nodes = Array.from(graph.nodes());
+    const nodeCount = nodes.length;
+    if (nodeCount === 0) {
+        return {
+            clusters: new Map(),
+            loss: 0,
+            iterations: 0,
+            embeddings: new Map(),
+            converged: true,
+        };
+    }
+    if (numClusters <= 0 || numClusters > 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)
+    const embeddingDim = Math.min(64, nodeCount);
+    const embeddings = new Map();
+    // Initialize embeddings based on node features
+    for (const node of nodes) {
+        const embedding = initializeNodeEmbedding(graph, node.id, embeddingDim);
+        embeddings.set(node.id, embedding);
+    }
+    // Initialize cluster centers
+    const clusterCenters = initializeClusterCenters(embeddings, numClusters);
+    let previousLoss = Infinity;
+    let iterations = 0;
+    let converged = false;
+    for (iterations = 0; iterations < maxIterations; iterations++) {
+        // E-step: Assign nodes to clusters
+        const clusters = new Map();
+        for (const node of nodes) {
+            const nodeEmbedding = embeddings.get(node.id);
+            if (!nodeEmbedding) {
+                continue;
+            }
+            let bestCluster = 0;
+            let minDistance = Infinity;
+            for (let k = 0; k < numClusters; k++) {
+                const center = clusterCenters[k];
+                if (!center) {
+                    continue;
+                }
+                const distance = euclideanDistance(nodeEmbedding, center);
+                if (distance < minDistance) {
+                    minDistance = distance;
+                    bestCluster = k;
+                }
+            }
+            clusters.set(node.id, bestCluster);
+        }
+        // M-step: Update embeddings and cluster centers
+        updateEmbeddings(graph, embeddings, clusters, learningRate, lambda);
+        updateClusterCenters(embeddings, clusters, clusterCenters, numClusters);
+        // Calculate current loss
+        const currentLoss = calculateLoss(graph, embeddings, clusters, clusterCenters, lambda);
+        // Check for convergence
+        if (Math.abs(previousLoss - currentLoss) < tolerance) {
+            converged = true;
+            break;
+        }
+        previousLoss = currentLoss;
+    }
+    // Final cluster assignment
+    const finalClusters = new Map();
+    for (const node of nodes) {
+        const nodeEmbedding = embeddings.get(node.id);
+        if (!nodeEmbedding) {
+            continue;
+        }
+        let bestCluster = 0;
+        let minDistance = Infinity;
+        for (let k = 0; k < numClusters; k++) {
+            const center = clusterCenters[k];
+            if (!center) {
+                continue;
+            }
+            const distance = euclideanDistance(nodeEmbedding, center);
+            if (distance < minDistance) {
+                minDistance = distance;
+                bestCluster = k;
+            }
+        }
+        finalClusters.set(node.id, bestCluster);
+    }
+    // Restore original random function
+    Math.random = originalRandom;
+    return {
+        clusters: finalClusters,
+        loss: previousLoss,
+        iterations: iterations + 1,
+        embeddings,
+        converged,
+    };
+}
+/**
+ * Initialize node embedding based on graph structure and features
+ */
+function initializeNodeEmbedding(graph, nodeId, dim) {
+    const embedding = new Array(dim).fill(0);
+    // Use node degree as a base feature
+    const degree = graph.degree(nodeId);
+    const normalizedDegree = degree / Math.max(1, graph.nodeCount - 1);
+    // 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);
+    }
+    return embedding;
+}
+/**
+ * Initialize cluster centers using k-means++ style initialization
+ */
+function initializeClusterCenters(embeddings, numClusters) {
+    const embeddingArray = Array.from(embeddings.values());
+    const centers = [];
+    // Choose first center randomly
+    const firstCenter = embeddingArray[Math.floor(Math.random() * embeddingArray.length)];
+    if (firstCenter) {
+        centers.push([...firstCenter]);
+    }
+    // Choose remaining centers using k-means++ initialization
+    for (let k = 1; k < numClusters; k++) {
+        const distances = [];
+        let totalDistance = 0;
+        for (const embedding of embeddingArray) {
+            let minDistance = Infinity;
+            for (const center of centers) {
+                const distance = euclideanDistance(embedding, center);
+                minDistance = Math.min(minDistance, distance);
+            }
+            distances.push(minDistance * minDistance);
+            totalDistance += minDistance * minDistance;
+        }
+        // Choose next center with probability proportional to squared distance
+        let randomValue = Math.random() * totalDistance;
+        for (let i = 0; i < embeddingArray.length; i++) {
+            const distanceValue = distances[i];
+            if (distanceValue !== undefined) {
+                randomValue -= distanceValue;
+            }
+            if (randomValue <= 0) {
+                const newCenter = embeddingArray[i];
+                if (newCenter) {
+                    centers.push([...newCenter]);
+                }
+                break;
+            }
+        }
+    }
+    return centers;
+}
+/**
+ * Update node embeddings using gradient descent
+ */
+function updateEmbeddings(graph, embeddings, clusters, learningRate, lambda) {
+    const gradients = new Map();
+    // Initialize gradients
+    for (const [nodeId, embedding] of embeddings) {
+        gradients.set(nodeId, new Array(embedding.length).fill(0));
+    }
+    // Calculate gradients based on graph structure (simplified)
+    for (const node of graph.nodes()) {
+        const nodeId = node.id;
+        const nodeEmbedding = embeddings.get(nodeId);
+        if (!nodeEmbedding) {
+            continue;
+        }
+        const gradient = gradients.get(nodeId);
+        if (!gradient) {
+            continue;
+        }
+        // Neighbor reconstruction loss gradient
+        for (const neighborId of graph.neighbors(nodeId)) {
+            const neighborEmbedding = embeddings.get(neighborId);
+            if (!neighborEmbedding) {
+                continue;
+            }
+            const diff = nodeEmbedding.map((val, i) => val - (neighborEmbedding[i] ?? 0));
+            for (let i = 0; i < gradient.length; i++) {
+                const gradVal = gradient[i];
+                const diffVal = diff[i];
+                if (gradVal !== undefined && diffVal !== undefined) {
+                    gradient[i] = gradVal + (lambda * diffVal);
+                }
+            }
+        }
+        // Regularization gradient
+        for (let i = 0; i < gradient.length; i++) {
+            const gradVal = gradient[i];
+            const nodeVal = nodeEmbedding[i];
+            if (gradVal !== undefined && nodeVal !== undefined) {
+                gradient[i] = gradVal + (lambda * nodeVal);
+            }
+        }
+    }
+    // Update embeddings
+    for (const [nodeId, embedding] of embeddings) {
+        const gradient = gradients.get(nodeId);
+        if (!gradient) {
+            continue;
+        }
+        for (let i = 0; i < embedding.length; i++) {
+            const embVal = embedding[i];
+            const gradVal = gradient[i];
+            if (embVal !== undefined && gradVal !== undefined) {
+                embedding[i] = embVal - (learningRate * gradVal);
+            }
+        }
+    }
+}
+/**
+ * Update cluster centers based on current assignments
+ */
+function updateClusterCenters(embeddings, clusters, clusterCenters, numClusters) {
+    const dimensions = clusterCenters[0]?.length ?? 0;
+    const clusterSums = Array.from({ length: numClusters }, () => new Array(dimensions).fill(0));
+    const clusterCounts = new Array(numClusters).fill(0);
+    // Sum embeddings for each cluster
+    for (const [nodeId, clusterIdx] of clusters) {
+        const embedding = embeddings.get(nodeId);
+        if (!embedding) {
+            continue;
+        }
+        for (let i = 0; i < embedding.length; i++) {
+            const clusterSum = clusterSums[clusterIdx];
+            if (!clusterSum) {
+                continue;
+            }
+            const sumVal = clusterSum[i];
+            const embVal = embedding[i];
+            if (sumVal !== undefined && embVal !== undefined) {
+                clusterSum[i] = sumVal + embVal;
+            }
+        }
+        if (clusterCounts[clusterIdx] !== undefined) {
+            clusterCounts[clusterIdx]++;
+        }
+    }
+    // Update cluster centers (average of assigned embeddings)
+    for (let k = 0; k < numClusters; k++) {
+        const count = clusterCounts[k];
+        const center = clusterCenters[k];
+        const sum = clusterSums[k];
+        if (count !== undefined && count > 0 && center && sum) {
+            for (let i = 0; i < center.length; i++) {
+                const sumVal = sum[i];
+                if (sumVal !== undefined) {
+                    center[i] = sumVal / count;
+                }
+            }
+        }
+    }
+}
+/**
+ * Calculate the total loss function
+ */
+function calculateLoss(graph, embeddings, clusters, clusterCenters, lambda) {
+    let clusteringLoss = 0;
+    let reconstructionLoss = 0;
+    let regularizationLoss = 0;
+    // Clustering loss (distance to cluster centers)
+    for (const [nodeId, clusterIdx] of clusters) {
+        const embedding = embeddings.get(nodeId);
+        if (!embedding) {
+            continue;
+        }
+        const center = clusterCenters[clusterIdx];
+        if (!center) {
+            continue;
+        }
+        clusteringLoss += euclideanDistance(embedding, center) ** 2;
+    }
+    // Graph reconstruction loss
+    for (const node of graph.nodes()) {
+        const nodeId = node.id;
+        const nodeEmbedding = embeddings.get(nodeId);
+        if (!nodeEmbedding) {
+            continue;
+        }
+        for (const neighborId of graph.neighbors(nodeId)) {
+            const neighborEmbedding = embeddings.get(neighborId);
+            if (!neighborEmbedding) {
+                continue;
+            }
+            const distance = euclideanDistance(nodeEmbedding, neighborEmbedding);
+            reconstructionLoss += distance ** 2;
+        }
+    }
+    // Regularization loss
+    for (const embedding of embeddings.values()) {
+        for (const value of embedding) {
+            regularizationLoss += value ** 2;
+        }
+    }
+    return clusteringLoss + (lambda * reconstructionLoss) + (lambda * regularizationLoss);
+}
+//# sourceMappingURL=sync.js.map

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

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

package/dist/src/research/terahac.d.ts

@@ -0,0 +1,65 @@
+import type { Graph } from "../core/graph.js";
+import type { NodeId } from "../types/index.js";
+/**
+ * Configuration options for the TeraHAC (Hierarchical Agglomerative Clustering) algorithm
+ */
+export interface TeraHACConfig {
+    /** Linkage criterion: 'single', 'complete', 'average', 'ward' */
+    linkage?: "single" | "complete" | "average" | "ward";
+    /** Number of clusters to stop at (optional) */
+    numClusters?: number;
+    /** Distance threshold to stop clustering */
+    distanceThreshold?: number;
+    /** Maximum number of nodes to process efficiently */
+    maxNodes?: number;
+    /** Use graph structure for distance calculation */
+    useGraphDistance?: boolean;
+    /** Custom warning handler (default: console.warn) */
+    onWarning?: (message: string) => void;
+}
+/**
+ * Represents a node in the dendrogram/cluster hierarchy
+ */
+export interface ClusterNode {
+    /** Unique identifier for this cluster */
+    id: string;
+    /** Node IDs in this cluster */
+    members: Set<NodeId>;
+    /** Left child cluster (if internal node) */
+    left?: ClusterNode;
+    /** Right child cluster (if internal node) */
+    right?: ClusterNode;
+    /** Distance at which this cluster was formed */
+    distance: number;
+    /** Size of the cluster */
+    size: number;
+}
+/**
+ * Result of the TeraHAC clustering algorithm
+ */
+export interface TeraHACResult {
+    /** Root of the dendrogram */
+    dendrogram: ClusterNode;
+    /** Flat clustering at specified level */
+    clusters: Map<NodeId, number>;
+    /** All merge distances in order */
+    distances: number[];
+    /** Number of clusters in final result */
+    numClusters: number;
+}
+/**
+ * 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 declare function teraHAC(graph: Graph, config?: TeraHACConfig): TeraHACResult;
+//# sourceMappingURL=terahac.d.ts.map

package/dist/src/research/terahac.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terahac.d.ts","sourceRoot":"","sources":["../../../src/research/terahac.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,KAAK,EAAC,MAAM,kBAAkB,CAAC;AAC5C,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,iEAAiE;IACjE,OAAO,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;IACrD,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,qDAAqD;IACrD,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IACxB,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,+BAA+B;IAC/B,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACrB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,6BAA6B;IAC7B,UAAU,EAAE,WAAW,CAAC;IACxB,yCAAyC;IACzC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,mCAAmC;IACnC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,GAAE,aAAkB,GAAG,aAAa,CAmJ/E"}