@graphty/algorithms 1.0.1 → 1.1.0

package/src/flow/ford-fulkerson.ts

@@ -0,0 +1,459 @@
+/**
+ * Ford-Fulkerson Algorithm for Maximum Flow
+ *
+ * Finds the maximum flow from source to sink in a flow network
+ * using the method of augmenting paths.
+ */
+
+export interface FlowEdge {
+    from: string;
+    to: string;
+    capacity: number;
+    flow: number;
+}
+
+export interface FlowNetwork {
+    nodes: Set<string>;
+    edges: Map<string, Map<string, FlowEdge>>;
+}
+
+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};
+}
+
+/**
+ * Create residual graph from original graph
+ */
+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) {
+        residual.set(u, new Map());
+        for (const [v, capacity] of neighbors) {
+            const uResidualNeighbors = residual.get(u);
+            if (uResidualNeighbors) {
+                uResidualNeighbors.set(v, capacity);
+            }
+        }
+    }
+
+    return residual;
+}
+
+/**
+ * Find augmenting path using DFS
+ */
+function findAugmentingPath(
+    residualGraph: Map<string, Map<string, number>>,
+    source: string,
+    sink: string,
+): string[] | null {
+    const visited = new Set<string>();
+    const path: string[] = [];
+
+    function dfs(node: string): boolean {
+        if (node === sink) {
+            path.push(node);
+            return true;
+        }
+
+        visited.add(node);
+        path.push(node);
+
+        const neighbors = residualGraph.get(node);
+        if (neighbors) {
+            for (const [neighbor, capacity] of neighbors) {
+                if (!visited.has(neighbor) && capacity > 0) {
+                    if (dfs(neighbor)) {
+                        return true;
+                    }
+                }
+            }
+        }
+
+        path.pop();
+        return false;
+    }
+
+    if (dfs(source)) {
+        return path;
+    }
+
+    return null;
+}
+
+/**
+ * Find augmenting path using BFS (for Edmonds-Karp)
+ */
+function findAugmentingPathBFS(
+    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) {
+            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;
+                    }
+
+                    queue.push(neighbor);
+                }
+            }
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Find minimum cut from source side
+ */
+function findMinCut(
+    residualGraph: Map<string, Map<string, number>>,
+    source: 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];
+    sourceSet.add(source);
+
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current) {
+            continue;
+        }
+
+        const neighbors = residualGraph.get(current);
+
+        if (neighbors) {
+            for (const [neighbor, capacity] of neighbors) {
+                if (!sourceSet.has(neighbor) && capacity > 0) {
+                    sourceSet.add(neighbor);
+                    queue.push(neighbor);
+                }
+            }
+        }
+    }
+
+    // All other nodes are in sink set
+    const sinkSet = new Set<string>();
+    for (const node of residualGraph.keys()) {
+        if (!sourceSet.has(node)) {
+            sinkSet.add(node);
+        }
+    }
+
+    // Find cut edges
+    const cutEdges: [string, string][] = [];
+    for (const u of sourceSet) {
+        const neighbors = residualGraph.get(u);
+        if (neighbors) {
+            for (const v of neighbors.keys()) {
+                if (sinkSet.has(v)) {
+                    cutEdges.push([u, v]);
+                }
+            }
+        }
+    }
+
+    return {source: sourceSet, sink: sinkSet, edges: cutEdges};
+}
+
+/**
+ * Utility function to create a flow network for bipartite matching
+ */
+export function createBipartiteFlowNetwork(
+    leftNodes: string[],
+    rightNodes: string[],
+    edges: [string, 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__";
+
+    // Add source connections to left nodes
+    graph.set(source, new Map());
+    for (const left of leftNodes) {
+        const sourceNeighbors = graph.get(source);
+        if (sourceNeighbors) {
+            sourceNeighbors.set(left, 1);
+        }
+
+        graph.set(left, new Map());
+    }
+
+    // Add edges between left and right
+    for (const [left, right] of edges) {
+        if (!graph.has(left)) {
+            graph.set(left, new Map());
+        }
+
+        const leftNeighbors = graph.get(left);
+        if (leftNeighbors) {
+            leftNeighbors.set(right, 1);
+        }
+    }
+
+    // Add right node connections to sink
+    for (const right of rightNodes) {
+        if (!graph.has(right)) {
+            graph.set(right, new Map());
+        }
+
+        const rightNeighbors = graph.get(right);
+        if (rightNeighbors) {
+            rightNeighbors.set(sink, 1);
+        }
+    }
+
+    graph.set(sink, new Map());
+
+    return {graph, source, sink};
+}
+

package/src/flow/index.ts

@@ -0,0 +1,2 @@
+export * from "./ford-fulkerson.js";
+export * from "./min-cut.js";