@graphty/webgpu-graph-algorithms 0.5.1 → 0.6.0

package/dist/src/layouts/forceatlas2.js

@@ -4,27 +4,40 @@
  * record (spec 7.2 with the 4.6 NetworkX corrections), the per-iteration Fa2Params values, the controller resets of
  * spec 7.17 and the stats decoder -- plus the two option resolvers and `createForceAtlas2`. Positions are vec4f
  * (xyz + mass) in layout units on the device (D23, 7.18); the speed controller runs on the device (D15); no
- * displacement clamp (D25); K2 runs the thread-per-row tier over [0, n) with USE_PERM false (P3, spec 7.5).
+ * displacement clamp (D25); K2 runs the degree tiers over `degreeOrder()` (P4 PD-7).
  *
  * Model decisions this file fixes (the plan of P3-T2 lists the reasons): recordIteration with no `upTo` records every
- * stage including toScene; the K1-K5 dispatches of every iteration of one batch share ONE compute pass (opened by the
- * batch's first recordIteration and remembered by batch id) and toScene runs in a second pass that ends it (contract
- * 4.4); the fill kernel takes its FillParams from a model-owned 256-byte uniform buffer ("fillParams"); the first
- * iteration after every load() zeroes oldForce with a fill (paper mode); `repulsion: "grid"` is E_UNSUPPORTED at
- * load() for any n and `"auto"` above exactMaxNodes.
+ * stage including toScene; on the exact tier the K1-K5 dispatches of every iteration of one batch share ONE compute
+ * pass (opened by the batch's first recordIteration and remembered by batch id) and toScene runs in a second pass
+ * that ends it (contract 4.4); the fill kernel takes its FillParams from a model-owned 256-byte uniform buffer
+ * ("fillParams"); the first iteration after every load() zeroes oldForce with a fill (paper mode). The grid tier
+ * (P4-T10) is reached through `RepulsionGrid` when `tierFor(tuning, n)` says so (PD-18): `buffers()` adds the grid
+ * buffers, K1 derives the frame under `gridMax > 0` (PD-14), the iteration is recorded as the three passes `fa2-k1`
+ * / `fa2-attraction` / `fa2-grid` before `fa2-to-scene` (PD-16), and `stages` is the union list of both tiers
+ * (PD-17: `upTo` stops after the last stage recorded at or before its position).
  */
-import { FA2_DEFAULTS, LAYOUT_TUNING_DEFAULTS, MAX_ITERATIONS_PER_STEP, TRACE_RECORD_BYTES, UNIFORM_SLOT_BYTES, } from "../constants.js";
+import { EXACT_MAX_NODES, FA2_DEFAULTS, GRID_BBOX_MARGIN, GRID_EXTENT_FLOOR, LAYOUT_TUNING_DEFAULTS, MAX_ITERATIONS_PER_STEP, TRACE_RECORD_BYTES, UNIFORM_SLOT_BYTES, } from "../constants.js";
 import { BufferUsage } from "../device/webgpu-constants.js";
 import { WebGpuGraphError } from "../errors.js";
 import { plan1d } from "../kernel/dispatch.js";
-import { FA2_PARAMS, FA2_STATE, FA2_TRACE, FILL_PARAMS, graphBindings, kernelSpec } from "../kernels.js";
-import { ForceSimulation, } from "./force-simulation.js";
+import { FA2_PARAMS, FA2_STATE, FA2_TRACE, FILL_PARAMS, kernelSpec } from "../kernels.js";
+import { arcCountOf } from "../primitives/core-shape.js";
+import { gridSpecFor } from "../primitives/grid.js";
+import { ForceSimulation, tierFor, } from "./force-simulation.js";
 import { resolveNodeMass, resolveWeights } from "./inputs.js";
-import { describeValue, FILL_PARAMS_BUFFER, FORCE_BYTES_PER_NODE, invalid, isPositiveInteger, pickBoolean, pickCenter, pickDim, pickNumber, pickSeed, scalar, seedWord, subset, vector, } from "./model-common.js";
+import { bindAttraction, describeValue, FILL_PARAMS_BUFFER, FORCE_BYTES_PER_NODE, invalid, isPositiveInteger, pickBoolean, pickCenter, pickDim, pickNumber, pickSeed, recordAttraction, scalar, seedWord, subset, vector, } from "./model-common.js";
 import { RepulsionExact } from "./repulsion-exact.js";
+import { RepulsionGrid } from "./repulsion-grid.js";
 // ============================================================ constants and small helpers
-/** The stage names of one iteration in dispatch order plus the per-batch toScene (spec 7.4; contract 3.13). */
-const FA2_STAGES = ["K1", "K2", "K3", "K4", "K5", "toScene"];
+/** The stage names of both tiers in dispatch order plus the per-batch toScene (spec 7.4; contract 3.13; P4 PD-17): the exact tier records K1 K2 K3 K4 K5, the grid tier K1 K2 G1..G7 K4 K5. */
+const FA2_STAGES = ["K1", "K2", "K3", "G1", "G2", "G3", "G4", "G5", "G6", "G7", "K4", "K5", "toScene"];
+/** The FA2_STAGES index of the first grid stage, of K4, of K5 and of toScene. */
+const STAGE_G1 = 3;
+const STAGE_K4 = 10;
+const STAGE_K5 = 11;
+const STAGE_TO_SCENE = 12;
+/** The name of the model-owned hub-counter buffer K1 binds on every tier (P4 PD-14). */
+const HUB_COUNTERS_BUFFER = "hubCounters";
 /** The one-workgroup dispatch of K1 (spec 7.4). */
 const ONE_WORKGROUP = { x: 1, y: 1, z: 1, items: 1, stride: null };
 /** Every override K2 accepts, with its default (contract 3.10.1 plus the two standard graph overrides). */
@@ -52,6 +65,14 @@ function repulsionOverrides(merged) {
         GRAVITY_CENTER: merged.GRAVITY_CENTER === 1 ? 1 : 0,
     };
 }
