@graphty/webgpu-graph-algorithms 0.2.1 → 0.4.0

package/dist/src/algorithms/pagerank.js

@@ -0,0 +1,298 @@
+/**
+ * PageRank and personalized PageRank on the device (spec 8.2, 3.3): a pull over the reverse adjacency with the
+ * out-weight normaliser folded into `xNorm` by `pr-scale`, the dangling mass and the L1 delta folded by
+ * `pr-finalize` into the header at `partials[0]`, and `spmv-pull` writing the next iterate. Iterations run in
+ * batches of PR_BATCH per submit, ONE readback per batch (the header and the iterate together), and the device
+ * records `firstConverged` the first time the delta falls below `tolerance * n`, so the reported `iterations` is the
+ * first converged iteration and not the batch boundary (spec 9.7).
+ *
+ * PLAN DECISION PD-7: the ping-pong is TWO buffers (`rankA`, `rankB`) alternated through two cached bind groups;
+ * one buffer of two aliased halves would bind (each kernel sees the halves in one access mode) but saves nothing.
+ * PLAN DECISION PD-8: `outWeightSum` is call scratch from the Lease, one `segmentedReduce` pass per call.
+ * PLAN DECISION PD-9: `pr-scale` at iteration i reads x(i-1) and x(i-2), so its delta is the error of iteration
+ * i - 1 and `pr-finalize` records `P.iteration - 1`; the ping-pong supplies `rankPrev` for free because it is the
+ * buffer this iteration overwrites, and `pr-scale` runs before `spmv-pull` in the same pass.
+ */
+import { U32_MAX } from "../constants.js";
+import { isWebGpuGraphError, WebGpuGraphError } from "../errors.js";
+import { CommandBatch } from "../kernel/batch.js";
+import { groupsOf, plan1d } from "../kernel/dispatch.js";
+import { kernelSpec, PR_PARAMS, PR_PARTIAL } from "../kernels.js";
+import { coreOfView } from "../primitives/core-shape.js";
+import { prepareSegmentedReduce } from "../primitives/segmented-reduce.js";
+import { prepareSpmvPull } from "../primitives/spmv.js";
+import { algorithmScope } from "./scope.js";
+/** Iterations per submit (spec 8.2: k = 8). */
+const PR_BATCH = 8;
+/** Params slots of one batch: per iteration one PrParams (shared by pr-scale and pr-finalize) and one SpmvParams, plus the normaliser's RangeParams; a smaller ring wraps onto a slot the same batch still reads. */
+const RING_SLOTS = 2 * PR_BATCH + 1;
+/**
+ * Validates `options.dest` for a score result of `n` elements.
+ * @param dest - the caller's destination array, if any
+ * @param n - the node count
+ * @param algorithm - the caller's name, for the message
+ * @returns the destination as an F32, or null when none was given
+ */
+function checkDest(dest, n, algorithm) {
+    if (dest === undefined) {
+        return null;
+    }
+    if (dest instanceof Float32Array && dest.length === n && dest.buffer instanceof ArrayBuffer) {
+        return dest;
+    }
+    throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${algorithm}: dest must be a Float32Array of length ${n} over an ArrayBuffer`, {
+        argument: "dest",
+        value: `${dest.constructor.name}(${dest.length})`,
+        expected: `Float32Array(${n}) over an ArrayBuffer`,
+    });
+}
+/**
+ * The resident core; a windowed plan (`E_TOO_LARGE { path: "windowed", algorithm: null }`, spec 3.8) is re-thrown
+ * with the algorithm name (3.12). Transcribed from degree.ts, whose coreOf is module-private.
+ * @param ctx - the context
+ * @param s - the snapshot
+ * @param algorithm - the caller's name
+ * @returns the core binding
+ */
+function coreOf(ctx, s, algorithm) {
+    try {
+        return ctx.residency.core(s);
+    }
+    catch (error) {
+        if (isWebGpuGraphError(error) && error.code === "E_TOO_LARGE" && error.details.path === "windowed") {
+            throw new WebGpuGraphError("E_TOO_LARGE", `${algorithm}: the arc arrays need a windowed upload, which P1-P3 plan but do not execute`, { ...error.details, algorithm });
+        }
+        throw error;
+    }
+}
+/**
+ * Whole-buffer binding of a scratch buffer over its first `size` bytes.
+ * @param buffer - the buffer
+ * @param size - the bound byte length
+ * @returns the binding
+ */
+function bindingOf(buffer, size) {
+    return { buffer, offset: 0, size, window: null };
+}
+/**
+ * The E_ABORTED error of a signal.
+ * @param algorithm - the caller's name
+ * @param batchId - the last submitted batch, when one exists
+ * @returns the error
+ */
+function aborted(algorithm, batchId) {
+    return new WebGpuGraphError("E_ABORTED", `${algorithm}: the signal was aborted`, batchId === undefined ? {} : { batchId });
+}
+/**
+ * The shared driver: `personalization` is the normalised vector of personalizedPageRank or null for the uniform
+ * 1 / n of pageRank.
+ * @param ctx - the context
+ * @param s - the snapshot
+ * @param personalization - the normalised personalization (sum 1), or null
+ * @param options - the PageRank and run options
+ * @param algorithm - the public name, for messages and labels
+ * @returns the result
+ */
+async function run(ctx, s, personalization, options, algorithm) {
+    ctx.assertReady();
+    const n = s.nodeCount;
+    const alpha = options?.dampingFactor ?? 0.85;
+    const maxIterations = options?.maxIterations ?? 100;
+    const tolerance = options?.tolerance ?? 1e-6;
+    const useWeights = options?.weighted !== false;
+    if (!Number.isInteger(maxIterations) || maxIterations < 1) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${algorithm}: maxIterations must be a positive integer`, {
+            argument: "maxIterations",
+            value: maxIterations,
+            expected: "a positive integer",
+        });
+    }
+    const dest = checkDest(options?.dest, n, algorithm);
+    if (options?.signal?.aborted) {
+        throw aborted(algorithm);
+    }
+    if (n === 0) {
+        options?.onProgress?.(maxIterations, maxIterations);
+        return { scores: dest ?? new Float32Array(0), iterations: 0, converged: true, danglingMass: 0, precision: "f32" };
+    }
+    const core = coreOf(ctx, s, algorithm);
+    if (s.arcCount === 0) {
+        // every node is dangling: the whole mass is redistributed by pv each iteration, so pv is the fixed point
+        const scores = dest ?? new Float32Array(n);
+        if (personalization === null) {
+            scores.fill(1 / n);
+        }
+        else {
+            scores.set(personalization);
+        }
+        options?.onProgress?.(maxIterations, maxIterations);
+        return { scores, iterations: 0, converged: true, danglingMass: 1, precision: "f32" };
+    }
+    const view = ctx.residency.view(s, "reverse");
+    const rev = coreOfView(view, view.scalars.arcCount[0]);
+    // weighted: false runs the unweighted algorithm on BOTH sides: the normaliser sums 1 per arc and the pull folds 1
+    const weights = useWeights ? undefined : null;
+    const weightedCore = useWeights ? core : { ...core, weights: null, hasWeights: false };
+    const weightedRev = useWeights ? rev : { ...rev, weights: null, hasWeights: false };
+    const scope = algorithmScope(ctx, algorithm, RING_SLOTS);
+    let uploaded = null;
+    try {
+        const bytes = 4 * n;
+        const rankA = scope.scratch(bytes, "rankA");
+        const rankB = scope.scratch(bytes, "rankB");
+        const xNorm = scope.scratch(bytes, "xNorm");
+        const outWeightSum = scope.scratch(bytes, "outWeightSum");
+        const scalePlan = plan1d(n, ctx.workgroupSize, ctx.caps);
+        const groups = groupsOf(scalePlan);
+        const partialsBytes = PR_PARTIAL.byteLength * (1 + groups);
+        const partials = scope.scratch(partialsBytes, "partials");
+        if (personalization !== null) {
+            uploaded = ctx.residency.array(personalization, `${algorithm}/personalization`);
+        }
+        await ctx.allocator.check();
+        const normaliser = await prepareSegmentedReduce(scope, weightedCore, {
+            op: "sum",
+            valueSnippet: "v = weight;",
+            tiers: null,
+        });
+        const pull = await prepareSpmvPull(scope, weightedRev, {
+            personalization: personalization !== null,
+            dangling: true,
+            weights,
+            tiers: null,
+        });
+        const scale = await ctx.pipelines.kernel(kernelSpec("pr-scale", { NORM_MODE: 0 }));
+        const finalize = await ctx.pipelines.kernel(kernelSpec("pr-finalize", { NORM_MODE: 0 }));
+        const finalizePlan = plan1d(1, ctx.workgroupSize, ctx.caps);
+        const { queue } = ctx.device;
+        queue.writeBuffer(rankA, 0, new Float32Array(n).fill(1 / n));
+        queue.writeBuffer(rankB, 0, new Float32Array(n));
+        const header = new ArrayBuffer(PR_PARTIAL.byteLength);
+        PR_PARTIAL.write(new DataView(header), { firstConverged: U32_MAX, iteration: 0 });
+        queue.writeBuffer(partials, 0, header);
+        const rank = [bindingOf(rankA, bytes), bindingOf(rankB, bytes)];
+        const xNormBinding = bindingOf(xNorm, bytes);
+        const outWeightSumBinding = bindingOf(outWeightSum, bytes);
+        const partialsBinding = bindingOf(partials, partialsBytes);
+        const coefficients = { alpha, beta: 1 - alpha, uniformP: 1 / n };
+        let cur = 0;
+        let iterationsRun = 0;
+        for (;;) {
+            const k = Math.min(PR_BATCH, maxIterations - iterationsRun);
+            const batch = new CommandBatch(ctx, algorithm);
+            const pass = batch.pass("iterations");
+            if (iterationsRun === 0) {
+                normaliser.record(pass, weightedCore, outWeightSumBinding);
+            }
+            for (let i = 0; i < k; i++) {
+                const params = scope.params(PR_PARAMS, {
+                    n,
+                    groups,
+                    iteration: iterationsRun + i + 1,
+                    trackConvergence: 1,
+                    convergeThreshold: tolerance * n,
+                });
+                const other = 1 - cur;
+                const scaleBound = scale.bind({
+                    rankIn: rank[cur],
+                    rankPrev: rank[other],
+                    outWeightSum: outWeightSumBinding,
+                    xNorm: xNormBinding,
+                    partials: partialsBinding,
+                    P: params.binding,
+                });
+                scale.dispatch(pass, scaleBound, scalePlan, [params.offset]);
+                const finalizeBound = finalize.bind({ partials: partialsBinding, P: params.binding });
+                finalize.dispatch(pass, finalizeBound, finalizePlan, [params.offset]);
+                pull.record(pass, weightedRev, {
+                    xNorm: xNormBinding,
+                    rankOut: rank[other],
+                    personalization: uploaded?.binding ?? null,
+                    partials: partialsBinding,
+                }, coefficients);
+                cur = other;
+            }
+            batch.endPass();
+            const headerRequest = batch.readback(partials, 0, PR_PARTIAL.byteLength);
+            const scoresRequest = batch.readback(rank[cur].buffer, 0, bytes);
+            scope.flush();
+            const submitted = batch.submit();
+            const back = await submitted.readback;
+            iterationsRun += k;
+            ctx.assertReady();
+            if (options?.signal?.aborted) {
+                throw aborted(algorithm, submitted.id);
+            }
+            options?.onProgress?.(iterationsRun, maxIterations);
+            const folded = PR_PARTIAL.read(new DataView(back), headerRequest.offset);
+            const firstConverged = folded.firstConverged;
+            const converged = firstConverged !== U32_MAX;
+            if (converged || iterationsRun >= maxIterations) {
+                const scores = dest ?? new Float32Array(n);
+                scores.set(new Float32Array(back, scoresRequest.offset, n));
+                if (converged && iterationsRun < maxIterations) {
+                    options?.onProgress?.(maxIterations, maxIterations);
+                }
+                return {
+                    scores,
+                    iterations: converged ? firstConverged : iterationsRun,
+                    converged,
+                    danglingMass: folded.danglingMass,
+                    precision: "f32",
+                };
+            }
+        }
+    }
+    finally {
+        uploaded?.destroy();
+        scope.dispose();
+    }
+}
+/**
+ * PageRank on the device (spec 3.3, 8.2): NetworkX semantics, f32 scores, `iterations` the first converged
+ * iteration (spec 9.7).
+ * @param ctx - the context whose device runs the kernels
+ * @param s - the snapshot (uploaded through ctx.residency, or found there)
+ * @param options - dampingFactor 0.85 / maxIterations 100 / tolerance 1e-6 / weighted true, plus dest / signal / onProgress
+ * @returns the scores, iterations, converged, danglingMass and precision
+ */
+export function pageRank(ctx, s, options) {
+    return run(ctx, s, null, options, "pageRank");
+}
+/**
+ * Personalized PageRank on the device (spec 3.3, 8.2): the personalization vector replaces the uniform 1 / n in
+ * the teleport and the dangling redistribution; it is normalised to sum 1 on the host.
+ * @param ctx - the context whose device runs the kernels
+ * @param s - the snapshot (uploaded through ctx.residency, or found there)
+ * @param personalization - one finite non-negative mass per node, not all zero
+ * @param options - dampingFactor 0.85 / maxIterations 100 / tolerance 1e-6 / weighted true, plus dest / signal / onProgress
+ * @returns the scores, iterations, converged, danglingMass and precision
+ */
+export async function personalizedPageRank(ctx, s, personalization, options) {
+    const n = s.nodeCount;
+    const invalid = (value, expected) => new WebGpuGraphError("E_INVALID_ARGUMENT", `personalizedPageRank: personalization must be ${expected}`, {
+        argument: "personalization",
+        value,
+        expected,
+    });
+    if (!(personalization instanceof Float32Array) || personalization.length !== n) {
+        throw invalid(`${personalization.constructor.name}(${personalization.length})`, `a Float32Array of length ${n}`);
+    }
+    let total = 0;
+    for (let v = 0; v < n; v++) {
+        const mass = personalization[v];
+        if (!Number.isFinite(mass) || mass < 0) {
+            throw invalid(mass, "finite and non-negative in every entry");
+        }
+        total += mass;
+    }
+    if (n > 0 && !(total > 0)) {
+        throw invalid(total, "a vector whose entries sum to a positive number");
+    }
+    const normalised = new Float32Array(n);
+    for (let v = 0; v < n; v++) {
+        normalised[v] = personalization[v] / total;
+    }
+    return run(ctx, s, normalised, options, "personalizedPageRank");
+}
+//# sourceMappingURL=pagerank.js.map

