@graphty/algorithms 1.2.0 → 1.3.1

package/src/optimized/direction-optimized-bfs.ts

@@ -0,0 +1,291 @@
+import type {NodeId} from "../types/index.js";
+import {CompactDistanceArray, GraphBitSet} from "./bit-packed.js";
+import {CSRGraph} from "./csr-graph.js";
+
+/**
+ * Options for Direction-Optimized BFS
+ */
+export interface DirectionOptimizedBFSOptions {
+    alpha?: number; // Default: 15 - Controls top-down to bottom-up switch
+    beta?: number; // Default: 18 - Controls bottom-up to top-down switch
+}
+
+/**
+ * Result of BFS traversal
+ */
+export interface BFSResult<TNodeId> {
+    distances: Map<TNodeId, number>;
+    parents: Map<TNodeId, TNodeId | null>;
+    visitedCount: number;
+}
+
+/**
+ * Direction-Optimized Breadth-First Search
+ *
+ * Dynamically switches between top-down and bottom-up search strategies
+ * based on the size of the frontier. Particularly effective for low-diameter
+ * graphs like social networks.
+ *
+ * Based on: Beamer, S., Asanović, K., & Patterson, D. (2012).
+ * "Direction-optimizing breadth-first search." SC'12.
+ */
+export class DirectionOptimizedBFS<TNodeId = NodeId> {
+    private graph: CSRGraph<TNodeId>;
+    private alpha: number;
+    private beta: number;
+
+    // Data structures
+    private parent: Int32Array; // -1 = unvisited, -2 = source, else parent ID
+    private frontier: GraphBitSet; // Current frontier bitmap
+    private nextFrontier: GraphBitSet; // Next level frontier
+    private distances: CompactDistanceArray;
+
+    constructor(graph: CSRGraph<TNodeId>, options?: DirectionOptimizedBFSOptions) {
+        this.graph = graph;
+        this.alpha = options?.alpha ?? 15;
+        this.beta = options?.beta ?? 18;
+
+        const nodeCount = graph.nodeCount();
+        this.parent = new Int32Array(nodeCount).fill(-1);
+        this.frontier = new GraphBitSet(nodeCount);
+        this.nextFrontier = new GraphBitSet(nodeCount);
+        this.distances = new CompactDistanceArray(nodeCount);
+    }
+
+    /**
+   * Perform BFS from a single source
+   */
+    search(source: TNodeId): BFSResult<TNodeId> {
+        const sourceIndex = this.graph.nodeToIndex(source);
+        this.parent[sourceIndex] = -2; // Mark as source
+        this.frontier.add(sourceIndex);
+        this.distances.set(sourceIndex, 0);
+
+        // let currentDistance = 0; // Variable not used
+        // Initialize edgesToCheck to total edges to prevent immediate switch to bottom-up
+        let edgesToCheck = this.graph.edgeCount();
+        let scoutCount = 0; // Will be set after first top-down step
+        let awakeCount = 1; // Number of nodes in current frontier
+        let oldAwakeCount = 0;
+
+        // Direction tracking
+        let useBottomUp = false;
+
+        while (!this.frontier.isEmpty()) {
+            oldAwakeCount = awakeCount;
+
+            if (useBottomUp) {
+                // Check if we should switch back to top-down
+                if (awakeCount >= oldAwakeCount ||
+            awakeCount > this.graph.nodeCount() / this.beta) {
+                    useBottomUp = false;
+                }
+            } else {
+                // Check if we should switch to bottom-up
+                if (scoutCount > edgesToCheck / this.alpha) {
+                    useBottomUp = true;
+                }
+            }
+
+            if (useBottomUp) {
+                awakeCount = this.bottomUpStep();
+            } else {
+                scoutCount = this.topDownStep();
+                awakeCount = this.nextFrontier.size();
+            }
+
+            // Swap frontiers
+            this.frontier.swap(this.nextFrontier);
+            this.nextFrontier.clear();
+
+            // currentDistance++; // Variable not used
+            edgesToCheck = this.calculateEdgesToCheck();
+        }
+
+        return this.buildResult();
+    }
+
+    /**
+   * Top-down BFS step - explore from frontier
+   */
+    private topDownStep(): number {
+        let scoutCount = 0;
+
+        // Iterate through frontier nodes
+        for (const node of this.frontier) {
+            const currentDistance = this.distances.get(node);
+
+            for (const neighbor of this.graph.iterateNeighborIndices(node)) {
+                if (this.parent[neighbor] === -1) {
+                    this.parent[neighbor] = node;
+                    this.distances.set(neighbor, currentDistance + 1);
+                    this.nextFrontier.add(neighbor);
+                    scoutCount += this.graph.outDegreeByIndex(neighbor);
+                }
+            }
+        }
+
+        return scoutCount;
+    }
+
+    /**
+   * Bottom-up BFS step - check unvisited nodes
+   */
+    private bottomUpStep(): number {
+        const nodeCount = this.graph.nodeCount();
+        let awakeCount = 0;
+
+        // Check all unvisited nodes
+        for (let node = 0; node < nodeCount; node++) {
+            if (this.parent[node] === -1) {
+                // Use incoming edges for bottom-up traversal
+                for (const neighbor of this.graph.iterateIncomingNeighborIndices(node)) {
+                    if (this.frontier.has(neighbor)) {
+                        this.parent[node] = neighbor;
+                        const neighborDist = this.distances.get(neighbor);
+                        this.distances.set(node, neighborDist + 1);
+                        this.nextFrontier.add(node);
+                        awakeCount++;
+                        break; // Found a parent, no need to check more
+                    }
+                }
+            }
+        }
+
+        return awakeCount;
+    }
+
+    /**
+   * Calculate edges to check for switching heuristic
+   */
+    private calculateEdgesToCheck(): number {
+        let count = 0;
+        for (const node of this.frontier) {
+            count += this.graph.outDegreeByIndex(node);
+        }
+        return count;
+    }
+
+    /**
+   * Build result map from internal data structures
+   */
+    private buildResult(): BFSResult<TNodeId> {
+        const distances = new Map<TNodeId, number>();
+        const parents = new Map<TNodeId, TNodeId | null>();
+        let visitedCount = 0;
+
+        for (let i = 0; i < this.graph.nodeCount(); i++) {
+            if (this.parent[i] !== -1) {
+                const nodeId = this.graph.indexToNodeId(i);
+                distances.set(nodeId, this.distances.get(i));
+
+                if (this.parent[i] === -2) {
+                    // Source node
+                    parents.set(nodeId, null);
+                } else {
+                    // Regular node with parent
+                    const parentIndex = this.parent[i];
+                    if (parentIndex !== undefined && parentIndex >= 0) {
+                        parents.set(nodeId, this.graph.indexToNodeId(parentIndex));
+                    }
+                }
+
+                visitedCount++;
+            }
+        }
+
+        return {distances, parents, visitedCount};
+    }
+
+    /**
+   * Perform multi-source BFS
+   */
+    searchMultiple(sources: TNodeId[]): BFSResult<TNodeId> {
+    // Initialize multiple sources
+        for (const source of sources) {
+            const sourceIndex = this.graph.nodeToIndex(source);
+            this.parent[sourceIndex] = -2; // Mark as source
+            this.frontier.add(sourceIndex);
+            this.distances.set(sourceIndex, 0);
+        }
+
+        // let currentDistance = 0; // Variable not used
+        let edgesToCheck = 0;
+        let scoutCount = 0;
+
+        // Calculate initial edges to check
+        for (const node of this.frontier) {
+            const degree = this.graph.outDegreeByIndex(node);
+            edgesToCheck += degree;
+            scoutCount += degree;
+        }
+
+        let awakeCount = sources.length;
+        let oldAwakeCount = 0;
+        let useBottomUp = false;
+
+        while (!this.frontier.isEmpty()) {
+            oldAwakeCount = awakeCount;
+
+            if (useBottomUp) {
+                if (awakeCount >= oldAwakeCount ||
+            awakeCount > this.graph.nodeCount() / this.beta) {
+                    useBottomUp = false;
+                }
+            } else {
+                if (scoutCount > edgesToCheck / this.alpha) {
+                    useBottomUp = true;
+                }
+            }
+
+            if (useBottomUp) {
+                awakeCount = this.bottomUpStep();
+            } else {
+                scoutCount = this.topDownStep();
+                awakeCount = this.nextFrontier.size();
+            }
+
+            this.frontier.swap(this.nextFrontier);
+            this.nextFrontier.clear();
+
+            // currentDistance++; // Variable not used
+            edgesToCheck = this.calculateEdgesToCheck();
+        }
+
+        return this.buildResult();
+    }
+
+    /**
+   * Reset internal state for reuse
+   */
+    reset(): void {
+        this.parent.fill(-1);
+        this.frontier.clear();
+        this.nextFrontier.clear();
+        this.distances.clear();
+    }
+}
+
+/**
+ * Convenience function for single-source BFS
+ */
+export function directionOptimizedBFS<TNodeId = NodeId>(
+    graph: CSRGraph<TNodeId>,
+    source: TNodeId,
+    options?: DirectionOptimizedBFSOptions,
+): BFSResult<TNodeId> {
+    const bfs = new DirectionOptimizedBFS(graph, options);
+    return bfs.search(source);
+}
+
+/**
+ * Convenience function for multi-source BFS
+ */
+export function directionOptimizedBFSMultiple<TNodeId = NodeId>(
+    graph: CSRGraph<TNodeId>,
+    sources: TNodeId[],
+    options?: DirectionOptimizedBFSOptions,
+): BFSResult<TNodeId> {
+    const bfs = new DirectionOptimizedBFS(graph, options);
+    return bfs.searchMultiple(sources);
+}

