Module ir 

SpatialProgram — the spatial IR proper.

Tensors live in global memory. Stages move tiles (Load/Store), receive multicast blocks (Recv), compute on tiles (Compute) or run a scalar dataflow body (Scalar). Stages exchange tiles through bounded Buffers along typed Edges. The tile pass fixes the per-site block plan, place pins every stage to a Site and engine, fuse_readers introduces multicast Groups, size_buffers fixes depths and offsets, synthesize_handshakes emits the per-engine Schedule of ChoreoOps, and verify attaches the certificate. Every phase marker is an Option in strict order — a program is always in exactly one Phase and SpatialProgram::validate holds after every pass.

There is deliberately NO strategy enum in this file: PlanSummary REPORTS the emergent plan (how many multicast groups, which block shape, how many engine-program classes) from the structure itself.

Structs

AccessPattern

A rectangular block of tiles read or written per step: block_h × block_w tiles starting at origin, consecutive tiles stride_w apart along a row and rows stride_h apart.

BlockPlan

The per-site block plan the tile pass fixes.

BlockShape

The compute block shape in tiles: output sub-block osh × osw, inner-dimension block ibw.

Buffer

BufferAt

BufferId

A buffer.

ChipId

WHICH RDU. A tensor-parallel program is one program over many chips; the chip is a COORDINATE of a site, not a separate compilation. Absent (or zero) everywhere in a single-chip program, so every artifact and fixture written before tensor parallelism serializes and parses byte-identically.

Edge

EdgeId

An edge.

ElemAccess

A FLAT, SIGNED affine map from the iteration space to one operand’s element offset: base + Σ var·stride, over the operand’s page read as a row-major plane of tile.rows rows and page_tiles · tile.cols columns. The evaluator recovers (row, col) = (off / width, off % width), and an offset outside the plane reads 0.0 — never a fault — so an unselected TensorBody::Select branch may point past the page.

ElemShape

EngineProgram

EngineSlot

Group

GroupId

A multicast group.

IndirectTerm

