@graphty/webgpu-graph-algorithms 0.4.1 → 0.5.1

package/src/layouts/forceatlas2.ts

@@ -50,22 +50,30 @@ import {
     type StateWriter,
 } from "./force-simulation.js";
 import { resolveNodeMass, resolveWeights } from "./inputs.js";
+import {
+    describeValue,
+    FILL_PARAMS_BUFFER,
+    FORCE_BYTES_PER_NODE,
+    invalid,
+    isPositiveInteger,
+    type Overrides,
+    pickBoolean,
+    pickCenter,
+    pickDim,
+    pickNumber,
+    pickSeed,
+    scalar,
+    seedWord,
+    subset,
+    vector,
+} from "./model-common.js";
 import { RepulsionExact, type RepulsionExactOverrides } from "./repulsion-exact.js";
 
 // ============================================================ constants and small helpers
 
-/** An override record as the kernel layer takes it. */
-type Overrides = Readonly<Record<string, number | boolean>>;
-
 /** The stage names of one iteration in dispatch order plus the per-batch toScene (spec 7.4; contract 3.13). */
 const FA2_STAGES = ["K1", "K2", "K3", "K4", "K5", "toScene"] as const;
 
-/** Bytes of the stride-3 f32 force arrays per node. */
-const FORCE_BYTES_PER_NODE = 12;
-
-/** The name of the model-owned FillParams buffer (a BufferSpec, reached through ModelResources.buffer). */
-const FILL_PARAMS_BUFFER = "fillParams";
-
 /** The one-workgroup dispatch of K1 (spec 7.4). */
 const ONE_WORKGROUP: DispatchPlan = { x: 1, y: 1, z: 1, items: 1, stride: null };
 
@@ -75,9 +83,6 @@ const K2_DEFAULTS: Overrides = { LINLOG: false, DISTRIBUTED: false, TIER: 0, USE
 /** Every override K5 accepts, with its default. */
 const K5_DEFAULTS: Overrides = { SWING_MODE: 0 };
 
-/** 2^32, the modulus of the u32 seed word (computed with `%`, never a bitwise operator). */
-const U32_MODULUS = 4294967296;
-
 /** The resolved record with no option given: FA2_DEFAULTS plus the null / origin defaults of spec 7.14. */
 const DEFAULT_RESOLVED: ResolvedForceAtlas2Options = Object.freeze<ResolvedForceAtlas2Options>({
     ...FA2_DEFAULTS,
@@ -88,214 +93,6 @@ const DEFAULT_RESOLVED: ResolvedForceAtlas2Options = Object.freeze<ResolvedForce
     seed: null,
 });
 
-/**
- * A short, safe rendering of an argument value for error messages (never String() on an object).
- * @param value - the value
- * @returns the rendering
- */
-function describeValue(value: unknown): string {
-    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)
- */
-function invalid(argument: string, value: unknown, expected: string): WebGpuGraphError {
-    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
- */
-function pickNumber(
-    name: string,
-    given: number | undefined,
-    fallback: number,
-    check: (value: number) => boolean,
-    expected: string,
-): number {
-    const value: unknown = 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
- */
-function pickBoolean(name: string, given: boolean | undefined, fallback: boolean): boolean {
-    const value: unknown = 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
- */
-function pickDim(given: 2 | 3 | undefined, fallback: 2 | 3): 2 | 3 {
-    const value: unknown = 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
- */
-function pickCenter(
-    given: ArrayLike<number> | undefined,
-    fallback: readonly [number, number, number],
-): readonly [number, number, number] {
-    if (given === undefined) {
-        return fallback;
-    }
-    const expected = "an array of 2 or 3 finite numbers";
-    const value: unknown = 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: unknown = given[0];
-    const y: unknown = given[1];
-    const z: unknown = 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
- */
-function pickSeed(given: number | null | undefined, fallback: number | null): number | null {
-    if (given === undefined) {
-        return fallback;
-    }
-    const value: unknown = 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
- */
-function isPositiveInteger(value: number): boolean {
-    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
- */
-function seedWord(seed: number | null): number {
-    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
- */
-function scalar(values: UniformValues, name: string): number {
-    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
- */
-function vector(values: UniformValues, name: string): readonly number[] {
-    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
- */
-function subset(merged: Overrides, defaults: Overrides): Overrides {
-    const out: Record<string, number | boolean> = {};
-    for (const name of Object.keys(defaults)) {
-        out[name] = name in merged ? merged[name] : defaults[name];
-    }
-    return out;
-}
-
 /**
  * The K3 / K4 override values of a merged set (typed for RepulsionExact).
  * @param merged - the merged override set