@graphty/algorithms 1.2.0 → 1.4.2

package/src/algorithms/traversal/bfs-variants.ts

@@ -0,0 +1,520 @@
+import type { Graph } from "../../core/graph.js";
+import { PriorityQueue } from "../../data-structures/priority-queue.js";
+import { CSRGraph } from "../../optimized/csr-graph.js";
+import { DirectionOptimizedBFS } from "../../optimized/direction-optimized-bfs.js";
+import { toCSRGraph } from "../../optimized/graph-adapter.js";
+import type { NodeId } from "../../types/index.js";
+
+/**
+ * Threshold for switching to CSR-optimized implementations.
+ * Based on benchmarks showing CSR benefits at this scale due to
+ * improved cache locality and reduced memory allocation overhead.
+ */
+const LARGE_GRAPH_THRESHOLD = 10000;
+
+/**
+ * BFS that tracks shortest path counts (for betweenness centrality)
+ *
+ * This variant of BFS computes:
+ * - Shortest distances from source to all reachable nodes
+ * - All predecessors on shortest paths
+ * - Number of shortest paths (sigma)
+ * - Stack of nodes in reverse BFS order
+ * @param graph - The input graph to traverse
+ * @param source - The source node to start BFS from
+ * @param options - Configuration options
+ * @param options.optimized - Whether to use CSR-optimized implementation for large graphs
+ * @returns Object containing distances, predecessors, path counts (sigma), and traversal stack
+ */
+export function bfsWithPathCounting(
+    graph: Graph,
+    source: NodeId,
+    options: { optimized?: boolean } = {},
+): {
+    distances: Map<NodeId, number>;
+    predecessors: Map<NodeId, NodeId[]>;
+    sigma: Map<NodeId, number>;
+    stack: NodeId[];
+} {
+    const useOptimized = options.optimized ?? false;
+
+    // Use CSR format for large graphs
+    if (useOptimized && graph.nodeCount > LARGE_GRAPH_THRESHOLD) {
+        const csrGraph = toCSRGraph(graph);
+        return bfsWithPathCountingCSR(csrGraph, source);
+    }
+
+    const distances = new Map<NodeId, number>();
+    const predecessors = new Map<NodeId, NodeId[]>();
+    const sigma = new Map<NodeId, number>();
+    const stack: NodeId[] = [];
+    const queue: NodeId[] = [];
+
+    // Initialize
+    distances.set(source, 0);
+    sigma.set(source, 1);
+    queue.push(source);
+
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === undefined) {
+            continue;
+        }
+
+        stack.push(current);
+
+        const currentDistance = distances.get(current) ?? 0;
+        const currentSigma = sigma.get(current) ?? 0;
+
+        // Process neighbors
+        const neighbors = graph.neighbors(current);
+        for (const neighbor of neighbors) {
+            // First time visiting this neighbor
+            if (!distances.has(neighbor)) {
+                distances.set(neighbor, currentDistance + 1);
+                queue.push(neighbor);
+            }
+
+            // Found a shortest path to neighbor
+            if (distances.get(neighbor) === currentDistance + 1) {
+                const neighborSigma = sigma.get(neighbor) ?? 0;
+                sigma.set(neighbor, neighborSigma + currentSigma);
+
+                const preds = predecessors.get(neighbor) ?? [];
+                preds.push(current);
+                predecessors.set(neighbor, preds);
+            }
+        }
+    }
+
+    return {
+        distances,
+        predecessors,
+        sigma,
+        stack,
+    };
+}
+
+/**
+ * BFS that only returns distances (for closeness centrality)
+ *
+ * Optimized variant that skips predecessor tracking
+ * @param graph - The input graph to traverse
+ * @param source - The source node to start BFS from
+ * @param cutoff - Maximum distance to explore (optional)
+ * @param options - Configuration options
+ * @param options.optimized - Whether to use CSR-optimized implementation for large graphs
+ * @returns Map of node IDs to their shortest distances from the source
+ */
+export function bfsDistancesOnly(
+    graph: Graph,
+    source: NodeId,
+    cutoff?: number,
+    options: { optimized?: boolean } = {},
+): Map<NodeId, number> {
+    const useOptimized = options.optimized ?? false;
+
+    // Use CSR format for large graphs
+    if (useOptimized && graph.nodeCount > LARGE_GRAPH_THRESHOLD) {
+        const csrGraph = toCSRGraph(graph);
+        return bfsDistancesOnlyCSR(csrGraph, source, cutoff);
+    }
+
+    const distances = new Map<NodeId, number>();
+    const queue: NodeId[] = [];
+
+    distances.set(source, 0);
+    queue.push(source);
+
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === undefined) {
+            continue;
+        }
+
+        const currentDistance = distances.get(current) ?? 0;
+
+        // Stop if we've reached the cutoff distance
+        if (cutoff !== undefined && currentDistance >= cutoff) {
+            continue;
+        }
+
+        const neighbors = graph.neighbors(current);
+        for (const neighbor of neighbors) {
+            if (!distances.has(neighbor)) {
+                distances.set(neighbor, currentDistance + 1);
+                queue.push(neighbor);
+            }
+        }
+    }
+
+    return distances;
+}
+
+/**
+ * BFS for bipartite checking with partition sets
+ *
+ * Returns whether the graph is bipartite and the two partitions if it is
+ * @param graph - The input graph to check for bipartiteness
+ * @returns Object with bipartite status and optional partition sets
+ */
+export function bfsColoringWithPartitions(graph: Graph): {
+    isBipartite: boolean;
+    partitions?: [Set<NodeId>, Set<NodeId>];
+} {
+    const colors = new Map<NodeId, number>();
+    const partitionA = new Set<NodeId>();
+    const partitionB = new Set<NodeId>();
+
+    // Handle disconnected components
+    for (const node of graph.nodes()) {
+        if (!colors.has(node.id)) {
+            const queue: NodeId[] = [node.id];
+            colors.set(node.id, 0);
+            partitionA.add(node.id);
+
+            while (queue.length > 0) {
+                const current = queue.shift();
+                if (current === undefined) {
+                    continue;
+                }
+
+                const currentColor = colors.get(current) ?? 0;
+                const nextColor = 1 - currentColor;
+
+                for (const neighbor of graph.neighbors(current)) {
+                    if (!colors.has(neighbor)) {
+                        colors.set(neighbor, nextColor);
+                        queue.push(neighbor);
+
+                        if (nextColor === 0) {
+                            partitionA.add(neighbor);
+                        } else {
+                            partitionB.add(neighbor);
+                        }
+                    } else if (colors.get(neighbor) === currentColor) {
+                        // Same color as current node - not bipartite
+                        return { isBipartite: false };
+                    }
+                }
+            }
+        }
+    }
+
+    return {
+        isBipartite: true,
+        partitions: [partitionA, partitionB],
+    };
+}
+
+/**
+ * BFS for finding augmenting paths (for flow algorithms)
+ *
+ * Finds a path from source to sink in a residual graph with positive capacity
+ * @param residualGraph - Map representing the residual graph with capacities
+ * @param source - The source node ID
+ * @param sink - The sink node ID
+ * @returns Object with path and capacity, or null if no path exists
+ */
+export function bfsAugmentingPath(
+    residualGraph: Map<string, Map<string, number>>,
+    source: string,
+    sink: string,
+): {
+    path: string[];
+    pathCapacity: number;
+} | null {
+    const parent = new Map<string, string | null>();
+    const queue: string[] = [];
+
+    parent.set(source, null);
+    queue.push(source);
+
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === undefined) {
+            continue;
+        }
+
+        if (current === sink) {
+            // Reconstruct path
+            const path: string[] = [];
+            let node: string | null = sink;
+            let pathCapacity = Infinity;
+
+            while (node !== null) {
+                path.unshift(node);
+                const parentNode = parent.get(node);
+
+                if (parentNode !== null && parentNode !== undefined) {
+                    const capacity = residualGraph.get(parentNode)?.get(node) ?? 0;
+                    pathCapacity = Math.min(pathCapacity, capacity);
+                }
+
+                node = parentNode ?? null;
+            }
+
+            return { path, pathCapacity };
+        }
+
+        const neighbors = residualGraph.get(current);
+        if (neighbors) {
+            for (const [neighbor, capacity] of neighbors) {
+                if (!parent.has(neighbor) && capacity > 0) {
+                    parent.set(neighbor, current);
+                    queue.push(neighbor);
+                }
+            }
+        }
+    }
+
+    return null;
+}
+
+/**
+ * BFS for weighted graphs using priority queue (simplified Dijkstra)
+ *
+ * Returns distances from source using edge weights
+ * @param graph - The input weighted graph to traverse
+ * @param source - The source node to start BFS from
+ * @param cutoff - Maximum distance to explore (optional)
+ * @param options - Configuration options
+ * @param options.optimized - Whether to use CSR-optimized implementation for large graphs
+ * @returns Map of node IDs to their shortest weighted distances from the source
+ */
+export function bfsWeightedDistances(
+    graph: Graph,
+    source: NodeId,
+    cutoff?: number,
+    options: { optimized?: boolean } = {},
+): Map<NodeId, number> {
+    const useOptimized = options.optimized ?? false;
+
+    // Use CSR format for large graphs
+    if (useOptimized && graph.nodeCount > LARGE_GRAPH_THRESHOLD) {
+        const csrGraph = toCSRGraph(graph);
+        return bfsWeightedDistancesCSR(csrGraph, source, cutoff);
+    }
+
+    const distances = new Map<NodeId, number>();
+    const visited = new Set<NodeId>();
+
+    // Use efficient priority queue instead of array-based queue
+    const queue = new PriorityQueue<NodeId>();
+
+    distances.set(source, 0);
+    queue.enqueue(source, 0);
+
+    while (!queue.isEmpty()) {
+        const current = queue.dequeue();
+        if (current === undefined) {
+            continue;
+        }
+
+        const currentDist = distances.get(current) ?? 0;
+
+        if (visited.has(current)) {
+            continue;
+        }
+
+        visited.add(current);
+
+        // Stop if we've reached the cutoff distance
+        if (cutoff !== undefined && currentDist >= cutoff) {
+            continue;
+        }
+
+        for (const neighbor of graph.neighbors(current)) {
+            if (!visited.has(neighbor)) {
+                const edge = graph.getEdge(current, neighbor);
+                const weight = edge?.weight ?? 1;
+                const newDistance = currentDist + weight;
+
+                const oldDistance = distances.get(neighbor);
+                if (oldDistance === undefined || newDistance < oldDistance) {
+                    distances.set(neighbor, newDistance);
+                    queue.enqueue(neighbor, newDistance);
+                }
+            }
+        }
+    }
+
+    return distances;
+}
+
+/**
+ * CSR-optimized version of bfsWithPathCounting
+ * @param graph - The CSR graph representation
+ * @param source - The source node to start BFS from
+ * @returns Object containing distances, predecessors, path counts (sigma), and traversal stack
+ */
+function bfsWithPathCountingCSR(
+    graph: CSRGraph,
+    source: NodeId,
+): {
+    distances: Map<NodeId, number>;
+    predecessors: Map<NodeId, NodeId[]>;
+    sigma: Map<NodeId, number>;
+    stack: NodeId[];
+} {
+    const distances = new Map<NodeId, number>();
+    const predecessors = new Map<NodeId, NodeId[]>();
+    const sigma = new Map<NodeId, number>();
+    const stack: NodeId[] = [];
+    const queue: NodeId[] = [];
+
+    // Initialize
+    distances.set(source, 0);
+    sigma.set(source, 1);
+    queue.push(source);
+
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === undefined) {
+            continue;
+        }
+
+        stack.push(current);
+
+        const currentDistance = distances.get(current) ?? 0;
+        const currentSigma = sigma.get(current) ?? 0;
+
+        // Process neighbors using CSR iteration
+        for (const neighbor of graph.neighbors(current)) {
+            // First time visiting this neighbor
+            if (!distances.has(neighbor)) {
+                distances.set(neighbor, currentDistance + 1);
+                queue.push(neighbor);
+            }
+
+            // Found a shortest path to neighbor
+            if (distances.get(neighbor) === currentDistance + 1) {
+                const neighborSigma = sigma.get(neighbor) ?? 0;
+                sigma.set(neighbor, neighborSigma + currentSigma);
+
+                const preds = predecessors.get(neighbor) ?? [];
+                preds.push(current);
+                predecessors.set(neighbor, preds);
+            }
+        }
+    }
+
+    return {
+        distances,
+        predecessors,
+        sigma,
+        stack,
+    };
+}
+
+/**
+ * CSR-optimized version of bfsDistancesOnly
+ * @param graph - The CSR graph representation
+ * @param source - The source node to start BFS from
+ * @param cutoff - Maximum distance to explore (optional)
+ * @returns Map of node IDs to their shortest distances from the source
+ */
+function bfsDistancesOnlyCSR(graph: CSRGraph, source: NodeId, cutoff?: number): Map<NodeId, number> {
+    // Use Direction-Optimized BFS for best performance
+    if (graph.nodeCount() > LARGE_GRAPH_THRESHOLD) {
+        const dobfs = new DirectionOptimizedBFS(graph);
+        const result = dobfs.search(source);
+
+        // Filter by cutoff if specified
+        if (cutoff !== undefined) {
+            const filtered = new Map<NodeId, number>();
+            for (const [nodeId, distance] of result.distances) {
+                if (distance <= cutoff) {
+                    filtered.set(nodeId, distance);
+                }
+            }
+            return filtered;
+        }
+
+        return result.distances;
+    }
+
+    // Fallback to standard BFS on CSR
+    const distances = new Map<NodeId, number>();
+    const queue: NodeId[] = [];
+
+    distances.set(source, 0);
+    queue.push(source);
+
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === undefined) {
+            continue;
+        }
+
+        const currentDistance = distances.get(current) ?? 0;
+
+        // Stop if we've reached the cutoff distance
+        if (cutoff !== undefined && currentDistance >= cutoff) {
+            continue;
+        }
+
+        for (const neighbor of graph.neighbors(current)) {
+            if (!distances.has(neighbor)) {
+                distances.set(neighbor, currentDistance + 1);
+                queue.push(neighbor);
+            }
+        }
+    }
+
+    return distances;
+}
+
+/**
+ * CSR-optimized version of bfsWeightedDistances
+ * @param graph - The CSR graph representation
+ * @param source - The source node to start BFS from
+ * @param cutoff - Maximum distance to explore (optional)
+ * @returns Map of node IDs to their shortest weighted distances from the source
+ */
+function bfsWeightedDistancesCSR(graph: CSRGraph, source: NodeId, cutoff?: number): Map<NodeId, number> {
+    const distances = new Map<NodeId, number>();
+    const visited = new Set<NodeId>();
+
+    // Use efficient priority queue
+    const queue = new PriorityQueue<NodeId>();
+
+    distances.set(source, 0);
+    queue.enqueue(source, 0);
+
+    while (!queue.isEmpty()) {
+        const current = queue.dequeue();
+        if (current === undefined) {
+            continue;
+        }
+
+        const currentDist = distances.get(current) ?? 0;
+
+        if (visited.has(current)) {
+            continue;
+        }
+
+        visited.add(current);
+
+        // Stop if we've reached the cutoff distance
+        if (cutoff !== undefined && currentDist >= cutoff) {
+            continue;
+        }
+
+        for (const neighbor of graph.neighbors(current)) {
+            if (!visited.has(neighbor)) {
+                // Use actual edge weight from CSR graph, default to 1
+                const weight = graph.getEdgeWeight(current, neighbor) ?? 1;
+                const newDistance = currentDist + weight;
+
+                const oldDistance = distances.get(neighbor);
+                if (oldDistance === undefined || newDistance < oldDistance) {
+                    distances.set(neighbor, newDistance);
+                    queue.enqueue(neighbor, newDistance);
+                }
+            }
+        }
+    }
+
+    return distances;
+}