@graphty/webgpu-graph-algorithms 0.6.14 → 0.6.16

package/dist/src/algorithms/label-propagation.js

@@ -0,0 +1,254 @@
+/**
+ * Label propagation (design 8.6, 3.3 line 807; the P11 plan's P11-T6) over the simple symmetric graph of the
+ * snapshot (`buildSimpleSymmetric`). Every vertex starts with its own index as its label; each pass,
+ * `group-by-key-row` finds every vertex's weighted mode of its neighbours' labels (the lowest label on a tie) and
+ * `lpa-step` adopts it synchronously -- but only in the pass's direction: down to a lower label on even passes, up to
+ * a higher one on odd passes (cuGraph's swap-avoidance rule), which is what stops two neighbours trading labels
+ * forever. A pass that moves nothing in either direction after one that moved nothing in the other is a fixed point,
+ * and the run stops there or at `maxIterations` passes.
+ *
+ * Passes are recorded LABEL_PROP_PASSES_PER_SUBMIT to a submit with one readback of their move counts, because a
+ * readback per pass costs more than the passes on a small graph; the passes after the fixed point inside the last
+ * submit change nothing, so the labels are those of the fixed point. The first submit is the graph build's second.
+ * The labels are renumbered in first-seen order on the host (`renumberPartition`), as connected components' are.
+ *
+ * The result is bitwise reproducible on one device and between devices: the grouping is order-independent and every
+ * sum is an integer.
+ */
+import { renumberPartition } from "@graphty/graph-format";
+import { LABEL_PROP_PASSES_PER_SUBMIT } from "../constants.js";
+import { WebGpuGraphError } from "../errors.js";
+import { CommandBatch } from "../kernel/batch.js";
+import { plan1d } from "../kernel/dispatch.js";
+import { FILL_PARAMS, kernelSpec, LPA_PARAMS } from "../kernels.js";
+import { planGroupRows, prepareGroupByKeyRow } from "../primitives/group-by-key.js";
+import { assertDeviceComputes } from "../primitives/verify.js";
+import { labelResult } from "./components.js";
+import { algorithmScope } from "./scope.js";
+import { assertBindable, assertBuildSorted, buildSimpleSymmetric } from "./simple-symmetric.js";
+const ALGORITHM = "labelPropagation";
+/** The default pass cap, as in `@graphty/algorithms`' labelPropagation. */
+const DEFAULT_MAX_ITERATIONS = 100;
+/** Params slots of the largest batch: the graph build's second submit plus one batch of passes. */
+const RING_SLOTS = 1024;
+/**
+ * Validates `options.dest` for a label result of `n` elements.
+ * @param dest - the caller's destination array, if any
+ * @param n - the node count
+ * @returns the destination as a U32, or null when none was given
+ */
+function checkDest(dest, n) {
+    if (dest === undefined) {
+        return null;
+    }
+    if (dest instanceof Uint32Array && dest.length === n && dest.buffer instanceof ArrayBuffer) {
+        return dest;
+    }
+    throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${ALGORITHM}: dest must be a Uint32Array of length ${n} over an ArrayBuffer`, {
+        argument: "dest",
+        value: `${dest.constructor.name}(${dest.length})`,
+        expected: `Uint32Array(${n}) over an ArrayBuffer`,
+    });
+}
+/**
+ * The pass cap.
+ * @param value - options.maxIterations
+ * @returns the cap
+ */
+function maxIterationsOf(value) {
+    if (value === undefined) {
+        return DEFAULT_MAX_ITERATIONS;
+    }
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new WebGpuGraphError("E_INVALID_ARGUMENT", `${ALGORITHM}: maxIterations must be a non-negative integer`, {
+            argument: "maxIterations",
+            value,
+            expected: "a non-negative integer",
+        });
+    }
+    return value;
+}
+/**
+ * An upper bound of every vertex's number of distinct neighbours in the simple symmetric graph: its arcs in both
+ * directions, which the merge of parallel edges and the drop of self-loops can only shrink.
+ * @param s - the snapshot
+ * @returns one bound per vertex
+ */
+function neighbourBound(s) {
+    const out = s.outDegree();
+    if (!s.directed) {
+        return out;
+    }
+    const inDegree = s.inDegree();
+    const bound = new Uint32Array(s.nodeCount);
+    for (let v = 0; v < bound.length; v++) {
+        bound[v] = out[v] + inDegree[v];
+    }
+    return bound;
+}
+/**
+ * The labels as a result: every label must be a node index (a device bug otherwise), then renumbered first-seen.
+ * @param raw - the labels the device produced
+ * @param dest - the caller's destination, if any
+ * @returns the result
+ */
+function resultOf(raw, dest) {
+    const n = raw.length;
+    for (let v = 0; v < n; v++) {
+        if (raw[v] >= n) {
+            throw new WebGpuGraphError("E_VALIDATION", `${ALGORITHM}: labels[${v}] = ${raw[v]} is not a node index`, {
+                label: `${ALGORITHM}/labels`,
+                message: `the device produced a label outside [0, ${n})`,
+            });
+        }
+    }
+    const { labels, count } = renumberPartition(raw, dest ?? undefined);
+    return labelResult(labels, count);
+}
+/**
+ * The identity labelling: every vertex its own community.
+ * @param n - the node count
+ * @param dest - the caller's destination, if any
+ * @returns the result
+ */
+function identityResult(n, dest) {
+    const labels = dest ?? new Uint32Array(n);
+    for (let v = 0; v < n; v++) {
+        labels[v] = v;
+    }
+    return labelResult(labels, n);
+}
+/**
+ * Label propagation on the device (see the file header).
+ * @param ctx - the context whose device runs the kernels
+ * @param s - the snapshot (its edge list is uploaded through ctx.residency, or found there)
+ * @param options - maxIterations (default 100), weighted (default true), plus dest / signal / onProgress
+ * @returns the labels, dense in first-seen order, the community count and groups()
+ */
+export async function labelPropagation(ctx, s, options) {
+    ctx.assertReady();
+    await assertDeviceComputes(ctx);
+    const n = s.nodeCount;
+    const dest = checkDest(options?.dest, n);
+    const maxIterations = maxIterationsOf(options?.maxIterations);
+    const weighted = options?.weighted !== false;
+    if (options?.signal?.aborted) {
+        throw new WebGpuGraphError("E_ABORTED", `${ALGORITHM}: the signal was aborted before any work started`, {});
+    }
+    if (n === 0 || s.edgeCount === 0 || maxIterations === 0) {
+        options?.onProgress?.(1, 1);
+        return identityResult(n, dest);
+    }
+    // the hash region of the workgroup tier is bound whole: refuse a graph it outgrows before any device work
+    const plan = planGroupRows(neighbourBound(s));
+    assertBindable(ctx, 4 * plan.regionWords, "the group-by hash region", ALGORITHM);
+    const scope = algorithmScope(ctx, ALGORITHM, RING_SLOTS);
+    try {
+        const build = await buildSimpleSymmetric(ctx, s, scope, weighted, ALGORITHM);
+        const { graph } = build;
+        if (graph.colIdx === null) {
+            // only self-loops: no vertex has a neighbour, so nothing ever moves
+            scope.flush();
+            const bytes = await build.batch.submit().readback;
+            ctx.assertReady();
+            assertBuildSorted(bytes, build, ALGORITHM);
+            options?.onProgress?.(1, 1);
+            return identityResult(n, dest);
+        }
+        const wg = ctx.workgroupSize;
+        const words = (count, label) => {
+            const size = 4 * Math.max(1, count);
+            return { buffer: scope.scratch(size, label), offset: 0, size, window: null };
+        };
+        const rows = words(plan.words.length, "rows");
+        const region = words(plan.regionWords, "hashRegion");
+        const labelsA = words(n, "labelsA");
+        const labelsB = words(n, "labelsB");
+        const bestKey = words(n, "bestKey");
+        const bestScore = words(n, "bestScore");
+        const counters = words(LABEL_PROP_PASSES_PER_SUBMIT, "counters");
+        await ctx.allocator.check();
+        const { queue } = ctx.device;
+        queue.writeBuffer(rows.buffer, 0, plan.words);
+        queue.writeBuffer(region.buffer, 0, new Uint32Array(1));
+        const groupBy = await prepareGroupByKeyRow(scope);
+        const step = await ctx.pipelines.kernel(kernelSpec("lpa-step"));
+        const fill = await ctx.pipelines.kernel(kernelSpec("fill"));
+        const nodePlan = plan1d(n, wg, ctx.caps);
+        let { batch } = build;
+        let first = true;
+        let cur = labelsA;
+        let next = labelsB;
+        let done = 0;
+        let previousLast = -1;
+        for (;;) {
+            const k = Math.min(LABEL_PROP_PASSES_PER_SUBMIT, maxIterations - done);
+            queue.writeBuffer(counters.buffer, 0, new Uint32Array(k));
+            const pass = batch.pass("passes");
+            if (first) {
+                const iota = scope.params(FILL_PARAMS, { count: n, value: 0, mode: 1, pad0: 0 });
+                fill.dispatch(pass, fill.bind({ dst: labelsA, P: iota.binding }), nodePlan, [iota.offset]);
+            }
+            for (let i = 0; i < k; i++) {
+                groupBy.record(pass, {
+                    rowPtr: graph.rowPtr,
+                    colIdx: graph.colIdx,
+                    weights: weighted ? graph.weights : null,
+                    keyIn: cur,
+                    plan,
+                    rows,
+                    hashRegion: region,
+                    bestKey,
+                    bestScore,
+                });
+                const params = scope.params(LPA_PARAMS, {
+                    n,
+                    direction: (done + i) % 2,
+                    counterIndex: i,
+                    pad0: 0,
+                });
+                step.dispatch(pass, step.bind({ labelsIn: cur, bestKey, labelsOut: next, counters, P: params.binding }), nodePlan, [params.offset]);
+                [cur, next] = [next, cur];
+            }
+            batch.endPass();
+            const movesRequest = batch.readback(counters.buffer, 0, 4 * k);
+            const exhaustedRequest = batch.readback(region.buffer, 0, 4);
+            scope.flush();
+            const submitted = batch.submit();
+            const bytes = await submitted.readback;
+            ctx.assertReady();
+            if (first) {
+                assertBuildSorted(bytes, build, ALGORITHM);
+                first = false;
+            }
+            if (new Uint32Array(bytes, exhaustedRequest.offset, 1)[0] !== 0) {
+                throw new WebGpuGraphError("E_VALIDATION", `${ALGORITHM}: a hash probe exhausted its bound`, {
+                    label: `${ALGORITHM}/group-by-key`,
+                    message: "a compare-exchange loop of the workgroup tier ran out of steps",
+                });
+            }
+            const moves = new Uint32Array(bytes, movesRequest.offset, k);
+            done += k;
+            const lastTwo = k >= 2 ? moves[k - 2] + moves[k - 1] : previousLast + moves[0];
+            previousLast = moves[k - 1];
+            if (options?.signal?.aborted) {
+                throw new WebGpuGraphError("E_ABORTED", `${ALGORITHM}: the signal was aborted`, {
+                    batchId: submitted.id,
+                });
+            }
+            options?.onProgress?.(done, maxIterations);
+            if (lastTwo === 0 || done >= maxIterations) {
+                break;
+            }
+            batch = new CommandBatch(ctx, `${ALGORITHM}/passes`);
+        }
+        const raw = new Uint32Array(n);
+        await ctx.readback.read(cur.buffer, 4 * n, raw);
+        ctx.assertReady();
+        return resultOf(raw, dest);
+    }
+    finally {
+        scope.dispose();
+    }
+}
+//# sourceMappingURL=label-propagation.js.map

package/dist/src/algorithms/label-propagation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"label-propagation.js","sourceRoot":"","sources":["../../../src/algorithms/label-propagation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAsB,iBAAiB,EAAY,MAAM,uBAAuB,CAAC;AAExF,OAAO,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAE/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AACpF,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAK/D,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAEhG,MAAM,SAAS,GAAG,kBAAkB,CAAC;AACrC,2EAA2E;AAC3E,MAAM,sBAAsB,GAAG,GAAG,CAAC;AACnC,mGAAmG;AACnG,MAAM,UAAU,GAAG,IAAI,CAAC;AAExB;;;;;GAKG;AACH,SAAS,SAAS,CAAC,IAA4C,EAAE,CAAS;IACtE,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,IAAI,IAAI,YAAY,WAAW,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,YAAY,WAAW,EAAE,CAAC;QACzF,OAAO,IAAW,CAAC;IACvB,CAAC;IACD,MAAM,IAAI,gBAAgB,CACtB,oBAAoB,EACpB,GAAG,SAAS,0CAA0C,CAAC,sBAAsB,EAC7E;QACI,QAAQ,EAAE,MAAM;QAChB,KAAK,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG;QACjD,QAAQ,EAAE,eAAe,CAAC,uBAAuB;KACpD,CACJ,CAAC;AACN,CAAC;AAED;;;;GAIG;AACH,SAAS,eAAe,CAAC,KAAyB;IAC9C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,sBAAsB,CAAC;IAClC,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,gBAAgB,CAAC,oBAAoB,EAAE,GAAG,SAAS,gDAAgD,EAAE;YAC3G,QAAQ,EAAE,eAAe;YACzB,KAAK;YACL,QAAQ,EAAE,wBAAwB;SACrC,CAAC,CAAC;IACP,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,SAAS,cAAc,CAAC,CAAgB;IACpC,MAAM,GAAG,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC;IAC1B,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,GAAG,CAAC;IACf,CAAC;IACD,MAAM,QAAQ,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC9B,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC3C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,KAAK,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,SAAS,QAAQ,CAAC,GAAQ,EAAE,IAAgB;IACxC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC;IACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACzB,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;YACd,MAAM,IAAI,gBAAgB,CAAC,cAAc,EAAE,GAAG,SAAS,YAAY,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,sBAAsB,EAAE;gBACrG,KAAK,EAAE,GAAG,SAAS,SAAS;gBAC5B,OAAO,EAAE,2CAA2C,CAAC,GAAG;aAC3D,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IACD,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,iBAAiB,CAAC,GAAG,EAAE,IAAI,IAAI,SAAS,CAAC,CAAC;IACpE,OAAO,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AACtC,CAAC;AAED;;;;;GAKG;AACH,SAAS,cAAc,CAAC,CAAS,EAAE,IAAgB;IAC/C,MAAM,MAAM,GAAG,IAAI,IAAI,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC;IAC1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACzB,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAClC,GAAe,EACf,CAAgB,EAChB,OAAiD;IAEjD,GAAG,CAAC,WAAW,EAAE,CAAC;IAClB,MAAM,oBAAoB,CAAC,GAAG,CAAC,CAAC;IAChC,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC;IACtB,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACzC,MAAM,aAAa,GAAG,eAAe,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IAC9D,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,KAAK,KAAK,CAAC;IAC7C,IAAI,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QAC3B,MAAM,IAAI,gBAAgB,CAAC,WAAW,EAAE,GAAG,SAAS,kDAAkD,EAAE,EAAE,CAAC,CAAC;IAChH,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,SAAS,KAAK,CAAC,IAAI,aAAa,KAAK,CAAC,EAAE,CAAC;QACtD,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC5B,OAAO,cAAc,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;IACD,0GAA0G;IAC1G,MAAM,IAAI,GAAG,aAAa,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9C,cAAc,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE,0BAA0B,EAAE,SAAS,CAAC,CAAC;IACjF,MAAM,KAAK,GAAG,cAAc,CAAC,GAAG,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IACzD,IAAI,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,oBAAoB,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;QAC7E,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;QACxB,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YACxB,oEAAoE;YACpE,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC;YAClD,GAAG,CAAC,WAAW,EAAE,CAAC;YAClB,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;YAC3C,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YAC5B,OAAO,cAAc,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QACnC,CAAC;QACD,MAAM,EAAE,GAAG,GAAG,CAAC,aAAa,CAAC;QAC7B,MAAM,KAAK,GAAG,CAAC,KAAa,EAAE,KAAa,EAAW,EAAE;YACpD,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;YACpC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;QACjF,CAAC,CAAC;QACF,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC9C,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;QACrD,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QACpC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QACpC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QACpC,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;QACxC,MAAM,QAAQ,GAAG,KAAK,CAAC,4BAA4B,EAAE,UAAU,CAAC,CAAC;QACjE,MAAM,GAAG,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QAC5B,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC;QAC7B,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9C,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;QACxD,MAAM,OAAO,GAAG,MAAM,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAClD,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;QAChE,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;QAC5D,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QAEzC,IAAI,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;QACtB,IAAI,KAAK,GAAG,IAAI,CAAC;QACjB,IAAI,GAAG,GAAG,OAAO,CAAC;QAClB,IAAI,IAAI,GAAG,OAAO,CAAC;QACnB,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,IAAI,YAAY,GAAG,CAAC,CAAC,CAAC;QACtB,SAAS,CAAC;YACN,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,4BAA4B,EAAE,aAAa,GAAG,IAAI,CAAC,CAAC;YACvE,KAAK,CAAC,WAAW,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;YAC1D,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAClC,IAAI,KAAK,EAAE,CAAC;gBACR,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;gBACjF,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;YAC/F,CAAC;YACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;gBACzB,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE;oBACjB,MAAM,EAAE,KAAK,CAAC,MAAM;oBACpB,MAAM,EAAE,KAAK,CAAC,MAAM;oBACpB,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI;oBACxC,KAAK,EAAE,GAAG;oBACV,IAAI;oBACJ,IAAI;oBACJ,UAAU,EAAE,MAAM;oBAClB,OAAO;oBACP,SAAS;iBACZ,CAAC,CAAC;gBACH,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,UAAU,EAAE;oBACpC,CAAC;oBACD,SAAS,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC;oBACzB,YAAY,EAAE,CAAC;oBACf,IAAI,EAAE,CAAC;iBACV,CAAC,CAAC;gBACH,IAAI,CAAC,QAAQ,CACT,IAAI,EACJ,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,EACnF,QAAQ,EACR,CAAC,MAAM,CAAC,MAAM,CAAC,CAClB,CAAC;gBACF,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC9B,CAAC;YACD,KAAK,CAAC,OAAO,EAAE,CAAC;YAChB,MAAM,YAAY,GAAG,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;YAC/D,MAAM,gBAAgB,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YAC7D,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YACjC,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC;YACvC,GAAG,CAAC,WAAW,EAAE,CAAC;YAClB,IAAI,KAAK,EAAE,CAAC;gBACR,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;gBAC3C,KAAK,GAAG,KAAK,CAAC;YAClB,CAAC;YACD,IAAI,IAAI,WAAW,CAAC,KAAK,EAAE,gBAAgB,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC9D,MAAM,IAAI,gBAAgB,CAAC,cAAc,EAAE,GAAG,SAAS,oCAAoC,EAAE;oBACzF,KAAK,EAAE,GAAG,SAAS,eAAe;oBAClC,OAAO,EAAE,gEAAgE;iBAC5E,CAAC,CAAC;YACP,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;YAC7D,IAAI,IAAI,CAAC,CAAC;YACV,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YAC/E,YAAY,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC5B,IAAI,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;gBAC3B,MAAM,IAAI,gBAAgB,CAAC,WAAW,EAAE,GAAG,SAAS,0BAA0B,EAAE;oBAC5E,OAAO,EAAE,SAAS,CAAC,EAAE;iBACxB,CAAC,CAAC;YACP,CAAC;YACD,OAAO,EAAE,UAAU,EAAE,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;YAC3C,IAAI,OAAO,KAAK,CAAC,IAAI,IAAI,IAAI,aAAa,EAAE,CAAC;gBACzC,MAAM;YACV,CAAC;YACD,KAAK,GAAG,IAAI,YAAY,CAAC,GAAG,EAAE,GAAG,SAAS,SAAS,CAAC,CAAC;QACzD,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC;QAC/B,MAAM,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;QAChD,GAAG,CAAC,WAAW,EAAE,CAAC;QAClB,OAAO,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC/B,CAAC;YAAS,CAAC;QACP,KAAK,CAAC,OAAO,EAAE,CAAC;IACpB,CAAC;AACL,CAAC"}

package/dist/src/algorithms/simple-symmetric.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The simple symmetric graph (the P11 plan's PD-4): triangle counting and label propagation are defined over an
+ * undirected graph with no parallel edges and no self-loops, and a snapshot may be directed, may carry parallel
+ * edges and may carry self-loops. This builds that graph on the device from the snapshot's edge list:
+ *
+ * 1. `coo-emit` writes two arcs per logical edge -- the edge as declared and its reverse -- and drops a self-loop
+ *    by writing both of its arcs as `INVALID_INDEX`, which sorts last.
+ * 2. Two stable radix sorts order the arcs by (source, target): by target first, then by source, the second sort's
+ *    stability keeping the first's order among equal sources. Between and after them `coo-emit` re-reads the edge
+ *    list through the sorted permutation (INDEXED), so no gather kernel is needed.
+ * 3. `run-flags` marks the first arc of every run of equal pairs; the scan of the flags counts the runs, which is
+ *    the number of distinct arcs `U` -- read back once, because every later size depends on it.
+ * 4. Three `compact`s keep the first arc of every run (its source, its target and its position), and a segmented
+ *    sum over the runs merges the weights of parallel arcs in input order (so the merged weight is bitwise
+ *    reproducible).
+ * 5. `cooToCsr` in its sorted-input mode builds the rows, which come out sorted by target.
+ *
+ * The first submit ends at step 3; steps 4 and 5 are recorded into a batch that is RETURNED OPEN, so the caller
+ * records its own first work into the same submit and saves a synchronisation. The caller must check the
+ * precondition flag of `cooToCsr` with `assertBuildSorted` after that submit.
+ *
+ * Every intermediate array is `2 x edgeCount` words and is bound whole, so a snapshot whose arcs exceed one storage
+ * binding is refused with `E_TOO_LARGE` before any upload. A weighted build refuses, with `E_UNSUPPORTED`, a pair
+ * joined by more than PARALLEL_MERGE_LIMIT parallel edges (see the constant).
+ *
+ * ponytail: about nine of the arrays are alive at the peak (72 bytes per logical edge); reuse buffers across the
+ * steps if a 1M-node / 10M-edge build needs the room.
+ */
+import { type GraphSnapshot } from "@graphty/graph-format";
+import { type GpuContext } from "../context.js";
+import { CommandBatch, type ReadbackRequest } from "../kernel/batch.js";
+import { type Binding } from "../types/memory.js";
+import { type AlgorithmScope } from "./scope.js";
+/**
+ * The simple symmetric graph on the device.
+ * @public
+ */
+export interface SimpleGraph {
+    readonly n: number;
+    /** Arcs: twice the undirected edges of the simple graph. */
+    readonly arcCount: number;
+    /** `n + 1` words. */
+    readonly rowPtr: Binding;
+    /** `arcCount` words, each row sorted ascending; null when there are no arcs. */
+    readonly colIdx: Binding | null;
+    /** `arcCount` f32, the summed weight of the parallel edges each arc merges (1 per edge on an unweighted snapshot); null when there are no arcs or weights were not asked for. */
+    readonly weights: Binding | null;
+    /** The source of every arc (`arcCount` words, non-decreasing); null when there are no arcs. */
+    readonly src: Binding | null;
+}
+/**
+ * The open second batch of a build: record more work into it, submit it, then call `assertBuildSorted`.
+ * @public
+ */
+export interface SimpleGraphBuild {
+    readonly graph: SimpleGraph;
+    readonly batch: CommandBatch;
+    /** The readback of the sorted-input flag of `cooToCsr`, already scheduled on `batch`. */
+    readonly flag: ReadbackRequest;
+}
+/**
+ * Throws `E_TOO_LARGE` when a buffer the caller binds whole is larger than one storage binding of the device.
+ * @param ctx - the context whose limit applies
+ * @param needed - the bytes of the largest whole binding
+ * @param path - what does not fit
+ * @param algorithm - the algorithm, for the error
+ */
+export declare function assertBindable(ctx: GpuContext, needed: number, path: string, algorithm: string): void;
+/**
+ * Throws `E_VALIDATION` when the device found the build's arcs out of source order, which would mean a bug in the
+ * sorts: the rows would be scrambled and every intersection over them wrong.
+ * @param bytes - the batch's readback bytes
+ * @param build - the build whose flag was read
+ * @param label - the algorithm, for the error
+ */
+export declare function assertBuildSorted(bytes: ArrayBuffer, build: SimpleGraphBuild, label: string): void;
+/**
+ * Builds the simple symmetric graph of `s` (see the file header): submits the first batch and waits for its
+ * four-byte readback, then records the rest into a batch it returns open.
+ * @param ctx - the context
+ * @param s - the snapshot (its edge list is uploaded through the residency, or found there)
+ * @param scope - the caller's scope: every buffer of the graph is its scratch
+ * @param withWeights - merge and keep the weights (label propagation) or not (triangle counting)
+ * @param label - the batch label prefix
+ * @returns the graph and the open batch
+ */
+export declare function buildSimpleSymmetric(ctx: GpuContext, s: GraphSnapshot, scope: AlgorithmScope, withWeights: boolean, label: string): Promise<SimpleGraphBuild>;
+//# sourceMappingURL=simple-symmetric.d.ts.map

package/dist/src/algorithms/simple-symmetric.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simple-symmetric.d.ts","sourceRoot":"","sources":["../../../src/algorithms/simple-symmetric.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG3D,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAAE,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAUxE,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;GAGG;AACH,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qBAAqB;IACrB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAChC,iLAAiL;IACjL,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,+FAA+F;IAC/F,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;CAClC;AA6BD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CASrG;AA8CD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAOlG;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACtC,GAAG,EAAE,UAAU,EACf,CAAC,EAAE,aAAa,EAChB,KAAK,EAAE,cAAc,EACrB,WAAW,EAAE,OAAO,EACpB,KAAK,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,CAAC,CA0L3B"}