@graphty/webgpu-graph-algorithms 0.6.13 → 0.6.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/webgpu-graph-algorithms",
-  "version": "0.6.13",
+  "version": "0.6.15",
   "description": "WebGPU-accelerated graph algorithms and layouts over the @graphty/graph-format snapshot, for Node (Dawn) and browsers",
   "author": "Adam Powers <apowers@ato.ms>",
   "type": "module",
@@ -61,10 +61,10 @@
   "homepage": "https://github.com/graphty-org/graphty-monorepo/tree/master/webgpu-graph-algorithms#readme",
   "dependencies": {
     "@webgpu/types": "^0.1.72",
-    "@graphty/graph-format": "^1.2.0"
+    "@graphty/graph-format": "^1.2.2"
   },
   "peerDependencies": {
-    "@graphty/algorithms": "^1.0.0 || ^2.0.0",
+    "@graphty/algorithms": "^1.0.0 || ^2.0.0 || ^3.0.0",
     "@graphty/graph-format": "^1.0.0",
     "@graphty/layout": "^1.7.0 || ^2.0.0",
     "webgpu": ">=0.4.0 <1.0.0"
@@ -95,8 +95,8 @@
     "vite": "^7.0.5",
     "vitest": "4.1.11",
     "webgpu": "0.4.0",
-    "@graphty/algorithms": "^2.2.0",
-    "@graphty/layout": "^2.0.0"
+    "@graphty/layout": "^2.0.2",
+    "@graphty/algorithms": "^3.0.0"
   },
   "scripts": {
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",

package/src/accelerator.ts

@@ -17,6 +17,7 @@
 import { type F32, type F64, type GraphSnapshot } from "@graphty/graph-format";
 
 import { bellmanFord } from "./algorithms/bellman-ford.js";
+import { betweennessCentrality, edgeBetweennessCentrality } from "./algorithms/betweenness.js";
 import { breadthFirstSearch } from "./algorithms/bfs.js";
 import { closenessCentrality } from "./algorithms/closeness.js";
 import { connectedComponents } from "./algorithms/components.js";
@@ -29,14 +30,16 @@ import { createFruchtermanReingold } from "./layouts/fruchterman-reingold.js";
 import { createSpringElectrical } from "./layouts/spring-electrical.js";
 import {
     type AcceleratorOptions,
+    type BetweennessAcceleratorOptions,
     type BfsOptions,
+    type ClosenessAcceleratorOptions,
     type GpuAccelerator,
-    type HitsOptionsLike,
     type SsspOptions,
 } from "./types/accelerator.js";
 import {
     type ComponentsOptions,
     type EigenvectorOptions,
+    type GpuClosenessResult,
     type GpuHitsResult,
     type GpuLabelResult,
     type GpuPageRankResult,
@@ -45,6 +48,7 @@ import {
     type KatzOptions,
     type PageRankOptions,
 } from "./types/algorithms.js";
+import { type GpuBetweennessResult, type GpuEdgeScoresResult } from "./types/betweenness.js";
 import {
     type ForceAtlas2Stats,
     type FruchtermanReingoldStats,
@@ -79,6 +83,30 @@ function copyBetweenness(defaults: BetweennessDefaults): BetweennessDefaults {
     return Object.freeze(copy);
 }
 
+/**
+ * A betweenness call's options with the accelerator's `algorithms.betweenness` defaults applied: the defaults supply
+ * `sources` / `k` only when the call names neither, so a call's own sampling always wins whole. The defaults serve
+ * graphs of every size, so they are fitted to this one: a default `sources` list keeps only the indices below
+ * `nodeCount` (and then wins over a default `k`), and a default `k` of `nodeCount` or more runs every vertex.
+ * @param defaults - the frozen defaults, if any
+ * @param options - the call's options
+ * @param nodeCount - the snapshot's vertex count
+ * @returns the options the driver runs with
+ */
+function withBetweennessDefaults(
+    defaults: BetweennessDefaults | undefined,
+    options: BetweennessAcceleratorOptions | undefined,
+    nodeCount: number,
+): BetweennessAcceleratorOptions | undefined {
+    if (defaults === undefined || options?.sources !== undefined || options?.k !== undefined) {
+        return options;
+    }
+    if (defaults.sources !== undefined) {
+        return { ...options, sources: defaults.sources.filter((v) => v < nodeCount) };
+    }
+    return { ...options, k: defaults.k !== undefined && defaults.k < nodeCount ? defaults.k : undefined };
+}
+
 /**
  * Frozen copy of the algorithms record, one level deeper for `betweenness`.
  * @param algorithms - the caller's record
@@ -118,8 +146,9 @@ function freezeOptions(options: AcceleratorOptions | undefined): Readonly<Accele
  * Spec 3.3 createAccelerator, verbatim: the object implementing AlgorithmAccelerator & LayoutAccelerator
  * structurally; P3's forceAtlas2, release and dispose, P5's fruchtermanReingold and springElectrical (the same
  * `{ ...o, ...options.layout }` shape as forceAtlas2) plus P7's seven algorithm members and P8's four traversal
- * members, each a delegation to its algorithm with `ctx.assertReady()` first. The accelerator's algorithm defaults are not consulted by any of
- * them: only `betweenness` has any, and it belongs to P9. One per call (the app creates one and injects
+ * members and the two betweenness members, each a delegation to its algorithm with `ctx.assertReady()` first. Only
+ * the betweenness members consult the accelerator's algorithm defaults (`algorithms.betweenness` supplies `sources` /
+ * `k` when a call names neither). One per call (the app creates one and injects
  * it, spec 2.4); `kind` is "webgpu"; `options` is a frozen deep copy; `forceAtlas2(o)` is
  * `createForceAtlas2(ctx, { ...o, ...options.layout })`, so the GPU tuning given here wins over anything the
  * CPU-typed option object carries (spec 3.3: tuning never comes from the caller of the accelerator method);
@@ -163,7 +192,9 @@ export function createAccelerator(ctx: GpuContext, options?: AcceleratorOptions)
          * @param o - the CPU option type (spec 9.3 SpringElectricalOptions, ngraph's names)
          * @returns a fresh simulation in state "created"
          */
-        springElectrical(o?: SpringElectricalOptions): GpuLayoutSimulation<SpringElectricalOptions, SpringElectricalStats> {
+        springElectrical(
+            o?: SpringElectricalOptions,
+        ): GpuLayoutSimulation<SpringElectricalOptions, SpringElectricalStats> {
             ctx.assertReady();
             return createSpringElectrical(ctx, { ...o, ...frozen.layout });
         },
@@ -278,14 +309,51 @@ export function createAccelerator(ctx: GpuContext, options?: AcceleratorOptions)
             ctx.assertReady();
             return await bellmanFord(ctx, gs, source, o);
         },
+        /**
+         * Betweenness centrality on the device (spec 8.4): exact, or sampled through `sources` / `k` (the call's own,
+         * else the accelerator's `algorithms.betweenness` defaults), the unscaled sum over the sources run.
+         * `endpoints: true` is refused.
+         * @param gs - the snapshot
+         * @param o - the seam's `BetweennessAcceleratorOptions`
+         * @returns the f32 scores with `sourcesUsed` and `sigmaOverflow`
+         */
+        async betweennessCentrality(
+            gs: GraphSnapshot,
+            o?: BetweennessAcceleratorOptions,
+        ): Promise<GpuBetweennessResult> {
+            ctx.assertReady();
+            return await betweennessCentrality(
+                ctx,
+                gs,
+                withBetweennessDefaults(frozen.algorithms?.betweenness, o, gs.nodeCount),
+            );
+        },
+        /**
+         * Edge betweenness on the device (spec 8.4): one score per edge, arcs summed and halved when undirected; sampling
+         * and defaults as `betweennessCentrality`.
+         * @param gs - the snapshot
+         * @param o - the seam's `BetweennessAcceleratorOptions`
+         * @returns the f32 per-edge scores with `sourcesUsed` and `sigmaOverflow`
+         */
+        async edgeBetweennessCentrality(
+            gs: GraphSnapshot,
+            o?: BetweennessAcceleratorOptions,
+        ): Promise<GpuEdgeScoresResult> {
+            ctx.assertReady();
+            return await edgeBetweennessCentrality(
+                ctx,
+                gs,
+                withBetweennessDefaults(frozen.algorithms?.betweenness, o, gs.nodeCount),
+            );
+        },
         /**
          * Closeness centrality on the device (spec 8.4; P8-T13): the bit-parallel multi-source sweep, or one `sssp`
          * per source when `weighted`. `maxIterations` / `tolerance` are refused when defined (P8 PD-25).
          * @param gs - the snapshot
-         * @param o - the seam's placeholder `HitsOptionsLike` (`weighted`)
-         * @returns the f32 scores with `precision: "f32"` (spec 9.7)
+         * @param o - `weighted`, and a sampled run's `sources` (undirected snapshots only)
+         * @returns the f32 scores with `precision: "f32"` (spec 9.7) and `sourcesUsed`
          */
-        async closenessCentrality(gs: GraphSnapshot, o?: HitsOptionsLike): Promise<GpuScoresResult> {
+        async closenessCentrality(gs: GraphSnapshot, o?: ClosenessAcceleratorOptions): Promise<GpuClosenessResult> {
             ctx.assertReady();
             return await closenessCentrality(ctx, gs, o);
         },