@driftengine/texture 4.0.0

package/dist/tensor/linear.js

@@ -0,0 +1,136 @@
+/**
+ * The dense operators a transformer is built from: matrix multiply, bias, layer norm, GELU, softmax.
+ *
+ * **The references the device kernels are held to**, which is why they are written for exactness
+ * rather than speed: every sum accumulates in double precision and is rounded once, on the way into
+ * the caller's single-precision output. A kernel that disagrees with one of these is wrong, not
+ * this.
+ *
+ * **Contiguous row-major arrays with their dimensions, and nothing that allocates.** A strided view
+ * that permutes without copying would make every operator handle strides, and every device kernel
+ * would materialise the permutation anyway; so a permutation is a copy into a buffer the caller
+ * owns, and the operators stay one loop each.
+ *
+ * **The exact GELU, `x·Φ(x)`, and never the tanh approximation.** The two differ by 4e-4 at 3, and
+ * a port of a network trained with one and evaluated with the other is a different network. `erf`
+ * is here for that reason, accurate to double precision.
+ */
+/**
+ * `out[m×n] = a[m×k] · b`, where `b` is `k×n`, or `n×k` read as its transpose when `transposeB`.
+ * The offsets are where each matrix starts in its array, which is how one head of many is taken.
+ */
+export function matmul(out, a, b, m, k, n, transposeB = false, outAt = 0, aAt = 0, bAt = 0) {
+    for (let row = 0; row < m; row += 1) {
+        const aRow = aAt + row * k;
+        for (let col = 0; col < n; col += 1) {
+            let sum = 0;
+            if (transposeB) {
+                const bRow = bAt + col * k;
+                for (let i = 0; i < k; i += 1)
+                    sum += a[aRow + i] * b[bRow + i];
+            }
+            else {
+                for (let i = 0; i < k; i += 1) {
+                    sum += a[aRow + i] * b[bAt + i * n + col];
+                }
+            }
+            out[outAt + row * n + col] = sum;
+        }
+    }
+}
+/** Add `bias[cols]` to every one of `rows` rows of `x`, in place. */
+export function addBias(x, rows, cols, bias) {
+    for (let row = 0; row < rows; row += 1) {
+        for (let col = 0; col < cols; col += 1) {
+            x[row * cols + col] = x[row * cols + col] + bias[col];
+        }
+    }
+}
+/**
+ * Each row normalised to zero mean and unit variance, then scaled by `gamma` and shifted by `beta`.
+ *
+ * **The population variance, divided by the row's length and not one less**, which is what the
+ * upstream frameworks compute and therefore what their trained weights expect.
+ */
+export function layerNorm(x, rows, cols, gamma, beta, epsilon, out) {
+    for (let row = 0; row < rows; row += 1) {
+        const at = row * cols;
+        let mean = 0;
+        for (let col = 0; col < cols; col += 1)
+            mean += x[at + col];
+        mean /= cols;
+        let variance = 0;
+        for (let col = 0; col < cols; col += 1)
+            variance += (x[at + col] - mean) ** 2;
+        variance /= cols;
+        const scale = 1 / Math.sqrt(variance + epsilon);
+        for (let col = 0; col < cols; col += 1) {
+            const normal = variance + epsilon === 0 ? 0 : (x[at + col] - mean) * scale;
+            out[at + col] = normal * gamma[col] + beta[col];
+        }
+    }
+}
+const TWO_OVER_ROOT_PI = 2 / Math.sqrt(Math.PI);
+/**
+ * The error function, to double precision.
+ *
+ * A Maclaurin series below 3, where its alternating terms peak near 170 at `x = 3` and cost about
+ * three digits to cancellation — still 1e-13; a continued fraction for the complement above, which
+ * converges fastest exactly where the series is worst; and ±1 past 6, where the complement is below
+ * a double's last place.
+ */
+export function erf(x) {
+    const sign = x < 0 ? -1 : 1;
+    const a = Math.abs(x);
+    if (a >= 6)
+        return sign;
+    if (a < 3) {
+        let term = a;
+        let sum = a;
+        const square = a * a;
+        for (let n = 1; n < 100; n += 1) {
+            term *= -square / n;
+            const next = term / (2 * n + 1);
+            sum += next;
+            if (Math.abs(next) < 1e-17 * Math.abs(sum))
+                break;
+        }
+        return sign * TWO_OVER_ROOT_PI * sum;
+    }
+    /* erfc(a) = exp(−a²)/√π · 1/(a + ½/(a + 1/(a + 3/2/(a + ...)))), evaluated from the tail up. */
+    let fraction = 0;
+    for (let n = 60; n >= 1; n -= 1)
+        fraction = n / 2 / (a + fraction);
+    const complement = Math.exp(-a * a) / Math.sqrt(Math.PI) / (a + fraction);
+    return sign * (1 - complement);
+}
+/** `x·Φ(x)`, the exact GELU, from `x` into `out`. */
+export function gelu(x, out) {
+    for (let i = 0; i < x.length; i += 1) {
+        const value = x[i];
+        out[i] = 0.5 * value * (1 + erf(value / Math.SQRT2));
+    }
+}
+/** The logistic, `1/(1 + e^−x)`, from `x` into `out`: 1 far to the right, and 0 far to the left. */
+export function sigmoid(x, out) {
+    for (let i = 0; i < x.length; i += 1)
+        out[i] = 1 / (1 + Math.exp(-x[i]));
+}
+/**
+ * Each row of `x` to a distribution, stably: the row's largest value is subtracted before the
+ * exponential, so logits near a thousand give their logistic rather than `Infinity / Infinity`.
+ */
+export function softmax(x, rows, cols, out) {
+    for (let row = 0; row < rows; row += 1) {
+        const at = row * cols;
+        let largest = -Infinity;
+        for (let col = 0; col < cols; col += 1)
+            largest = Math.max(largest, x[at + col]);
+        let total = 0;
+        for (let col = 0; col < cols; col += 1)
+            total += Math.exp(x[at + col] - largest);
+        for (let col = 0; col < cols; col += 1) {
+            out[at + col] = Math.exp(x[at + col] - largest) / total;
+        }
+    }
+}