+/**
+ * The G6 / G7 / K4 override values of a merged set (typed for RepulsionGrid): K3's three and the FA2 law (P4-T13).
+ * @param merged - the merged override set
+ * @returns the grid stage's overrides
+ */
+function gridOverrides(merged) {
+    return { ...repulsionOverrides(merged), LAW: 0 };
+}
 // ============================================================ the resolvers
 /**
  * Applies FA2_DEFAULTS to the option record; validates ranges (spec 7.14; contract 3.13). With `previous` the record
@@ -96,8 +117,8 @@ export function resolveForceAtlas2Options(options, previous) {
     return Object.freeze(resolved);
 }
 /**
- * Applies LAYOUT_TUNING_DEFAULTS (spec 7.14); the grid knobs are validated and stored but only `repulsion`,
- * `exactMaxNodes`, `deterministic` and `compat` have an effect in P3 (contract 3.3).
+ * Applies LAYOUT_TUNING_DEFAULTS (spec 7.14; contract 3.3). `nearMax` is an integer >= 2 (P4 DEP-P4-M: the
+ * near-field estimator needs at least one sampled entry besides the node itself).
  * @param tuning - the GPU-only knobs given (any object carrying them, e.g. the createForceAtlas2 options)
  * @returns the frozen resolved tuning
  */
