Timeloop searches for a mapping instead of letting you guess one

What Timeloop is actually for

Timeloop describes itself as an infrastructure that aims to provide modeling, mapping and code-generation for dense and sparse tensor algebra workloads on a range of accelerator architectures. That sentence names three distinct jobs, and the pairing of modelling with code generation is what distinguishes it from a cost model or a compiler. The audience is a hardware architect or a kernel engineer who has a tensor algebra problem, such as a convolution or a matrix multiplication, a target architecture in mind, and no principled answer to the question of which loop order, which tiling and which data layout the hardware should use. That question is normally answered by hand, by trying a handful of candidates and benchmarking them. Timeloop exists to turn that into a search over the space of possible mappings, with an analytical model standing in for the hardware so the search does not require building and running each candidate. The homepage is timeloop.csail.mit.edu, and the documentation there covers installation, usage and examples.

Two modular components: the model and the mapper

The architecture is described as two modular components. The first is a fast analytical model that can emulate a range of architecture designs and provide performance and energy projections. The second is a mapper that searches for an optimal mapping in the space of mappings of a tensor-algebra problem on a given architecture. That split is the whole design, and it explains both what Timeloop is good at and where its limits lie. The model is what makes the search cheap, because an analytical emulation of an architecture runs far faster than a full hardware simulation and much faster than building and benchmarking a candidate implementation. The mapper is what turns the model into an answer, and it is the component that has to encode the structure of the search space, including which mappings are legal and which are merely bad. The modularity claim also means the two pieces can be replaced independently, which matters in a research tool where the hardware model changes every time you take a new accelerator generation seriously.

The version history explains the feature set

The README maps the version history onto two research papers, which is the clearest account of what the tool can do. Timeloop version 2.0, also known as Sparseloop, provides stochastic modeling of compressed-sparse tensor algebra, described in the MICRO 2022 paper. Timeloop version 3.0, also known as Ruby, adds support for imperfectly-factorized mappings, described in the ISPASS 2022 paper, in addition to support for spatial skews and flattened mappings. The released versions listed for the project are v3.0.3 from 2024-01-10, v3.0.2 from 2023-10-05 and v3.0.1 from 2023-09-25. The deeper mechanics are described in the ISPASS 2019 paper, which the README recommends for a deeper understanding of Timeloop's internals. If you work in this area, that 2019 paper is the primary source for the model and the mapper, and the 2022 papers are the primary source for the sparse and imperfect-factorization extensions.

Building it: isl and barvinok are the hard dependency

Timeloop depends on the isl and barvinok libraries, and the README is specific about versions. Barvinok version 0.41.6, along with the pre-packaged isl library, has been tested to build successfully with this version of Timeloop, and instructions for installing barvinok are linked from the barvinok project itself. That is the whole of the installation guidance in the README, which is consistent with a tool whose users are usually arriving from a research environment where the documentation site covers the rest. The two dependencies are not incidental. barvinok is the polyhedral library that provides the counting and enumeration machinery over index sets, and isl does the set and polyhedral manipulation that the mapper's search space is expressed in. A mapping in this context is a statement about which loop iterates over which tensor dimension, and expressing that space requires polyhedral reasoning, which is why the tool cannot be built without those two libraries. The build itself uses SConstruct, and the repository layout is conventional for a research C++ project, with src, include, tests, configs, doc, scripts, env and problem-shapes directories alongside several experiment directories.

The tutorial is not optional reading

The README's instruction on this point is unusually firm. New users are strongly encouraged to complete the Timeloop tutorial, and serially walking through the exercises from that tutorial serves as an essential hands-on introduction to the tool. The tutorial lives with the Accelergy project at accelergy.mit.edu, and the exercises are a separate repository, timeloop-accelergy-exercises. That recommendation is a signal about the tool's shape. Timeloop's input is not a tensor program you hand it and receive an optimised kernel. The input is a specification of a tensor algebra problem, expressed through the Accelergy-style description of loops, iterators and storage, along with an architecture model, and the output is a mapping and generated code. Learning that input language is the real onboarding step, and the exercise sequence is where you learn it. The problem-shapes directory in the repository, which holds example problems, is the place to look once you can read that format.

Where Timeloop is the wrong choice

Three limits, and they are structural rather than fixable. The first is that the output is a mapping, not a guarantee. The analytical model approximates a hardware architecture, and the numbers it produces are projections from that model, so an answer from the mapper is only as good as the architecture model you supplied and the fidelity of its parameters. If your architecture is something the model cannot emulate, the search will still return a candidate, and the projection will be optimistic or meaningless. The second is the problem class. Timeloop is for tensor algebra workloads on accelerators, dense and sparse, which means it is aimed at deep learning inference and training kernels and at the hardware that runs them. It is the wrong tool for a general-purpose compiler, for a graph of irregular operations with no tensor structure, or for an application where the bottleneck is memory bandwidth rather than a loop structure. The third is the maturity of the surrounding practice. The build depends on a specific barvinok version, the releases stop in January 2024, and the last push was on 2026-07-26, so this is a research tool in maintenance rather than a product with a supported release train. The realistic alternatives are of two kinds. Either you keep the hand-written mapping and use a cost model such as the one in Accelergy directly to evaluate a handful of candidates, which is far less machinery for a small search space. Or you use a real autotuning compiler such as TVM or Triton, which do the search by compiling and measuring actual code rather than by emulating, giving ground truth instead of projections at the cost of far longer search time and the need for the hardware to be present.

Editorial conclusion

Adopt Timeloop if you are designing a hardware accelerator or a dense or sparse tensor algebra kernel and want performance and energy projections instead of a guess at a mapping. Skip it if you want a production inference runtime, since this is an analysis and code-generation tool rather than a serving stack. Before you build it, install barvinok 0.41.6 with the pre-packaged isl, and work through the Accelergy tutorial exercises, which the README calls an essential hands-on introduction.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. NVlabs/timeloop on GitHub
3. Project website
4. README
5. Releases