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:
...
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 (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:
name
: a stringdimension
: a list of unique, single-character dimension namesdataspaces
: a list of tensors, each defined with name
, projection
as a list of lists with dimension variables, and read-write
.