Timeloop

https://timeloop.csail.mit.edu/
Admin
Timeloop is an infrastructure for modeling, mapping, and code generation for tensor algebra...
Tokens:17,008
Snippets:235
Trust Score:10
Update:6 months ago
Show doc for...
Tokens:
Raw
### Clone and Install PyTimeloop

Source: https://timeloop.csail.mit.edu/v4/python-interface

Commands to clone the repository, update submodules, set environment paths, and install the package.

```bash
git clone --recurse-submodules git@github.com:Accelergy-Project/timeloop-python.git
```

```bash
$ git submodule update
```

```bash
export TIMELOOP_INCLUDE_PATH=your/timeloop/path/include
export TIMELOOP_LIB_PATH=directory/with/timeloop/libs
```

```bash
$ pip3 install -e .
```

```bash
rm -rf build
```

--------------------------------

### Reference Mapper Configuration File

Source: https://timeloop.csail.mit.edu/v4/input-formats/mapper

Path to a full mapper configuration example file.

```text
/user/media/repos/timeloop-accelergy-exercises/workspace/baseline_designs/example_designs/_include/mapper.yaml
```

--------------------------------

### Start Docker Container

Source: https://timeloop.csail.mit.edu/tutorials-and-examples

Launch the Docker container to begin the workspace environment.

```bash
docker-compose up
```

--------------------------------

### Clone and Install Accelergy/Timeloop Infrastructure

Source: https://timeloop.csail.mit.edu/installation

Use this command to clone the repository and install Accelergy and the Timeloop Python Front-End. Ensure you have git and pip3 installed.

```bash
git clone --recurse-submodules https://github.com/Accelergy-Project/accelergy-timeloop-infrastructure.git
cd accelergy-timeloop-infrastructure

# Install Accelergy
make install_accelergy

# Install the Timeloop Python Front-End
pip3 install ./src/timeloopfe

# Install Timeloop
make install_timeloop
```

--------------------------------

### Install Orojenesis Software Dependencies

Source: https://timeloop.csail.mit.edu/orojenesis

Install software dependencies for Orojenesis by running the install script within the 'orojenesis' directory.

```bash
./install.sh
```

--------------------------------

### Test GAMMA Mapper Installation

Source: https://timeloop.csail.mit.edu/installation

Run this script to test if the GAMMA mapper has been installed correctly. This script is expected to generate a 'map.yaml' file in the './src/report' directory upon successful execution.

```bash
% ./run_gamma_timeloop.sh
```

--------------------------------

### Timeloop Output Mapping Example

Source: https://timeloop.csail.mit.edu/v4/output-formats/mapping

An example of a pretty-printed mapping file generated by Timeloop, showing memory hierarchy and loop structures.

```text
MainMemory [ Weights:3072 (3072) Inputs:576 (576) Outputs:512 (512) ]
---------------------------------------------------------------------
| for P in [0:1)

GlobalBuffer [ Weights:3072 (3072) Inputs:576 (576) Outputs:512 (512) ]
-----------------------------------------------------------------------
|   for C in [0:2)
|     for K in [0:32)
|       for R in [0:3)
|         for C in [0:16) (Spatial-X)

RegisterFile [ Weights:1 (1) Inputs:16 (16) Outputs:16 (16) ]
-------------------------------------------------------------
|           for P in [0:16)
```

--------------------------------

### Install Timeloop and PyTimeloop Dependencies

Source: https://timeloop.csail.mit.edu/v4/python-interface

List of required system dependencies for building Timeloop and PyTimeloop.

```bash
// Timeloop dependencies
scons
libconfig++-dev
libboost-dev
libboost-iostreams-dev
libboost-serialization-dev
libyaml-cpp-dev
libncurses-dev
libtinfo-dev
libgpm-dev
// PyTimeloop dependencies
cmake
```

--------------------------------

### Timeloop Loop Tiling Example

Source: https://timeloop.csail.mit.edu/v4/output-formats/mapping

Illustrates loop tiling by showing nested loops with specific iteration ranges, indicating partitioning of the problem dimension.

```text
|   for C in [0:2)
    ...
|     for C in [0:16)
```

--------------------------------

### Example Timeloop Trace Output

Source: https://timeloop.csail.mit.edu/v4/output-formats/trace

This is an example of the trace output generated by Timeloop when tracing is enabled. It shows space-time coordinates and the data tiles (Weights, Inputs, Outputs) present at each.

