Tensor

Description

The templated class tensor<value_t,format_t,storage_t> is the base container adaptor for dense tensors. Every element $t_{i_1,i_2,\dots,i_p}$ of a $p$-order $(n_1 \times n_2 \times \cdots \times n_p)$-dimensional tensor $T$ is mapped to $j$-th element of a one-dimensional container where $j = \sum_{r=1}^p i_r \cdot w_r$ with $1 \leq i_r \leq n_r $ for $1 \leq r \leq p$. For the first-order orientation $w_1 = 1$ and $w_k = n_{k-1} \cdot w_{k-1}$ for $k > 1$. For last-order orientation $w_p = 1$ and $ w_k = n_{k+1} \cdot w_{k+1}$ for $k < p$.

Example

#include <boost/numeric/ublas/tensor.hpp>

int main () {
  using namespace boost::numeric::ublas;
  tensor<double> t{4,2,3};
  for (auto k = 0ul; k < t.size (2); ++ k)
    for (auto j = 0ul; j < t.size (1); ++ j)
      for (auto i = 0ul; i < t.size (0); ++ i)
        t.at(i,j,k) = 3*i + 2*j + 5*k;
        
  std::cout << t << std::endl;
}

Definition

Defined in the header file tensor/tensor.hpp.

Model of

Tensor

Type requirements

None, except for those imposed by the requirements of Tensor .

Public base classes

tensor_container<tensor<value_t,format_t,storage_t> >

Template parameters

Parameter	Description	Default
`value_t`	The type of object stored in the tensor.
`format_t`	Storage organization. [1]	`first_order`
`storage_t`	The type of the Storage array. [2]	`std::vector<value_t>`

Member types

Member type	Description
`value_type`	Type `value_t` of the tensor elements.
`layout_type`	Format of the tensor which is either `first_order` or `last_order`.
`array_type`	Sequence container type that stores all tensor elements and is accessible with a single index.
`strides_type`	Type of the strides vector `basic_strides<std::size_t,layout_type>` that stores all tensor elements and is accessible with a single index.
`extents_type`	Type of the dimension extents vector `shape` that stores all tensor elements and is accessible with a single index.
`size_type`	Unsigned integer which is usually `std::size_t`.
`difference_type`	Unsigned integer which is usually `std::ptrdiff_t`.
`reference`	Reference type `storage_type::reference` which is in most cases `value_type&`.
`const_reference`	Constant reference type `storage_type::const_reference` which is in most cases `const value_type&`.
`pointer`	Pointer type `storage_type::pointer` which is in most cases `value_type*`.
`const_pointer`	Constant reference type `storage_type::const_reference` which is in most cases `const value_type*`.
`iterator`	RandomAccessIterator `storage_type::iterator`.
`const_iterator`	Constant RandomAccessIterator `storage_type::const_iterator`.
`reverse_iterator`	Reverse RandomAccessIterator `storage_type::reverse_iterator`.
`const_reverse_iterator`	Reverse RandomAccessIterator `storage_type::const_reverse_iterator`.
`matrix_type`	Type of the matrix `matrix<value_type,layout_type,array_type>` with which the tensor type interacts.
`vector_type`	Type of the vector `matrix<value_type,layout_type,array_type>` with which the tensor type interacts.

Alias templates

Alias template	Description
`template<class derived_type> using tensor_expression_type = detail::tensor_expression<self_type,derived_type>`	Type of tensor_expression where `self_type` is the `tensor` type.
`template<class derived_type> using matrix_expression_type = matrix_expression<derived_type>`	Type of matrix_expression.
`template<class derived_type> using vector_expression_type = vector_expression<derived_type>`	Type of vector_expression.

Member Functions

Construction

