#### Computing with tensors in Vespa Photo by Pietro Jengr on Unsplash

In computer science, a tensor is a data structure that generalizes scalars,
vectors, matrices, and higher-order structures into a single construct.

In Vespa we have introduced a tensor formalism that differs from what one
usually finds in most modern machine learning frameworks today. The main
differences are:

• Named dimensions
• Unified sparse and dense tensor types
• A small but powerful set of core functions

In this blog post, we’ll explore these and other aspects of tensors in Vespa.
We will also introduce the recently released tensor
playground, a tool to get familiar with and
explore tensors and tensor expressions in an interactive environment.

Tensors are multi-dimensional arrays of numeric values and can be viewed as a
generalization of vectors and matrices. A tensor with one dimension (a
first-order tensor) is a vector, a two-dimensional (second-order) tensor is a
matrix, and so on. A scalar value is a tensor without any dimensions.

In most frameworks, these dimensions have an implicit ordering. For instance, a
matrix has two dimensions. A multiplication between two matrices, `A` and `B`
with sizes `(i,j)` and `(j,k)`, results in a matrix with size `(i,k)`. Values
along the columns in `A` and the rows in `B` are multiplied and summed. Thus
these must have equal size. If not, for instance if `B` had size `(k,j)`, `B`
would need a transpose to `(j,k)` before multiplication.

Implicitly ordered dimensions pose a problem: what do the dimensions represent?
For instance, consider loading a (monochrome) image from a file into a matrix.
It is not immediately clear which dimension represents the height or width, as
that depends on the file format. Additionally, a file containing a set of color
images has two additional dimensions: the number of images, and the color
channels (e.g. RGB). This is called NCHW format. Sometimes it is stored as
NHWC, which is the default representation in TensorFlow. Interestingly, NCHW is
the preferred format on GPUs.

Knowing which dimension is which is essential when performing various
operations; one generally wants to rotate images by working on the height and
width dimensions, not on the channel and height dimensions. However, after a
series of data manipulations, keeping track of dimensions can quickly become
challenging.

However, the tensor does not contain the information itself to help describe the
dimensions. As a result, practitioners often use comments such as the following
to document the dimension order:

``````# Num x Height x Width x Channel
tensor.shape
> torch.Size([100, 64, 64, 3])
``````

This is obviously error-prone.

In Vespa, we have taken a different approach and introduced named dimensions.
This enables a strong tensor type system. An example of a tensor type in Vespa
which holds the same data as above:

``````tensor(num, height, width, channel)
``````

This type system provides more formal documentation, which makes it easier to
work with for humans. It also introduces the ability for tensors and tensor
operations to be semantically verified. This means we can perform static type
inference for all computation, catching errors at an early compile-time stage
rather than during runtime.

Later in the post, we’ll see how this enables arbitrarily complex computation
with only a minimal, concise set of core operations.

## Sparse and dense tensors

The tensor as a multi-dimensional array is often considered to be dense. This
means that all combinations of dimension indexes have a value, even if that
value is `0` or `NaN`. However, a tensor with many such values could be
represented more efficiently as a sparse tensor, where only the non-empty values
are defined. This can lead to considerable savings in space.

Unfortunately, the internal representation of sparse tensors in most frameworks
makes them incompatible with regular dense tensors. This leads to an entirely
separate set of functions operating on sparse and dense tensors, with functions
to convert between the two.

Vespa supports dense, sparse, and tensors that contain both dense and sparse
dimensions, called a mixed tensor. A dense tensor is a tensor containing only
“indexed” dimensions. An indexed dimension is indexed by integers, like an
array. The following is an example of a dense tensor containing two indexed
dimensions:

``````tensor(width, height)
``````

A sparse tensor is conversely a tensor consisting of only “mapped” dimensions. A
mapped dimension is indexed by strings, like a map or hash table. An example of
a sparse tensor containing two mapped dimensions:

``````tensor(model_id{}, feature{})
``````

A mixed tensor can contain both types:

``````tensor(model_version_id{}, first_layer_weights, second_layer_weights)
``````