```text
    t/7/ s/0/ Weights: { [0,0,0,0:2,256,1,1), } Inputs: { [0,0,0,14:1,2,8,28), } Outputs: { [0,0,14,0:1,256,28,8), } 
      t/8/0/ s/0/0/ Weights: { [0,0,0,0:2,16,1,1), } Inputs: { [0,0,8,14:1,2,16,15), } Outputs: { [0,0,14,8:1,16,15,16), } 
      t/8/1/ s/0/0/ Weights: { [0,128,0,0:2,144,1,1), } Inputs: { [0,0,8,14:1,2,16,15), } Outputs: { [0,128,14,8:1,144,15,16), } 
      t/8/2/ s/0/0/ Weights: { [0,0,0,0:2,16,1,1), } Inputs: { [0,0,8,16:1,2,16,17), } Outputs: { [0,0,16,8:1,16,17,16), } 
      t/8/3/ s/0/0/ Weights: { [0,128,0,0:2,144,1,1), } Inputs: { [0,0,8,16:1,2,16,17), } Outputs: { [0,128,16,8:1,144,17,16), } 
    t/8/ s/0/ Weights: { [0,0,0,0:2,256,1,1), } Inputs: { [0,0,8,14:1,2,16,28), } Outputs: { [0,0,14,8:1,256,28,16), } 
  t/ s/ Weights: { [0,0,0,0:2,256,1,1), } Inputs: { [0,0,0,0:1,2,56,56), } Outputs: { [0,0,0,0:1,256,56,56), }
```

--------------------------------

### Run Orojenesis Docker Container

Source: https://timeloop.csail.mit.edu/orojenesis

Start the Orojenesis Docker container. This command maps port 8888 and mounts the current directory to '/home/workspace'.

```bash
docker run -it orojenesis -p 8888:8888 -v $(pwd):/home/workspace bash
```

--------------------------------

### Clone GAMMA Repository

Source: https://timeloop.csail.mit.edu/installation

Clone the GAMMA repository to install it as an optional mapper. This requires git and assumes you are in a directory where you want to create the 'gamma' subdirectory.

```bash
% mkdir gamma
% cd gamma
% git git@github.com:maestro-project/gamma-timeloop.git
```

--------------------------------

### Get Stats Files and Print Output Path

Source: https://timeloop.csail.mit.edu/orojenesis

This snippet retrieves statistics files and prints the path of the first file. Ensure the 'utils' module is available and 'output_dir' and 'prob' are defined.

```python
stats_files = utils.get_stats_files(output_dir, [prob]) 
print(f'Output CSV file: {stats_files[0]}')
```

--------------------------------

### Compound Component Actions with Arguments (YAML)

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/components

Defines actions for a compound component with arguments, mapping compound action arguments to subcomponent action arguments. This example maps 'data_delta' and 'address_delta' for the 'read' action.

```yaml
compound_components:
classes:
- name: smartbuffer
  attributes:
    ...
  subcomponents:
      ...
  actions:     
  - name: read
    arguments:
      data_delta: 0..1
      address_delta: 0..n_banks
    subcomponents:
      - name: storage
        actions:
          - name: read
            arguments:
              data_delta: data_delta
              address_delta: address_delta
      - name: address_generators
        actions:
          - name: add
      ...

```

--------------------------------

### Specify Metadata Bitwidth for Rank

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/sparse-optimizations

Optionally specify the metadata bitwidth for each rank's metadata storage. This example sets the coordinate metadata to 4 bits.

```yaml
sparse_optimizations:
  targets:
    - name: Buffer                
      representation_format:  
        data_spaces:
          - name: A            
            ranks:                
              - format: CP   
                metadata_word_bits: 4
                ...

```

--------------------------------

### Configure Leader-Follower Intersection

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/sparse-optimizations

Example of gating access to a follower dataspace based on the value of a leader dataspace.

```yaml
- !Component
  name: buffer
  sparse_optimizations:
    action_optimization:   
        - type: gating           
          target: B                
          condition-on: [ A ]  
    ...
```

--------------------------------

### Configure Double-Sided Intersection

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/sparse-optimizations

Example of mutual gating where two dataspaces act as leaders and followers for each other.

```yaml
- !Component
  name: buffer
  sparse_optimizations:
    action_optimization:   
        - type: gating           
          target: B                
          condition-on: [ A ]  
        - type: gating           
          target: A                
          condition-on: [ B ]  
    ...
```

--------------------------------

### Primitive Component with Special Attributes (YAML)

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/components

Specifies special attributes for a primitive component to guide Accelergy's plug-in selection for energy and area estimation. Includes minimum_accuracy and plug_in.

```yaml
compound_components:
  version: 0.4
  classes:
  - name: smartbuffer
    attributes:
      ...
      minimum_accuracy: 70 # Scale of 0 to 100
      plug_in: "pick_me_as_a_plug_in"
    ...

```

--------------------------------

### Compound Component Actions Definition (YAML)

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/components

Defines the actions for a compound component, including how subcomponent actions are composed. This example shows a 'read' action composed of 'read' from 'storage' and 'add' from 'address_generators'.

