@graphty/webgpu-graph-algorithms 0.6.5 → 0.6.7

package/README.md

@@ -143,7 +143,7 @@ names and defaults as the CPU port in `@graphty/layout`) plus the GPU tuning:
 | `nodeSize`                        | `null`           | `E_UNSUPPORTED` when non-null (no overlap prevention)                                                                                                                     |
 | `weight`                          | unset            | `true`: the snapshot's arc weights; an edge column name: that numeric column; unset / `false` / `null`: every edge weighs 1                                               |
 | `dissuadeHubs`                    | `false`          | accepted and ignored                                                                                                                                                      |
-| `settleThreshold`, `settleWindow` | `0.001`, `10`    | settled when the mean displacement stayed below the threshold for `settleWindow` iterations                                                                               |
+| `settleThreshold`, `settleWindow` | `0.001`, `10`    | settled when the mean displacement stayed below `settleThreshold x rmsRadius` AND below an absolute floor (a fraction of the model's length unit: 0.003 `springLength` x (2000 / n)^(1/4) for spring-electrical, 0.002 `k` for Fruchterman-Reingold; ForceAtlas2 has none) for `settleWindow` iterations                                                                               |
 | `iterationsPerStep`               | `1`              | iterations per `step()` (the Node `run()` uses its own `batch`)                                                                                                           |
 | `maxInFlight`                     | `2`              | batches in flight before `step()` coalesces; `1` for the strictest freshness                                                                                              |
 
@@ -692,22 +692,22 @@ are the T-table of plan section 10.4. A missed target is re-fixed by a recorded
 
 Measured on nvidia-lovelace-driver580 (NVIDIA: 580.173.02 580.173.2.0), session 2026-09-20T01:06:48.656Z, medians of 5 runs; Chromium: nvidia / lovelace (nvidia-lovelace-driver0, the description is redacted by Chromium), session 2026-09-16T02:18:11.896Z. The T-5 (100k), T-6 and T-7 rows are from the later session 2026-09-21T06:15:17.027Z (the file's last session, the current baseline, the one the crossover re-check reads; its Chromium session 2026-09-21T05:48:14.190Z), whose other rows are within 1.25x of this table's.
 
-| Id   | What                                                                                                                                                                                                                            | Target                        | Measured                                                                                                                                                                                                                 |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| T-1  | Upload of the 100k / 1M weighted hot prefix (16.4 MB); 1M / 10M (164 MB)                                                                                                                                                        | <= 10 ms; <= 100 ms           | 5.980 ms; 125.738 ms                                                                                                                                                                                                     |
-| T-2  | `degree` + 400 KB readback at 100k (core resident), Node                                                                                                                                                                        | <= 2 ms                       | 0.870 ms                                                                                                                                                                                                                 |
-| T-3  | Empty submit + 4-byte `readU32` round trip, Dawn                                                                                                                                                                                | <= 0.1 ms                     | 0.181 ms                                                                                                                                                                                                                 |
-| T-4  | ForceAtlas2 exact tier, GPU time per iteration (profiler) at 10k; at 16k                                                                                                                                                        | <= 1 ms; <= 2 ms              | 0.586 ms; 1.053 ms                                                                                                                                                                                                       |
-| T-5  | ForceAtlas2 per-frame cost, `step(1)` + the 12n readback at 10k, Chromium (Node in brackets)                                                                                                                                    | <= 6 ms                       | 2.400 ms (0.726 ms)                                                                                                                                                                                                      |
-| T-5  | ForceAtlas2 per-frame cost, `step(1)` + the 12n readback at 100k on the grid tier, Chromium (Node in brackets)                                                                                                                  | <= 12 ms                      | 3.700 ms (2.087 ms)                                                                                                                                                                                                      |
-| T-6  | ForceAtlas2 grid tier, GPU time per iteration (profiler) at 100k 2D; at 1M 2D; at 100k 3D                                                                                                                                       | <= 10 ms; <= 100 ms; <= 20 ms | 0.634 ms; 5.414 ms; 1.306 ms                                                                                                                                                                                             |
-| T-7  | Attraction gather (the `fa2-attraction` pass of the grid tier), GPU time per iteration (profiler) at 1M / 10M                                                                                                                   | <= 15 ms                      | 1.493 ms                                                                                                                                                                                                                 |
-| T-8  | PageRank, 100 iterations, wall end to end including the upload, at 100k / 1M; at 1M / 10M                                                                                                                                       | <= 150 ms; <= 1.5 s           | 17.204 ms; 198.645 ms                                                                                                                                                                                                    |
-| T-9  | Weakly connected components (Afforest), wall end to end including the upload and the label readback, at 1M / 10M (100k / 1M in brackets)                                                                                        | <= 100 ms                     | 145.970 ms (12.613 ms)                                                                                                                                                                                                   |
-| T-14 | Fruchterman-Reingold exact tier, GPU time per iteration (profiler) at 10k; at 100k (`repulsion: "exact"`)                                                                                                                       | recorded                      | 0.617 ms; 16.367 ms                                                                                                                                                                                                      |
-| T-10 | BFS direction-optimizing (`breadthFirstSearch`), wall end to end including the upload, from node 0 of the undirected RMAT at 1M / 10M (577,681 nodes reached, 6 levels; 100k / 1M in brackets; top-down 233.064 ms / 97.259 ms) | <= 100 ms                     | 237.388 ms (101.183 ms) in the baseline session; 156.560 ms (16.731 ms) re-measured 2026-09-25 under load after the direct-dispatch change, top-down 88.606 ms -- see below and G8-F5 / G8-F21 of `docs/decisions/G8.md` |
-| T-10 | BFS on the 1000 x 1000 grid from a corner (1,999 levels; 64 `mapAsync` calls = ceil(levels / 32) + 1), wall including the upload                                                                                                | <= 1.5 s                      | 5680.192 ms in the baseline session; 427.235 ms re-measured 2026-09-25 under load after the direct-dispatch change, MET -- see below and G8-F5 of `docs/decisions/G8.md`                                                 |
-| T-10 | `sssp` (the near-far queue), wall end to end including the upload, random f32 weights in [0.1, 10), at 1M / 10M (100k / 1M in brackets)                                                                                         | recorded                      | 310.351 ms (118.064 ms); 271.040 ms (50.871 ms) re-measured 2026-09-25 under load                                                                                                                                        |
+| Id   | What                                                                                                                                                                                                                            | Target                        | Measured                                                                                                                                                                                                                                                                                                                                                                                         |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| T-1  | Upload of the 100k / 1M weighted hot prefix (16.4 MB); 1M / 10M (164 MB)                                                                                                                                                        | <= 10 ms; <= 100 ms           | 5.980 ms; 125.738 ms                                                                                                                                                                                                                                                                                                                                                                             |
+| T-2  | `degree` + 400 KB readback at 100k (core resident), Node                                                                                                                                                                        | <= 2 ms                       | 0.870 ms                                                                                                                                                                                                                                                                                                                                                                                         |
+| T-3  | Empty submit + 4-byte `readU32` round trip, Dawn                                                                                                                                                                                | <= 0.1 ms                     | 0.181 ms                                                                                                                                                                                                                                                                                                                                                                                         |
+| T-4  | ForceAtlas2 exact tier, GPU time per iteration (profiler) at 10k; at 16k                                                                                                                                                        | <= 1 ms; <= 2 ms              | 0.586 ms; 1.053 ms                                                                                                                                                                                                                                                                                                                                                                               |
+| T-5  | ForceAtlas2 per-frame cost, `step(1)` + the 12n readback at 10k, Chromium (Node in brackets)                                                                                                                                    | <= 6 ms                       | 2.400 ms (0.726 ms)                                                                                                                                                                                                                                                                                                                                                                              |
+| T-5  | ForceAtlas2 per-frame cost, `step(1)` + the 12n readback at 100k on the grid tier, Chromium (Node in brackets)                                                                                                                  | <= 12 ms                      | 3.700 ms (2.087 ms)                                                                                                                                                                                                                                                                                                                                                                              |
+| T-6  | ForceAtlas2 grid tier, GPU time per iteration (profiler) at 100k 2D; at 1M 2D; at 100k 3D                                                                                                                                       | <= 10 ms; <= 100 ms; <= 20 ms | 0.634 ms; 5.414 ms; 1.306 ms                                                                                                                                                                                                                                                                                                                                                                     |
+| T-7  | Attraction gather (the `fa2-attraction` pass of the grid tier), GPU time per iteration (profiler) at 1M / 10M                                                                                                                   | <= 15 ms                      | 1.493 ms                                                                                                                                                                                                                                                                                                                                                                                         |
+| T-8  | PageRank, 100 iterations, wall end to end including the upload, at 100k / 1M; at 1M / 10M                                                                                                                                       | <= 150 ms; <= 1.5 s           | 17.204 ms; 198.645 ms                                                                                                                                                                                                                                                                                                                                                                            |
+| T-9  | Weakly connected components (Afforest), wall end to end including the upload and the label readback, at 1M / 10M (100k / 1M in brackets)                                                                                        | <= 100 ms                     | 145.970 ms (12.613 ms)                                                                                                                                                                                                                                                                                                                                                                           |
+| T-14 | Fruchterman-Reingold exact tier, GPU time per iteration (profiler) at 10k; at 100k (`repulsion: "exact"`)                                                                                                                       | recorded                      | 0.617 ms; 16.367 ms                                                                                                                                                                                                                                                                                                                                                                              |
+| T-10 | BFS direction-optimizing (`breadthFirstSearch`), wall end to end including the upload, from node 0 of the undirected RMAT at 1M / 10M (577,681 nodes reached, 6 levels; 100k / 1M in brackets; top-down 233.064 ms / 97.259 ms) | <= 100 ms                     | 237.388 ms (101.183 ms) in the baseline session; 89.212 ms (14.925 ms) re-measured 2026-09-25 at load average 7.3 after the direct-dispatch change and the m_f fix of issue #391, top-down 95.014 ms (14.744 ms); a sample one minute earlier at load average 10.5 read 134.674 ms (15.183 ms) auto and 99.002 ms (14.630 ms) top-down -- see below and G8-F5 / G8-F21 of `docs/decisions/G8.md` |
+| T-10 | BFS on the 1000 x 1000 grid from a corner (1,999 levels; 64 `mapAsync` calls = ceil(levels / 32) + 1), wall including the upload                                                                                                | <= 1.5 s                      | 5680.192 ms in the baseline session; 427.235 ms re-measured 2026-09-25 under load after the direct-dispatch change, 542.370 ms (536.980 ms one minute earlier) after the m_f fix at load average 7.3-10.5, 382.680 ms at load average 2.5 once `bfs-next-degree` took a capped grid, MET -- see below and G8-F5 of `docs/decisions/G8.md`                                                        |
+| T-10 | `sssp` (the near-far queue), wall end to end including the upload, random f32 weights in [0.1, 10), at 1M / 10M (100k / 1M in brackets)                                                                                         | recorded                      | 310.351 ms (118.064 ms); 271.040 ms (50.871 ms) re-measured 2026-09-25 under load; 275.474 ms (48.326 ms) after the m_f fix at load average 7.3                                                                                                                                                                                                                                                  |
 
 Three rows miss their target in this session: the 1M / 10M upload (125.7 ms against 100 ms, the open owner decision of
 `docs/decisions/G1.md` section 7), the empty-submit round trip (0.181 ms against 0.1 ms: the row is measured after the
@@ -741,6 +741,27 @@ to the baseline): a 34-node BFS 7.2 ms (from 89.3 with the core resident), the g
 auto row 156.6 ms and the top-down row 88.6 ms. The auto row now misses only because the direction-optimizing
 choice itself is slower than top-down on that graph, which the validation cost had hidden (G8-F21).
 
+That miss was not the direction choice either (G8-F21, closed by issue #391). The 156.6 against 88.6 ms gap was the
+card clocking down to P5 and then ramping back up: the benchmark runs the auto row first, so whichever row runs
+first carries the ramp, and alternating the two directions end to end reads the same 75 ms from the third iteration
+on. The upload cannot explain it, being paid by both rows alike. The real defect the issue uncovered was Beamer's m_f
+measured one level stale -- `frontierDegreeSum` is the degree of the frontier the PREVIOUS level expanded, which is
+0 after a bottom-up level -- so the switch into bottom-up was missed at the level holding 13.6M of the 21M arcs. The
+`bfs-next-degree` kernel now sums the out-degree of the frontier about to be expanded (counters word 25) and the
+boundary compares that. With the core resident on the card the 1M / 10M auto traversal went from 37.8 to 31.4 ms
+and 100k / 1M from 10.3 to 8.8 ms; the three bottom-up levels of the 1M / 10M run read 649,743 arcs in total. At
+100k / 1M the direction-optimizing traversal still loses to plain top-down on this card, 9.55 against 9.34 ms
+resident, which is a smaller loss than the 10.87 against 9.91 ms it read before the fix, and still a loss. The
+new kernel is dispatched on every level, so a high-diameter traversal pays its fixed cost per level: the grid
+traversal resident on the card went 339 -> 421 ms with the full-width grid `planGridStride(n, wg)` gives it and
+back to 356 ms with the grid capped at 128 workgroups (`NEXT_DEGREE_MAX_GROUPS`), which is still enough to sum n
+out-degrees by grid stride; neither R-MAT row moved. The
+rows in the table (`--no-save --runs 3`, not appended to the baseline; both samples on 2026-09-25, one minute
+apart): at load average 7.3 the 1M / 10M auto row is 89.2 ms against 95.0 ms top-down, the 100k / 1M row 14.9
+against 14.7 ms, the grid row 542 ms and `sssp` 275.5 ms (48.3 ms); at load average 10.5 the same auto row read
+134.7 ms and top-down 99.0 ms. The two samples ran the same code on the same card, so the 100 ms target is met or
+missed by the upload and the clock state the row starts in, not by the traversal.
+
 The exact curve (the `layout-exact` group: 2D, E = 10n, seeded G(n, m), one simulation per rung; ms / iteration from the profiler):
 
 | n     | ms / iteration | step(1) wall (ms) | pairs / s |

package/dist/browser.js

@@ -1,4 +1,4 @@
-import { G as GpuContext, W as WebGpuGraphError } from "./chunks/context-hzGggHeM.js";
+import { G as GpuContext, W as WebGpuGraphError } from "./chunks/context-Cezi7qpi.js";
 function navigatorGpu() {
   if (typeof navigator === "undefined") {
     return void 0;

package/dist/chunks/{context-hzGggHeM.js → context-Cezi7qpi.js}

@@ -49,6 +49,7 @@ const LAYOUT_TUNING_DEFAULTS = Object.freeze({
 const FA2_DISTANCE_FLOOR = 0.01;
 const FA2_DISTANCE_FLOOR_SQ = 1e-4;
 const FA2_COINCIDENT_SQ = 1e-8;
+const EXACT_TILES_PER_PASS = 128;
 const FA2_FLAG_FIRST = 1;
 const FA2_FLAG_ADAPTIVE = 2;
 const FR_START_TEMPERATURE = 0.1;
@@ -82,6 +83,14 @@ const SE_DEFAULTS = Object.freeze({
   iterationsPerStep: 1,
   maxInFlight: 2
 });
+const SETTLE_FLOOR_FRACTION = Object.freeze(
+  {
+    springElectrical: 3e-3,
+    fruchtermanReingold: 2e-3
+  }
+);
+const SETTLE_FLOOR_REFERENCE_NODES = 2e3;
+const SETTLE_FLOOR_UNBOUNDED = 2 ** 128 - 2 ** 104;
 const GRID_MIN_SIDE = 8;
 const GRID_COARSEST_SIDE = 4;
 const GRID_HUB_CELL = 1024;
@@ -733,7 +742,7 @@ class Kernel {
     return bound;
   }
   /**
-   * setPipeline + setBindGroup for every group (dynamic offsets in dynamicGroups order) + dispatchWorkgroups(plan.x, plan.y, 1); a plan with x === 0 records nothing (spec 5.6).
+   * setPipeline + setBindGroup for every group (dynamic offsets in dynamicGroups order) + dispatchWorkgroups(plan.x, plan.y, plan.z); a plan with x === 0 records nothing (spec 5.6).
    * PLAN DECISION: one dynamic offset per dynamic GROUP, replicated over every uniform binding of that group (every
    * P1-P3 kernel has exactly one params uniform per group); absent offsets mean 0; a BoundKernel of another kernel
    * or an offset list of the wrong length is E_INVALID_ARGUMENT.
@@ -751,7 +760,7 @@ class Kernel {
       return;
     }
     this.setUp(pass, bound, dynamicOffsets);
-    pass.dispatchWorkgroups(plan.x, plan.y, 1);
+    pass.dispatchWorkgroups(plan.x, plan.y, plan.z);
   }
   /**
    * setPipeline + the bind groups exactly as dispatch(), then dispatchWorkgroupsIndirect(args.buffer, args.offset +
@@ -890,6 +899,7 @@ 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 EXACT_TILES_PER_PASS: u32 = ${EXACT_TILES_PER_PASS}u;
 const FA2_DIST_FLOOR: f32 = ${wgslF32Literal(FA2_DISTANCE_FLOOR)};
 const FA2_DIST_FLOOR_SQ: f32 = ${wgslF32Literal(FA2_DISTANCE_FLOOR_SQ)};
 const FA2_COINCIDENT_SQ: f32 = ${wgslF32Literal(FA2_COINCIDENT_SQ)};
@@ -2786,7 +2796,9 @@ class GraphResidency {
     });
   }
   /**
-   * One resident per array (spec 4.3: views upload in perArray mode, never into the arena).
+   * One resident per array (spec 4.3: views upload in perArray mode, never into the arena). An empty array (the
+   * colIdx of an edgeless directed reverse view, the src / dst of an edgeless edgeList) is skipped: spec 5.6 never
+   * uploads a zero-length array, and Kernel.bind rejects a zero-size binding, so it is absent as in core().
    * @param record - the owning record
    * @param arrays - the named arrays
    * @param label - the buffer label prefix
@@ -2795,6 +2807,9 @@ class GraphResidency {
   separateArrays(record, arrays, label) {
     const bindings = {};
     for (const [name, array] of arrays) {
+      if (array.byteLength === 0) {
+        continue;
+      }
       const resident = this.upload(record, array, array, `${label}:${name}`);
       bindings[name] = { buffer: resident.buffer, offset: 0, size: resident.byteLength, window: null };
     }
@@ -2808,14 +2823,19 @@ class GraphResidency {
    * lengths, so keying the packed buffer on `rev.rowPtr` would make the packed and the unpacked view of one
    * snapshot collide -- whichever was built second would get the other's buffer. The record still owns the
    * resident, so release(s) destroys it with the rest. Offsets are STORAGE_ALIGN-aligned because Kernel.bind
-   * rejects any other offset synchronously (E_INVALID_ARGUMENT { argument: "offset" }).
+   * rejects any other offset synchronously (E_INVALID_ARGUMENT { argument: "offset" }). Empty arrays are left
+   * out as in separateArrays; when nothing is left, nothing is uploaded.
    * @param record - the owning record
-   * @param arrays - the named arrays, in buffer order
+   * @param all - the named arrays, in buffer order
    * @param key - the marker object the resident is keyed on
    * @param label - the buffer label
    * @returns the bindings by name, all into the one buffer
    */
-  packArrays(record, arrays, key, label) {
+  packArrays(record, all, key, label) {
+    const arrays = all.filter(([, array]) => array.byteLength > 0);
+    if (arrays.length === 0) {
+      return Object.freeze({});
+    }
     const offsets = [];
     let total = 0;
     for (const [, array] of arrays) {
@@ -3483,19 +3503,23 @@ class GpuContext {
   }
 }
 export {
-  ARC_WINDOW_ALIGN as A,
+  FR_DEFAULTS as A,
   BufferUsage as B,
-  PASSTHROUGH_FORMAT_CODES as C,
-  STORAGE_ALIGN as D,
-  EXACT_MAX_NODES as E,
+  SE_DEFAULTS as C,
+  SETTLE_FLOOR_REFERENCE_NODES as D,
+  EXACT_TILES_PER_PASS as E,
   FUSED_FRONTIER_MAX as F,
   GpuContext as G,
-  WORKGROUP_SIZE as H,
+  SE_SCALE_REFERENCE_NODES as H,
   INDIRECT_ARGS_STRIDE as I,
-  isSoftwareAdapter as J,
+  ARC_WINDOW_ALIGN as J,
+  PASSTHROUGH_FORMAT_CODES as K,
   LAYOUT_TUNING_DEFAULTS as L,
   MAX_WORKGROUPS_PER_DIM as M,
+  STORAGE_ALIGN as N,
+  WORKGROUP_SIZE as O,
   PARTIAL_BYTES as P,
+  isSoftwareAdapter as Q,
   RADIX_BINS as R,
   STATE_HEADER_BYTES as S,
   TRACE_RECORD_BYTES as T,
@@ -3518,14 +3542,14 @@ export {
   hasErrorCode as o,
   FA2_FLAG_FIRST as p,
   GRID_HUB_CELL as q,
-  GRID_BBOX_MARGIN as r,
-  GRID_EXTENT_FLOOR as s,
-  FR_ADAPTIVE_MAX_ITERATIONS as t,
-  FR_START_TEMPERATURE as u,
-  FA2_FLAG_ADAPTIVE as v,
-  FR_REHEAT_FRACTION as w,
-  FR_DEFAULTS as x,
-  SE_DEFAULTS as y,
-  SE_SCALE_REFERENCE_NODES as z
+  EXACT_MAX_NODES as r,
+  SETTLE_FLOOR_UNBOUNDED as s,
+  GRID_BBOX_MARGIN as t,
+  GRID_EXTENT_FLOOR as u,
+  FR_ADAPTIVE_MAX_ITERATIONS as v,
+  FR_START_TEMPERATURE as w,
+  FA2_FLAG_ADAPTIVE as x,
+  SETTLE_FLOOR_FRACTION as y,
+  FR_REHEAT_FRACTION as z
 };
-//# sourceMappingURL=context-hzGggHeM.js.map
+//# sourceMappingURL=context-Cezi7qpi.js.map