Module tensor_recognize

Expand description

Backend-neutral tensor-op recognition (LOGOS AST → typed specs), shared by every codegen backend. Backend-agnostic tensor-op recognition — LOGOS AST -> typed op specs, shared by every codegen backend.

The recognizers here read an ordinary (desugared) LOGOS program and lift it into a typed spec — a matmul, an elementwise op, a reduction / fused-row normalization, or a SwiGLU map — or REFUSE (typed). They are backend-neutral: the CUDA (crate::codegen_cuda), Tenstorrent (crate::codegen_tt), and RISC-V (crate::codegen_riscv) tiers all consume the SAME spec and each emit their own kernel from it. The per-backend EMITTERS (lower_*_to_tensix, the CUDA emit_* fns, …) live in their backend module; only the recognition + spec types are shared, and they live HERE rather than under any one backend.

Modules§

qwen: The Qwen-family recognizers — the ops beyond matmul / elementwise / fused-row / swiglu that an authored transformer forward is made of, each lifted from the EXACT statement shape its parser sugar desugars to (parser/mod.rs, the desugar_tensor_* family) into a typed spec.

Structs§

DotSpec: A recognized dot product acc = Σ_{t<n} A[t]·B[t]: one counted loop accumulating the product of two declared Seq of Int arrays read at the same unit-stride index.
ElementwiseSpec: The recognized shape of an elementwise tensor op: two source tensors a, b, a destination c, the operator, and the shared element count n.
Epsilon: A norm’s epsilon — the E of sqrt(… + E) — kept as its bits, so a spec holding one stays Eq and hashable.
Factor: A constant factor an op multiplies by, kept as its bits, so a spec holding one stays Eq and hashable.
Fills: Every tensor’s fill in a statement list at once (recognize_fill of each), from one walk of the list: for each tensor the first loop pushing onto it — a loop’s own pushes met before the loops nested in it, as recognize_fill meets them — and its top-level literal writes, in order.
FusedRowSpec: A recognized fused row op — a per-row reduction over a rows × cols tensor: one output row per input row, each normalized independently over its cols entries. This is the transformer-normalization shape (RMSNorm / softmax / LayerNorm over the hidden dim, batched across rows). The flat single-vector reduction ReductionSpec is exactly the rows == 1 special case; this spec is what the one-block-per-row CUDA emitter consumes, and it grows weight/residual as the fused variants land — the durable foundation.
HeadMatmulSpec: A recognized per-head matmul, Y = X matmul W across H heads: each head’s slice of every row of X times its own block of W’s rows. X is m × (heads·a), W (heads·a) × b, Y m × (heads·b), and Y[t][h·b + r] = Σ_e X[t][h·a + e]·W[h·a + e][r] — a block-diagonal product, one a × b block per head.
KmeansSpec: A recognized k-means clustering (Lloyd’s algorithm): n points of f integer features, row-major in points, around k centroids, row-major in centroids, which start as the first k points. Each of iters epochs assigns every point to its nearest centroid by the distance Σ_d term(point[d], centroid[d]) (ties as ties says), sums each centroid’s points and counts them, then sets every centroid to the integer mean of its points — 0 for a centroid with none.
MatmulSpec: A recognized matmul: C(M×N) = A(M×K) · B(K×N), row-major, over the named Seq of Int arrays.
OuterSpec: A recognized outer product C[i·n + j] = A[i]·B[j] over i < m, j < n: a counted nest storing (not accumulating) the product of two Seq of Int arrays into a row-major m × n array.
Program: What a loop’s term may draw on beyond the loop: the program’s pure functions (inlined where they are called), the builtin abs, and the element type of every array it declares (a new Seq of Int, Seq of Real, Seq of Bool).
ReductionSpec: The recognized shape of a reduction: source tensor x, destination y, element count n, and (an rmsnorm’s) the divisor its normalize step divides by, whose assignment holds its epsilon.
ScatterSpec: A recognized scatter-matrix accumulation S = Σ_{r<R} d_r d_rᵀ (C × C, row-major, from zero): each row’s vector d_r[c] = term computed into a scratch array by an elementwise loop over the row, then added to S as a rank-1 update of itself — the covariance step of Gaussian discriminant analysis.
SwiGluSpec: A recognized SwiGLU map: Y[i] = silu(gate[i]) * up[i], silu(g) = g / (1 + e^-g), over total elements — the gated MLP activation (not a row-reduction; a pure two-input elementwise map).
TermDag: A term as a DAG: each distinct subterm once, every node after its operands — how a large term (a function inlined at each call) is evaluated per element and printed with each shared subterm bound once.
ZipMap: A recognized zip map out[t] = f(A₀[t], A₁[t], …) for t < n: one counted loop storing a term of several arrays into another, every one read at the index it stores at — Black-Scholes over its option columns, any elementwise map over aligned streams. The term’s type is the output’s element type, Int or Real.
ZipSum: A recognized zip sum acc = Σ_{t<n} f(A₀[t], A₁[t], …): one counted loop accumulating an integer term of several Seq of Int arrays, every one read at the same unit-stride index — a dot product, TPC-H Q6’s filtered revenue, any map-reduce over aligned streams.

Enums§

