@graphty/webgpu-graph-algorithms 0.4.1 → 0.5.1

package/dist/src/layouts/model-common.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The option and value helpers every force model's resolver and stats decoder share (PD-7): moved verbatim from
+ * src/layouts/forceatlas2.ts (P3-T2) so the Fruchterman-Reingold and spring-electrical models of P5 neither copy
+ * them nor import a sibling model. Layout zone; imports errors.ts only.
+ */
+import { WebGpuGraphError } from "../errors.js";
+import { type UniformValues } from "../kernel/struct-block.js";
+/** An override record as the kernel layer takes it. */
+export type Overrides = Readonly<Record<string, number | boolean>>;
+/** Bytes of the stride-3 f32 force arrays per node. */
+export declare const FORCE_BYTES_PER_NODE = 12;
+/** The name of the model-owned FillParams buffer (a BufferSpec, reached through ModelResources.buffer). */
+export declare const FILL_PARAMS_BUFFER = "fillParams";
+/**
+ * A short, safe rendering of an argument value for error messages (never String() on an object).
+ * @param value - the value
+ * @returns the rendering
+ */
+export declare function describeValue(value: unknown): string;
+/**
+ * The E_INVALID_ARGUMENT error of an option check (contract 3.1: { argument, value, expected }).
+ * @param argument - the option name
+ * @param value - the value given
+ * @param expected - what was expected
+ * @returns the error (not thrown here)
+ */
+export declare function invalid(argument: string, value: unknown, expected: string): WebGpuGraphError;
+/**
+ * A numeric option: the given value when defined, else the fallback; validated by `check` (the value is checked as
+ * `unknown` so a JS caller's string or object is E_INVALID_ARGUMENT too).
+ * @param name - the option name
+ * @param given - the value given (undefined = absent)
+ * @param fallback - the previous record's value or the default
+ * @param check - the range predicate over a finite number
+ * @param expected - the range in words (the error message)
+ * @returns the value
+ */
+export declare function pickNumber(name: string, given: number | undefined, fallback: number, check: (value: number) => boolean, expected: string): number;
+/**
+ * A boolean option: the given value when defined, else the fallback; a non-boolean is E_INVALID_ARGUMENT.
+ * @param name - the option name
+ * @param given - the value given (undefined = absent)
+ * @param fallback - the previous record's value or the default
+ * @returns the value
+ */
+export declare function pickBoolean(name: string, given: boolean | undefined, fallback: boolean): boolean;
+/**
+ * The layout dimension: 2 or 3.
+ * @param given - the value given (undefined = absent)
+ * @param fallback - the previous record's value or the default
+ * @returns 2 or 3
+ */
+export declare function pickDim(given: 2 | 3 | undefined, fallback: 2 | 3): 2 | 3;
+/**
+ * The scene-unit center: an array-like of 2 (z = 0) or 3 finite numbers.
+ * @param given - the value given (undefined = absent)
+ * @param fallback - the previous record's value or the default
+ * @returns the three components
+ */
+export declare function pickCenter(given: ArrayLike<number> | undefined, fallback: readonly [number, number, number]): readonly [number, number, number];
+/**
+ * The seed: a finite number, or null (unseeded; 0 keeps the port's "0 = unseeded" quirk through the Lcg).
+ * @param given - the value given (undefined = absent)
+ * @param fallback - the previous record's value or the default
+ * @returns the seed or null
+ */
+export declare function pickSeed(given: number | null | undefined, fallback: number | null): number | null;
+/**
+ * Integer >= 1.
+ * @param value - a finite number
+ * @returns whether it is a positive integer
+ */
+export declare function isPositiveInteger(value: number): boolean;
+/**
+ * The u32 word written into Fa2Params.seed: 0 for null, else floor(|seed|) mod 2^32.
+ * @param seed - the resolved seed
+ * @returns the u32 value
+ */
+export declare function seedWord(seed: number | null): number;
+/**
+ * A scalar field of a block's read() result.
+ * @param values - the values read
+ * @param name - the field name
+ * @returns the number
+ */
+export declare function scalar(values: UniformValues, name: string): number;
+/**
+ * A vector field of a block's read() result.
+ * @param values - the values read
+ * @param name - the field name
+ * @returns the components
+ */
+export declare function vector(values: UniformValues, name: string): readonly number[];
+/**
+ * The override record a kernel gets: its defaults overlaid with the values present in the merged set (contract 3.9:
+ * a name a spec does not declare is rejected at compose time, so nothing else is passed through).
+ * @param merged - the merged override set of the model (plus USE_PERM / HAS_WEIGHTS from the simulation)
+ * @param defaults - the kernel's accepted names with their defaults
+ * @returns the kernel's override record, every accepted name explicit
+ */
+export declare function subset(merged: Overrides, defaults: Overrides): Overrides;
+//# sourceMappingURL=model-common.d.ts.map

