@graphty/webgpu-graph-algorithms 0.6.24 → 0.6.25

package/src/wgsl/bc-backward.wgsl.ts

@@ -4,7 +4,10 @@
  * level's range `S[P.start .. P.start + P.count)`, which the host planned from the `ends` it read back. Each entry
  * walks the out-arcs of `w` -- the rows the forward pass expanded -- and sums `sigma[s][w] / sigma[s][v] * (1 +
  * delta[s][v])` over the successors `v` (`depth[s][v] == depth[s][w] + 1`), whose dependencies the previous (deeper)
- * dispatch wrote, then writes `delta[s][w]` ONCE. No float is ever accumulated through an atomic, so the result is
+ * dispatch wrote, then writes `delta[s][w]` ONCE. The stored counts are scaled per depth (`bc-count`), so the ratio
+ * is taken back to true scale with `ldexp(..., -sigma_shift(levelMax[depth]))`, the step `bc-count` applied between
+ * `w`'s depth and its successors'. Only under `SCALED` (the batch reran with `bc-count`'s f32 counts); otherwise the
+ * counts are exact u32 and the step is 0, which leaves every ratio bit for bit what it was. No float is ever accumulated through an atomic, so the result is
  * bitwise reproducible. The sources (depth 0) are never dispatched: their dependency stays 0, which is what keeps a
  * source's own dependency out of its score. Grid-stride loop (`P.stride`). ponytail: one lane walks one row, so a
  * vertex of degree above 65,535 exceeds llvmpipe's per-invocation loop cap (CLAUDE.md, Verified Platform Facts) and
@@ -12,6 +15,11 @@
  * test/helpers/sabotage.ts are textual edits of it.
  */
 export const bcBackwardWgsl = /* wgsl */ `
+fn sigma_of(word: u32) -> f32 {                                     // a stored count: u32, or f32 bits when SCALED
+    if (SCALED) { return bitcast<f32>(word); }
+    return f32(word);
+}
+
 @compute @workgroup_size(WG)
 fn bc_backward(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
     for (var i = linear_id(wid, lid.x); i < P.count; i = i + P.stride) {
@@ -19,12 +27,13 @@ fn bc_backward(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_
         let w = t % P.n;
         let base = t - w;                                            // s * n
         let succ = depthK[t] + 1u;
-        let sw = f32(sigmaK[t]);
+        let sw = sigma_of(sigmaK[t]);
+        let shift = select(0i, sigma_shift(levelMax[depthK[t]]), SCALED);   // the scale step to the successors' depth
         var acc = 0.0;
         for (var a = rowPtr[w]; a < rowPtr[w + 1u]; a = a + 1u) {
             let v = base + colIdx[a];
             if (depthK[v] == succ) {                                 // v is a successor of w for source s
-                acc = acc + (sw / f32(sigmaK[v])) * (1.0 + deltaK[v]);
+                acc = acc + ldexp(sw / sigma_of(sigmaK[v]), -shift) * (1.0 + deltaK[v]);
             }
         }
         deltaK[t] = acc;                                             // written once per (w, s)

package/src/wgsl/bc-count.wgsl.ts

@@ -0,0 +1,45 @@
+/**
+ * The `bc-count` kernel body (design 8.4, issue #719): the shortest-path counts of the depth a betweenness forward
+ * level has just claimed, PULLED once the claims are complete. It runs only in a batch rerun because its u32 counts
+ * wrapped (the forward bodies then run with `SCALED` and count nothing); `sigmaK` holds f32 bits throughout. One invocation per entry `t = s * n + x` of the range
+ * `S[ends[level + 1] .. stackTop)` (the entries the forward dispatch appended), each summing `sigma[s][v]` over the
+ * in-arcs `(v, x)` with `depth[s][v] == level` in CSR order -- the reverse adjacency, which on an undirected snapshot
+ * is the forward one. No atomic touches a count, so the sums are bitwise reproducible, and both forward bodies leave
+ * the same counts.
+ *
+ * The counts are f32 and rescaled per depth, because a lattice outgrows any fixed width (a 40 x 40 grid has C(78, 39),
+ * about 2.6e22, corner-to-corner paths): each sum is multiplied by `2^-sigma_shift(levelMax[level])`, the power of
+ * two that brings the previous depth's largest count down to 2^BC_SIGMA_EXPONENT_CAP, and the result's bits go into
+ * `levelMax[level + 1]` by `atomicMax` (positive f32 bits order like the values). Every count of one (depth, batch)
+ * shares that scale, and Brandes' backward pass reads only ratios of a count to its successors', so `bc-backward`
+ * undoes the one step between two depths and nothing else. A count that leaves f32's normal range anyway -- zero,
+ * subnormal, infinite -- raises `sigmaOverflow` (counters word 27): the counts at one depth spread wider than f32 can
+ * hold, and the scores are wrong. Grid-stride loop (`P.stride`); the range is read from the device, so the host
+ * dispatches for the largest possible level. Body only; the sabotage rows of test/helpers/sabotage.ts are textual
+ * edits of it.
+ */
+export const bcCountWgsl = /* wgsl */ `
+@compute @workgroup_size(WG)
+fn bc_count(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
+    let level = atomicLoad(&counters[11]);
+    let start = ends[level + 1u];                                    // the boundary closed the claim-from level here
+    let count = atomicLoad(&counters[26]) - start;                   // stackTop: what the forward dispatch appended
+    let shift = sigma_shift(atomicLoad(&levelMax[level]));
+    for (var i = linear_id(wid, lid.x); i < count; i = i + P.stride) {
+        let t = S[start + i];                                        // s * n + x, at depth level + 1
+        let x = t % P.n;
+        let base = t - x;                                            // s * n
+        var acc = 0.0;
+        for (var a = rowPtr[x]; a < rowPtr[x + 1u]; a = a + 1u) {    // the in-arcs (v, x)
+            let v = base + colIdx[a];
+            if (depthK[v] == level) { acc = acc + bitcast<f32>(sigmaK[v]); }   // every predecessor's paths, CSR order
+        }
+        let sigma = ldexp(acc, -shift);
+        let bits = bitcast<u32>(sigma);
+        sigmaK[t] = bits;
+        let exponent = (bits >> 23u) & 0xffu;
+        if (exponent == 0u || exponent == 0xffu) { atomicOr(&counters[27], 1u); }   // out of f32's normal range
+        atomicMax(&levelMax[level + 1u], bits);
+    }
+}
+`;

package/src/wgsl/bc-edge-gather.wgsl.ts

@@ -3,12 +3,18 @@
  * twin of `bc-gather`, run once per batch after the backward sweep. One invocation per ARC (`P.count` arcs,
  * grid-stride): it finds the row `w` that owns the arc by an upper-bound search over `rowPtr`, then adds over the
  * batch's sources in order the term the backward pass summed -- `sigma[s][w] / sigma[s][v] * (1 + delta[s][v])`
- * whenever `w` was reached and `depth[s][v] == depth[s][w] + 1` -- into `arcScores[arc]`. Each arc is written by one
+ * whenever `w` was reached and `depth[s][v] == depth[s][w] + 1`, with `bc-backward`'s depth scale step under `SCALED` -- into
+ * `arcScores[arc]`. Each arc is written by one
  * invocation: no atomic, a fixed order. Arc-parallel rather than row-parallel so a hub row is not one lane's loop
  * (llvmpipe caps a shader loop at 65,535 iterations, and a 1,000-arc hub times 64 sources passed it). Body only;
  * the sabotage rows of test/helpers/sabotage.ts are textual edits of it.
  */
 export const bcEdgeGatherWgsl = /* wgsl */ `
+fn sigma_of(word: u32) -> f32 {                                     // a stored count: u32, or f32 bits when SCALED
+    if (SCALED) { return bitcast<f32>(word); }
+    return f32(word);
+}
+
 @compute @workgroup_size(WG)
 fn bc_edge_gather(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_id) lid: vec3<u32>) {
     for (var a = linear_id(wid, lid.x); a < P.count; a = a + P.stride) {
@@ -26,7 +32,9 @@ fn bc_edge_gather(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocati
             let base = s * P.n;
             let dw = depthK[base + w];
             if (dw != INVALID_INDEX && depthK[base + nbr] == dw + 1u) {   // (w, nbr) is on a shortest path from s
-                acc = acc + (f32(sigmaK[base + w]) / f32(sigmaK[base + nbr])) * (1.0 + deltaK[base + nbr]);
+                let shift = select(0i, sigma_shift(levelMax[dw]), SCALED);
+                let ratio = ldexp(sigma_of(sigmaK[base + w]) / sigma_of(sigmaK[base + nbr]), -shift);
+                acc = acc + ratio * (1.0 + deltaK[base + nbr]);
             }
         }
         arcScores[a] = acc;

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

@@ -5,8 +5,9 @@
  * entries at depth `L` are `S[ends[L] .. ends[L + 1])`. That log is Brandes' stack, so the backward pass walks the
  * same ranges from the deepest level up and nothing is ever copied between levels.
  *
- * Role 1 seeds the batch: the k seed entries the host wrote into `S[0 .. k)` get depth 0 and one shortest path,
- * `ends[0] = 0`, the append cursor `stackTop` (counters word 26) starts at k, the overflow flag (word 27) is cleared,
+ * Role 1 seeds the batch: the k seed entries the host wrote into `S[0 .. k)` get depth 0 and one shortest path (the
+ * u32 1, or under `SCALED` the bits of the f32 1.0), `levelMax[0]` the bits of 1.0 (the largest count at depth 0,
+ * which `bc-count` scales depth 1 from), `ends[0] = 0`, the append cursor `stackTop` (counters word 26) starts at k, the overflow flag (word 27) is cleared,
  * `level` (word 11) is U32_MAX so the first boundary lands on 0, and `done` (word 15) is cleared.
  *
  * Role 0 is the level boundary, recorded before every forward level: it advances `level`, closes the level just
@@ -25,8 +26,9 @@ fn bc_finalize(@builtin(local_invocation_id) lid: vec3<u32>) {
         for (var i = 0u; i < P.k; i = i + 1u) {
             let t = S[i];
             depthK[t] = 0u;                                          // the source is at depth 0
-            sigmaK[t] = 1u;                                          // with one shortest path, itself
+            sigmaK[t] = select(1u, bitcast<u32>(1.0), SCALED);       // with one shortest path, itself (f32 bits when SCALED)
         }
+        levelMax[0] = bitcast<u32>(1.0);                             // the largest count at depth 0
         ends[0] = 0u;
         atomicStore(&counters[26], P.k);                             // stackTop: the seeds are the log's first k entries
         atomicStore(&counters[27], 0u);                              // sigmaOverflow

package/src/wgsl/bc-forward-edge.wgsl.ts

@@ -5,7 +5,7 @@
  * and source `s`, when `depth[s][u]` is the level the edge is relaxed toward `x` with EXACTLY the claim and the count
  * of `bc-forward` (the pre-check, `atomicMin`, the winner appends `s * n + x` to the same claim log, every arc on a
  * shortest path adds `sigma[s][u]`, a u32 wrap raises word 27); `UNDIRECTED` relaxes the other direction too, the
- * edge list holding each undirected edge once. So the two forward bodies are interchangeable level by level and the
+ * edge list holding each undirected edge once. Under `SCALED` the count is skipped, as in `bc-forward`. So the two forward bodies are interchangeable level by level and the
  * backward pass cannot tell which ran. A workgroup does nothing when the level is empty (the done boundary). The
  * winners of a strip are packed into the log with one global `atomicAdd` per strip; every barrier is in uniform
  * control flow (the loop bounds are uniforms and the workgroup id). Body only; the sabotage rows of
@@ -22,7 +22,7 @@ fn claim(x: u32, next: u32) -> bool {
 }
 
 fn count_paths(origin: u32, x: u32, next: u32) {
-    if (atomicLoad(&depthK[x]) == next) {                            // every arc on a shortest path adds
+    if (!SCALED && atomicLoad(&depthK[x]) == next) {                 // every arc on a shortest path adds
         let add = atomicLoad(&sigmaK[origin]);
         let old = atomicAdd(&sigmaK[x], add);
         if (old + add < old) { atomicOr(&counters[27], 1u); }        // the u32 wrap, reported

package/src/wgsl/bc-forward.wgsl.ts

@@ -12,7 +12,9 @@
  * observes INVALID_INDEX the unique winner, which appends `t` to the log; and, as a SEPARATE condition, the COUNT:
  * every arc that reaches `t` at `level + 1` adds `sigma[s][u]` into `sigma[s][x]`, winner or not, which is what makes
  * sigma the number of shortest paths rather than of claims. The add detects a u32 wrap from `atomicAdd`'s return
- * value (`old + add < old`) and raises `sigmaOverflow` (counters word 27); the count is never clamped. The winners of
+ * value (`old + add < old`) and raises `sigmaOverflow` (counters word 27); the count is never clamped. Under
+ * `SCALED` (a batch rerun because the u32 counts wrapped) the count is skipped and `bc-count` pulls rescaled f32
+ * counts after the level instead. The winners of
  * a strip are packed into the log with one workgroup-memory counter and ONE global `atomicAdd` on `stackTop` (word
  * 26) per strip. Uniformity (spec 3.5 rule 1): the range and the aggregate are `workgroupUniformLoad`s and the strip
  * loop steps a uniform `p0`, so every barrier is in uniform control flow. The order of the log inside a level is
@@ -82,7 +84,7 @@ fn bc_forward(@builtin(workgroup_id) wid: vec3<u32>, @builtin(local_invocation_i
                 if (atomicLoad(&depthK[x]) == INVALID_INDEX) {       // the pre-check of design 16.1
                     won = atomicMin(&depthK[x], next) == INVALID_INDEX;   // the claim: the one winner appends
                 }
-                if (atomicLoad(&depthK[x]) == next) {                // the count: EVERY arc on a shortest path adds
+                if (!SCALED && atomicLoad(&depthK[x]) == next) {     // the count: EVERY arc on a shortest path adds
                     let add = atomicLoad(&sigmaK[origin]);
                     let old = atomicAdd(&sigmaK[x], add);
                     if (old + add < old) { atomicOr(&counters[27], 1u); }   // the u32 wrap, reported