A value-dependent element term: (operand's value at this point) · stride, taken modulo modulus — the element-level gather (a top-k index into a row, a token id into a table row). Declared in B-P3 as a type (validated: operand must be one of the stage’s operands, modulus nonzero); its evaluation and certificate semantics are B-P5, and until then the evaluator REFUSES a map that carries one rather than dropping the term.

IndirectTile

A value-dependent tile address: the tile is chosen by an INDEX read from a buffer, not by the loop variables — an embedding row, a KV-cache slot, a flash-attention block, a chosen expert’s weights.

InnerLoop

IterSpec

One axis of a ComputeOp::Generic iteration space.

LinkPoint

★ A HALT AT A SECTION BOUNDARY, FOR WHAT CROSSES THE LINK. One chip’s program of a program split over chips (compile_program_to_chips) stops here so its tensors can cross: first sends, which the sections before it have written and another chip reads, are taken from it; then receives, which another chip writes and the sections after it read, are put into it; then it continues.

LoopVar

A loop variable of the choreography.

MemoryMap

NocId

A NOC channel index.

Placement

PlanSummary

The emergent plan, REPORTED from structure — never an input.

Rect

An inclusive rectangle of sites.

Rendezvous

The rendezvous that closes a section: its gather and its release semaphore.

Requirements

What a pass recorded the program as needing from its target (kept on the program so validate stays target-free while the pipeline gates the requirements against the descriptor).

ScalarBody

A scalar dataflow body (the CGRA’s LoopCell datapath) applied element-wise over its input tiles.

Schedule

SectionSpan

One SECTION of a composed program: the half-open range this section owns in every id space, the plan and work list it was lowered under, the tensor it writes, and the rendezvous every engine passes through before the next section begins.

SemId

A semaphore.

Semaphore

Site

A LOGICAL mesh coordinate. Physical (NOC) coordinates are a lowering concern and never enter the IR.

SiteItems

Every site’s work items, section by section — see SpatialProgram::site_items.

SpatialProgram

Stage

StageId

A stage.

TaggedOp

TensorDecl

TensorId

A global tensor.

TileAddr

A tile id that is affine in the choreography’s loop variables: base + Σ env[var]·stride, plus an optional value-dependent term (IndirectTile).

TileGrid

TileRect

Trip

★ A LOOP COUNT THE PROGRAM READS FROM ITS OWN DATA. Element elem of the input tensor — a program argument, set before the program runs and never written by it — gives v, and every loop run to the trip runs n = ⌈(v + bias) / per⌉ times. The program admits the values admit.0 ..= admit.1, stated in the value’s own units — a position against the cache it indexes — so a value outside them is refused before anything runs, by the same range the program’s own checks hold it to, never as a clamped or wrapped count. The counts run from Trip::lo to Trip::hi, the bound every static question takes (a loop’s LoopCount::Trip::max is exactly it).

TripId

A loop count the program reads from its data (Trip).

WorkItem

WorkItemId

A work item (one output block).

WorkList

Enums

AccPolicy

The accumulator format of a tile matmul.

AccRead

How an AccMap reads an operand for element e of accumulator tile k.

ArchCond

BarrierPhase

The two halves of a centralized barrier over n engine programs.

BufferKind

ChoreoOp

One step of a site engine’s choreography.

ComputeOp

ComputeShape

A ComputeOp as the shapes a printer that computes in software tells apart: a tile product, an elementwise map over the acquired accumulator, the general form, a scalar body. Such a printer matches on what an op computes and never on which epilogue it is. Requant, bias and ReLU are each an AccMap, whose body it prints as it prints a Generic’s.

DimAxis

One of a tensor’s two tile-grid extents.

Direction

Engine

Which engine of a site runs a stage.

EnginePacking

Which movement engine carries which stream. Engines run concurrently, so the packing decides what overlaps what: keeping both operand loads together serialises them against each other, while giving one operand an engine to itself and pairing the other with the store overlaps block k’s output write with block k+1’s operand reads. Both are legal on any target with two movement engines; which one wins is measured.

FoldLevel

Where a stage runs in its item’s fold over K blocks — see SpatialProgram::fold_levels.

Granularity

Whether the matrix engine is driven one tile per call or one sub-block per call.

Handshake

IrViolation

A structural invariant the program breaks. Every arm is a lock.

IterKind

Whether an axis survives into the output or is folded away.

Layout

LoopCount

How many times a loop runs.

MemSpace

NumericsClaim

What the program claims about its result versus the exact integer reference.

NumericsPolicy

Whether a partial sum may round when it spills to a narrower intermediate buffer.

Operand

Phase

Pred

An axis predicate: which side of a bound the current point of the iteration space is on.

PredRhs

The bound of an axis predicate.

ReducePool

The pooling function of a reduction (over whichever axis is marked IterKind::Reduce).

RowXformKind

How a reduced per-row scalar becomes the multiplier the rescale broadcasts back across the row.

SemCond

SemRole

SemValue

SfpuKind

The SFPU’s element-wise repertoire. A new transform is a new KIND, never a new ComputeOp.

SiteRole

StageKind

TensorBody

The scalar expression a ComputeOp::Generic applies at each point of its iteration space.

TensorInit

How a tensor’s contents are produced — recognized from the source’s array-build loop, so a host can reproduce the data and the numerics claim can bound the operand range.

TensorRole

TensorSpace

Functions

body_ops

The untagged ops of a loop body.

walk_ops

Walk a choreography with loop multiplicities: f(op, multiplicity) for every op reached. A loop run to a trip counts its trip’s greatest count here (LoopCount::bound).

walk_tagged

Walk a tagged choreography: f(tagged op, multiplicity) for every op reached, loop bodies included, each loop run to a trip counted at its greatest count.

walk_tagged_counted

walk_tagged with each loop counted by count — LoopCount::bound for the static bound, a trip’s count at a position for the run a position makes.

walk_tagged_ops

walk_ops over a tagged choreography.