Concepts: just enough to follow the tutorial
July 18, 2026 · View on GitHub
This page is a short on-ramp for someone who skimmed the LOOPer paper (PACT 2025). It covers only the ideas you need to read the tutorial's output. For the full story, read the paper.
What LOOPer does
LOOPer is an autoscheduler for the Tiramisu polyhedral compiler. Given a program, it searches for a schedule — an ordered sequence of loop transformations — that makes the program run faster, without you having to tune anything by hand.
Schedule
A schedule is a sequence of loop transformations applied to the original program. LOOPer's transformations are the classic polyhedral ones: fusion, shifting, interchange, reversal, skewing, parallelization, tiling, and unrolling. Interchange, skewing and reversal can appear multiple times and in any order; the others are applied once, near the end of the sequence.
In the search log you will see schedules printed as compact strings, e.g.
M({C0},-1,0,0,1)M({C1},-1,0,0,0,1,0,0,0,-1)U({C0},L1,8)
Read left to right: this applies two affine matrix transforms (M, here
reversals/interchanges on computations C0 and C1) and then unrolls loop L1
of C0 by a factor of 8. P(...) is parallelization, T(...) tiling,
F(...) fusion.
The search: beam search
LOOPer builds the schedule with beam search over a tree. The root is the
untransformed program; each edge adds one transformation. At every level it keeps
only the top-K partial schedules, where K is the beam size (--beam,
default 3). A larger beam explores more candidates and tends to find better
schedules, at the cost of speed.
Illegal transformations (ones that would violate data dependencies) are pruned
using polyhedral dependence analysis, and "apply nothing" is always kept as an
option, so LOOPer can always fall back to the original program.
The two modes
At each step the search must score candidate schedules to decide which to keep. That scoring is where the two modes differ:
Model-guided (--mode model) | Execution-guided (--mode execution) | |
|---|---|---|
| How a candidate is scored | The learned cost model predicts its speedup | The candidate is compiled and run; the real time is measured |
| Speed | Fast, ~constant per candidate | Slow; grows with how long the program takes to run |
| Needs the target machine to score candidates? | No (pure inference) | Yes |
| Role | The intended production mode | The "perfect evaluator" / ground-truth baseline |
The paper reports that model-guided scoring is, on average, orders of magnitude faster than measuring (see it for the exact factor). The reason is concrete: scoring one candidate is a few-millisecond model prediction, whereas measuring compiles and runs the program several times — so model-guided search finishes far sooner than execution-guided.
Why have both? Execution-guided search is what the search could achieve with a flawless cost model — it is the yardstick. Model-guided search is what you actually deploy: no target-machine runs during the search, just one prediction per candidate. The tutorial wrapper still measures the original program and the selected winner after model-guided search so it can report a real speedup.
The cost model
A tree-structured neural network (recursive + LSTM) that mirrors the program's
loop nest. It reads the untransformed program's structure (loop-nest tree,
per-computation iteration domains, memory accesses, and expression trees) plus the
candidate's list of transformations, and regresses to a single predicted
speedup = initial_time / transformed_time. The bundled weights
(model/PACT25_repro_weights.pt) were trained on the
LOOPerSet pact25 split and
reproduce the cost-model accuracy reported in the paper.
What "the output" is
Each run produces an exploration trace and a best schedule, written to
<func>_explored_schedules.json, plus a human-readable search_output.txt.
docs/output.md explains how to read them. The headline number is the
speedup of the best schedule over the original program — predicted by the
model, and (in model mode, because we also measure the initial and best schedules)
confirmed by a real measurement.
Your results will vary. The schedules, speedups, and timings a run produces depend on your CPU, the search parameters, and the data the bundled model was trained on, and can differ substantially from the numbers in the paper (measured on an Intel Xeon E5-2695 v2 with a model trained for it). See the paper for the reported speedups; treat the outputs here as illustrative.