@graphty/webgpu-graph-algorithms 0.0.0 → 0.2.1

package/src/layouts/inputs.ts

@@ -0,0 +1,252 @@
+/**
+ * nodeMass and weight resolution from graph-format primitives only (spec 7.14, 7.5; D28, Q-30): the role-"mass"
+ * node column first, then outDegree() + 1; weights from the arc array, from a named edge column expanded to arcs
+ * with expandEdges, or none. The Record form of nodeMass is rejected with the hint of spec 7.14 (graphty-element
+ * writes its nodeMass config as the role column once at engine creation, so both simulations find it the same way
+ * and this package parses no ids).
+ */
+
+import { type Column, expandEdges, type F32, type GraphSnapshot, type NodeId } from "@graphty/graph-format";
+
+import { WebGpuGraphError } from "../errors.js";
+
+/** The message of spec 7.14 for the Record form of nodeMass. */
+const NODE_MASS_HINT =
+    "write a role 'mass' node column (nodes.set(name, vec, { role: 'mass', replaceRole: true })) or pass a " +
+    "Float32Array; @graphty/layout's resolveNodeVector does this on the CPU path";
+
+/**
+ * An E_INVALID_ARGUMENT with the documented details shape.
+ * @param argument - the option name
+ * @param value - the offending value
+ * @param expected - what was expected
+ * @param message - the message
+ * @returns the error
+ */
+function invalid(argument: string, value: unknown, expected: unknown, message: string): WebGpuGraphError {
+    return new WebGpuGraphError("E_INVALID_ARGUMENT", message, { argument, value, expected });
+}
+
+/**
+ * Asserts every mass is finite and > 0 (spec 7.14: a mass of 0 would divide the distributed action by zero).
+ * @param mass - the masses
+ * @param source - what the masses came from, for the message
+ */
+function checkMass(mass: ArrayLike<number>, source: string): void {
+    for (let i = 0; i < mass.length; i++) {
+        const v = mass[i];
+        if (!Number.isFinite(v) || v <= 0) {
+            throw new WebGpuGraphError(
+                "E_INVALID_ARGUMENT",
+                `${source}: mass[${i}] = ${v} is not a finite number > 0`,
+                {
+                    argument: "nodeMass",
+                    value: v,
+                    index: i,
+                    expected: "finite masses > 0",
+                },
+            );
+        }
+    }
+}
+
+/**
+ * outDegree()[i] + 1 for every node (spec 7.2 "Mass" row; one O(n) loop over the cached view).
+ * @param s - the snapshot
+ * @returns a fresh F32 of nodeCount masses
+ */
+function degreePlusOne(s: GraphSnapshot): F32 {
+    const n = s.nodeCount;
+    const degree = s.outDegree();
+    const out = new Float32Array(n);
+    for (let i = 0; i < n; i++) {
+        out[i] = degree[i] + 1;
+    }
+    return out;
+}
+
+/**
+ * The masses of a node column: f32 as is, f64 / u32 / i32 through gpuView (f64 = the cached f32 copy; u32 / i32
+ * converted to a fresh F32), u8 through column.data; every other dtype is E_INVALID_ARGUMENT (PLAN DECISION 14).
+ * @param s - the snapshot (the column belongs to s.nodes)
+ * @param column - the node column
+ * @returns nodeCount masses
+ */
+function massFromColumn(s: GraphSnapshot, column: Column): F32 {
+    const { name } = column.meta;
+    if (column.meta.components !== 1) {
+        throw invalid(
+            "nodeMass",
+            name,
+            "a one-component numeric node column",
+            `node column "${name}" has ${column.meta.components} components; a mass column has one`,
+        );
+    }
+    let values: ArrayLike<number>;
+    switch (column.dtype) {
+        case "f32":
+        case "f64": {
+            const view = s.nodes.gpuView(name);
+            const out = view instanceof Float32Array ? view : new Float32Array(view);
+            checkMass(out, `node column "${name}"`);
+            return out;
+        }
+        case "u32":
+        case "i32":
+            values = s.nodes.gpuView(name);
+            break;
+        case "u8":
+            values = column.data;
+            break;
+        default:
+            throw invalid(
+                "nodeMass",
+                name,
+                "a numeric node column (f32, f64, u32, i32, u8)",
+                `node column "${name}" is ${column.dtype}, not numeric`,
+            );
+    }
+    const out = new Float32Array(s.nodeCount);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = values[i];
+    }
+    checkMass(out, `node column "${name}"`);
+    return out;
+}
+
+/**
+ * nodeMass resolution by ROLE (spec 7.14): null -> the role-"mass" node column when present (any numeric dtype
+ * through gpuView, converted to a fresh F32 when not f32), else outDegree()[i] + 1; an F32 of length n -> as is;
+ * a column NAME -> nodes.get(name) (numeric); a Record -> E_UNSUPPORTED with the spec's message. Always returns n
+ * values, every one finite and > 0.
+ * @param s - the snapshot
+ * @param spec - the ForceAtlas2Options.nodeMass value
+ * @returns nodeCount masses (the caller's array when an F32 was given)
+ */
+export function resolveNodeMass(
+    s: GraphSnapshot,
+    spec: F32 | string | Readonly<Record<NodeId, number>> | null | undefined,
+): F32 {
+    const n = s.nodeCount;
+    if (spec === null || spec === undefined) {
+        const column = s.nodes.byRole("mass");
+        if (column === null) {
+            return degreePlusOne(s);
+        }
+        return massFromColumn(s, column);
+    }
+    if (spec instanceof Float32Array) {
+        if (spec.length !== n) {
+            throw invalid("nodeMass", spec.length, `${n} values`, `nodeMass has ${spec.length} values, expected ${n}`);
+        }
+        checkMass(spec, "nodeMass");
+        return spec;
+    }
+    if (typeof spec === "string") {
+        const column = s.nodes.get(spec);
+        if (column === null) {
+            throw invalid(
+                "nodeMass",
+                spec,
+                "an existing numeric node column",
+                `nodeMass names node column "${spec}", which the snapshot does not hold`,
+            );
+        }
+        return massFromColumn(s, column);
+    }
+    if (ArrayBuffer.isView(spec)) {
+        throw invalid(
+            "nodeMass",
+            "typed array",
+            "a Float32Array",
+            "nodeMass must be a Float32Array, a column name or null",
+        );
+    }
+    throw new WebGpuGraphError(
+        "E_UNSUPPORTED",
+        `nodeMass as a Record is not supported on the GPU path: ${NODE_MASS_HINT}`,
+        {
+            option: "nodeMass",
+            hint: NODE_MASS_HINT,
+        },
+    );
+}
+
+/** What resolveWeights found. */
+export interface ResolvedWeights {
+    readonly data: F32 | null;
+    readonly source: "arcs" | "column" | "none";
+    readonly column: Column | null;
+}
+
+/**
+ * Weight resolution (spec 7.5, 7.14): true -> { data: s.weights, source: "arcs" } (data null when unweighted ->
+ * ones); a string -> a name `s.edges` does not hold is E_INVALID_ARGUMENT (spec 7.14's nodeMass rule applied to
+ * weight too), else `column = s.edges.get(name)`, then by `column.dtype`: f32 / f64 / u32 / i32 ->
+ * expandEdges(s, s.edges.gpuView(name)) (f64 arrives as gpuView's cached f32 copy; u32 / i32 are converted to a
+ * fresh F32; `Column.data` is NOT used because it is U8 for u8 / bool and absent for string / list / json), string /
+ * list / json -> the gpuView E_GPU_INELIGIBLE pass-through, u8 / bool / dict -> E_INVALID_ARGUMENT (gpuView returns
+ * packed words, not per-edge values); source "column", `column` kept for the version check; false / null /
+ * undefined -> none. A named column must have one component (PLAN DECISION 15); the weight values are never
+ * inspected.
+ * @param s - the snapshot
+ * @param spec - the ForceAtlas2Options.weight value
+ * @returns the resolved weights
+ */
+export function resolveWeights(s: GraphSnapshot, spec: boolean | string | null | undefined): ResolvedWeights {
+    if (spec === true) {
+        return { data: s.weights, source: "arcs", column: null };
+    }
+    if (spec === false || spec === null || spec === undefined) {
+        return { data: null, source: "none", column: null };
+    }
+    if (typeof spec !== "string") {
+        throw invalid(
+            "weight",
+            spec,
+            "true, false, null or an edge column name",
+            "weight must be true, false, null or an edge column name",
+        );
+    }
+    const column = s.edges.get(spec);
+    if (column === null) {
+        throw invalid(
+            "weight",
+            spec,
+            "an existing numeric edge column",
+            `weight names edge column "${spec}", which the snapshot does not hold`,
+        );
+    }
+    if (column.meta.components !== 1) {
+        throw invalid(
+            "weight",
+            spec,
+            "a one-component numeric edge column",
+            `edge column "${spec}" has ${column.meta.components} components; a weight column has one`,
+        );
+    }
+    switch (column.dtype) {
+        case "f32":
+        case "f64":
+        case "u32":
+        case "i32": {
+            const view = s.edges.gpuView(spec);
+            const expanded = expandEdges(s, view);
+            const data = expanded instanceof Float32Array ? expanded : new Float32Array(expanded);
+            return { data, source: "column", column };
+        }
+        case "string":
+        case "list":
+        case "json":
+            // gpuView throws the GraphFormatError E_GPU_INELIGIBLE, which passes through unchanged (D12)
+            s.edges.gpuView(spec);
+            throw invalid("weight", spec, "a numeric edge column", `edge column "${spec}" is ${column.dtype}`);
+        default:
+            throw invalid(
+                "weight",
+                spec,
+                "an f32 / f64 / u32 / i32 edge column",
+                `edge column "${spec}" is ${column.dtype}: its gpuView is packed words, not per-edge values`,
+            );
+    }
+}