package/dist/tensor/operatorKit.d.ts

@@ -0,0 +1,27 @@
+/**
+ * What every operator table shares: the shape of an operator, and the few helpers they all read
+ * their attributes and shapes with.
+ */
+export type AttributeValue = number | string | boolean | readonly number[];
+export type Attributes = Readonly<Record<string, AttributeValue>>;
+export type Shape = readonly number[];
+export interface Operator {
+    /** How many inputs it takes, fewest and most. */
+    readonly arity: readonly [number, number];
+    /**
+     * The rank each input must have, in order, where it matters. **Checked before `shape` runs**,
+     * because an operator reading an image as `[channels, height, width]` reads a value with one more
+     * axis as its first three and validates it — and then declares an output it fills only part of.
+     */
+    readonly ranks?: readonly number[];
+    shape(inputs: readonly Shape[], attributes: Attributes): number[] | string;
+    /** Scratch values it needs beyond its output, if any. */
+    scratch?(inputs: readonly Shape[], attributes: Attributes): number;
+    evaluate(inputs: readonly Float32Array[], shapes: readonly Shape[], attributes: Attributes, out: Float32Array, scratch: Float32Array): void;
+}
+export declare const num: (attributes: Attributes, name: string, fallback?: number) => number;
+export declare const list: (attributes: Attributes, name: string) => readonly number[];
+export declare const same: (a: Shape, b: Shape) => boolean;
+export declare const elementwise: (apply: (a: number, b: number) => number) => Operator;
+export declare function strides(shape: Shape): number[];
+export declare const product: (shape: Shape, from?: number, to?: number) => number;

package/dist/tensor/operatorKit.js

@@ -0,0 +1,45 @@
+export const num = (attributes, name, fallback) => {
+    const value = attributes[name];
+    if (typeof value === 'number')
+        return value;
+    if (fallback !== undefined)
+        return fallback;
+    throw new RangeError(`attribute "${name}" must be a number`);
+};
+export const list = (attributes, name) => {
+    const value = attributes[name];
+    return Array.isArray(value) ? value : [];
+};
+export const same = (a, b) => a.length === b.length && a.every((d, i) => d === b[i]);
+export const elementwise = (apply) => ({
+    arity: [2, 2],
+    shape: ([a, b]) => {
+        const x = a;
+        const y = b;
+        if (same(x, y) || (y.length === 1 && y[0] === x[x.length - 1]))
+            return [...x];
+        return `[${y.join(', ')}] is neither [${x.join(', ')}] nor its last dimension`;
+    },
+    evaluate: ([a, b], _shapes, _attributes, out) => {
+        const left = a;
+        const right = b;
+        const n = right.length;
+        for (let i = 0; i < left.length; i += 1) {
+            out[i] = apply(left[i], right[i % n]);
+        }
+    },
+});
+/* Strides of a row-major shape. */
+export function strides(shape) {
+    const out = new Array(shape.length).fill(1);
+    for (let d = shape.length - 2; d >= 0; d -= 1) {
+        out[d] = out[d + 1] * shape[d + 1];
+    }
+    return out;
+}
+export const product = (shape, from = 0, to = shape.length) => {
+    let total = 1;
+    for (let d = from; d < to; d += 1)
+        total *= shape[d];
+    return total;
+};

