@graphty/webgpu-graph-algorithms 0.6.3 → 0.6.4

package/src/constants.ts

@@ -214,3 +214,15 @@ export const GRID_EXTENT_FLOOR = 1e-6;
 export const GRID_BBOX_MARGIN = 1.01;
 /** The key width the grid always sorts with (P4 PD-5): three 8-bit passes cover the 19-bit 2D keys at G = 512 and the 22-bit 3D keys at G = 128, and an odd pass count leaves `sortedIdx` in the scratch pair. */
 export const GRID_SORT_BITS = 24;
+/** Design 8.4 (P8 PD-7): traversal levels recorded per submit -- one four-byte readback per 32 BFS levels, SSSP rounds or closeness levels. */
+export const MAX_LEVELS_PER_SUBMIT = 32;
+/** Design 8.4 and 6 row 8 (P8): a frontier at most this long runs the fused expand-contract kernel (Merrill's "fleeting iterations"); the default of the `fusedMax` uniform, which a test may set to 0 or `U32_MAX`. */
+export const FUSED_FRONTIER_MAX = 4096;
+/** P8-T4: the indirect dispatch slots `frontier-finalize` writes per level (expand, contract, fused, fill-bits, bitset-build, bottom-up, fused-retry); the args buffer is `MAX_LEVELS_PER_SUBMIT x FRONTIER_CANDIDATES x 16` bytes. */
+export const FRONTIER_CANDIDATES = 7;
+/** Design 8.4 (P8 PD-21): Beamer's beta -- switch back to top-down when `frontierCount * BEAMER_BETA < unvisitedCount` and the frontier is shrinking; alpha is derived from the graph, so it has no constant. */
+export const BEAMER_BETA = 24;
+/** Design 8.4 (P8 PD-22): the near-far split `delta = SSSP_DELTA_FACTOR * avgWeight / avgDegree`, computed on the host from the weight vector the run uses. */
+export const SSSP_DELTA_FACTOR = 32;
+/** The bit pattern of +Infinity, the unreached sentinel of `dist` (P8 PD-9); interpolated into the prelude as `F32_INF_BITS` so no body types the literal. */
+export const F32_INF_BITS = 0x7f800000;

package/src/index.ts

@@ -8,7 +8,8 @@
  * isSoftwareAdapter. P1 adds GpuContext and degree (values) and the context / run / profiler types. P2 adds nothing
  * (Lease, CommandBatch, UniformRing are internal). P3 adds the layout factory, the accelerator, the two default
  * tables, the seeder and the layout / accelerator types. P5 adds the two factories, the two default tables and the
- * two stats records. P4 adds calibrateLayout and its two records. test/index.test.ts pins the value list and
+ * two stats records. P4 adds calibrateLayout and its two records. P8 adds the four traversals and their three result
+ * records. test/index.test.ts pins the value list and
  * test/types/public-api.test-d.ts the type list. This comment must never spell the internal
  * JSDoc tag: it is the leading comment of the first export statement, and stripInternal would drop that statement
  * from the emitted declarations.
@@ -54,6 +55,12 @@ export { connectedComponents } from "./algorithms/components.js";
 export { pageRank, personalizedPageRank } from "./algorithms/pagerank.js";
 export { eigenvectorCentrality, hits, katzCentrality } from "./algorithms/spectral.js";
 
+// ==================== algorithms (P8: the frontier family, spec 3.3 lines 807-810, 8.4; the seam's option types in)
+export { bellmanFord } from "./algorithms/bellman-ford.js";
+export { breadthFirstSearch } from "./algorithms/bfs.js";
+export { closenessCentrality } from "./algorithms/closeness.js";
+export { sssp } from "./algorithms/sssp.js";
+
 // ==================== layouts and the accelerator (P3; the two P5 factories; P4's calibrateLayout, spec 2.2)
 export { createAccelerator } from "./accelerator.js";
 export { calibrateLayout } from "./layouts/calibrate.js";
