@graphty/webgpu-graph-algorithms 0.2.0 → 0.3.0

package/src/types/algorithms.ts

@@ -0,0 +1,82 @@
+/**
+ * The result and option records of the P7 algorithms (spec 3.3 lines 815-828, 9.7). The `Gpu*Result` shapes are the
+ * design's verbatim; the option records are this package's own, spelled MEMBER FOR MEMBER as the CPU seam spells
+ * them so one object literal satisfies both sides (the same D27 mirror rule src/types/options.ts follows for the
+ * layout options). Types only: this file imports nothing at runtime.
+ *
+ * The CPU counterparts, when phase M8a lands them (plan 2026-09-19-webgpu-m8a-algorithms-seam, Task M8a-T8):
+ * `PageRankOptions` here is `IndexedPageRankOptions` there (`{ dampingFactor?, maxIterations?, tolerance?,
+ * weighted? }`); `HitsOptions`, `EigenvectorOptions` and `KatzOptions` here all correspond to the ONE
+ * `HitsOptionsLike` there (`{ maxIterations?, tolerance?, weighted? }`), which is why every one of them carries
+ * those three members and `KatzOptions` adds `alpha` / `beta` on top; `ComponentsOptions` has no CPU counterpart at
+ * all, because `AlgorithmAccelerator.connectedComponents?(s: GraphSnapshot): Promise<LabelResultLike>` declares no
+ * options parameter. `weighted`, never `weight`: that is the member name graph-format design 14.2 fixes at
+ * `design/graph-format/graph-format-design.md:3892` and the one M8a ports.
+ */
+
+import type { F32, U32 } from "@graphty/graph-format";
+
+/** Spec 3.3 line 815: every score result carries `precision` so a consumer can label GPU scores (Q-24). */
+export interface GpuScoresResult {
+    readonly scores: F32;
+    readonly iterations: number;
+    readonly converged: boolean;
+    readonly precision: "f32";
+}
+
+/** Spec 3.3 line 816: `iterations` is the first iteration whose L1 delta fell below the tolerance (8.2), not the batch boundary. */
+export interface GpuPageRankResult extends GpuScoresResult {
+    readonly danglingMass: number;
+}
+
+/** Spec 3.3 line 817. */
+export interface GpuHitsResult {
+    readonly hubs: F32;
+    readonly authorities: F32;
+    readonly iterations: number;
+    readonly converged: boolean;
+    readonly precision: "f32";
+}
+
+/** Spec 3.3 line 818: labels dense 0..count-1 in first-seen order (renumberPartition); groups() is index-aligned. */
+export interface GpuLabelResult {
+    readonly labels: U32;
+    readonly count: number;
+    groups(): U32[];
+}
+
+/** The CPU seam's IndexedPageRankOptions, member for member (M8a Task M8a-T8; graph-format design 14.2 :3892). */
+export interface PageRankOptions {
+    readonly dampingFactor?: number | undefined;
+    readonly maxIterations?: number | undefined;
+    readonly tolerance?: number | undefined;
+    readonly weighted?: boolean | undefined;
+}
+
+/** The CPU seam's HitsOptionsLike, member for member (M8a Task M8a-T8). */
+export interface HitsOptions {
+    readonly maxIterations?: number | undefined;
+    readonly tolerance?: number | undefined;
+    readonly weighted?: boolean | undefined;
+}
+
+/** The CPU seam's HitsOptionsLike again: `eigenvectorCentrality` takes that same shape on the CPU side. */
+export interface EigenvectorOptions {
+    readonly maxIterations?: number | undefined;
+    readonly tolerance?: number | undefined;
+    readonly weighted?: boolean | undefined;
+}
+
+/** HitsOptionsLike plus Katz's own two: `alpha` is the attenuation and `beta` the constant term. */
+export interface KatzOptions {
+    readonly alpha?: number | undefined;
+    readonly beta?: number | undefined;
+    readonly maxIterations?: number | undefined;
+    readonly tolerance?: number | undefined;
+    readonly weighted?: boolean | undefined;
+}
+
+/** GPU-only (spec 3.3 line 797: `renumber: true` by default, Q-12); the CPU seam's connectedComponents takes none. */
+export interface ComponentsOptions {
+    readonly renumber?: boolean | undefined;
+}

package/src/wgsl/pr-finalize.wgsl.ts