package/dist/tensor/operators.d.ts

@@ -0,0 +1,3 @@
+import type { Operator } from './operatorKit.ts';
+export type { AttributeValue, Attributes, Operator } from './operatorKit.ts';
+export declare const OPERATORS: ReadonlyMap<string, Operator>;

package/dist/tensor/operators.js

@@ -0,0 +1,24 @@
+/**
+ * The operators a graph may name: what each one's output shape is, and how it is evaluated.
+ *
+ * **One table, and a graph naming anything not in it is refused at validation, by name** — the
+ * runtime lacking an operator is a fact about the model, and a caller learns it when the model is
+ * loaded rather than at its first frame. Adding an operator is adding a row here, with its reference
+ * in `linear.ts`, `attention.ts` or `spatial.ts` and its device kernel in core.
+ *
+ * **`linear` is the upstream layer, `x·Wᵀ + b`, with its weight in the upstream layout `[out][in]`,
+ * and the bias added in double precision before the one rounding** — which is what makes a
+ * perceptron written as a graph agree with `evalNetwork` bit for bit, and is the evidence there is
+ * one runtime rather than two.
+ *
+ * Shapes are checked before anything runs; a shape function returns the output shape, or a sentence
+ * saying why there is none.
+ */
+import { DENSE_OPERATORS } from './denseOperators.js';
+import { SHAPE_OPERATORS } from './shapeOperators.js';
+import { SPATIAL_OPERATORS } from './spatialOperators.js';
+export const OPERATORS = new Map([
+    ...DENSE_OPERATORS,
+    ...SPATIAL_OPERATORS,
+    ...SHAPE_OPERATORS,
+]);

package/dist/tensor/resize.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `out[channels][outH][outW]` resized from `input[channels][inH][inW]`. `step`, without aligned
+ * corners, is the source pixels a destination pixel covers, vertically and then horizontally, where
+ * it is not the ratio of the sizes.
+ */
+export declare function resize(out: Float32Array, input: Float32Array, channels: number, inH: number, inW: number, outH: number, outW: number, mode: 'bilinear' | 'bicubic' | 'nearest', alignCorners: boolean, step?: readonly [number, number]): void;

package/dist/tensor/resize.js

