LOOPer

LOOPer is a learned automatic code optimizer — an autoscheduler — for the Tiramisu polyhedral compiler. Given a program, it searches for a sequence of loop transformations (a schedule) that makes the program run faster, and uses a deep-learning cost model to rank candidate schedules without compiling and running each one.

LOOPer: A Learned Automatic Code Optimizer For Polyhedral Compilers — PACT 2025. Paper: arXiv:2403.11522 · IEEE

This repository is a hands-on showcase and tutorial: clone it, follow the steps, and run LOOPer end-to-end on benchmark programs in both of its modes, with a bundled pretrained cost model so model-guided runs work out of the box.

• Model-guided (--mode model) — search ranked by the cost model. Candidate scoring needs no target-machine runs; the tutorial measures only the baseline and selected winner. The intended production mode.
• Execution-guided (--mode execution) — each candidate is actually compiled and run. The ground-truth baseline; slower, needs the target hardware.

New to LOOPer? Read the 5-minute concepts primer first.

What you need

• A compiled Tiramisu master checkout with the LOOPer autoscheduler and Halide 14. "Compiled" means TIRAMISU_ROOT/build contains both libtiramisu and libtiramisu_auto_scheduler.
• The LOOPerCostModel repository (provides the model↔search interface).
• A system C++ compiler (GCC/Clang) and Python ≥ 3.9.

If you clone this repo next to your tiramisu and LOOPerCostModel checkouts, setup_env.sh finds them automatically; otherwise point it at them with the TIRAMISU_ROOT and LOOPER_INTERFACE environment variables (see below).

Quickstart

# 1. Set up the Python env and write config.env (autodetects Tiramisu + interface).
#    Override paths if needed:
#    TIRAMISU_ROOT=/path/to/tiramisu LOOPER_INTERFACE=/path/to/looper_search_interface \
scripts/setup_env.sh

# 2. Optimize a benchmark with the cost model (bundled weights, no runs during search).
scripts/autoschedule.sh examples/function_gemm_MINI --mode model

# 3. Same benchmark, ground-truth execution-guided search.
scripts/autoschedule.sh examples/function_gemm_MINI --mode execution

Each run prints a live log and writes a run directory under runs/ containing search_output.txt (human-readable) and <func>_explored_schedules.json (the full exploration trace + best schedule). The headline is the speedup of the best schedule over the original program.

function_gemm_MINI is a tiny warm-up (model-guided search finishes in seconds; its runtime is so small that speedups are noise-dominated). For a run that shows a real, meaningful speedup, use examples/function_gemm_MEDIUM — walked through in the tutorial.

Repository layout

README.md            you are here
config.env.example   template for the paths every script reads
scripts/
  setup_env.sh       create the venv + write config.env
  autoschedule.sh    build + run one benchmark (--mode model|execution)
  lib.sh             shared helpers (config, validation, env)
examples/            self-contained autoscheduler-ready benchmarks (gemm, jacobi1d, gramschmidt)
model/               bundled pretrained weights + interface notes
docs/
  concepts.md        5-minute primer (schedule, modes, beam size, output)
  tutorial.md        full walkthrough, both modes
  output.md          how to read the logs and the JSON trace
  bring-your-own.md  put your own Tiramisu program in the right shape

Documentation

• docs/concepts.md — what a schedule is, the two modes, beam search, and what the output means.
• docs/tutorial.md — the full end-to-end tutorial.
• docs/output.md — reading search_output.txt and the JSON.
• docs/bring-your-own.md — optimize your own program.

Resources

• Tiramisu master — the compiler and LOOPer search module this repository drives.
• LOOPerCostModel — the cost model, its training code, and the model↔search interface.
• LOOPerSet dataset — the dataset the bundled weights were trained on (dataset paper).
• polybench-tiramisu — PolyBench implemented in Tiramisu; the source of the example kernels.
• LOOPer paper: arXiv:2403.11522 · IEEE.

Notes

• Results depend on your setup. The speedups, schedules, and timings you get vary with your CPU, the search parameters, and the data the bundled model was trained on — and can differ substantially from the numbers reported in the paper (measured on an Intel Xeon E5-2695 v2). See the paper for the reported speedups.
• No hard-coded paths. Every script reads config.env; regenerate it with setup_env.sh or edit it by hand.

License & citation

This repository's own code is under the MIT License. Tiramisu is Apache-2.0; the LOOPerSet dataset is CC-BY-4.0. If you use this work, please cite the LOOPer paper (and the LOOPerSet dataset if you use the model or its data) — see CITATION.cff.