```yaml
compound_components: version: 0.4 classes:
  * name: smartbuffer attributes: ... subcomponents: ... actions:
  * name: read subcomponents: 
    * name: storage actions: 
      * name: read
    * name: address_generators actions: 
      * name: add ... 

```

--------------------------------

### Initialize Docker Compose Configuration

Source: https://timeloop.csail.mit.edu/tutorials-and-examples

Create the docker-compose.yaml file from the provided template.

```bash
cp docker-compose.yaml.template docker-compose.yaml
```

--------------------------------

### Basic PyTimeloop Usage and Design Space Exploration

Source: https://timeloop.csail.mit.edu/v4/python-interface

Demonstrates loading specifications, running the mapper, and performing parallel design space exploration.

```python
import pytimeloop.timeloopfe.v4 as tl
from joblib import Parallel, delayed

# Basic setup. Gathers input files, checks for errors
spec = tl.Specification.from_yaml_files(
"your_input_file.yaml", "your_other_input_file.yaml"
)

# Call Timeloop mapper
tl.call_mapper(spec, output_dir="your_output_dir")

# Call Accelergy verbose
tl.call_accelergy_verbose(spec, output_dir="your_output_dir")

# Multiprocessed design space exploration
def run_mapper_with_spec(buf_size: int):
spec = tl.Specification.from_yaml_files(
"your_input_file.yaml", "your_other_input_file.yaml"
)
spec.architecture.find("my_buffer").attributes.depth = buf_size
return tl.call_mapper(spec, output_dir=f"outputs_bufsize={buf_size}")

buf_sizes = [1024, 2048, 4096, 8192, 16384]
results = Parallel(n_jobs=8)(
delayed(run_mapper_with_spec)(buf_size) for buf_size in buf_sizes
)
```

--------------------------------

### Launch Python Script from Notebook

Source: https://timeloop.csail.mit.edu/orojenesis

After converting a notebook to a Python script, use this command to execute it. Replace '<my-notebook.py>' with the generated Python script filename.

```bash
python <my-notebook.py>
```

--------------------------------

### Define 1D Convolution Problem Shape

Source: https://timeloop.csail.mit.edu/v4/input-formats/problem

Example of defining a 1D convolution workload using dimensions and data space projections.

```yaml
problem:
  version: 0.4
  shape:
    name: Conv1D
    dimensions: [ R, P ]
  data_spaces:
      - name: Weights
        projection:
        - [ [R] ]
      - name: Inputs
        projection:
        - [ [P], [R] ]
      - name: Outputs
        projection:
        - [ [P] ]
        read-write: True
  instance:
        ...
```

--------------------------------

### Build Orojenesis Docker Image

Source: https://timeloop.csail.mit.edu/orojenesis

Build the Docker container image for Orojenesis. Ensure you are in the root of the 'orojenesis' repository.

```bash
docker build -f ./docker/Dockerfile -t orojenesis .
```

--------------------------------

### Launch Jupyter Notebook GUI

Source: https://timeloop.csail.mit.edu/orojenesis

Use this command to launch the Jupyter Notebook graphical interface within the 'orojenesis' directory. This is the recommended way to explore the provided notebooks.

```bash
jupyter notebook
```

--------------------------------

### Custom Expression Function Script

Source: https://timeloop.csail.mit.edu/v4/input-formats/globals

Example Python script defining a custom function for use in Timeloop expressions. Ensure the function is in the top-level scope.

```python
def my_function(x):
    return x + 5
```

--------------------------------

### Reference Architecture Nodes and Attributes

Source: https://timeloop.csail.mit.edu/v4/parsing_and_intermediate_files/arithmetic-parsing

Demonstrates referencing architecture nodes, parent container attributes, and other component attributes.

```yaml
  - !Container # Top-level system
    name: system
    attributes:
      system_val: 123

  - !Component
    name: component1
    subclass: component_name_here
    attributes:
      value1: TOP_LEVEL_DEFINE       # Reference top-level define
      scalar: TOP_LEVEL_DEFINE * 123 # Overwrite component default
      from_system: system_val        # Directly reference parent containers
    spatial: {meshX: value1} # Can reference attributes of this component

  - !Component
    name: component2
    subclass: component_name_here
    attributes:
      value1: component1.attributes["value1"] # Reference component1 attribute
```

--------------------------------

### Python Loop Tiling Calculation

Source: https://timeloop.csail.mit.edu/v4/output-formats/mapping

A Python code snippet demonstrating how loop tiling factors are used to calculate an index, showing the logic behind partitioning.

```python
for c1 in range(0,2):
  for c0 in range(0,16):
    c_idx= c1*16+c0
```

--------------------------------

### Initialize Timeloop Environment for Orojenesis

Source: https://timeloop.csail.mit.edu/orojenesis

