# Compiler architecture and pipeline

See the [documentation index](../README.md) for related compiler and evaluation
references. Source paths below are relative to the repository root.

## Compilation pipeline

```text
ONNX-MLIR -> Spatial -> Pim (tensor) -> Pim (bufferized) -> Pim artifacts
```

| Stage | Responsibility and source |
|---|---|
| ONNX → Spatial | Operation lowering, target-neutral layout planning, and plan materialization in `src/PIM/Conversion/ONNXToSpatial`. |
| Spatial scheduling | Graph merging, scheduling, verification, and communication realization in `src/PIM/Dialect/Spatial/Passes/Transforms/MergeComputeNodes`; see [scheduling ownership](scheduling.md). |
| Spatial → Pim | Cores, communication, packing, and global tensors in `src/PIM/Conversion/SpatialToPim`. |
| Bufferization | Writable destinations, one-shot analysis, memory normalization, and verification in `src/PIM/Dialect/Pim/Passes/Transforms/Bufferization`. |
| Local-memory planning | Whole-core lifetimes and address reuse in `src/PIM/Dialect/Pim/Passes/Transforms/LocalMemoryPlanning`. |
| Verification/codegen | Verify the explicit memory plan and emit artifacts in `src/PIM/Passes/PimCodegen` and `src/PIM/Compiler`. |

Spatial plans select physical layouts and insert explicit materializations at
boundaries. Dense NCHW is the default; compatible operations can use row-strip
layouts, while Flatten can reassemble fragmented inputs. Function results
remain dense NCHW. See the [layout compatibility reference](spatial-layouts.md)
for operation alternatives, legality checks, and planner behavior.

## Validation and tests

[Validation instructions](../../validation/README.md) cover ONNX-MLIR reference
comparison, functional simulation, performance measurement, and artifacts.
The Rust functional simulator reads Raptor's artifact directory;
`pimsim-nn` supplies latency, power, and energy estimates.

```bash
cd backend-simulators/pim/pim-simulator
cargo test
```

## Repository layout

- `src/PIM/`: accelerator, dialects, conversions, analyses, and codegen.
- `test/PIM/`: compiler unit tests.
- `validation/`: operation/network suites and simulator configuration.
- `backend-simulators/pim/pim-simulator/`: Rust functional simulator.
- `backend-simulators/pim/pimsim-nn/`: performance simulator submodule.
- `tools/raptor_graph_explorer/`: [Spatial CSV viewer](../../tools/raptor_graph_explorer/README.md).
- `pimcomp_utils/`: comparison helpers containing local paths.
- `.github/`: CI build and validation setup.

CMake exposes `src/PIM` and `test/PIM` through generated shims under
`onnx-mlir/src/Accelerators/PIM` and `onnx-mlir/test/accelerators/PIM`.