@@ -0,0 +1,107 @@
+/**
+ * Resizing a channel-major image, `[channels][height][width]`, by the upstream's conventions.
+ *
+ * **They are followed exactly, because they are the bug every port has.** Without aligned corners
+ * a destination pixel reads source `(i + ½)·scale − ½`, and for bilinear a negative source is
+ * clamped to zero; with aligned corners it reads `i·(in − 1)/(out − 1)`, and an output of one reads
+ * source zero. Bicubic uses the cubic convolution kernel with `a = −0.75`, not the −0.5 of the
+ * textbooks, and clamps its four taps to the border rather than its coordinate. Nearest reads
+ * `⌊i·scale⌋`, PyTorch's legacy `nearest` rather than `nearest-exact`.
+ */
+const CUBIC_A = -0.75;
+/* The cubic convolution kernel's two pieces, for |x| ≤ 1 and 1 < |x| < 2. */
+function cubicNear(x) {
+    return ((CUBIC_A + 2) * x - (CUBIC_A + 3)) * x * x + 1;
+}
+function cubicFar(x) {
+    return ((CUBIC_A * x - 5 * CUBIC_A) * x + 8 * CUBIC_A) * x - 4 * CUBIC_A;
+}
+/*
+ * Where destination index `i` reads from, in the upstream's convention. Without aligned corners a
+ * destination pixel covers `input / output` source pixels — unless a step is given, which is what
+ * PyTorch's interpolate uses when it is handed a scale factor: the factor's inverse, not the ratio
+ * of the sizes it rounded to.
+ */
+function sourceOf(i, input, output, align, cubic, step) {
+    if (align)
+        return output <= 1 ? 0 : (i * (input - 1)) / (output - 1);
+    const source = step === undefined ? ((i + 0.5) * input) / output - 0.5 : (i + 0.5) * step - 0.5;
+    return !cubic && source < 0 ? 0 : source;
+}
+function clampIndex(i, size) {
+    return i < 0 ? 0 : i >= size ? size - 1 : i;
+}
+/**
+ * `out[channels][outH][outW]` resized from `input[channels][inH][inW]`. `step`, without aligned
+ * corners, is the source pixels a destination pixel covers, vertically and then horizontally, where
+ * it is not the ratio of the sizes.
+ */
+export function resize(out, input, channels, inH, inW, outH, outW, mode, alignCorners, step) {
+    if (mode === 'nearest') {
+        nearest(out, input, channels, inH, inW, outH, outW, step);
+        return;
+    }
+    const cubic = mode === 'bicubic';
+    const wx = [0, 0, 0, 0];
+    const wy = [0, 0, 0, 0];
+    for (let c = 0; c < channels; c += 1) {
+        const plane = c * inH * inW;
+        for (let y = 0; y < outH; y += 1) {
+            const sy = sourceOf(y, inH, outH, alignCorners, cubic, step?.[0]);
+            const y0 = Math.floor(sy);
+            const ty = sy - y0;
+            for (let x = 0; x < outW; x += 1) {
+                const sx = sourceOf(x, inW, outW, alignCorners, cubic, step?.[1]);
+                const x0 = Math.floor(sx);
+                const tx = sx - x0;
+                let value = 0;
+                if (cubic) {
+                    wx[0] = cubicFar(tx + 1);
+                    wx[1] = cubicNear(tx);
+                    wx[2] = cubicNear(1 - tx);
+                    wx[3] = cubicFar(2 - tx);
+                    wy[0] = cubicFar(ty + 1);
+                    wy[1] = cubicNear(ty);
+                    wy[2] = cubicNear(1 - ty);
+                    wy[3] = cubicFar(2 - ty);
+                    for (let j = 0; j < 4; j += 1) {
+                        const row = plane + clampIndex(y0 - 1 + j, inH) * inW;
+                        let across = 0;
+                        for (let i = 0; i < 4; i += 1) {
+                            across += wx[i] * input[row + clampIndex(x0 - 1 + i, inW)];
+                        }
+                        value += wy[j] * across;
+                    }
+                }
+                else {
+                    const x1 = Math.min(x0 + 1, inW - 1);
+                    const y1 = Math.min(y0 + 1, inH - 1);
+                    const top = input[plane + y0 * inW + x0] * (1 - tx) +
+                        input[plane + y0 * inW + x1] * tx;
+                    const bottom = input[plane + y1 * inW + x0] * (1 - tx) +
+                        input[plane + y1 * inW + x1] * tx;
+                    value = top * (1 - ty) + bottom * ty;
+                }
+                out[(c * outH + y) * outW + x] = value;
+            }
+        }
+    }
+}
+/*
+ * PyTorch's `nearest`: destination `i` reads source `⌊i·scale⌋`, clamped to the last, the product
+ * taken in single precision as its kernel takes it — `scale` the step where the node gives one, as
+ * a resize by a scale factor does, and the sizes' ratio otherwise.
+ */
+function nearest(out, input, channels, inH, inW, outH, outW, step) {
+    const scaleY = Math.fround(step?.[0] ?? inH / outH);
+    const scaleX = Math.fround(step?.[1] ?? inW / outW);
+    for (let c = 0; c < channels; c += 1) {
+        for (let y = 0; y < outH; y += 1) {
+            const sy = Math.min(Math.floor(Math.fround(y * scaleY)), inH - 1);
+            for (let x = 0; x < outW; x += 1) {
+                const sx = Math.min(Math.floor(Math.fround(x * scaleX)), inW - 1);
+                out[(c * outH + y) * outW + x] = input[(c * inH + sy) * inW + sx];
+            }
+        }
+    }
+}