@@ -70,6 +77,7 @@ export type {
     ApspResultLike,
     BellmanFordResultLike,
     BetweennessAcceleratorOptions,
+    BfsOptions,
     BfsResultLike,
     CommunityResultLike,
     CorenessResultLike,
@@ -83,9 +91,14 @@ export type {
     MstResultLike,
     PageRankResultLike,
     ScoresResultLike,
+    SsspOptions,
     SsspResultLike,
 } from "./types/accelerator.js";
 
+// ==================== types: the P8 traversal results (spec 3.3 lines 830-832, 9.7); the option types are the seam's
+// BfsOptions / SsspOptions / HitsOptionsLike above (P8 PD-19)
+export type { GpuBellmanFordResult, GpuBfsResult, GpuSsspResult } from "./types/traversal.js";
+
 // ==================== types: the P7 algorithm results and option records (spec 3.3 lines 815-828, 9.7)
 export type {
     ComponentsOptions,

package/src/kernel/prelude.ts

@@ -12,6 +12,7 @@
 import { INVALID_INDEX } from "@graphty/graph-format";
 
 import {
+    F32_INF_BITS,
     FA2_COINCIDENT_SQ,
     FA2_DISTANCE_FLOOR,
     FA2_DISTANCE_FLOOR_SQ,
@@ -51,6 +52,7 @@ export function wgslF32Literal(value: number): string {
 export const PRELUDE_WGSL: string = /* wgsl */ `// ---- prelude: constants, standard overrides, helpers (every module receives this text first)
 const INVALID_INDEX: u32 = ${INVALID_INDEX}u;
 const U32_MAX: u32 = ${U32_MAX}u;
+const F32_INF_BITS: u32 = ${F32_INF_BITS}u;
 const MAX_WORKGROUPS_PER_DIM: u32 = ${MAX_WORKGROUPS_PER_DIM}u;
 const FA2_DIST_FLOOR: f32 = ${wgslF32Literal(FA2_DISTANCE_FLOOR)};
 const FA2_DIST_FLOOR_SQ: f32 = ${wgslF32Literal(FA2_DISTANCE_FLOOR_SQ)};
@@ -101,7 +103,7 @@ fn kick_dir(i: u32, j: u32, dim: u32) -> vec3f {
 /** Line count of PRELUDE_WGSL (the compilation-info formatter subtracts it plus the emitted declarations). */
 export const PRELUDE_LINES: number = PRELUDE_WGSL.split("\n").length;
 
-/** The workgroup-memory reduction helpers (the twin) (4.3). */
+/** The workgroup-memory reduction helpers (the twin) (4.3), plus the workgroup-memory form of the P8 scan helper. */
 export const REDUCE_HELPERS_WORKGROUP_WGSL: string = /* wgsl */ `var<workgroup> wg_scratch_v: array<vec4f, WG>;
 var<workgroup> wg_scratch_u: array<u32, WG>;
 fn combine_v(a: vec4f, b: vec4f, op: u32) -> vec4f {
@@ -138,9 +140,24 @@ fn wg_reduce_u32(v: u32, lid: u32, op: u32) -> u32 {
     workgroupBarrier();
     return total;
 }
+fn wg_scan_u32(v: u32, lid: u32) -> u32 {
+    workgroupBarrier();
+    wg_scratch_u[lid] = v;
+    workgroupBarrier();
+    for (var s = 1u; s < WG; s = s * 2u) {                       // Hillis-Steele inclusive scan (scan-block's body); uniform: every lane runs every round
+        var t = 0u;
+        if (lid >= s) { t = wg_scratch_u[lid - s]; }
+        workgroupBarrier();
+        wg_scratch_u[lid] = wg_scratch_u[lid] + t;
+        workgroupBarrier();
+    }
+    let inclusive = wg_scratch_u[lid];
+    workgroupBarrier();                                          // the scratch is free for the next call
+    return inclusive;
+}
 fn wg_reduce_f32(v: f32, lid: u32, op: u32) -> f32 { return wg_reduce_vec4(vec4f(v, 0.0, 0.0, 0.0), lid, op).x; }`;
 
-/** The subgroup reduction helpers, spliced only with `enable subgroups;` (4.3). */
+/** The subgroup reduction helpers, spliced only with `enable subgroups;` (4.3), plus the subgroup form of the P8 scan helper. */
 export const REDUCE_HELPERS_SUBGROUP_WGSL: string = /* wgsl */ `override SG_SLOTS: u32 = (WG + SUBGROUP_MIN - 1u) / SUBGROUP_MIN;   // one slot per subgroup; the count is largest when the compiler picks the SMALLEST size
 var<workgroup> sg_counter: atomic<u32>;
 var<workgroup> sg_val_v: array<vec4f, SG_SLOTS>;
@@ -216,10 +233,28 @@ fn wg_reduce_u32(v: u32, lid: u32, op: u32) -> u32 {
     workgroupBarrier();
     return total;
 }
+fn wg_scan_u32(v: u32, lid: u32) -> u32 {
+    workgroupBarrier();
+    if (lid == 0u) { atomicStore(&sg_counter, 0u); }
+    workgroupBarrier();
+    let inSub = subgroupExclusiveAdd(v) + v;                     // the lane's inclusive sum within its subgroup
+    let total = subgroupAdd(v);
+    let key = subgroupMin(lid);                                   // the subgroup's identity: its smallest local id (D16)
+    var slot = 0u;
+    if (subgroupElect()) { slot = atomicAdd(&sg_counter, 1u); }
+    slot = subgroupBroadcast(slot, 0u);
+    if (subgroupElect()) { sg_val_u[slot] = total; sg_key[slot] = key; }
+    workgroupBarrier();
+    let count = atomicLoad(&sg_counter);
+    var carry = 0u;                                               // the totals of every subgroup whose key is below this lane's: LANE order, whatever order the slots were taken in
+    for (var k = 0u; k < count; k = k + 1u) { if (sg_key[k] < key) { carry = carry + sg_val_u[k]; } }
+    workgroupBarrier();                                          // the slots are free for the next call
+    return inSub + carry;
+}
 fn wg_reduce_f32(v: f32, lid: u32, op: u32) -> f32 { return wg_reduce_vec4(vec4f(v, 0.0, 0.0, 0.0), lid, op).x; }`;
 
-/** The helper function names a body may call when its spec lists needs: ["subgroups"]. */
-export const REDUCE_HELPER_NAMES = ["wg_reduce_f32", "wg_reduce_u32", "wg_reduce_vec4"] as const;
+/** The helper function names a body may call when its spec lists needs: ["subgroups"]; `wg_scan_u32(v, lid)` is an INCLUSIVE prefix sum over the workgroup in lane order (P8-T1), bitwise the same in both forms. */
+export const REDUCE_HELPER_NAMES = ["wg_reduce_f32", "wg_reduce_u32", "wg_reduce_vec4", "wg_scan_u32"] as const;
 
 /**
  * The WGSL reserved words of spec section 16.2 (the `_reserved` production), frozen; composeWgsl rejects a body or

package/src/kernel/uniform-ring.ts

@@ -18,6 +18,14 @@ import type { UniformBlock, UniformValues } from "./struct-block.js";
 export class UniformRing {
     /** Number of slots. */
     readonly slots: number;
+    /**
+     * How many reservations covered a DIRTY slot (written since the last `flush()`): the one reuse that corrupts,
+     * because the batch being recorded still reads that record and the shadow overwrites it before the flush sends
+     * either. A wrap onto slots an earlier, flushed batch wrote is harmless: its `writeBuffer` is ordered before that
+     * batch's submit and the next flush after it. A driver sizes its ring so this stays 0 (P8-T12: `bfsRingSlots`).
+     */
+    overruns = 0;
+    private readonly dirty: Uint8Array;
     private readonly device: GPUDevice;
     private readonly allocator: AllocationTracker;
     private readonly buffer: GPUBuffer;
@@ -54,6 +62,7 @@ export class UniformRing {
         this.label = label;
         this.shadow = new ArrayBuffer(slots * UNIFORM_SLOT_BYTES);
         this.view = new DataView(this.shadow);
+        this.dirty = new Uint8Array(slots);
         this.buffer = allocator.createBuffer({
             label,
             size: slots * UNIFORM_SLOT_BYTES,
@@ -105,6 +114,9 @@ export class UniformRing {
         }
         const first = this.next;
         this.next += count;
+        if (this.dirty.subarray(first, first + count).includes(1)) {
+            this.overruns += 1;
+        }
         return first;
     }
 
@@ -118,6 +130,7 @@ export class UniformRing {
         this.checkSlot(slot);
         this.assertFits(block);
         block.write(this.view, values, slot * UNIFORM_SLOT_BYTES);
+        this.dirty[slot] = 1;
         if (this.dirtyLo < 0 || slot < this.dirtyLo) {
             this.dirtyLo = slot;
         }
@@ -138,6 +151,7 @@ export class UniformRing {
         const begin = this.dirtyLo * UNIFORM_SLOT_BYTES;
         const end = (this.dirtyHi + 1) * UNIFORM_SLOT_BYTES;
         this.device.queue.writeBuffer(this.buffer, begin, this.shadow, begin, end - begin);
+        this.dirty.fill(0);
         this.dirtyLo = -1;
         this.dirtyHi = -1;
     }