@graphty/algorithms 1.2.0 → 1.3.1

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
  *
@@ -23,219 +27,6 @@ export interface MaxFlowResult {
     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
  */
@@ -260,7 +51,7 @@ function createResidualGraph(
 /**
  * Find augmenting path using DFS
  */
-function findAugmentingPath(
+function findAugmentingPathDFS(
     residualGraph: Map<string, Map<string, number>>,
     source: string,
     sink: string,
@@ -300,55 +91,57 @@ function findAugmentingPath(
 }
 
 /**
- * Find augmenting path using BFS (for Edmonds-Karp)
+ * Update flow along an augmenting 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;
 }
 
 /**
@@ -405,6 +198,104 @@ function findMinCut(
     return {source: sourceSet, sink: sinkSet, edges: cutEdges};
 }
 
+/**
+ * Core max flow algorithm implementation
+ */
+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
+ */
+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
+ */
+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
  */
@@ -457,3 +348,44 @@ export function createBipartiteFlowNetwork(
     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);
+}

package/src/flow/min-cut.ts

@@ -4,6 +4,8 @@
  * Various algorithms for finding minimum cuts in graphs
  */
 
+import type {Graph} from "../core/graph.js";
+import {graphToMap} from "../utils/graph-converters.js";
 import {fordFulkerson} from "./ford-fulkerson.js";
 
 export interface MinCutResult {
@@ -25,7 +27,7 @@ export interface MinCutResult {
  * Time Complexity: Same as max flow algorithm used
  */
 export function minSTCut(
-    graph: Map<string, Map<string, number>>,
+    graph: Graph,
     source: string,
     sink: string,
 ): MinCutResult {
@@ -44,7 +46,8 @@ export function minSTCut(
 
     // Find actual cut edges and their weights
     for (const [u, v] of flowResult.minCut.edges) {
-        const weight = graph.get(u)?.get(v) ?? 0;
+        const edge = graph.getEdge(u, v);
+        const weight = edge?.weight ?? 0;
         if (weight > 0) {
             cutEdges.push({from: u, to: v, weight});
         }
@@ -62,16 +65,20 @@ export function minSTCut(
  * Stoer-Wagner algorithm for finding global minimum cut
  * Finds the minimum cut that separates the graph into two parts
  *
- * @param graph - Undirected weighted graph
+ * @param graph - Undirected weighted graph - accepts Graph class or Map representation
  * @returns Global minimum cut
  *
  * Time Complexity: O(V³) or O(VE + V² log V) with heap
  */
 export function stoerWagner(
-    graph: Map<string, Map<string, number>>,
+    graph: Graph | Map<string, Map<string, number>>,
 ): MinCutResult {
+    // Convert Graph to Map representation if needed
+    const graphMap = graph instanceof Map ? graph : graphToMap(graph);
     // Convert to undirected if necessary
-    const undirectedGraph = makeUndirected(graph);
+    const undirectedGraph = makeUndirected(graphMap);
+    // Keep a copy for finding cut edges later
+    const originalGraph = makeUndirected(graphMap);
 
     if (undirectedGraph.size < 2) {
         return {
@@ -84,6 +91,7 @@ export function stoerWagner(
 
     // Initialize
     const nodes = Array.from(undirectedGraph.keys());
+    const originalNodes = new Set(nodes); // Keep track of original nodes
     let minCutValue = Infinity;
     let bestPartition = new Set<string>();
     const contractionMap = new Map<string, Set<string>>();
@@ -125,7 +133,7 @@ export function stoerWagner(
     const partition1 = bestPartition;
     const partition2 = new Set<string>();
 
-    for (const node of graph.keys()) {
+    for (const node of originalNodes) {
         if (!partition1.has(node)) {
             partition2.add(node);
         }
@@ -134,7 +142,7 @@ export function stoerWagner(
     // Find cut edges
     const cutEdges: {from: string, to: string, weight: number}[] = [];
     for (const u of partition1) {
-        const neighbors = graph.get(u);
+        const neighbors = originalGraph.get(u);
         if (neighbors) {
             for (const [v, weight] of neighbors) {
                 if (partition2.has(v)) {
@@ -308,22 +316,24 @@ function makeUndirected(
  * Karger's randomized min-cut algorithm
  * Probabilistic algorithm that finds min cut with high probability
  *
- * @param graph - Undirected graph
+ * @param graph - Undirected graph - accepts Graph class or Map representation
  * @param iterations - Number of iterations (higher = better accuracy)
  * @returns Minimum cut found
  *
  * Time Complexity: O(V² * iterations)
  */
 export function kargerMinCut(
-    graph: Map<string, Map<string, number>>,
+    graph: Graph | Map<string, Map<string, number>>,
     iterations = 100,
 ): MinCutResult {
+    // Convert Graph to Map representation if needed
+    const graphMap = graph instanceof Map ? graph : graphToMap(graph);
     let minCutValue = Infinity;
     let bestPartition1 = new Set<string>();
     let bestPartition2 = new Set<string>();
 
     for (let i = 0; i < iterations; i++) {
-        const result = kargerSingleRun(graph);
+        const result = kargerSingleRun(graphMap);
 
         if (result.cutValue < minCutValue) {
             minCutValue = result.cutValue;
@@ -335,7 +345,7 @@ export function kargerMinCut(
     // Find cut edges
     const cutEdges: {from: string, to: string, weight: number}[] = [];
     for (const u of bestPartition1) {
-        const neighbors = graph.get(u);
+        const neighbors = graphMap.get(u);
         if (neighbors) {
             for (const [v, weight] of neighbors) {
                 if (bestPartition2.has(v)) {

package/src/index.ts

@@ -38,3 +38,9 @@ export * from "./research/index.js";
 
 // Data structure exports
 export * from "./data-structures/index.js";
+
+// Optimized algorithm exports
+export * from "./optimized/index.js";
+
+// Note: Configuration exports have been removed.
+// The library now automatically optimizes based on graph size.

package/src/link-prediction/adamic-adar.ts

@@ -1,5 +1,6 @@
 import type {Graph} from "../core/graph.js";
 import type {NodeId} from "../types/index.js";
+import {getCommonNeighbors, getIntermediateNodes} from "../utils/graph-utilities.js";
 import type {LinkPredictionOptions, LinkPredictionScore} from "./common-neighbors.js";
 
 /**
@@ -31,28 +32,24 @@ export function adamicAdarScore(
 
     const {directed = false} = options;
 
-    // Get neighbors
-    const sourceNeighbors = new Set(
-        directed ? Array.from(graph.outNeighbors(source)) : Array.from(graph.neighbors(source)),
-    );
-    const targetNeighbors = new Set(
-        directed ? Array.from(graph.inNeighbors(target)) : Array.from(graph.neighbors(target)),
-    );
+    // Use utility function to get common neighbors
+    // For directed graphs, we want intermediate nodes that form paths source->X->target
+    const commonNeighborsSet = directed ?
+        getIntermediateNodes(graph, source, target) :
+        getCommonNeighbors(graph, source, target, false);
 
     // Calculate Adamic-Adar score
     let score = 0;
-    for (const neighbor of sourceNeighbors) {
-        if (targetNeighbors.has(neighbor)) {
-            const degree = directed ?
-                graph.outDegree(neighbor) : // Use out-degree for directed graphs
-                graph.degree(neighbor); // Use total degree for undirected graphs
-
-            if (degree > 1) {
-                score += 1 / Math.log(degree);
-            } else if (degree === 1) {
-                // For degree 1, we can't use log(1) = 0, so use a small constant
-                score += 1; // or some other reasonable value
-            }
+    for (const neighbor of commonNeighborsSet) {
+        const degree = directed ?
+            graph.outDegree(neighbor) : // Use out-degree for directed graphs
+            graph.degree(neighbor); // Use total degree for undirected graphs
+
+        if (degree > 1) {
+            score += 1 / Math.log(degree);
+        } else if (degree === 1) {
+            // For degree 1, we can't use log(1) = 0, so use a small constant
+            score += 1; // or some other reasonable value
         }
     }
 
@@ -275,17 +272,7 @@ export function compareAdamicAdarWithCommonNeighbors(
         pairs.map(([source, target]) => ({
             source,
             target,
-            score: (() => {
-                const sourceNeighbors = new Set(Array.from(graph.neighbors(source)));
-                const targetNeighbors = new Set(Array.from(graph.neighbors(target)));
-                let count = 0;
-                for (const n of sourceNeighbors) {
-                    if (targetNeighbors.has(n)) {
-                        count++;
-                    }
-                }
-                return count;
-            })(),
+            score: getCommonNeighbors(graph, source, target, options.directed).size,
         }));
 
     const testScores = commonNeighborsPairs(testEdges);