@thi.ng/adjacency 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-10-18T18:06:31Z
+- **Last updated**: 2023-10-19T09:52:45Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,18 @@ 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.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/adjacency@2.5.0) (2023-10-19)
+
+#### 🚀 Features
+
+- explicit version bump for @firfi's recent additions ([#400](https://github.com/thi-ng/umbrella/issues/400)) ([0d00025](https://github.com/thi-ng/umbrella/commit/0d00025))
+  - see: [2fd123d741586fe29a8cc63b7aa30f3ea9d35ab2](https://github.com/thi-ng/umbrella/commit/2fd123d741586fe29a8cc63b7aa30f3ea9d35ab2)
+  - update readme with API examples
+
+#### 🩹 Bug fixes
+
+- fix AdjacencyBitMatrix.numVertices() ([bd034ab](https://github.com/thi-ng/umbrella/commit/bd034ab))
+
 ## [2.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/adjacency@2.4.0) (2023-10-18)
 
 #### 🚀 Features

package/README.md

@@ -19,6 +19,7 @@ This project is part of the
 - [Dependencies](#dependencies)
 - [Usage examples](#usage-examples)
 - [API](#api)
+  - [Basic usage](#basic-usage)
 - [Authors](#authors)
 - [License](#license)
 
@@ -73,7 +74,7 @@ For Node.js REPL:
 const adjacency = await import("@thi.ng/adjacency");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 2.54 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.57 KB
 
 ## Dependencies
 
@@ -102,16 +103,91 @@ A selection:
 
 TODO
 
+### Basic usage
+
+```ts tangle:export/readme.ts
+import { defAdjBitMatrix, type Edge } from "@thi.ng/adjacency";
+
+// relationships
+const rels = {
+    a: ["b", "c"],
+    b: ["d"],
+    c: ["d", "e"],
+    e: ["a", "d", "b"],
+};
+
+// form set of unique node IDs
+const nodeIDs = [
+    ...new Set(Object.entries(rels).flatMap(([id, rels]) => [id, ...rels])),
+];
+
+// the current adjacency matrix impls only support numeric node IDs
+// therefore, we first map node names to numeric IDs
+const index = new Map(nodeIDs.map((id, i) => [id, i]));
+
+// transform relationships into sequence of edges (aka `[from,to]` tuples)
+const edges = Object.entries(rels).flatMap(([id, rels]) =>
+    rels.map((x) => <Edge>[index.get(id), index.get(x)])
+);
+
+// build adjacency matrix, treat as undirected graph
+// edges can also be added/removed later
+const graph = defAdjBitMatrix(nodeIDs.length, edges, true);
+
+// graph queries
+console.log("edges:", graph.numEdges(), "verts:", graph.numVertices());
+// edges: 8 verts: 5
+
+// check if vertex/node is present in graph
+// (this is implementation specific and for the bitmatrix backed version here
+// only true if the vertex has at least 1 edge...)
+console.log(graph.hasVertex(index.get("d")!));
+// true
+
+// are `a` and `d` connected?
+console.log(graph.hasEdge(index.get("a")!, index.get("d")!));
+// false
+
+// number of connected nodes for `a`
+// (in directed graphs, there's also possibility to distinguish between in/out/inout)
+console.log(graph.degree(index.get("a")!));
+// 3
+
+// neighbors of `a` (with reverse lookup of node names)
+console.log(graph.neighbors(index.get("a")!).map((x) => nodeIDs[x]));
+// [ 'b', 'c', 'e' ]
+
+// serialize to GraphViz DOT format (see result visualization below)
+console.log(graph.toDot(nodeIDs));
+// graph g {
+// "d"--"e";
+// "c"--"d";
+// "c"--"e";
+// "b"--"d";
+// "b"--"e";
+// "a"--"b";
+// "a"--"c";
+// "a"--"e";
+// }
+
+// resize to new capacity & add add/remove vertices/edges
+graph.resize(10);
+
+graph.addEdge(4, 5);
+graph.removeEdge(0, 1);
+```
+
 ## Authors
 
-- [Karsten Schmidt](https://thi.ng)
+- [Karsten Schmidt](https://thi.ng) (Main author)
+- [Igor Loskutov](https://github.com/Firfi)
 
 If this project contributes to an academic publication, please cite it as:
 
 ```bibtex
 @misc{thing-adjacency,
   title = "@thi.ng/adjacency",
-  author = "Karsten Schmidt",
+  author = "Karsten Schmidt and others",
   note = "https://thi.ng/adjacency",
   year = 2018
 }

package/api.d.ts

@@ -38,6 +38,12 @@ export interface IGraph<T = number> {
      * @param to -
      */
     hasEdge(from: T, to: T): boolean;
+    /**
+     * Returns true if a vertex exists for the given id.
+     *
+     * @param id -
+     */
+    hasVertex(id: T): boolean;
     /**
      * Returns number of edges for given vertex. By default only outgoing edges
      * are counted, but can be customized via given {@link DegreeType}. Note: In

package/binary.d.ts

@@ -23,6 +23,7 @@ export declare class AdjacencyBitMatrix implements IGraph<number> {
     addEdge(from: number, to: number): boolean;
     removeEdge(from: number, to: number): boolean;
     hasEdge(from: number, to: number): boolean;
+    hasVertex(id: number): boolean;
     degree(id: number, type?: DegreeType): number;
     neighbors(id: number): number[];
     similarity(id: number, threshold?: number): number[][];

package/binary.js

@@ -27,7 +27,7 @@ export class AdjacencyBitMatrix {
         return this.numE;
     }
     numVertices() {
-        return this.mat.n;
+        return this.mat.m;
     }
     /**
      * Resizes matrix to new size given.
@@ -57,6 +57,9 @@ export class AdjacencyBitMatrix {
     hasEdge(from, to) {
         return this.mat.at(from, to) !== 0;
     }
+    hasVertex(id) {
+        return (this.mat.popCountRow(id) !== 0 || this.mat.popCountColumn(id) !== 0);
+    }
     degree(id, type = "out") {
         let degree = 0;
         if (this.undirected || type !== "in")

package/list.d.ts

@@ -12,6 +12,7 @@ export declare class AdjacencyList implements IGraph<number> {
     edges(): Generator<Edge, void, unknown>;
     addVertex(id: number): void;
     removeVertex(id: number): boolean;
+    hasVertex(id: number): boolean;
     addEdge(from: number, to: number): boolean;
     removeEdge(from: number, to: number): boolean;
     hasEdge(from: number, to: number): boolean;

package/list.js

@@ -55,6 +55,9 @@ export class AdjacencyList {
         this.numV--;
         return true;
     }
+    hasVertex(id) {
+        return !!this.adjacency[id];
+    }
     addEdge(from, to) {
         const vertex = this.ensureVertexData(from);
         this.ensureVertexData(to);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/adjacency",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Sparse & bitwise adjacency matrices, lists and selected traversal algorithms for directed & undirected graphs",
   "type": "module",
   "module": "./index.js",
@@ -22,6 +22,9 @@
     }
   ],
   "author": "Karsten Schmidt (https://thi.ng)",
+  "contributors": [
+    "Igor Loskutov (https://github.com/Firfi)"
+  ],
   "license": "Apache-2.0",
   "scripts": {
     "build": "yarn clean && tsc --declaration",
@@ -122,5 +125,5 @@
     ],
     "year": 2018
   },
-  "gitHead": "46e445c09f2909d1aeaa9fdc8d8b3aa61c114db2\n"
+  "gitHead": "7377b4b99095076ffc857b4b320902816ea6ae34\n"
 }

package/sparse.d.ts

@@ -7,6 +7,7 @@ export declare class AdjacencyMatrix extends CSR implements IGraph<number> {
     addEdge(from: number, to: number): boolean;
     removeEdge(from: number, to: number): boolean;
     hasEdge(from: number, to: number): boolean;
+    hasVertex(id: number): boolean;
     numEdges(): number;
     numVertices(): number;
     degree(id: number, type?: DegreeType): number;

package/sparse.js

@@ -38,6 +38,9 @@ export class AdjacencyMatrix extends CSR {
     hasEdge(from, to) {
         return this.at(from, to) !== 0;
     }
+    hasVertex(id) {
+        return this.degree(id, "inout") > 0;
+    }
     numEdges() {
         const n = this.data.length;
         return this.undirected ? n / 2 : n;