@thi.ng/adjacency 2.2.19 → 2.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-12-16T12:52:25Z
+- **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/binary.d.ts

@@ -30,10 +30,11 @@ export declare class AdjacencyBitMatrix implements IGraph<number> {
     toDot(ids?: string[]): string;
 }
 /**
- * Creates adjacency matrix backed by a {@link @thi.ng/bitfield#BitMatrix}
+ * Creates adjacency matrix backed by a
+ * [`BitMatrix`](https://docs.thi.ng/umbrella/bitfield/classes/BitMatrix.html)
  * with capacity `n` (max vertices), optionally initialized with given edge
- * pairs. Each edge is `[src-node dest-node]`. If `undirected` is true
- * (default: false), creates symmetrical adjacencies.
+ * pairs. Each edge is `[src-node dest-node]`. If `undirected` is true (default:
+ * false), creates symmetrical adjacencies.
  *
  * @param n - max vertices
  * @param edges - edge pairs

package/binary.js

@@ -90,10 +90,11 @@ export class AdjacencyBitMatrix {
     }
 }
 /**
- * Creates adjacency matrix backed by a {@link @thi.ng/bitfield#BitMatrix}
+ * Creates adjacency matrix backed by a
+ * [`BitMatrix`](https://docs.thi.ng/umbrella/bitfield/classes/BitMatrix.html)
  * with capacity `n` (max vertices), optionally initialized with given edge
- * pairs. Each edge is `[src-node dest-node]`. If `undirected` is true
- * (default: false), creates symmetrical adjacencies.
+ * pairs. Each edge is `[src-node dest-node]`. If `undirected` is true (default:
+ * false), creates symmetrical adjacencies.
  *
  * @param n - max vertices
  * @param edges - edge pairs

package/disjoint-set.d.ts

@@ -1,10 +1,10 @@
 /**
- * Typed array based Disjoint Set implementation with quick union and
- * path compression, after Sedgewick & Wayne.
+ * Typed array based Disjoint Set implementation with quick union and path
+ * compression, after Sedgewick & Wayne.
  *
  * @remarks
- * - {@link https://en.wikipedia.org/wiki/Disjoint-set_data_structure}
- * - {@link https://algs4.cs.princeton.edu/lectures/15UnionFind-2x2.pdf}
+ * - https://en.wikipedia.org/wiki/Disjoint-set_data_structure
+ * - https://algs4.cs.princeton.edu/lectures/15UnionFind-2x2.pdf
  */
 export declare class DisjointSet {
     roots: Uint32Array;

package/disjoint-set.js

@@ -1,11 +1,11 @@
 import { fillRange } from "@thi.ng/arrays/fill-range";
 /**
- * Typed array based Disjoint Set implementation with quick union and
- * path compression, after Sedgewick & Wayne.
+ * Typed array based Disjoint Set implementation with quick union and path
+ * compression, after Sedgewick & Wayne.
  *
  * @remarks
- * - {@link https://en.wikipedia.org/wiki/Disjoint-set_data_structure}
- * - {@link https://algs4.cs.princeton.edu/lectures/15UnionFind-2x2.pdf}
+ * - https://en.wikipedia.org/wiki/Disjoint-set_data_structure
+ * - https://algs4.cs.princeton.edu/lectures/15UnionFind-2x2.pdf
  */
 export class DisjointSet {
     /**

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/mst.d.ts

@@ -15,9 +15,11 @@ import type { Fn } from "@thi.ng/api";
  * criteria. The result edges will be in ascending order, based on the supplied
  * cost function. The cost function is called once for each edge and return
  * values will be cached prior to sorting (see
- * {@link @thi.ng/arrays#sortByCachedKey} for details).
+ * [`sortByCachedKey()`](https://docs.thi.ng/umbrella/arrays/functions/sortByCachedKey.html)
+ * for details).
  *
- * Reference: {@link https://en.wikipedia.org/wiki/Kruskal%27s_algorithm}
+ * References:
+ * - https://en.wikipedia.org/wiki/Kruskal%27s_algorithm
  *
  * @example
  * ```ts

package/mst.js

@@ -16,9 +16,11 @@ import { DisjointSet } from "./disjoint-set.js";
  * criteria. The result edges will be in ascending order, based on the supplied
  * cost function. The cost function is called once for each edge and return
  * values will be cached prior to sorting (see
- * {@link @thi.ng/arrays#sortByCachedKey} for details).
+ * [`sortByCachedKey()`](https://docs.thi.ng/umbrella/arrays/functions/sortByCachedKey.html)
+ * for details).
  *
- * Reference: {@link https://en.wikipedia.org/wiki/Kruskal%27s_algorithm}
+ * References:
+ * - https://en.wikipedia.org/wiki/Kruskal%27s_algorithm
  *
  * @example
  * ```ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thi.ng/adjacency",
-  "version": "2.2.19",
-  "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.0",
-    "@thi.ng/arrays": "^2.4.5",
-    "@thi.ng/bitfield": "^2.2.15",
-    "@thi.ng/dcons": "^3.2.26",
-    "@thi.ng/errors": "^2.2.6",
-    "@thi.ng/sparse": "^0.3.31"
+    "@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.27",
+    "@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": "f445a9cc8022bcdebbf6ff91fd66ced016d72f01\n"
+  "gitHead": "bc6f7f5e2765bb96fe64db804eaf4b2443b47fc6\n"
 }

package/sparse.d.ts

@@ -13,7 +13,8 @@ export declare class AdjacencyMatrix extends CSR implements IGraph<number> {
     neighbors(id: number): number[];
     invert(): AdjacencyMatrix;
     /**
-     * Returns a diagonal sparse matrix {@link @thi.ng/sparse#CSR} containing
+     * Returns a diagonal sparse matrix
+     * [`CSR`](https://docs.thi.ng/umbrella/sparse/classes/CSR.html) containing
      * information about the degree of each vertex, i.e. the number of edges
      * attached to each vertex.
      *
@@ -24,12 +25,13 @@ export declare class AdjacencyMatrix extends CSR implements IGraph<number> {
      */
     degreeMat(deg?: DegreeType): CSR;
     /**
-     * Returns this graph's Laplacian matrix: `L = D - A` Where `D` is
-     * the degree matrix and `A` this adjacency matrix.
+     * Returns this graph's Laplacian matrix: `L = D - A` Where `D` is the
+     * degree matrix and `A` this adjacency matrix.
      *
      * @remarks
-     * - {@link https://en.wikipedia.org/wiki/Laplacian_matrix}
-     * - {@link https://en.wikipedia.org/wiki/Discrete_Laplace_operator}
+     * References:
+     * - https://en.wikipedia.org/wiki/Laplacian_matrix
+     * - https://en.wikipedia.org/wiki/Discrete_Laplace_operator
      *
      * @param deg - degree type for {@link AdjacencyMatrix.degreeMat}
      */
@@ -50,10 +52,11 @@ export declare class AdjacencyMatrix extends CSR implements IGraph<number> {
     toDot(ids?: string[]): string;
 }
 /**
- * Creates an adjacency matrix backed by a sparse {@link @thi.ng/sparse#CSR}
- * matrix, optionally initialize with given edge pairs. Each edge is a `[src,
- * dest]` tuple. If `undirected` is true (default: false), creates symmetrical
- * edges (i.e. undirected graph).
+ * Creates an adjacency matrix backed by a sparse
+ * [`CSR`](https://docs.thi.ng/umbrella/sparse/classes/CSR.html) matrix,
+ * optionally initialize with given edge pairs. Each edge is a `[src, dest]`
+ * tuple. If `undirected` is true (default: false), creates symmetrical edges
+ * (i.e. undirected graph).
  *
  * @param n - max number of vertices
  * @param edges - edge pairs

package/sparse.js

@@ -61,7 +61,8 @@ export class AdjacencyMatrix extends CSR {
         return __invert(defAdjMatrix(this.m, undefined, this.undirected), this.edges());
     }
     /**
-     * Returns a diagonal sparse matrix {@link @thi.ng/sparse#CSR} containing
+     * Returns a diagonal sparse matrix
+     * [`CSR`](https://docs.thi.ng/umbrella/sparse/classes/CSR.html) containing
      * information about the degree of each vertex, i.e. the number of edges
      * attached to each vertex.
      *
@@ -93,12 +94,13 @@ export class AdjacencyMatrix extends CSR {
         return res;
     }
     /**
-     * Returns this graph's Laplacian matrix: `L = D - A` Where `D` is
-     * the degree matrix and `A` this adjacency matrix.
+     * Returns this graph's Laplacian matrix: `L = D - A` Where `D` is the
+     * degree matrix and `A` this adjacency matrix.
      *
      * @remarks
-     * - {@link https://en.wikipedia.org/wiki/Laplacian_matrix}
-     * - {@link https://en.wikipedia.org/wiki/Discrete_Laplace_operator}
+     * References:
+     * - https://en.wikipedia.org/wiki/Laplacian_matrix
+     * - https://en.wikipedia.org/wiki/Discrete_Laplace_operator
      *
      * @param deg - degree type for {@link AdjacencyMatrix.degreeMat}
      */
@@ -144,10 +146,11 @@ export class AdjacencyMatrix extends CSR {
     }
 }
 /**
- * Creates an adjacency matrix backed by a sparse {@link @thi.ng/sparse#CSR}
- * matrix, optionally initialize with given edge pairs. Each edge is a `[src,
- * dest]` tuple. If `undirected` is true (default: false), creates symmetrical
- * edges (i.e. undirected graph).
+ * Creates an adjacency matrix backed by a sparse
+ * [`CSR`](https://docs.thi.ng/umbrella/sparse/classes/CSR.html) matrix,
+ * optionally initialize with given edge pairs. Each edge is a `[src, dest]`
+ * tuple. If `undirected` is true (default: false), creates symmetrical edges
+ * (i.e. undirected graph).
  *
  * @param n - max number of vertices
  * @param edges - edge pairs