Axis: How a scatter row’s term reads an array: at the row (y[r]), at the column (mu[c]), or at both, row-major (x[r·C + c]).
DagNode: A node of a TermDag: a ZipTerm node whose operands are nodes, by index.
DotReject: Why a program is not a recognizable dot product — a typed refusal, never a miscompile. Ordered from the least to the most advanced, so a search reports the refusal of the loop that came closest: what a loop’s body computes ranks before whether its counter is provable, so a dot product with an unprovable counter outranks a loop that accumulates nothing.
ElementwiseOp: An elementwise tensor op — C[p] = A[p] ⊕ B[p] over a shared flat length.
ElementwiseReject: Why a program is not a recognizable elementwise op.
Fill: How an array is FILLED by its build loop — recognized from While iv is less than N: Push <expr> to xs, so a backend host can reproduce the source’s data and a numerics claim can bound the operand range.
KmeansReject: Why a program is not a recognizable k-means clustering, least to most advanced.
MatmulReject: Why a program is not a recognizable tile-matmul — a typed refusal, never a miscompile.
OuterReject: Why a program is not a recognizable outer product, least to most advanced.
ReductionKind: A float reduction tensor op — rmsnorm (unit-RMS rescale) or softmax (probability distribution).
ReductionReject: Why a program is not a recognizable reduction op.
RowReduceKind: The reduction performed per row in a fused row op — the extensible core of the fused-row family (LayerNorm / fused-add-RMSNorm join here as they land). Each is a shared-memory reduction over one row.
Scalar: A scalar a ZipTerm takes, as the VM holds it.
ScatterReject: Why a program is not a recognizable scatter accumulation, least to most advanced.
Stop: Why ZipTerm::value has no value: an Int left the range asked for, a Real is not finite or left its bound, a divisor is zero, an exponent negative, or an operator met an operand it does not take.
Ties: Which of several equally near centroids a point joins.
Ty: The type of a ZipTerm, or of an array element it reads: LOGOS’s 64-bit Int, its Real (a double) and Bool.
ZipMapReject: Why a program is not a recognizable zip map, least to most advanced.
ZipOp: An operator of a ZipTerm: arithmetic, a comparison (a boolean), or a boolean connective. On two Ints arithmetic is Int (/ truncating toward zero, ** exact); with a Real operand it is Real — the VM’s rules.
ZipReject: Why a program is not a recognizable zip sum, least to most advanced (what a loop’s body computes ranks before whether its counter is provable).
ZipTerm: The term a zip loop computes from the elements it reads at the counter’s index: arithmetic, comparisons and selects over array elements and constants. A guarded accumulation (If P: Set s to s + E) is the select P ? E : 0; a call of one of the program’s pure functions is its body, inlined.

Functions§

epsilon_of: The epsilon of the norm whose divisor is denom: the E of the sqrt(… + E) the norm’s desugar assigns to it.
hoist_common_operand: term with every select whose two arms apply one operator to a common operand rewritten to apply it once, to the select of what differs — c ? x − a : x − b becomes x − (c ? a : b), and the same for +, × and a common right operand. Exact for every value: both forms apply the same operator to the same operands of the arm taken.
recognize_dot: Recognize a dot product anywhere in a LOGOS statement list:
recognize_elementwise: Recognize an elementwise idiom Push (item p of A) ⊕ (item p of B) to C inside a counted loop — the exact shape the plus/hadamard sugar desugars to — anywhere in the statement list (through Splice).
recognize_fill: Recognize the fill of tensor anywhere in the statement list: the FIRST loop whose body pushes onto it.
recognize_fused_row: Recognize the fused row-op idiom. First it lifts the PER-ROW WEIGHTED RMSNorm shape (a row loop whose normalize body Push (X[idx] / denom) * W[col] gives x, weight, y, and whose enclosing loop bounds give rows/cols); failing that it falls back to the weightless flat rmsnorm/softmax sugar (rows == 1, cols == n) via recognize_reduction. Backend-agnostic (CUDA + Tenstorrent).
recognize_head_matmul: Recognize Let Y be X matmul W across H heads — the matmul’s nest with a head loop between the row loop and the contraction: Y[t·(H·b) + h·b + r + 1] += X[t·(H·a) + h·a + e + 1] · W[(h·a + e)·b + r + 1], the loops t, h, e, r over m, H, a, b.
recognize_kmeans: Recognize a k-means clustering anywhere in a LOGOS statement list — the epoch loop of Lloyd’s algorithm:
recognize_matmul: Recognize a row-major GEMM idiom anywhere in a LOGOS statement list and extract its MatmulSpec.
recognize_outer: Recognize an outer product anywhere in a LOGOS statement list:
recognize_reduction: Recognize the rmsnorm / softmax normalize-loop idiom the sugar desugars to — a counted loop that Pushes X[p] / denom (rmsnorm) or e^(X[p]-m) / s (softmax) into Y — anywhere (through Splice).
recognize_scatter: Recognize a scatter accumulation anywhere in a LOGOS statement list:
recognize_swiglu: Recognize the SwiGLU idiom the sugar desugars to — Push (gate[iv] / (1 + E^(0 - gate[iv]))) * up[iv] in a counted loop. Backend-agnostic (CUDA + Tenstorrent).
recognize_zip_map: Recognize a zip map anywhere in a LOGOS statement list:
recognize_zip_map_where: recognize_zip_map for the first loop whose zip map wanted accepts; one it turns away counts as ZipMapReject::UnsupportedTerm (its term is not the one asked for).
recognize_zip_sum: Recognize a zip sum anywhere in a LOGOS statement list:
recognize_zip_sum_where: recognize_zip_sum for the first loop whose zip sum wanted accepts; a zip sum it turns away counts as ZipReject::UnsupportedTerm (its term is not the one asked for).