unify memory opimization passes

better reports
cleanups

README.md

@@ -67,14 +67,11 @@ ONNX-MLIR -> Spatial -> Pim (tensor) -> Pim (bufferized) -> PIM artifacts
    Converts tensor-semantics PIM IR into memref-semantics PIM IR using MLIR's
    bufferization interfaces.
 
-5. **Safe IR memory coalescing**
-   (`src/PIM/Dialect/Pim/Transforms/MemoryCoalescing`).
-   Normalizes compatible block-local allocations before final planning.
-6. **PIM local-memory planning**
+5. **PIM local-memory planning**
    (`src/PIM/Dialect/Pim/Transforms/LocalMemoryPlanning`).
-   Computes whole-core lifetimes, coalesces non-overlapping allocations into
-   physical slots, assigns addresses, and records the explicit plan in PIM IR.
-7. **PIM verification and code generation** (`src/PIM/Pass/PimCodegen` and
+   Computes whole-core lifetimes, reuses addresses for non-overlapping
+   allocations, and records the explicit plan in PIM IR.
+6. **PIM verification and code generation** (`src/PIM/Pass/PimCodegen` and
    `src/PIM/Compiler`).
    Verifies the memory plan and other PIM invariants, then emits `.pim` core
    files, weights, and `memory.bin` / `config.json` without rerunning liveness.
@@ -90,9 +87,10 @@ Supporting pieces:
 - `src/PIM/Pass` - pass registration and auxiliary passes.
 - `src/PIM/PimAccelerator.{cpp,hpp}` - ONNX-MLIR accelerator entry point.
 
-## Key compiler options
+## PIM compiler options
 
-Pass these to `onnx-mlir` when compiling for PIM:
+Pass these to `onnx-mlir` when compiling for PIM. These are all Raptor/PIM-specific
+options; `onnx-mlir --help` lists the inherited ONNX-MLIR options.
 
 - `--maccel=PIM` - select the PIM accelerator.
 - `--EmitSpatial`, `--EmitPim`, `--EmitPimBufferized`,
@@ -101,14 +99,30 @@ Pass these to `onnx-mlir` when compiling for PIM:
 - `--core-count=<N>` - required positive core count for PIM compilation.
 - `--crossbar-size=<N>` - crossbar width/height. Default in code is `128`.
 - `--crossbar-count=<N>` - crossbars per core. Default in code is `64`.
+- `--pim-memory-report=<summary|none>` - emit the concise combined memory report
+  under `reports/memory_report.txt`, or disable it. Default is `summary`.
 - `--pim-only-codegen` - assume input is already bufferized PIM IR and only run
   the codegen tail.
 - `--pim-emit-json` - also emit `core_*.json` instruction files alongside
   `core_*.pim`.
-- `--pim-export-spatial-dataflow=<none|spatial1|spatial2|spatial3|spatial4|all>` - control Spatial
-  dataflow CSV reports for the graph, trivially merged graph, scheduled, and
-  realized snapshots under `reports/`.
+- `--pim-export-spatial-dataflow=<none|spatial1|spatial2|spatial3|spatial4|all>` -
+  control Spatial dataflow CSV reports for the graph, trivially merged graph,
+  scheduled, and realized snapshots under `reports/`. Default is `none`.
+- `--pim-conv-lowering=<auto|legacy|depthwise|packed-im2col|streamed-patch|streamed-packed|output-channel-tiled|input-k-tiled|tiled-2d>` -
+  select the convolution lowering strategy. Default is `auto`.
+- `--pim-conv-im2col-max-elements=<N>` - maximum globally materialized im2col
+  elements per convolution before streaming. Default is `1048576`.
+- `--pim-conv-stream-chunk-positions=<N>` - maximum output positions per
+  streamed convolution chunk. Default is `1024`.
+- `--pim-report-conv-lowering=<true|false>` - emit the bounded convolution
+  lowering report. Default is `true`.
 - `--use-experimental-conv-impl` - use the alternate convolution lowering.
+- `--pim-detect-communication-deadlock` - statically simulate expanded
+  send/receive ordering and reject blocking deadlocks. Default is off.
+- `--pim-materialize-scalar-fanout-global-order` - use the experimental,
+  expensive globally ordered scalar-fanout materializer. Default is off.
+- `--pim-trace-communication-materialization` - emit verbose communication
+  materialization diagnostics and provenance attributes. Default is off.
 - `--ignore-concat-error` - soft-fail a ConcatOp corner case.
 
 ## Standard PIM hardware profile
@@ -149,7 +163,7 @@ Python dependencies used by the validation scripts are `numpy`, `onnx`, and
 Per-operation validation from the repository root:
 
 ```bash
-python validation/validate.py \
+.venv/bin/python validation/validate.py \
   --raptor-path build_release/Release/bin/onnx-mlir \
   --onnx-include-dir onnx-mlir/include \
   --operations-dir validation/operations \
@@ -165,7 +179,7 @@ Validate one network or a subset by pointing `--operations-dir` at any directory
 containing `.onnx` files:
 
 ```bash
-python validation/validate.py \
+.venv/bin/python validation/validate.py \
   --raptor-path build_release/Release/bin/onnx-mlir \
   --onnx-include-dir onnx-mlir/include \
   --operations-dir validation/networks/yolo11n/depth_04 \
@@ -173,7 +187,6 @@ python validation/validate.py \
   --crossbar-size 128 \
   --core-count 144 \
   --verbose \
-  --raptor-extra-arg=--pim-memory-report=summary \
   --raptor-extra-arg=--pim-detect-communication-deadlock \
   --raptor-extra-arg=--pim-export-spatial-dataflow=none
 ```
@@ -200,7 +213,7 @@ Each validation run writes artifacts in the model workspace, for example under
 The compiler currently dumps dialect snapshots such as `spatial0.mlir`,
 `spatial1_graph.mlir`, `spatial2_trivial_merged.mlir`,
 `spatial3_scheduled_no_comm.mlir`, `spatial4_scheduled.mlir`, `pim0.mlir`, `pim1_buff.mlir`,
-`pim2_folded.mlir`, `pim3_coalesced.mlir`, and `pim4_memory_planned.mlir` when an output directory is
+`pim2_folded.mlir`, and `pim3_memory_planned.mlir` when an output directory is
 available.
 
 To rerun the simulator manually with tracing after validation has produced a
@@ -229,7 +242,7 @@ Available operation suites under `validation/operations/`: `add`, `concat`,
 Generated operation tests can be regenerated with:
 
 ```bash
-python3 validation/operations/gen_tests.py
+.venv/bin/python validation/operations/gen_tests.py
 ```
 
 ## Build