@graphty/algorithms 1.1.0 → 1.3.1

package/src/utils/graph-converters.ts

@@ -0,0 +1,241 @@
+import {Graph} from "../core/graph.js";
+import type {NodeId} from "../types/index.js";
+
+/**
+ * Convert Graph class to Map representation
+ * Used by community detection and flow algorithms
+ */
+export function graphToMap(graph: Graph): Map<string, Map<string, number>> {
+    const map = new Map<string, Map<string, number>>();
+
+    // Initialize all nodes
+    for (const node of graph.nodes()) {
+        map.set(String(node.id), new Map());
+    }
+
+    // Add edges with weights
+    for (const edge of graph.edges()) {
+        const source = String(edge.source);
+        const target = String(edge.target);
+        const weight = edge.weight ?? 1;
+
+        const sourceMap = map.get(source);
+        if (sourceMap) {
+            sourceMap.set(target, weight);
+        }
+
+        // For undirected graphs, add reverse edge
+        if (!graph.isDirected) {
+            const targetMap = map.get(target);
+            if (targetMap) {
+                targetMap.set(source, weight);
+            }
+        }
+    }
+
+    return map;
+}
+
+/**
+ * Convert Map representation to Graph class
+ */
+export function mapToGraph(
+    map: Map<string, Map<string, number>>,
+    isDirected = true,
+): Graph {
+    const graph = new Graph({directed: isDirected});
+
+    // Add all nodes first
+    for (const node of map.keys()) {
+        graph.addNode(node);
+    }
+
+    // Add edges
+    const processedEdges = new Set<string>();
+
+    for (const [source, neighbors] of map) {
+        for (const [target, weight] of neighbors) {
+            const edgeKey = isDirected ? `${source}->${target}` : [source, target].sort().join("-");
+
+            // Skip if we've already processed this edge (for undirected graphs)
+            if (!isDirected && processedEdges.has(edgeKey)) {
+                continue;
+            }
+
+            graph.addEdge(source, target, weight);
+            processedEdges.add(edgeKey);
+        }
+    }
+
+    return graph;
+}
+
+/**
+ * Adapter for using Graph algorithms with Map representation
+ * Implements a subset of Graph interface methods needed by algorithms
+ */
+export class GraphAdapter {
+    private map: Map<string, Map<string, number>>;
+    public readonly isDirected: boolean;
+
+    constructor(map: Map<string, Map<string, number>>, isDirected = true) {
+        this.map = map;
+        this.isDirected = isDirected;
+    }
+
+    /**
+     * Get all nodes
+     */
+    nodes(): {id: NodeId}[] {
+        return Array.from(this.map.keys()).map((id) => ({id}));
+    }
+
+    /**
+     * Get node count
+     */
+    get nodeCount(): number {
+        return this.map.size;
+    }
+
+    /**
+     * Check if node exists
+     */
+    hasNode(nodeId: NodeId): boolean {
+        return this.map.has(String(nodeId));
+    }
+
+    /**
+     * Get neighbors of a node
+     */
+    neighbors(nodeId: NodeId): NodeId[] {
+        const neighbors = this.map.get(String(nodeId));
+        if (!neighbors) {
+            return [];
+        }
+
+        return Array.from(neighbors.keys());
+    }
+
+    /**
+     * Get edge between two nodes
+     */
+    getEdge(source: NodeId, target: NodeId): {source: NodeId, target: NodeId, weight?: number} | null {
+        const sourceNeighbors = this.map.get(String(source));
+        if (!sourceNeighbors) {
+            return null;
+        }
+
+        const weight = sourceNeighbors.get(String(target));
+        if (weight === undefined) {
+            return null;
+        }
+
+        return {source, target, weight};
+    }
+
+    /**
+     * Check if edge exists
+     */
+    hasEdge(source: NodeId, target: NodeId): boolean {
+        const sourceNeighbors = this.map.get(String(source));
+        if (!sourceNeighbors) {
+            return false;
+        }
+
+        return sourceNeighbors.has(String(target));
+    }
+
+    /**
+     * Get all edges
+     */
+    edges(): {source: NodeId, target: NodeId, weight?: number}[] {
+        const edges: {source: NodeId, target: NodeId, weight?: number}[] = [];
+        const processedEdges = new Set<string>();
+
+        for (const [source, neighbors] of this.map) {
+            for (const [target, weight] of neighbors) {
+                const edgeKey = this.isDirected ? `${source}->${target}` : [source, target].sort().join("-");
+
+                // Skip if we've already processed this edge (for undirected graphs)
+                if (!this.isDirected && processedEdges.has(edgeKey)) {
+                    continue;
+                }
+
+                edges.push({source, target, weight});
+                processedEdges.add(edgeKey);
+            }
+        }
+
+        return edges;
+    }
+
+    /**
+     * Get edge count
+     */
+    get edgeCount(): number {
+        if (this.isDirected) {
+            let count = 0;
+            for (const neighbors of this.map.values()) {
+                count += neighbors.size;
+            }
+            return count;
+        }
+
+        // For undirected graphs, count each edge once
+        let count = 0;
+        const counted = new Set<string>();
+
+        for (const [source, neighbors] of this.map) {
+            for (const target of neighbors.keys()) {
+                const edgeKey = [source, target].sort().join("-");
+                if (!counted.has(edgeKey)) {
+                    counted.add(edgeKey);
+                    count++;
+                }
+            }
+        }
+        return count;
+    }
+
+    /**
+     * Get node degree
+     */
+    degree(nodeId: NodeId): number {
+        const neighbors = this.map.get(String(nodeId));
+        return neighbors ? neighbors.size : 0;
+    }
+
+    /**
+     * Get in-degree (for directed graphs)
+     */
+    inDegree(nodeId: NodeId): number {
+        if (!this.isDirected) {
+            return this.degree(nodeId);
+        }
+
+        let count = 0;
+        const targetId = String(nodeId);
+
+        for (const neighbors of this.map.values()) {
+            if (neighbors.has(targetId)) {
+                count++;
+            }
+        }
+
+        return count;
+    }
+
+    /**
+     * Get out-degree (for directed graphs)
+     */
+    outDegree(nodeId: NodeId): number {
+        return this.degree(nodeId);
+    }
+
+    /**
+     * Get underlying map representation
+     */
+    getMap(): Map<string, Map<string, number>> {
+        return this.map;
+    }
+}

