@graphty/algorithms 1.2.0 → 1.4.2

package/src/flow/ford-fulkerson.ts

@@ -1,3 +1,7 @@
+import { bfsAugmentingPath } from "../algorithms/traversal/bfs-variants.js";
+import type { Graph } from "../core/graph.js";
+import { graphToMap } from "../utils/graph-converters.js";
+
 /**
  * Ford-Fulkerson Algorithm for Maximum Flow
  *
@@ -20,228 +24,15 @@ export interface FlowNetwork {
 export interface MaxFlowResult {
     maxFlow: number;
     flowGraph: Map<string, Map<string, number>>;
-    minCut?: {source: Set<string>, sink: Set<string>, edges: [string, string][]};
-}
-
-/**
- * Ford-Fulkerson algorithm using DFS for finding augmenting paths
- *
- * @param graph - Adjacency list representation with capacities
- * @param source - Source node
- * @param sink - Sink node
- * @returns Maximum flow value and flow graph
- *
- * Time Complexity: O(E * f) where f is the maximum flow
- * Space Complexity: O(V + E)
- */
-export function fordFulkerson(
-    graph: Map<string, Map<string, number>>,
-    source: string,
-    sink: string,
-): MaxFlowResult {
-    if (!graph.has(source) || !graph.has(sink)) {
-        return {maxFlow: 0, flowGraph: new Map()};
-    }
-
-    // Create residual graph
-    const residualGraph = createResidualGraph(graph);
-    const flowGraph = new Map<string, Map<string, number>>();
-
-    // Initialize flow graph
-    for (const [u, neighbors] of graph) {
-        flowGraph.set(u, new Map());
-        for (const v of neighbors.keys()) {
-            const uFlowNeighbors = flowGraph.get(u);
-            if (uFlowNeighbors) {
-                uFlowNeighbors.set(v, 0);
-            }
-        }
-    }
-
-    let maxFlow = 0;
-    let path = findAugmentingPath(residualGraph, source, sink);
-
-    while (path !== null) {
-    // Find minimum capacity along the path
-        let pathFlow = Infinity;
-        for (let i = 0; i < path.length - 1; i++) {
-            const u = path[i];
-            const v = path[i + 1];
-            if (!u || !v) {
-                continue;
-            }
-
-            const uEdges = residualGraph.get(u);
-            if (!uEdges) {
-                continue;
-            }
-
-            const capacity = uEdges.get(v);
-            if (capacity !== undefined) {
-                pathFlow = Math.min(pathFlow, capacity);
-            }
-        }
-
-        // Update residual capacities
-        for (let i = 0; i < path.length - 1; i++) {
-            const u = path[i];
-            const v = path[i + 1];
-            if (!u || !v) {
-                continue;
-            }
-
-            // Update residual graph
-            const uEdges = residualGraph.get(u);
-            if (uEdges) {
-                const currentCapacity = uEdges.get(v);
-                if (currentCapacity !== undefined) {
-                    uEdges.set(v, currentCapacity - pathFlow);
-                }
-            }
-
-            // Add reverse edge
-            if (!residualGraph.has(v)) {
-                residualGraph.set(v, new Map());
-            }
-
-            const vEdges = residualGraph.get(v);
-            if (vEdges) {
-                vEdges.set(u, (vEdges.get(u) ?? 0) + pathFlow);
-            }
-
-            // Update flow graph
-            if (graph.get(u)?.has(v)) {
-                const uFlowEdges = flowGraph.get(u);
-                if (uFlowEdges) {
-                    const currentFlow = uFlowEdges.get(v) ?? 0;
-                    uFlowEdges.set(v, currentFlow + pathFlow);
-                }
-            } else if (graph.get(v)?.has(u)) {
-                // This is a reverse flow
-                const vFlowEdges = flowGraph.get(v);
-                if (vFlowEdges) {
-                    const currentFlow = vFlowEdges.get(u) ?? 0;
-                    vFlowEdges.set(u, currentFlow - pathFlow);
-                }
-            }
-        }
-
-        maxFlow += pathFlow;
-        path = findAugmentingPath(residualGraph, source, sink);
-    }
-
-    // Find minimum cut
-    const minCut = findMinCut(residualGraph, source);
-
-    return {maxFlow, flowGraph, minCut};
-}
-
-/**
- * Edmonds-Karp algorithm (Ford-Fulkerson with BFS)
- * More efficient implementation with better time complexity
- *
- * Time Complexity: O(V * E²)
- */
-export function edmondsKarp(
-    graph: Map<string, Map<string, number>>,
-    source: string,
-    sink: string,
-): MaxFlowResult {
-    if (!graph.has(source) || !graph.has(sink)) {
-        return {maxFlow: 0, flowGraph: new Map()};
-    }
-
-    const residualGraph = createResidualGraph(graph);
-    const flowGraph = new Map<string, Map<string, number>>();
-
-    // Initialize flow graph
-    for (const [u, neighbors] of graph) {
-        flowGraph.set(u, new Map());
-        for (const v of neighbors.keys()) {
-            const uFlowNeighbors = flowGraph.get(u);
-            if (uFlowNeighbors) {
-                uFlowNeighbors.set(v, 0);
-            }
-        }
-    }
-
-    let maxFlow = 0;
-    let path = findAugmentingPathBFS(residualGraph, source, sink);
-
-    while (path !== null) {
-        let pathFlow = Infinity;
-        for (let i = 0; i < path.length - 1; i++) {
-            const u = path[i];
-            const v = path[i + 1];
-            if (!u || !v) {
-                continue;
-            }
-
-            const uEdges = residualGraph.get(u);
-            if (!uEdges) {
-                continue;
-            }
-
-            const capacity = uEdges.get(v);
-            if (capacity !== undefined) {
-                pathFlow = Math.min(pathFlow, capacity);
-            }
-        }
-
-        for (let i = 0; i < path.length - 1; i++) {
-            const u = path[i];
-            const v = path[i + 1];
-            if (!u || !v) {
-                continue;
-            }
-
-            const uEdges = residualGraph.get(u);
-            if (uEdges) {
-                const currentCapacity = uEdges.get(v);
-                if (currentCapacity !== undefined) {
-                    uEdges.set(v, currentCapacity - pathFlow);
-                }
-            }
-
-            if (!residualGraph.has(v)) {
-                residualGraph.set(v, new Map());
-            }
-
-            const vEdges = residualGraph.get(v);
-            if (vEdges) {
-                vEdges.set(u, (vEdges.get(u) ?? 0) + pathFlow);
-            }
-
-            if (graph.get(u)?.has(v)) {
-                const uFlowEdges = flowGraph.get(u);
-                if (uFlowEdges) {
-                    const currentFlow = uFlowEdges.get(v) ?? 0;
-                    uFlowEdges.set(v, currentFlow + pathFlow);
-                }
-            } else if (graph.get(v)?.has(u)) {
-                const vFlowEdges = flowGraph.get(v);
-                if (vFlowEdges) {
-                    const currentFlow = vFlowEdges.get(u) ?? 0;
-                    vFlowEdges.set(u, currentFlow - pathFlow);
-                }
-            }
-        }
-
-        maxFlow += pathFlow;
-        path = findAugmentingPathBFS(residualGraph, source, sink);
-    }
-
-    const minCut = findMinCut(residualGraph, source);
-
-    return {maxFlow, flowGraph, minCut};
+    minCut?: { source: Set<string>; sink: Set<string>; edges: [string, string][] };
 }
 
 /**
  * Create residual graph from original graph
+ * @param graph - The original graph with capacity values
+ * @returns A residual graph initialized with the original capacities
  */