package/dist/tensor/reuse.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Which values of a graph may share one buffer, as one rule both sides plan by: the reference
+ * evaluator here, and the device's runner in `@driftengine/core`.
+ *
+ * **A value's buffer is given back after the last node that reads it, and not before** — so a
+ * node's output never shares a buffer with any of its own inputs, since the inputs are read while
+ * the output is written. What is `held` keeps a buffer of its own for the life of the plan, and so
+ * does every output; a value that is neither written by a node nor held is not planned at all,
+ * which is how the evaluator leaves weights and inputs in the caller's own arrays.
+ *
+ * **Two implementations of this would drift**, and the failure is a network that runs, validates
+ * and answers wrongly — a value overwritten before its last reader reads it.
+ *
+ * What it gives up: a free buffer is taken first-come rather than by the size that fits best, so a
+ * small value may hold a large buffer while a larger one waits. The transformers this runs repeat a
+ * block of identically shaped values, where first-come and best-fit choose the same buffers.
+ */
+export interface BufferReuse {
+    /** The buffer each planned value lives in. */
+    readonly slotOf: ReadonlyMap<string, number>;
+    /** Each buffer's size, in values: the largest value it ever holds. */
+    readonly sizes: readonly number[];
+}
+export declare function planReuse(graph: {
+    readonly nodes: readonly {
+        readonly inputs: readonly string[];
+        readonly output: string;
+    }[];
+    /** Values given a buffer each before any node runs, in this order. */
+    readonly held: readonly string[];
+    /** Values never given back, claimed where they are written. */
+    readonly outputs: readonly string[];
+}, sizeOf: (name: string) => number): BufferReuse;

package/dist/tensor/reuse.js

@@ -0,0 +1,59 @@
+/**
+ * Which values of a graph may share one buffer, as one rule both sides plan by: the reference
+ * evaluator here, and the device's runner in `@driftengine/core`.
+ *
+ * **A value's buffer is given back after the last node that reads it, and not before** — so a
+ * node's output never shares a buffer with any of its own inputs, since the inputs are read while
+ * the output is written. What is `held` keeps a buffer of its own for the life of the plan, and so
+ * does every output; a value that is neither written by a node nor held is not planned at all,
+ * which is how the evaluator leaves weights and inputs in the caller's own arrays.
+ *
+ * **Two implementations of this would drift**, and the failure is a network that runs, validates
+ * and answers wrongly — a value overwritten before its last reader reads it.
+ *
+ * What it gives up: a free buffer is taken first-come rather than by the size that fits best, so a
+ * small value may hold a large buffer while a larger one waits. The transformers this runs repeat a
+ * block of identically shaped values, where first-come and best-fit choose the same buffers.
+ */
+export function planReuse(graph, sizeOf) {
+    const slotOf = new Map();
+    const sizes = [];
+    const pinned = new Set([...graph.held, ...graph.outputs]);
+    const claim = (name) => {
+        sizes.push(sizeOf(name));
+        slotOf.set(name, sizes.length - 1);
+        return sizes.length - 1;
+    };
+    for (const name of graph.held)
+        claim(name);
+    /* The last node reading each value; a value never read is last read where it is written. */
+    const lastRead = new Map();
+    graph.nodes.forEach((node, at) => {
+        lastRead.set(node.output, at);
+        for (const input of node.inputs)
+            lastRead.set(input, at);
+    });
+    const free = [];
+    graph.nodes.forEach((node, at) => {
+        if (pinned.has(node.output)) {
+            claim(node.output);
+        }
+        else {
+            const reuse = free.shift();
+            if (reuse === undefined)
+                claim(node.output);
+            else {
+                slotOf.set(node.output, reuse);
+                sizes[reuse] = Math.max(sizes[reuse], sizeOf(node.output));
+            }
+        }
+        /* Only after the node has run: its inputs are read while its output is written. */
+        for (const value of new Set([...node.inputs, node.output])) {
+            const slot = slotOf.get(value);
+            if (slot === undefined || pinned.has(value) || lastRead.get(value) !== at)
+                continue;
+            free.push(slot);
+        }
+    });
+    return { slotOf, sizes };
+}

package/dist/tensor/shapeOperators.d.ts

@@ -0,0 +1,3 @@
+/** The shape operators' rows: they move values and compute nothing. */
+import { type Operator } from './operatorKit.ts';
+export declare const SHAPE_OPERATORS: readonly (readonly [string, Operator])[];

package/dist/tensor/shapeOperators.js