package/src/utils/graph-utilities.ts

@@ -0,0 +1,199 @@
+import {Graph} from "../core/graph.js";
+import type {NodeId} from "../types/index.js";
+
+/**
+ * Reconstructs a path from source to target using a predecessor map
+ * @param target - The target node
+ * @param predecessor - Map of node to its predecessor in the path
+ * @returns Array of nodes from source to target, or empty array if no path exists
+ */
+export function reconstructPath<T>(
+    target: T,
+    predecessor: Map<T, T | null>,
+): T[] {
+    const path: T[] = [];
+    let current: T | null = target;
+
+    // Build path backwards from target to source
+    while (current !== null) {
+        path.unshift(current);
+        const pred = predecessor.get(current);
+        if (pred === undefined) {
+            // No path exists
+            return [];
+        }
+
+        current = pred;
+    }
+
+    return path;
+}
+
+/**
+ * Find common neighbors between two nodes
+ * @param graph - The graph
+ * @param source - First node
+ * @param target - Second node
+ * @param directed - Whether to consider edge direction
+ * @returns Set of common neighbor node IDs
+ */
+export function getCommonNeighbors(
+    graph: Graph,
+    source: NodeId,
+    target: NodeId,
+    directed = false,
+): Set<NodeId> {
+    const sourceNeighbors = new Set(
+        directed ? graph.outNeighbors(source) : graph.neighbors(source),
+    );
+    const targetNeighbors = new Set(
+        directed ? graph.outNeighbors(target) : graph.neighbors(target),
+    );
+
+    const common = new Set<NodeId>();
+    for (const neighbor of sourceNeighbors) {
+        if (targetNeighbors.has(neighbor)) {
+            common.add(neighbor);
+        }
+    }
+
+    return common;
+}
+
+/**
+ * Find common neighbors for link prediction in directed graphs
+ * This finds nodes that form a path from source to target (source->X->target)
+ * @param graph - The graph
+ * @param source - First node
+ * @param target - Second node
+ * @returns Set of intermediate node IDs
+ */
+export function getIntermediateNodes(
+    graph: Graph,
+    source: NodeId,
+    target: NodeId,
+): Set<NodeId> {
+    const sourceOutNeighbors = new Set(graph.outNeighbors(source));
+    const targetInNeighbors = new Set(graph.inNeighbors(target));
+
+    const common = new Set<NodeId>();
+    for (const neighbor of sourceOutNeighbors) {
+        if (targetInNeighbors.has(neighbor)) {
+            common.add(neighbor);
+        }
+    }
+
+    return common;
+}
+
+/**
+ * Generate a consistent edge key for undirected graphs
+ * @param source - Source node
+ * @param target - Target node
+ * @param isDirected - Whether the graph is directed
+ * @returns A consistent edge identifier
+ */
+export function getEdgeKey(
+    source: NodeId,
+    target: NodeId,
+    isDirected: boolean,
+): string {
+    if (isDirected) {
+        return `${String(source)}->${String(target)}`;
+    }
+
+    // For undirected graphs, sort to ensure consistency
+    const [first, second] = source < target ? [source, target] : [target, source];
+    return `${String(first)}-${String(second)}`;
+}
+
+/**
+ * Calculate total edge weight in a graph
+ * @param graph - The graph
+ * @returns Total weight of all edges
+ */
+export function getTotalEdgeWeight(graph: Graph): number {
+    let totalWeight = 0;
+    for (const edge of graph.edges()) {
+        totalWeight += edge.weight ?? 1;
+    }
+    return graph.isDirected ? totalWeight : totalWeight / 2;
+}
+
+/**
+ * Get node degree with optional mode for directed graphs
+ * @param graph - The graph
+ * @param nodeId - The node ID
+ * @param mode - Degree mode for directed graphs
+ * @returns Node degree
+ */
+export function getNodeDegree(
+    graph: Graph,
+    nodeId: NodeId,
+    mode: "in" | "out" | "total" = "total",
+): number {
+    if (!graph.isDirected || mode === "total") {
+        return graph.degree(nodeId);
+    }
+
+    if (mode === "in") {
+        return graph.inDegree(nodeId);
+    }
+
+    return graph.outDegree(nodeId);
+}
+
+/**
+ * Convert directed graph to undirected
+ * @param graph - The directed graph
+ * @returns A new undirected graph
+ */
+export function makeUndirected(graph: Graph): Graph {
+    if (!graph.isDirected) {
+        return graph;
+    }
+
+    const undirected = new Graph({directed: false});
+
+    // Add all nodes
+    for (const node of graph.nodes()) {
+        undirected.addNode(node.id, node.data);
+    }
+
+    // Add edges (will automatically be made bidirectional)
+    for (const edge of graph.edges()) {
+        // For undirected, we only add each edge once
+        if (!undirected.hasEdge(edge.source, edge.target)) {
+            undirected.addEdge(edge.source, edge.target, edge.weight, edge.data);
+        }
+    }
+
+    return undirected;
+}
+
+/**
+ * Renumber communities consecutively starting from 0
+ * @param communities - Map of node to community ID
+ * @returns Map with renumbered community IDs
+ */
+export function renumberCommunities<T>(
+    communities: Map<T, number>,
+): Map<T, number> {
+    const uniqueCommunities = new Set(communities.values());
+    const remapping = new Map<number, number>();
+    let newId = 0;
+
+    for (const community of uniqueCommunities) {
+        remapping.set(community, newId++);
+    }
+
+    const renumbered = new Map<T, number>();
+    for (const [node, community] of communities) {
+        const newCommunity = remapping.get(community);
+        if (newCommunity !== undefined) {
+            renumbered.set(node, newCommunity);
+        }
+    }
+
+    return renumbered;
+}