Set the TIMELOOP_BASE_PATH and TIMELOOP_DIR environment variables to point to the Timeloop repository root. This script also enables first read elision.

```python
import os
if "TIMELOOP_BASE_PATH" not in os.environ:
    timeloop_path = input("Please specify the path to Timeloop repo (default: " +  os.getcwd() + "/../):" ) or os.getcwd() + "/../"
    os.environ["TIMELOOP_BASE_PATH"] = timeloop_path
    os.environ["TIMELOOP_DIR"] = timeloop_path
os.environ["TIMELOOP_ENABLE_FIRST_READ_ELISION"] = "1"
print("Path to timeloop repo: ", os.environ["TIMELOOP_BASE_PATH"])
import pathlib
import src.utils as utils
```

--------------------------------

### Enable Timeloop Tracing

Source: https://timeloop.csail.mit.edu/v4/output-formats/trace

Set these environment variables to enable detailed tracing and disable temporal/spatial extrapolation. This significantly slows down simulation speed and is best used with 'timeloop-model' on a specific mapping.

```bash
TIMELOOP_ENABLE_TRACING=1
TIMELOOP_DISABLE_TEMPORAL_EXTRAPOLATION=1
TIMELOOP_DISABLE_SPATIAL_EXTRAPOLATION=1
```

--------------------------------

### Configure Mapspace Template

Source: https://timeloop.csail.mit.edu/v4/input-formats/mapspace

Set the template to "ruby" to allow imperfect factorizations, or any other string to restrict to perfect factorizations only.

```yaml
mapspace:
  version: 0.4
  template: "ruby"  
```

--------------------------------

### Configure Mapper Optimization Metrics

Source: https://timeloop.csail.mit.edu/v4/input-formats/mapper

Sets the optimization metrics to prioritize mappings by delay, followed by energy.

```yaml
mapper:
  optimization_metric: [ delay, energy ]
```

--------------------------------

### Access Global Specification Object

Source: https://timeloop.csail.mit.edu/v4/parsing_and_intermediate_files/arithmetic-parsing

Shows how to access the top-level specification using the 'spec' keyword.

```yaml
dict_to_parse:
a: spec.variables["global_a"]
num_threads: spec.mapper.num_threads
```

--------------------------------

### Configure Sparse Optimizations

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/sparse-optimizations

Define sparse optimization targets, their representation formats including data spaces and ranks, and specify skipping actions with conditions.

```yaml
sparse_optimizations:
  targets:
    - name: BackingStorage
      representation-format:
        data-spaces:
          - name: A
            ranks:
              - format: UOP
              - format: CP
          - name: B
            ranks:
              - format: UOP
              - format: CP

    - name: Buffer
      representation-format:
        data-spaces:
          - name: B
            ranks:
              - format: UOP # uncompressed offset pair
              - format: CP  # coordinate payload
          - name: A
            ranks:
              - format: UOP # uncompressed offset pair
              - format: CP  # coordinate payload

      action-optimization:
        - type: skipping
          options:
            - target: A
              condition-on: [ B ]
        - type: skipping
          options:
            - target: B
              condition-on: [ A ]
        - type: skipping
          options:
            - target: Z
              condition-on: [ A, B ]
```

--------------------------------

### Reference Previously-Parsed Keys

Source: https://timeloop.csail.mit.edu/v4/parsing_and_intermediate_files/arithmetic-parsing

Shows how keys within the same dictionary can reference previously defined keys.

```yaml
dict_to_parse:
a: 1
b: a + 5
```

--------------------------------

### Pull Docker Image

Source: https://timeloop.csail.mit.edu/tutorials-and-examples

Download the latest version of the Docker image defined in the configuration.

```bash
docker-compose pull
```

--------------------------------

### Define Sparse Optimizations in Separate File

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/sparse-optimizations

Structure for defining sparse optimizations in a standalone configuration file.

```yaml
sparse_optimizations:
  version: 0.4
  targets:
  - target: <Name of component>
    action_optimization: <Action optimization dictionary>
    representation_format: <Representation format dictionary>
    compute_optimization: <Compute optimization dictionary>
  - target: <Name of component>
    ...
  - target: <Name of component>
    ...
```

--------------------------------

### Specify Architecture Version

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/components

The 'version' key specifies the schema version for the architecture definition. Ensure this matches the expected version for Timeloop/Accelergy inputs.

```yaml
compound_components:
  version: 0.4
  ...
```

--------------------------------

### Define YAML Variables and Expressions

Source: https://timeloop.csail.mit.edu/v4/parsing_and_intermediate_files/arithmetic-parsing

Demonstrates the use of scalars, arrays, dictionaries, and Python expressions within a variables block.

