# Raptor

Raptor is an MLIR compiler for ONNX neural networks targeting processing-in-memory
(PIM) architectures. It extends ONNX-MLIR and emits per-core `.pim` binaries,
`memory.bin`, `config.json`, and weights for the simulators under
`backend-simulators/pim/`. Optional JSON instructions use `--pim-emit-json`.

The target has shared host memory, PIM cores with ReRAM crossbars, explicit
inter-core communication, and no hardware branches or loops. Lowering,
scheduling, and memory planning keep repeated work compact until codegen.

## Build

Initialize submodules:

```bash
git submodule update --init --recursive
```

Follow [ONNX-MLIR's LLVM/MLIR build instructions](onnx-mlir/docs/BuildOnLinuxOSX.md).
The [CI workflow](.github/workflows/validate_operations.yml) records dependency
versions and setup, including CMake and Protobuf. Rust stable is required for
the functional simulator. Python requirements include the Graph Explorer and
need Python 3.13+; create the repository environment if absent, then install:

```bash
python3.13 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
```

If compatible Protobuf libraries are unavailable locally:

```bash
git clone --depth 1 --branch v34.0 https://github.com/protocolbuffers/protobuf
cmake -S protobuf -B protobuf/build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release -Dprotobuf_BUILD_TESTS=OFF
cmake --build protobuf/build
sudo cmake --install protobuf/build
```

Configure and build Raptor, adjusting `MLIR_DIR` to your LLVM build:

```bash
cmake -S . -B build_release -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DONNX_MLIR_ACCELERATORS=PIM \
  -DLLVM_ENABLE_ASSERTIONS=ON \
  -DMLIR_DIR="$PWD/onnx-mlir/llvm-project/build_release/lib/cmake/mlir"
cmake --build ./build_release
```

Use release builds first. For debugging, configure `build_debug` with
`-DCMAKE_BUILD_TYPE=Debug` and the matching MLIR package, then run
`cmake --build ./build_debug`. Use debug only for small cases requiring symbols.
Optional `mold` linking uses `-fuse-ld=mold` in
`CMAKE_{EXE,SHARED,MODULE}_LINKER_FLAGS`.

Always build through `cmake --build`; invoking `ninja` directly bypasses CMake
configuration and generated shim updates.

## Compile a model

```bash
./build_release/Release/bin/onnx-mlir model.onnx -o /tmp/raptor/model \
  --maccel=PIM --EmitPimCodegen \
  --crossbar-count=64 --crossbar-size=128 --core-count=144
```

This writes artifacts under `/tmp/raptor/pim/`. All three hardware flags are
mandatory positive values. The example uses the development/YOLO profile;
[Pimcomp comparison profiles](validation/networks/pimcomp_models/README.md#hardware-profiles)
differ, and validation defaults to Arch-A.

## Documentation

Start with the [documentation index](docs/README.md). It links the
[compiler architecture](docs/compiler/architecture.md),
[compiler options](docs/compiler/options.md), and
[evaluation methodology](docs/evaluation/methodology.md).

[Validation commands](validation/README.md), the
[operation inventory](validation/operations/INVENTORY.md), and the
[Graph Explorer](tools/raptor_graph_explorer/README.md) remain beside their
components.