Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the develop branch, built from commit 4fd07a224d.

Tensor

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 ).