```yaml
variables:
  scalar: 123
  array:  [1, 2, 3]
  dict:   {key1: 1, key2: 2}
  string: "string" # Quotes are required for strings

  # Any Python expression can be used. A limited set of functions are available.
  expression: scalar + 1 # Any Python expression can be used
  complex_expression: scalar + array[0] + dict["key1"] + pow(len(string), 4)

  # If an expression WOULD otherwise be wrapped in quotes, we can force it
  # to be treated as an expression by wrapping it in parentheses
  expresssion_with_strings: ("string1" + "string2")
  multiline_expression: |
    def func(x):
      return x + 1
  expression_calling_function: func(1)
```

--------------------------------

### Instantiate Array of Tiles in Timeloop

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/architecture

Define an array of tiles using `!Hierarchical` and `!Container` with spatial properties. Each tile can contain its own storage and compute units, allowing for a large number of replicated elements.

```yaml
- !Hierarchical
  nodes:
  - !Component
    name: backing_store
    ... # backing_store defnition

  - !Container
    name: tile
    ... # tile defnition
    spatial: {meshX: 8, meshY: 12}
    constraints:
        spatial:
            permutation: ABCD
            split: 2
            factors: [A=8, B=2, C=3, D=4]

  - !Component # The local cache is in the tile, so there are 96 total caches
    name: local_cache
    ... # definition

  - !Component # The compute is in the tile, so there are 96 total compute elements
    name: compute
    ... # definition
```

--------------------------------

### Clone Orojenesis Repository

Source: https://timeloop.csail.mit.edu/orojenesis

Clone the Timeloop GitHub repository and checkout the Orojenesis branch to begin.

```bash
git clone --recurse-submodules -b oaves_keep_max https://github.com/NVlabs/timeloop.git
cd orojenesis
```

--------------------------------

### Define Compound Component Classes

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/components

The 'classes' key introduces a list of compound component definitions. Each class can have attributes, subcomponents, and actions.

```yaml
compound_components:
   ...
  classes:
     ...
```

--------------------------------

### Specify Action Optimization Type

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/sparse-optimizations

Basic syntax for defining the type of action optimization, such as gating or skipping.

```yaml
action_optimization:  
    type: gating          
    ...
```

--------------------------------

### Environment Variable: ACCELERGY_COMPONENT_LIBRARIES

Source: https://timeloop.csail.mit.edu/v4/input-formats/globals

Adds a path to the search path for Accelergy Library Plug-Ins. Multiple paths can be specified using prefixes and suffixes.

```yaml
*ACCELERGY_COMPONENT_LIBRARIES*: <PATH>
```

--------------------------------

### Basic Problem Specification Structure

Source: https://timeloop.csail.mit.edu/v4/input-formats/problem

The root structure for a Timeloop problem definition file.

```yaml
# problem.yaml
problem:
  version: 0.4
  shape:
      ...
  instance:
      ...
```

--------------------------------

### Globals Configuration Structure

Source: https://timeloop.csail.mit.edu/v4/input-formats/globals

Defines the top-level 'globals' key for setting environment variables and custom expression functions. Ensure the version is compatible.

```yaml
globals:
  version: 0.4

  environment_variables:
    ENVIRONMENT_VARIABLE_1: Value1
    ENVIRONMENT_VARIABLE_2: Value2
    ...
  expression_custom_functions:
    - path_to_script_1.py
    - path_to_script_2.py
```

--------------------------------

### Convert Jupyter Notebook to Python Script

Source: https://timeloop.csail.mit.edu/orojenesis

If a GUI is not accessible, this command converts a Jupyter notebook file to a Python script. Replace '<my-notebook.ipynb>' with the actual notebook filename.

```bash
jupyter nbconvert --to script <my-notebook.ipynb>
```

--------------------------------

### Skeleton YAML Input Structure

Source: https://timeloop.csail.mit.edu/v4/input-formats

A template showing the primary top-level keys required for a timeloop-mapper run.

```yaml
problem:
    ...

architecture:
    ...

sparse_optimizations:
    ...

contraints:
   ....

mapper:
   ....
```

--------------------------------

### Define Component Constraints

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/constraints

Constraints can be attached directly to a component definition or provided in a standalone file.

```yaml
- !Component
  constraints:
    spatial: <Spatial constraint dictionary>
    temporal: <Temporal constraint dictionary>
    dataspace: <Dataspace constraint dictionary>
```

```yaml
constraints:
  version: 0.4
  targets:
  - target: <Name of component>
    type: <Spatial, temporal, or dataspace>
    constraints: <Constraint dictionary>
  - target: <Name of component>
    ...
  - target: <Name of component>
    ...
```

--------------------------------

### Define Sparse Optimizations in Component

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/sparse-optimizations

Structure for defining sparse optimizations directly within a component definition.

```yaml
- !Component
  sparse_optimizations:
    action_optimization: <Action optimization dictionary>
    representation_format: <Representation format dictionary>
    compute_optimization: <Compute optimization dictionary>
```

