rework documentation

add plot generation scripts
adjust validation tools
add up-to-date results

docs/compiler/spatial-layouts.md

@@ -0,0 +1,63 @@
+# 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.