package/src/utils/index.ts

@@ -0,0 +1,4 @@
+export * from "./algorithm-utilities.js";
+export * from "./graph-utilities.js";
+export * from "./math-utilities.js";
+export * from "./matrix-utilities.js";

package/src/utils/math-utilities.ts

@@ -0,0 +1,140 @@
+/**
+ * Seeded random number generator for reproducible results
+ */
+export class SeededRandom {
+    private seed: number;
+    private readonly m = 0x80000000; // 2**31
+    private readonly a = 1103515245;
+    private readonly c = 12345;
+
+    constructor(seed: number) {
+        // Handle negative seeds correctly
+        this.seed = ((seed % this.m) + this.m) % this.m;
+    }
+
+    /**
+     * Generate next random number between 0 and 1
+     */
+    next(): number {
+        this.seed = ((this.a * this.seed) + this.c) % this.m;
+        return this.seed / (this.m - 1);
+    }
+
+    /**
+     * Create a generator function for backward compatibility
+     */
+    static createGenerator(seed: number): () => number {
+        const rng = new SeededRandom(seed);
+        return () => rng.next();
+    }
+}
+
+/**
+ * Fisher-Yates shuffle algorithm
+ * @param array - Array to shuffle (will be modified in place)
+ * @param rng - Optional random number generator (defaults to Math.random)
+ * @returns The shuffled array (same reference as input)
+ */
+export function shuffle<T>(array: T[], rng: () => number = Math.random): T[] {
+    for (let i = array.length - 1; i > 0; i--) {
+        const j = Math.floor(rng() * (i + 1));
+        const temp = array[i];
+        const tempJ = array[j];
+        if (temp !== undefined && tempJ !== undefined) {
+            array[i] = tempJ;
+            array[j] = temp;
+        }
+    }
+    return array;
+}
+
+/**
+ * Calculate Euclidean distance between two vectors
+ * @param a - First vector
+ * @param b - Second vector
+ * @returns Euclidean distance
+ * @throws Error if vectors have different lengths
+ */
+export function euclideanDistance(a: number[], b: number[]): number {
+    if (a.length !== b.length) {
+        throw new Error("Vectors must have same length");
+    }
+
+    let sum = 0;
+    for (let i = 0; i < a.length; i++) {
+        const aVal = a[i];
+        const bVal = b[i];
+        if (aVal !== undefined && bVal !== undefined) {
+            const diff = aVal - bVal;
+            sum += diff * diff;
+        }
+    }
+    return Math.sqrt(sum);
+}
+
+export const normalize = {
+    /**
+     * Min-max normalization to [0, 1] range
+     */
+    minMax(values: Map<string, number>): void {
+        const vals = Array.from(values.values());
+        const min = Math.min(... vals);
+        const max = Math.max(... vals);
+        const range = max - min;
+
+        if (range === 0) {
+            return;
+        }
+
+        for (const [key, value] of values) {
+            values.set(key, (value - min) / range);
+        }
+    },
+
+    /**
+     * Normalize by maximum value
+     */
+    byMax(values: Map<string, number>): void {
+        const max = Math.max(... values.values());
+        if (max === 0) {
+            return;
+        }
+
+        for (const [key, value] of values) {
+            values.set(key, value / max);
+        }
+    },
+
+    /**
+     * L2 (Euclidean) normalization
+     */
+    l2Norm(values: Map<string, number>): void {
+        const sumSquares = Array.from(values.values())
+            .reduce((sum, val) => sum + (val * val), 0);
+        const norm = Math.sqrt(sumSquares);
+
+        if (norm === 0) {
+            return;
+        }
+
+        for (const [key, value] of values) {
+            values.set(key, value / norm);
+        }
+    },
+
+    /**
+     * Normalize to sum to 1
+     */
+    sumToOne(values: Map<string, number>): void {
+        const sum = Array.from(values.values())
+            .reduce((acc, val) => acc + val, 0);
+
+        if (sum === 0) {
+            return;
+        }
+
+        for (const [key, value] of values) {
+            values.set(key, value / sum);
+        }
+    },
+};

