@graphty/algorithms 1.1.0 → 1.3.1

package/dist/src/optimized/graph-adapter.d.ts

@@ -0,0 +1,62 @@
+import type { Graph } from "../core/graph.js";
+import type { NodeId } from "../types/index.js";
+import { CSRGraph, type ReadonlyGraph } from "./csr-graph.js";
+/**
+ * Adapter to convert standard Graph to CSR format
+ *
+ * Provides transparent conversion while maintaining API compatibility
+ */
+export declare class GraphAdapter<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
+    private csrGraph;
+    constructor(graph: Graph | ReadonlyGraph<TNodeId>);
+    /**
+   * Convert standard graph to CSR format
+   */
+    private convertToCSR;
+    nodeCount(): number;
+    edgeCount(): number;
+    hasNode(nodeId: TNodeId): boolean;
+    hasEdge(source: TNodeId, target: TNodeId): boolean;
+    neighbors(nodeId: TNodeId): IterableIterator<TNodeId>;
+    outDegree(nodeId: TNodeId): number;
+    nodes(): IterableIterator<TNodeId>;
+    /**
+   * Get the underlying CSR graph
+   */
+    getCSRGraph(): CSRGraph<TNodeId>;
+}
+/**
+ * Configuration for graph algorithm optimizations
+ */
+export interface GraphAlgorithmConfig {
+    useDirectionOptimizedBFS?: boolean;
+    useCSRFormat?: boolean;
+    useBitPackedStructures?: boolean;
+    bfsAlpha?: number;
+    bfsBeta?: number;
+    preallocateSize?: number;
+    enableCaching?: boolean;
+}
+/**
+ * Configure optimizations globally
+ * @deprecated This function is a no-op and will be removed in a future version
+ */
+export declare function configureOptimizations(_config: GraphAlgorithmConfig): void;
+/**
+ * Get current configuration
+ * @deprecated This function returns empty config and will be removed in a future version
+ */
+export declare function getOptimizationConfig(): GraphAlgorithmConfig;
+/**
+ * Check if a graph is already in CSR format
+ */
+export declare function isCSRGraph<TNodeId = NodeId>(graph: unknown): graph is CSRGraph<TNodeId>;
+/**
+ * Convert any graph to CSR format
+ */
+export declare function toCSRGraph<TNodeId = NodeId>(graph: Graph | ReadonlyGraph<TNodeId> | CSRGraph<TNodeId>): CSRGraph<TNodeId>;
+/**
+ * Create an optimized graph from nodes and edges
+ */
+export declare function createOptimizedGraph<TNodeId = NodeId>(nodes: TNodeId[], edges: [TNodeId, TNodeId, number?][]): CSRGraph<TNodeId>;
+//# sourceMappingURL=graph-adapter.d.ts.map

package/dist/src/optimized/graph-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-adapter.d.ts","sourceRoot":"","sources":["../../../src/optimized/graph-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,KAAK,EAAC,MAAM,kBAAkB,CAAC;AAC5C,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAC,QAAQ,EAAE,KAAK,aAAa,EAAC,MAAM,gBAAgB,CAAC;AAE5D;;;;GAIG;AACH,qBAAa,YAAY,CAAC,OAAO,GAAG,MAAM,CAAE,YAAW,aAAa,CAAC,OAAO,CAAC;IACzE,OAAO,CAAC,QAAQ,CAAoB;gBAExB,KAAK,EAAE,KAAK,GAAG,aAAa,CAAC,OAAO,CAAC;IAUjD;;KAEC;IACD,OAAO,CAAC,YAAY;IAuDpB,SAAS,IAAI,MAAM;IAInB,SAAS,IAAI,MAAM;IAInB,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO;IAIjC,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO;IAIlD,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB,CAAC,OAAO,CAAC;IAIrD,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM;IAIlC,KAAK,IAAI,gBAAgB,CAAC,OAAO,CAAC;IAIlC;;KAEC;IACD,WAAW,IAAI,QAAQ,CAAC,OAAO,CAAC;CAGnC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IAEjC,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,sBAAsB,CAAC,EAAE,OAAO,CAAC;IAGjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;GAGG;AAEH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAE1E;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,oBAAoB,CAE5D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAG,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAAC,OAAO,CAAC,CAEvF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAG,MAAM,EACvC,KAAK,EAAE,KAAK,GAAG,aAAa,CAAC,OAAO,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,GAC1D,QAAQ,CAAC,OAAO,CAAC,CAOnB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAG,MAAM,EACjD,KAAK,EAAE,OAAO,EAAE,EAChB,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,EAAE,GACrC,QAAQ,CAAC,OAAO,CAAC,CAqBnB"}

package/dist/src/optimized/graph-adapter.js