package/dist/src/layouts/model-common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-common.d.ts","sourceRoot":"","sources":["../../../src/layouts/model-common.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D,uDAAuD;AACvD,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;AAEnE,uDAAuD;AACvD,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,2GAA2G;AAC3G,eAAO,MAAM,kBAAkB,eAAe,CAAC;AAK/C;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAcpD;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAM5F;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACtB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,EACjC,QAAQ,EAAE,MAAM,GACjB,MAAM,CAMR;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,SAAS,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAMhG;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAMxE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACtB,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,SAAS,EACpC,QAAQ,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAC5C,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CA2BnC;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CASjG;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAKpD;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMlE;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAM7E;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,GAAG,SAAS,CAMxE"}

package/dist/src/layouts/model-common.js

@@ -0,0 +1,198 @@
+/**
+ * The option and value helpers every force model's resolver and stats decoder share (PD-7): moved verbatim from
+ * src/layouts/forceatlas2.ts (P3-T2) so the Fruchterman-Reingold and spring-electrical models of P5 neither copy
+ * them nor import a sibling model. Layout zone; imports errors.ts only.
+ */
+import { WebGpuGraphError } from "../errors.js";
+/** Bytes of the stride-3 f32 force arrays per node. */
+export const FORCE_BYTES_PER_NODE = 12;
+/** The name of the model-owned FillParams buffer (a BufferSpec, reached through ModelResources.buffer). */
+export const FILL_PARAMS_BUFFER = "fillParams";
+/** 2^32, the modulus of the u32 seed word (computed with `%`, never a bitwise operator). */
+const U32_MODULUS = 4294967296;
+/**
+ * A short, safe rendering of an argument value for error messages (never String() on an object).
+ * @param value - the value
+ * @returns the rendering
+ */
+export function describeValue(value) {
+    if (value === null) {
+        return "null";
+    }
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "string") {
+        return String(value);
+    }
+    if (typeof value === "undefined") {
+        return "undefined";
+    }
+    if (typeof value === "object" && "length" in value && typeof value.length === "number") {
+        return `[${value.length} values]`;
+    }
+    return typeof value;
+}
+/**
+ * The E_INVALID_ARGUMENT error of an option check (contract 3.1: { argument, value, expected }).
+ * @param argument - the option name
+ * @param value - the value given
+ * @param expected - what was expected
+ * @returns the error (not thrown here)
+ */
+export function invalid(argument, value, expected) {
+    return new WebGpuGraphError("E_INVALID_ARGUMENT", `${argument} must be ${expected}; got ${describeValue(value)}`, {
+        argument,
+        value,
+        expected,
+    });
+}
+/**
+ * A numeric option: the given value when defined, else the fallback; validated by `check` (the value is checked as
+ * `unknown` so a JS caller's string or object is E_INVALID_ARGUMENT too).
+ * @param name - the option name
+ * @param given - the value given (undefined = absent)
+ * @param fallback - the previous record's value or the default
+ * @param check - the range predicate over a finite number
+ * @param expected - the range in words (the error message)
+ * @returns the value
+ */
+export function pickNumber(name, given, fallback, check, expected) {
+    const value = given === undefined ? fallback : given;
+    if (typeof value !== "number" || !Number.isFinite(value) || !check(value)) {
+        throw invalid(name, value, expected);
+    }
+    return value;
+}
+/**
+ * A boolean option: the given value when defined, else the fallback; a non-boolean is E_INVALID_ARGUMENT.
+ * @param name - the option name
+ * @param given - the value given (undefined = absent)
+ * @param fallback - the previous record's value or the default
+ * @returns the value
+ */
+export function pickBoolean(name, given, fallback) {
+    const value = given === undefined ? fallback : given;
+    if (typeof value !== "boolean") {
+        throw invalid(name, value, "a boolean");
+    }
+    return value;
+}
+/**
+ * The layout dimension: 2 or 3.
+ * @param given - the value given (undefined = absent)
+ * @param fallback - the previous record's value or the default
+ * @returns 2 or 3
+ */
+export function pickDim(given, fallback) {
+    const value = given === undefined ? fallback : given;
+    if (value !== 2 && value !== 3) {
+        throw invalid("dim", value, "2 or 3");
+    }
+    return value;
+}
+/**
+ * The scene-unit center: an array-like of 2 (z = 0) or 3 finite numbers.
+ * @param given - the value given (undefined = absent)
+ * @param fallback - the previous record's value or the default
+ * @returns the three components
+ */
+export function pickCenter(given, fallback) {
+    if (given === undefined) {
+        return fallback;
+    }
+    const expected = "an array of 2 or 3 finite numbers";
+    const value = given;
+    if (typeof value !== "object" || value === null || !("length" in value)) {
+        throw invalid("center", given, expected);
+    }
+    const { length } = value;
+    if (length !== 2 && length !== 3) {
+        throw invalid("center", given, expected);
+    }
+    const x = given[0];
+    const y = given[1];
+    const z = length === 3 ? given[2] : 0;
+    if (typeof x !== "number" ||
+        typeof y !== "number" ||
+        typeof z !== "number" ||
+        !Number.isFinite(x) ||
+        !Number.isFinite(y) ||
+        !Number.isFinite(z)) {
+        throw invalid("center", given, expected);
+    }
+    return [x, y, z];
+}
+/**
+ * The seed: a finite number, or null (unseeded; 0 keeps the port's "0 = unseeded" quirk through the Lcg).
+ * @param given - the value given (undefined = absent)
+ * @param fallback - the previous record's value or the default
+ * @returns the seed or null
+ */
+export function pickSeed(given, fallback) {
+    if (given === undefined) {
+        return fallback;
+    }
+    const value = given;
+    if (value !== null && (typeof value !== "number" || !Number.isFinite(value))) {
+        throw invalid("seed", given, "a finite number or null");
+    }
+    return value;
+}
+/**
+ * Integer >= 1.
+ * @param value - a finite number
+ * @returns whether it is a positive integer
+ */
+export function isPositiveInteger(value) {
+    return Number.isInteger(value) && value >= 1;
+}
+/**
+ * The u32 word written into Fa2Params.seed: 0 for null, else floor(|seed|) mod 2^32.
+ * @param seed - the resolved seed
+ * @returns the u32 value
+ */
+export function seedWord(seed) {
+    if (seed === null) {
+        return 0;
+    }
+    return Math.floor(Math.abs(seed)) % U32_MODULUS;
+}
+/**
+ * A scalar field of a block's read() result.
+ * @param values - the values read
+ * @param name - the field name
+ * @returns the number
+ */
+export function scalar(values, name) {
+    const value = values[name];
+    if (typeof value !== "number") {
+        throw invalid(name, value, "a scalar field");
+    }
+    return value;
+}
+/**
+ * A vector field of a block's read() result.
+ * @param values - the values read
+ * @param name - the field name
+ * @returns the components
+ */
+export function vector(values, name) {
+    const value = values[name];
+    if (typeof value === "number") {
+        throw invalid(name, value, "a vector field");
+    }
+    return value;
+}
+/**
+ * The override record a kernel gets: its defaults overlaid with the values present in the merged set (contract 3.9:
+ * a name a spec does not declare is rejected at compose time, so nothing else is passed through).
+ * @param merged - the merged override set of the model (plus USE_PERM / HAS_WEIGHTS from the simulation)
+ * @param defaults - the kernel's accepted names with their defaults
+ * @returns the kernel's override record, every accepted name explicit
+ */
+export function subset(merged, defaults) {
+    const out = {};
+    for (const name of Object.keys(defaults)) {
+        out[name] = name in merged ? merged[name] : defaults[name];
+    }
+    return out;
+}
+//# sourceMappingURL=model-common.js.map