@@ -0,0 +1,36 @@
+/**
+ * The `pr-finalize` kernel body (spec 8.2 dispatch (b)): ONE workgroup folds the `P.groups` per-workgroup partials
+ * into the header at `partials[0]` -- a STORAGE region, never a uniform, read by the next dispatch of the same
+ * pass -- and records `firstConverged` the first time the delta falls below `P.convergeThreshold`. NORM_MODE 2
+ * stores the square root of the folded norm (the L2 case). The recorded iteration is `P.iteration - 1u` because
+ * the delta a scale pass produces at iteration i is `|x(i-1) - x(i-2)|`, the error of iteration i - 1 (PD-9).
+ * The body is normative: a sabotage mutation is a textual edit of it, so it is not restyled.
+ */
+
+/** Entry point `pr_finalize`; override NORM_MODE (2 takes the square root of the folded norm, every other value stores it as folded). */
+export const prFinalizeWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn pr_finalize(@builtin(local_invocation_id) lid: vec3<u32>) {
+    var d = 0.0;
+    var e = 0.0;
+    var m = 0.0;
+    for (var g = lid.x; g < P.groups; g = g + WG) {
+        d = d + partials[1u + g].danglingMass;
+        e = e + partials[1u + g].delta;
+        m = m + partials[1u + g].norm;
+    }
+    let folded = wg_reduce_vec4(vec4f(d, e, m, 0.0), lid.x, 0u);
+    if (lid.x == 0u) {
+        partials[0].danglingMass = folded.x;
+        partials[0].delta = folded.y;
+        var norm = folded.z;
+        if (NORM_MODE == 2u) { norm = sqrt(max(0.0, folded.z)); }
+        partials[0].norm = norm;
+        partials[0].iteration = P.iteration;
+        let unset = partials[0].firstConverged == U32_MAX;
+        if (P.trackConvergence == 1u && P.iteration >= 2u && folded.y < P.convergeThreshold && unset) {
+            partials[0].firstConverged = P.iteration - 1u;
+        }
+    }
+}
+`;

package/src/wgsl/pr-scale.wgsl.ts

@@ -0,0 +1,48 @@
+/**
+ * The `pr-scale` kernel body (spec 8.2 dispatch (a)): one invocation per node writes `xNorm[u]` and contributes a
+ * per-workgroup partial of the dangling mass, the L1 delta `|rankIn - rankPrev|` and, for the spectral modes, the
+ * norm term. NORM_MODE selects the divisor: 0 PageRank (`rankIn[u] / outWeightSum[u]`, 0 and a dangling
+ * contribution when the sum is not positive); 1 and 2 are NORM PASSES that write no xNorm and only accumulate
+ * `abs(x)` (L1) or `x * x` (L2); 3 divides by the scalar `partials[0].norm` the previous dispatch folded; 4 is the
+ * identity (Katz). The body is normative: a sabotage mutation is a textual edit of it, so it is not restyled.
+ *
+ * The guard is named `inRange`, never `active`: `active` is a WGSL reserved word (spec 16.2) and the composer
+ * rejects it before a device is touched.
+ */
+
+/** Entry point `pr_scale`; override NORM_MODE (0 PageRank, 1 L1 norm pass, 2 L2 norm pass, 3 scale by partials[0].norm, 4 identity). */
+export const prScaleWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn pr_scale(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let u = linear_id(wid, lid.x);
+    let inRange = u < P.n;
+    var x = 0.0;
+    var prev = 0.0;
+    if (inRange) { x = rankIn[u]; prev = rankPrev[u]; }
+    var dangling = 0.0;
+    var delta = 0.0;
+    var normTerm = 0.0;
+    if (inRange) {
+        delta = abs(x - prev);
+        if (NORM_MODE == 0u) {
+            let divisor = outWeightSum[u];
+            if (divisor <= 0.0) { dangling = x; xNorm[u] = 0.0; } else { xNorm[u] = x / divisor; }
+        }
+        if (NORM_MODE == 1u) { normTerm = abs(x); }
+        if (NORM_MODE == 2u) { normTerm = x * x; }
+        if (NORM_MODE == 3u) {
+            var scale = partials[0].norm;
+            if (scale <= 0.0) { scale = 1.0; }
+            xNorm[u] = x / scale;
+        }
+        if (NORM_MODE == 4u) { xNorm[u] = x; }
+    }
+    let folded = wg_reduce_vec4(vec4f(dangling, delta, normTerm, 0.0), lid.x, 0u);
+    if (lid.x == 0u) {
+        let slot = 1u + group_id(wid);
+        partials[slot].danglingMass = folded.x;
+        partials[slot].delta = folded.y;
+        partials[slot].norm = folded.z;
+    }
+}
+`;

package/src/wgsl/spmv-pull.wgsl.ts

