---
title: Problem
url: 'https://timeloop.csail.mit.edu/v4/input-formats/problem'
markdown: 'https://timeloop.csail.mit.edu/v4/input-formats/problem.md'
date: '2024-08-15'
description: 'Problem specification The problem specification for timeloop defines the tensor workload (e.g., a CNN layer, an MLP layer, or a GEMM kernel) for the tool to model. It starts with the root key problem and uses two second-level keywords: shape and instance to specify the two fundamental properties of…'
taxonomy:
  category:
    - docs
---

[](#)  [ Overview ](https://timeloop.csail.mit.edu/)     [ Timeloop+Accelergy v4 ](https://timeloop.csail.mit.edu/v4)     [ Input Formats ](https://timeloop.csail.mit.edu/v4/input-formats)      Problem    

# Problem

## Problem specification

The problem specification for timeloop defines the tensor workload (e.g., a CNN layer, an MLP layer, or a GEMM kernel) for the tool to model. It starts with the root key **problem** and uses two second-level keywords: **shape** and **instance** to specify the two fundamental properties of a tensor workload.

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

### Problem Shape

A problem shape defines the operation space and data spaces of a tensor workload. The way a Timeloop user specifies the shape of a tensor workload follows closely with the [Einstein summation notation](https://en.wikipedia.org/wiki/Einstein_notation) (einsum). First, the specification requires a `name` for the problem shape. Second, the specification requires a list of `dimensions` that defines the compute (operation) space of the tensor workload. Finally, the specification requires the projection relation between the compute space and the data space (input and output tensors) using data\_spaces` key words. For example, the following specification defines the shape of a 1D convolution tensor workload:

```
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:
        ...
```

Note that the output tensor is defined as `read-write: True`, while the other input tensors are read-only with the `read-write` keyword unspecified.

With this problem shape specification, Timeloop is able to model tensor workloads that can be represnted with an einsum. In practice, because many tensor workloads share the same shape (e.g, Conv2D layers), Timeloop supports reading an existing problem shape defined in another file, for example the ones under the `problem-shapes` directory.

```
problem:
  shape: cnn-layer
  ...
```

Optionally, in the problem shape specification, the user can also specify `coefficients` to define the projection relation in data\_spaces` in a sum of product (SOP) form. These optional coefficients are useful when the user needs to specify a complex projection relationship, such as in convolutions with strides and dilations. For example, the following problem shape specification defines a 2D convolution with strides and dilations:

```
problem:
  version: 0.4
  shape:
    dimensions: [ R, S, P, Q, C, K, N ]
    coefficients:
      - name: Wstride
        default: 1
      - name: Hstride
        default: 1
      - name: Wdilation
        default: 1
      - name: Hdilation
        default: 1

  data_spaces:
      - name: Weights
        projection:
          - [ [C] ]
          - [ [K] ]
          - [ [R] ]
          - [ [S] ]
      - name: Inputs
        projection:
          - [ [N] ]
          - [ [C] ]
          # SOP form: R*Wdilation + P*Wstride
          - [ [R, Wdilation], [P, Wstride] ]
          # SOP form: S*Hdilation + Q*Hstride 
          - [ [S, Hdilation], [Q, Hstride] ] 
      - name: Outputs
        projection:
          - [ [N] ]
          - [ [K] ]
          - [ [Q] ]
          - [ [P] ]
        read-write: True
```

In summary, the keys under `shapes` are:

1. `name`: a string
2. `dimension`: a list of unique, single-character dimension names
3. `dataspaces`: a list of tensors, each defined with `name`, `projection` as a list of lists with dimension variables, and `read-write`.

### A Complete Example

```yaml

```

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

 [ ](https://timeloop.csail.mit.edu/v4/input-formats) [](https://timeloop.csail.mit.edu/v4/input-formats/design)

---

## Navigation

- Parent: [Input Formats](https://timeloop.csail.mit.edu/v4/input-formats.md)
- Next: [Design](https://timeloop.csail.mit.edu/v4/input-formats/design.md)