This particular example effectively works as a lookup table. By providing the
`model_version_id`, one can extract a dense tensor (called a dense subspace).
For instance, this can be useful for a single tensor to contain the weights for
multiple versions of a model, e.g., a neural network.

All in all, this enables a flexible data representation.

## Tensor operations

Most frameworks that operate on and manipulate tensors have an extensive library
of functions. For instance, TensorFlow has hundreds of different operations
organized in various groups according to their function. Examples are
constructors, general manipulation, linear algebra, neural networks, and so on.
Some operations work element-wise, some on entire tensors, and some combine
tensors.

All operations have assumptions on their input tensors. For instance, a matrix
multiplication operation requires two matrix tensors with the same column/row
size. Likewise, a dot product operation requires two vectors with the same
vector length. These two operations are essentially the same: the sum of the
products of elements along a dimension. Yet two different operations are
provided: `matmul` and `dotprod`.

A two-dimensional convolution requires an input of four dimensions: the batch
size, color channels, width and height. This ordering is called NCHW, which is
the most efficient for GPU processing. However, the default in TensorFlow is
NHWC. Therefore, the operations working on these tensors need to know the
format, which must be provided by the developer as the format is not part of the
tensor.

Another example is the different operations based on tensor type. For instance,
there are two different operations for `concat`: one for a dense tensor and one
for sparse.

The inevitable consequence is that most frameworks get an extensive library of
operations. The problem with such large libraries is interoperability and
maintainability.

Assume you train a model on one framework and want to run inference on another.
The common way to represent the model is as a computational graph, where each
vertex is an operation. Evaluating a given graph on another system requires the
implementation of all operations in the graph. To guarantee general
interoperability between two frameworks, all operations in the original
framework must have an implementation. This becomes increasingly less feasible
as frameworks grow to have hundreds or thousands of operations.

interoperability by requiring binary compatibility.

The tensor framework in Vespa, on the other hand, takes a different approach.
Tensors with named dimensions allow for a strong type system with well-founded
semantics. This makes it possible to define a small set of foundational
mathematical operations in which all other computations can be expressed.

Unary operations work on single tensors; examples include filtering and
reduction. Binary operations combine two input tensors to an output tensor, for
instance, joining, extending, or calculating some relation. By combining these
operations, they can express complex computation.

Vespa provides just 8 core operations to transform tensors:

• `tensor` – construct a new tensor from a given expression
• `map` – apply a function to all values
• `reduce` – aggregate values along a dimension
• `rename` – rename a dimension
• `slice` – returns a tensor with all cells matching a partial address
• `join` – the natural join between two input tensors with a custom expression applied
• `merge` – merge two input tensors with a custom expression
• `concat` – concatenate two tensors along a given dimension

To aid developers, Vespa additionally provides higher-level, non-core
operations, which are all implemented in terms of these core operations.

This approach enables interoperability as implementing this small set is all
that is needed to realize complete support for tensor computation. Furthermore,
it makes optimization work more efficient. This is because low-level
optimizations are only required on this set of functions. Higher-level
optimizations can work on whichever chunks of these operations are beneficial,
independent of any chunking into higher-level functions humans happen to find
meaningful.

In this section, we’ll describe Vespa’s full tensor formalism, including
tensors and tensor types, and the core set of tensor operations.

## Tensor types

A tensor type consists of a value type and a set of dimensions. The value type is a numeric data type: double, float, int8, bfloat16, etc. The default value type is double.

A dimension consists of a name and a type. The type can be either indexed or mapped, and, if indexed, can optionally include a size. The number of dimensions in the tensor is called its order. A tensor without dimensions (0-order) is a single scalar value. A tensor with one dimension (first-order) is a vector. A tensor with two dimensions (second-order) is a matrix.

Note that this notion of dimensions is not to be confused with the concept of dimensions in vector space, where a vector with 3 elements can represent a vector in a 3-dimensional space.

A value in a dimension is addressed by a label. For mapped dimensions, this label is a string. For indexed dimensions this label is an integer index. Tensors with mapped dimensions only hold values for the labels that exist. Indexed dimensions must have values for all indices.

Some examples:

• `tensor()` – a scalar value (double)
• `tensor<float>(x)` – An indexed vector with 3 floats
• `tensor(x, y)` – An indexed matrix of size 2-by-3
• `tensor(name{})` – A (sparse) map of named values
• `tensor<int8>(name{}, x)` – A map of named vectors of int8

## Tensors

A tensor is simply a tensor type and a set of values. Values are held in
cells that are fully defined by the address given by the labels in each
dimension. A tensor has a string representation defined by the type followed
by the cell values.

Some examples:

• `tensor():3.0` – a scalar value (double)
• `tensor<float>(x):[1.0, 2.0, 3.0]` – An indexed vector with 3 floats
• `tensor(x, y):[[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]` – An indexed matrix of size 2-by-3
• `tensor(name{}):{ {name:foo}:2, {name:bar}:5 }` – A (sparse) map of named values
• `tensor(name{}):{ foo:2, bar:5 }` – Same as above with inferred dimension (single sparse)
• `tensor<int8>(name{}, x):{foo:[1,2], bar:[3,4]}` – A map of named vectors of int8

## Tensor functions

Vespa has a small core set of just 8 tensor functions:

• Creational: `tensor`
• Unary: `map`, `reduce`, `rename`, `slice`
• Binary: `join`, `merge`, `concat`

These can be combined and used to express potentially complex computation, as
some take general lambda expressions as arguments. Please refer to the tensor
function
reference
for detailed descriptions of these functions.

We’ll provide some examples to demonstrate the expressive power of `join` and
`reduce` in the following. These examples are also provided with a link to the
tensor playground. In this interactive
environment, you can experiment with tensor expressions. Feel free to take any
of these examples and play around with them

### Vector outer product

Given two tensors representing vectors, `A` and `B`:

``````A: tensor(x):[1,2,3]
B: tensor(y):[4,5,6]
``````

Notice that these tensors have different dimension names. We can multiply
these two tensors together, `A * B`, and the result is:

``````tensor(x,y):[[4.0, 5.0, 6.0], [8.0, 10.0, 12.0], [12.0, 15.0, 18.0]]
``````

This tensor has type `tensor(x,y)`. To see what is happening
here, note that the expression `A * B` is a convenience form of the underlying
expression:

``````join(A, B, f(a,b)(a * b))
``````

The `join` function is the most used function when combining two input tensors.
As input, it takes two tensors and a lambda function (here `f(a,b)(a * b)`) to
define how to combine matching cells. The resulting tensor is the natural join
between the input tensors, and the cell values are defined by the lambda. The
resulting type is the union of dimensions from the input tensors.

The actual operation is to combine all cells in `A` with all matching cells in
`B`, where a match is defined as having equal values on their common dimensions.
If `A` and `B` have no common dimensions, this combines all cells in `A` with
all cells in `B`.

In this example, the two input tensors have different dimensions. Since there
are no overlapping dimensions, this is in effect a Cartesian product. As
vectors, this represents an outer product and the result is thus an `x-by-y`
matrix.

Play around with this example in the playground.

### Vector inner product (dot product)

Again, given the two vectors `A` and `B` representing vectors:

``````A: tensor(x):[1,2,3]
B: tensor(x):[4,5,6]
``````

Here, the vectors have the same dimension name. Given the exact same expression
as above, `A * B` or, equivalently, `join(A, B, f(a,b)(a * b))`, the result is
now:

``````tensor(x):[4.0, 10.0, 18.0]
``````

Since the two tensors now have a common dimension, the `join` matches the cells
with equal values in that dimension. So `x` from `A` is combined with `x`
from `B`, and so on. The lambda expression `f(a,b)(a * b)` defines these values
should be multiplied. This is called the element-wise product.

The actual inner (dot) product requires these values to be summed. Thus we can
add a `sum` operation so the expression becomes `sum(A * B)`. The `sum`
operation is actually a `reduce` operation, so this expands fully to the
following:

``````reduce(join(A, B, f(a,b)(a * b)), sum)
``````

The `reduce` operation aggregates values along a dimension (or all dimensions if
omitted). Vespa has a set of built-in aggregators: `sum`, `max`, `min`, `prod`,
`count`, and `avg`. In any case, the result is:

