#
Introduction to working with tensors in Vespa

Tensors allow Vespa to support more advanced ranking models such as large
logistic regression models and neural networks. In this document tensors are
introduced and some examples of their use are shown. For more detailed
information, please refer to the tensor user guide
and the tensor reference.

## Tensor concepts

In Vespa, we refer to tensors as a data structure which is a generalization of
scalars, vectors and matrices:

- A scalar is a tensor of order 0.
- A vector is a tensor of order 1.
- A matrix is a tensor of order 2.

Tensors can have any order.

Tensors consist of a set of double valued cells, with each cell having a unique
address. A cells address is specified by its index or label along all
dimensions. The number of dimensions in a tensor is the order of the tensor.
Each dimension can be either sparse or dense. Sparse dimensions have labels
designating their address, while dense dimensions have indices.

For instance, using literal form, the tensor:

```
{
{x:2, y:1}:1.0,
{x:0, y:2}:1.0
}
```

has two dimensions named `x`

and `y`

, and has two cells with defined values. A
graphical representation is showed here:

When tensors are defined you need to declare it’s type. The following defines a
sparse matrix:

The following defines a dense matrix:

Vespa needs to know the type of tensor to optimize the ranking pipeline. As
seen above, the dimensions themselves define if they are sparse or dense.
However, mixed tensors (sparse along one dimension, but dense along another) is
currently not supported.

## Tensor examples

In the following examples, we will use the tensor playground to visualize
tensor operations. The playground can be started by deploying the tensor sample
app, and opening “http://[host]:[port]/playground/index.html”. By clicking
on the links below, a setup string will be copied to the clipboard. Paste
this string into the setup input box in the playground and press enter.

- Dense tensor dot product
- Sparse tensor dot product
- Vector-matrix product
- Matrix-matrix product
- Tensor generation, dimension renaming and concatenation
- Neural network

The neural network example is quite a bit more involved. Here, the network has
3 input neurons, 5 hidden neurons and a single output neuron. An example of
neural networks in action can be found in the blog recommendation tutorial
part 3.

## Using tensors in Vespa

Please refer to the the tensor user guide and for
details of using tensors in Vespa. Also try the blog
recommendation tutorial.