@@ -0,0 +1,173 @@
+/** The shape operators' rows: they move values and compute nothing. */
+import { list, num, product, strides } from './operatorKit.js';
+export const SHAPE_OPERATORS = [
+    [
+        'permute',
+        {
+            arity: [1, 1],
+            shape: ([x], attributes) => {
+                const order = list(attributes, 'order');
+                const shape = x;
+                const valid = order.length === shape.length &&
+                    [...order].sort((p, q) => p - q).every((d, i) => d === i);
+                return valid
+                    ? order.map((d) => shape[d])
+                    : `order [${order.join(', ')}] is not a permutation of ${shape.length} axes`;
+            },
+            evaluate: ([x], [xs], attributes, out) => {
+                const shape = xs;
+                const order = list(attributes, 'order');
+                const from = strides(shape);
+                const to = order.map((d) => shape[d]);
+                const index = new Array(shape.length).fill(0);
+                for (let at = 0; at < out.length; at += 1) {
+                    let source = 0;
+                    for (let d = 0; d < order.length; d += 1)
+                        source += index[d] * from[order[d]];
+                    out[at] = x[source];
+                    for (let d = order.length - 1; d >= 0; d -= 1) {
+                        index[d] = index[d] + 1;
+                        if (index[d] < to[d])
+                            break;
+                        index[d] = 0;
+                    }
+                }
+            },
+        },
+    ],
+    [
+        'reshape',
+        {
+            arity: [1, 1],
+            shape: ([x], attributes) => {
+                const shape = list(attributes, 'shape');
+                return product(shape) === product(x)
+                    ? [...shape]
+                    : `[${shape.join(', ')}] does not hold [${x.join(', ')}]`;
+            },
+            evaluate: ([x], _shapes, _attributes, out) => out.set(x),
+        },
+    ],
+    [
+        'concat',
+        {
+            arity: [2, 16],
+            shape: (inputs, attributes) => {
+                const axis = num(attributes, 'axis');
+                const first = inputs[0];
+                let along = 0;
+                for (const shape of inputs) {
+                    if (shape.length !== first.length || shape.some((d, i) => i !== axis && d !== first[i])) {
+                        return `inputs differ off axis ${axis}`;
+                    }
+                    along += shape[axis];
+                }
+                return first.map((d, i) => (i === axis ? along : d));
+            },
+            evaluate: (inputs, shapes, attributes, out) => {
+                const axis = num(attributes, 'axis');
+                const first = shapes[0];
+                const outer = product(first, 0, axis);
+                let at = 0;
+                for (let o = 0; o < outer; o += 1) {
+                    for (let i = 0; i < inputs.length; i += 1) {
+                        const block = product(shapes[i], axis);
+                        out.set(inputs[i].subarray(o * block, (o + 1) * block), at);
+                        at += block;
+                    }
+                }
+            },
+        },
+    ],
+    [
+        'slice',
+        {
+            arity: [1, 1],
+            shape: ([x], attributes) => {
+                const axis = num(attributes, 'axis');
+                const start = num(attributes, 'start');
+                const end = num(attributes, 'end');
+                const shape = x;
+                return start >= 0 && end <= shape[axis] && start < end
+                    ? shape.map((d, i) => (i === axis ? end - start : d))
+                    : `[${start}, ${end}) is outside axis ${axis} of length ${shape[axis]}`;
+            },
+            evaluate: ([x], [xs], attributes, out) => {
+                const axis = num(attributes, 'axis');
+                const start = num(attributes, 'start');
+                const end = num(attributes, 'end');
+                const shape = xs;
+                const inner = product(shape, axis + 1);
+                const outer = product(shape, 0, axis);
+                const length = shape[axis];
+                const take = (end - start) * inner;
+                for (let o = 0; o < outer; o += 1) {
+                    const from = (o * length + start) * inner;
+                    out.set(x.subarray(from, from + take), o * take);
+                }
+            },
+        },
+    ],
+    [
+        /*
+         * Zeros after the end of each axis, `after[axis]` of them, as a window partition pads a grid it
+         * does not divide. Every value keeps its index along every axis.
+         */
+        'pad',
+        {
+            arity: [1, 1],
+            shape: ([x], attributes) => {
+                const after = list(attributes, 'after');
+                const shape = x;
+                if (after.length !== shape.length) {
+                    return `the pad names ${after.length} axes and the value has ${shape.length} axes`;
+                }
+                if (after.some((d) => d < 0))
+                    return `a pad of [${after.join(', ')}] is negative`;
+                return shape.map((d, i) => d + after[i]);
+            },
+            evaluate: ([x], [xs], attributes, out) => {
+                const shape = xs;
+                const after = list(attributes, 'after');
+                const outShape = shape.map((d, i) => d + after[i]);
+                const from = strides(shape);
+                const to = strides(outShape);
+                out.fill(0);
+                const values = x;
+                for (let i = 0; i < values.length; i += 1) {
+                    let at = 0;
+                    for (let axis = 0; axis < shape.length; axis += 1) {
+                        at +=
+                            (Math.floor(i / from[axis]) % shape[axis]) *
+                                to[axis];
+                    }
+                    out[at] = values[i];
+                }
+            },
+        },
+    ],
+    [
+        /*
+         * Rows of a table by index, as a token's embedding is looked up: `indices` holds whole numbers
+         * as values, and row i of the output is row `indices[i]` of the table. An index that is not one
+         * of the table's rows is refused here; a device cannot refuse, and clamps it to the last row.
+         */
+        'gather',
+        {
+            ranks: [2, 1],
+            arity: [2, 2],
+            shape: ([table, indices]) => [indices[0], table[1]],
+            evaluate: ([table, indices], [ts], _attributes, out) => {
+                const [rows, width] = ts;
+                const at = indices;
+                for (let i = 0; i < at.length; i += 1) {
+                    const row = at[i];
+                    if (!Number.isInteger(row) || row < 0 || row >= rows) {
+                        throw new RangeError(`gather: index ${row} at ${i} is not a row of a table of ${rows}`);
+                    }
+                    out.set(table.subarray(row * width, (row + 1) * width), i * width);
+                }
+            },
+        },
+    ],
+];