@@ -0,0 +1,47 @@
+/**
+ * The `spmv-pull` kernel body (spec 6 row 9, 8.2; PD-1 of the M8b plan): one invocation per row of the REVERSE
+ * adjacency, grid-stride over `[0, P.n)`, folding `weight * xNorm[nbr]` over the row's in-arcs in chunks of 64
+ * terms (a two-level f32 sum: the chunk absorbs the rounding of 64 terms, the row total the rounding of the chunk
+ * count, so a 10,000-arc hub row loses about 200 rounding steps instead of 10,000; Kahan compensation is not used
+ * because Metal's shader compiler folds `((acc + term) - acc) - term` to zero whatever hides it) and writing
+ * `rankOut[v] = beta * pv + alpha * (sum + danglingMass * pv)`, where `pv` is `personalization[v]` when
+ * HAS_PERSONALIZATION and the uniform `P.uniformP` otherwise. PageRank sets alpha to the
+ * damping factor, beta to `1 - alpha` and USE_DANGLING; HITS and eigenvector set alpha 1, beta 0, uniformP 0; Katz
+ * sets alpha to the attenuation, beta to its constant and uniformP 1. The body is normative: a sabotage mutation
+ * (test/helpers/sabotage.ts) is a textual edit of it, so it is not restyled.
+ */
+
+/** Entry point `spmv_pull`; overrides HAS_PERSONALIZATION and USE_DANGLING plus the standard USE_PERM / HAS_WEIGHTS. */
+export const spmvPullWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn spmv_pull(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    var dangling = 0.0;
+    if (USE_DANGLING) { dangling = partials[0].danglingMass; }
+    let first = linear_id(wid, lid.x);
+    for (var row = first; row < P.n; row = row + P.stride) {
+        let v = select(row, perm[row], USE_PERM);
+        let a0 = max(rowPtr[v], P.arcBase);
+        let a1 = min(rowPtr[v + 1u], P.arcEnd);
+        var acc = 0.0;
+        var chunk = 0.0;
+        var inChunk = 0u;
+        for (var arc = a0; arc < a1; arc = arc + 1u) {
+            let nbr = colIdx[arc - P.arcBase];               // \`target\` is a WGSL reserved word (spec 16.2)
+            var weight = 1.0;
+            if (HAS_WEIGHTS) { weight = weights[arc - P.arcBase]; }
+            // two-level sum: 64 terms into chunk, chunk into acc (see the header; no compensation, no select)
+            chunk = chunk + (weight * xNorm[nbr]);
+            inChunk = inChunk + 1u;
+            if (inChunk == 64u) {
+                acc = acc + chunk;
+                chunk = 0.0;
+                inChunk = 0u;
+            }
+        }
+        acc = acc + chunk;
+        var pv = P.uniformP;
+        if (HAS_PERSONALIZATION) { pv = personalization[v]; }
+        rankOut[v] = (P.beta * pv) + (P.alpha * (acc + (dangling * pv)));
+    }
+}
+`;

package/src/wgsl/wcc-compress.wgsl.ts

@@ -0,0 +1,26 @@
+/**
+ * The `wcc-compress` kernel body (spec 8.3): pointer jumping to the root, reading through `atomicLoad` on the same
+ * `array<atomic<u32>>` because WGSL forbids mixing atomic and plain access to one element. The walk is bounded by
+ * `P.maxSteps`; a walk that runs out leaves a shorter path, which the next round finishes. The body is normative:
+ * a sabotage mutation is a textual edit of it, so it is not restyled.
+ */
+
+/** Entry point `wcc_compress`; no overrides. */
+export const wccCompressWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn wcc_compress(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let first = linear_id(wid, lid.x);
+    for (var v = first; v < P.items; v = v + P.stride) {
+        var root = atomicLoad(&comp[v]);
+        var steps = 0u;
+        loop {
+            let parent = atomicLoad(&comp[root]);
+            if (parent == root) { break; }
+            if (steps >= P.maxSteps) { break; }
+            steps = steps + 1u;
+            root = parent;
+        }
+        atomicStore(&comp[v], root);
+    }
+}
+`;

package/src/wgsl/wcc-link-edges.wgsl.ts

