CXX Interface

Overview

The TBLIS [C interface](C Interface) is complicated by requiring explicit user specification and management of tensor layouts, generic typing, etc. The C++ interface is designed to streamline this process by providing convenient tensor, matrix, and vector container and view objects. TBLIS containers behave similarly to STL containers in that they own the tensor/matrix/vector data and handle allocation and deallocation based on the container lifetime. Views offer a similar interface for accessing the underlying data, but do not imply ownership and are relatively lightweight. View come in two flavors: const_views that do not allow modification of the underlying data (but can be shifted, resized, etc.), and non-const views, that do allow modification. Container and view objects are templated over the underlying data type.

Tensor, Matrix, and Vector Objects

Object Type	Tensor	Matrix	Vector
container	tensor<T,Allocator=...>	matrix<T,Allocator=...>	row<T,Allocator=...>
const view	const_tensor_view<T>	const_matrix_view<T>	const_row_view<T>
non-const view	tensor_view<T>	matrix_view<T>	row_view<T>

C++ Interface for Tensor Operations

The six basic [tensor operations](Tensor Operations) (and their matrix and vector counterparts) are accessible via:

Operation	Interface
add	template <typename T> void add(T alpha, const_row_view<T> A, T beta, row_view<T> B); template <typename T> void add(tblis::single, T alpha, const_row_view<T> A, T beta, row_view<T> B); template <typename T> void add(const communicator& comm, T alpha, const_row_view<T> A, T beta, row_view<T> B); template <typename T> void add(T alpha, const_matrix_view<T> A, T beta, matrix_view<T> B); template <typename T> void add(tblis::single, T alpha, const_matrix_view<T> A, T beta, matrix_view<T> B); template <typename T> void add(const communicator& comm, T alpha, const_matrix_view<T> A, T beta, matrix_view<T> B); template <typename T> void add(T alpha, const_tensor_view<T> A, const label_type* idx_A, T beta, tensor_view<T> B, const label_type* idx_B); template <typename T> void add(tblis::single, T alpha, const_tensor_view<T> A, const label_type* idx_A, T beta, tensor_view<T> B, const label_type* idx_B); template <typename T> void add(const communicator& comm, T alpha, const_tensor_view<T> A, const label_type* idx_A, T beta, tensor_view<T> B, const label_type* idx_B);
dot	template <typename T> void dot(const_row_view<T> A, const_row_view<T> B, T& result); template <typename T> void dot(tblis::single, const_row_view<T> A, const_row_view<T> B, T& result); template <typename T> void dot(const communicator& comm, const_row_view<T> A, const_row_view<T> B, T& result); template <typename T> T dot(const_row_view<T> A, const_row_view<T> B); template <typename T> T dot(tblis::single, const_row_view<T> A, const_row_view<T> B); template <typename T> T dot(const communicator& comm, const_row_view<T> A, const_row_view<T> B); template <typename T> void dot(const_matrix_view<T> A, const_matrix_view<T> B, T& result); template <typename T> void dot(tblis::single, const_matrix_view<T> A, const_matrix_view<T> B, T& result); template <typename T> void dot(const communicator& comm, const_matrix_view<T> A, const_matrix_view<T> B, T& result); template <typename T> T dot(const_matrix_view<T> A, const_matrix_view<T> B); template <typename T> T dot(tblis::single, const_matrix_view<T> A, const_matrix_view<T> B); template <typename T> T dot(const communicator& comm, const_matrix_view<T> A, const_matrix_view<T> B); template <typename T> void dot(const_tensor_view<T> A, const label_type* idx_A, const_tensor_view<T> B, const label_type* idx_B, T& result); template <typename T> void dot(tblis::single, const_tensor_view<T> A, const label_type* idx_A, const_tensor_view<T> B, const label_type* idx_B, T& result); template <typename T> void dot(const communicator& comm, const_tensor_view<T> A, const label_type* idx_A, const_tensor_view<T> B, const label_type* idx_B, T& result); template <typename T> T dot(const_tensor_view<T> A, const label_type* idx_A, const_tensor_view<T> B, const label_type* idx_B); template <typename T> T dot(tblis::single, const_tensor_view<T> A, const label_type* idx_A, const_tensor_view<T> B, const label_type* idx_B); template <typename T> T dot(const communicator& comm, const_tensor_view<T> A, const label_type* idx_A, const_tensor_view<T> B, const label_type* idx_B);
reduce	template <typename T> void reduce(reduce_t op, const_row_view<T> A, T& result, len_type& idx); template <typename T> void reduce(tblis::single, reduce_t op, const_row_view<T> A, T& result, len_type& idx); template <typename T> void reduce(const communicator& comm, reduce_t op, const_row_view<T> A, T& result, len_type& idx); template <typename T> std::pair<T,len_type> reduce(reduce_t op, const_row_view<T> A); template <typename T> std::pair<T,len_type> reduce(tblis::single, reduce_t op, const_row_view<T> A); template <typename T> std::pair<T,len_type> reduce(const communicator& comm, reduce_t op, const_row_view<T> A); template <typename T> void reduce(reduce_t op, const_matrix_view<T> A, T& result, len_type& idx); template <typename T> void reduce(tblis::single, reduce_t op, const_matrix_view<T> A, T& result, len_type& idx) template <typename T> void reduce(const communicator& comm, reduce_t op, const_matrix_view<T> A, T& result, len_type& idx); template <typename T> std::pair<T,len_type> reduce(reduce_t op, const_matrix_view<T> A); template <typename T> std::pair<T,len_type> reduce(tblis::single, reduce_t op, const_matrix_view<T> A); template <typename T> std::pair<T,len_type> reduce(const communicator& comm, reduce_t op, const_matrix_view<T> A); template <typename T> void reduce(reduce_t op, const_tensor_view<T> A, const label_type* idx_A, T& result, len_type& idx); template <typename T> void reduce(tblis::single, reduce_t op, const_tensor_view<T> A, const label_type* idx_A, T& result, len_type& idx); template <typename T> void reduce(const communicator& comm, reduce_t op, const_tensor_view<T> A, const label_type* idx_A, T& result, len_type& idx); template <typename T> std::pair<T,len_type> reduce(reduce_t op, const_tensor_view<T> A, const label_type* idx_A); template <typename T> std::pair<T,len_type> reduce(tblis::single, reduce_t op, const_tensor_view<T> A, const label_type* idx_A); template <typename T> std::pair<T,len_type> reduce(const communicator& comm, reduce_t op, const_tensor_view<T> A, const label_type* idx_A);
scale	template <typename T> void scale(T alpha, row_view<T> A); template <typename T> void scale(tblis::single, T alpha, row_view<T> A); template <typename T> void scale(const communicator& comm, T alpha, row_view<T> A); template <typename T> void scale(T alpha, matrix_view<T> A); template <typename T> void scale(tblis::single, T alpha, matrix_view<T> A); template <typename T> void scale(const communicator& comm, T alpha, matrix_view<T> A); template <typename T> void scale(T alpha, tensor_view<T> A, const label_type* idx_A); template <typename T> void scale(tblis::single, T alpha, tensor_view<T> A, const label_type* idx_A); template <typename T> void scale(const communicator& comm, T alpha, tensor_view<T> A, const label_type* idx_A);
set	template <typename T> void set(T alpha, row_view<T> A); template <typename T> void set(tblis::single, T alpha, row_view<T> A); template <typename T> void set(const communicator& comm, T alpha, row_view<T> A); template <typename T> void set(T alpha, matrix_view<T> A); template <typename T> void set(tblis::single, T alpha, matrix_view<T> A); template <typename T> void set(const communicator& comm, T alpha, matrix_view<T> A); template <typename T> void set(T alpha, tensor_view<T> A, const label_type* idx_A); template <typename T> void set(tblis::single, T alpha, tensor_view<T> A, const label_type* idx_A); template <typename T> void set(const communicator& comm, T alpha, tensor_view<T> A, const label_type* idx_A);
mult	template <typename T> void mult(T alpha, const_matrix_view<T> A, const_matrix_view<T> B, T beta, matrix_view<T> C); template <typename T> void mult(tblis::single, T alpha, const_matrix_view<T> A, const_matrix_view<T> B, T beta, matrix_view<T> C); template <typename T> void mult(const communicator& comm, T alpha, const_matrix_view<T> A, const_matrix_view<T> B, T beta, matrix_view<T> C); template <typename T> void mult(T alpha, const_tensor_view<T> A, const label_type* idx_A, const_tensor_view<T> B, const label_type* idx_B, T beta, tensor_view<T> C, const label_type* idx_C); template <typename T> void mult(tblis::single, T alpha, const_tensor_view<T> A, const label_type* idx_A, const_tensor_view<T> B, const label_type* idx_B, T beta, tensor_view<T> C, const label_type* idx_C); template <typename T> void mult(const communicator& comm, T alpha, const_tensor_view<T> A, const label_type* idx_A, const_tensor_view<T> B, const label_type* idx_B, T beta, tensor_view<T> C, const label_type* idx_C);

