Documentation

General

Following the documentation style of Boost.uBLAS, the HTML documentation is in the doc and doc/tensor directories. Additionally, most functions and data structures are doxygen documented. This page shall provide an overview and demonstrate how uBLAS was extended with tensors. Note that complete examples are found in examples/tensor directory.

Tensor

Constructing

Indexing

Reshaping

Tensor Operations

Entrywise Arithmetic Operations

Entrywise arithmetic tensor operations perform a binary or unary operations on tensor, matrix and vector elements with the same multi-index. The operators are overloaded and implemented in operators_arithmetic.hpp. Consequently all objects must have the same shape. Note that none of the operators evaluate the expression but rather construct an expression template with respect to the operation. Expression templates are evaluated when the assignment operator of the tensor is encountered.

Operations	Operators	Example
Binary Operations with Tensors	+,-,/,*	Z = X*Y;
Binary Operations with Matrices	+,-,/,*	Z = X*A;
Binary Operations with Vectors	+,-,/,*	Z = X*v;
Binary Operations with Scalars	+,-,/,*	Z = 4*X;
Unary Operations	+,-	Z = -X;

Computed Assignment

Tensor assignments perform a binary or unary operations on tensor, matrix and vector elements with the same multi-index. The operators are overloaded and implemented in operators_arithmetic.hpp. Note that the implementation evaluates the expression.

Operations	Operators	Example
Operations with Tensors	+=,-=,/=,*=	Z += X;, Z *= Y;
Operations with Scalars	+=,-=,/=,*=	Z += 4;

Comparison

Comparison operations compare tensor elements with the same multi-index. The operators are overloaded and implemented in operators_comparison.hpp. Consequently all objects must have the same shape. Note that all comparisons are evaluated when the compare operator is encountered and expression objects are not generated.

Operations	Operators	Example
Tensors	==,!=,<,>,<=,>=	X==Y && Y!=Z;
Tensors with Scalars	==,!=,<,>,<=,>=	X==Y && 3*Z<=4;

Special Functions

The following free tensor functions are implemented in functions.hpp. Internally they call generic functions, defined in multiplication.hpp and algorithms.hpp, that are implemented in terms of pointers, strides and offsets. Note that the functions are evaluated immediately and no expression object is generated. Note that you can combine entrywise and compare operations as well as computed assignments with these free functions.

Operations	Operators	Example
Tensor Transposition	trans()	auto Z = trans(X,{4,3,2})
k-mode Tensor-Times-Vector	prod()	auto Z = prod(X,v,2);
k-mode Tensor-Times-Matrix	prod()	auto Z = prod(X,A,2);
Tensor-Times-Tensor	prod()	auto Z = prod(X,Y,{1,3});, auto Z = prod(X,Y,{1,3},{4,2});
Inner Product	inner_prod()	auto a = inner_prod(X,Y);
Outer Product	outer_prod()	auto Z = outer_prod(X,Y);

Einstein Notation

Expressions

Expression Template Types

There are three types of expression templates that are defined in expression.hpp. A more detailed documentation of tensor expressions is given in tensor_expression.html.

1. The templated class tensor_expression is required to be a public base of the tensor, binary_tensor_expression and unary_tensor_expression classes. It inherits from ublas_expression.
2. The templated class binary_tensor_expression contains a constant reference to a left and right expression that can be evaluated by using the access operator. It inherits from tensor_expression.
3. The templated class unary_tensor_expression contains a constant reference to an expression that can be evaluated by using the access operator. It inherits from tensor_expression.

GEneration of an Expression Template Instance

Instances of tensor expressions are generated when binary or unary entrywise operations are encountered.

Operator Type	Operand	Tensor Expression Type	Example
Binary Arithmetic Operators	Tensor Expression	Binary Tensor Expression	X*Y, X*Y+X
Binary Arithmetic Operators	Tensor & Matrix Expression	Binary Tensor Expression	B*Y-A
Binary Arithmetic Operators	Tensor & Vector Expression	Binary Tensor Expression	Z*u-A/X
Binary Arithmetic Operators	Tensor Expression & Scalar	Unary Tensor Expression	Y-3
Unary Arithmetic Operators	Tensor Expression	Unary Tensor Expression	-Z, -(X*v)

Expression Evaluation

Expressions are evaluated at latest when the assignment operator is encountered. The evaluation time depends on their types. Entrywise arithmetic tensor operations generate expression objects and are evaluated when the assignment operator is encountered. Other tensor operations such as computed assignments, comparison operations and special functions expression objects are immediately evaluated without generating expression objects.