@@ -114,7 +135,7 @@ export function resolveLayoutTuning(tuning) {
     const resolved = {
         repulsion,
         exactMaxNodes: pickNumber("exactMaxNodes", t.exactMaxNodes, LAYOUT_TUNING_DEFAULTS.exactMaxNodes, isPositiveInteger, "an integer >= 1"),
-        nearMax: pickNumber("nearMax", t.nearMax, LAYOUT_TUNING_DEFAULTS.nearMax, isPositiveInteger, "an integer >= 1"),
+        nearMax: pickNumber("nearMax", t.nearMax, LAYOUT_TUNING_DEFAULTS.nearMax, (v) => isPositiveInteger(v) && v >= 2, "an integer >= 2"),
         deterministic: pickBoolean("deterministic", t.deterministic, LAYOUT_TUNING_DEFAULTS.deterministic),
         gridMax2D: pickNumber("gridMax2D", t.gridMax2D, LAYOUT_TUNING_DEFAULTS.gridMax2D, isPositiveInteger, "an integer >= 1"),
         gridMax3D: pickNumber("gridMax3D", t.gridMax3D, LAYOUT_TUNING_DEFAULTS.gridMax3D, isPositiveInteger, "an integer >= 1"),
@@ -123,7 +144,7 @@ export function resolveLayoutTuning(tuning) {
     };
     return Object.freeze(resolved);
 }
-/** The ForceAtlas2 model (spec 7.4: K1 K2 K3 K4 K5 per iteration; toScene once per batch). Stages: ["K1", "K2", "K3", "K4", "K5", "toScene"]. */
+/** The ForceAtlas2 model (spec 7.4: K1 K2 K3 K4 K5 per iteration on the exact tier, K1 K2 G1..G7 K4 K5 on the grid tier; toScene once per batch). Stages: the union list of PD-17. */
 export class ForceAtlas2Model {
     /**
      * Creates the model for one simulation.
@@ -148,6 +169,8 @@ export class ForceAtlas2Model {
         this.bound = null;
         /** Armed by onLoad(): the next recordIteration zeroes oldForce first (paper mode). */
         this.resetOldForce = false;
+        /** The grid of the load inputs() last resolved (null on the exact tier): onLoad() writes its frame, specs() lists its kernels. */
+        this.nextGrid = null;
         /**
          * The K1-K5 compute pass of the batch being recorded, keyed by CommandBatch.id (unique per batch): every
          * recordIteration of one batch dispatches into it (ONE pass per batch, contract 4.4); null between batches and
@@ -166,15 +189,18 @@ export class ForceAtlas2Model {
     }
     /**
      * force 12n and oldForce 12n (zeroed) in BOTH swing modes (3.10.1: a writable slot is never aliased; mode 1 leaves
-     * oldForce unread and unwritten), plus the 256-byte FillParams uniform buffer the fill dispatches read. n = 0
-     * reports one node's worth of bytes so no zero-length buffer is ever created (spec 3.6).
+     * oldForce unread and unwritten), the 256-byte FillParams uniform buffer the fill dispatches read, the 16-byte
+     * `hubCounters` K1 binds on every tier (P4 PD-14), and the grid buffers of `RepulsionGrid.buffers` exactly when
+     * `tierFor(tuning, n)` is the grid tier (PD-18). n = 0 reports one node's worth of bytes so no zero-length buffer
+     * is ever created (spec 3.6).
      * @param n - the node count
-     * @param _dim - the layout dimension (the force arrays are stride 3 in both)
-     * @returns the three model-owned buffer specs
+     * @param dim - the layout dimension (the force arrays are stride 3 in both; the grid's geometry differs)
+     * @returns the model-owned buffer specs
      */
-    buffers(n, _dim) {
+    buffers(n, dim) {
         const bytes = Math.max(1, n) * FORCE_BYTES_PER_NODE;
         const usage = BufferUsage.STORAGE | BufferUsage.COPY_SRC | BufferUsage.COPY_DST;
+        const grid = tierFor(this.tuning, n) === "grid" ? RepulsionGrid.buffers(n, gridSpecFor(n, dim, this.tuning)) : [];
         return [
             { name: "force", byteLength: bytes, usage, zero: true },
             { name: "oldForce", byteLength: bytes, usage, zero: true },
@@ -184,29 +210,25 @@ export class ForceAtlas2Model {
                 usage: BufferUsage.UNIFORM | BufferUsage.COPY_DST,
                 zero: false,
             },
+            { name: HUB_COUNTERS_BUFFER, byteLength: 16, usage, zero: true },
+            ...grid,
         ];
     }
     /**
-     * { mass: resolveNodeMass(s, resolved.nodeMass), weights: resolveWeights(s, resolved.weight) } (3.13 inputs.ts),
-     * after the tier rule of spec 7.8 / lead f: `repulsion: "grid"` is E_UNSUPPORTED { feature: "repulsion.grid" }
-     * for any n and `"auto"` when n > exactMaxNodes (the grid tier lands in P4); `"exact"` always runs.
+     * { mass: resolveNodeMass(s, resolved.nodeMass), weights: resolveWeights(s, resolved.weight) } (3.13 inputs.ts).
+     * Also remembers the grid of this load (`tierFor(tuning, n)`, spec 7.8) for onLoad() and specs(): the simulation
+     * calls inputs() first, then onLoad() before bind().
      * @param s - the snapshot being loaded
      * @param options - the simulation's current option record
      * @returns the per-load inputs
      */
     inputs(s, options) {
         const resolved = resolveForceAtlas2Options(options, this.current);
-        const { repulsion, exactMaxNodes } = this.tuning;
         const n = s.nodeCount;
-        if (repulsion === "grid" || (repulsion === "auto" && n > exactMaxNodes)) {
-            throw new WebGpuGraphError("E_UNSUPPORTED", repulsion === "grid"
-                ? 'repulsion: "grid" is not available yet (the grid tier lands in P4)'
-                : `the graph has ${n} nodes, above exactMaxNodes ${exactMaxNodes}, and the grid tier lands in P4`, {
-                feature: "repulsion.grid",
-                hint: 'pass repulsion: "exact" (or raise exactMaxNodes) to run the exact tier at this size',
-            });
-        }
-        return { mass: resolveNodeMass(s, resolved.nodeMass), weights: resolveWeights(s, resolved.weight) };
+        // resolve first: a throwing mass / weight resolution leaves the remembered grid of the previous load intact
+        const inputs = { mass: resolveNodeMass(s, resolved.nodeMass), weights: resolveWeights(s, resolved.weight) };
+        this.nextGrid = tierFor(this.tuning, n) === "grid" ? gridSpecFor(n, resolved.dim, this.tuning) : null;
+        return inputs;
     }
     /**
      * { LINLOG, DISTRIBUTED, TIER: 0, SWING_MODE: compat === "networkx" ? 1 : 0, STRONG_GRAVITY, GRAVITY_CENTER:
@@ -230,7 +252,9 @@ export class ForceAtlas2Model {
     }
     /**
      * The seven module specs of an override set in dispatch order -- K1, K2, K3, K4, K5, toScene, fill -- each with
-     * only the override names its entry declares (K2 also USE_PERM / HAS_WEIGHTS), for warm() and the compile matrix.
+     * only the override names its entry declares (K2 also USE_PERM / HAS_WEIGHTS), for warm() and the compile matrix,
+     * followed by the grid tier's specs (`RepulsionGrid.specs`) when the load inputs() last resolved is a grid load
+     * (the pipeline key carries no geometry, so the spec's size is immaterial).
      * @param overrides - the merged override set (the model's plus USE_PERM / HAS_WEIGHTS)
      * @param _subgroups - accepted for the ForceModel interface and unused: every reducing FA2 body carries
      *   needs: ["subgroups"] in its registry entry and the composer picks the twin from caps.features (contract 4.3)
@@ -238,6 +262,9 @@ export class ForceAtlas2Model {
      */
     specs(overrides, _subgroups) {
         const [repulsionSpec, speedSpec] = RepulsionExact.specs(repulsionOverrides(overrides));
+        const grid = this.nextGrid === null
+            ? []
+            : RepulsionGrid.specs(gridOverrides(overrides), gridSpecFor(EXACT_MAX_NODES + 1, 2, this.tuning));
         return [
             kernelSpec("fa2-stats-finalize"),
             kernelSpec("fa2-attraction", subset(overrides, K2_DEFAULTS)),
@@ -246,44 +273,56 @@ export class ForceAtlas2Model {
             kernelSpec("fa2-integrate", subset(overrides, K5_DEFAULTS)),
             kernelSpec("fa2-to-scene"),
             kernelSpec("fill"),
+            ...grid,
         ];
     }
     /**
-     * Compiles (through the cache) and binds every kernel against the buffers of this load(): K1, K2 (or the fill of
-     * force when arcCount === 0), K3 + K4 through RepulsionExact, K5, toScene, and the fill of oldForce; writes the
-     * FillParams { count: 3n, value: 0, mode: 0 } into the model's uniform buffer. With n === 0 nothing is bound.
+     * Compiles (through the cache) and binds every kernel against the buffers of this load(): K1, K2 over the degree
+     * tiers through bindAttraction (or the fill of force when arcCount === 0), K3 + K4 through RepulsionExact, K5,
+     * toScene, and the fill of oldForce; writes the FillParams { count: 3n, value: 0, mode: 0 } into the model's
+     * uniform buffer. With n === 0 nothing is bound. The K2 TIER 1 / 2 pipelines compile on the first load whose
+     * degrees need them (P4 PD-7), a one-time cost at that load.
      * @param resources - the graph, the shared and model buffers, the ring and the cache
      * @param overrides - the merged override set
      */
     async bind(resources, overrides) {
         this.dropBound();
         this.resources = resources;
-        const { n, pipelines, caps, core, perm, ring, device } = resources;
+        const { n, pipelines, caps, core, ring, device } = resources;
         if (n === 0) {
             return;
         }
-        const [k1, k2, k5, toScene, fill] = await Promise.all([
+        const pos = resources.buffer("positions");
+        const force = resources.buffer("force");
+        const params = ring.binding(FA2_PARAMS);
+        const hasArcs = core.colIdx !== null;
+        const [k1, k5, toScene, fill] = await Promise.all([
             pipelines.kernel(kernelSpec("fa2-stats-finalize")),
-            pipelines.kernel(kernelSpec("fa2-attraction", subset(overrides, K2_DEFAULTS))),
             pipelines.kernel(kernelSpec("fa2-integrate", subset(overrides, K5_DEFAULTS))),
             pipelines.kernel(kernelSpec("fa2-to-scene")),
             pipelines.kernel(kernelSpec("fill")),
         ]);
-        const repulsion = await RepulsionExact.create(pipelines, caps, repulsionOverrides(overrides));
+        const repulsion = resources.tier === "grid"
+            ? null
+            : await RepulsionExact.create(pipelines, caps, repulsionOverrides(overrides));
+        const attraction = hasArcs
+            ? await bindAttraction(resources, subset(overrides, K2_DEFAULTS), { pos, force, params })
+            : null;
+        const grid = resources.tier === "grid"
+            ? await RepulsionGrid.create(resources, k1.workgroupSize, gridOverrides(overrides), gridSpecFor(n, resources.dim, this.tuning))
+            : null;
         if (this.resources !== resources) {
             // a newer bind() superseded this one while the pipelines compiled; its own bind groups stand
+            grid?.dispose();
             return;
         }
-        const pos = resources.buffer("positions");
         const scene = resources.buffer("scenePositions");
         const fixed = resources.buffer("fixed");
         const partials = resources.buffer("partials");
         const state = resources.buffer("state");
         const trace = resources.buffer("trace");
-        const force = resources.buffer("force");
         const oldForce = resources.buffer("oldForce");
         const fillParamsBuffer = resources.buffer(FILL_PARAMS_BUFFER);
-        const params = ring.binding(FA2_PARAMS);
         const fillParams = {
             buffer: fillParamsBuffer.buffer,
             offset: fillParamsBuffer.offset,
@@ -293,20 +332,41 @@ export class ForceAtlas2Model {
         const fillBytes = new ArrayBuffer(FILL_PARAMS.byteLength);
         FILL_PARAMS.write(new DataView(fillBytes), { count: 3 * n, value: 0, mode: 0 });
         device.queue.writeBuffer(fillParamsBuffer.buffer, fillParamsBuffer.offset, fillBytes);
-        const hasArcs = core.colIdx !== null;
-        repulsion.bind({ pos, state, trace, force, oldForce, fixedMask: fixed, partials, params });
+        const hubCounters = resources.buffer(HUB_COUNTERS_BUFFER);
+        const exact = { pos, state, trace, force, oldForce, fixedMask: fixed, partials, params };
+        repulsion?.bind(exact);
+        grid?.bind({
+            ...exact,
+            cellKey: resources.buffer("cellKey"),
+            cellVal: resources.buffer("cellVal"),
+            sortedKey: resources.buffer("sortedKey"),
+            sortedIdx: resources.buffer("sortedIdx"),
+            cellHist: resources.buffer("cellHist"),
+            cellStart: resources.buffer("cellStart"),
+            hubList: resources.buffer("hubList"),
+            hubCounters,
+            hubArgs: resources.buffer("hubArgs"),
+            pyramid: resources.buffer("pyramid"),
+        });
         const wg = k1.workgroupSize;
         this.bound = {
             n,
             plan: plan1d(n, wg, caps),
             fillPlan: plan1d(3 * n, wg, caps),
             k1,
-            k1Bound: k1.bind({ partials, S: state, T: trace, P: params }),
-            k2,
-            k2Bound: hasArcs
-                ? k2.bind({ ...graphBindings(core, perm, resources.weights), pos, force, P: params })
-                : null,
+            // PD-14: on the exact tier K1's grid slots take dummies (cellHist := partials, both read-only; hubCounters
+            // is the model's 16-byte buffer on every tier) and the block is dead under gridMax 0
+            k1Bound: k1.bind({
+                partials,
+                S: state,
+                T: trace,
+                cellHist: grid === null ? partials : resources.buffer("cellHist"),
+                hubCounters,
+                P: params,
+            }),
+            attraction,
             repulsion,
+            grid,
             k5,
             k5Bound: k5.bind({ force, oldForce, fixedMask: fixed, S: state, pos, partials, P: params }),
             toScene,
@@ -324,14 +384,19 @@ export class ForceAtlas2Model {
      * @returns the uniform values
      */
     paramsFor(iteration, options) {
-        const { n } = this.requireResources();
+        const { n, core, tiers, tier, dim } = this.requireResources();
         const resolved = resolveForceAtlas2Options(options, this.current);
         const { nearMax, extentFactor } = this.tuning;
+        const grid = tier === "grid" ? gridSpecFor(n, dim, this.tuning) : null;
+        // P4 PD-7: TIER 2 reads [0, hiEnd), TIER 1 [hiEnd, midEnd), TIER 0 [tierStart, tierEnd) = [midEnd, n)
+        const so = tiers?.segmentOffsets;
+        const hiEnd = so?.[1] ?? 0;
+        const midEnd = so?.[2] ?? 0;
         return {
             n,
             dim: resolved.dim,
             flags: 0,
-            tierStart: 0,
+            tierStart: midEnd,
             tierEnd: n,
             iterationIndex: iteration,
             seed: seedWord(resolved.seed),
@@ -343,33 +408,37 @@ export class ForceAtlas2Model {
             center: [resolved.center[0], resolved.center[1], resolved.center[2], 0],
             settleThreshold: resolved.settleThreshold,
             extentFactor,
-            gridMax: 0,
-            levels: 0,
-            pad: [0, 0, 0, 0],
+            gridMax: grid?.g ?? 0,
+            levels: grid?.levels ?? 0,
+            arcBase: 0,
+            arcEnd: arcCountOf(core),
+            accumulate: 0,
+            hiEnd,
+            midEnd,
         };
     }
     /**
-     * Records one iteration into the batch: K1, K2 (or the fill of force when arcCount === 0), K3, K4, K5 in the
-     * batch's ONE K1-K5 compute pass (opened by the first call of a batch and reused by every later call with the
-     * same batch.id, PLAN DECISION 2), then toScene in a second pass that ends it, stopping after stage `upTo` when
-     * given (spec 7.4; debugRunStages / inspect, spec 11.9 item 2). The simulation passes "K5" for iterations
-     * 0..k-2 and undefined for the last, so toScene runs once per batch. The first call after load() zeroes
-     * oldForce before K1 (paper mode). With n === 0 nothing is recorded (PLAN DECISION 9); a call before bind()
-     * completed is E_NOT_LOADED (never a silent no-op).
+     * Records one iteration into the batch, stopping after stage `upTo` when given (spec 7.4; debugRunStages /
+     * inspect, spec 11.9 item 2; PD-17: `upTo` names a position in the union list and the recording stops after the
+     * last stage recorded at or before it, so "K3" on the grid tier stops after K2 and "G5" on the exact tier after
+     * K3). The exact tier: K1, K2 (or the fill of force when arcCount === 0), K3, K4, K5 in the batch's ONE compute
+     * pass (opened by the first call of a batch and reused by every later call with the same batch.id, PLAN
+     * DECISION 2), then toScene in a second pass that ends it. The grid tier (PD-16): the passes `fa2-k1` (K1),
+     * `fa2-attraction` (K2's tiers) and `fa2-grid` (G1-G7, K4, K5) per iteration, then `fa2-to-scene`. The profiler
+     * budgets PROFILER_QUERY_SLOTS / 2 = 128 passes per batch, so a grid batch above 42 iterations is timed only in
+     * part (the exact tier's two passes per batch always fit): the simulation then reports msPerIteration from the
+     * wall time, never from the sum of the timed prefix (`ForceSimulation.batchMilliseconds`). The simulation
+     * passes "K5" for iterations 0..k-2 and undefined for the last, so toScene runs once per batch. The first call
+     * after load() zeroes oldForce before K1 (paper mode). With n === 0 nothing is recorded (PLAN DECISION 9); a
+     * call before bind() completed is E_NOT_LOADED (never a silent no-op).
      * @param batch - the batch being recorded
      * @param slot - the UniformRing slot holding this iteration's Fa2Params
-     * @param tier - "exact" (the grid tier is E_UNSUPPORTED until P4; the simulation never passes "grid")
+     * @param tier - the tier the simulation resolved at load() (the same rule bind() applied, PD-18)
      * @param upTo - a stage name to stop after; undefined records every stage including toScene
      */
     recordIteration(batch, slot, tier, upTo) {
-        if (tier === "grid") {
-            throw new WebGpuGraphError("E_UNSUPPORTED", "the grid repulsion tier lands in P4", {
-                feature: "repulsion.grid",
-                hint: 'pass repulsion: "exact"',
-            });
-        }
         const resources = this.requireResources();
-        const stop = upTo === undefined ? FA2_STAGES.length - 1 : this.stageIndex(upTo);
+        const stop = upTo === undefined ? STAGE_TO_SCENE : this.stageIndex(upTo);
         const { bound } = this;
         if (bound === null) {
             if (resources.n === 0) {
@@ -380,47 +449,124 @@ export class ForceAtlas2Model {
             });
         }
         const offset = resources.ring.offsetOf(slot);
+        if (tier === "grid") {
+            this.recordGridIteration(batch, bound, offset, stop);
+            return;
+        }
+        const { repulsion } = bound;
+        if (repulsion === null) {
+            throw new WebGpuGraphError("E_NOT_LOADED", "the ForceAtlas2 model was bound on the grid tier", {
+                state: "loaded",
+            });
+        }
         const pass = this.openPass !== null && this.openPass.id === batch.id ? this.openPass.pass : batch.pass("fa2");
         this.openPass = { id: batch.id, pass };
-        if (this.resetOldForce) {
-            this.resetOldForce = false;
-            if (bound.fillOldBound !== null) {
-                bound.fill.dispatch(pass, bound.fillOldBound, bound.fillPlan, [0]);
-            }
-        }
-        bound.k1.dispatch(pass, bound.k1Bound, ONE_WORKGROUP, [offset]);
+        this.recordK1(pass, bound, offset);
         if (stop < 1) {
             return;
         }
-        if (bound.k2Bound !== null) {
-            bound.k2.dispatch(pass, bound.k2Bound, bound.plan, [offset]);
+        this.recordK2(pass, bound, offset);
+        if (stop < 2) {
+            return;
         }
-        else if (bound.fillForceBound !== null) {
-            bound.fill.dispatch(pass, bound.fillForceBound, bound.fillPlan, [0]);
+        repulsion.recordRepulsion(pass, bound.n, offset);
+        if (stop < STAGE_K4) {
+            return;
         }
-        if (stop < 2) {
+        repulsion.recordSpeedFinalize(pass, offset);
+        if (stop < STAGE_K5) {
             return;
         }
-        bound.repulsion.recordRepulsion(pass, bound.n, offset);
-        if (stop < 3) {
+        bound.k5.dispatch(pass, bound.k5Bound, bound.plan, [offset]);
+        if (stop < STAGE_TO_SCENE) {
             return;
         }
-        bound.repulsion.recordSpeedFinalize(pass, offset);
-        if (stop < 4) {
+        this.recordToScene(batch, bound, offset);
+    }
+    /**
+     * The grid tier's iteration (PD-16): three compute passes before toScene.
+     * @param batch - the batch being recorded
+     * @param bound - the bound model
+     * @param offset - the Fa2Params dynamic offset of the iteration
+     * @param stop - the FA2_STAGES index to stop after
+     */
+    recordGridIteration(batch, bound, offset, stop) {
+        const { grid } = bound;
+        if (grid === null) {
+            throw new WebGpuGraphError("E_NOT_LOADED", "the ForceAtlas2 model was bound on the exact tier", {
+                state: "loaded",
+            });
+        }
+        this.openPass = null;
+        this.recordK1(batch.pass("fa2-k1"), bound, offset);
+        if (stop < 1) {
+            return;
+        }
+        this.recordK2(batch.pass("fa2-attraction"), bound, offset);
+        if (stop < STAGE_G1) {
+            return;
+        }
+        const pass = batch.pass("fa2-grid");
+        const gridStop = stop < STAGE_K4 ? FA2_STAGES[stop] : undefined;
+        grid.recordRepulsion(pass, bound.n, offset, gridStop);
+        if (stop < STAGE_K4) {
+            return;
+        }
+        grid.recordSpeedFinalize(pass, offset);
+        if (stop < STAGE_K5) {
             return;
         }
         bound.k5.dispatch(pass, bound.k5Bound, bound.plan, [offset]);
-        if (stop < 5) {
+        if (stop < STAGE_TO_SCENE) {
             return;
         }
-        // the second pass ends the K1-K5 pass; the batch is complete after toScene, so nothing reuses it
+        this.recordToScene(batch, bound, offset);
+    }
+    /**
+     * The oldForce reset of the first iteration after load() (paper mode), then K1 (one workgroup).
+     * @param pass - the open compute pass
+     * @param bound - the bound model
+     * @param offset - the Fa2Params dynamic offset
+     */
+    recordK1(pass, bound, offset) {
+        if (this.resetOldForce) {
+            this.resetOldForce = false;
+            if (bound.fillOldBound !== null) {
+                bound.fill.dispatch(pass, bound.fillOldBound, bound.fillPlan, [0]);
+            }
+        }
+        bound.k1.dispatch(pass, bound.k1Bound, ONE_WORKGROUP, [offset]);
+    }
+    /**
+     * K2's tier dispatches, or the fill of force when the graph has no arcs (spec 7.5).
+     * @param pass - the open compute pass
+     * @param bound - the bound model
+     * @param offset - the Fa2Params dynamic offset
+     */
+    recordK2(pass, bound, offset) {
+        if (bound.attraction !== null) {
+            recordAttraction(pass, bound.attraction, offset);
+        }
+        else if (bound.fillForceBound !== null) {
+            bound.fill.dispatch(pass, bound.fillForceBound, bound.fillPlan, [0]);
+        }
+    }
+    /**
+     * The toScene pass that ends the iteration's pass; the batch is complete after it, so nothing reuses the pass.
+     * @param batch - the batch
+     * @param bound - the bound model
+     * @param offset - the Fa2Params dynamic offset
+     */
+    recordToScene(batch, bound, offset) {
         this.openPass = null;
         const scenePass = batch.pass("fa2-to-scene");
         bound.toScene.dispatch(scenePass, bound.toSceneBound, bound.plan, [offset]);
     }
     /**
      * speed = 1, speedEfficiency = 1, swing = 1, traction = 1 (mode 1 accumulates from 1; mode 0 overwrites them each
-     * iteration, the initial value is irrelevant); arms the oldForce reset of the next recordIteration.
+     * iteration, the initial value is irrelevant); arms the oldForce reset of the next recordIteration. On a grid
+     * load the frame of the first build (K1 folds nothing on the first iteration): the same six values K1 derives,
+     * in f32 with the kernel's order of operations, from the host-written min / max / centroid / rmsRadius.
      * @param state - the state writer of the simulation
      */
     onLoad(state) {
@@ -429,6 +575,9 @@ export class ForceAtlas2Model {
         state.set("swing", 1);
         state.set("traction", 1);
         this.resetOldForce = true;
+        if (this.nextGrid !== null) {
+            writeGridFrame(state, this.nextGrid, this.tuning.extentFactor);
+        }
     }
     /**
      * Mode 0: nothing (D8). Mode 1 (networkx): swing = traction = 1 (spec 7.2 "load() and reheat() reset them to 1").
@@ -462,7 +611,9 @@ export class ForceAtlas2Model {
     }
     /**
      * Decodes the state header and the k trace records of a completed batch (k = trace.byteLength / 32) into
-     * ForceAtlas2Stats: the exact tier with null grid fields; msPerIteration null (the simulation owns the clock).
+     * ForceAtlas2Stats: `repulsionTier` is the bound tier, the grid fields are the header's on the grid tier
+     * (`maxCellOccupancy` / `outsideGrid`: the counts of the iteration before the last K1) and null on the exact
+     * tier; msPerIteration null (the simulation owns the clock).
      * @param state - a DataView over the 256-byte state header
      * @param trace - a DataView over the k Fa2Trace records of the batch
      * @returns the stats
@@ -483,15 +634,16 @@ export class ForceAtlas2Model {
                 settledCount: scalar(record, "settledCount"),
             });
         }
+        const grid = this.resources?.tier === "grid";
         return {
             iteration: scalar(header, "iteration"),
             meanDisplacement: scalar(header, "meanDisplacement"),
             rmsRadius: scalar(header, "rmsRadius"),
             layoutRadius: scalar(header, "radius"),
             centroid: [centroid[0], centroid[1], centroid[2]],
-            repulsionTier: "exact",
-            maxCellOccupancy: null,
-            outsideGrid: null,
+            repulsionTier: grid ? "grid" : "exact",
+            maxCellOccupancy: grid ? scalar(header, "maxCellOccupancy") : null,
+            outsideGrid: grid ? scalar(header, "outsideGrid") : null,
             msPerIteration: null,
             swing: scalar(header, "swing"),
             traction: scalar(header, "traction"),
@@ -525,10 +677,17 @@ export class ForceAtlas2Model {
         }
         throw invalid("upTo", upTo, FA2_STAGES.join(" | "));
     }
+    /**
+     * Releases the grid stage's lease and the bind groups (the simulation calls it from dispose() once every
+     * in-flight batch has settled).
+     */
+    dispose() {
+        this.dropBound();
+    }
     /**
      * Drops the bind groups of the previous bind() (the buffers changed) so the cached kernels do not accumulate stale
-     * groups across reloads; K3 / K4 live inside RepulsionExact and keep the P1-T6 behaviour. Also forgets the pass
-     * of a batch recorded before the rebind.
+     * groups across reloads; K3 / K4 live inside RepulsionExact and keep the P1-T6 behaviour; the grid stage
+     * releases its lease. Also forgets the pass of a batch recorded before the rebind.
      */
     dropBound() {
         this.openPass = null;
@@ -536,12 +695,48 @@ export class ForceAtlas2Model {
         if (bound === null) {
             return;
         }
-        for (const kernel of [bound.k1, bound.k2, bound.k5, bound.toScene, bound.fill]) {
+        for (const kernel of [bound.k1, bound.k5, bound.toScene, bound.fill]) {
+            kernel.invalidate();
+        }
+        for (const [kernel] of bound.attraction?.kernels ?? []) {
             kernel.invalidate();
         }
+        bound.grid?.dispose();
         this.bound = null;
     }
 }
+/**
+ * The grid frame of the first build after load() (spec 7.7 geometry table; PD-10): K1's text in f32 with the same
+ * order of operations -- `box = (max - min) * GRID_BBOX_MARGIN`, `extent = max(min(max(box), extentFactor *
+ * rmsRadius), GRID_EXTENT_FLOOR)`, `cellSize = extent / G`, `gridMin = centroid - extent / 2` (cellSize in `.w`),
+ * `invCellSize = 1 / cellSize`, `eps = 0.25 cellSize` -- plus zero counts. Shared with the FR and spring-electrical
+ * models' onLoad (P4-T13).
+ * @param state - the state writer (min / max / centroid / rmsRadius already written by the simulation)
+ * @param spec - the grid of the load
+ * @param extentFactor - the tuning's extent factor
+ */
+export function writeGridFrame(state, spec, extentFactor) {
+    const f = Math.fround;
+    const axis = (name) => {
+        const value = state.get(name);
+        return typeof value === "number" ? [value, value, value] : value;
+    };
+    const min = axis("min");
+    const max = axis("max");
+    const centroid = axis("centroid");
+    const rms = state.get("rmsRadius");
+    const box = [0, 1, 2].map((a) => f(f(f(max[a]) - f(min[a])) * f(GRID_BBOX_MARGIN)));
+    const bboxExtent = spec.dim === 3 ? Math.max(box[0], box[1], box[2]) : Math.max(box[0], box[1]);
+    const rmsTerm = f(f(extentFactor) * f(typeof rms === "number" ? rms : 0));
+    const extent = Math.max(Math.min(bboxExtent, rmsTerm), f(GRID_EXTENT_FLOOR));
+    const cellSize = f(extent / spec.g);
+    const half = f(0.5 * extent);
+    state.set("gridMin", [f(f(centroid[0]) - half), f(f(centroid[1]) - half), f(f(centroid[2]) - half), cellSize]);
+    state.set("invCellSize", f(1 / cellSize));
+    state.set("eps", f(0.25 * cellSize));
+    state.set("outsideGrid", 0);
+    state.set("maxCellOccupancy", 0);
+}
 // ============================================================ the factory
 /**
  * The resolve callback of the simulation's setParams: the patch over the current record, re-validated (the current
@@ -554,8 +749,9 @@ function resolvePatch(patch, current) {
     return resolveForceAtlas2Options(patch, resolveForceAtlas2Options(current));
 }
 /**
- * Spec 3.3 createForceAtlas2, verbatim: a GpuLayoutSimulation running ForceAtlas2 on the exact repulsion tier with
- * the option defaults of spec 7.14 and the GPU-only tuning of GpuLayoutTuning (contract 3.13 "Contracts").
+ * Spec 3.3 createForceAtlas2, verbatim: a GpuLayoutSimulation running ForceAtlas2 on the exact or the grid repulsion
+ * tier (spec 7.8) with the option defaults of spec 7.14 and the GPU-only tuning of GpuLayoutTuning (contract 3.13
+ * "Contracts").
  * @param ctx - the context (E_DISPOSED / E_DEVICE_LOST through assertReady)
  * @param options - the ForceAtlas2 options and the GPU-only tuning knobs in one record
  * @returns the simulation in state "created"; load() next