So, we have implemented a dot product function by combining the `join` and
`reduce` operations.

Play around with this example in the playground.

### Matrix multiplication

Consider the two following tensors, `A` and `B` representing matrices:

``````A: tensor(i,j):[[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]
B: tensor(j,k):[[4.0, 5.0], [6.0, 7.0], [8.0, 9.0]]
``````

Recall that a matrix multiplication between an `n-by-x` matrix and an `x-by-m`
matrix results in a `n-by-m` matrix. This is because the multiplication iterates
over each column in the first tensor and each row in the second, and sums the
products of elements together. This is, in essence, an inner product, or dot
product, for each column and row vector in the matrices.

Multiplying (`A * B`) these two tensors together, or equivalently, joining with
a multiplication (`join(A, B, f(a,b)(a * b))`), we get the following:

``````tensor(i,j,k):[
[[4.0, 5.0], [12.0, 14.0], [24.0, 27.0]],
[[16.0, 20.0], [30.0, 35.0], [48.0, 54.0]]
]
``````

This tensor type is, as expected, the union of dimensions. The `join` has
combined all cells with a given `j` index in `A` with all cells with the same
`j` index in `B`, and multiplied the matching values together. This is entirely
similar to the first step of the dot product seen above. In mathematics, this is

Like the dot product, we need to sum over the common dimension `j`. Again, this
is either a `sum(A, B, j)` or `reduce(join(A, B, f(a,b)(a * b)), sum, j)`. Note
that we need to specify the dimension in this case because we are not summing
all elements together. This results in:

``````tensor(i,k):[[40.0, 46.0], [94.0, 109.0]]
``````

The tensor type here is as expected: the `i-by-j` matrix multiplied with
the`j-by-k` matrix resulted in a `i-by-k` matrix. So the matrix multiplication is
a `join` followed by a `sum` `reduce` over the common dimension, like the inner
product. This pattern is generalizable to tensors of any order.

Vespa also provides a higher-level `matmul` function which performs this same
operation: `matmul(A, B, j)`. This is provided as an aid for developers.
However, it is entirely implemented by the core functions `join` and `reduce`.

Play around with this example in the playground.

## Discussion

The interesting point here is that the three operations just demonstrated, outer
product, dot product, and matrix multiplication, are performed with the same
low-level functions. Thus, there is no need for multiple distinct functions or
even another separate set of functions for sparse tensors.

Much of the expressive power of Vespa’s tensor language comes from two features:
argument lambdas and the generality afforded by using named dimensions
in ‘join’s.

Many of the functions accept a lambda, which allows for evaluating general
expressions in context of a unary or binary function. These expressions can
perform any necessary calculation on their scalar inputs, and have a set of
mathematical functions available. In addition, tensor generation accepts a
lambda function without arguments that has access to other variables. This can
be used to generate a tensor by looking up values from another tensor. This is
called peeking:

``````tensor(y)(another_tensor{x:(y)})
``````

The generality of the `join` resulting from tensors with named dimensions is
arguably the most unique aspect of the language:

• A `join` between tensors with the same dimensions is equivalent to performing
an operation element-wise between the input tensors. If the lambda defines a
multiplication, this is the same as an element-wise product.
• A `join` between tensors with disjunct dimensions is the cross join, or
Cartesian product, between the input tensors.
• A `join` between tensors with partially overlapping dimensions produces
results in-between these extremes, as seen in the matrix multiplication
example above.

By combining `join` with `rename`, any such semantics can be achieved for any
tensors.

The `join` operation implements a natural join between tensors: it combines
cells in one tensor with cells from another based on the matching cells in their
common dimensions. It is thus the tensor language counterpart of the logical AND
operator.

## Summary

In this post, we’ve presented Vespa’s tensor language. This formalism provides
generic computation over dense and sparse tensors, with full static type
inference, using just eight foundational tensor functions. Named dimensions are
used to add semantic information and achieve generality, and index labels
provide support for models working with strings.

In Vespa, this formalism makes numerical computation easier to express,
understand, and optimize.