@graphty/algorithms 1.2.0 → 1.4.2

package/src/flow/min-cut.ts

@@ -4,19 +4,20 @@
  * Various algorithms for finding minimum cuts in graphs
  */
 
-import {fordFulkerson} from "./ford-fulkerson.js";
+import type { Graph } from "../core/graph.js";
+import { graphToMap } from "../utils/graph-converters.js";
+import { fordFulkerson } from "./ford-fulkerson.js";
 
 export interface MinCutResult {
     cutValue: number;
     partition1: Set<string>;
     partition2: Set<string>;
-    cutEdges: {from: string, to: string, weight: number}[];
+    cutEdges: { from: string; to: string; weight: number }[];
 }
 
 /**
  * Find minimum s-t cut using max flow
  * The minimum cut value equals the maximum flow value (max-flow min-cut theorem)
- *
  * @param graph - Weighted graph
  * @param source - Source node
  * @param sink - Sink node
@@ -24,11 +25,7 @@ export interface MinCutResult {
  *
  * Time Complexity: Same as max flow algorithm used
  */
-export function minSTCut(
-    graph: Map<string, Map<string, number>>,
-    source: string,
-    sink: string,
-): MinCutResult {
+export function minSTCut(graph: Graph, source: string, sink: string): MinCutResult {
     const flowResult = fordFulkerson(graph, source, sink);
 
     if (!flowResult.minCut) {
@@ -40,13 +37,14 @@ export function minSTCut(
         };
     }
 
-    const cutEdges: {from: string, to: string, weight: number}[] = [];
+    const cutEdges: { from: string; to: string; weight: number }[] = [];
 
     // 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});
+            cutEdges.push({ from: u, to: v, weight });
         }
     }
 
@@ -61,17 +59,18 @@ 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>>,
-): MinCutResult {
+export function stoerWagner(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 +83,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,20 +125,20 @@ 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);
         }
     }
 
     // Find cut edges
-    const cutEdges: {from: string, to: string, weight: number}[] = [];
+    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)) {
-                    cutEdges.push({from: u, to: v, weight});
+                    cutEdges.push({ from: u, to: v, weight });
                 }
             }
         }