package/dist/src/algorithms/pagerank.js.map

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

package/dist/src/algorithms/power-iteration.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The power-iteration driver HITS, eigenvector centrality and Katz centrality share (spec 8.2 lines 2603-2605; M8b
+ * plan PD-10): per iteration `pr-scale` at NORM_MODE 1 | 2 | 4 folds the norm term (and the L1 delta) into the
+ * per-workgroup partials, `pr-finalize` folds them into the header at `partials[0]` (the square root for L2) and
+ * records `firstConverged`, `pr-scale` at NORM_MODE 3 writes `xNorm[u] = x[u] / partials[0].norm` (skipped at
+ * mode 4, the identity, where the first scale pass already wrote `xNorm[u] = x[u]`), and `spmv-pull` writes the
+ * next iterate. Four dispatches (three for Katz), all on the device, NO readback inside the batch: the scalar
+ * normaliser the host cannot supply without a readback is exactly what stays on the device, so these three batch
+ * eight iterations per submit like PageRank does.
+ *
+ * The ping-pong is TWO buffers alternated through two cached bind groups (PD-7 / DEP-M8B-G), and `rankPrev` is the
+ * buffer this iteration overwrites: it still holds x(i-2) when `pr-scale` reads it, because the scale runs before
+ * the pull in the same pass (PD-9). With an `alternate` adjacency (HITS, spec 8.2: "alternates two pulls") the
+ * iterations pull over `adjacency` and `alternate` in turn, and the ring is THREE buffers so the buffer being
+ * overwritten holds x(i-3) -- the previous iterate of the same kind -- and the delta stays meaningful. The batch
+ * loop duplicates src/algorithms/pagerank.ts, which its own task owns.
+ */
+import { type F32, type GraphSnapshot } from "@graphty/graph-format";
+import { type GpuContext } from "../context.js";
+import { WebGpuGraphError } from "../errors.js";
+import { type CoreBinding } from "../memory/residency.js";
+import { type Binding } from "../types/memory.js";
+/**
+ * What one power iteration run needs. `adjacency` is the CoreBinding the pull walks -- the forward core for hubs
+ * and eigenvector, coreOfView(view(s, "reverse")) for authorities and Katz (spec 8.2 lines 2603-2606). Exported
+ * for runPowerIteration's signature, not imported by name.
+ * @public
+ */
+export interface PowerIterationConfig {
+    /**
+     * 1 = L1 (sum) normalise, 2 = L2 normalise, 4 = identity (Katz: no normaliser). Never 0 or 3 here: 0 is
+     * PageRank's per-node divisor and 3 is the internal scale pass this driver issues itself.
+     */
+    readonly normMode: 1 | 2 | 4;
+    readonly adjacency: CoreBinding;
+    /**
+     * Null: every iteration pulls over `adjacency`. Non-null: the odd iterations (1, 3, ...) pull over `adjacency`
+     * and the even ones over `alternate`, so x(i) = A_alt * norm(A * norm(x(i-2))) -- one interleaved chain of HITS,
+     * whose hubs and authorities are the last iterates of the two chains (forward-first and reverse-first). The
+     * ring then has three buffers and `weights` must be null or undefined (each core's own weights).
+     */
+    readonly alternate: CoreBinding | null;
+    readonly alpha: number;
+    readonly beta: number;
+    readonly uniformP: number;
+    readonly maxIterations: number;
+    readonly tolerance: number;
+    /** undefined takes the adjacency's weights, null runs UNWEIGHTED on a weighted snapshot (T4 Step 4). */
+    readonly weights: Binding | null | undefined;
+    readonly label: string;
+    readonly signal: AbortSignal | undefined;
+    readonly onProgress: ((done: number, total: number) => void) | undefined;
+}
+/** The iterate, the device-recorded first converged iteration, and the number of iterations actually run. */
+export interface PowerIterationRun {
+    readonly scores: F32;
+    /** x(m - 1) on an alternating run: the chain's last iterate of the OTHER kind (hub or authority); null otherwise. */
+    readonly previous: F32 | null;
+    readonly iterations: number;
+    readonly converged: boolean;
+    readonly iterationsRun: number;
+}
+/**
+ * Validates `options.dest` for a score result of `n` elements.
+ * @param dest - the caller's destination array, if any
+ * @param n - the node count
+ * @param algorithm - the caller's name, for the message
+ * @returns the destination as an F32, or null when none was given
+ */
+export declare function checkDest(dest: Float32Array | Uint32Array | undefined, n: number, algorithm: string): F32 | null;
+/**
+ * The resident core; a windowed plan (`E_TOO_LARGE { path: "windowed", algorithm: null }`, spec 3.8) is re-thrown
+ * with the algorithm name (3.12). Transcribed from degree.ts, whose coreOf is module-private.
+ * @param ctx - the context
+ * @param s - the snapshot
+ * @param algorithm - the caller's name
+ * @returns the core binding
+ */
+export declare function coreOf(ctx: GpuContext, s: GraphSnapshot, algorithm: string): CoreBinding;
+/**
+ * The reverse adjacency as the CoreBinding the pull walks (the forward buffers on an undirected snapshot, PD-13).
+ * @param ctx - the context
+ * @param s - the snapshot (n > 0)
+ * @returns the reverse core
+ */
+export declare function reverseOf(ctx: GpuContext, s: GraphSnapshot): CoreBinding;
+/**
+ * The E_ABORTED error of a signal.
+ * @param algorithm - the caller's name
+ * @param batchId - the last submitted batch, when one exists
+ * @returns the error
+ */
+export declare function aborted(algorithm: string, batchId?: number): WebGpuGraphError;
+/**
+ * Runs the power iteration of `config` over `n` nodes from x(0) = 1 / n, in batches of eight iterations with ONE
+ * readback per batch (the header and the iterate together), stopping at the first batch whose header records a
+ * converged iteration or at `maxIterations`. The returned iterate is RAW: the last `spmv-pull` output, which the
+ * caller normalises once on the host. The iterate travels with the header in EVERY batch, not once after the loop:
+ * whether a batch terminates the run is known only from its header, and a second readback for the iterate would
+ * be a second mapAsync (the plan's case 8 counts exactly one). The cost is 4n bytes (8n on an alternating run) of
+ * staging per batch of 8 that the loop then discards when it continues -- 40 MB per 8 iterations at 10M nodes;
+ * pagerank.ts pays the same.
+ * @param ctx - the context
+ * @param n - the node count (> 0)
+ * @param config - the recurrence, the adjacency and the run options
+ * @returns the raw iterate, the first converged iteration, whether it converged and the iterations actually run
+ */
+export declare function runPowerIteration(ctx: GpuContext, n: number, config: PowerIterationConfig): Promise<PowerIterationRun>;
+//# sourceMappingURL=power-iteration.d.ts.map

