@graphty/webgpu-graph-algorithms 0.6.15 → 0.6.17

package/src/primitives/coo-to-csr.ts

@@ -0,0 +1,251 @@
+/**
+ * The `cooToCsr` primitive driver (design 6 row 10; the P11 plan's PD-1): compressed sparse rows built on the device
+ * from `count` arcs `(src[i], dst[i], weights[i])` over `n` nodes. It is the histogram of the sources (over `n + 1`
+ * bins, so the last word is 0), their exclusive scan into `rowPtr` (so `rowPtr[n]` is the arc count) and the
+ * `coo-scatter` of the targets and weights into `colIdx` and `outWeights`.
+ *
+ * The scatter has two modes, and they promise different things:
+ * - `sortedInput: false` is design 6 row 10's cursor scatter. Each arc reserves its slot with an atomic on its row's
+ *   cursor, so slots go out in race order: `rowPtr` is deterministic, but the order inside a row is not, and a row is
+ *   NOT sorted by target even when the input was.
+ * - `sortedInput: true` requires the arcs ordered by source and writes each at its own index minus its row's start:
+ *   no cursor, no atomic, the input order survives into every row, and the output is a pure function of the input.
+ *   Arcs sorted by (source, target) therefore give rows sorted by target -- which every intersection relies on. The
+ *   precondition is checked on the device: an out-of-order source raises word 0 of `out.flag`, which the caller
+ *   must read back and refuse, because unsorted input in this mode gives rows that are silently scrambled.
+ *
+ * A caller who passes unsorted arcs with `sortedInput: true`, or sorted arcs with `sortedInput: false`, and needs
+ * sorted rows gets a graph whose rows are not sorted and whose triangle intersection is then silently wrong.
+ *
+ * A planner over a ReduceScope with a synchronous `record` (the shape of every primitive here), not the design's free
+ * function: pipelines compile once in `prepareCooToCsr`, and `src/primitives/**` never imports `src/context.ts`.
+ */
+
+import { U32_MAX } from "../constants.js";
+import { WebGpuGraphError } from "../errors.js";
+import { plan1d } from "../kernel/dispatch.js";
+import { type Kernel } from "../kernel/kernel.js";
+import { COO_PARAMS, FILL_PARAMS, kernelSpec } from "../kernels.js";
+import { type Binding } from "../types/memory.js";
+import { type HistogramPlanner, prepareHistogram } from "./histogram.js";
+import { type ReduceScope } from "./reduce.js";
+import { prepareScan, type ScanPlanner } from "./scan.js";
+
+/**
+ * The graph `record` writes.
+ * @public
+ */
+export interface CooToCsrOutput {
+    /** `n + 1` words. */
+    readonly rowPtr: Binding;
+    /** At least `count` words. */
+    readonly colIdx: Binding;
+    /** At least `count` f32, or null when the input has no weights. */
+    readonly weights: Binding | null;
+    /** Word 0 is zeroed, then raised to 1 by an out-of-order source under `sortedInput`; a scratch word otherwise. */
+    readonly flag: Binding;
+}
+
+/**
+ * One build: `count` arcs whose sources are below `n`.
+ * @public
+ */
+export interface CooToCsrRecord {
+    readonly src: Binding;
+    readonly dst: Binding;
+    /** One f32 per arc, or null (the output then has no weights). */
+    readonly weights: Binding | null;
+    readonly count: number;
+    readonly n: number;
+    /** The arcs are ordered by source: take the order-preserving scatter (see the file header). */
+    readonly sortedInput: boolean;
+    readonly out: CooToCsrOutput;
+}
+
+/**
+ * A prepared `cooToCsr`.
+ * @public
+ */
+export interface CooToCsrPlanner {
+    /**
+     * Records the histogram, the scan and (for count > 0) the scatter of one build into the pass.
+     * @param pass - the compute pass
+     * @param record - the arcs and the output
+     */
+    record(pass: GPUComputePassEncoder, record: CooToCsrRecord): void;
+}
+
+/**
+ * Compiles the scatter's four variants, the histogram's, the scan's and `fill` so record() is synchronous. The
+ * planner lives as long as the scope: its scratch comes from it.
+ * @param scope - the caller's scope
+ * @returns the planner
+ */
+export async function prepareCooToCsr(scope: ReduceScope): Promise<CooToCsrPlanner> {
+    const histogram = await prepareHistogram(scope);
+    const scan = await prepareScan(scope);
+    const fill = await scope.pipelines.kernel(kernelSpec("fill"));
+    const scatter = new Map<string, Kernel>();
+    for (const sorted of [false, true]) {
+        for (const weighted of [false, true]) {
+            const spec = kernelSpec("coo-scatter", { SORTED_INPUT: sorted, WEIGHTED: weighted });
+            scatter.set(`${sorted}/${weighted}`, await scope.pipelines.kernel(spec));
+        }
+    }
+    return new CooToCsrPlannerImpl(scope, histogram, scan, fill, scatter);
+}
+
+/**
+ * The E_INVALID_ARGUMENT of a binding shorter than `words` u32.
+ * @param name - the argument name
+ * @param binding - the binding
+ * @param words - the words it must hold
+ */
+function checkWords(name: string, binding: Binding, words: number): void {
+    if (binding.size < 4 * words) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `cooToCsr: ${name} is smaller than 4 x ${words} bytes`, {
+            argument: name,
+            value: binding.size,
+            expected: 4 * words,
+        });
+    }
+}
+
+/**
+ * The argument checks of record() (E_INVALID_ARGUMENT before anything is recorded).
+ * @param r - the record
+ */
+function checkRecord(r: CooToCsrRecord): void {
+    for (const [name, value] of [
+        ["count", r.count],
+        ["n", r.n],
+    ] as const) {
+        if (!Number.isSafeInteger(value) || value < 0 || value >= U32_MAX) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", `cooToCsr: ${name} must be an integer in [0, 2^32 - 1)`, {
+                argument: name,
+                value,
+            });
+        }
+    }
+    if ((r.weights === null) !== (r.out.weights === null)) {
+        throw new WebGpuGraphError(
+            "E_INVALID_ARGUMENT",
+            "cooToCsr: weights and out.weights must be both present or both null",
+            {
+                argument: "weights",
+                value: r.weights === null ? "null" : "present",
+                expected: r.out.weights === null ? "null" : "present",
+            },
+        );
+    }
+    checkWords("src", r.src, r.count);
+    checkWords("dst", r.dst, r.count);
+    checkWords("out.rowPtr", r.out.rowPtr, r.n + 1);
+    checkWords("out.colIdx", r.out.colIdx, r.count);
+    checkWords("out.flag", r.out.flag, 1);
+    if (r.weights !== null && r.out.weights !== null) {
+        checkWords("weights", r.weights, r.count);
+        checkWords("out.weights", r.out.weights, r.count);
+    }
+}
+
+/** The planner: the histogram and scan planners, `fill` and the four scatter variants over one scope. */
+class CooToCsrPlannerImpl implements CooToCsrPlanner {
+    private readonly scope: ReduceScope;
+    private readonly histogram: HistogramPlanner;
+    private readonly scan: ScanPlanner;
+    private readonly fill: Kernel;
+    private readonly scatter: ReadonlyMap<string, Kernel>;
+
+    /**
+     * Wraps the resolved planners and kernels; use prepareCooToCsr().
+     * @param scope - the caller's scope
+     * @param histogram - the histogram planner
+     * @param scan - the scan planner
+     * @param fill - the `fill` kernel
+     * @param scatter - the `coo-scatter` variants by `sorted/weighted`
+     */
+    constructor(
+        scope: ReduceScope,
+        histogram: HistogramPlanner,
+        scan: ScanPlanner,
+        fill: Kernel,
+        scatter: ReadonlyMap<string, Kernel>,
+    ) {
+        this.scope = scope;
+        this.histogram = histogram;
+        this.scan = scan;
+        this.fill = fill;
+        this.scatter = scatter;
+    }
+
+    /**
+     * Records one build (see the interface).
+     * @param pass - the compute pass
+     * @param r - the arcs and the output
+     */
+    record(pass: GPUComputePassEncoder, r: CooToCsrRecord): void {
+        checkRecord(r);
+        const { scope } = this;
+        const wg = scope.workgroupSize;
+        const degreeBytes = 4 * (r.n + 1);
+        const degrees: Binding = {
+            buffer: scope.scratch(degreeBytes, "cooToCsr/degrees"),
+            offset: 0,
+            size: degreeBytes,
+            window: null,
+        };
+        this.histogram.record(pass, r.src, r.count, r.n + 1, degrees);
+        this.scan.record(pass, degrees, r.n + 1, r.out.rowPtr);
+        let cursors = r.out.flag;
+        if (r.sortedInput) {
+            this.zero(pass, r.out.flag, 1);
+        } else if (r.n > 0) {
+            const bytes = 4 * r.n;
+            cursors = { buffer: scope.scratch(bytes, "cooToCsr/cursors"), offset: 0, size: bytes, window: null };
+            this.zero(pass, cursors, r.n);
+        }
+        if (r.count === 0) {
+            return;
+        }
+        const weighted = r.weights !== null;
+        const kernel = this.scatter.get(`${r.sortedInput}/${weighted}`);
+        if (kernel === undefined) {
+            throw new WebGpuGraphError("E_INVALID_ARGUMENT", "cooToCsr: no scatter variant was prepared", {
+                argument: "sortedInput",
+                value: r.sortedInput,
+            });
+        }
+        // the unweighted variant never touches the weight slots: a read-only dummy and a writable scratch word
+        const outWeight = r.out.weights ?? {
+            buffer: scope.scratch(4, "cooToCsr/weight-dummy"),
+            offset: 0,
+            size: 4,
+            window: null,
+        };
+        const params = scope.params(COO_PARAMS, { count: r.count, pad0: 0, pad1: 0, pad2: 0 });
+        const bound = kernel.bind({
+            src: r.src,
+            dst: r.dst,
+            weight: r.weights ?? r.dst,
+            rowPtr: r.out.rowPtr,
+            cursors,
+            colIdx: r.out.colIdx,
+            outWeight,
+            P: params.binding,
+        });
+        kernel.dispatch(pass, bound, plan1d(r.count, wg, scope.caps), [params.offset]);
+    }
+
+    /**
+     * Records a `fill` of `words` zeros.
+     * @param pass - the compute pass
+     * @param dst - the words
+     * @param words - how many (>= 1)
+     */
+    private zero(pass: GPUComputePassEncoder, dst: Binding, words: number): void {
+        const params = this.scope.params(FILL_PARAMS, { count: words, value: 0, mode: 0, pad0: 0 });
+        const bound = this.fill.bind({ dst, P: params.binding });
+        this.fill.dispatch(pass, bound, plan1d(words, this.scope.workgroupSize, this.scope.caps), [params.offset]);
+    }
+}

