---
title: 'Input Formats'
url: 'https://timeloop.csail.mit.edu/v4/input-formats'
markdown: 'https://timeloop.csail.mit.edu/v4/input-formats.md'
date: '2024-08-15'
description: 'Top-Level Keys Timeloop and Accelergy take inputs in the form of a YAML file with specific top-level keys. These top-level keys may be included in one or more files (one or more top-level keys per file) that are concatenated together by the tool. Some keys are used only for one of the programs or…'
taxonomy:
  category:
    - docs
---

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

# Input Formats

## Top-Level Keys

Timeloop and Accelergy take inputs in the form of a YAML file with specific top-level keys. These top-level keys may be included in one or more files (one or more top-level keys per file) that are concatenated together by the tool.

Some keys are used only for one of the programs or are optional. So a skeleton input with the top-level keys for a run of `timeloop-mapper` would look like:

```yaml
problem:
    ...

architecture:
    ...

sparse_optimizations:
    ...

contraints:
   ....

mapper:
   ....
```

The following top-level keys are available to the Timeloop+Accelergy specification.

Top-level keys that are wrapped in \* may be specified multiple times using prefixes and suffixes (e.g., constraints\_1, constraints\_2, map\_constraints, arch\_constraints). Their contents will be combined by the parser.

- [architecture](https://timeloop.csail.mit.edu/v4/input-formats/./design/architecture): The architecture specification.
- [\*constraints\*](https://timeloop.csail.mit.edu/v4/input-formats/./design/constraints): Additional constraints on the mapspace (optional).
- [\*variables\*](https://timeloop.csail.mit.edu/v4/input-formats/./design/variables): Top-level variables to be used in parsing (optional).
- [\*components\*](https://timeloop.csail.mit.edu/v4/input-formats/./design/components): Compound components used in the system.
- [mapper](https://timeloop.csail.mit.edu/v4/input-formats/./mapper): Directives for the Mapper such as search algorithm and timeout (only if using the Mapper).
- [problem](https://timeloop.csail.mit.edu/v4/input-formats/./problem): Workload specification.
- [sparse\_optimizations](https://timeloop.csail.mit.edu/v4/input-formats/./sparse_optimizations): Optimizations available for sparse tensor accelerators.
- [\*globals\*](https://timeloop.csail.mit.edu/v4/input-formats/./globals): Global environment variables and directives for the parser.
- [mapspace](https://timeloop.csail.mit.edu/v4/input-formats/./mapspace): Directives describing the mapspace (i.e., imperfectly-factorized or perfectly-factorized)

## Jinja parsing

The Timeloop Python Front-End can take in a Jinja2 template and parse it to create a top-level file.

### Parser functions available

- add\_to\_path(path): Adds a path to the environment. This will be used to search for files in later parsing.
- cwd(): Returns the path of the current file. - include(file\_path, subkey=None): Parses the other file, returning the value at the subkey. If subkey is None, the contents of the full file are returned. This function substutes a YAML object into the YAML object of the current location; it does not do text substitution. Subkey may also be a period-separated list of subkeys (e.g., "a.b.c").
- include\_text(file\_path): Substitutes text from the file into the current location. This function does text substitution.
- include\_all(file\_path, subkey): Parses all files that match the file\_path and returns a list with the content of each file. This function substutes a YAML object into the YAML object of the current location; it does not do text substitution. Subkey may also be a period-separated list of subkeys (e.g., "a.b.c").
- path\_exists(path): Returns True if a path exists and False otherwise.

## Example top-level file using Jinja2 templating

```yaml

```

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

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

---

## Navigation

- Parent: [Timeloop+Accelergy v4](https://timeloop.csail.mit.edu/v4.md)
- Previous: [Python Interface](https://timeloop.csail.mit.edu/v4/python-interface.md)
- Next: [Output Formats](https://timeloop.csail.mit.edu/v4/output-formats.md)
- Children:
  - [Problem](https://timeloop.csail.mit.edu/v4/input-formats/problem.md)
  - [Design](https://timeloop.csail.mit.edu/v4/input-formats/design.md)
  - [Mapper](https://timeloop.csail.mit.edu/v4/input-formats/mapper.md)
  - [Mapspace](https://timeloop.csail.mit.edu/v4/input-formats/mapspace.md)
  - [Variables](https://timeloop.csail.mit.edu/v4/input-formats/variables.md)
  - [Globals](https://timeloop.csail.mit.edu/v4/input-formats/globals.md)