@graphty/webgpu-graph-algorithms 0.4.1 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/webgpu-graph-algorithms",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "WebGPU-accelerated graph algorithms and layouts over the @graphty/graph-format snapshot, for Node (Dawn) and browsers",
   "author": "Adam Powers <apowers@ato.ms>",
   "type": "module",
@@ -60,7 +60,7 @@
   "homepage": "https://github.com/graphty-org/graphty-monorepo/tree/master/webgpu-graph-algorithms#readme",
   "dependencies": {
     "@webgpu/types": "^0.1.72",
-    "@graphty/graph-format": "^1.0.1"
+    "@graphty/graph-format": "^1.0.2"
   },
   "peerDependencies": {
     "@graphty/algorithms": "^1.0.0",
@@ -84,13 +84,16 @@
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
     "fast-check": "^4.2.0",
+    "ngraph.forcelayout": "^3.3.1",
+    "ngraph.graph": "^20.0.1",
     "playwright": "^1.54.1",
     "tsx": "^4.20.3",
     "typescript": "^5.9.3",
     "vite": "^7.0.5",
     "vitest": "^3.2.4",
     "webgpu": "0.4.0",
-    "@graphty/layout": "^1.7.0"
+    "@graphty/layout": "^1.8.0",
+    "@graphty/algorithms": "^1.8.1"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/src/accelerator.ts

@@ -1,14 +1,15 @@
 /**
  * createAccelerator (spec 3.3, 9; contract 3.14): the injectable object that satisfies the CPU packages'
- * AlgorithmAccelerator and LayoutAccelerator interfaces (spec 9.2, 9.3; D27). Since W1b `LayoutAccelerator` is
- * the REAL `@graphty/layout` declaration, `import type`d by src/types/accelerator.ts; the AlgorithmAccelerator half
- * is still satisfied STRUCTURALLY against that file's mirror until M8a gives it something real. It carries P3's
- * `forceAtlas2`, `release` and `dispose` and P7's seven
- * algorithm members (spec 8.2, 8.3; M8b-T8, PD-14) and nothing else: the CPU-side dispatchers (`accelerated()`,
- * `createSimulation()`) test `acc.betweennessCentrality !== undefined` and route to the CPU when the member is
- * absent (spec 2.4 row "method missing"), so a method the GPU does not implement must not exist here -- never a
- * throwing stub. The remaining algorithm members arrive one per shipped algorithm from P8; `fruchtermanReingold` /
- * `springElectrical` with P5.
+ * AlgorithmAccelerator and LayoutAccelerator interfaces (spec 9.2, 9.3). Both are the REAL declarations,
+ * `LayoutAccelerator` from `@graphty/layout` (W1b, layout half) and `AlgorithmAccelerator` from
+ * `@graphty/algorithms` (W1b, algorithms half), `import type`d by src/types/accelerator.ts, so the object built
+ * here is checked against the CPU packages' own contracts. It carries P3's `forceAtlas2`, `release` and `dispose`,
+ * P5's `fruchtermanReingold` and `springElectrical` (the two other layout members of spec 9.3, landed together once
+ * both models were green, P5 PD-19) and P7's seven algorithm members (spec 8.2, 8.3; M8b-T8, PD-14) and nothing
+ * else: the CPU-side dispatchers (`accelerated()`, `createSimulation()`) test `acc.betweennessCentrality !== undefined`
+ * / `acc.fruchtermanReingold !== undefined` and route to the CPU when the member is absent (spec 2.4 row "method
+ * missing"), so a method the GPU does not implement must not exist here -- never a throwing stub. The remaining
+ * algorithm members arrive one per shipped algorithm from P8.
  */
 
 import { type F32, type F64, type GraphSnapshot } from "@graphty/graph-format";
@@ -18,6 +19,8 @@ import { pageRank, personalizedPageRank } from "./algorithms/pagerank.js";
 import { eigenvectorCentrality, hits, katzCentrality } from "./algorithms/spectral.js";
 import { type GpuContext } from "./context.js";
 import { createForceAtlas2 } from "./layouts/forceatlas2.js";
+import { createFruchtermanReingold } from "./layouts/fruchterman-reingold.js";
+import { createSpringElectrical } from "./layouts/spring-electrical.js";
 import { type AcceleratorOptions, type GpuAccelerator } from "./types/accelerator.js";
 import {
     type ComponentsOptions,
@@ -30,8 +33,18 @@ import {
     type KatzOptions,
     type PageRankOptions,
 } from "./types/algorithms.js";
-import { type ForceAtlas2Stats, type GpuLayoutSimulation, type GpuLayoutTuning } from "./types/layout.js";
-import { type ForceAtlas2Options } from "./types/options.js";
+import {
+    type ForceAtlas2Stats,
+    type FruchtermanReingoldStats,
+    type GpuLayoutSimulation,
+    type GpuLayoutTuning,
+    type SpringElectricalStats,
+} from "./types/layout.js";
+import {
+    type ForceAtlas2Options,
+    type FruchtermanReingoldOptions,
+    type SpringElectricalOptions,
+} from "./types/options.js";
 
 /** The `algorithms` record of AcceleratorOptions (spec 3.3), named for the copy helpers. */
 type AlgorithmDefaults = NonNullable<AcceleratorOptions["algorithms"]>;
@@ -90,7 +103,8 @@ function freezeOptions(options: AcceleratorOptions | undefined): Readonly<Accele
 
 /**
  * Spec 3.3 createAccelerator, verbatim: the object implementing AlgorithmAccelerator & LayoutAccelerator
- * structurally; P3's forceAtlas2, release and dispose plus P7's seven algorithm members, each a delegation to
+ * structurally; P3's forceAtlas2, release and dispose, P5's fruchtermanReingold and springElectrical (the same
+ * `{ ...o, ...options.layout }` shape as forceAtlas2) plus P7's seven algorithm members, each a delegation to
  * its algorithm with `ctx.assertReady()` first. The accelerator's algorithm defaults are not consulted by any of
  * them: only `betweenness` has any, and it belongs to P9. One per call (the app creates one and injects
  * it, spec 2.4); `kind` is "webgpu"; `options` is a frozen deep copy; `forceAtlas2(o)` is
@@ -100,8 +114,9 @@ function freezeOptions(options: AcceleratorOptions | undefined): Readonly<Accele
  * @param ctx - the context every simulation the accelerator creates runs on
  * @param options - GPU-only defaults inherited by every simulation (`layout`) and, from P9, the algorithm defaults
  * @returns the injectable accelerator
- * @throws E_DISPOSED / E_DEVICE_LOST from `ctx.assertReady()` (here and inside `forceAtlas2()`); `forceAtlas2()`
- *   also throws what createForceAtlas2 throws (E_UNSUPPORTED for `nodeSize`, E_INVALID_ARGUMENT for a bad range)
+ * @throws E_DISPOSED / E_DEVICE_LOST from `ctx.assertReady()` (here and inside every creating member); `forceAtlas2()`
+ *   also throws what createForceAtlas2 throws (E_UNSUPPORTED for `nodeSize`, E_INVALID_ARGUMENT for a bad range), and
+ *   `fruchtermanReingold()` / `springElectrical()` what their factories throw (E_INVALID_ARGUMENT for a bad range)
  */
 export function createAccelerator(ctx: GpuContext, options?: AcceleratorOptions): GpuAccelerator {
     ctx.assertReady();
@@ -119,6 +134,26 @@ export function createAccelerator(ctx: GpuContext, options?: AcceleratorOptions)
             ctx.assertReady();
             return createForceAtlas2(ctx, { ...o, ...frozen.layout });
         },
+        /**
+         * The Fruchterman-Reingold simulation with this accelerator's layout tuning (spec 3.3, 7.20; P5).
+         * @param o - the CPU option type (spec 9.3 FruchtermanReingoldOptions); GPU tuning keys come from `options.layout`
+         * @returns a fresh simulation in state "created"
+         */
+        fruchtermanReingold(
+            o?: FruchtermanReingoldOptions,
+        ): GpuLayoutSimulation<FruchtermanReingoldOptions, FruchtermanReingoldStats> {
+            ctx.assertReady();
+            return createFruchtermanReingold(ctx, { ...o, ...frozen.layout });
+        },
+        /**
+         * The spring-electrical preset with this accelerator's layout tuning (spec 3.3, 7.20; P5).
+         * @param o - the CPU option type (spec 9.3 SpringElectricalOptions, ngraph's names)
+         * @returns a fresh simulation in state "created"
+         */
+        springElectrical(o?: SpringElectricalOptions): GpuLayoutSimulation<SpringElectricalOptions, SpringElectricalStats> {
+            ctx.assertReady();
+            return createSpringElectrical(ctx, { ...o, ...frozen.layout });
+        },
         /**
          * PageRank on the device (spec 8.2; contract 3.14).
          * @param gs - the snapshot

package/src/constants.ts

@@ -114,3 +114,73 @@ export const FA2_DISTANCE_FLOOR_SQ = 0.0001;
 export const FA2_COINCIDENT_SQ = 1e-8;
 /** Bits of Fa2Params.flags (contract 4.4). */
 export const FA2_FLAG_FIRST = 1;
+/** Fa2Params.flags bit: the Fruchterman-Reingold temperature is the adaptive one in the state block, not the uniform's (the `cooling: "adaptive"` option). */
+export const FA2_FLAG_ADAPTIVE = 2;
+/** The Fruchterman-Reingold loop's starting temperature (spec 7.20; `layout/src/simulation/fruchterman-reingold.ts:30`). */
+export const FR_START_TEMPERATURE = 0.1;
+/** The reheat point of spec 7.20: the temperature index a reheat restarts at, as a fraction of `iterations`. */
+export const FR_REHEAT_FRACTION = 0.7;
+/** Adaptive cooling (Yifan Hu 2005, section 3.2): the temperature is multiplied by this when the force energy rose, divided by it after FR_COOLING_PATIENCE consecutive falls. */
+export const FR_COOLING_STEP = 0.9;
+/** Adaptive cooling: consecutive iterations of falling energy before the temperature grows. */
+export const FR_COOLING_PATIENCE = 5;
+/** Adaptive cooling: the iteration budget when `iterations` is not given (the schedule no longer needs one; this is the cap on a run that never settles). */
+export const FR_ADAPTIVE_MAX_ITERATIONS = 10_000;
+/** Fruchterman-Reingold defaults (spec 7.20, 9.3; the CPU simulation's, `layout/src/simulation/fruchterman-reingold.ts:32`): `k` null = `1 / sqrt(n)`. */
+export const FR_DEFAULTS: Readonly<{
+    k: null;
+    iterations: 50;
+    fixed: null;
+    dim: 2;
+    scale: 1;
+    settleThreshold: 0.001;
+    settleWindow: 10;
+    iterationsPerStep: 1;
+    maxInFlight: 2;
+    cooling: "linear";
+}> = Object.freeze({
+    k: null,
+    iterations: 50,
+    fixed: null,
+    dim: 2,
+    scale: 1,
+    settleThreshold: 0.001,
+    settleWindow: 10,
+    iterationsPerStep: 1,
+    maxInFlight: 2,
+    cooling: "linear",
+});
+/**
+ * Spring-electrical size scaling: when `gravity` or `springCoefficient` is left to its default, ngraph's constant is
+ * multiplied by min(1, SE_SCALE_REFERENCE_NODES / n). ngraph's values were tuned for graphs of a few hundred nodes;
+ * on tens of thousands the per-node forces are so large that every node moves at the unit speed clamp and the layout
+ * never comes to rest (measured on the 58k-node Brightkite graph: 3,350 iterations to the settle rule with the
+ * kinetic energy still at the clamp; a uniform 1/1000 factor settled in 1,000 with the energy decayed 25x).
+ */
+export const SE_SCALE_REFERENCE_NODES = 300;
+/** Spring-electrical defaults: ngraph.forcelayout 3.3.1's (`lib/createPhysicsSimulator.js:29,34,40,54,59`; spec 7.20), plus the shared simulation defaults. `gravity` is ngraph's Coulomb constant: negative repels. */
+export const SE_DEFAULTS: Readonly<{
+    springLength: 10;
+    springCoefficient: 0.8;
+    gravity: -12;
+    dragCoefficient: 0.9;
+    timeStep: 0.5;
+    dim: 2;
+    scale: 1;
+    settleThreshold: 0.001;
+    settleWindow: 10;
+    iterationsPerStep: 1;
+    maxInFlight: 2;
+}> = Object.freeze({
+    springLength: 10,
+    springCoefficient: 0.8,
+    gravity: -12,
+    dragCoefficient: 0.9,
+    timeStep: 0.5,
+    dim: 2,
+    scale: 1,
+    settleThreshold: 0.001,
+    settleWindow: 10,
+    iterationsPerStep: 1,
+    maxInFlight: 2,
+});

package/src/index.ts

@@ -7,20 +7,24 @@
  * ForceSimulation, ForceAtlas2Model: tests import them from their files). P0: the error class, the constants and
  * isSoftwareAdapter. P1 adds GpuContext and degree (values) and the context / run / profiler types. P2 adds nothing
  * (Lease, CommandBatch, UniformRing are internal). P3 adds the layout factory, the accelerator, the two default
- * tables, the seeder and the layout / accelerator types. test/index.test.ts pins the value list and
- * test/types/public-api.test-d.ts the type list; P4+ extends both. This comment must never spell the internal
+ * tables, the seeder and the layout / accelerator types. P5 adds the two factories, the two default tables and the
+ * two stats records. test/index.test.ts pins the value list and test/types/public-api.test-d.ts the type list; P4+
+ * extends both. This comment must never spell the internal
  * JSDoc tag: it is the leading comment of the first export statement, and stripInternal would drop that statement
  * from the emitted declarations.
  */
 
-// ==================== constants and errors (P0; FA2_DEFAULTS / LAYOUT_TUNING_DEFAULTS public from P3)
+// ==================== constants and errors (P0; FA2_DEFAULTS / LAYOUT_TUNING_DEFAULTS public from P3, FR_DEFAULTS /
+// SE_DEFAULTS from P5)
 export {
     ARC_WINDOW_ALIGN,
     EXACT_MAX_NODES,
     FA2_DEFAULTS,
+    FR_DEFAULTS,
     LAYOUT_TUNING_DEFAULTS,
     MAX_1D_ITEMS,
     MAX_WORKGROUPS_PER_DIM,
+    SE_DEFAULTS,
     STORAGE_ALIGN,
     WORKGROUP_SIZE,
 } from "./constants.js";
@@ -45,24 +49,27 @@ export { connectedComponents } from "./algorithms/components.js";
 export { pageRank, personalizedPageRank } from "./algorithms/pagerank.js";
 export { eigenvectorCentrality, hits, katzCentrality } from "./algorithms/spectral.js";
 
-// ==================== layouts and the accelerator (P3)
+// ==================== layouts and the accelerator (P3; the two P5 factories)
 export { createAccelerator } from "./accelerator.js";
 export { createForceAtlas2 } from "./layouts/forceatlas2.js";
+export { createFruchtermanReingold } from "./layouts/fruchterman-reingold.js";
 export { seedPositions } from "./layouts/seed.js";
+export { createSpringElectrical } from "./layouts/spring-electrical.js";
 
-// ==================== types: the accelerator surface, layout's re-exported declarations (spec 9.3; W1b) and the
-// @graphty/algorithms mirrors (spec 9.2; D27, until M8a)
+// ==================== types: the accelerator surface and the re-exported declarations of @graphty/layout (spec 9.3)
+// and @graphty/algorithms (spec 9.2), both `import type` since W1b (D27)
 export type {
     AcceleratorOptions,
     AlgorithmAccelerator,
     ApspResultLike,
     BellmanFordResultLike,
+    BetweennessAcceleratorOptions,
     BfsResultLike,
     CommunityResultLike,
     CorenessResultLike,
-    CpuAlgorithmOptions,
     EdgeScoresResultLike,
     GpuAccelerator,
+    HitsOptionsLike,
     HitsResultLike,
     LabelResultLike,
     LayoutAccelerator,
@@ -100,14 +107,18 @@ export type {
     RaisableLimit,
 } from "./types/context.js";
 
-// ==================== types: layouts (P3)
+// ==================== types: layouts (P3; the P5 stats and trace records)
 export type {
     ForceAtlas2Stats,
     ForceAtlas2TraceRecord,
+    FruchtermanReingoldStats,
+    FruchtermanReingoldTraceRecord,
     GpuLayoutSimulation,
     GpuLayoutTuning,
     LayoutStatsBase,
     RunOptions,
+    SpringElectricalStats,
+    SpringElectricalTraceRecord,
 } from "./types/layout.js";
 export type {
     CommonLayoutOptions,

package/src/kernel/prelude.ts

@@ -15,7 +15,10 @@ import {
     FA2_COINCIDENT_SQ,
     FA2_DISTANCE_FLOOR,
     FA2_DISTANCE_FLOOR_SQ,
+    FA2_FLAG_ADAPTIVE,
     FA2_FLAG_FIRST,
+    FR_COOLING_PATIENCE,
+    FR_COOLING_STEP,
     MAX_WORKGROUPS_PER_DIM,
     U32_MAX,
     WORKGROUP_SIZE,
@@ -49,6 +52,9 @@ const FA2_DIST_FLOOR: f32 = ${wgslF32Literal(FA2_DISTANCE_FLOOR)};
 const FA2_DIST_FLOOR_SQ: f32 = ${wgslF32Literal(FA2_DISTANCE_FLOOR_SQ)};
 const FA2_COINCIDENT_SQ: f32 = ${wgslF32Literal(FA2_COINCIDENT_SQ)};
 const FA2_FLAG_FIRST: u32 = ${FA2_FLAG_FIRST}u;
+const FA2_FLAG_ADAPTIVE: u32 = ${FA2_FLAG_ADAPTIVE}u;
+const FR_COOLING_STEP: f32 = ${wgslF32Literal(FR_COOLING_STEP)};
+const FR_COOLING_PATIENCE: u32 = ${FR_COOLING_PATIENCE}u;
 const F32_MAX: f32 = 0x1.fffffep+127;
 override WG: u32 = ${WORKGROUP_SIZE}u;
 override USE_PERM: bool = false;

package/src/kernels.ts

@@ -101,7 +101,7 @@ export const FILL_PARAMS: UniformBlock = UniformBlock.define("FillParams", [
     ["pad0", "u32"],
 ]);
 
-/** `Fa2Params` (uniform, 96 B; spec 7.3): the per-iteration ForceAtlas2 parameters -- `n` @0, `dim` @4, `flags` @8 (bit 0 = FA2_FLAG_FIRST), `tierStart` @12, `tierEnd` @16, `iterationIndex` @20, `seed` @24, `nearMax` @28, `scalingRatio` @32, `gravity` @36, `jitterTolerance` @40, `scale` @44, `center` @48 (xyz, w 0), `settleThreshold` @64, `extentFactor` @68, `gridMax` @72, `levels` @76, `pad` @80 (reserved for the P4 GridSpec). */
+/** `Fa2Params` (uniform, 128 B; spec 7.3): the per-iteration ForceAtlas2 parameters -- `n` @0, `dim` @4, `flags` @8 (bit 0 = FA2_FLAG_FIRST), `tierStart` @12, `tierEnd` @16, `iterationIndex` @20, `seed` @24, `nearMax` @28, `scalingRatio` @32, `gravity` @36, `jitterTolerance` @40, `scale` @44, `center` @48 (xyz, w 0), `settleThreshold` @64, `extentFactor` @68, `gridMax` @72, `levels` @76, `pad` @80 (reserved for the P4 GridSpec); the P5 model fields (PD-3): `frK` @96 (the FR optimal distance), `temperature` @100 (the FR temperature of this iteration), `springLength` @104, `springCoefficient` @108, `coulomb` @112 (ngraph's `gravity`, negative repels), `dragCoefficient` @116, `timeStep` @120, `pad1` @124; 128 B. */
 export const FA2_PARAMS: UniformBlock = UniformBlock.define("Fa2Params", [
     ["n", "u32"],
     ["dim", "u32"],
@@ -121,9 +121,17 @@ export const FA2_PARAMS: UniformBlock = UniformBlock.define("Fa2Params", [
     ["gridMax", "u32"],
     ["levels", "u32"],
     ["pad", "vec4f"],
+    ["frK", "f32"],
+    ["temperature", "f32"],
+    ["springLength", "f32"],
+    ["springCoefficient", "f32"],
+    ["coulomb", "f32"],
+    ["dragCoefficient", "f32"],
+    ["timeStep", "f32"],
+    ["pad1", "f32"],
 ]);
 
-/** `Fa2State` (storage, padded to STATE_HEADER_BYTES = 256; spec 7.3): the device-resident controller state the finalize kernels write and the host reads back for stats -- `speed` @0, `speedEfficiency` @4, `swing` @8, `traction` @12, `centroid` @16, `rmsRadius` @32, `radius` @36, `meanDisplacement` @40, `iteration` @44, `min` @48, `max` @64, `gridMin` @80 (P4), `eps` @96 (P4), `settledCount` @100, `outsideGrid` @104 (P4), `maxCellOccupancy` @108 (P4), `reserved0` .. `reserved8` @112 .. @240. */
+/** `Fa2State` (storage, padded to STATE_HEADER_BYTES = 256; spec 7.3): the device-resident controller state the finalize kernels write and the host reads back for stats -- `speed` @0, `speedEfficiency` @4, `swing` @8, `traction` @12, `centroid` @16, `rmsRadius` @32, `radius` @36, `meanDisplacement` @40, `iteration` @44, `min` @48, `max` @64, `gridMin` @80 (P4), `eps` @96 (P4), `settledCount` @100, `outsideGrid` @104 (P4), `maxCellOccupancy` @108 (P4), `temperature` @112 (FR, written by K1 under STATS_MODE 1), `kineticEnergy` @116 (the preset, K1 under STATS_MODE 2), `reserved0` @120 (vec2f), `reserved1` .. `reserved8` @128 .. @240. */
 export const FA2_STATE: UniformBlock = UniformBlock.define(
     "Fa2State",
     [
@@ -143,7 +151,10 @@ export const FA2_STATE: UniformBlock = UniformBlock.define(
         ["settledCount", "u32"],
         ["outsideGrid", "u32"],
         ["maxCellOccupancy", "u32"],
-        ["reserved0", "vec4f"],
+        ["temperature", "f32"],
+        ["kineticEnergy", "f32"],
+        ["frEnergy", "f32"],
+        ["frProgress", "u32"],
         ["reserved1", "vec4f"],
         ["reserved2", "vec4f"],
         ["reserved3", "vec4f"],
@@ -156,7 +167,7 @@ export const FA2_STATE: UniformBlock = UniformBlock.define(
     { layout: "storage", padTo: STATE_HEADER_BYTES },
 );
 
-/** `Fa2Trace` (storage record, 32 B; spec 7.3): one per-iteration trace record -- `swing` @0, `traction` @4, `speed` @8, `speedEfficiency` @12 (written by K4), `meanDisplacement` @16, `settledCount` @20, `iteration` @24 (written by K1), `pad0` @28; the trace region is `array<Fa2Trace>` at byte offset STATE_HEADER_BYTES of the state buffer. */
+/** `Fa2Trace` (storage record, 32 B; spec 7.3): one per-iteration trace record -- `swing` @0, `traction` @4, `speed` @8, `speedEfficiency` @12 (written by K4), `meanDisplacement` @16, `settledCount` @20, `iteration` @24 (written by K1), `modelScalar` @28 (K1: the temperature under STATS_MODE 1, the kinetic energy under 2, 0 under 0); the trace region is `array<Fa2Trace>` at byte offset STATE_HEADER_BYTES of the state buffer. */
 export const FA2_TRACE: UniformBlock = UniformBlock.define(
     "Fa2Trace",
     [
@@ -167,7 +178,7 @@ export const FA2_TRACE: UniformBlock = UniformBlock.define(
         ["meanDisplacement", "f32"],
         ["settledCount", "u32"],
         ["iteration", "u32"],
-        ["pad0", "u32"],
+        ["modelScalar", "f32"],
     ],
     { layout: "storage" },
 );
@@ -335,7 +346,7 @@ const SEGMENTED_REDUCE: KernelEntry = {
     phase: "P2",
 };
 
-/** `fa2-stats-finalize` (K1, 3.10.1): the one-workgroup fold of the previous integrate's partials into the state block and the K1 half of the trace record; 3 storage bindings; calls the reduction helpers. */
+/** `fa2-stats-finalize` (K1, 3.10.1): the one-workgroup fold of the previous integrate's partials into the state block and the K1 half of the trace record; STATS_MODE 0 FA2 / 1 FR temperature / 2 kinetic energy (P5); 3 storage bindings; calls the reduction helpers. */
 const FA2_STATS_FINALIZE: KernelEntry = {
     id: "fa2-stats-finalize",
     body: fa2StatsFinalizeWgsl,
@@ -346,14 +357,14 @@ const FA2_STATS_FINALIZE: KernelEntry = {
         decl(1, 2, "T", "storage", "array<Fa2Trace>"),
         decl(2, 0, "P", "uniform", "Fa2Params"),
     ],
-    overrideDecls: [],
+    overrideDecls: [{ name: "STATS_MODE", type: "u32", default: 0 }],
     uniforms: [FA2_PARAMS, FA2_STATE, FA2_TRACE, FA2_PARTIAL],
     needs: ["subgroups"],
     snippetSlots: [],
     phase: "P3",
 };
 
-/** `fa2-attraction` (K2, 3.10.1): the thread-per-row attraction gather over the CSR rows (the first writer of `force` each iteration); LINLOG / DISTRIBUTED / TIER 0 plus the standard USE_PERM / HAS_WEIGHTS; 6 storage bindings. */
+/** `fa2-attraction` (K2, 3.10.1): the thread-per-row attraction gather over the CSR rows (the first writer of `force` each iteration); LINLOG / DISTRIBUTED / TIER 0 plus the standard USE_PERM / HAS_WEIGHTS; LAW 0 FA2 / 1 FR / 2 spring (P5); 6 storage bindings. */
 const FA2_ATTRACTION: KernelEntry = {
     id: "fa2-attraction",
     body: fa2AttractionWgsl,
@@ -367,6 +378,7 @@ const FA2_ATTRACTION: KernelEntry = {
         { name: "LINLOG", type: "bool", default: false },
         { name: "DISTRIBUTED", type: "bool", default: false },
         { name: "TIER", type: "u32", default: 0 },
+        { name: "LAW", type: "u32", default: 0 },
     ],
     uniforms: [FA2_PARAMS],
     needs: [],
@@ -374,7 +386,7 @@ const FA2_ATTRACTION: KernelEntry = {
     phase: "P3",
 };
 
-/** `fa2-repulsion-exact` (K3, 3.10.1): the tiled all-pairs repulsion with the gravity and swing / traction epilogue; 6 storage bindings (`oldForce` read-only: it only calls load_old); calls the reduction helpers. */
+/** `fa2-repulsion-exact` (K3, 3.10.1): the tiled all-pairs repulsion with the gravity and swing / traction epilogue; LAW 0 FA2 / 1 FR / 2 coulomb (P5); 6 storage bindings (`oldForce` read-only: it only calls load_old); calls the reduction helpers. */
 const FA2_REPULSION_EXACT: KernelEntry = {
     id: "fa2-repulsion-exact",
     body: fa2RepulsionExactWgsl,
@@ -392,6 +404,7 @@ const FA2_REPULSION_EXACT: KernelEntry = {
         { name: "SWING_MODE", type: "u32", default: 0 },
         { name: "STRONG_GRAVITY", type: "bool", default: false },
         { name: "GRAVITY_CENTER", type: "u32", default: 0 },
+        { name: "LAW", type: "u32", default: 0 },
     ],
     uniforms: [FA2_PARAMS, FA2_STATE, FA2_PARTIAL],
     needs: ["subgroups"],
@@ -417,7 +430,7 @@ const FA2_SPEED_FINALIZE: KernelEntry = {
     phase: "P1",
 };
 
-/** `fa2-integrate` (K5, 3.10.1): the per-node speed factor and position update (no clamp, D25), `oldForce` stored in SWING_MODE 0, and the partials A / C of the next K1; 6 storage bindings; calls the reduction helpers. */
+/** `fa2-integrate` (K5, 3.10.1): the per-node speed factor and position update (no clamp, D25), `oldForce` stored in SWING_MODE 0, and the partials A / C of the next K1; APPLY 0 FA2 / 1 FR temperature cap / 2 ngraph Euler (P5); 6 storage bindings; calls the reduction helpers. */
 const FA2_INTEGRATE: KernelEntry = {
     id: "fa2-integrate",
     body: fa2IntegrateWgsl,
@@ -431,7 +444,10 @@ const FA2_INTEGRATE: KernelEntry = {
         decl(1, 5, "partials", "storage", "array<Fa2Partial>"),
         decl(2, 0, "P", "uniform", "Fa2Params"),
     ],
-    overrideDecls: [{ name: "SWING_MODE", type: "u32", default: 0 }],
+    overrideDecls: [
+        { name: "SWING_MODE", type: "u32", default: 0 },
+        { name: "APPLY", type: "u32", default: 0 },
+    ],
     uniforms: [FA2_PARAMS, FA2_STATE, FA2_PARTIAL],
     needs: ["subgroups"],
     snippetSlots: [],

package/src/layouts/force-simulation.ts

@@ -84,6 +84,8 @@ export interface ModelResources {
 export interface ModelInputs {
     readonly mass: F32;
     readonly weights: ResolvedWeights;
+    /** A mask to apply at load (the FR `fixed` option, PD-6); validated against `ceil(n / 32)` words; absent / null leaves the words as they are (kept on a same-size reload, cleared on a resize, spec 7.12). */
+    readonly fixed?: NodeMask | null | undefined;
 }
 
 /**
@@ -930,6 +932,15 @@ export class ForceSimulation<
                     `the model resolved ${inputs.mass.length} masses for ${n} nodes`,
                 );
             }
+            const fixedWords = Math.ceil(n / 32);
+            if (inputs.fixed !== undefined && inputs.fixed !== null && inputs.fixed.length < fixedWords) {
+                throw invalidArgument(
+                    "fixed",
+                    inputs.fixed.length,
+                    fixedWords,
+                    `the model resolved a fixed mask of ${inputs.fixed.length} words, ${fixedWords} needed for ${n} nodes`,
+                );
+            }
         }
 
         // ---- every check passed: mutate
@@ -956,6 +967,10 @@ export class ForceSimulation<
             this.fixedWords = makeMask(n);
             this.fixedDirty = false;
         }
+        if (inputs !== null && inputs.fixed !== undefined && inputs.fixed !== null) {
+            this.fixedWords.set(inputs.fixed.subarray(0, Math.ceil(n / 32)));
+            this.fixedDirty = true;
+        }
         if (n === 0 || core === null || inputs === null) {
             // PLAN DECISION 10: an empty graph loads with no GPU work
             this.weightsUpload = null;
@@ -1542,22 +1557,24 @@ export class ForceSimulation<
      * The uniform values of one iteration slot: the model's values with the shared fields on top (PLAN DECISION 6).
      * @param global - the global iteration index (iterationsSubmitted + i)
      * @param index - the slot index within the batch (the trace slot)
-     * @param flags - FA2_FLAG_FIRST for the first iteration after load(), else 0
+     * @param flags - FA2_FLAG_FIRST for the first iteration after load(), else 0; the model's own flag bits are OR-ed in
      * @returns the values
      */
     private paramsForSlot(global: number, index: number, flags: number): UniformValues {
         const [cx, cy, cz] = this.center;
+        const model = this.model.paramsFor(global, this.optionsValue);
+        const modelFlags = typeof model.flags === "number" ? model.flags : 0;
         const shared: UniformValues = {
             n: this.n,
             dim: this.dimValue,
-            flags,
+            flags: flags | modelFlags,
             iterationIndex: index,
             seed: this.seedU32(),
             scale: this.scale,
             center: [cx, cy, cz, 0],
             settleThreshold: this.settleThreshold(),
         };
-        return { ...this.model.paramsFor(global, this.optionsValue), ...shared };
+        return { ...model, ...shared };
     }
 
     /**