-function createResidualGraph(
-    graph: Map<string, Map<string, number>>,
-): Map<string, Map<string, number>> {
+function createResidualGraph(graph: Map<string, Map<string, number>>): Map<string, Map<string, number>> {
     const residual = new Map<string, Map<string, number>>();
 
     for (const [u, neighbors] of graph) {
@@ -259,8 +50,12 @@ function createResidualGraph(
 
 /**
  * Find augmenting path using DFS
+ * @param residualGraph - The residual graph with remaining capacities
+ * @param source - The source node
+ * @param sink - The sink node
+ * @returns An array of nodes forming the path, or null if no path exists
  */
-function findAugmentingPath(
+function findAugmentingPathDFS(
     residualGraph: Map<string, Map<string, number>>,
     source: string,
     sink: string,
@@ -300,64 +95,74 @@ function findAugmentingPath(
 }
 
 /**
- * Find augmenting path using BFS (for Edmonds-Karp)
+ * Update flow along an augmenting path
+ * @param residualGraph - The residual graph to update
+ * @param flowGraph - The flow graph to update with new flow values
+ * @param originalGraph - The original graph for edge direction reference
+ * @param path - The augmenting path to update flow along
+ * @param pathFlow - The amount of flow to push through the path
  */
-function findAugmentingPathBFS(
+function updateFlow(
     residualGraph: Map<string, Map<string, number>>,
-    source: string,
-    sink: string,
-): string[] | null {
-    const parent = new Map<string, string>();
-    const visited = new Set<string>();
-    const queue: string[] = [source];
-    visited.add(source);
-
-    while (queue.length > 0) {
-        const current = queue.shift();
-        if (!current) {
+    flowGraph: Map<string, Map<string, number>>,
+    originalGraph: Map<string, Map<string, number>>,
+    path: string[],
+    pathFlow: number,
+): void {
+    for (let i = 0; i < path.length - 1; i++) {
+        const u = path[i];
+        const v = path[i + 1];
+        if (!u || !v) {
             continue;
         }
 
-        const neighbors = residualGraph.get(current);
-        if (neighbors) {
-            for (const [neighbor, capacity] of neighbors) {
-                if (!visited.has(neighbor) && capacity > 0) {
-                    visited.add(neighbor);
-                    parent.set(neighbor, current);
-
-                    if (neighbor === sink) {
-                        // Reconstruct path
-                        const path: string[] = [];
-                        let node = sink;
-                        while (node !== source) {
-                            path.unshift(node);
-                            const parentNode = parent.get(node);
-                            if (!parentNode) {
-                                break;
-                            }
-
-                            node = parentNode;
-                        }
-                        path.unshift(source);
-                        return path;
-                    }
+        // Update residual graph
+        const uEdges = residualGraph.get(u);
+        if (uEdges) {
+            const currentCapacity = uEdges.get(v);
+            if (currentCapacity !== undefined) {
+                uEdges.set(v, currentCapacity - pathFlow);
+            }
+        }
 
-                    queue.push(neighbor);
-                }
+        // Add reverse edge
+        if (!residualGraph.has(v)) {
+            residualGraph.set(v, new Map());
+        }
+
+        const vEdges = residualGraph.get(v);
+        if (vEdges) {
+            vEdges.set(u, (vEdges.get(u) ?? 0) + pathFlow);
+        }
+
+        // Update flow graph
+        if (originalGraph.get(u)?.has(v)) {
+            const uFlowEdges = flowGraph.get(u);
+            if (uFlowEdges) {
+                const currentFlow = uFlowEdges.get(v) ?? 0;
+                uFlowEdges.set(v, currentFlow + pathFlow);
+            }
+        } else if (originalGraph.get(v)?.has(u)) {
+            // This is a reverse flow
+            const vFlowEdges = flowGraph.get(v);
+            if (vFlowEdges) {
+                const currentFlow = vFlowEdges.get(u) ?? 0;
+                vFlowEdges.set(u, currentFlow - pathFlow);
             }
         }
     }
-
-    return null;
 }
 
 /**
  * Find minimum cut from source side
+ * @param residualGraph - The residual graph after max flow computation
+ * @param source - The source node
+ * @returns The minimum cut partition with source and sink sets and cut edges
  */
 function findMinCut(
     residualGraph: Map<string, Map<string, number>>,
     source: string,
-): {source: Set<string>, sink: Set<string>, edges: [string, string][]} {
+): { source: Set<string>; sink: Set<string>; edges: [string, string][] } {
     // Find all reachable nodes from source in residual graph
     const sourceSet = new Set<string>();
     const queue = [source];
@@ -402,17 +207,136 @@ function findMinCut(
         }
     }
 
-    return {source: sourceSet, sink: sinkSet, edges: cutEdges};
+    return { source: sourceSet, sink: sinkSet, edges: cutEdges };
+}
+
+/**
+ * Core max flow algorithm implementation
+ * @param graph - The graph with capacity values
+ * @param source - The source node
+ * @param sink - The sink node
+ * @param findPath - Function to find an augmenting path in the residual graph
+ * @returns The maximum flow result including flow value, flow graph, and minimum cut
+ */
+function maxFlowCore(
+    graph: Map<string, Map<string, number>>,
+    source: string,
+    sink: string,
+    findPath: (
+        residual: Map<string, Map<string, number>>,
+        src: string,
+        snk: string,
+    ) => { path: string[]; pathCapacity: number } | null,
+): MaxFlowResult {
+    if (!graph.has(source) || !graph.has(sink)) {
+        return { maxFlow: 0, flowGraph: new Map() };
+    }
+
+    // Create residual graph
+    const residualGraph = createResidualGraph(graph);
+    const flowGraph = new Map<string, Map<string, number>>();
+
+    // Initialize flow graph
+    for (const [u, neighbors] of graph) {
+        flowGraph.set(u, new Map());
+        for (const v of neighbors.keys()) {
+            const uFlowNeighbors = flowGraph.get(u);
+            if (uFlowNeighbors) {
+                uFlowNeighbors.set(v, 0);
+            }
+        }
+    }
+
+    let maxFlow = 0;
+    let pathResult = findPath(residualGraph, source, sink);
+
+    while (pathResult !== null) {
+        const { path, pathCapacity } = pathResult;
+
+        // Update flow
+        updateFlow(residualGraph, flowGraph, graph, path, pathCapacity);
+        maxFlow += pathCapacity;
+
+        // Find next path
+        pathResult = findPath(residualGraph, source, sink);
+    }
+
+    // Find minimum cut
+    const minCut = findMinCut(residualGraph, source);
+
+    return { maxFlow, flowGraph, minCut };
+}
+
+/**
+ * Internal implementation of Ford-Fulkerson algorithm using DFS
+ * @param graph - The graph with capacity values
+ * @param source - The source node
+ * @param sink - The sink node
+ * @returns The maximum flow result
+ */
+function fordFulkersonImpl(graph: Map<string, Map<string, number>>, source: string, sink: string): MaxFlowResult {
+    // Adapter function for DFS path finding
+    const findPathDFS = (
+        residual: Map<string, Map<string, number>>,
+        src: string,
+        snk: string,
+    ): { path: string[]; pathCapacity: number } | null => {
+        const path = findAugmentingPathDFS(residual, src, snk);
+        if (!path) {
+            return null;
+        }
+
+        // Calculate path capacity
+        let pathCapacity = Infinity;
+        for (let i = 0; i < path.length - 1; i++) {
+            const u = path[i];
+            const v = path[i + 1];
+            if (u && v) {
+                const capacity = residual.get(u)?.get(v);
+                if (capacity !== undefined) {
+                    pathCapacity = Math.min(pathCapacity, capacity);
+                }
+            }
+        }
+
+        return { path, pathCapacity };
+    };
+
+    return maxFlowCore(graph, source, sink, findPathDFS);
+}
+
+/**
+ * Internal implementation of Edmonds-Karp algorithm
+ * @param graph - The graph with capacity values
+ * @param source - The source node
+ * @param sink - The sink node
+ * @returns The maximum flow result
+ */
+function edmondsKarpImpl(graph: Map<string, Map<string, number>>, source: string, sink: string): MaxFlowResult {
+    // Use BFS variant for path finding
+    const findPathBFS = (
+        residual: Map<string, Map<string, number>>,
+        src: string,
+        snk: string,
+    ): { path: string[]; pathCapacity: number } | null => {
+        return bfsAugmentingPath(residual, src, snk);
+    };
+
+    return maxFlowCore(graph, source, sink, findPathBFS);
 }
 
 /**
  * Utility function to create a flow network for bipartite matching
+ * @param leftNodes - Array of left partition node identifiers
+ * @param rightNodes - Array of right partition node identifiers
+ * @param edges - Array of edges connecting left nodes to right nodes
+ * @returns The flow network graph with source and sink nodes
  */
 export function createBipartiteFlowNetwork(
     leftNodes: string[],
     rightNodes: string[],
     edges: [string, string][],
-): {graph: Map<string, Map<string, number>>, source: string, sink: string} {
+): { graph: Map<string, Map<string, number>>; source: string; sink: string } {
     const graph = new Map<string, Map<string, number>>();
     const source = "__source__";
     const sink = "__sink__";
@@ -454,6 +378,41 @@ export function createBipartiteFlowNetwork(
 
     graph.set(sink, new Map());
 
-    return {graph, source, sink};
+    return { graph, source, sink };
+}
+
+/**
+ * Ford-Fulkerson algorithm using DFS for finding augmenting paths
+ * @param graph - Adjacency list representation with capacities - accepts Graph class or Map
+ * @param source - Source node
+ * @param sink - Sink node
+ * @returns Maximum flow value and flow graph
+ *
+ * Time Complexity: O(E * f) where f is the maximum flow
+ * Space Complexity: O(V + E)
+ */
+export function fordFulkerson(graph: Graph, source: string, sink: string): MaxFlowResult {
+    // Convert Graph to Map representation
+    const graphMap = graphToMap(graph);
+    return fordFulkersonImpl(graphMap, source, sink);
 }
 
+/**
+ * Edmonds-Karp algorithm (Ford-Fulkerson with BFS)
+ * More efficient implementation with better time complexity
+ * @param graph - Adjacency list representation with capacities - accepts Graph class or Map
+ * @param source - Source node
+ * @param sink - Sink node
+ * @returns Maximum flow value and flow graph
+ *
+ * Time Complexity: O(V * E²)
+ */
+export function edmondsKarp(
+    graph: Graph | Map<string, Map<string, number>>,
+    source: string,
+    sink: string,
+): MaxFlowResult {
+    // Convert Graph to Map representation if needed
+    const graphMap = graph instanceof Map ? graph : graphToMap(graph);
+    return edmondsKarpImpl(graphMap, source, sink);
+}