@graphty/algorithms 1.2.0 → 1.4.2

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

@@ -0,0 +1,310 @@
+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;
+
+    /**
+     * Creates a new DirectionOptimizedBFS instance.
+     * @param graph - The CSR graph to perform BFS on
+     * @param options - Optional configuration for switching thresholds
+     */
+    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 node.
+     * @param source - The source node ID to start the BFS from
+     * @returns The BFS result containing distances and parent pointers
+     */
+    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.
+     * @returns The scout count (total degree of newly discovered nodes)
+     */
+    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 for frontier neighbors.
+     * @returns The number of newly discovered 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.
+     * @returns The total number of outgoing edges from frontier nodes
+     */
+    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.
+     * @returns The BFS result containing distances and parent pointers
+     */
+    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 from multiple source nodes.
+     * @param sources - Array of source node IDs to start the BFS from
+     * @returns The BFS result containing distances and parent pointers
+     */
+    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.
+ * @param graph - The CSR graph to perform BFS on
+ * @param source - The source node ID to start the BFS from
+ * @param options - Optional configuration for switching thresholds
+ * @returns The BFS result containing distances and parent pointers
+ */
+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.
+ * @param graph - The CSR graph to perform BFS on
+ * @param sources - Array of source node IDs to start the BFS from
+ * @param options - Optional configuration for switching thresholds
+ * @returns The BFS result containing distances and parent pointers
+ */
+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,248 @@
+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>;
+
+    /**
+     * Creates a new GraphAdapter that wraps or converts a graph to CSR format.
+     * @param graph - The graph to adapt (either standard Graph or ReadonlyGraph)
+     */
+    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.
+     * @param graph - The graph to convert
+     * @returns A new CSRGraph instance
+     */
+    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
+    /**
+     * Get the total number of nodes in the graph.
+     * @returns The number of nodes
+     */
+    nodeCount(): number {
+        return this.csrGraph.nodeCount();
+    }
+
+    /**
+     * Get the total number of edges in the graph.
+     * @returns The number of edges
+     */
+    edgeCount(): number {
+        return this.csrGraph.edgeCount();
+    }
+
+    /**
+     * Check if a node exists in the graph.
+     * @param nodeId - The node ID to check
+     * @returns True if the node exists, false otherwise
+     */
+    hasNode(nodeId: TNodeId): boolean {
+        return this.csrGraph.hasNode(nodeId);
+    }
+
+    /**
+     * Check if an edge exists between two nodes.
+     * @param source - The source node ID
+     * @param target - The target node ID
+     * @returns True if the edge exists, false otherwise
+     */
+    hasEdge(source: TNodeId, target: TNodeId): boolean {
+        return this.csrGraph.hasEdge(source, target);
+    }
+
+    /**
+     * Get neighbors of a node as node IDs.
+     * @param nodeId - The node ID to get neighbors for
+     * @returns An iterator over neighbor node IDs
+     */
+    neighbors(nodeId: TNodeId): IterableIterator<TNodeId> {
+        return this.csrGraph.neighbors(nodeId);
+    }
+
+    /**
+     * Get the out-degree (number of outgoing edges) of a node.
+     * @param nodeId - The node ID to get the out-degree for
+     * @returns The number of outgoing edges from the node
+     */
+    outDegree(nodeId: TNodeId): number {
+        return this.csrGraph.outDegree(nodeId);
+    }
+
+    /**
+     * Get all nodes in the graph.
+     * @returns An iterator over all node IDs
+     */
+    nodes(): IterableIterator<TNodeId> {
+        return this.csrGraph.nodes();
+    }
+
+    /**
+     * Get the underlying CSR graph.
+     * @returns The CSRGraph instance used internally
+     */
+    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
+ * @param _config - The configuration object (ignored)
+ */
+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
+ * @returns An empty configuration object
+ */
+export function getOptimizationConfig(): GraphAlgorithmConfig {
+    return {};
+}
+
+/**
+ * Check if a graph is already in CSR format.
+ * @param graph - The graph to check
+ * @returns True if the graph is a CSRGraph instance
+ */
+export function isCSRGraph<TNodeId = NodeId>(graph: unknown): graph is CSRGraph<TNodeId> {
+    return graph instanceof CSRGraph;
+}
+
+/**
+ * Convert any graph to CSR format.
+ * @param graph - The graph to convert
+ * @returns A CSRGraph instance (either the original if already CSR, or a new converted one)
+ */
+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.
+ * @param nodes - Array of node IDs
+ * @param edges - Array of edge tuples [source, target, weight?]
+ * @returns A new CSRGraph instance
+ */
+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,34 @@
+/**
+ * Optimized graph algorithm implementations
+ *
+ * High-performance implementations using:
+ * - Direction-Optimized BFS
+ * - Compressed Sparse Row (CSR) format
+ * - Bit-packed data structures
+ */
+
+// Configuration and optimization control
+// These deprecated functions are intentionally re-exported for backward compatibility
+// eslint-disable-next-line @typescript-eslint/no-deprecated
+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";