package/src/layouts/repulsion-exact.ts

@@ -0,0 +1,183 @@
+/**
+ * The exact-tier repulsion stage of ForceAtlas2 (spec 7.6, 7.9, 7.10; contract 3.13): K3, the tiled all-pairs
+ * repulsion with the gravity term and the swing / traction epilogue, followed by K4, the one-workgroup speed finalize
+ * that folds the per-workgroup partials and runs estimateFactor on the device (D15). P1 ships the stage driven over a
+ * pass the caller opens (the tests); P3-T2 records it from ForceAtlas2Model.recordIteration without changing these
+ * declarations. Both kernels come from the registry (src/kernels.ts) through the pipeline cache, so a distinct
+ * override set is a distinct pipeline and the subgroup twin is selected by the device's features (spec 5.1, D16).
+ */
+
+import { WebGpuGraphError } from "../errors.js";
+import { type DispatchPlan, plan1d } from "../kernel/dispatch.js";
+import { type BoundKernel, type Kernel } from "../kernel/kernel.js";
+import { type PipelineCache } from "../kernel/pipeline-cache.js";
+import { type WgslModuleSpec } from "../kernel/wgsl.js";
+import { kernelSpec } from "../kernels.js";
+import { type PlanCaps } from "../types/context.js";
+import { type Binding } from "../types/memory.js";
+
+/** The buffers the exact-tier repulsion stage binds (all in layout units; spec 7.3). */
+export interface RepulsionExactResources {
+    readonly pos: Binding;
+    readonly state: Binding;
+    readonly trace: Binding;
+    readonly force: Binding;
+    readonly oldForce: Binding;
+    readonly fixedMask: Binding;
+    readonly partials: Binding;
+    readonly params: Binding;
+}
+
+/** The overrides K3 / K4 compile with. */
+export interface RepulsionExactOverrides {
+    readonly SWING_MODE: 0 | 1;
+    readonly STRONG_GRAVITY: boolean;
+    readonly GRAVITY_CENTER: 0 | 1;
+}
+
+/** K3 (tiled all-pairs repulsion + gravity + the swing / traction epilogue) followed by K4 (the one-workgroup speed finalize) (spec 7.6, 7.10). */
+export class RepulsionExact {
+    /** The overrides both kernels were compiled with (a frozen copy of the argument of create()). */
+    readonly overrides: RepulsionExactOverrides;
+
+    private readonly caps: PlanCaps;
+    private readonly repulsion: Kernel;
+    private readonly speedFinalize: Kernel;
+    /** Exactly one workgroup of K4 (spec 7.4: "1 workgroup"). */
+    private readonly finalizePlan: DispatchPlan;
+    private boundRepulsion: BoundKernel | null = null;
+    private boundSpeedFinalize: BoundKernel | null = null;
+
+    /**
+     * Holds the two compiled kernels; create() is the only caller.
+     * @param repulsion - the K3 kernel
+     * @param speedFinalize - the K4 kernel
+     * @param caps - the device caps the dispatch planner reads
+     * @param overrides - the override set both kernels were compiled with
+     */
+    private constructor(repulsion: Kernel, speedFinalize: Kernel, caps: PlanCaps, overrides: RepulsionExactOverrides) {
+        this.repulsion = repulsion;
+        this.speedFinalize = speedFinalize;
+        this.caps = caps;
+        this.overrides = Object.freeze({
+            SWING_MODE: overrides.SWING_MODE,
+            STRONG_GRAVITY: overrides.STRONG_GRAVITY,
+            GRAVITY_CENTER: overrides.GRAVITY_CENTER,
+        });
+        this.finalizePlan = plan1d(speedFinalize.workgroupSize, speedFinalize.workgroupSize, caps);
+    }
+
+    /**
+     * Compiles both kernels through the cache (the twin is selected by caps.features).
+     * @param pipelines - the context's pipeline cache
+     * @param caps - the device caps the dispatch planner reads
+     * @param overrides - the SWING_MODE / STRONG_GRAVITY / GRAVITY_CENTER set of this stage
+     * @returns the stage, ready for bind()
+     */
+    static async create(
+        pipelines: PipelineCache,
+        caps: PlanCaps,
+        overrides: RepulsionExactOverrides,
+    ): Promise<RepulsionExact> {
+        const [repulsionSpec, finalizeSpec] = RepulsionExact.specs(overrides);
+        // Sequential on purpose: PipelineCache.get runs createComputePipelineAsync inside a validation scope, and error
+        // scopes form one stack per device, so two interleaved compilations would pop each other's scope.
+        const repulsion = await pipelines.kernel(repulsionSpec);
+        const speedFinalize = await pipelines.kernel(finalizeSpec);
+        return new RepulsionExact(repulsion, speedFinalize, caps, overrides);
+    }
+
+    /**
+     * The two specs (for warm() and the compile matrix).
+     * @param overrides - the override set of the stage
+     * @returns the K3 spec then the K4 spec
+     */
+    static specs(overrides: RepulsionExactOverrides): readonly [WgslModuleSpec, WgslModuleSpec] {
+        return [
+            kernelSpec("fa2-repulsion-exact", {
+                SWING_MODE: overrides.SWING_MODE,
+                STRONG_GRAVITY: overrides.STRONG_GRAVITY,
+                GRAVITY_CENTER: overrides.GRAVITY_CENTER,
+            }),
+            kernelSpec("fa2-speed-finalize", { SWING_MODE: overrides.SWING_MODE }),
+        ];
+    }
+
+    /**
+     * Creates the bind groups once per load(): K3 takes pos, state (S), force, oldForce, fixedMask, partials and the
+     * params slot; K4 takes partials, state (S), trace (T) and the params slot (the 3.10.1 binding names). The state
+     * header and the trace region are two disjoint ranges of one buffer, which Kernel.bind() accepts (no writable alias).
+     * @param resources - the buffers of spec 7.3
+     */
+    bind(resources: RepulsionExactResources): void {
+        this.boundRepulsion = this.repulsion.bind({
+            pos: resources.pos,
+            S: resources.state,
+            force: resources.force,
+            oldForce: resources.oldForce,
+            fixedMask: resources.fixedMask,
+            partials: resources.partials,
+            P: resources.params,
+        });
+        this.boundSpeedFinalize = this.speedFinalize.bind({
+            partials: resources.partials,
+            S: resources.state,
+            T: resources.trace,
+            P: resources.params,
+        });
+    }
+
+    /**
+     * Records K3 (plan1d(n)) then K4 (1 workgroup) with the params slot's dynamic offset.
+     * @param pass - the open compute pass of the batch
+     * @param n - the node count (rows [0, n) of pos / force)
+     * @param paramsOffset - the dynamic offset of this iteration's Fa2Params slot in the uniform ring
+     */
+    record(pass: GPUComputePassEncoder, n: number, paramsOffset: number): void {
+        this.recordRepulsion(pass, n, paramsOffset);
+        this.recordSpeedFinalize(pass, paramsOffset);
+    }
+
+    /**
+     * Records K3 only (the inspect() stage split, spec 11.9 item 2).
+     * @param pass - the open compute pass
+     * @param n - the node count
+     * @param paramsOffset - the dynamic offset of the Fa2Params slot
+     * @internal
+     */
+    recordRepulsion(pass: GPUComputePassEncoder, n: number, paramsOffset: number): void {
+        const bound = this.bound(this.boundRepulsion, "recordRepulsion");
+        const plan = plan1d(n, this.repulsion.workgroupSize, this.caps);
+        this.repulsion.dispatch(pass, bound, plan, [paramsOffset]);
+    }
+
+    /**
+     * Records K4 only.
+     * @param pass - the open compute pass
+     * @param paramsOffset - the dynamic offset of the Fa2Params slot
+     * @internal
+     */
+    recordSpeedFinalize(pass: GPUComputePassEncoder, paramsOffset: number): void {
+        const bound = this.bound(this.boundSpeedFinalize, "recordSpeedFinalize");
+        this.speedFinalize.dispatch(pass, bound, this.finalizePlan, [paramsOffset]);
+    }
+
+    /**
+     * The bound kernel of a method, or E_NOT_LOADED when bind() has not run.
+     * @param bound - the cached BoundKernel, null before bind()
+     * @param method - the caller's name for the message
+     * @returns the bound kernel
+     */
+    private bound(bound: BoundKernel | null, method: string): BoundKernel {
+        if (bound === null) {
+            throw new WebGpuGraphError(
+                "E_NOT_LOADED",
+                `RepulsionExact.${method}(): bind() has not been called for this stage`,
+                {
+                    state: "unbound",
+                },
+            );
+        }
+        return bound;
+    }
+}