--------------------------------

### Environment Variable: TIMELOOP_USE_ISL

Source: https://timeloop.csail.mit.edu/v4/input-formats/globals

Enables ISL-based mapping evaluation. Set to 1 to activate.

```yaml
TIMELOOP_USE_ISL: 1
```

--------------------------------

### Configure Exhaustive Search

Source: https://timeloop.csail.mit.edu/v4/input-formats/mapper

Sets up an exhaustive search across the mapspace using the linear_pruned algorithm.

```yaml
mapper:
  version: 0.4
  optimization_metric: [ delay, energy ]
  algorithm:           linear_pruned
  timeout:             0
  victory_condition:   0
  search_size:         0
```

--------------------------------

### Define a Storage Hierarchy

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/architecture

Create a three-level storage hierarchy using a top-level Hierarchical branch with Component leaves.

```yaml
- !Hierarchical
  nodes:
  - !Component
    name: backing_storage
    ... # Backing storage definition

  - !Component
    name: local_cache
    ... # Local cache definition

  - !Component
    name: compute
    ... # Compute definition
```

--------------------------------

### Hierarchical Architecture Definitions

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/architecture

Defines how to structure hardware components using hierarchical, parallel, and container nodes.

```APIDOC
## Hierarchical Architecture Configuration

### Description
Defines the hardware hierarchy using branch nodes like `!Hierarchical` and `!Parallel` to organize storage and compute components.

### Structure
- **!Hierarchical**: A branch node containing a list of sub-nodes.
- **!Parallel**: A branch node where sub-nodes operate in parallel.
- **!Container**: A node that can hold other elements and define spatial constraints.
- **!Component**: A leaf node representing physical hardware elements like storage or compute units.
```

--------------------------------

### Define Parallel Local Stores in Timeloop

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/architecture

Use the `!Parallel` key to define multiple local stores that operate in parallel within a hierarchical structure. This is useful for scenarios where independent data paths are required.

```yaml
- !Hierarchical
  nodes:
  - !Container
    name: backing_store
    ... # backing_store defnition

  - !Parallel # local_store_for_dataspace_A and local_store_for_dataspace_B are parallel
    nodes:
    - !Component
      name: local_store_for_dataspace_A
      ... # definition
    - !Component
      name: local_store_for_dataspace_B
      ... # definition

  - !Component # Back out of the parallel block, the compute is lower in the hierarchy below the local stores
    name: compute
    ... # definition
```

--------------------------------

### Access Top-Level Variables

Source: https://timeloop.csail.mit.edu/v4/parsing_and_intermediate_files/arithmetic-parsing

Demonstrates referencing global variables defined at the top level of the specification.

```yaml

variables:
global_a: 5

# Somewhere else
expression: global_a
```

--------------------------------

### Mapper Configuration Root Key

Source: https://timeloop.csail.mit.edu/v4/input-formats/mapper

The root YAML key for configuring the mapper module. This is the entry point for all mapper-related settings.

```yaml
mapper:
```

--------------------------------

### Accelerator Design YAML Skeleton

Source: https://timeloop.csail.mit.edu/v4/input-formats/design

The base structure for defining an accelerator design, including optional constraints and sparse optimizations.

```yaml
architecture:
      ....

constraints: # Extra constraints that are not embedded in the architecture
     ....

sparse_optimizations: # Extra sparse optimizations that are not embedded in the architecture
     ...

components: # Compound components that may be instantiated in the architecture
     ...
```

--------------------------------

### Dataspace Constraints Configuration

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/constraints

Defines the constraints applied to dataspaces to control data movement and storage behavior.

```APIDOC
## Dataspace Constraints

### Description
Defines how dataspaces interact with components, specifically regarding coalescing, bypassing, and storage retention.

### Parameters
- **no_coalesce** (list) - Optional - A list of dataspaces for which coalescing opportunities are disallowed.
- **bypass** (list) - Optional - A list of dataspaces which bypass this component, transferring directly between parents/children.
- **keep** (list) - Optional - A list of dataspaces which are stored in this component.
- **keep_only** (list) - Optional - A list of dataspaces to keep; all other dataspaces are bypassed.
```

--------------------------------

### Using Custom Expression Function in YAML

Source: https://timeloop.csail.mit.edu/v4/input-formats/globals

Demonstrates how to reference a custom Python function defined in a script within the YAML specification. The function must be imported via the 'expression_custom_functions' key.

```yaml
globals:
    version: 0.4
    expression_custom_functions:
    - script.py
    ...

variables:
    evaluated_value: my_function(5) # Imported my_function from script.py
```

--------------------------------

### Arithmetic Level Specifications and Stats

Source: https://timeloop.csail.mit.edu/v4/output-formats/stats