package/src/primitives/group-by-key.ts

@@ -0,0 +1,209 @@
+/**
+ * The per-row group-by-key primitive (design 8.6; the P11 plan's PD-8): for every row `v` of a CSR graph, group the
+ * row's arcs by the key of their target (`keyIn[colIdx[a]]`), sum the weights per key, and write the key with the
+ * largest sum to `bestKey[v]` -- the LOWEST such key on a tie, which makes the answer independent of the visiting
+ * order -- and its summed weight to `bestScore[v]`. An empty row gets `INVALID_INDEX` and 0. Label propagation's step
+ * is its first caller: the best key of a row is the weighted mode of the neighbours' labels.
+ *
+ * Sums are u32 fixed point at a per-row power-of-two scale (the kernel header says how), so the two tiers and any
+ * reference that follows the same arithmetic agree bitwise. A key must be below `INVALID_INDEX`.
+ *
+ * Two tiers, chosen per row on the host from an upper bound of each row's length (`planGroupRows`):
+ * - TIER 0, a thread per row, for rows of at most `threadMax` arcs (GROUP_ROW_THREAD_MAX by default): a pairwise scan
+ *   in registers, no workgroup memory, no barrier.
+ * - TIER 1, a workgroup per row, for the rest: the row's keys are hashed into its own region of
+ *   `GROUP_HASH_LOAD_FACTOR x length` slots of `hashRegion`, then the workgroup reduces the slots to the best one.
+ *
+ * PLAN DECISION (the P11 plan, PD-8): the plan's small tier sorted a row of up to 256 arcs in workgroup memory with a
+ * bitonic sort, one workgroup per row; this tier is a thread per row instead, because a workgroup of 256 lanes spent
+ * on a row of ten arcs -- the typical row -- idles 246 of them, and the pairwise scan needs no barrier at all. Rows
+ * above GROUP_ROW_THREAD_MAX take the workgroup hash tier, which is the plan's large tier unchanged.
+ */
+
+import { GROUP_HASH_LOAD_FACTOR, GROUP_ROW_THREAD_LIMIT, GROUP_ROW_THREAD_MAX } from "../constants.js";
+import { WebGpuGraphError } from "../errors.js";
+import { plan1d, plan2d } from "../kernel/dispatch.js";
+import { type Kernel } from "../kernel/kernel.js";
+import { GROUP_PARAMS, kernelSpec } from "../kernels.js";
+import { type Binding } from "../types/memory.js";
+import { type ReduceScope } from "./reduce.js";
+
+/**
+ * The rows of each tier, as the host planned them: upload `words` into the `rows` binding and size `hashRegion` by `regionWords`.
+ * @public
+ */
+export interface GroupRows {
+    /** The thread tier's rows, then the workgroup tier's rows, then each workgroup-tier row's region offset (in words of `hashRegion`). */
+    readonly words: Uint32Array<ArrayBuffer>;
+    readonly threadCount: number;
+    readonly hashCount: number;
+    /** The words of `hashRegion`: word 0 is the exhausted flag, then two words (key, sum) per slot of every workgroup-tier row. */
+    readonly regionWords: number;
+}
+
+/**
+ * Splits the rows into the two tiers from an upper bound of every row's length (the exact length works too; a bound
+ * only costs region space): rows whose bound is at most `threadMax` go to the thread tier, the rest to the workgroup
+ * tier with `GROUP_HASH_LOAD_FACTOR x bound` slots each.
+ * @param lengthBound - an upper bound of every row's arc count, one per row
+ * @param threadMax - the longest row the thread tier takes (0 sends every row to the workgroup tier; at most GROUP_ROW_THREAD_LIMIT)
+ * @returns the plan
+ */
+export function planGroupRows(lengthBound: ArrayLike<number>, threadMax: number = GROUP_ROW_THREAD_MAX): GroupRows {
+    if (!Number.isInteger(threadMax) || threadMax < 0 || threadMax > GROUP_ROW_THREAD_LIMIT) {
+        throw new WebGpuGraphError(
+            "E_INVALID_ARGUMENT",
+            `planGroupRows: threadMax must be an integer in [0, ${GROUP_ROW_THREAD_LIMIT}]`,
+            { argument: "threadMax", value: threadMax, expected: `[0, ${GROUP_ROW_THREAD_LIMIT}]` },
+        );
+    }
+    const n = lengthBound.length;
+    const thread: number[] = [];
+    const hash: number[] = [];
+    for (let v = 0; v < n; v++) {
+        (lengthBound[v] <= threadMax ? thread : hash).push(v);
+    }
+    const words = new Uint32Array(thread.length + 2 * hash.length);
+    words.set(thread, 0);
+    words.set(hash, thread.length);
+    let next = 1;
+    for (let g = 0; g < hash.length; g++) {
+        words[thread.length + hash.length + g] = next;
+        next += 2 * GROUP_HASH_LOAD_FACTOR * lengthBound[hash[g]];
+    }
+    return { words, threadCount: thread.length, hashCount: hash.length, regionWords: next };
+}
+
+/**
+ * One grouping over a graph.
+ * @public
+ */
+export interface GroupByKeyRecord {
+    readonly rowPtr: Binding;
+    readonly colIdx: Binding;
+    /** One f32 per arc, or null (every arc weighs 1). */
+    readonly weights: Binding | null;
+    /** One key per node, each below `INVALID_INDEX`. */
+    readonly keyIn: Binding;
+    /** The plan's counts; its `words` must be what `rows` holds. */
+    readonly plan: GroupRows;
+    readonly rows: Binding;
+    /** At least `plan.regionWords` words; word 0 must be zeroed by the caller once, and is 1 afterwards iff a probe loop exhausted its bound. */
+    readonly hashRegion: Binding;
+    readonly bestKey: Binding;
+    readonly bestScore: Binding;
+}
+
+/**
+ * A prepared group-by-key.
+ * @public
+ */
+export interface GroupByKeyPlanner {
+    /**
+     * Records the (up to two) tier dispatches of one grouping into the pass.
+     * @param pass - the compute pass
+     * @param record - the graph, the keys, the tier plan and the outputs
+     */
+    record(pass: GPUComputePassEncoder, record: GroupByKeyRecord): void;
+}
+
+/**
+ * Compiles the four variants (two tiers, weighted or not) so record() is synchronous.
+ * @param scope - the caller's scope
+ * @returns the planner
+ */
+export async function prepareGroupByKeyRow(scope: ReduceScope): Promise<GroupByKeyPlanner> {
+    const kernels = new Map<string, Kernel>();
+    for (const tier of [0, 1]) {
+        for (const weighted of [false, true]) {
+            const spec = kernelSpec("group-by-key-row", { TIER: tier, WEIGHTED: weighted });
+            kernels.set(`${tier}/${weighted}`, await scope.pipelines.kernel(spec));
+        }
+    }
+    return new GroupByKeyPlannerImpl(scope, kernels);
+}
+
+/**
+ * The E_INVALID_ARGUMENT of a binding shorter than `words` u32.
+ * @param name - the argument name
+ * @param binding - the binding
+ * @param words - the words it must hold
+ */
+function checkWords(name: string, binding: Binding, words: number): void {
+    if (binding.size < 4 * words) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `groupByKeyRow: ${name} is smaller than 4 x ${words} bytes`, {
+            argument: name,
+            value: binding.size,
+            expected: 4 * words,
+        });
+    }
+}
+
+/** The planner: the four variants over one scope. */
+class GroupByKeyPlannerImpl implements GroupByKeyPlanner {
+    private readonly scope: ReduceScope;
+    private readonly kernels: ReadonlyMap<string, Kernel>;
+
+    /**
+     * Wraps the compiled variants; use prepareGroupByKeyRow().
+     * @param scope - the caller's scope
+     * @param kernels - the variants by `tier/weighted`
+     */
+    constructor(scope: ReduceScope, kernels: ReadonlyMap<string, Kernel>) {
+        this.scope = scope;
+        this.kernels = kernels;
+    }
+
+    /**
+     * Records the tier dispatches (see the interface).
+     * @param pass - the compute pass
+     * @param r - the record
+     */
+    record(pass: GPUComputePassEncoder, r: GroupByKeyRecord): void {
+        const { threadCount, hashCount } = r.plan;
+        const rows = threadCount + hashCount;
+        checkWords("rows", r.rows, rows + hashCount);
+        checkWords("hashRegion", r.hashRegion, r.plan.regionWords);
+        checkWords("rowPtr", r.rowPtr, rows + 1);
+        if (rows === 0) {
+            return;
+        }
+        const weighted = r.weights !== null;
+        const tiers: readonly (readonly [0 | 1, number, number])[] = [
+            [0, 0, threadCount],
+            [1, threadCount, hashCount],
+        ];
+        for (const [tier, rowsBase, count] of tiers) {
+            if (count === 0) {
+                continue;
+            }
+            const kernel = this.kernels.get(`${tier}/${weighted}`);
+            if (kernel === undefined) {
+                throw new WebGpuGraphError("E_INVALID_ARGUMENT", "groupByKeyRow: no variant was prepared", {
+                    argument: "tier",
+                    value: tier,
+                });
+            }
+            const params = this.scope.params(GROUP_PARAMS, {
+                rowsBase,
+                basesBase: threadCount + hashCount,
+                count,
+                pad0: 0,
+            });
+            const bound = kernel.bind({
+                rowPtr: r.rowPtr,
+                colIdx: r.colIdx,
+                weights: r.weights ?? r.colIdx,
+                keyIn: r.keyIn,
+                rows: r.rows,
+                hashRegion: r.hashRegion,
+                bestKey: r.bestKey,
+                bestScore: r.bestScore,
+                P: params.binding,
+            });
+            const plan =
+                tier === 0 ? plan1d(count, this.scope.workgroupSize, this.scope.caps) : plan2d(count, this.scope.caps);
+            kernel.dispatch(pass, bound, plan, [params.offset]);
+        }
+    }
+}

