@graphty/webgpu-graph-algorithms 0.5.0 → 0.6.0

package/dist/src/layouts/repulsion-grid.js

@@ -0,0 +1,318 @@
+/**
+ * The grid-tier repulsion stage of the force models (spec 7.7, 7.4; P4-T10): G1-G3 through the T8 grid build, G4-G5
+ * through the T9 pyramid, then G6 (`grid-far-field`) and G7 (`grid-near-field`, K3's pair law and epilogue) over
+ * `plan1d(n)`, followed by K4 (`fa2-speed-finalize`) exactly as `RepulsionExact` records it. The named grid buffers
+ * are the model's `BufferSpec`s (`buffers()`, so `inspect(name)` reaches them); the anonymous scratch of the sort
+ * and the scan and the static params of the pyramid draw on ONE `Lease` of the context's pool taken at `create()`
+ * (the scan planner takes its block-sum levels at prepare time) and released by `dispose()` (PD-11, DEP-P4-D: a
+ * per-batch lease would rebuild the G2-G4 bind groups every batch; a model creates one stage per bind(), so a stage
+ * is bound once). The stage is the ONE class every model reaches the grid tier through (PD-22): the FR and
+ * spring-electrical models pass `LAW` 1 / 2 in their override set, which reaches G6's per-cell law and G7's pair law
+ * (P4-T13).
+ */
+import { GRID_HUB_CELL } from "../constants.js";
+import { BufferUsage } from "../device/webgpu-constants.js";
+import { WebGpuGraphError } from "../errors.js";
+import { plan1d } from "../kernel/dispatch.js";
+import { INDIRECT_ARGS_STRIDE } from "../kernel/kernel.js";
+import { kernelSpec } from "../kernels.js";
+import { gridPyramidBytes, prepareGridBuild, } from "../primitives/grid.js";
+import { preparePyramid } from "../primitives/grid-pyramid.js";
+/** The stage names the grid tier records, in dispatch order (the `upTo` vocabulary of recordRepulsion). */
+const GRID_STAGES = ["G1", "G2", "G3", "G4", "G5", "G6", "G7"];
+/** The storage usage of every grid buffer. */
+const STORAGE_RW = BufferUsage.STORAGE | BufferUsage.COPY_SRC | BufferUsage.COPY_DST;
+/**
+ * The stage's lease, or E_DISPOSED after dispose().
+ * @param box - the stage's lease box
+ * @returns the lease
+ */
+function leaseOf(box) {
+    if (box.lease === null) {
+        throw new WebGpuGraphError("E_DISPOSED", "RepulsionGrid: the stage was disposed", { label: "RepulsionGrid" });
+    }
+    return box.lease;
+}
+/**
+ * A uniform buffer of the lease holding one written record of `block` (the pyramid's static params, PD-11).
+ * @param device - the device
+ * @param lease - the stage's lease
+ * @param block - the uniform block
+ * @param values - the values to write
+ * @returns the whole-buffer binding and a zero dynamic offset
+ */
+function writeParams(device, lease, block, values) {
+    const buffer = lease.uniform(block.byteLength, `grid/${block.name}`);
+    const bytes = new ArrayBuffer(block.byteLength);
+    block.write(new DataView(bytes), values);
+    device.queue.writeBuffer(buffer, 0, bytes);
+    return { binding: { buffer, offset: 0, size: block.byteLength, window: null }, offset: 0 };
+}
+/**
+ * The G6 spec of an override set (the law alone).
+ * @param overrides - the override set of the stage
+ * @returns the spec
+ */
+function farFieldSpec(overrides) {
+    return kernelSpec("grid-far-field", { LAW: overrides.LAW });
+}
+/**
+ * The G7 spec of an override set (K3's four).
+ * @param overrides - the override set of the stage
+ * @returns the spec
+ */
+function nearFieldSpec(overrides) {
+    return kernelSpec("grid-near-field", {
+        SWING_MODE: overrides.SWING_MODE,
+        STRONG_GRAVITY: overrides.STRONG_GRAVITY,
+        GRAVITY_CENTER: overrides.GRAVITY_CENTER,
+        LAW: overrides.LAW,
+    });
+}
+/** G1-G7 then K4 (spec 7.7, 7.4): the grid tier's repulsion stage. */
+export class RepulsionGrid {
+    /**
+     * Holds the planners and kernels; create() is the only caller.
+     * @param scope - the context pieces
+     * @param workgroupSize - the device's workgroup size (every kernel compiles with it)
+     * @param overrides - the override set G6 / G7 / K4 were compiled with
+     * @param spec - the grid
+     * @param box - the lease box the scope's scratch() and params() read
+     * @param build - the T8 planner (G1-G3)
+     * @param pyramid - the T9 planner (G4-G5)
+     * @param kernels - G6 (`far`), G7 (`near`) and K4 (`speedFinalize`)
+     */
+    constructor(scope, workgroupSize, overrides, spec, box, build, pyramid, kernels) {
+        this.bound = null;
+        this.caps = scope.caps;
+        this.box = box;
+        this.workgroupSize = workgroupSize;
+        this.overrides = Object.freeze({
+            SWING_MODE: overrides.SWING_MODE,
+            STRONG_GRAVITY: overrides.STRONG_GRAVITY,
+            GRAVITY_CENTER: overrides.GRAVITY_CENTER,
+            LAW: overrides.LAW,
+        });
+        this.spec = spec;
+        this.build = build;
+        this.pyramid = pyramid;
+        this.far = kernels.far;
+        this.near = kernels.near;
+        this.speedFinalize = kernels.speedFinalize;
+    }
+    /**
+     * The model-owned buffers of the grid tier (spec 7.3; PD-11): `cellKey` / `cellVal` / `sortedKey` / `sortedIdx`
+     * 4n, `cellHist` / `cellStart` 4 (cells + 2) zeroed, `hubList` one word per possible hub cell, `hubArgs` one
+     * indirect slot, `pyramid` 16 B per pyramid cell zeroed. `hubCounters` (16 B, zeroed) is the MODEL's on every
+     * tier (PD-14: K1 binds it on the exact tier too). n = 0 reports one node's worth of bytes (spec 3.6).
+     * @param n - the node count
+     * @param spec - the grid
+     * @returns the specs
+     */
+    static buffers(n, spec) {
+        const words = 4 * Math.max(1, n);
+        return [
+            { name: "cellKey", byteLength: words, usage: STORAGE_RW, zero: false },
+            { name: "cellVal", byteLength: words, usage: STORAGE_RW, zero: false },
+            { name: "sortedKey", byteLength: words, usage: STORAGE_RW, zero: false },
+            { name: "sortedIdx", byteLength: words, usage: STORAGE_RW, zero: false },
+            { name: "cellHist", byteLength: 4 * spec.histWords, usage: STORAGE_RW, zero: true },
+            { name: "cellStart", byteLength: 4 * spec.histWords, usage: STORAGE_RW, zero: true },
+            {
+                name: "hubList",
+                byteLength: 4 * Math.max(1, Math.ceil(n / GRID_HUB_CELL)),
+                usage: STORAGE_RW,
+                zero: false,
+            },
+            { name: "hubArgs", byteLength: INDIRECT_ARGS_STRIDE, usage: STORAGE_RW | BufferUsage.INDIRECT, zero: true },
+            { name: "pyramid", byteLength: gridPyramidBytes(spec), usage: STORAGE_RW, zero: true },
+        ];
+    }
+    /**
+     * The module specs of the grid tier under an override set (for warm() and the compile matrix): the build's
+     * (G1, the sort path `spec.deterministic` selects, the histogram, the scan, the fill), the pyramid's (G4, the
+     * finalize, G4b, G5), G6, G7 and K4.
+     * @param overrides - the override set of the stage
+     * @param spec - the grid (only its `deterministic` flag matters: the pipeline key carries no geometry)
+     * @returns the specs
+     */
+    static specs(overrides, spec) {
+        const sort = spec.deterministic
+            ? [kernelSpec("radix-hist"), kernelSpec("radix-scatter"), kernelSpec("scan-block"), kernelSpec("scan-add")]
+            : [kernelSpec("counting-scatter"), kernelSpec("scan-block"), kernelSpec("scan-add")];
+        return [
+            kernelSpec("grid-cell-key"),
+            ...sort,
+            kernelSpec("histogram"),
+            kernelSpec("fill"),
+            kernelSpec("grid-centroid"),
+            kernelSpec("indirect-finalize"),
+            kernelSpec("grid-centroid-hub"),
+            kernelSpec("grid-downsample"),
+            farFieldSpec(overrides),
+            nearFieldSpec(overrides),
+            kernelSpec("fa2-speed-finalize", { SWING_MODE: overrides.SWING_MODE }),
+        ];
+    }
+    /**
+     * Compiles every kernel of the tier through the cache (sequentially: PipelineCache.get compiles inside a
+     * validation scope, one stack per device) over a scope whose scratch and params draw on the stage's lease.
+     * @param scope - the context pieces (device, caps, pipelines, pool)
+     * @param workgroupSize - the device's workgroup size
+     * @param overrides - the SWING_MODE / STRONG_GRAVITY / GRAVITY_CENTER / LAW set of this stage
+     * @param spec - the grid
+     * @returns the stage, ready for bind()
+     */
+    static async create(scope, workgroupSize, overrides, spec) {
+        const box = { lease: scope.pool.lease() };
+        const reduceScope = {
+            device: scope.device,
+            caps: scope.caps,
+            pipelines: scope.pipelines,
+            pool: scope.pool,
+            workgroupSize,
+            scratch: (byteLength, label) => leaseOf(box).storage(byteLength, label),
+            params: (block, values) => writeParams(scope.device, leaseOf(box), block, values),
+        };
+        try {
+            const build = await prepareGridBuild(reduceScope, spec);
+            const pyramid = await preparePyramid(reduceScope, spec);
+            const far = await scope.pipelines.kernel(farFieldSpec(overrides));
+            const near = await scope.pipelines.kernel(nearFieldSpec(overrides));
+            const speedFinalize = await scope.pipelines.kernel(kernelSpec("fa2-speed-finalize", { SWING_MODE: overrides.SWING_MODE }));
+            return new RepulsionGrid(scope, workgroupSize, overrides, spec, box, build, pyramid, {
+                far,
+                near,
+                speedFinalize,
+            });
+        }
+        catch (error) {
+            leaseOf(box).release();
+            throw error;
+        }
+    }
+    /**
+     * Builds every bind group once per load(): the build's and the pyramid's bind() (which take their scratch and
+     * write their static params through the lease), then G6, G7 and K4 against the named buffers (the 3.10.1
+     * binding names). A second bind() takes fresh scratch from the same lease and the first bind()'s scratch stays
+     * held until dispose(): the one lease also holds the prepare-time allocations (the scan's block-sum levels), so
+     * it cannot be released on a rebind (the model creates one stage per bind(), so a rebind never happens).
+     * @param resources - the buffers of spec 7.3 plus the grid's
+     */
+    bind(resources) {
+        leaseOf(this.box);
+        const r = resources;
+        this.build.bind({
+            pos: r.pos,
+            state: r.state,
+            params: r.params,
+            cellKey: r.cellKey,
+            cellVal: r.cellVal,
+            sortedKey: r.sortedKey,
+            sortedIdx: r.sortedIdx,
+            cellHist: r.cellHist,
+            cellStart: r.cellStart,
+        });
+        this.pyramid.bind({
+            pos: r.pos,
+            params: r.params,
+            sortedIdx: r.sortedIdx,
+            cellStart: r.cellStart,
+            pyramid: r.pyramid,
+            hubList: r.hubList,
+            hubCounters: r.hubCounters,
+            hubArgs: r.hubArgs,
+        });
+        this.bound = {
+            far: this.far.bind({
+                pos: r.pos,
+                sortedIdx: r.sortedIdx,
+                pyramid: r.pyramid,
+                S: r.state,
+                force: r.force,
+                P: r.params,
+            }),
+            near: this.near.bind({
+                pos: r.pos,
+                sortedIdx: r.sortedIdx,
+                cellStart: r.cellStart,
+                S: r.state,
+                force: r.force,
+                oldForce: r.oldForce,
+                fixedMask: r.fixedMask,
+                partials: r.partials,
+                P: r.params,
+            }),
+            speedFinalize: this.speedFinalize.bind({ partials: r.partials, S: r.state, T: r.trace, P: r.params }),
+        };
+    }
+    /**
+     * Records G1..G7 for `n` nodes with the params slot's dynamic offset, stopping after `upTo` when given (spec 7.4
+     * grid sequence; the inspect() stage split, spec 11.9 item 2): G1-G3 through the build planner, G4-G5 through the
+     * pyramid planner, then G6 and G7 over plan1d(n).
+     * @param pass - the open compute pass of the batch
+     * @param n - the node count (in [1, the capacity of the grid buffers])
+     * @param paramsOffset - the dynamic offset of this iteration's Fa2Params slot in the uniform ring
+     * @param upTo - the last grid stage to record (default "G7")
+     */
+    recordRepulsion(pass, n, paramsOffset, upTo) {
+        const bound = this.requireBound("recordRepulsion");
+        const stop = GRID_STAGES.indexOf(upTo ?? "G7");
+        let buildStop = "G3";
+        if (stop === 0) {
+            buildStop = "G1";
+        }
+        else if (stop === 1) {
+            buildStop = "G2";
+        }
+        this.build.record(pass, n, paramsOffset, buildStop);
+        if (stop < 3) {
+            return;
+        }
+        this.pyramid.record(pass, paramsOffset, stop === 3 ? "G4" : "G5");
+        if (stop < 5) {
+            return;
+        }
+        const plan = plan1d(n, this.workgroupSize, this.caps);
+        this.far.dispatch(pass, bound.far, plan, [paramsOffset]);
+        if (stop < 6) {
+            return;
+        }
+        this.near.dispatch(pass, bound.near, plan, [paramsOffset]);
+    }
+    /**
+     * Records K4 only (one workgroup).
+     * @param pass - the open compute pass
+     * @param paramsOffset - the dynamic offset of the Fa2Params slot
+     */
+    recordSpeedFinalize(pass, paramsOffset) {
+        const bound = this.requireBound("recordSpeedFinalize");
+        const one = plan1d(this.speedFinalize.workgroupSize, this.speedFinalize.workgroupSize, this.caps);
+        this.speedFinalize.dispatch(pass, bound.speedFinalize, one, [paramsOffset]);
+    }
+    /** Releases the lease (the sort and scan scratch, the static params) and drops the bind groups; idempotent. */
+    dispose() {
+        if (this.box.lease !== null) {
+            this.box.lease.release();
+            this.box.lease = null;
+        }
+        for (const kernel of [this.far, this.near, this.speedFinalize]) {
+            kernel.invalidate();
+        }
+        this.bound = null;
+    }
+    /**
+     * The bound groups, or E_NOT_LOADED when bind() has not run.
+     * @param method - the caller's name for the message
+     * @returns the bound groups
+     */
+    requireBound(method) {
+        if (this.bound === null) {
+            throw new WebGpuGraphError("E_NOT_LOADED", `RepulsionGrid.${method}(): bind() has not been called for this stage`, {
+                state: "unbound",
+            });
+        }
+        return this.bound;
+    }
+}
+//# sourceMappingURL=repulsion-grid.js.map