package/dist/src/layouts/model-common.js.map

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

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

@@ -0,0 +1,179 @@
+/**
+ * The spring-electrical preset on the exact repulsion tier (spec 7.20 "the preset"; 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), 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: 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; `repulsion: "grid"` is E_UNSUPPORTED at load() (the simulation's tier rule).
+ */
+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 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; toScene once per batch). Stages: ["K1", "K2", "K3", "K5", "toScene"]. */
+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: readonly ["K1", "K2", "K3", "K5", "toScene"];
+    /** 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 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`) and the 256-byte FillParams uniform buffer. 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)
+     * @returns the three 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). The tier rule is the simulation's (load() throws
+     * E_UNSUPPORTED for the grid tier before calling this).
+     * @param s - the snapshot being loaded
+     * @param _options - the simulation's current option record (unused: nothing in it affects the inputs)
+     * @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.
+     * @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 (or the fill of
+     * force when arcCount === 0), K3 and K5 with the velocity in their `oldForce` slot (PD-2), toScene; writes the
+     * FillParams { count: 3n, value: 0, mode: 0 } into the model's uniform buffer. With n === 0 nothing is bound.
+     * @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: K1, K2 (or the fill of force when arcCount === 0), K3, K5 in the batch's
+     * ONE K1-K5 compute pass, then toScene in a second pass that ends it, stopping after stage `upTo` when given.
+     * 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 - "exact" (the grid tier is E_UNSUPPORTED; the simulation never passes "grid")
+     * @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;
+    /**
+     * kineticEnergy = 0 and temperature = 0 in the header (the velocities start at 0 through the buffer's `zero`).
+     * @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: the exact
+     * tier with null grid fields; 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;
+    /** Drops the bind groups of the previous bind() (the buffers changed) 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 repulsion tier 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>;
+//# 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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"}