package/dist/tensor/spatial.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The spatial operators: convolution, its transpose, a patch embedding and max pooling. Resizing is
+ * `resize.ts`'s.
+ *
+ * **Channel-major images, one at a time** — `[channels][height][width]`, the layout the upstream
+ * frameworks call NCHW with a batch of one — and **weights in the upstream layout**: a convolution's
+ * `[out][in][kh][kw]`, a transposed convolution's `[in][out][kh][kw]`. A converted checkpoint is
+ * then read as it was stored, and a rearrangement is never a place for a transposed weight to hide.
+ */
+/**
+ * `out[cout][oh][ow]` from `input[cin][h][w]`, with `oh = ⌊(h + 2·padding − kh)/stride⌋ + 1` and
+ * likewise `ow`. `bias` may be null.
+ *
+ * **Grouped, the channels split into `groups` runs** and output `o` reads only the run `o` falls in:
+ * the weight is `[cout][cin / groups][kh][kw]`, as the upstream stores it, and a depthwise
+ * convolution is `groups = cin = cout`.
+ */
+export declare function conv2d(out: Float32Array, input: Float32Array, cin: number, h: number, w: number, weight: Float32Array, bias: Float32Array | null, cout: number, kh: number, kw: number, stride: number, padding: number, groups?: number): void;
+/**
+ * `out[cout][oh][ow]` from `input[cin][h][w]`, with `oh = (h − 1)·stride − 2·padding + kh`: each input
+ * pixel spread over the kernel at its strided place, which is how a decoder head upsamples.
+ */
+export declare function convTranspose2d(out: Float32Array, input: Float32Array, cin: number, h: number, w: number, weight: Float32Array, bias: Float32Array | null, cout: number, kh: number, kw: number, stride: number, padding: number): void;
+/**
+ * A patch embedding: a convolution with stride and kernel both `patch`, written token-major —
+ * `out[tokens][dim]`, tokens row by row — which is the order a transformer reads them in.
+ */
+export declare function patchEmbed(out: Float32Array, image: Float32Array, cin: number, h: number, w: number, weight: Float32Array, bias: Float32Array | null, dim: number, patch: number): void;
+/**
+ * `out[channels][oh][ow]`, each the largest of its `kernel`-square window at `stride`, with
+ * `oh = ⌊(h − kernel)/stride⌋ + 1`: no padding, and a ragged last row or column dropped, as
+ * PyTorch's `max_pool2d` does without `ceil_mode`.
+ */
+export declare function maxPool2d(out: Float32Array, input: Float32Array, channels: number, h: number, w: number, kernel: number, stride: number): void;