---
title: Installation
url: 'https://timeloop.csail.mit.edu/previous_versions/timeloop-accelergy-v3/timeloop/installation'
markdown: 'https://timeloop.csail.mit.edu/previous_versions/timeloop-accelergy-v3/timeloop/installation.md'
date: '2024-08-15'
description: 'Docker This is the recommended method for new users. Windows users - manually turn on virtualization via BIOS settings. If you do not have the docker app installed already, please install docker (community edition). Go to our tutorial exercises repo and follow instructions under "Using Docker". N…'
taxonomy:
  category:
    - docs
---

[](#)  [ Overview ](https://timeloop.csail.mit.edu/)     [ Previous Versions ](https://timeloop.csail.mit.edu/previous_versions)     [ Timeloop+Accelergy v3 ](https://timeloop.csail.mit.edu/previous_versions/timeloop-accelergy-v3)     [ Timeloop ](https://timeloop.csail.mit.edu/previous_versions/timeloop-accelergy-v3/timeloop)      Installation    

# Installation

## Docker

This is the recommended method for new users.

1. Windows users - manually turn on virtualization via BIOS settings.
2. If you do not have the docker app installed already, please install [docker (community edition)](https://docs.docker.com/v17.09/engine/installation/).
3. Go to our [tutorial exercises repo](https://github.com/Accelergy-Project/timeloop-accelergy-exercises) and follow instructions under "Using Docker".

## Native install

You need to install:

- Timeloop
- Accelergy
- PyTimeloop (optional)
- GAMMA (optional)

#### Installing Timeloop and Accelergy

1. Install the following dependencies:

    ```shell
    % sudo apt install scons libconfig++-dev libboost-dev libboost-iostreams-dev libboost-serialization-dev libyaml-cpp-dev libncurses-dev libtinfo-dev libgpm-dev git build-essential python3-pip
    ```
2. Clone the timeloop repository:

    ```shell
    % mkdir timeloop-dev
    % cd timeloop-dev
    % git clone git@github.com:NVlabs/timeloop.git
    ```
3. In addition to the main source code, you need to provide Timeloop with an energy model. We recommend [Accelergy](http://accelergy.mit.edu). Please follow these [instructions](https://timeloop.csail.mit.edu/previous_versions/timeloop-accelergy-v3/accelergy/installation) to install Accelergy. Please be sure to either install Accelergy so that the shell can find it (i.e., `which accelergy` works), or provide the path to Accelergy binary as an environmental variable, `ACCELERGYPATH`, before running Timeloop.
4. Provide Timeloop with a power-area-table:

    ```shell
    % cd src
    % ln -s ../pat-public/src/pat .
    % cd ..
    ```
5. You are now ready to build Timeloop:

    ```shell
    % scons --accelergy -j4
    ```

    This builds 3 different tools:

    - `timeloop-mapper` is the complete application that instantiates an architecture, constructs its mapspace, searches for an optimal mapping within the mapspace and reports statistics for the optimal mapping.
    - `timeloop-model` instantiates an architecture, evalutes a specific given mapping of a workload and reports the statistics.
    - `timeloop-metrics` simply instantiates an architecture and reports its workload-independent characteristics such as area and energy-per-access for various architectural structures.
6. By default, the scons script will use shared (dynamic) linking. The timeloop libraries will be placed in the `lib/` subdirectory. You can manually add that to `LD_LIBRARY_PATH`, or if you are using bash you can just source the provided environment setup script:

    ```shell
    % source env/setup-env.bash
    ```
7. Test your install by running timeloop with a sample configuration.

    ```shell
    % cd configs/mapper
    % ../../build/timeloop-mapper ./sample.yaml > sample.out
    ```

    This will place timeloop's log in `sample.out` and generate the following outputs:

    - `timeloop-mapper.stats.txt` Simulation stats (performance, energy, etc.)
    - `timeloop-mapper.map.txt/cfg` The optimal mapping in different formats (the latter can be used in conjunction with the input architecture and problem spec to re-run the model on the optimal mapping.)
    - `timeloop-mapper.map+stats.xml` An XML-formatted copy of the stats and optimal mapping which is used by various Python scripts to extract results from batch runs.

#### Installing Timeloop with ISL (optional)

Timeloop can optionally use the [Integer Set Library (isl)](https://github.com/Meinersbur/isl) and [Barvinok](https://barvinok.sourceforge.io/).

There are many ways to install ISL and Barvinok. We have found th easiest to be the following:

- Install [NTL](https://libntl.org/), which Barvinok requires.
- Install the Barvinok library by downloading the [latest source](https://barvinok.sourceforge.io/) and building it.

The aforementioned Barvinok source includes a copy of ISL and, conveniently, a pre-generated C++ headers for ISL. If building from the GitHub source, these headers have to be generated first.

The following commands summarize the ISL and Barvinok installation process for Linux (where `NTL_VER` and `BARVINOK_VER` variables hold the latest ISL and Barvinok versions).

```
wget https://libntl.org/ntl-$NTL_VER.tar.gz \
    && tar -xvzf ntl-$NTL_VER.tar.gz \
    && cd ntl-$NTL_VER/src \
    && ./configure NTL_GMP_LIP=on SHARED=on \
    && make \
    && make install

wget https://barvinok.sourceforge.io/barvinok-$BARVINOK_VER.tar.gz \
    && tar -xvzf barvinok-$BARVINOK_VER.tar.gz \
    && cd barvinok-$BARVINOK_VER \
    && ./configure --enable-shared-barvinok \
    && make \
    && make install
```

To build Timeloop with ISL support, use the `--with-isl` option (e.g., `scons -j4 --with-isl`). This option requires ISL installed in the system. Instructions for installing ISL can be found in the Git repo above.

If building Timeloop as a dynamic library (i.e., without `--static` option), ISL and other required libraries need to be built with the PIC (position independent code) option enabled.

#### Installing PyTimeloop (optional)

PyTimeloop is a Python interface to Timeloop.

#### Installing the GAMMA mapper (optional)

GAMMA is a genetic-algorithm based mapper that can in many cases converge faster than Timeloop's built-in search heuristics. GAMMA depends on PyTimeloop.

1. Clone the Gamma repository:

    ```shell
    % mkdir gamma
    % cd gamma
    % git git@github.com:maestro-project/gamma-timeloop.git
    ```
2. Gamma is dependent on PyTimeloop.
3. Now, you are all set and can start using Gamma as a mapper.
4. Test you can can run Gamma

    ```shell
    % ./run_gamma_timeloop.sh
    ```

    This will generate the found mapping `map.yaml`, in `./src/report` directory

[accessibility](https://accessibility.mit.edu/)

 [ ](https://timeloop.csail.mit.edu/previous_versions/timeloop-accelergy-v3/timeloop) [](https://timeloop.csail.mit.edu/previous_versions/timeloop-accelergy-v3/timeloop/command-line)

---

## Navigation

- Parent: [Timeloop](https://timeloop.csail.mit.edu/previous_versions/timeloop-accelergy-v3/timeloop.md)
- Next: [Command Line](https://timeloop.csail.mit.edu/previous_versions/timeloop-accelergy-v3/timeloop/command-line.md)