The functions which take a const communicator& argument are parallelized over the given tblis::communicator (which is an alias of tci::communicator). See the Threading section for more details. Functions which take the global value tblis::single are single-threaded. The remaining functions are parallelized automatically over the current requested number of threads.

Containers and Views

Tensor containers allocated data for the tensor upon construction or re-initialization, and deallocate the data when they are destroyed. Containers are also templated over the base data type and an optional STL-style allocator. The possible tensor constructors are:

1. tensor<T,Alloc>()

   Create an empty tensor. The tensor data should not be dereferenced. The object can be later re-initialized.

2. template <typename OAlloc> tensor<T,Alloc>(const tensor<T, OAlloc>&, Layout layout=DEFAULT)

3. tensor<T,Alloc>(tensor<T,Alloc>&&)

   Copy (1) or move from (2) another tensor. When copying, the layout (see below) of the new tensor can be specified, which need not be the same as in the original tensor.

4. varray(const varray_view<T>& other, Layout layout=DEFAULT)

5. varray(const const_varray_view<T>& other, Layout layout=DEFAULT)

   Copy the data referenced by a tensor view, optionally specifying the layout of the new tensor.

6. template <typename U> explicit varray(const std::vector<U>& len, const T& val=T(), Layout layout=DEFAULT)

   Create a tensor with index lengths from the supplied std::vector of any integral type. The number of dimensions is assumed from the length of the vector. The tensor is filled with the specified value, and laid out according to the specified data layout. The layout ROW_MAJOR specifies generalized row-major storage, in which the last index has a unit stirdes. The layout COLUMN_MAJOR specifies generalized column-major storage, in which the first index has a unit stride. The layout DEFAULT specifies one of these layouts based on configuration parameters.

7. template <typename U> varray(const std::vector<U>& len, tblis::uninitialized, Layout layout=DEFAULT)

   Create a tensor as in (6), but do not initialize the tensor data.

Examples