package/src/types/accelerator.ts

@@ -42,6 +42,7 @@ import type {
     KatzOptions,
     PageRankOptions,
 } from "./algorithms.js";
+import type { GpuApspResult } from "./all-pairs.js";
 import type { GpuBetweennessResult, GpuEdgeScoresResult } from "./betweenness.js";
 import type {
     ForceAtlas2Stats,
@@ -51,6 +52,7 @@ import type {
     SpringElectricalStats,
 } from "./layout.js";
 import type { ForceAtlas2Options, FruchtermanReingoldOptions, SpringElectricalOptions } from "./options.js";
+import type { GpuTriangleResult } from "./structure.js";
 import type { GpuBellmanFordResult, GpuBfsResult, GpuSsspResult } from "./traversal.js";
 
 // ---- the real @graphty/layout interfaces (spec 9.3, D27): imported at W1b, re-exported so the package's public
@@ -115,8 +117,11 @@ export interface AcceleratorOptions {
  * take the seam's OWN option types (PD-19: `BfsOptions`, `SsspOptions` for both `sssp` and `bellmanFord`,
  * `ClosenessAcceleratorOptions` for `closenessCentrality`), so a key the CPU dispatcher forwards is exactly a key the GPU reads;
  * `test/types/conformance.test-d.ts` holds each parameter EQUAL to the seam's, not merely assignable. The two
- * betweenness members take the seam's `BetweennessAcceleratorOptions`. Later phases add one member per shipped
- * algorithm.
+ * betweenness members take the seam's `BetweennessAcceleratorOptions`. `allPairsShortestPath` (design 8.7) takes the
+ * seam's `SsspOptions` too and refuses both of its keys. P11 adds `triangleCount` (its result carries `coefficient`
+ * and `transitivity` beyond the seam's `{ perNode, total }`, which a wider object satisfies) and `labelPropagation`
+ * (the seam's `HitsOptionsLike`: `maxIterations` and `weighted` honoured, `tolerance` refused). Later phases add one
+ * member per shipped algorithm.
  * Exported: implemented by src/accelerator.ts (P3-T3); re-exported from src/index.ts at P3-T3.
  * @public
  */
@@ -148,6 +153,9 @@ export interface GpuAccelerator extends AlgorithmAccelerator, LayoutAccelerator
     closenessCentrality(s: GraphSnapshot, options?: ClosenessAcceleratorOptions): Promise<GpuClosenessResult>;
     betweennessCentrality(s: GraphSnapshot, options?: BetweennessAcceleratorOptions): Promise<GpuBetweennessResult>;
     edgeBetweennessCentrality(s: GraphSnapshot, options?: BetweennessAcceleratorOptions): Promise<GpuEdgeScoresResult>;
+    allPairsShortestPath(s: GraphSnapshot, options?: SsspOptions): Promise<GpuApspResult>;
+    triangleCount(s: GraphSnapshot): Promise<GpuTriangleResult>;
+    labelPropagation(s: GraphSnapshot, options?: HitsOptionsLike): Promise<GpuLabelResult>;
     release(s: GraphSnapshot): void;
     dispose(): void;
 }

package/src/types/all-pairs.ts

@@ -0,0 +1,37 @@
+/**
+ * The all-pairs shortest-path result and option records (design 3.3 lines 813 and 835, 8.7, 9.7). The result is the
+ * design's shape verbatim; every sentinel is spelled on its field, because a consumer who reads a `0` off the diagonal
+ * or an `Infinity` off the matrix and guesses what it means is the failure this file prevents. Types only: this file
+ * imports nothing at runtime.
+ */
+
+import type { F32 } from "@graphty/graph-format";
+
+/**
+ * Design 3.3 line 835: what `allPairsShortestPath` returns. Satisfies the seam's `ApspResultLike` (`dist:
+ * NumericVector` admits `F32`).
+ * @public
+ */
+export interface GpuApspResult {
+    /**
+     * The `n * n` distances, row-major: `dist[i * n + j]` is the shortest distance FROM `i` TO `j` (the i-to-j
+     * direction on a directed snapshot). `+Infinity` when `j` is unreachable from `i`. The diagonal is `0` even when
+     * a self-loop carries a weight. f32 throughout; hop counts are exact integers.
+     */
+    readonly dist: F32;
+    /** The node count; `dist.length === n * n`. */
+    readonly n: number;
+}
+
+/**
+ * The options of `allPairsShortestPath` beyond `GpuRunOptions`. Nothing else: a cutoff would change the meaning of
+ * `+Infinity`, and the design asks for none.
+ * @public
+ */
+export interface ApspOptions {
+    /**
+     * Use the snapshot's weight column. Default: true when the snapshot has weights. `false` on a weighted snapshot
+     * computes HOP COUNTS (every arc costs 1), not distances.
+     */
+    readonly weighted?: boolean | undefined;
+}

package/src/types/community.ts

@@ -0,0 +1,18 @@
+/**
+ * The option record of label propagation (design 3.3 line 807, 8.6). Types only.
+ */
+
+/**
+ * Label propagation's options. Ties between neighbour labels are broken by the LOWEST label, never at random, so
+ * the result is bitwise reproducible on one device; that is also why there is no `randomSeed`.
+ * @public
+ */
+export interface LabelPropagationOptions {
+    /** The largest number of passes (default 100, as in `@graphty/algorithms`); a non-negative integer. */
+    readonly maxIterations?: number | undefined;
+    /**
+     * Sum the weights of the edges to each neighbour label (default true; an unweighted snapshot's edges weigh 1
+     * each, so a parallel edge counts once per copy); false counts every distinct neighbour once.
+     */
+    readonly weighted?: boolean | undefined;
+}

package/src/types/structure.ts

@@ -0,0 +1,28 @@
+/**
+ * The result record of triangle counting (design 3.3 line 828, 8.5; design 17 line 5067). Design 3.3 declares
+ * `{ perNode, total }`; this package also returns the clustering coefficient and the transitivity, because they are
+ * an epilogue over the counts and degrees the call already holds and nothing else in the monorepo computes them.
+ * Types only.
+ */
+
+import type { F32, U32 } from "@graphty/graph-format";
+
+/**
+ * Triangle counting over the simple undirected graph underlying the snapshot: arc directions are ignored, parallel
+ * edges count once and self-loops not at all, so a directed snapshot and its undirected twin give the same answer.
+ * @public
+ */
+export interface GpuTriangleResult {
+    /** The triangles each node lies in. */
+    readonly perNode: U32;
+    /** The triangles of the graph (each counted once). */
+    readonly total: number;
+    /**
+     * The local clustering coefficient of every node, `2 T(v) / (d(v) (d(v) - 1))` with `d` the node's number of
+     * distinct neighbours. It is 0 -- a defined value, not a missing one -- for a node with fewer than two
+     * neighbours, so a star graph returns all zeros.
+     */
+    readonly coefficient: F32;
+    /** The graph's transitivity, `3 x triangles / connected triples`; 0 when the graph has no connected triple. */
+    readonly transitivity: number;
+}