package/dist/src/layouts/repulsion-grid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repulsion-grid.js","sourceRoot":"","sources":["../../../src/layouts/repulsion-grid.ts"],"names":[],"mappings":"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"}

package/dist/src/layouts/spring-electrical.d.ts

@@ -0,0 +1,224 @@
+/**
+ * The spring-electrical preset on the exact or the grid repulsion tier (spec 7.20 "the preset", 7.8; contract 3.13):
+ * ngraph.forcelayout's physics under ngraph's option names and defaults -- Coulomb repulsion `-g m_i m_j / d^2` (K3,
+ * LAW 2; G6 / G7 with LAW 2 on the grid tier, P4-T13), Hooke springs
+ * `k_s (d - L)` (K2, LAW 2), drag and the semi-implicit Euler step with the unit speed clamp over a per-node velocity
+ * (K5, APPLY 2), the kinetic energy folded into the trace (K1, STATS_MODE 2; PD-4) -- as the ForceModel that
+ * ForceSimulation drives over the four FA2 kernels K1 K2 K3 K5 per iteration and toScene per batch. No K4: there is no
+ * speed controller. The velocity is the model's `velocity` buffer bound into the `oldForce` slot of K3 and K5 (PD-2),
+ * left alone by the FA2 text because the model compiles `SWING_MODE = 1` (PD-20). Mass is `1 + degree / 3` and the
+ * weights are ignored (PD-11); `SpringElectricalOptions.gravity` is ngraph's Coulomb constant, written into
+ * `Fa2Params.coulomb` while FA2's centre gravity is 0 (PD-12). Settlement is the shared rule of spec 7.17
+ * (DEP-P5-A); `reheat()` leaves the velocities alone (ngraph has no reheat).
+ *
+ * Model decisions this file shares with forceatlas2.ts: on the exact tier the K1-K5 dispatches of one batch share ONE
+ * compute pass and toScene runs in a second pass that ends it; the fill kernel takes its FillParams from a model-owned
+ * 256-byte uniform buffer. The grid tier (P4-T13, PD-22) is FA2's: `RepulsionGrid` with `LAW` 2 when `tierFor(tuning,
+ * n)` says so (PD-18), the grid buffers from `buffers()`, K1's grid block under `gridMax > 0` (PD-14) over the model's
+ * own `hubCounters`, the three passes `se-k1` / `se-attraction` / `se-grid` before `se-to-scene` (PD-16), and the
+ * union stage list (PD-17; K4 is never recorded).
+ */
+import { type GraphSnapshot } from "@graphty/graph-format";
+import { type GpuContext } from "../context.js";
+import { type CommandBatch } from "../kernel/batch.js";
+import { type UniformBlock, type UniformValues } from "../kernel/struct-block.js";
+import { type WgslModuleSpec } from "../kernel/wgsl.js";
+import { type GpuLayoutSimulation, type GpuLayoutTuning, type ResolvedLayoutTuning, type SpringElectricalStats } from "../types/layout.js";
+import { type ResolvedSpringElectricalOptions, type SpringElectricalOptions } from "../types/options.js";
+import { type BufferSpec, type ForceModel, type ModelInputs, type ModelResources, type StateWriter } from "./force-simulation.js";
+import { type Overrides } from "./model-common.js";
+/** The stage names of both tiers in dispatch order plus the per-batch toScene (spec 7.20; P4 PD-17: the union list; the exact tier records K1 K2 K3 K5, the grid tier K1 K2 G1..G7 K5, K4 never). */
+declare const SE_STAGES: readonly ["K1", "K2", "K3", "G1", "G2", "G3", "G4", "G5", "G6", "G7", "K4", "K5", "toScene"];
+/**
+ * The size factor of the default force constants: 1 up to SE_SCALE_REFERENCE_NODES nodes (ngraph's constants as
+ * they are), then SE_SCALE_REFERENCE_NODES / n, so the per-node force stays at the level ngraph's constants were
+ * tuned for instead of pinning every node at the unit speed clamp.
+ * @param n - the node count
+ * @returns the factor in (0, 1]
+ */
+export declare function springSizeFactor(n: number): number;
+/**
+ * Applies SE_DEFAULTS to the option record; validates ranges (spec 7.20; ngraph's constraints): `springLength` > 0,
+ * `springCoefficient` > 0, `dragCoefficient` >= 0, `timeStep` > 0, `gravity` any finite number (negative repels; ngraph's
+ * comment: "if you make it positive nodes start attract each other"). `gravity` and `springCoefficient` left out (or
+ * null) resolve to null: ngraph's constant times springSizeFactor(n), applied in paramsFor once n is known. With `previous` the record is a PATCH over it and
+ * `maxInFlight` may not change (the uniform ring is sized by it at construction).
+ * @param options - the caller's options (or a setParams patch)
+ * @param previous - the current resolved record when resolving a patch
+ * @returns the frozen resolved record
+ */
+export declare function resolveSpringElectricalOptions(options: SpringElectricalOptions | undefined, previous?: ResolvedSpringElectricalOptions): ResolvedSpringElectricalOptions;
+/** The spring-electrical model (spec 7.20: K1 K2 K3 K5 per iteration on the exact tier, K1 K2 G1..G7 K5 on the grid tier; toScene once per batch). Stages: the union list of PD-17. */
+export declare class SpringElectricalModel implements ForceModel<SpringElectricalOptions, SpringElectricalStats> {
+    /** The model kind of spec 7.19. */
+    readonly kind = "springElectrical";
+    /** The stage names in dispatch order (the `upTo` vocabulary of recordIteration and debugRunStages). */
+    readonly stages: typeof SE_STAGES;
+    /** Fa2Params: the per-iteration uniform block (the simulation writes the shared fields into it). */
+    readonly params: UniformBlock;
+    /** Fa2State: the state header block. */
+    readonly state: UniformBlock;
+    /** Fa2Trace: one record per iteration of a batch. */
+    readonly trace: UniformBlock;
+    /** The resolved GPU-only tuning this model was created with (only `repulsion` / `exactMaxNodes` / `nearMax` / `extentFactor` matter here). */
+    readonly tuning: ResolvedLayoutTuning;
+    /** The option record the model holds: the constructor's record, replaced by onSetParams() ONLY (the query hooks never assign it). */
+    private current;
+    /** The resources of the last bind(), or null before the first. */
+    private resources;
+    /** The kernels and bind groups of the last bind(), or null before it (and for n === 0). */
+    private bound;
+    /** The grid of the load inputs() last resolved (null on the exact tier): onLoad() writes its frame, specs() lists its kernels. */
+    private nextGrid;
+    /** The K1-K5 compute pass of the batch being recorded, keyed by CommandBatch.id; null between batches. */
+    private openPass;
+    /**
+     * Creates the model for one simulation.
+     * @param tuning - the resolved GPU-only tuning
+     * @param resolved - the resolved option record at creation
+     */
+    constructor(tuning: ResolvedLayoutTuning, resolved: ResolvedSpringElectricalOptions);
+    /**
+     * force 12n (zeroed), velocity 12n (zeroed: every load() starts at rest, `allocate()` / `clearKept()` honour
+     * `zero`), the 256-byte FillParams uniform buffer, 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.
+     * @param n - the node count
+     * @param dim - the layout dimension (the arrays are stride 3 in both; the grid's geometry differs)
+     * @returns the model-owned buffer specs
+     */
+    buffers(n: number, dim: 2 | 3): readonly BufferSpec[];
+    /**
+     * { mass: 1 + degree / 3, weights: none } (PD-11): the preset has no mass or weight option, and K2 compiles
+     * HAS_WEIGHTS = false. No `fixed` (setFixed is the live API). 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 (its dimension picks the grid's geometry)
+     * @returns the per-load inputs
+     */
+    inputs(s: GraphSnapshot, options: SpringElectricalOptions): ModelInputs;
+    /**
+     * The constant SE_OVERRIDES (PD-1): no option changes a law, so setParams never recompiles.
+     * @param _options - an option record (unused)
+     * @returns the model's own override set
+     */
+    overrides(_options: SpringElectricalOptions): Overrides;
+    /**
+     * The six module specs of an override set in dispatch order -- K1, K2, K3, K5, toScene, fill -- each with 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` under SE_GRID_OVERRIDES) when the load inputs() last
+     * resolved is a grid load (the pipeline key carries no geometry).
+     * @param overrides - the merged override set (the model's plus USE_PERM / HAS_WEIGHTS)
+     * @param _subgroups - accepted for the ForceModel interface and unused (the composer picks the twin from caps)
+     * @returns the specs
+     */
+    specs(overrides: Overrides, _subgroups: boolean): readonly WgslModuleSpec[];
+    /**
+     * 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 on the exact tier or G1-G7 through
+     * RepulsionGrid on the grid tier (PD-18), K5, with the velocity in the `oldForce` slot of K3 / G7 / K5 (PD-2),
+     * toScene; 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).
+     * @param resources - the graph, the shared and model buffers, the ring and the cache
+     * @param overrides - the merged override set
+     */
+    bind(resources: ModelResources, overrides: Overrides): Promise<void>;
+    /**
+     * The Fa2Params values of one iteration: the shared fields, the FA2 fields at 0 (no centre gravity, PD-12; no
+     * FR temperature) and ngraph's five constants with `gravity` in `coulomb`.
+     * @param iteration - the global iteration index
+     * @param options - the simulation's current option record
+     * @returns the uniform values
+     */
+    paramsFor(iteration: number, options: SpringElectricalOptions): UniformValues;
+    /**
+     * Records one iteration into the batch, stopping after stage `upTo` when given (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, K5 in the batch's ONE compute pass, then toScene in a second pass that ends it. The grid
+     * tier (PD-16): the passes `se-k1` (K1), `se-attraction` (K2's tiers) and `se-grid` (G1-G7, K5) per iteration,
+     * then `se-to-scene`. With n === 0 nothing is recorded; a call before bind() completed is E_NOT_LOADED.
+     * @param batch - the batch being recorded
+     * @param slot - the UniformRing slot holding this iteration's Fa2Params
+     * @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: CommandBatch, slot: number, tier: "exact" | "grid", upTo?: string): void;
+    /**
+     * The grid tier's iteration (PD-16): three compute passes before toScene; no K4.
+     * @param batch - the batch being recorded
+     * @param bound - the bound model
+     * @param offset - the Fa2Params dynamic offset of the iteration
+     * @param stop - the SE_STAGES index to stop after
+     */
+    private recordGridIteration;
+    /**
+     * 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
+     */
+    private recordK2;
+    /**
+     * 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
+     */
+    private recordToScene;
+    /**
+     * kineticEnergy = 0 and temperature = 0 in the header (the velocities start at 0 through the buffer's `zero`);
+     * on a grid load the frame of the first build (K1 folds nothing on the first iteration).
+     * @param state - the state writer of the simulation
+     */
+    onLoad(state: StateWriter): void;
+    /**
+     * Nothing: the velocities carry on (ngraph has no reheat; a drag lands in the next batch through the override
+     * list, spec 7.12).
+     * @param _state - the state writer of the simulation (unused)
+     */
+    onReheat(_state: StateWriter): void;
+    /**
+     * Replaces the record with the patch applied (every option is a numeric tweak; nothing recompiles, no reset).
+     * @param patch - the setParams patch
+     * @param _state - the state writer of the simulation (unused)
+     */
+    onSetParams(patch: Partial<SpringElectricalOptions>, _state: StateWriter): void;
+    /**
+     * Decodes the state header and the k trace records of a completed batch into SpringElectricalStats:
+     * `repulsionTier` is the bound tier, the grid fields are the header's on the grid tier and null on the exact
+     * tier; msPerIteration null (the simulation owns the clock); `kineticEnergy` is the last folded value (one
+     * iteration behind the last integrate, PD-4).
+     * @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
+     */
+    readStats(state: DataView, trace: DataView): SpringElectricalStats;
+    /**
+     * The resources of the last bind(), or E_NOT_LOADED before it.
+     * @returns the resources
+     */
+    private requireResources;
+    /**
+     * The index of a stage name in SE_STAGES, or E_INVALID_ARGUMENT.
+     * @param upTo - the stage name
+     * @returns its index
+     */
+    private stageIndex;
+    /** Releases the grid stage's lease and the bind groups (the simulation calls it from dispose() once every in-flight batch has settled). */
+    dispose(): void;
+    /** Drops the bind groups of the previous bind() (the buffers changed), releases the grid stage's lease and forgets the pass of a batch recorded before the rebind. */
+    private dropBound;
+}
+/**
+ * Spec 3.3 createSpringElectrical, verbatim: a GpuLayoutSimulation running ngraph's spring-electrical model on the
+ * exact or the grid repulsion tier (spec 7.8) with ngraph's defaults (spec 7.20) and the GPU-only tuning of
+ * GpuLayoutTuning.
+ * @param ctx - the context (E_DISPOSED / E_DEVICE_LOST through assertReady)
+ * @param options - the spring-electrical options and the GPU-only tuning knobs in one record
+ * @returns the simulation in state "created"; load() next
+ */
+export declare function createSpringElectrical(ctx: GpuContext, options?: SpringElectricalOptions & GpuLayoutTuning): GpuLayoutSimulation<SpringElectricalOptions, SpringElectricalStats>;
+export {};
+//# sourceMappingURL=spring-electrical.d.ts.map

package/dist/src/layouts/spring-electrical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spring-electrical.d.ts","sourceRoot":"","sources":["../../../src/layouts/spring-electrical.ts"],"names":[],"mappings":"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"}