Details the specifications and statistics for the arithmetic level, including MACC instances, energy per compute, and total energy consumed. This is crucial for performance and power analysis.

```text
Level 0
-------
=== MACC ===

    SPECS
    -----
    Word bits             : 8
    Instances             : 16 (16*1) // (mesh-X*mesh-Y)
    Compute energy        : 0.56 pJ // energy per compute 

    STATS
    -----
    Utilized instances           : 16
    Cycles                       : 3072
    Algorithmic Computes (total) : 49152
    Actual Computes (total)      : 49152
    Gated Computes (total)       : 0
    Skipped Computes (total)     : 0
    Energy (total)               : 27564.44 pJ
    Area (total)                 : 5316.00 um^2
```

--------------------------------

### BibTeX Citations for Timeloop and Related Tools

Source: https://timeloop.csail.mit.edu/citing-timeloop

Use these BibTeX entries to cite Timeloop and its associated research methodologies in academic publications.

```BibTeX
@inproceedings{timeloop,
  author      = {Parashar, Angshuman and Raina, Priyanka and Shao, Yakun Sophia and  Chen, Yu-Hsin and Ying, Victor A and Mukkara, Anurag and Venkatesan, Rangharajan and Khailany, Brucek and Keckler, Stephen W and Emer, Joel},
  booktitle   = {2019 IEEE international symposium on performance analysis of systems and software (ISPASS)}, pages={304--315}, year={2019},
  title       = {Timeloop: A systematic approach to dnn accelerator evaluation},
  year        = {2019},
}
@inproceedings{ruby,
  author      = {M. Horeni and P. Taheri and P. Tsai and A. Parashar and J. Emer and S. Joshi},
  booktitle   = {2022 IEEE International Symposium on Performance Analysis of Systems and Software (ISPASS)},
  title       = {Ruby: Improving Hardware Efficiency for Tensor Algebra Accelerators Through Imperfect Factorization},
  year        = {2022},
}
@inproceedings{sparseloop,
  author      = {Wu, Yannan N. and Tsai, Po-An, and Parashar, Angshuman and Sze, Vivienne and Emer, Joel S.},
  booktitle   = {{ ACM/IEEE International Symposium on Microarchitecture (MICRO)}},
  title       = {{Sparseloop: An Analytical Approach To Sparse Tensor Accelerator Modeling }},
  year        = {{2022}}
}
@inproceedings{accelergy,
  author      = {Wu, Yannan Nellie and Emer, Joel S and Sze, Vivienne},
  booktitle   = {2019 IEEE/ACM International Conference on Computer-Aided Design (ICCAD)},
  title       = {Accelergy: An architecture-level energy estimation methodology for accelerator designs},
  year        = {2019},
}
@inproceedings{cimloop,
  author      = {Andrulis, Tanner and Emer, Joel S. and Sze, Vivienne},
  booktitle   = {2024 IEEE International Symposium on Performance Analysis of Systems and Software (ISPASS)}, 
  title       = {{CiMLoop}: A Flexible, Accurate, and Fast Compute-In-Memory Modeling Tool}, 
  year        = {2024},
}
```

--------------------------------

### Specify Representation Format for a Component

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/sparse-optimizations

Use the `data_spaces` key to specify a list of formats for each tensor rank. Each element in the list identifies the component by `name` and assigns formats to its ranks via the `ranks` key.

```yaml
!Component
  name: buffer
  sparse_optimizations:
    representation_format:   
      data_spaces:
        - name: A            
          ranks:                
            - format: CP   
            ...

```

--------------------------------

### Define a Branch Node Structure

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/architecture

The generalized format for defining branch nodes to organize architecture components.

```yaml
- !<BRANCHTYPE_ADJECTIVE>
  nodes: [List of nodes in this branch]
```

--------------------------------

### Specify Number of Instances in Timeloop

Source: https://timeloop.csail.mit.edu/v4/input-formats/variables

The 'n_instances' special variable denotes the number of component instances. It is required for all components and defaults to 1 if not specified.

```yaml
n_instances: 100
```

--------------------------------

### Generate Data Movement Bounds for 1x1 Convolution

Source: https://timeloop.csail.mit.edu/orojenesis

Define a 1x1 convolution workload and use the GenerateBound utility to compute its data movement bounds. This requires specifying the workload, output directory, architecture, and mapper configurations.

```python
# Define the workload shape. 
prob = utils.Conv(R=1, S=1, C=32, K=16)
mapper_yaml = pathlib.Path('./configs/single-einsum/conv_mapper.yaml') 

# Specify output directory
output_dir = pathlib.Path('./outputs/single-einsum')

arch_yaml = pathlib.Path('./configs/single-einsum/arch.yaml')
utils.GenerateBound(prob, output_dir, arch_yaml, mapper_yaml, keep_one_best_entry_across_buf=True)
```