@@ -0,0 +1,146 @@
+import { CSRGraph } from "./csr-graph.js";
+/**
+ * Adapter to convert standard Graph to CSR format
+ *
+ * Provides transparent conversion while maintaining API compatibility
+ */
+export class GraphAdapter {
+    constructor(graph) {
+        // Check if already a CSRGraph
+        if (graph instanceof CSRGraph) {
+            this.csrGraph = graph;
+        }
+        else {
+            // Convert to CSR format
+            this.csrGraph = this.convertToCSR(graph);
+        }
+    }
+    /**
+   * Convert standard graph to CSR format
+   */
+    convertToCSR(graph) {
+        const adjacencyList = new Map();
+        const weights = new Map();
+        // Handle both Graph and ReadonlyGraph interfaces
+        if ("nodes" in graph && typeof graph.nodes === "function") {
+            // Build adjacency list from Graph
+            for (const node of graph.nodes()) {
+                const nodeId = node.id;
+                const neighbors = [];
+                const graphTyped = graph;
+                for (const neighborId of graphTyped.neighbors(nodeId)) {
+                    neighbors.push(neighborId);
+                    // Get edge weight if available
+                    if ("getEdge" in graph && typeof graph.getEdge === "function") {
+                        const edge = graphTyped.getEdge(nodeId, neighborId);
+                        if (edge?.weight !== undefined) {
+                            weights.set(`${String(nodeId)}-${String(neighborId)}`, edge.weight);
+                        }
+                    }
+                }
+                adjacencyList.set(nodeId, neighbors);
+            }
+        }
+        else if ("nodeIds" in graph && typeof graph.nodeIds === "function") {
+            const readonlyGraph = graph;
+            for (const nodeId of readonlyGraph.nodeIds()) {
+                adjacencyList.set(nodeId, []);
+            }
+            // Build adjacency from edges
+            if ("edges" in readonlyGraph && typeof readonlyGraph.edges === "function") {
+                for (const edge of readonlyGraph.edges()) {
+                    const neighbors = adjacencyList.get(edge.source);
+                    if (neighbors) {
+                        neighbors.push(edge.target);
+                        if (edge.weight !== undefined) {
+                            weights.set(`${String(edge.source)}-${String(edge.target)}`, edge.weight);
+                        }
+                    }
+                }
+            }
+        }
+        return new CSRGraph(adjacencyList, weights.size > 0 ? weights : undefined);
+    }
+    // Delegate all methods to CSR implementation
+    nodeCount() {
+        return this.csrGraph.nodeCount();
+    }
+    edgeCount() {
+        return this.csrGraph.edgeCount();
+    }
+    hasNode(nodeId) {
+        return this.csrGraph.hasNode(nodeId);
+    }
+    hasEdge(source, target) {
+        return this.csrGraph.hasEdge(source, target);
+    }
+    neighbors(nodeId) {
+        return this.csrGraph.neighbors(nodeId);
+    }
+    outDegree(nodeId) {
+        return this.csrGraph.outDegree(nodeId);
+    }
+    nodes() {
+        return this.csrGraph.nodes();
+    }
+    /**
+   * Get the underlying CSR graph
+   */
+    getCSRGraph() {
+        return this.csrGraph;
+    }
+}
+/**
+ * Configure optimizations globally
+ * @deprecated This function is a no-op and will be removed in a future version
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export function configureOptimizations(_config) {
+    // No-op for backward compatibility
+}
+/**
+ * Get current configuration
+ * @deprecated This function returns empty config and will be removed in a future version
+ */
+export function getOptimizationConfig() {
+    return {};
+}
+/**
+ * Check if a graph is already in CSR format
+ */
+export function isCSRGraph(graph) {
+    return graph instanceof CSRGraph;
+}
+/**
+ * Convert any graph to CSR format
+ */
+export function toCSRGraph(graph) {
+    if (isCSRGraph(graph)) {
+        return graph;
+    }
+    const adapter = new GraphAdapter(graph);
+    return adapter.getCSRGraph();
+}
+/**
+ * Create an optimized graph from nodes and edges
+ */
+export function createOptimizedGraph(nodes, edges) {
+    const adjacencyList = new Map();
+    const weights = new Map();
+    // Initialize nodes
+    for (const node of nodes) {
+        adjacencyList.set(node, []);
+    }
+    // Add edges
+    for (const [source, target, weight] of edges) {
+        const neighbors = adjacencyList.get(source);
+        if (neighbors) {
+            neighbors.push(target);
+            if (weight !== undefined) {
+                weights.set(`${String(source)}-${String(target)}`, weight);
+            }
+        }
+    }
+    return new CSRGraph(adjacencyList, weights.size > 0 ? weights : undefined);
+}
+//# sourceMappingURL=graph-adapter.js.map

package/dist/src/optimized/graph-adapter.js.map

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

