@graphty/algorithms 1.0.1 → 1.2.0

package/dist/src/pathfinding/astar.js

@@ -0,0 +1,180 @@
+import { MinPriorityQueue } from "../utils/priorityQueue.js";
+import { pathfindingUtils } from "./utils.js";
+/**
+ * A* pathfinding algorithm
+ * Finds the shortest path from start to goal using a heuristic function
+ *
+ * @param graph - The graph represented as an adjacency list
+ * @param start - The starting node
+ * @param goal - The goal node
+ * @param heuristic - Heuristic function that estimates distance from node to goal
+ * @returns Object containing the shortest path and its cost, or null if no path exists
+ *
+ * Time Complexity: O(E) with good heuristic, O(b^d) worst case
+ * Space Complexity: O(V)
+ */
+export function astar(graph, start, goal, heuristic) {
+    if (!graph.has(start) || !graph.has(goal)) {
+        return null;
+    }
+    // Priority queue ordered by f(n) = g(n) + h(n)
+    const openSet = new MinPriorityQueue();
+    const gScore = new Map(); // Cost from start to node
+    const fScore = new Map(); // Estimated total cost
+    const cameFrom = new Map();
+    const closedSet = new Set();
+    // Initialize start node
+    gScore.set(start, 0);
+    fScore.set(start, heuristic(start, goal));
+    const startFScore = fScore.get(start);
+    if (startFScore === undefined) {
+        return null;
+    }
+    openSet.insert({ node: start, distance: startFScore });
+    while (!openSet.isEmpty()) {
+        const current = openSet.extractMin();
+        if (!current) {
+            break;
+        }
+        const currentNode = current.node;
+        if (currentNode === goal) {
+            // Reconstruct path
+            const path = pathfindingUtils.reconstructPath(cameFrom, goal);
+            const goalCost = gScore.get(goal);
+            if (goalCost === undefined) {
+                return null;
+            }
+            return { path, cost: goalCost };
+        }
+        closedSet.add(currentNode);
+        const neighbors = graph.get(currentNode);
+        if (!neighbors) {
+            continue;
+        }
+        for (const [neighbor, weight] of neighbors) {
+            if (closedSet.has(neighbor)) {
+                continue;
+            }
+            const currentNodeGScore = gScore.get(currentNode);
+            if (currentNodeGScore === undefined) {
+                continue;
+            }
+            const tentativeGScore = currentNodeGScore + weight;
+            const currentGScore = gScore.get(neighbor) ?? Infinity;
+            if (tentativeGScore < currentGScore) {
+                // This path to neighbor is better
+                cameFrom.set(neighbor, currentNode);
+                gScore.set(neighbor, tentativeGScore);
+                fScore.set(neighbor, tentativeGScore + heuristic(neighbor, goal));
+                // Add to open set if not already there
+                const neighborFScore = fScore.get(neighbor);
+                if (neighborFScore !== undefined) {
+                    openSet.insert({ node: neighbor, distance: neighborFScore });
+                }
+            }
+        }
+    }
+    return null; // No path found
+}
+/**
+ * A* pathfinding with path reconstruction details
+ * Returns detailed information about the search process
+ */
+export function astarWithDetails(graph, start, goal, heuristic) {
+    const openSet = new MinPriorityQueue();
+    const gScore = new Map();
+    const fScore = new Map();
+    const cameFrom = new Map();
+    const closedSet = new Set();
+    gScore.set(start, 0);
+    fScore.set(start, heuristic(start, goal));
+    const startFScore = fScore.get(start);
+    if (startFScore === undefined) {
+        return {
+            path: null,
+            cost: Infinity,
+            visited: new Set(),
+            gScores: new Map(),
+            fScores: new Map(),
+        };
+    }
+    openSet.insert({ node: start, distance: startFScore });
+    while (!openSet.isEmpty()) {
+        const current = openSet.extractMin();
+        if (!current) {
+            break;
+        }
+        const currentNode = current.node;
+        if (currentNode === goal) {
+            const path = pathfindingUtils.reconstructPath(cameFrom, goal);
+            return {
+                path,
+                cost: gScore.get(goal) ?? Infinity,
+                visited: closedSet,
+                gScores: gScore,
+                fScores: fScore,
+            };
+        }
+        closedSet.add(currentNode);
+        const neighbors = graph.get(currentNode);
+        if (!neighbors) {
+            continue;
+        }
+        for (const [neighbor, weight] of neighbors) {
+            if (closedSet.has(neighbor)) {
+                continue;
+            }
+            const currentNodeGScore = gScore.get(currentNode);
+            if (currentNodeGScore === undefined) {
+                continue;
+            }
+            const tentativeGScore = currentNodeGScore + weight;
+            const currentGScore = gScore.get(neighbor) ?? Infinity;
+            if (tentativeGScore < currentGScore) {
+                cameFrom.set(neighbor, currentNode);
+                gScore.set(neighbor, tentativeGScore);
+                fScore.set(neighbor, tentativeGScore + heuristic(neighbor, goal));
+                const neighborFScore = fScore.get(neighbor);
+                if (neighborFScore !== undefined) {
+                    openSet.insert({ node: neighbor, distance: neighborFScore });
+                }
+            }
+        }
+    }
+    return {
+        path: null,
+        cost: Infinity,
+        visited: closedSet,
+        gScores: gScore,
+        fScores: fScore,
+    };
+}
+/**
+ * Common heuristic functions for A*
+ */
+export const heuristics = {
+    /**
+   * Manhattan distance heuristic for grid-based graphs
+   */
+    manhattan: (a, b) => {
+        return Math.abs(a[0] - b[0]) + Math.abs(a[1] - b[1]);
+    },
+    /**
+   * Euclidean distance heuristic
+   */
+    euclidean: (a, b) => {
+        return Math.sqrt(Math.pow(a[0] - b[0], 2) + Math.pow(a[1] - b[1], 2));
+    },
+    /**
+   * Chebyshev distance heuristic (diagonal movement allowed)
+   */
+    chebyshev: (a, b) => {
+        return Math.max(Math.abs(a[0] - b[0]), Math.abs(a[1] - b[1]));
+    },
+    /**
+   * Zero heuristic (makes A* behave like Dijkstra)
+   */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    zero: (_a, _b) => 0,
+};
+//# sourceMappingURL=astar.js.map