--------------------------------

### Environment Variable: TIMELOOP_OUTPUT_STAT_SCIENTIFIC

Source: https://timeloop.csail.mit.edu/v4/input-formats/globals

Enables scientific notation for Timeloop statistic outputs. Use in conjunction with TIMELOOP_OUTPUT_STAT_DEFAULT_FLOAT: 0.

```yaml
TIMELOOP_OUTPUT_STAT_SCIENTIFIC: 1
```

--------------------------------

### Array of PEs with X and Y Spatial Constraints

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/architecture

Configure arrays of processing elements (PEs) with distinct spatial constraints for X and Y dimensions by splitting the fanout across multiple containers. This allows for fine-grained control over resource reuse.

```yaml
- !Hierarchical
  nodes:
  - !Component
    name: backing_store
    ... # backing_store defnition

  - !Container
    name: column_of_tiles
    ... # tile defnition
    spatial: {meshX: 8}
    constraints:
        spatial:
            permutation: AB
            split: 2 # There is no Y here, so we put the split after all dimensions so nothing is assigned to Y.
            factors: [A=1, B=8]

  - !Container
    name: tile
    ... # tile defnition
    spatial: {meshY: 12}
    constraints:
        spatial:
            permutation: CD
            split: 0 # There is no X here, so we put the split as early as possible so everything is assigned to X.
            factors: [C=3, D=4]
            no_reuse: [Weights] # Only applies to the Y dimension!

  - !Component # The local cache is in the tile, so there are 96 total caches
    name: local_cache
    ... # definition

  - !Component # The compute is in the tile, so there are 96 total compute elements
    name: compute
    ... # definition
```

--------------------------------

### Timeloop Memory Level Bypass and Utilization

Source: https://timeloop.csail.mit.edu/v4/output-formats/mapping

Shows the format for displaying memory level bypass and utilization information in Timeloop, including tensor details and their status.

```text
RegisterFile [ Weights:1 (1) Inputs:16 (16) Outputs:16 (16) ]
-------------------------------------------------------------
```

--------------------------------

### Environment Variable: TIMELOOP_HIDE_INCONSEQUENTIAL_STATS

Source: https://timeloop.csail.mit.edu/v4/input-formats/globals

When set to 1, this variable prevents the output of zero-energy zero-access buffers and networks in Timeloop results.

```yaml
TIMELOOP_HIDE_INCONSEQUENTIAL_STATS: 1
```

--------------------------------

### Express Spatial Fanout

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/architecture

Apply spatial fanout to a leaf node and define spatial constraints for mapping.

```yaml
nodes: # Top-level hierarchy
- !Container
  name: top

- !Container # PE
  name: PE
  attributes: {Omitted for brevity}
  spatial: {meshY: 12}
  constraints:
    spatial: {factors: [P=12]} # Each spatial PE handles a different index of P

- !Component # Storage
  name: spad
  class: storage
  attributes: {Omitted for brevity}

- !Component # MAC unit
  name: mac
  class: intmac
  attributes: {Omitted for brevity}
```

--------------------------------

### Name a Component Class

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/components

Assigns a unique name to a compound component class. This name is used when instantiating the component.

```yaml
compound_components:
   ...
  classes:
     - name: smartbuffer
```

--------------------------------

### Define Component Attributes

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/components

Specifies high-level hardware properties for a component class. 'must_specify' indicates user-provided values are required, while others can have defaults or be derived.

```yaml
compound_components:
classes:
- name: smartbuffer
  attributes:
    technology: must_specify
    memory_depth: must_specify
    memory_width: must_specify
    storage_n_banks: 1
    gen_width: log(memory_depth)
  ...
```

--------------------------------

### Representation Format for Pre-tiled Tensors

Source: https://timeloop.csail.mit.edu/v4/input-formats/design/sparse-optimizations

For pre-tiled tensors, the representation format can have more ranks than the tensor's dimensions to accommodate multiple storage levels. Storage levels closer to the root must have an equal or greater number of ranks than their children.

```yaml
sparse_optimizations:
  version: 0.4
  targets:
    - name: BackingStorage
      representation_format:
        data_spaces:
          - name: B          # pretiling is required, so B's is represented with 3 ranks
            ranks:
              - format: UOP
              - format: UOP
              - format: CP

    - name: Buffer
      representation_format:
        data_spaces:
          - name: B
            ranks:          # each tile of B requires two ranks only
              - format: UOP
              - format: CP
          ...

```

--------------------------------

### Reference Existing Problem Shape

Source: https://timeloop.csail.mit.edu/v4/input-formats/problem

Reference a pre-defined problem shape from an external file.

```yaml
problem:
  shape: cnn-layer
  ...
```
Tokens:
Raw