package/dist/src/optimized/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Optimized graph algorithm implementations
+ *
+ * High-performance implementations using:
+ * - Direction-Optimized BFS
+ * - Compressed Sparse Row (CSR) format
+ * - Bit-packed data structures
+ */
+export { configureOptimizations, getOptimizationConfig, type GraphAlgorithmConfig, } from "./graph-adapter.js";
+export { CompactDistanceArray, GraphBitSet, VisitedBitArray } from "./bit-packed.js";
+export { CSRGraph } from "./csr-graph.js";
+export { DirectionOptimizedBFS } from "./direction-optimized-bfs.js";
+export { createOptimizedGraph, isCSRGraph, toCSRGraph } from "./graph-adapter.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/optimized/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/optimized/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EACH,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,oBAAoB,GAC5B,MAAM,oBAAoB,CAAC;AAgB5B,OAAO,EAAC,oBAAoB,EAAE,WAAW,EAAE,eAAe,EAAC,MAAM,iBAAiB,CAAC;AACnF,OAAO,EAAC,QAAQ,EAAC,MAAM,gBAAgB,CAAC;AACxC,OAAO,EAAC,qBAAqB,EAAC,MAAM,8BAA8B,CAAC;AAGnE,OAAO,EAAC,oBAAoB,EAAE,UAAU,EAAE,UAAU,EAAC,MAAM,oBAAoB,CAAC"}

package/dist/src/optimized/index.js

@@ -0,0 +1,28 @@
+/**
+ * Optimized graph algorithm implementations
+ *
+ * High-performance implementations using:
+ * - Direction-Optimized BFS
+ * - Compressed Sparse Row (CSR) format
+ * - Bit-packed data structures
+ */
+// Configuration and optimization control
+export { configureOptimizations, getOptimizationConfig, } from "./graph-adapter.js";
+// Note: The main BFS functions in algorithms/traversal/bfs.ts automatically
+// use these optimizations for large graphs (>10k nodes) when optimizations are enabled.
+// No manual configuration needed - just use breadthFirstSearch, shortestPathBFS, etc.
+//
+// The previously exported bfsOptimized, shortestPathBFSOptimized, and
+// singleSourceShortestPathBFSOptimized functions have been removed since they
+// are no longer needed. All optimization happens automatically.
+// BFS optimization functions have been removed. The main BFS functions
+// (breadthFirstSearch, shortestPathBFS, singleSourceShortestPathBFS)
+// in algorithms/traversal/bfs.ts now automatically use optimizations
+// for large graphs without requiring manual configuration.
+// Export data structures for advanced users
+export { CompactDistanceArray, GraphBitSet, VisitedBitArray } from "./bit-packed.js";
+export { CSRGraph } from "./csr-graph.js";
+export { DirectionOptimizedBFS } from "./direction-optimized-bfs.js";
+// Export utilities
+export { createOptimizedGraph, isCSRGraph, toCSRGraph } from "./graph-adapter.js";
+//# sourceMappingURL=index.js.map

package/dist/src/optimized/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/optimized/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,yCAAyC;AACzC,OAAO,EACH,sBAAsB,EACtB,qBAAqB,GAExB,MAAM,oBAAoB,CAAC;AAE5B,4EAA4E;AAC5E,wFAAwF;AACxF,sFAAsF;AACtF,EAAE;AACF,sEAAsE;AACtE,8EAA8E;AAC9E,gEAAgE;AAEhE,uEAAuE;AACvE,qEAAqE;AACrE,qEAAqE;AACrE,2DAA2D;AAE3D,4CAA4C;AAC5C,OAAO,EAAC,oBAAoB,EAAE,WAAW,EAAE,eAAe,EAAC,MAAM,iBAAiB,CAAC;AACnF,OAAO,EAAC,QAAQ,EAAC,MAAM,gBAAgB,CAAC;AACxC,OAAO,EAAC,qBAAqB,EAAC,MAAM,8BAA8B,CAAC;AAEnE,mBAAmB;AACnB,OAAO,EAAC,oBAAoB,EAAE,UAAU,EAAE,UAAU,EAAC,MAAM,oBAAoB,CAAC"}

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

@@ -0,0 +1,83 @@
+import type { Graph } from "../core/graph.js";
+import type { NodeId } from "../types/index.js";
+/**
+ * Configuration options for the GRSBM (Greedy Recursive Spectral Bisection) algorithm
+ */
+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;
+}
+/**
+ * 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[];
+}
+/**
+ * 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[];
+}
+/**
+ * GRSBM - Greedy Recursive Spectral Bisection with Modularity
+ *
+ * This algorithm performs hierarchical community detection using spectral
+ * bisection guided by modularity optimization. It provides explainable
+ * 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
+ */
+export declare function grsbm(graph: Graph, config?: GRSBMConfig): GRSBMResult;
+//# sourceMappingURL=grsbm.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grsbm.d.ts","sourceRoot":"","sources":["../../../src/research/grsbm.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,KAAK,EAAC,MAAM,kBAAkB,CAAC;AAC5C,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAC;AAG9C;;GAEG;AACH,MAAM,WAAW,WAAW;IACxB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,+BAA+B;IAC/B,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACrB,oCAAoC;IACpC,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,qCAAqC;IACrC,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,aAAa,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IACxB,oCAAoC;IACpC,IAAI,EAAE,YAAY,CAAC;IACnB,oCAAoC;IACpC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,8CAA8C;IAC9C,WAAW,EAAE,kBAAkB,EAAE,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,qBAAqB,EAAE,MAAM,CAAC;IAC9B,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,gCAAgC;IAChC,cAAc,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,GAAE,WAAgB,GAAG,WAAW,CA4JzE"}