package/dist/src/pathfinding/astar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"astar.js","sourceRoot":"","sources":["../../../src/pathfinding/astar.ts"],"names":[],"mappings":"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"}

package/dist/src/pathfinding/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./astar.js";
+export * from "./utils.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/pathfinding/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/pathfinding/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/src/pathfinding/index.js

@@ -0,0 +1,3 @@
+export * from "./astar.js";
+export * from "./utils.js";
+//# sourceMappingURL=index.js.map

package/dist/src/pathfinding/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/pathfinding/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/src/pathfinding/utils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Utility functions for pathfinding algorithms
+ */
+export declare const pathfindingUtils: {
+    /**
+   * Reconstructs a path from start to goal using the cameFrom map
+   */
+    reconstructPath<T>(cameFrom: Map<T, T>, goal: T): T[];
+    /**
+   * Creates a grid graph for testing pathfinding algorithms
+   */
+    createGridGraph(width: number, height: number, obstacles?: Set<string>): Map<string, Map<string, number>>;
+    /**
+   * Parses a grid coordinate string
+   */
+    parseGridCoordinate(coord: string): [number, number];
+};
+//# sourceMappingURL=utils.d.ts.map

package/dist/src/pathfinding/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/pathfinding/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,gBAAgB;IACzB;;KAEC;oBACe,CAAC,YAAY,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE;IAiBrD;;KAEC;2BAEU,MAAM,UACL,MAAM,4BAEf,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAwCnC;;KAEC;+BAC0B,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;CAUvD,CAAC"}

package/dist/src/pathfinding/utils.js

@@ -0,0 +1,68 @@
+/**
+ * Utility functions for pathfinding algorithms
+ */
+export const pathfindingUtils = {
+    /**
+   * Reconstructs a path from start to goal using the cameFrom map
+   */
+    reconstructPath(cameFrom, goal) {
+        const path = [goal];
+        let current = goal;
+        while (cameFrom.has(current)) {
+            const next = cameFrom.get(current);
+            if (next === undefined) {
+                break;
+            }
+            current = next;
+            path.unshift(current);
+        }
+        return path;
+    },
+    /**
+   * Creates a grid graph for testing pathfinding algorithms
+   */
+    createGridGraph(width, height, obstacles = new Set()) {
+        const graph = new Map();
+        for (let x = 0; x < width; x++) {
+            for (let y = 0; y < height; y++) {
+                const node = `${String(x)},${String(y)}`;
+                if (obstacles.has(node)) {
+                    continue;
+                }
+                const neighbors = new Map();
+                // Add 4-directional neighbors
+                const directions = [
+                    [0, 1], [1, 0], [0, -1], [-1, 0],
+                ];
+                for (const dir of directions) {
+                    const dx = dir[0];
+                    const dy = dir[1];
+                    if (dx === undefined || dy === undefined) {
+                        continue;
+                    }
+                    const nx = x + dx;
+                    const ny = y + dy;
+                    const neighbor = `${String(nx)},${String(ny)}`;
+                    if (nx >= 0 && nx < width && ny >= 0 && ny < height && !obstacles.has(neighbor)) {
+                        neighbors.set(neighbor, 1); // Unit cost for grid movement
+                    }
+                }
+                graph.set(node, neighbors);
+            }
+        }
+        return graph;
+    },
+    /**
+   * Parses a grid coordinate string
+   */
+    parseGridCoordinate(coord) {
+        const parts = coord.split(",").map(Number);
+        const x = parts[0];
+        const y = parts[1];
+        if (x === undefined || y === undefined) {
+            throw new Error(`Invalid coordinate: ${coord}`);
+        }
+        return [x, y];
+    },
+};
+//# sourceMappingURL=utils.js.map

