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).
  3. Go to our tutorial exercises repo 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:

    % 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:

    % 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. Please follow these instructions 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:

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

    % 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:

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

    % 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) and Barvinok.

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

  • Install NTL, which Barvinok requires.
  • Install the Barvinok library by downloading the latest source 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:

    % 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

    % ./run_gamma_timeloop.sh

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

accessibility