package/src/utils/matrix-utilities.ts

@@ -0,0 +1,2 @@
+// Matrix utility functions will be added here
+export {};

package/src/utils/optimization-helpers.ts

@@ -0,0 +1,81 @@
+import type {Graph} from "../core/graph.js";
+
+/**
+ * Common interface for algorithm options with optimization support
+ */
+export interface OptimizableOptions {
+    /**
+     * Whether to use optimized implementations
+     * - true: Force use of optimizations
+     * - false: Disable optimizations
+     * - "auto": Automatically decide based on graph size (default)
+     */
+    optimized?: boolean | "auto";
+}
+
+/**
+ * Check if a graph should use optimizations based on its size
+ */
+function shouldUseOptimizations(nodeCount: number, edgeCount: number): boolean {
+    // Use optimizations for graphs with more than 10k nodes or 100k edges
+    return nodeCount > 10000 || edgeCount > 100000;
+}
+
+/**
+ * Determine if optimizations should be used for a given graph
+ */
+export function shouldOptimize(
+    graph: Graph,
+    options: OptimizableOptions = {},
+): boolean {
+    const {optimized = "auto"} = options;
+
+    if (optimized === "auto") {
+        // Check graph size
+        return shouldUseOptimizations(graph.nodeCount, graph.totalEdgeCount);
+    }
+
+    return optimized;
+}
+
+/**
+ * Merge optimization options with algorithm-specific options
+ */
+export function mergeOptimizationOptions<T extends Record<string, unknown>>(
+    graph: Graph,
+    options: T & OptimizableOptions,
+): T & {optimized?: boolean} {
+    const {optimized: userOptimized, ... rest} = options;
+
+    return {
+        ... rest,
+        optimized: shouldOptimize(graph, userOptimized !== undefined ? {optimized: userOptimized} : {}),
+    } as T & {optimized?: boolean};
+}
+
+/**
+ * Create an optimized version of an algorithm
+ * @example
+ * const optimizedBetweenness = createOptimizedAlgorithm(
+ *     betweennessCentrality,
+ *     (graph, options) => ({...options, optimized: true})
+ * );
+ */
+export function createOptimizedAlgorithm<
+    TArgs extends [Graph, ...unknown[]],
+    TResult,
+>(
+    algorithm: (... args: TArgs) => TResult,
+    optionsTransformer?: (graph: Graph, options: unknown) => unknown,
+): (... args: TArgs) => TResult {
+    return (... args: TArgs): TResult => {
+        const [graph, options, ... rest] = args;
+
+        if (optionsTransformer && options !== undefined) {
+            const transformedOptions = optionsTransformer(graph, options);
+            return algorithm(... ([graph, transformedOptions, ... rest] as unknown as TArgs));
+        }
+
+        return algorithm(... args);
+    };
+}