package/src/optimized/graph-adapter.ts

@@ -0,0 +1,200 @@
+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 class GraphAdapter<TNodeId = NodeId> implements ReadonlyGraph<TNodeId> {
+    private csrGraph: CSRGraph<TNodeId>;
+
+    constructor(graph: Graph | ReadonlyGraph<TNodeId>) {
+    // Check if already a CSRGraph
+        if (graph instanceof CSRGraph) {
+            this.csrGraph = graph as CSRGraph<TNodeId>;
+        } else {
+            // Convert to CSR format
+            this.csrGraph = this.convertToCSR(graph);
+        }
+    }
+
+    /**
+   * Convert standard graph to CSR format
+   */
+    private convertToCSR(graph: Graph | ReadonlyGraph<TNodeId>): CSRGraph<TNodeId> {
+        const adjacencyList = new Map<TNodeId, TNodeId[]>();
+        const weights = new Map<string, number>();
+
+        // 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 as {id: TNodeId}).id;
+                const neighbors: TNodeId[] = [];
+
+                const graphTyped = graph as Graph;
+                for (const neighborId of graphTyped.neighbors(nodeId as NodeId)) {
+                    neighbors.push(neighborId as TNodeId);
+
+                    // Get edge weight if available
+                    if ("getEdge" in graph && typeof graph.getEdge === "function") {
+                        const edge = graphTyped.getEdge(nodeId as 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") {
+            // Handle ReadonlyGraph with nodeIds method
+            interface ReadonlyGraphWithNodeIds {
+                nodeIds(): Iterable<TNodeId>;
+                edges?(): Iterable<{source: TNodeId, target: TNodeId, weight?: number}>;
+            }
+            const readonlyGraph = graph as ReadonlyGraphWithNodeIds;
+            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(): number {
+        return this.csrGraph.nodeCount();
+    }
+
+    edgeCount(): number {
+        return this.csrGraph.edgeCount();
+    }
+
+    hasNode(nodeId: TNodeId): boolean {
+        return this.csrGraph.hasNode(nodeId);
+    }
+
+    hasEdge(source: TNodeId, target: TNodeId): boolean {
+        return this.csrGraph.hasEdge(source, target);
+    }
+
+    neighbors(nodeId: TNodeId): IterableIterator<TNodeId> {
+        return this.csrGraph.neighbors(nodeId);
+    }
+
+    outDegree(nodeId: TNodeId): number {
+        return this.csrGraph.outDegree(nodeId);
+    }
+
+    nodes(): IterableIterator<TNodeId> {
+        return this.csrGraph.nodes();
+    }
+
+    /**
+   * Get the underlying CSR graph
+   */
+    getCSRGraph(): CSRGraph<TNodeId> {
+        return this.csrGraph;
+    }
+}
+
+/**
+ * Configuration for graph algorithm optimizations
+ */
+export interface GraphAlgorithmConfig {
+    // Enable optimizations
+    useDirectionOptimizedBFS?: boolean;
+    useCSRFormat?: boolean;
+    useBitPackedStructures?: boolean;
+
+    // Algorithm-specific parameters
+    bfsAlpha?: number;
+    bfsBeta?: number;
+
+    // Memory vs speed tradeoffs
+    preallocateSize?: number;
+    enableCaching?: boolean;
+}
+
+/**
+ * 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: GraphAlgorithmConfig): void {
+    // 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(): GraphAlgorithmConfig {
+    return {};
+}
+
+/**
+ * Check if a graph is already in CSR format
+ */
+export function isCSRGraph<TNodeId = NodeId>(graph: unknown): graph is CSRGraph<TNodeId> {
+    return graph instanceof CSRGraph;
+}
+
+/**
+ * Convert any graph to CSR format
+ */
+export function toCSRGraph<TNodeId = NodeId>(
+    graph: Graph | ReadonlyGraph<TNodeId> | CSRGraph<TNodeId>,
+): CSRGraph<TNodeId> {
+    if (isCSRGraph<TNodeId>(graph)) {
+        return graph;
+    }
+
+    const adapter = new GraphAdapter<TNodeId>(graph);
+    return adapter.getCSRGraph();
+}
+
+/**
+ * Create an optimized graph from nodes and edges
+ */
+export function createOptimizedGraph<TNodeId = NodeId>(
+    nodes: TNodeId[],
+    edges: [TNodeId, TNodeId, number?][],
+): CSRGraph<TNodeId> {
+    const adjacencyList = new Map<TNodeId, TNodeId[]>();
+    const weights = new Map<string, number>();
+
+    // 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);
+}

package/src/optimized/index.ts

@@ -0,0 +1,36 @@
+/**
+ * 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,
+    type GraphAlgorithmConfig,
+} 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";

package/src/research/grsbm.ts

@@ -1,5 +1,6 @@
 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
@@ -95,7 +96,9 @@ export function grsbm(graph: Graph, config: GRSBMConfig = {}): GRSBMResult {
     } = config;
 
     // Set random seed for reproducibility
-    Math.random = seedRandom(seed);
+    const rng = SeededRandom.createGenerator(seed);
+    const originalRandom = Math.random;
+    Math.random = rng;
 
     const nodes = Array.from(graph.nodes());
     const nodeCount = nodes.length;
@@ -228,6 +231,9 @@ export function grsbm(graph: Graph, config: GRSBMConfig = {}): GRSBMResult {
 
     assignClusterIds(root);
 
+    // Restore original random function
+    Math.random = originalRandom;
+
     return {
         root,
         clusters,
@@ -572,18 +578,3 @@ function calculateModularity(graph: Graph, assignment: Map<NodeId, number>): num
     return modularity;
 }
 
-/**
- * Simple seeded random number generator for reproducibility
- */
-function seedRandom(seed: number): () => number {
-    const m = 0x80000000; // 2**31
-    const a = 1103515245;
-    const c = 12345;
-
-    seed = seed % m;
-
-    return function() {
-        seed = ((a * seed) + c) % m;
-        return seed / (m - 1);
-    };
-}

package/src/research/sync.ts

@@ -1,5 +1,6 @@
 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
@@ -60,7 +61,8 @@ export function syncClustering(graph: Graph, config: SynCConfig): SynCResult {
 
     // Set random seed for reproducibility (save original)
     const originalRandom = Math.random;
-    Math.random = seedRandom(seed);
+    const rng = SeededRandom.createGenerator(seed);
+    Math.random = rng;
 
     const nodes = Array.from(graph.nodes());
     const nodeCount = nodes.length;
@@ -436,34 +438,3 @@ function calculateLoss(
     return clusteringLoss + (lambda * reconstructionLoss) + (lambda * regularizationLoss);
 }
 
-/**
- * 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 aVal = a[i];
-        const bVal = b[i];
-        if (aVal !== undefined && bVal !== undefined) {
-            const diff = aVal - bVal;
-            sum += diff * diff;
-        }
-    }
-    return Math.sqrt(sum);
-}
-
-/**
- * Simple seeded random number generator for reproducibility
- */
-function seedRandom(seed: number): () => number {
-    const m = 0x80000000; // 2**31
-    const a = 1103515245;
-    const c = 12345;
-
-    seed = seed % m;
-
-    return function() {
-        seed = ((a * seed) + c) % m;
-        return seed / (m - 1);
-    };
-}

package/src/research/terahac.ts

@@ -15,6 +15,8 @@ export interface TeraHACConfig {
     maxNodes?: number;
     /** Use graph structure for distance calculation */
     useGraphDistance?: boolean;
+    /** Custom warning handler (default: console.warn) */
+    onWarning?: (message: string) => void;
 }
 
 /**
@@ -70,8 +72,14 @@ export function teraHAC(graph: Graph, config: TeraHACConfig = {}): TeraHACResult
         distanceThreshold,
         maxNodes = 10000,
         useGraphDistance = true,
+        onWarning = console.warn,
     } = config;
 
+    // Input validation
+    if (numClusters !== undefined && (numClusters < 1 || !Number.isInteger(numClusters))) {
+        throw new Error("numClusters must be a positive integer");
+    }
+
     const nodes = Array.from(graph.nodes());
     const nodeCount = nodes.length;
 
@@ -80,7 +88,7 @@ export function teraHAC(graph: Graph, config: TeraHACConfig = {}): TeraHACResult
     }
 
     if (nodeCount > maxNodes) {
-        console.warn(`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
@@ -112,7 +120,7 @@ export function teraHAC(graph: Graph, config: TeraHACConfig = {}): TeraHACResult
     let dendrogram: ClusterNode | undefined;
 
     // Perform agglomerative clustering
-    while (clusters.size > 1) {
+    while (clusters.size > 1 && mergeCandidates.length > 0) {
         // Find closest pair of clusters
         const {cluster1Id, cluster2Id, distance} = findClosestPair(mergeCandidates);
 

package/src/types/index.ts

@@ -72,6 +72,12 @@ export interface TraversalOptions {
 
 export interface DijkstraOptions {
     target?: NodeId;
+    /**
+     * Use bidirectional search optimization for point-to-point queries.
+     * Defaults to true for graphs with >10 nodes, false for smaller graphs.
+     * Set explicitly to override automatic heuristic.
+     */
+    bidirectional?: boolean;
 }
 
 export interface BellmanFordResult {
@@ -98,9 +104,11 @@ export interface LouvainOptions {
     resolution?: number; // Resolution parameter (default: 1.0)
     maxIterations?: number; // Maximum iterations (default: 100)
     tolerance?: number; // Improvement tolerance (default: 1e-6)
+    useOptimized?: boolean; // Use optimized implementation for large graphs (default: true for graphs > 50 nodes)
 }
 
 export interface GirvanNewmanOptions {
     maxCommunities?: number; // Stop when this many communities reached
     minCommunitySize?: number; // Minimum size for valid community
+    maxIterations?: number; // Maximum iterations to prevent infinite loops
 }

package/src/utils/algorithm-utilities.ts

@@ -0,0 +1,2 @@
+// Algorithm utility functions will be added here
+export {};