Member function	Description
`tensor ()`	Constructs an uninitialized `tensor` that holds zero elements.
`tensor (std::initializer_list<size_type> list)`	Constructs an uninitialized `tensor` where `list` specifies the dimension extents.
`tensor (extents_type const& s)`	Constructs an uninitialized `tensor` where `s` specifies the dimension extents.
`tensor (extents_type const& e, array_type const& a)`	Constructs an uninitialized `tensor` where `e` specifies the dimension extents and `a` the data elements of the tensor.
`tensor (tensor<value_type,other_layout&rt; const& other)`	Constructs tensor by copying elements from `other` where the layout is different from this layout type.
`tensor (tensor const& other)`	Constructs tensor by copying elements from `other`.
`tensor (tensor && other)`	Constructs tensor by moving elements from `other`.
`tensor (matrix_type const& other)`	Constructs tensor by copying elements from `other` matrix. The tensor will have the order 2.
`tensor (matrix_type && other)`	Constructs tensor by moving elements from `other` matrix. The tensor will have the order 2.
`tensor (vector_type const& other)`	Constructs tensor by copying elements from `other` vector. The tensor will have the order 1.
`tensor (vector_type && other)`	Constructs tensor by moving elements from `other` vector. The tensor will have the order 1.
`tensor (tensor_expression_type<derived_type> const& expr)`	Constructs tensor by evaluating the tensor expression `expr` and copying all elements of the result.
`tensor (matrix_expression_type<derived_type> const& expr)`	Constructs tensor by evaluating the matrix expression `expr` and copying all elements of the result.
`tensor (vector_expression_type<derived_type> const& expr)`	Constructs tensor by evaluating the vector expression `expr` and copying all elements of the result.

Assignment

Member function	Description
`tensor& operator=(tensor_expression_type<derived_type> const& expr)`	Evaluates the tensor expression `expr` and copyies all elements of the result.
`tensor& operator=(tensor other)`	Copies or moves elements of `other`.
`tensor& operator=(const_reference v)`	Initialiates all elements of a tensor with `v`.

Capacity

Member function	Description
`bool empty() const`	Returns true if a tensor has zero elements.
`size_type size() const`	Returns the number of elements of the tensor.
`size_type rank() const`	Returns the number of dimensions of the tensor.
`size_type order() const`	Returns the number of dimensions of the tensor.
`strides_type const& strides() const`	Returns a constant reference to the strides of the tensor.
`extents_type const& extents() const`	Returns a constant reference to the extents of the tensor.

Element access

Member function	Description
`pointer data()`	Returns a `pointer` the first element of the tensor.
`const_pointer data() const`	Returns a `const_pointer` the first element of the tensor.
`reference operator[](size_type j)`	Returns a `reference` to the `j`-th element of the storage array of the tensor. Corresponds to the function call `tensor::data()+j`
`const_reference operator[](size_type j) const`	Returns a `const_reference` to the `j`-th element of the storage array of the tensor. Corresponds to the function call `tensor::data()+j`.
`template<class ... size_types> reference at(size_type i, size_types ... is)`	Returns a `reference` to the `(i,is...)`-th element of the tensor where `(i,is...)` denotes a multi-index with `tensor::order()` elements. If `sizeof...(is)==0`, `tensor::operator[i]` is called.
`template<class ... size_types> const_reference at(size_type i, size_types ... is)`	Returns a `const_reference` to the `(i,is...)`-th element of the tensor where `(i,is...)` denotes a multi-index with `tensor::order()` elements. If `sizeof...(is)==0`, `tensor::operator[i]` is called.

Proxy Generation

Member function	Description
`template<std::size_t I, class ... index_types> tensor_index operator()(indices::Index<I> p, index_types ... ps)`	Returns a tensor index instance with index objects `(p,ps...)` for a tensor contraction where `sizeof...(ps)+1` must be equal to `tensor::order()`.

Iterators

Member function	Description
`const_iterator begin() const`	Returns a const_iterator pointing to the first element of the tensor.
`const_iterator cbegin() const`	Returns a const_iterator pointing to the first element of the tensor.
`iterator begin()`	Returns an iterator pointing to the first element of the tensor.
`const_iterator end() const`	Returns a const_iterator pointing to the position after the last element of the tensor.
`const_iterator cend() const`	Returns a const_iterator pointing to the position after the last element of the tensor.
`iterator begin()`	Returns an iterator pointing to the position after the last element of the tensor.

Modifiers

Member function	Description
`void reshape(extents_type const& e, value_type v = value_type{})`	Reshapes the tensor according to the extents `e`. If `e.product()` is greater than `tensor::size()`, the tensor is resized with `v`.

Notes

[1] Supported parameters for the storage organization are first_order and last_order.

[2] Common parameters for the storage array are std::array<N,T> and std::vector<T>.

Copyright (©) 2018 Cem Bassoy
Use, modification and distribution are subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt ).