@graphty/webgpu-graph-algorithms 0.5.1 → 0.6.0

package/src/layouts/calibrate.ts

@@ -0,0 +1,187 @@
+/**
+ * calibrateLayout (spec 2.2, 7.8, D26; contract 3.3): the layout-tier micro-benchmark a consumer runs ONCE, off the
+ * critical path, to measure the exact / grid crossover on the actual device. For every probed size it builds a seeded
+ * G(n, 10n) snapshot, runs ForceAtlas2 on the exact tier and on the grid tier -- one untimed `step(1)` after
+ * `load()` (which warms every pipeline through `PipelineCache.warm` of the model's specs, so the first timed step
+ * compiles nothing) and then TIMED_ITERATIONS timed `step(1)` calls whose `stats.msPerIteration` (the profiler's GPU
+ * time when "timestamp-query" was granted, else the batch wall time) are averaged -- and releases the probe.
+ *
+ * PLAN DECISION PD-23 (P4-T14): `src/` cannot import `test/helpers` or `benchmarks/`, so the probe graphs are built
+ * here from the package's own LCG (`Lcg`, seed.ts) with a fixed seed, and the spec 7.8 rule is re-implemented in
+ * `suggestedExactMaxNodes` below; its twin is `exactMaxNodesFromLadder` in benchmarks/layout-exact.bench.ts (the
+ * one copy the G3 / G4 records apply to the committed baselines), which test/layouts/calibrate.test.ts compares it
+ * with. The function reads `caps` for nothing: never `caps.software` (spec 7.8, Q-6), so on a software adapter it
+ * returns honest numbers a caller can compare in shape, never in value.
+ */
+
+import { fromEdgeArrays, type GraphSnapshot } from "@graphty/graph-format";
+
+import { type GpuContext } from "../context.js";
+import { WebGpuGraphError } from "../errors.js";
+import { assertDeviceComputes } from "../primitives/verify.js";
+import { type CalibrateOptions, type GpuCalibration } from "../types/layout.js";
+import { createForceAtlas2 } from "./forceatlas2.js";
+import { Lcg } from "./seed.js";
+
+/** The default probe sizes (spec 2.2): the 8k-65k subset of the exact ladder of spec 7.8 / 10.4 T-4. */
+export const CALIBRATE_SIZES: readonly number[] = [8_192, 16_384, 32_768, 65_536];
+
+/** The spec 7.8 per-iteration budget of the exact tier, milliseconds (the twin of EXACT_BUDGET_MS in benchmarks/layout-exact.bench.ts). */
+const BUDGET_MS = 4;
+
+/** Edges per node of every probe graph (E = 10n, the density of the exact ladder). */
+const EDGES_PER_NODE = 10;
+
+/** Timed iterations per size and tier (spec 2.2: "10 timed iterations"). */
+const TIMED_ITERATIONS = 10;
+
+/** The seed of every probe graph and of the simulation's own LCG. */
+const SEED = 12345;
+
+/**
+ * A seeded G(n, 10n) probe snapshot (self-loops and parallels allowed, unweighted, undirected).
+ * @param n - the node count
+ * @returns the snapshot
+ */
+function probeSnapshot(n: number): GraphSnapshot {
+    const m = EDGES_PER_NODE * n;
+    const rng = new Lcg(SEED);
+    const src = new Uint32Array(m);
+    const dst = new Uint32Array(m);
+    for (let e = 0; e < m; e++) {
+        src[e] = Math.floor(rng.next() * n);
+        dst[e] = Math.floor(rng.next() * n);
+    }
+    return fromEdgeArrays({ directed: false, nodeCount: n, src, dst }, { label: `calibrate/${n}` });
+}
+
+/**
+ * The mean ms per iteration of one tier at one size: one untimed step after load(), then TIMED_ITERATIONS timed
+ * steps (reheat() before each so a settled simulation never short-circuits). With the profiler (a device that granted
+ * "timestamp-query") the sample is the GPU time of the iteration's passes, the quantity the spec 7.8 rule reads; without
+ * it the sample is the step's wall time, which also carries the JS submit and the 12n-byte readback -- a fixed cost of
+ * ~1-2 ms on a discrete card that is the same for either tier, so the wall ratio understates the grid tier's
+ * advantage at every size and the crossover it suggests is, if anything, too high.
+ * @param ctx - the context
+ * @param snapshot - the probe snapshot
+ * @param tier - the repulsion tier to force
+ * @returns milliseconds per iteration
+ */
+async function probeTier(ctx: GpuContext, snapshot: GraphSnapshot, tier: "exact" | "grid"): Promise<number> {
+    const n = snapshot.nodeCount;
+    const positions = new Float32Array(3 * n).fill(Number.NaN);
+    const sim = createForceAtlas2(ctx, {
+        dim: 2,
+        seed: SEED,
+        maxIter: 1_000_000,
+        iterationsPerStep: 1,
+        maxInFlight: 1,
+        repulsion: tier,
+        compat: "paper",
+    });
+    try {
+        sim.load(snapshot, positions);
+        await sim.step(1);
+        let total = 0;
+        for (let i = 0; i < TIMED_ITERATIONS; i++) {
+            sim.reheat();
+            const start = performance.now();
+            await sim.step(1);
+            const wall = performance.now() - start;
+            total += sim.stats.msPerIteration ?? wall;
+        }
+        return total / TIMED_ITERATIONS;
+    } finally {
+        sim.dispose();
+    }
+}
+
+/**
+ * The largest power of two that is <= n (the twin of floorPow2 in benchmarks/layout-exact.bench.ts).
+ * @param n - a number >= 1
+ * @returns the largest power of two not above n
+ */
+function floorPow2(n: number): number {
+    let p = 1;
+    while (p * 2 <= n) {
+        p *= 2;
+    }
+    return p;
+}
+
+/**
+ * The spec 7.8 rule over the probed sizes (the twin of exactMaxNodesFromLadder(rows, budget, gridRows) in
+ * benchmarks/layout-exact.bench.ts, which test/layouts/calibrate.test.ts compares it with): the largest probed n with
+ * exactMs(n) <= BUDGET_MS and exactMs(n) <= gridMs(n), rounded down to a power of two.
+ *
+ * CONTRACT DECISION (the review of P4-T14; spec 2.2 is silent): when NO probed size satisfies the rule -- the grid
+ * tier faster than the exact tier at every probe (the RTX 4070 SUPER with the default sizes: the grid beats the exact
+ * tier from 4k up), or every probe over the budget -- the benchmark twin throws and hands the value to an owner
+ * decision (spec 10.4), which a library call cannot do. The answer here is then the largest power of two STRICTLY
+ * BELOW the smallest probe (1 when the smallest probe is 1): the exact tier runs at no probed size, the unprobed range
+ * below keeps the exact tier (whose cost falls with n^2 and is the oracle), and the value is distinguishable from a
+ * rule answer, which is never below floorPow2(min(sizes)). A caller that wants the crossover itself probes smaller
+ * sizes (the T-4 ladder from 1k); one that wants the exact tier nowhere passes `repulsion: "grid"`.
+ * @param sizes - the probed sizes (integers >= 1)
+ * @param exactMs - ms per iteration of the exact tier per size
+ * @param gridMs - ms per iteration of the grid tier per size
+ * @returns the suggested exactMaxNodes
+ */
+export function suggestedExactMaxNodes(
+    sizes: readonly number[],
+    exactMs: Readonly<Record<number, number>>,
+    gridMs: Readonly<Record<number, number>>,
+): number {
+    let best = 0;
+    for (const n of sizes) {
+        if (exactMs[n] <= BUDGET_MS && exactMs[n] <= gridMs[n] && n > best) {
+            best = n;
+        }
+    }
+    return floorPow2(best === 0 ? Math.max(1, Math.min(...sizes) - 1) : best);
+}
+
+/**
+ * Spec 2.2 calibrateLayout, verbatim: measures ms per iteration of the exact and the grid repulsion tier at every
+ * probed size on THIS device and suggests `exactMaxNodes` by the spec 7.8 rule (`suggestedExactMaxNodes` above, with
+ * its below-the-range answer when no probed size qualifies). Every probe graph is built here and released before the
+ * call returns; `firstCallMs` is the wall time of the whole call (pipeline compilation included the first time). The
+ * app passes `suggestedExactMaxNodes` through `createAccelerator(ctx, { layout: { exactMaxNodes } })`; the package
+ * never calls this implicitly and `"auto"` never depends on `caps.software`.
+ * @param ctx - the context (E_DISPOSED / E_DEVICE_LOST through assertReady)
+ * @param options - the probe sizes (positive integers; default CALIBRATE_SIZES)
+ * @returns the calibration record
+ */
+export async function calibrateLayout(ctx: GpuContext, options?: CalibrateOptions): Promise<GpuCalibration> {
+    ctx.assertReady();
+    await assertDeviceComputes(ctx);
+    const sizes = options?.sizes ?? CALIBRATE_SIZES;
+    if (!Array.isArray(sizes) || sizes.length === 0 || !sizes.every((n) => Number.isInteger(n) && n >= 1)) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", "sizes must be a non-empty list of integers >= 1", {
+            argument: "sizes",
+            value: sizes,
+            expected: "a non-empty list of integers >= 1",
+        });
+    }
+    const start = performance.now();
+    const exactMsPerIter: Record<number, number> = {};
+    const gridMsPerIter: Record<number, number> = {};
+    for (const n of sizes) {
+        const snapshot = probeSnapshot(n);
+        try {
+            exactMsPerIter[n] = await probeTier(ctx, snapshot, "exact");
+            gridMsPerIter[n] = await probeTier(ctx, snapshot, "grid");
+        } finally {
+            ctx.release(snapshot);
+        }
+    }
+    const largest = Math.max(...sizes);
+    const pairs = largest * (largest - 1);
+    return {
+        pairsPerSecond: (pairs / exactMsPerIter[largest]) * 1000,
+        exactMsPerIter,
+        gridMsPerIter,
+        suggestedExactMaxNodes: suggestedExactMaxNodes(sizes, exactMsPerIter, gridMsPerIter),
+        firstCallMs: performance.now() - start,
+    };
+}

package/src/layouts/force-simulation.ts

@@ -24,11 +24,15 @@ import { BufferUsage } from "../device/webgpu-constants.js";
 import { hasErrorCode, WebGpuGraphError } from "../errors.js";
 import { CommandBatch, type ReadbackRequest, type SubmittedBatch } from "../kernel/batch.js";
 import { type PipelineCache } from "../kernel/pipeline-cache.js";
+import { type PassTiming } from "../kernel/profiler.js";
 import { type UniformBlock, type UniformFieldType, type UniformValues } from "../kernel/struct-block.js";
 import { UniformRing } from "../kernel/uniform-ring.js";
 import { type WgslModuleSpec } from "../kernel/wgsl.js";
 import { graphOverrides } from "../kernels.js";
+import { type BufferPool } from "../memory/buffer-pool.js";
 import { type ArrayBinding, type CoreBinding } from "../memory/residency.js";
+import { type DegreeTiers, degreeTiersOf } from "../primitives/core-shape.js";
+import { assertDeviceComputes } from "../primitives/verify.js";
 import { type PlanCaps } from "../types/context.js";
 import {
     type GpuLayoutSimulation,
@@ -65,7 +69,14 @@ export interface ModelResources {
     readonly caps: PlanCaps;
     readonly pipelines: PipelineCache;
     readonly core: CoreBinding;
+    /** `tiers.perm`, or null when no row has degree >= 32 (P4 PD-7: the rowPtr dummy is bound and USE_PERM is false). */
     readonly perm: Binding | null;
+    /**
+     * The degree tiers of the snapshot's degreeOrder view (the perm binding and the CPU-side segment offsets
+     * [0, hiEnd, midEnd, lowEnd, n]), or null when no row has degree >= 32 -- then every K2 dispatch is the
+     * thread-per-row TIER 0 over node indices, as before P4.
+     */
+    readonly tiers: DegreeTiers | null;
     /**
      * The RESOLVED weights binding (model.inputs(): source "arcs" -> core.weights (null on an unweighted snapshot),
      * "column" -> the registered ArrayBinding's binding, "none" -> null); group 0 is built as
@@ -76,6 +87,8 @@ export interface ModelResources {
     readonly dim: 2 | 3;
     readonly tier: "exact" | "grid";
     readonly ring: UniformRing;
+    /** The context's buffer pool (the grid stage's lease of sort scratch draws on it, P4 PD-11). */
+    readonly pool: BufferPool;
     /** A shared or model-owned buffer by name: "positions", "scenePositions", "fixed", "partials", "state", "trace", plus every BufferSpec name. */
     buffer(name: string): Binding;
 }
@@ -125,6 +138,8 @@ export interface ForceModel<Options, Stats extends LayoutStatsBase> {
     onReheat(state: StateWriter): void;
     onSetParams(patch: Partial<Options>, state: StateWriter): void;
     readStats(state: DataView, trace: DataView): Stats;
+    /** Releases what the model holds outside the simulation's buffers (the grid stage's lease, P4-T10); called by dispose() once every in-flight batch has settled. */
+    dispose?(): void;
 }
 
 // ============================================================ module-private helpers
@@ -156,6 +171,21 @@ const SHARED_STATE_FIELDS: readonly (readonly [string, number])[] = [
 /** The names of the shared buffers a BufferSpec may not reuse. */
 const SHARED_BUFFER_NAMES: readonly string[] = ["positions", "scenePositions", "fixed", "partials", "state", "trace"];
 
+/** The buffers inspect() returns as Uint32Array: the mask, the trace records and the grid tier's index / count arrays (P4). */
+const U32_BUFFER_NAMES: ReadonlySet<string> = new Set([
+    "fixed",
+    "trace",
+    "cellKey",
+    "cellVal",
+    "sortedKey",
+    "sortedIdx",
+    "cellHist",
+    "cellStart",
+    "hubList",
+    "hubCounters",
+    "hubArgs",
+]);
+
 /** The per-batch epilogue stage: iterations 0..k-2 stop after the stage that precedes it (PLAN DECISION 2). */
 const EPILOGUE_STAGE = "toScene";
 
@@ -355,12 +385,13 @@ function centerOf(options: CommonLayoutOptions): [number, number, number] {
 }
 
 /**
- * The repulsion tier of a node count under a tuning (PLAN DECISION 11).
+ * The repulsion tier of a node count under a tuning (PLAN DECISION 11; spec 7.8: `"auto"` by `n` alone). Exported
+ * so a model's `buffers(n, dim)` decides the tier by the same rule `load()` applies (P4 PD-18).
  * @param tuning - the resolved tuning
  * @param n - the node count
  * @returns "exact" or "grid"
  */
-function tierFor(tuning: ResolvedLayoutTuning, n: number): "exact" | "grid" {
+export function tierFor(tuning: ResolvedLayoutTuning, n: number): "exact" | "grid" {
     if (tuning.repulsion === "exact") {
         return "exact";
     }
@@ -621,6 +652,7 @@ export class ForceSimulation<
     private settledValue = false;
     private firstPending = true;
     private statsValue: Stats | null = null;
+    private lastPassTimingsValue: readonly PassTiming[] | null = null;
     private lastSubmittedBatchIdValue = 0;
     /** The id of the last batch submitted BEFORE the most recent reheat() (PLAN DECISION 21); 0 = none. */
     private reheatedAfterBatchId = 0;
@@ -731,13 +763,24 @@ export class ForceSimulation<
     }
 
     /**
-     * The repulsion tier of the current load ("exact" until P4 lifts the grid tier).
+     * The repulsion tier of the current load (spec 7.8).
      * @returns the tier
      */
     get tier(): "exact" | "grid" {
         return this.tierValue;
     }
 
+    /**
+     * The profiler's per-pass timings of the last landed batch (pass order; the grid tier's `fa2-k1` /
+     * `fa2-attraction` / `fa2-grid` / `fa2-to-scene` rows give T-7's attraction figure, P4 PD-16), or null before a
+     * batch landed or without `timestamp-query`.
+     * @internal
+     * @returns the timings
+     */
+    get lastPassTimings(): readonly PassTiming[] | null {
+        return this.lastPassTimingsValue;
+    }
+
     /**
      * The generation counter bumped by every load() (stale readbacks are discarded).
      * @internal
@@ -888,16 +931,6 @@ export class ForceSimulation<
         const scale = scaleOf(this.optionsValue);
         const center = centerOf(this.optionsValue);
         const tier = tierFor(this.tuning, n);
-        if (tier === "grid") {
-            throw new WebGpuGraphError(
-                "E_UNSUPPORTED",
-                `the grid repulsion tier lands at P4 (n = ${n}, exactMaxNodes = ${this.tuning.exactMaxNodes})`,
-                {
-                    feature: "repulsion.grid",
-                    hint: 'pass repulsion: "exact" or raise exactMaxNodes',
-                },
-            );
-        }
         const positionsBytes = 16 * n;
         if (positionsBytes > this.ctx.caps.limits.maxBufferSize) {
             throw new WebGpuGraphError("E_TOO_LARGE", `${positionsBytes} bytes of positions exceed maxBufferSize`, {
@@ -908,6 +941,7 @@ export class ForceSimulation<
             });
         }
         let core: CoreBinding | null = null;
+        let tiers: DegreeTiers | null = null;
         let inputs: ModelInputs | null = null;
         if (n > 0) {
             core = this.ctx.residency.core(snapshot);
@@ -923,6 +957,11 @@ export class ForceSimulation<
                     },
                 );
             }
+            // PD-7 (the 7.3 rule): the permutation is bound iff a row of degree >= 32 exists; the view is uploaded
+            // only then, so a low-degree snapshot compiles and runs the same pipelines as before P4
+            if (snapshot.degreeOrder().segmentOffsets[2] > 0) {
+                tiers = degreeTiersOf(this.ctx.residency.view(snapshot, "degreeOrder"));
+            }
             inputs = this.model.inputs(snapshot, this.optionsValue);
             if (inputs.mass.length !== n) {
                 throw invalidArgument(
@@ -991,8 +1030,11 @@ export class ForceSimulation<
         seedPositions(snapshot, positions, this.optionsValue.seed ?? null, this.dimValue, scale, center, range);
         this.uploadPositions(buffers, positions, inputs.mass);
         const weights = this.resolveWeightsBinding(snapshot, core, inputs.weights);
-        const overrides = { ...this.model.overrides(this.optionsValue), ...graphOverrides(core, null, weights) };
-        const resources = this.makeResources(core, weights, buffers);
+        const overrides = {
+            ...this.model.overrides(this.optionsValue),
+            ...graphOverrides(core, tiers?.perm ?? null, weights),
+        };
+        const resources = this.makeResources(core, tiers, weights, buffers);
         this.resources = resources;
         this.startBind(resources, overrides);
         this.settledValue = false;
@@ -1267,7 +1309,10 @@ export class ForceSimulation<
         this.center = center;
         const { resources, core } = this;
         if (this.stateValue === "loaded" && resources !== null && core !== null && before !== after) {
-            const overrides = { ...this.model.overrides(next), ...graphOverrides(core, null, resources.weights) };
+            const overrides = {
+                ...this.model.overrides(next),
+                ...graphOverrides(core, resources.perm, resources.weights),
+            };
             this.startBind(resources, overrides);
         }
         this.model.onSetParams(patch, this.writer);
@@ -1484,7 +1529,10 @@ export class ForceSimulation<
     }
 
     /**
-     * The batch's duration in milliseconds: the profiler's pass timings summed when present, else wall time.
+     * The batch's duration in milliseconds: the profiler's pass timings summed when present and complete, else wall
+     * time. The profiler budgets PROFILER_QUERY_SLOTS / 2 passes per batch; the grid tier records three passes per
+     * iteration (P4 PD-16), so a grid batch above (PROFILER_QUERY_SLOTS / 2 - 1) / 3 iterations is timed partially:
+     * its rows stay in `lastPassTimings` but the duration is the wall time, never the sum of a prefix.
      * @param record - the batch
      * @param bytes - its readback (the profiler's resolve lands in it)
      * @returns milliseconds
@@ -1493,7 +1541,8 @@ export class ForceSimulation<
         const { profiler } = this.ctx;
         if (profiler !== null && record.profile !== null) {
             const timings = profiler.timings(bytes, record.profile);
-            if (timings.length > 0) {
+            this.lastPassTimingsValue = timings;
+            if (timings.length > 0 && !profiler.partial(record.profile)) {
                 let ns = 0;
                 for (const timing of timings) {
                     ns += timing.ns;
@@ -1934,23 +1983,31 @@ export class ForceSimulation<
     /**
      * The ModelResources of a load.
      * @param core - the core
+     * @param tiers - the degree tiers, or null when no row has degree >= 32
      * @param weights - the resolved weights binding
      * @param buffers - the buffers
      * @returns the resources
      */
-    private makeResources(core: CoreBinding, weights: Binding | null, buffers: SimulationBuffers): ModelResources {
+    private makeResources(
+        core: CoreBinding,
+        tiers: DegreeTiers | null,
+        weights: Binding | null,
+        buffers: SimulationBuffers,
+    ): ModelResources {
         const { bindings } = buffers;
         return {
             device: this.ctx.device,
             caps: this.ctx.caps,
             pipelines: this.ctx.pipelines,
             core,
-            perm: null,
+            perm: tiers?.perm ?? null,
+            tiers,
             weights,
             n: this.n,
             dim: this.dimValue,
             tier: this.tierValue,
             ring: this.ring,
+            pool: this.ctx.pool,
             buffer: (name: string): Binding => {
                 const binding = bindings.get(name);
                 if (binding === undefined) {
@@ -1980,7 +2037,16 @@ export class ForceSimulation<
     }
 
     /**
-     * warm(model.specs()) then model.bind(); the await re-checks that the load is current before binding.
+     * assertDeviceComputes() then warm(model.specs()) then model.bind(); the await re-checks that the load is
+     * current before binding.
+     *
+     * The device self-check sits HERE rather than in submitBatch (its first home) because this promise is the one
+     * submitBatch already awaits before every batch: the check is therefore settled before the simulation can
+     * submit a single iteration, yet costs the frame loop nothing per batch. An extra await on the per-batch path
+     * moves the moment a submission becomes visible to a step() issued in the same tick, which is precisely what
+     * coalescing is measured on (test/layouts/frame-loop.test.ts, "a coalesced step() returns the same promise").
+     * A device that computes incorrectly rejects this promise, so the first step() rejects E_DEVICE_INCORRECT
+     * before any position is written; a check that could not RUN rejects with its own error, unchanged.
      * @param resources - the resources
      * @param overrides - the merged override set
      * @param generation - the generation the bind belongs to
@@ -1990,6 +2056,7 @@ export class ForceSimulation<
         overrides: Readonly<Record<string, number | boolean>>,
         generation: number,
     ): Promise<void> {
+        await assertDeviceComputes(this.ctx);
         const subgroups = this.ctx.caps.features.has("subgroups");
         await this.ctx.pipelines.warm(this.model.specs(overrides, subgroups));
         if (this.stateValue !== "loaded" || generation !== this.generationValue) {
@@ -2001,7 +2068,7 @@ export class ForceSimulation<
     // ---------------------------------------------------------------- private: inspect and debug runs
 
     /**
-     * inspect(name): flush, read the named buffer back, Uint32Array for "fixed" and "trace", Float32Array otherwise.
+     * inspect(name): flush, read the named buffer back, Uint32Array for the u32 buffers (U32_BUFFER_NAMES), Float32Array otherwise.
      * @param name - a shared or BufferSpec name
      * @returns the words
      */
@@ -2019,7 +2086,7 @@ export class ForceSimulation<
         }
         await this.flush();
         const bytes = await this.ctx.readback.read(binding.buffer, binding.size, undefined, binding.offset);
-        return name === "fixed" || name === "trace" ? new Uint32Array(bytes) : new Float32Array(bytes);
+        return U32_BUFFER_NAMES.has(name) ? new Uint32Array(bytes) : new Float32Array(bytes);
     }
 
     /**
@@ -2100,6 +2167,7 @@ export class ForceSimulation<
         this.destroyBuffers();
         this.afterInFlight(() => {
             this.ring.destroy();
+            this.model.dispose?.();
         });
         if (this.ctx.state === "ready") {
             this.ctx.pool.trim();