@thi.ng/adjacency 2.2.20 → 2.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-12-20T16:33:11Z
+- **Last updated**: 2022-12-22T21:47:07Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,13 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [2.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/adjacency@2.3.0) (2022-12-22)
+
+#### 🚀 Features
+
+- add FloydWarshall shortest-path impl ([26fa3ac](https://github.com/thi-ng/umbrella/commit/26fa3ac))
+- update BFS distance array to Float32Array ([3997923](https://github.com/thi-ng/umbrella/commit/3997923))
+
 ### [2.2.12](https://github.com/thi-ng/umbrella/tree/@thi.ng/adjacency@2.2.12) (2022-10-26)
 
 #### ♻️ Refactoring

package/README.md

@@ -10,6 +10,8 @@ This project is part of the
 [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo.
 
 - [About](#about)
+  - [Graph implementations](#graph-implementations)
+  - [Traversals](#traversals)
 - [Status](#status)
 - [Related packages](#related-packages)
 - [Installation](#installation)
@@ -21,7 +23,24 @@ This project is part of the
 
 ## About
 
-Sparse & bitwise adjacency matrices and related functions for directed & undirected graphs
+Sparse & bitwise adjacency matrices, lists and selected traversal algorithms for directed & undirected graphs.
+
+### Graph implementations
+
+The following types all implement the [`IGraph`
+interface](https://docs.thi.ng/umbrella/adjacency/interfaces/IGraph.html) and
+support both directed & undirected graphs:
+
+- [AdjacencyBitMatrix (bit matrix based)](https://docs.thi.ng/umbrella/adjacency/classes/AdjacencyBitMatrix.html)
+- [AdjacencyMatrix (sparse matrix based)](https://docs.thi.ng/umbrella/adjacency/classes/AdjacencyMatrix.html)
+- [AdjacencyList](https://docs.thi.ng/umbrella/adjacency/classes/AdjacencyList.html)
+
+### Traversals
+
+- [Breadth-First Search](https://docs.thi.ng/umbrella/adjacency/functions/bfs.html)
+- [Depth-First Search](https://docs.thi.ng/umbrella/adjacency/functions/dfs.html)
+- [Floyd-Warshall (global shortest paths search)](https://docs.thi.ng/umbrella/adjacency/functions/floydWarshall.html)
+- [Minimum Spanning Tree](https://docs.thi.ng/umbrella/adjacency/functions/mst.html)
 
 ## Status
 
@@ -53,7 +72,7 @@ For Node.js REPL:
 const adjacency = await import("@thi.ng/adjacency");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 2.28 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.54 KB
 
 ## Dependencies
 

package/bfs.d.ts

@@ -1,10 +1,22 @@
 import { BitField } from "@thi.ng/bitfield/bitfield";
 import type { CostFn, IGraph } from "./api.js";
+/**
+ * Breadth-First / shortest path search between `src` and `dest` in `graph`,
+ * with optional `cost` function. By default all edges have an uniform cost,
+ * i.e. the overall path cost is topological distance.
+ *
+ * @remarks
+ * Also see {@link bfs} for ad hoc queries.
+ *
+ * Reference:
+ * - https://en.wikipedia.org/wiki/Breadth-first_search
+ * - https://algs4.cs.princeton.edu/40graphs/
+ */
 export declare class BFS {
     graph: IGraph;
     marked: BitField;
     edges: Uint32Array;
-    dist: Uint32Array;
+    dist: Float32Array;
     constructor(graph: IGraph, src: number, cost?: CostFn);
     protected search(id: number, cost: CostFn): void;
     hasPathTo(id: number): boolean;

package/bfs.js

@@ -1,11 +1,23 @@
 import { BitField } from "@thi.ng/bitfield/bitfield";
 import { DCons } from "@thi.ng/dcons/dcons";
+/**
+ * Breadth-First / shortest path search between `src` and `dest` in `graph`,
+ * with optional `cost` function. By default all edges have an uniform cost,
+ * i.e. the overall path cost is topological distance.
+ *
+ * @remarks
+ * Also see {@link bfs} for ad hoc queries.
+ *
+ * Reference:
+ * - https://en.wikipedia.org/wiki/Breadth-first_search
+ * - https://algs4.cs.princeton.edu/40graphs/
+ */
 export class BFS {
     constructor(graph, src, cost = () => 1) {
         this.graph = graph;
         const numV = graph.numVertices();
         this.edges = new Uint32Array(numV);
-        this.dist = new Uint32Array(numV);
+        this.dist = new Float32Array(numV);
         this.marked = new BitField(numV);
         this.search(src, cost);
     }

package/floyd-warshall.d.ts

@@ -0,0 +1,61 @@
+import type { CostFn, IGraph } from "./api.js";
+/**
+ * Implementation of the Floyd-Warshall algorithm for finding _all_ shortest
+ * paths in a directed graph, optionally with positive or negative edge weights.
+ * A single execution of the algorithm will find the lengths (summed weights) of
+ * shortest paths between all pairs of vertices.
+ *
+ * @remarks
+ * The default cost function is topological distance (i.e. every edge has a
+ * length/cost of 1).
+ *
+ * Paths & accumulated distances can be queried via {@link FloydWarshall.path}
+ * and {@link FloydWarshall.distance}.
+ *
+ * This algorithm is quite memory hungry and requires `|V| * |V| * 8 bytes`,
+ * i.e. ~8MB for a graph with 1000 nodes. If possible, use {@link BFS} to
+ * perform individual shortest-path queries (rather than this global approach).
+ *
+ * Reference:
+ * - https://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm
+ */
+export declare class FloydWarshall {
+    dist: Float32Array;
+    next: Int32Array;
+    numV: number;
+    /**
+     * Instantiates and pre-computes all shortest paths in given `graph`. See
+     * class comments for details.
+     *
+     * @param graph
+     * @param cost
+     */
+    constructor(graph: IGraph<number>, cost?: CostFn);
+    /**
+     * Returns shortest distance between vertices `a` and `b`, or `undefined` if
+     * no connecting path exists. Throws an error if either `a` or `b` are out
+     * of bounds.
+     *
+     * @param a
+     * @param b
+     */
+    distance(a: number, b: number): number | undefined;
+    /**
+     * Returns iterator of vertex IDs of path between `a` and `b` (if any).
+     * Throws an error if either `a` or `b` are out of bounds.
+     *
+     * @param a
+     * @param b
+     */
+    path(a: number, b: number): Generator<number, void, unknown>;
+    protected ensureIndex(id: number): void;
+    protected ensurePair(a: number, b: number): void;
+}
+/**
+ * Factory function for {@link FloydWarshall}.
+ *
+ * @param graph
+ * @param cost
+ */
+export declare const floydWarshall: (graph: IGraph<number>, cost?: CostFn) => FloydWarshall;
+//# sourceMappingURL=floyd-warshall.d.ts.map

package/floyd-warshall.js

@@ -0,0 +1,103 @@
+import { outOfBounds } from "@thi.ng/errors/out-of-bounds";
+/**
+ * Implementation of the Floyd-Warshall algorithm for finding _all_ shortest
+ * paths in a directed graph, optionally with positive or negative edge weights.
+ * A single execution of the algorithm will find the lengths (summed weights) of
+ * shortest paths between all pairs of vertices.
+ *
+ * @remarks
+ * The default cost function is topological distance (i.e. every edge has a
+ * length/cost of 1).
+ *
+ * Paths & accumulated distances can be queried via {@link FloydWarshall.path}
+ * and {@link FloydWarshall.distance}.
+ *
+ * This algorithm is quite memory hungry and requires `|V| * |V| * 8 bytes`,
+ * i.e. ~8MB for a graph with 1000 nodes. If possible, use {@link BFS} to
+ * perform individual shortest-path queries (rather than this global approach).
+ *
+ * Reference:
+ * - https://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm
+ */
+export class FloydWarshall {
+    /**
+     * Instantiates and pre-computes all shortest paths in given `graph`. See
+     * class comments for details.
+     *
+     * @param graph
+     * @param cost
+     */
+    constructor(graph, cost = () => 1) {
+        const numV = (this.numV = graph.numVertices());
+        const dist = (this.dist = new Float32Array(numV * numV).fill(Infinity));
+        const next = (this.next = new Int32Array(numV * numV).fill(-1));
+        for (let [u, v] of graph.edges()) {
+            const idx = u * numV + v;
+            dist[idx] = cost(u, v);
+            next[idx] = v;
+        }
+        for (let v = 0; v < numV; v++) {
+            const idx = v * numV + v;
+            dist[idx] = 0;
+            next[idx] = v;
+        }
+        for (let k = 0; k < numV; k++) {
+            for (let i = 0; i < numV; i++) {
+                const idxIK = i * numV + k;
+                for (let j = 0; j < numV; j++) {
+                    const idxIJ = i * numV + j;
+                    const idxKJ = k * numV + j;
+                    const minD = dist[idxIK] + dist[idxKJ];
+                    if (dist[idxIJ] > minD) {
+                        dist[idxIJ] = minD;
+                        next[idxIJ] = next[idxIK];
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Returns shortest distance between vertices `a` and `b`, or `undefined` if
+     * no connecting path exists. Throws an error if either `a` or `b` are out
+     * of bounds.
+     *
+     * @param a
+     * @param b
+     */
+    distance(a, b) {
+        this.ensurePair(a, b);
+        return this.dist[a * this.numV + b];
+    }
+    /**
+     * Returns iterator of vertex IDs of path between `a` and `b` (if any).
+     * Throws an error if either `a` or `b` are out of bounds.
+     *
+     * @param a
+     * @param b
+     */
+    *path(a, b) {
+        this.ensurePair(a, b);
+        const { next, numV } = this;
+        if (next[a * numV + b] === -1)
+            return;
+        yield a;
+        while (a !== b) {
+            a = next[a * numV + b];
+            yield a;
+        }
+    }
+    ensureIndex(id) {
+        !(id >= 0 && id < this.numV) && outOfBounds(id);
+    }
+    ensurePair(a, b) {
+        this.ensureIndex(a);
+        this.ensureIndex(b);
+    }
+}
+/**
+ * Factory function for {@link FloydWarshall}.
+ *
+ * @param graph
+ * @param cost
+ */
+export const floydWarshall = (graph, cost) => new FloydWarshall(graph, cost);

package/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./api.js";
 export * from "./binary.js";
 export * from "./disjoint-set.js";
+export * from "./floyd-warshall.js";
 export * from "./list.js";
 export * from "./sparse.js";
 export * from "./bfs.js";

package/index.js

@@ -1,6 +1,7 @@
 export * from "./api.js";
 export * from "./binary.js";
 export * from "./disjoint-set.js";
+export * from "./floyd-warshall.js";
 export * from "./list.js";
 export * from "./sparse.js";
 export * from "./bfs.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thi.ng/adjacency",
-  "version": "2.2.20",
-  "description": "Sparse & bitwise adjacency matrices and related functions for directed & undirected graphs",
+  "version": "2.3.0",
+  "description": "Sparse & bitwise adjacency matrices, lists and selected traversal algorithms for directed & undirected graphs",
   "type": "module",
   "module": "./index.js",
   "typings": "./index.d.ts",
@@ -34,17 +34,17 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.6.1",
-    "@thi.ng/arrays": "^2.4.6",
-    "@thi.ng/bitfield": "^2.2.16",
-    "@thi.ng/dcons": "^3.2.27",
-    "@thi.ng/errors": "^2.2.6",
-    "@thi.ng/sparse": "^0.3.32"
+    "@thi.ng/api": "^8.6.2",
+    "@thi.ng/arrays": "^2.4.7",
+    "@thi.ng/bitfield": "^2.2.17",
+    "@thi.ng/dcons": "^3.2.28",
+    "@thi.ng/errors": "^2.2.7",
+    "@thi.ng/sparse": "^0.3.33"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.33.7",
-    "@thi.ng/testament": "^0.3.7",
-    "@thi.ng/vectors": "^7.5.28",
+    "@thi.ng/testament": "^0.3.8",
+    "@thi.ng/vectors": "^7.5.29",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
     "typedoc": "^0.23.22",
@@ -103,6 +103,9 @@
     "./disjoint-set": {
       "default": "./disjoint-set.js"
     },
+    "./floyd-warshall": {
+      "default": "./floyd-warshall.js"
+    },
     "./list": {
       "default": "./list.js"
     },
@@ -119,5 +122,5 @@
     ],
     "year": 2018
   },
-  "gitHead": "7b2af448da8a63fb21704a79cc4cdf1f3d7d7a64\n"
+  "gitHead": "bc6f7f5e2765bb96fe64db804eaf4b2443b47fc6\n"
 }