@@ -154,11 +154,14 @@ export function stoerWagner(
 
 /**
  * Minimum cut phase of Stoer-Wagner algorithm
+ * @param graph - The undirected weighted graph
+ * @param nodes - Array of remaining nodes in the graph
+ * @returns The cut result with last two nodes, cut value, and partition
  */
 function minimumCutPhase(
     graph: Map<string, Map<string, number>>,
     nodes: string[],
-): {s: string, t: string, value: number, partition: string[]} {
+): { s: string; t: string; value: number; partition: string[] } {
     const n = nodes.length;
     const weight = new Map<string, number>();
     const added = new Set<string>();
@@ -172,7 +175,7 @@ function minimumCutPhase(
     // Start with arbitrary node
     let lastAdded = nodes[0];
     if (!lastAdded) {
-        return {s: "", t: "", value: 0, partition: []};
+        return { s: "", t: "", value: 0, partition: [] };
     }
 
     added.add(lastAdded);
@@ -180,7 +183,7 @@ function minimumCutPhase(
 
     // Add remaining nodes
     for (let i = 1; i < n; i++) {
-    // Update weights
+        // Update weights
         if (!lastAdded) {
             continue;
         }
@@ -217,7 +220,7 @@ function minimumCutPhase(
     const s = order[order.length - 2];
     const t = order[order.length - 1];
     if (!s || !t) {
-        return {s: "", t: "", value: 0, partition: []};
+        return { s: "", t: "", value: 0, partition: [] };
     }
 
     const cutValue = weight.get(t) ?? 0;
@@ -225,18 +228,17 @@ function minimumCutPhase(
     // Partition is all nodes except t
     const partition = order.slice(0, -1);
 
-    return {s, t, value: cutValue, partition};
+    return { s, t, value: cutValue, partition };
 }
 
 /**
  * Contract two nodes in the graph
+ * @param graph - The graph to modify by contracting nodes
+ * @param nodes - Array of nodes to update after contraction
+ * @param s - The node to keep after contraction
+ * @param t - The node to merge into s
  */
-function contractNodes(
-    graph: Map<string, Map<string, number>>,
-    nodes: string[],
-    s: string,
-    t: string,
-): void {
+function contractNodes(graph: Map<string, Map<string, number>>, nodes: string[], s: string, t: string): void {
     // Merge t into s
     const sNeighbors = graph.get(s);
     const tNeighbors = graph.get(t);
@@ -271,10 +273,10 @@ function contractNodes(
 
 /**
  * Convert directed graph to undirected
+ * @param graph - The directed graph to convert
+ * @returns An undirected graph with edges in both directions
  */
-function makeUndirected(
-    graph: Map<string, Map<string, number>>,
-): Map<string, Map<string, number>> {
+function makeUndirected(graph: Map<string, Map<string, number>>): Map<string, Map<string, number>> {
     const undirected = new Map<string, Map<string, number>>();
 
     // Initialize all nodes
@@ -307,23 +309,21 @@ 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>>,
-    iterations = 100,
-): MinCutResult {
+export function kargerMinCut(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;
@@ -333,13 +333,13 @@ export function kargerMinCut(
     }
 
     // Find cut edges
-    const cutEdges: {from: string, to: string, weight: number}[] = [];
+    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)) {
-                    cutEdges.push({from: u, to: v, weight});
+                    cutEdges.push({ from: u, to: v, weight });
                 }
             }
         }
@@ -355,10 +355,14 @@ export function kargerMinCut(
 
 /**
  * Single run of Karger's algorithm
+ * @param graph - The undirected weighted graph
+ * @returns The cut result with cut value and two partitions
  */
-function kargerSingleRun(
-    graph: Map<string, Map<string, number>>,
-): {cutValue: number, partition1: Set<string>, partition2: Set<string>} {
+function kargerSingleRun(graph: Map<string, Map<string, number>>): {
+    cutValue: number;
+    partition1: Set<string>;
+    partition2: Set<string>;
+} {
     // Create a copy of the graph
     const workGraph = new Map<string, Map<string, number>>();
     const superNodes = new Map<string, Set<string>>();
@@ -371,11 +375,12 @@ function kargerSingleRun(
 
     // Contract until 2 nodes remain
     while (workGraph.size > 2) {
-    // Pick random edge
+        // Pick random edge
         const edges: [string, string, number][] = [];
         for (const [u, neighbors] of workGraph) {
             for (const [v, weight] of neighbors) {
-                if (u < v) { // Avoid duplicates
+                if (u < v) {
+                    // Avoid duplicates
                     edges.push([u, v, weight]);
                 }
             }
@@ -430,6 +435,10 @@ function kargerSingleRun(
 
 /**
  * Contract edge in Karger's algorithm
+ * @param graph - The working graph to modify
+ * @param superNodes - Map tracking which original nodes are in each super node
+ * @param u - First endpoint of the edge to contract
+ * @param v - Second endpoint of the edge to contract (merged into u)
  */
 function contractKarger(
     graph: Map<string, Map<string, number>>,
@@ -479,4 +488,3 @@ function contractKarger(
     graph.delete(v);
     superNodes.delete(v);
 }
-

package/src/index.ts

@@ -1,12 +1,13 @@
 /**
- * @graphty/algorithms - Graph algorithms library for browser environments
+ * graphty/algorithms - Graph algorithms library for browser environments
  *
  * A comprehensive TypeScript library implementing fundamental graph algorithms
  * optimized for browser environments and visualization applications.
+ * @module
  */
 
 // Core exports
-export {Graph} from "./core/graph.js";
+export { Graph } from "./core/graph.js";
 
 // Type exports
 export type {
@@ -38,3 +39,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,6 +1,7 @@
-import type {Graph} from "../core/graph.js";
-import type {NodeId} from "../types/index.js";
-import type {LinkPredictionOptions, LinkPredictionScore} from "./common-neighbors.js";
+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";
 
 /**
  * Adamic-Adar Index link prediction implementation
@@ -18,6 +19,11 @@ import type {LinkPredictionOptions, LinkPredictionScore} from "./common-neighbor
 
 /**
  * Calculate Adamic-Adar index for a pair of nodes
+ * @param graph - The input graph
+ * @param source - The source node ID
+ * @param target - The target node ID
+ * @param options - Link prediction options
+ * @returns The Adamic-Adar score for the node pair
  */
 export function adamicAdarScore(
     graph: Graph,
@@ -29,30 +35,26 @@ export function adamicAdarScore(
         return 0;
     }
 
-    const {directed = false} = options;
+    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
         }
     }
 
@@ -61,16 +63,12 @@ export function adamicAdarScore(
 
 /**
  * Calculate Adamic-Adar scores for all possible node pairs
+ * @param graph - The input graph
+ * @param options - Link prediction options
+ * @returns Array of link prediction scores sorted by score descending
  */
-export function adamicAdarPrediction(
-    graph: Graph,
-    options: LinkPredictionOptions = {},
-): LinkPredictionScore[] {
-    const {
-        directed = false,
-        includeExisting = false,
-        topK,
-    } = options;
+export function adamicAdarPrediction(graph: Graph, options: LinkPredictionOptions = {}): LinkPredictionScore[] {
+    const { directed = false, includeExisting = false, topK } = options;
 
     const scores: LinkPredictionScore[] = [];
     const nodes = Array.from(graph.nodes()).map((n) => n.id);
@@ -89,14 +87,14 @@ export function adamicAdarPrediction(
                 continue;
             }
 
-            const score = adamicAdarScore(graph, source, target, {directed});
+            const score = adamicAdarScore(graph, source, target, { directed });
 
             if (score > 0) {
-                scores.push({source, target, score});
+                scores.push({ source, target, score });
 
                 // For undirected graphs, also add the reverse pair
                 if (!directed && source !== target) {
-                    scores.push({source: target, target: source, score});
+                    scores.push({ source: target, target: source, score });
                 }
             }
         }
@@ -115,6 +113,10 @@ export function adamicAdarPrediction(
 
 /**
  * Calculate Adamic-Adar scores for specific node pairs
+ * @param graph - The input graph
+ * @param pairs - Array of node ID pairs to calculate scores for
+ * @param options - Link prediction options
+ * @returns Array of link prediction scores for the specified pairs
  */
 export function adamicAdarForPairs(
     graph: Graph,
@@ -130,22 +132,21 @@ export function adamicAdarForPairs(
 
 /**
  * Get top Adamic-Adar candidates for link prediction for a specific node
+ * @param graph - The input graph
+ * @param node - The node ID to get candidates for
+ * @param options - Link prediction options with optional candidate list
+ * @returns Array of top link prediction candidates sorted by score descending
  */
 export function getTopAdamicAdarCandidatesForNode(
     graph: Graph,
     node: NodeId,
-    options: LinkPredictionOptions & {candidates?: NodeId[]} = {},
+    options: LinkPredictionOptions & { candidates?: NodeId[] } = {},
 ): LinkPredictionScore[] {
     if (!graph.hasNode(node)) {
         return [];
     }
 
-    const {
-        directed = false,
-        includeExisting = false,
-        topK = 10,
-        candidates,
-    } = options;
+    const { directed = false, includeExisting = false, topK = 10, candidates } = options;
 
     const scores: LinkPredictionScore[] = [];
     const targetNodes = candidates ?? Array.from(graph.nodes()).map((n) => n.id);
@@ -160,10 +161,10 @@ export function getTopAdamicAdarCandidatesForNode(
             continue;
         }
 
-        const score = adamicAdarScore(graph, node, target, {directed});
+        const score = adamicAdarScore(graph, node, target, { directed });
 
         if (score > 0) {
-            scores.push({source: node, target, score});
+            scores.push({ source: node, target, score });
         }
     }
 
@@ -175,6 +176,11 @@ export function getTopAdamicAdarCandidatesForNode(
 
 /**
  * Calculate precision and recall for Adamic-Adar link prediction evaluation
+ * @param trainingGraph - The training graph without test edges
+ * @param testEdges - Array of node pairs that are actual edges
+ * @param nonEdges - Array of node pairs that are not edges
+ * @param options - Link prediction options
+ * @returns Evaluation metrics including precision, recall, F1 score, and AUC
  */
 export function evaluateAdamicAdar(
     trainingGraph: Graph,
@@ -182,19 +188,19 @@ export function evaluateAdamicAdar(
     nonEdges: [NodeId, NodeId][],
     options: LinkPredictionOptions = {},
 ): {
-        precision: number;
-        recall: number;
-        f1Score: number;
-        auc: number;
-    } {
+    precision: number;
+    recall: number;
+    f1Score: number;
+    auc: number;
+} {
     // Get scores for test edges and non-edges
     const testScores = adamicAdarForPairs(trainingGraph, testEdges, options);
     const nonEdgeScores = adamicAdarForPairs(trainingGraph, nonEdges, options);
 
     // Combine and sort all scores
     const allScores = [
-        ... testScores.map((s) => ({... s, isActualEdge: true})),
-        ... nonEdgeScores.map((s) => ({... s, isActualEdge: false})),
+        ...testScores.map((s) => ({ ...s, isActualEdge: true })),
+        ...nonEdgeScores.map((s) => ({ ...s, isActualEdge: false })),
     ].sort((a, b) => b.score - a.score);
 
     // Calculate precision and recall at different thresholds
@@ -215,7 +221,7 @@ export function evaluateAdamicAdar(
 
         const precision = truePositives / (truePositives + falsePositives);
         const recall = truePositives / totalPositives;
-        const f1 = precision + recall > 0 ? 2 * (precision * recall) / (precision + recall) : 0;
+        const f1 = precision + recall > 0 ? (2 * (precision * recall)) / (precision + recall) : 0;
 
         if (f1 > bestF1) {
             bestF1 = f1;
@@ -254,6 +260,11 @@ export function evaluateAdamicAdar(
 
 /**
  * Compare Adamic-Adar with Common Neighbors for the same dataset
+ * @param graph - The input graph
+ * @param testEdges - Array of node pairs that are actual edges
+ * @param nonEdges - Array of node pairs that are not edges
+ * @param options - Link prediction options
+ * @returns Comparison of evaluation metrics for both algorithms
  */
 export function compareAdamicAdarWithCommonNeighbors(
     graph: Graph,
@@ -261,39 +272,29 @@ export function compareAdamicAdarWithCommonNeighbors(
     nonEdges: [NodeId, NodeId][],
     options: LinkPredictionOptions = {},
 ): {
-        adamicAdar: ReturnType<typeof evaluateAdamicAdar>;
-        commonNeighbors: {
-            precision: number;
-            recall: number;
-            f1Score: number;
-            auc: number;
-        };
-    } {
+    adamicAdar: ReturnType<typeof evaluateAdamicAdar>;
+    commonNeighbors: {
+        precision: number;
+        recall: number;
+        f1Score: number;
+        auc: number;
+    };
+} {
     // Import common neighbors evaluation function
     // Since we're using ES modules, we can't use require. Instead, we'll implement a simple version here
     const commonNeighborsPairs = (pairs: [NodeId, NodeId][]): LinkPredictionScore[] =>
         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);
     const nonEdgeScores = commonNeighborsPairs(nonEdges);
 
     const allScores = [
-        ... testScores.map((s) => ({... s, isActualEdge: true})),
-        ... nonEdgeScores.map((s) => ({... s, isActualEdge: false})),
+        ...testScores.map((s) => ({ ...s, isActualEdge: true })),
+        ...nonEdgeScores.map((s) => ({ ...s, isActualEdge: false })),
     ].sort((a, b) => b.score - a.score);
 
     let truePositives = 0;
@@ -312,7 +313,7 @@ export function compareAdamicAdarWithCommonNeighbors(
 
         const precision = truePositives / (truePositives + falsePositives);
         const recall = truePositives / totalPositives;
-        const f1 = precision + recall > 0 ? 2 * (precision * recall) / (precision + recall) : 0;
+        const f1 = precision + recall > 0 ? (2 * (precision * recall)) / (precision + recall) : 0;
         if (f1 > bestF1) {
             bestF1 = f1;
             bestPrecision = precision;