# Spatial layout capabilities

This reference describes the alternatives advertised by
[`SpatialLayoutCapabilities.cpp`](../../src/PIM/Conversion/ONNXToSpatial/Passes/Analyses/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`](../../src/PIM/Dialect/Spatial/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](../../src/PIM/Conversion/ONNXToSpatial/Passes/Transforms)
and [bias helper](../../src/PIM/Conversion/ONNXToSpatial/Common/BiasAddUtils.hpp). They check operation geometry and
target resources; the matrix does not replace those legality checks.

## Selection and materialization

[`SpatialLayoutPlanningPass.cpp`](../../src/PIM/Conversion/ONNXToSpatial/Passes/Transforms/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`](../../src/PIM/Conversion/ONNXToSpatial/Passes/Transforms/LowerSpatialPlansPass.cpp) 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.