Raptor/docs/compiler/spatial-layouts.md

Spatial layout capabilities

This reference describes the alternatives advertised by SpatialLayoutCapabilities.cpp, through SpatialLayoutCapabilityInterface. Each alternative specifies all operand layouts and one result layout; it is not a global promise that every shape or target can use that layout.

Physical layouts

Logical tensor coordinates remain NCHW. The physical enum is defined in Spatial.td.

Layout	Contract and current use
DenseNCHW	Ordinary dense storage; first/default alternative for every layout-aware plan.
NHWCRowStrip	Physical row strips of channel vectors for logically NCHW tensors; compatible operations can preserve this representation through a chain.
Fragmented	Existing fragmented input accepted by Flatten for dense reconstruction; no current capability advertises it as a result alternative.
NCHWRowStrip	Reserved NCHW-oriented row-strip enum; no current capability advertises it as an alternative.

Compatibility matrix

Every operation below also advertises all-dense operands → DenseNCHW. Here R means NHWCRowStrip, D means DenseNCHW; Conv's other operands retain the layouts supplied to its interface on the R path.

Plan operation	Additional operand → result alternatives	Interface gate
Conv2D	Dense input → R; R input → R	canLowerConvPlanToRowStrip; canConsumeAndProduceRowStrip, respectively.
Flatten	Fragmented → D; R → D	Fragmented input already present; canLowerFlattenFromRowStrip for R.
Relu	R → R	Input already R.
SiLU	R → R	Input already R; intrinsic cost −3 instead of the generic R cost −2.
ResizeNearest	R → R	Input already R and canLowerResizeNearestPlanToRowStrip.
MaxPool2D	D → R; R → R	canLowerMaxPoolPlanToRowStrip.
GlobalAveragePool	D → R; R → R	canLowerGlobalAveragePoolPlanToRowStrip.
BiasAdd	(R data, D bias) → R	Ranked result, R data input, and isSupportedBiasAddValue for the bias shape.
Add	(R, R) → R	Both data operands already R.
Concat	All R inputs → R	Nonempty operand list, all already R.

The named predicates live in the plan-lowering implementation and bias helper. They check operation geometry and target resources; the matrix does not replace those legality checks.

Selection and materialization

SpatialLayoutPlanningPass.cpp starts every plan at its dense alternative. It scores intrinsic cost, operand layout mismatches, and downstream inability to accept the candidate layout. Strictly cheaper alternatives replace the current selection; ties preserve it. Traversal alternates forward/reverse order for at most 2 × plan_count + 1 rounds. Nonconvergence fails the pass with a diagnostic.

Results returned from the function must remain dense. The pass records selected layouts and inserts explicit spat.materialize_layout operations where selected producer/consumer contracts disagree, including non-layout-aware consumers of non-dense values. It verifies exact operand/result compatibility before LowerSpatialPlans lowers plans and materializations.

--pim-disable-spatial-planning skips cost selection, choosing alternative 0 for every plan. The planning/materialization/verification pass still runs. ONNX rewrites and later graph merging are unchanged; disabling layout planning does not request fusion or removal of separate elementwise graph nodes.