package/dist/src/pathfinding/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/pathfinding/utils.ts"],"names":[],"mappings":"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"}

package/dist/src/research/grsbm.d.ts

@@ -0,0 +1,83 @@
+import type { Graph } from "../core/graph.js";
+import type { NodeId } from "../types/index.js";
+/**
+ * Configuration options for the GRSBM (Greedy Recursive Spectral Bisection) algorithm
+ */
+export interface GRSBMConfig {
+    /** Maximum depth of recursive bisection */
+    maxDepth?: number;
+    /** Minimum cluster size to continue splitting */
+    minClusterSize?: number;
+    /** Number of eigenvectors to use for spectral embedding */
+    numEigenvectors?: number;
+    /** Convergence tolerance for eigenvalue computation */
+    tolerance?: number;
+    /** Maximum number of power iterations for eigenvalue computation */
+    maxIterations?: number;
+    /** Random seed for reproducibility */
+    seed?: number;
+}
+/**
+ * Represents a cluster in the hierarchical structure
+ */
+export interface GRSBMCluster {
+    /** Unique identifier for this cluster */
+    id: string;
+    /** Node IDs in this cluster */
+    members: Set<NodeId>;
+    /** Left child cluster (if split) */
+    left?: GRSBMCluster;
+    /** Right child cluster (if split) */
+    right?: GRSBMCluster;
+    /** Modularity score of this cluster */
+    modularity: number;
+    /** Depth in the hierarchy */
+    depth: number;
+    /** Spectral embedding quality score */
+    spectralScore: number;
+}
+/**
+ * Result of the GRSBM clustering algorithm
+ */
+export interface GRSBMResult {
+    /** Root of the cluster hierarchy */
+    root: GRSBMCluster;
+    /** Flat clustering at leaf level */
+    clusters: Map<NodeId, number>;
+    /** Number of final clusters */
+    numClusters: number;
+    /** Modularity scores for each level */
+    modularityScores: number[];
+    /** Explanation of the clustering structure */
+    explanation: ClusterExplanation[];
+}
+/**
+ * Explanation for a cluster split decision
+ */
+export interface ClusterExplanation {
+    /** Cluster that was split */
+    clusterId: string;
+    /** Reason for the split */
+    reason: string;
+    /** Modularity improvement from the split */
+    modularityImprovement: number;
+    /** Key nodes that influenced the split */
+    keyNodes: NodeId[];
+    /** Spectral embedding values */
+    spectralValues: number[];
+}
+/**
+ * GRSBM - Greedy Recursive Spectral Bisection with Modularity
+ *
+ * This algorithm performs hierarchical community detection using spectral
+ * bisection guided by modularity optimization. It provides explainable
+ * community structure by tracking the reasoning behind each split.
+ *
+ * Based on: "Explainable Community Detection via Hierarchical Spectral Clustering" (2024)
+ *
+ * @param graph - Input graph to cluster
+ * @param config - Configuration options
+ * @returns Hierarchical clustering result with explanations
+ */
+export declare function grsbm(graph: Graph, config?: GRSBMConfig): GRSBMResult;
+//# sourceMappingURL=grsbm.d.ts.map

package/dist/src/research/grsbm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grsbm.d.ts","sourceRoot":"","sources":["../../../src/research/grsbm.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,KAAK,EAAC,MAAM,kBAAkB,CAAC;AAC5C,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,mBAAmB,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,WAAW;IACxB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,+BAA+B;IAC/B,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACrB,oCAAoC;IACpC,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,qCAAqC;IACrC,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,aAAa,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IACxB,oCAAoC;IACpC,IAAI,EAAE,YAAY,CAAC;IACnB,oCAAoC;IACpC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,8CAA8C;IAC9C,WAAW,EAAE,kBAAkB,EAAE,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,qBAAqB,EAAE,MAAM,CAAC;IAC9B,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,gCAAgC;IAChC,cAAc,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,GAAE,WAAgB,GAAG,WAAW,CAuJzE"}