@@ -0,0 +1,46 @@
+/**
+ * The `wcc-link-edges` kernel body (spec 8.3): the each-edge-once link round of Afforest, correct for directed and
+ * undirected input alike because `edgeList()` yields every logical edge once in declared orientation (design 10.1).
+ * `link_pair` is the same GAP `Link` transcription as wcc-link-sample (each module is composed alone, so the helper
+ * is copied, not shared): all-u32 CAS on `comp`, an `array<atomic<u32>>` because WGSL forbids mixing atomic and
+ * plain access to one element, with a bounded retry loop (PD-5) and the changed flag at `P.flagIndex` inside the
+ * same array (PD-4). The `P.giant` guard is GAP's "skip the vertices already in the giant component" and is a pure
+ * optimisation -- linking two vertices already in one component is a no-op. The body is normative: a sabotage
+ * mutation is a textual edit of it, so it is not restyled.
+ */
+
+/** Entry point `wcc_link_edges`; no overrides. */
+export const wccLinkEdgesWgsl = /* wgsl */ `
+fn link_pair(a: u32, b: u32) {
+    var p1 = atomicLoad(&comp[a]);
+    var p2 = atomicLoad(&comp[b]);
+    var steps = 0u;
+    loop {
+        if (p1 == p2) { break; }
+        if (steps >= P.maxSteps) { atomicStore(&comp[P.flagIndex], 1u); break; }
+        steps = steps + 1u;
+        let hi = max(p1, p2);
+        let lo = min(p1, p2);
+        let pHigh = atomicLoad(&comp[hi]);
+        if (pHigh == lo) { break; }
+        if (pHigh == hi) {
+            let swapped = atomicCompareExchangeWeak(&comp[hi], hi, lo);
+            if (swapped.exchanged) { atomicStore(&comp[P.flagIndex], 1u); break; }
+        }
+        p1 = atomicLoad(&comp[atomicLoad(&comp[hi])]);
+        p2 = atomicLoad(&comp[lo]);
+    }
+}
+
+@compute @workgroup_size(WG)
+fn wcc_link_edges(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let first = linear_id(wid, lid.x);
+    for (var e = first; e < P.items; e = e + P.stride) {
+        let u = edgeSrc[e];
+        let v = edgeDst[e];
+        if (u == v) { continue; }
+        if (atomicLoad(&comp[u]) == P.giant && atomicLoad(&comp[v]) == P.giant) { continue; }
+        link_pair(u, v);
+    }
+}
+`;

package/src/wgsl/wcc-link-sample.wgsl.ts

@@ -0,0 +1,45 @@
+/**
+ * The `wcc-link-sample` kernel body (spec 8.3): one of Afforest's sampled link rounds -- every vertex links its
+ * r-th neighbour, `colIdx[rowPtr[v] + P.r]`, when it has one. `link_pair` is GAP's `Link` (gapbs/cc.cc lines
+ * 40-150) transcribed for WGSL: all-u32 CAS on `comp`, which is `array<atomic<u32>>` because WGSL forbids mixing
+ * atomic and plain access to one element, with a bounded retry loop (PD-5). The changed flag is the word at
+ * `P.flagIndex` inside the same array (PD-4). The body is normative: a sabotage mutation is a textual edit of it,
+ * so it is not restyled.
+ */
+
+/** Entry point `wcc_link_sample`; standard USE_PERM / HAS_WEIGHTS only (the body reads neither weights nor a permutation beyond the row select). */
+export const wccLinkSampleWgsl = /* wgsl */ `
+fn link_pair(a: u32, b: u32) {
+    var p1 = atomicLoad(&comp[a]);
+    var p2 = atomicLoad(&comp[b]);
+    var steps = 0u;
+    loop {
+        if (p1 == p2) { break; }
+        if (steps >= P.maxSteps) { atomicStore(&comp[P.flagIndex], 1u); break; }
+        steps = steps + 1u;
+        let hi = max(p1, p2);
+        let lo = min(p1, p2);
+        let pHigh = atomicLoad(&comp[hi]);
+        if (pHigh == lo) { break; }
+        if (pHigh == hi) {
+            let swapped = atomicCompareExchangeWeak(&comp[hi], hi, lo);
+            if (swapped.exchanged) { atomicStore(&comp[P.flagIndex], 1u); break; }
+        }
+        p1 = atomicLoad(&comp[atomicLoad(&comp[hi])]);
+        p2 = atomicLoad(&comp[lo]);
+    }
+}
+
+@compute @workgroup_size(WG)
+fn wcc_link_sample(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let first = linear_id(wid, lid.x);
+    for (var row = first; row < P.items; row = row + P.stride) {
+        let v = select(row, perm[row], USE_PERM);
+        let a0 = rowPtr[v];
+        let a1 = rowPtr[v + 1u];
+        if (a0 + P.r < a1) {
+            link_pair(v, colIdx[a0 + P.r]);
+        }
+    }
+}
+`;

package/src/wgsl/wcc-sample.wgsl.ts

@@ -0,0 +1,18 @@
+/**
+ * The `wcc-sample` kernel body (spec 8.3 "a 1,024-entry histogram readback to find the giant component"): writes
+ * the component label of `P.items` pseudo-randomly chosen vertices into `hist`, which the host reads back and takes
+ * the mode of (PD-12: GAP's SampleFrequentElement counts on the host too, and a device histogram over component
+ * ids would return a bucket, not an id). The sampler uses the prelude's `lowbias32` and `%`, never a bitwise
+ * operator on an index.
+ */
+
+/** Entry point `wcc_sample`; no overrides. */
+export const wccSampleWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn wcc_sample(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let i = linear_id(wid, lid.x);
+    if (i >= P.items) { return; }
+    let v = lowbias32(i + P.r) % P.n;
+    hist[i] = atomicLoad(&comp[v]);
+}
+`;