package/dist/src/algorithms/power-iteration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"power-iteration.d.ts","sourceRoot":"","sources":["../../../src/algorithms/power-iteration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,KAAK,GAAG,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAGrE,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAIpE,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAG1D,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAQlD;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACjC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wGAAwG;IACxG,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CAC5E;AAED,6GAA6G;AAC7G,MAAM,WAAW,iBAAiB;IAC9B,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC;IACrB,qHAAqH;IACrH,QAAQ,CAAC,QAAQ,EAAE,GAAG,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,YAAY,GAAG,WAAW,GAAG,SAAS,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAgBhH;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,UAAU,EAAE,CAAC,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,CAaxF;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,UAAU,EAAE,CAAC,EAAE,aAAa,GAAG,WAAW,CAGxE;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAM7E;AAYD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CACnC,GAAG,EAAE,UAAU,EACf,CAAC,EAAE,MAAM,EACT,MAAM,EAAE,oBAAoB,GAC7B,OAAO,CAAC,iBAAiB,CAAC,CAiG5B"}

package/dist/src/algorithms/power-iteration.js

@@ -0,0 +1,206 @@
+/**
+ * The power-iteration driver HITS, eigenvector centrality and Katz centrality share (spec 8.2 lines 2603-2605; M8b
+ * plan PD-10): per iteration `pr-scale` at NORM_MODE 1 | 2 | 4 folds the norm term (and the L1 delta) into the
+ * per-workgroup partials, `pr-finalize` folds them into the header at `partials[0]` (the square root for L2) and
+ * records `firstConverged`, `pr-scale` at NORM_MODE 3 writes `xNorm[u] = x[u] / partials[0].norm` (skipped at
+ * mode 4, the identity, where the first scale pass already wrote `xNorm[u] = x[u]`), and `spmv-pull` writes the
+ * next iterate. Four dispatches (three for Katz), all on the device, NO readback inside the batch: the scalar
+ * normaliser the host cannot supply without a readback is exactly what stays on the device, so these three batch
+ * eight iterations per submit like PageRank does.
+ *
+ * The ping-pong is TWO buffers alternated through two cached bind groups (PD-7 / DEP-M8B-G), and `rankPrev` is the
+ * buffer this iteration overwrites: it still holds x(i-2) when `pr-scale` reads it, because the scale runs before
+ * the pull in the same pass (PD-9). With an `alternate` adjacency (HITS, spec 8.2: "alternates two pulls") the
+ * iterations pull over `adjacency` and `alternate` in turn, and the ring is THREE buffers so the buffer being
+ * overwritten holds x(i-3) -- the previous iterate of the same kind -- and the delta stays meaningful. The batch
+ * loop duplicates src/algorithms/pagerank.ts, which its own task owns.
+ */
+import { U32_MAX } from "../constants.js";
+import { isWebGpuGraphError, WebGpuGraphError } from "../errors.js";
+import { CommandBatch } from "../kernel/batch.js";
+import { groupsOf, plan1d } from "../kernel/dispatch.js";
+import { kernelSpec, PR_PARAMS, PR_PARTIAL } from "../kernels.js";
+import { coreOfView } from "../primitives/core-shape.js";
+import { prepareSpmvPull } from "../primitives/spmv.js";
+import { algorithmScope } from "./scope.js";
+/** Iterations per submit (spec 8.2: k = 8). */
+const BATCH = 8;
+/** Params slots of one batch: four blocks per iteration times the batch, plus a margin (the plan's `4 * 8 + 8`). */
+const RING_SLOTS = 4 * BATCH + 8;
+/**
+ * Validates `options.dest` for a score result of `n` elements.
+ * @param dest - the caller's destination array, if any
+ * @param n - the node count
+ * @param algorithm - the caller's name, for the message
+ * @returns the destination as an F32, or null when none was given
+ */
+export function checkDest(dest, n, algorithm) {
+    if (dest === undefined) {
+        return null;
+    }
+    if (dest instanceof Float32Array && dest.length === n && dest.buffer instanceof ArrayBuffer) {
+        return dest;
+    }
+    throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${algorithm}: dest must be a Float32Array of length ${n} over an ArrayBuffer`, {
+        argument: "dest",
+        value: `${dest.constructor.name}(${dest.length})`,
+        expected: `Float32Array(${n}) over an ArrayBuffer`,
+    });
+}
+/**
+ * The resident core; a windowed plan (`E_TOO_LARGE { path: "windowed", algorithm: null }`, spec 3.8) is re-thrown
+ * with the algorithm name (3.12). Transcribed from degree.ts, whose coreOf is module-private.
+ * @param ctx - the context
+ * @param s - the snapshot
+ * @param algorithm - the caller's name
+ * @returns the core binding
+ */
+export function coreOf(ctx, s, algorithm) {
+    try {
+        return ctx.residency.core(s);
+    }
+    catch (error) {
+        if (isWebGpuGraphError(error) && error.code === "E_TOO_LARGE" && error.details.path === "windowed") {
+            throw new WebGpuGraphError("E_TOO_LARGE", `${algorithm}: the arc arrays need a windowed upload, which P1-P3 plan but do not execute`, { ...error.details, algorithm });
+        }
+        throw error;
+    }
+}
+/**
+ * The reverse adjacency as the CoreBinding the pull walks (the forward buffers on an undirected snapshot, PD-13).
+ * @param ctx - the context
+ * @param s - the snapshot (n > 0)
+ * @returns the reverse core
+ */
+export function reverseOf(ctx, s) {
+    const view = ctx.residency.view(s, "reverse");
+    return coreOfView(view, view.scalars.arcCount[0]);
+}
+/**
+ * The E_ABORTED error of a signal.
+ * @param algorithm - the caller's name
+ * @param batchId - the last submitted batch, when one exists
+ * @returns the error
+ */
+export function aborted(algorithm, batchId) {
+    return new WebGpuGraphError("E_ABORTED", `${algorithm}: the signal was aborted`, batchId === undefined ? {} : { batchId });
+}
+/**
+ * Whole-buffer binding of a scratch buffer over its first `size` bytes.
+ * @param buffer - the buffer
+ * @param size - the bound byte length
+ * @returns the binding
+ */
+function whole(buffer, size) {
+    return { buffer, offset: 0, size, window: null };
+}
+/**
+ * Runs the power iteration of `config` over `n` nodes from x(0) = 1 / n, in batches of eight iterations with ONE
+ * readback per batch (the header and the iterate together), stopping at the first batch whose header records a
+ * converged iteration or at `maxIterations`. The returned iterate is RAW: the last `spmv-pull` output, which the
+ * caller normalises once on the host. The iterate travels with the header in EVERY batch, not once after the loop:
+ * whether a batch terminates the run is known only from its header, and a second readback for the iterate would
+ * be a second mapAsync (the plan's case 8 counts exactly one). The cost is 4n bytes (8n on an alternating run) of
+ * staging per batch of 8 that the loop then discards when it continues -- 40 MB per 8 iterations at 10M nodes;
+ * pagerank.ts pays the same.
+ * @param ctx - the context
+ * @param n - the node count (> 0)
+ * @param config - the recurrence, the adjacency and the run options
+ * @returns the raw iterate, the first converged iteration, whether it converged and the iterations actually run
+ */
+export async function runPowerIteration(ctx, n, config) {
+    const scope = algorithmScope(ctx, config.label, RING_SLOTS);
+    try {
+        const bytes = 4 * n;
+        // x(i) lives in ring[i % ring.length]: two buffers for one pull per iteration, three for the alternating pair
+        const ring = (config.alternate === null ? ["rankA", "rankB"] : ["rankA", "rankB", "rankC"]).map((label) => whole(scope.scratch(bytes, label), bytes));
+        const xNorm = whole(scope.scratch(bytes, "xNorm"), bytes);
+        const scalePlan = plan1d(n, ctx.workgroupSize, ctx.caps);
+        const groups = groupsOf(scalePlan);
+        const partialsBytes = PR_PARTIAL.byteLength * (1 + groups);
+        const partialsBuffer = scope.scratch(partialsBytes, "partials");
+        const partials = whole(partialsBuffer, partialsBytes);
+        await ctx.allocator.check();
+        const pullOptions = { personalization: false, dangling: false, weights: config.weights, tiers: null };
+        const pulls = [{ core: config.adjacency, pull: await prepareSpmvPull(scope, config.adjacency, pullOptions) }];
+        if (config.alternate !== null) {
+            pulls.push({ core: config.alternate, pull: await prepareSpmvPull(scope, config.alternate, pullOptions) });
+        }
+        const scaleNorm = await ctx.pipelines.kernel(kernelSpec("pr-scale", { NORM_MODE: config.normMode }));
+        const scaleApply = config.normMode === 4 ? null : await ctx.pipelines.kernel(kernelSpec("pr-scale", { NORM_MODE: 3 }));
+        const finalize = await ctx.pipelines.kernel(kernelSpec("pr-finalize", { NORM_MODE: config.normMode }));
+        const finalizePlan = plan1d(1, ctx.workgroupSize, ctx.caps);
+        const { queue } = ctx.device;
+        queue.writeBuffer(ring[0].buffer, 0, new Float32Array(n).fill(1 / n));
+        for (const slot of ring.slice(1)) {
+            queue.writeBuffer(slot.buffer, 0, new Float32Array(n));
+        }
+        const header = new ArrayBuffer(PR_PARTIAL.byteLength);
+        PR_PARTIAL.write(new DataView(header), { firstConverged: U32_MAX, iteration: 0 });
+        queue.writeBuffer(partialsBuffer, 0, header);
+        const coefficients = { alpha: config.alpha, beta: config.beta, uniformP: config.uniformP };
+        let iterationsRun = 0;
+        for (;;) {
+            const k = Math.min(BATCH, config.maxIterations - iterationsRun);
+            const batch = new CommandBatch(ctx, config.label);
+            const pass = batch.pass("iterations");
+            for (let i = 0; i < k; i++) {
+                const iteration = iterationsRun + i + 1;
+                const params = scope.params(PR_PARAMS, {
+                    n,
+                    groups,
+                    iteration,
+                    trackConvergence: 1,
+                    convergeThreshold: config.tolerance * n,
+                });
+                const rankIn = ring[(iteration - 1) % ring.length];
+                // the slot the pull overwrites still holds x(iteration - ring.length): that is rankPrev (PD-9)
+                const rankOut = ring[iteration % ring.length];
+                const { core, pull } = pulls[(iteration - 1) % pulls.length];
+                // outWeightSum takes rankIn as its dummy: storage-ro, read only under NORM_MODE 0, never compiled here
+                const scaleBindings = { rankIn, rankPrev: rankOut, outWeightSum: rankIn, xNorm, partials, P: params.binding };
+                scaleNorm.dispatch(pass, scaleNorm.bind(scaleBindings), scalePlan, [params.offset]);
+                finalize.dispatch(pass, finalize.bind({ partials, P: params.binding }), finalizePlan, [params.offset]);
+                if (scaleApply !== null) {
+                    scaleApply.dispatch(pass, scaleApply.bind(scaleBindings), scalePlan, [params.offset]);
+                }
+                pull.record(pass, core, { xNorm, rankOut, personalization: null, partials }, coefficients);
+            }
+            batch.endPass();
+            const headerRequest = batch.readback(partialsBuffer, 0, PR_PARTIAL.byteLength);
+            const scoresRequest = batch.readback(ring[(iterationsRun + k) % ring.length].buffer, 0, bytes);
+            // x(m - 1) on an alternating run: the other kind, still intact in the third ring slot
+            const previousRequest = config.alternate === null
+                ? null
+                : batch.readback(ring[(iterationsRun + k - 1) % ring.length].buffer, 0, bytes);
+            scope.flush();
+            const submitted = batch.submit();
+            const back = await submitted.readback; // the ONE mapAsync of the batch (G7 item 5)
+            iterationsRun += k;
+            ctx.assertReady();
+            if (config.signal?.aborted === true) {
+                throw aborted(config.label, submitted.id);
+            }
+            config.onProgress?.(iterationsRun, config.maxIterations);
+            const folded = PR_PARTIAL.read(new DataView(back), headerRequest.offset);
+            const firstConverged = folded.firstConverged;
+            const converged = firstConverged !== U32_MAX;
+            if (converged || iterationsRun >= config.maxIterations) {
+                if (converged && iterationsRun < config.maxIterations) {
+                    config.onProgress?.(config.maxIterations, config.maxIterations);
+                }
+                return {
+                    scores: new Float32Array(back, scoresRequest.offset, n).slice(),
+                    previous: previousRequest === null ? null : new Float32Array(back, previousRequest.offset, n).slice(),
+                    iterations: converged ? firstConverged : iterationsRun,
+                    converged,
+                    iterationsRun,
+                };
+            }
+        }
+    }
+    finally {
+        scope.dispose();
+    }
+}
+//# sourceMappingURL=power-iteration.js.map