package/src/layouts/seed.ts

@@ -0,0 +1,198 @@
+/**
+ * The CPU port's random number generator, bit for bit, and the NaN-row seeding both paths share (spec 7.2 "Initial
+ * positions", 9.3 seedPositions, 7.14 `pos`, 7.19 topology change): a seed gives the same start on the CPU and the
+ * GPU because both write the same f32 values in index order. The package carries its own copy of the LCG for its
+ * whole life (D27: it cannot import @graphty/layout); W1 cross-tests it against the real RandomNumberGenerator.
+ */
+
+import type { F32, GraphSnapshot } from "@graphty/graph-format";
+
+import { WebGpuGraphError } from "../errors.js";
+
+/** The CPU port's LCG constants (layout/src/utils/random.ts): m = 2^35 - 31, a = 185852, c = 1. */
+export const LCG_M = 34359738337;
+/** The multiplier a of the port's LCG. */
+export const LCG_A = 185852;
+/** The increment c of the port's LCG. */
+export const LCG_C = 1;
+
+/**
+ * The port's RandomNumberGenerator, bit for bit: `seed || Math.floor(Math.random() * 1000000)` (seed 0 / null =
+ * unseeded, the quirk preserved), state = seed % m, next = (a * state + c) % m, value = state / m. The product
+ * a * state stays below 2^53 (a < 2^18, state < 2^35), so every step is exact in f64, as it is in the port.
+ */
+export class Lcg {
+    /** The seed actually used (a random one when unseeded). */
+    readonly seed: number;
+
+    private state: number;
+
+    /**
+     * Creates the generator; a seed of 0, -0, NaN or null means unseeded (the port's `seed || random` quirk).
+     * @param seed - the seed, or null for a random seed
+     */
+    constructor(seed: number | null) {
+        this.seed = seed === null || seed === 0 || Number.isNaN(seed) ? Math.floor(Math.random() * 1000000) : seed;
+        this.state = this.seed % LCG_M;
+    }
+
+    /**
+     * Next value in [0, 1).
+     * @returns state / m after one LCG step
+     */
+    next(): number {
+        this.state = (LCG_A * this.state + LCG_C) % LCG_M;
+        return this.state / LCG_M;
+    }
+}
+
+/**
+ * The three center components of a CommonLayoutOptions.center (missing components are 0).
+ * @param center - the caller's center, or null
+ * @returns [x, y, z]; E_INVALID_ARGUMENT when a component is not finite
+ */
+function resolveCenter(center: ArrayLike<number> | null): [number, number, number] {
+    const out: [number, number, number] = [0, 0, 0];
+    if (center === null) {
+        return out;
+    }
+    for (let axis = 0; axis < 3 && axis < center.length; axis++) {
+        const v = center[axis];
+        if (!Number.isFinite(v)) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", `center[${axis}] is not finite`, {
+                argument: "center",
+                value: v,
+                expected: "finite components",
+            });
+        }
+        out[axis] = v;
+    }
+    return out;
+}
+
+/**
+ * Seeds the unseeded rows of the owner's stride-3 SCENE array in index order (spec 9.3 seedPositions, 7.14 `pos`,
+ * 7.19 topology change): a row is unseeded when any of its `dim` components is not finite; every such component
+ * draws one LCG value; when NO row is fully finite the draw is uniform in [-1, 1) layout units per axis (`range:
+ * "fa2"`; `"fr"` is [0, 1)), otherwise uniform inside the [min, max] box of the finite components per axis,
+ * converted to layout units (an axis with no finite value falls back to the range box); the value is written as
+ * `v * scale + center[axis]`, which for scale 1 / center 0 is bit-identical to the port's `u * 2 - 1` (resp. `u`);
+ * in 2D the third component of a seeded row is written as center[2]. Finite components are never changed and a
+ * fully finite row is never touched. No random number is drawn when nothing needs seeding.
+ * PLAN DECISION 12 (P3-T1): the box is taken over every finite COMPONENT (the port's rule), not over the fully
+ * finite ROWS only; the two differ only when a partially finite row's finite axis lies outside the fully finite
+ * rows' box (pinned by test/layouts/seed.test.ts). PLAN DECISION 13: a 2D row whose x and y are finite is seeded
+ * whatever its z holds.
+ * @param s - the snapshot (nodeCount rows)
+ * @param positions - the owner's stride-3 scene-unit array, length 3 * nodeCount, modified in place
+ * @param seed - the LCG seed (0 / null = unseeded, the port's quirk)
+ * @param dim - 2 or 3
+ * @param scale - the scene scale (> 0)
+ * @param center - the scene center, or null for the origin
+ * @param range - "fa2" for [-1, 1), "fr" for [0, 1)
+ */
+export function seedPositions(
+    s: GraphSnapshot,
+    positions: F32,
+    seed: number | null,
+    dim: 2 | 3,
+    scale: number,
+    center: ArrayLike<number> | null,
+    range: "fa2" | "fr",
+): void {
+    const n = s.nodeCount;
+    if (dim !== 2 && dim !== 3) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `dim must be 2 or 3, got ${String(dim)}`, {
+            argument: "dim",
+            value: dim,
+            expected: "2 or 3",
+        });
+    }
+    if (positions.length !== 3 * n) {
+        throw new WebGpuGraphError(
+            "E_INVALID_ARGUMENT",
+            `positions has ${positions.length} entries, expected ${3 * n}`,
+            {
+                argument: "positions",
+                value: positions.length,
+                expected: 3 * n,
+            },
+        );
+    }
+    if (!Number.isFinite(scale) || scale <= 0) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `scale must be a finite number > 0, got ${scale}`, {
+            argument: "scale",
+            value: scale,
+            expected: "a finite number > 0",
+        });
+    }
+    const c = resolveCenter(center);
+
+    // classify the rows and collect the per-axis box of the finite components (scene units)
+    const lo = [Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY];
+    const hi = [Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY];
+    let finiteRows = 0;
+    let unseededRows = 0;
+    for (let i = 0; i < n; i++) {
+        let finite = true;
+        for (let axis = 0; axis < dim; axis++) {
+            const v = positions[3 * i + axis];
+            if (Number.isFinite(v)) {
+                if (v < lo[axis]) {
+                    lo[axis] = v;
+                }
+                if (v > hi[axis]) {
+                    hi[axis] = v;
+                }
+            } else {
+                finite = false;
+            }
+        }
+        if (finite) {
+            finiteRows++;
+        } else {
+            unseededRows++;
+        }
+    }
+    if (unseededRows === 0) {
+        return;
+    }
+
+    // the per-axis draw box in layout units
+    const rangeLo = range === "fr" ? 0 : -1;
+    const rangeHi = 1;
+    const boxLo = [rangeLo, rangeLo, rangeLo];
+    const boxHi = [rangeHi, rangeHi, rangeHi];
+    if (finiteRows > 0) {
+        for (let axis = 0; axis < dim; axis++) {
+            if (Number.isFinite(lo[axis]) && Number.isFinite(hi[axis])) {
+                boxLo[axis] = (lo[axis] - c[axis]) / scale;
+                boxHi[axis] = (hi[axis] - c[axis]) / scale;
+            }
+        }
+    }
+
+    const rng = new Lcg(seed);
+    for (let i = 0; i < n; i++) {
+        let unseeded = false;
+        for (let axis = 0; axis < dim; axis++) {
+            if (!Number.isFinite(positions[3 * i + axis])) {
+                unseeded = true;
+            }
+        }
+        if (!unseeded) {
+            continue;
+        }
+        for (let axis = 0; axis < dim; axis++) {
+            const at = 3 * i + axis;
+            if (!Number.isFinite(positions[at])) {
+                const u = rng.next();
+                const v = boxLo[axis] + u * (boxHi[axis] - boxLo[axis]);
+                positions[at] = v * scale + c[axis];
+            }
+        }
+        if (dim === 2) {
+            positions[3 * i + 2] = c[2];
+        }
+    }
+}