@graphty/algorithms 1.2.0 → 1.4.2

package/src/utils/math-utilities.ts

@@ -0,0 +1,149 @@
+/**
+ * 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;
+
+    /**
+     * Creates a new SeededRandom instance with the given seed.
+     * @param seed - The seed value for reproducible random number generation
+     */
+    constructor(seed: number) {
+        // Handle negative seeds correctly
+        this.seed = ((seed % this.m) + this.m) % this.m;
+    }
+
+    /**
+     * Generate next random number between 0 and 1
+     * @returns A pseudo-random number in the range [0, 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
+     * @param seed - The seed value for reproducible random number generation
+     * @returns A function that returns the next random number when called
+     */
+    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
+     * @param values - Map of values to normalize in place
+     */
+    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
+     * @param values - Map of values to normalize in place
+     */
+    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
+     * @param values - Map of values to normalize in place
+     */
+    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
+     * @param values - Map of values to normalize in place
+     */
+    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,87 @@
+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
+ * @param nodeCount - The number of nodes in the graph
+ * @param edgeCount - The number of edges in the graph
+ * @returns True if the graph is large enough to benefit from optimizations
+ */
+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
+ * @param graph - The graph to check for optimization eligibility
+ * @param options - Options containing the optimization preference
+ * @returns True if optimizations should be used for this 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
+ * @param graph - The graph to determine optimization settings for
+ * @param options - Algorithm options that may include optimization settings
+ * @returns The options with resolved optimization boolean flag
+ */
+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
+ * @param algorithm - The algorithm function to wrap with optimization support
+ * @param optionsTransformer - Optional function to transform options before passing to the algorithm
+ * @returns A wrapped version of the algorithm that applies optimization transformations
+ * @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);
+    };
+}

package/src/utils/priorityQueue.ts

@@ -5,13 +5,17 @@ export class MinPriorityQueue<T> {
     private heap: T[] = [];
     private compare: (a: T, b: T) => number;
 
+    /**
+     * Creates a new MinPriorityQueue instance.
+     * @param compareFunction - Custom comparison function. Returns negative if a has higher priority than b.
+     */
     constructor(compareFunction?: (a: T, b: T) => number) {
         this.compare = compareFunction ?? ((a: T, b: T) => this.defaultCompare(a, b));
     }
 
     private defaultCompare(a: T, b: T): number {
-        const aWithDistance = a as T & {distance?: number};
-        const bWithDistance = b as T & {distance?: number};
+        const aWithDistance = a as T & { distance?: number };
+        const bWithDistance = b as T & { distance?: number };
 
         if (aWithDistance.distance !== undefined && bWithDistance.distance !== undefined) {
             return aWithDistance.distance - bWithDistance.distance;
@@ -25,11 +29,11 @@ export class MinPriorityQueue<T> {
     }
 
     private leftChild(i: number): number {
-        return (2 * i) + 1;
+        return 2 * i + 1;
     }
 
     private rightChild(i: number): number {
-        return (2 * i) + 2;
+        return 2 * i + 2;
     }
 
     private swap(i: number, j: number): void {
@@ -63,13 +67,23 @@ export class MinPriorityQueue<T> {
 
             const leftItem = this.heap[left];
             const minItem = this.heap[minIndex];
-            if (left < this.heap.length && leftItem !== undefined && minItem !== undefined && this.compare(leftItem, minItem) < 0) {
+            if (
+                left < this.heap.length &&
+                leftItem !== undefined &&
+                minItem !== undefined &&
+                this.compare(leftItem, minItem) < 0
+            ) {
                 minIndex = left;
             }
 
             const rightItem = this.heap[right];
             const newMinItem = this.heap[minIndex];
-            if (right < this.heap.length && rightItem !== undefined && newMinItem !== undefined && this.compare(rightItem, newMinItem) < 0) {
+            if (
+                right < this.heap.length &&
+                rightItem !== undefined &&
+                newMinItem !== undefined &&
+                this.compare(rightItem, newMinItem) < 0
+            ) {
                 minIndex = right;
             }
 
@@ -82,11 +96,19 @@ export class MinPriorityQueue<T> {
         }
     }
 
+    /**
+     * Insert a value into the priority queue.
+     * @param value - The value to insert
+     */
     insert(value: T): void {
         this.heap.push(value);
         this.heapifyUp(this.heap.length - 1);
     }
 
+    /**
+     * Remove and return the minimum value from the priority queue.
+     * @returns The minimum value, or undefined if the queue is empty
+     */
     extractMin(): T | undefined {
         if (this.heap.length === 0) {
             return undefined;
@@ -106,14 +128,26 @@ export class MinPriorityQueue<T> {
         return min;
     }
 
+    /**
+     * View the minimum value without removing it.
+     * @returns The minimum value, or undefined if the queue is empty
+     */
     peek(): T | undefined {
         return this.heap[0];
     }
 
+    /**
+     * Check if the priority queue is empty.
+     * @returns True if the queue has no items, false otherwise
+     */
     isEmpty(): boolean {
         return this.heap.length === 0;
     }
 
+    /**
+     * Get the number of items in the priority queue.
+     * @returns The number of items currently in the queue
+     */
     size(): number {
         return this.heap.length;
     }