ublas/doc/tensor.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="generator" content="Bluefish 2.2.10" />
<meta http-equiv="Content-Type" content=
"text/html; charset=us-ascii" />
<link rel="stylesheet" href="../../../../boost.css" type="text/css"/>
<link rel="stylesheet" href="ublas.css" type="text/css" />
<script type="text/javascript" src="js/jquery-1.3.2.min.js" async="async" ></script>
<script type="text/javascript" src="js/jquery.toc-gw.js" async="async" ></script>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
      jax: ["input/TeX", "output/HTML-CSS"],
      extensions: ["tex2jax.js"],
      "HTML-CSS": { preferredFont: "TeX", availableFonts: ["STIX","TeX"], scale: "80" },
      tex2jax: {
      	inlineMath: [ ["$", "$"], ["\\(","\\)"] ],
      	displayMath: [ ["$$","$$"], ["\\[", "\\]"] ],
      	processEscapes: true,
      	ignoreClass: "tex2jax_ignore|dno" },
      TeX: { noUndefined: { attributes: { mathcolor: "red", mathbackground: "#FFEEEE", mathsize: "90%" } } },
      messageStyle: "none"
    });
</script>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js"></script>


<title>Tensor</title>
</head>
<body>
<h1><img src="../../../../boost.png" align="middle" />Tensor</h1>
<div class="toc" id="toc"></div>
<h2><a name="tensor"></a>Tensor</h2>
<h4>Description</h4>
<p>The templated class <code>tensor&lt;value_t,format_t,storage_t&gt;</code> 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$.
</p>
<h4>Example</h4>
<pre>
<b>#include</b> &lt;boost/numeric/ublas/tensor.hpp&gt;

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

  std::cout &lt;&lt; t &lt;&lt; std::endl;
}
</pre>

<h4>Definition</h4>
<p>Defined in the header file <code>tensor/tensor.hpp</code>.</p>

<h4>Model of</h4>
<p><a href="container_concept.html#tensor">Tensor</a></p>

<h4>Type requirements</h4>
<p>None, except for those imposed by the requirements of <a href="container_concept.html#tensor">Tensor</a> .</p>

<h4>Public base classes</h4>
<p><code>tensor_container&lt;tensor&lt;value_t,format_t,storage_t&gt; &gt;</code></p>

<h4>Template parameters</h4>
<table border="1" summary="parameters">
<tbody>
<tr>
<th>Parameter</th>
<th>Description</th>
<th>Default</th>
</tr>
<tr>
<td><code>value_t</code></td>
<td>The type of object stored in the tensor.</td>
<td></td>
</tr>
<tr>
<td><code>format_t</code></td>
<td>Storage organization. <a href=
"#tensor_1">[1]</a></td>
<td><code>first_order</code></td>
</tr>
<tr>
<td><code>storage_t</code></td>
<td>The type of the Storage array. <a href="#tensor_2">[2]</a></td>
<td><code>std::vector&lt;value_t&gt;</code></td>
</tr>
</tbody>
</table>

<h4>Member types</h4>
<table border="1" style="font-size:100%" summary="members">
<tbody style="font-size:100%" >
<tr>
<th>Member type</th>
<th>Description</th>
</tr>
<tr>
<td><code>value_type</code></td>
<td>Type <code>value_t</code> of the tensor elements.</td>
</tr>
<tr>
<td><code>layout_type</code></td>
<td>Format of the tensor which is either <code>first_order</code> or <code>last_order</code>.</td>
</tr>
<tr>
<td><code>array_type</code></td>
<td>Sequence container type that stores all tensor elements and is accessible with a single index.</td>
</tr>

<tr>
<td><code>strides_type</code></td>
<td>Type of the strides vector <code>basic_strides&lt;std::size_t,layout_type&gt;</code> that stores all tensor elements and is accessible with a single index.</td>
</tr>

<tr>
<td><code>extents_type</code></td>
<td>Type of the dimension extents vector <code>shape</code> that stores all tensor elements and is accessible with a single index.</td>
</tr>


<tr>
<td><code>size_type</code></td>
<td>Unsigned integer which is usually <code>std::size_t</code>.</td>
</tr>
<tr>
<td><code>difference_type</code></td>
<td>Unsigned integer which is usually <code>std::ptrdiff_t</code>.</td>
</tr>
<tr>
<td><code>reference</code></td>
<td>Reference type <code>storage_type::reference</code> which is in most cases <code>value_type&</code>.</td>
</tr>
<tr>
<td><code>const_reference</code></td>
<td>Constant reference type <code>storage_type::const_reference</code> which is in most cases <code>const value_type&</code>.</td>
</tr>
<tr>
<td><code>pointer</code></td>
<td>Pointer type <code>storage_type::pointer</code> which is in most cases <code>value_type*</code>.</td>
</tr>
<tr>
<td><code>const_pointer</code></td>
<td>Constant reference type <code>storage_type::const_reference</code> which is in most cases <code>const value_type*</code>.</td>
</tr>
<tr>
<td><code>iterator</code></td>
<td>RandomAccessIterator <code>storage_type::iterator</code>.</td>
</tr>
<tr>
<td><code>const_iterator</code></td>
<td>Constant RandomAccessIterator <code>storage_type::const_iterator</code>.</td>
</tr>
<tr>
<td><code>reverse_iterator</code></td>
<td>Reverse RandomAccessIterator <code>storage_type::reverse_iterator</code>.</td>
</tr>
<tr>
<td><code>const_reverse_iterator</code></td>
<td>Reverse RandomAccessIterator <code>storage_type::const_reverse_iterator</code>.</td>
</tr>

<tr>
<td><code>matrix_type</code></td>
<td>Type of the matrix <code>matrix&lt;value_type,layout_type,array_type&gt;</code> with which the tensor type interacts.</td>
</tr>
<tr>
<td><code>vector_type</code></td>
<td>Type of the vector <code>matrix&lt;value_type,layout_type,array_type&gt;</code> with which the tensor type interacts.</td>
</tr>
</tbody>
</table>

<h4>Alias templates</h4>
<table border="1" style="font-size:100%" summary="members">
<tbody style="font-size:100%" >
<tr>
<th>Alias template</th>
<th>Description</th>
<tr>
<td><code>template&lt;class derived_type&gt; <br> using tensor_expression_type = detail::tensor_expression&lt;self_type,derived_type&gt;</code></td>
<td>Type of <a href= "tensor/tensor_expression.html#tensor_expression">tensor_expression</a> where <code>self_type</code> is the <code>tensor</code> type.</td>
</tr>
<tr>
<td><code>template&lt;class derived_type&gt; <br> using matrix_expression_type = matrix_expression&lt;derived_type&gt;</code></td>
<td>Type of <a href= "matrix_expression.html#matrix_expression">matrix_expression</a>.</td>
</tr>
<tr>
<td><code>template&lt;class derived_type&gt; <br> using vector_expression_type = vector_expression&lt;derived_type&gt;</code></td>
<td>Type of <a href= "vector_expression.html#vector_expression">vector_expression</a>.</td>
</tr>
</tbody>
</table>


<h3>Member Functions</h3>

<h4>Construction</h4>


<table border="1" style="font-size:100%" summary="constructors">
<tbody style="font-size:100%" >
<tr>
<th>Member function</th>
<th>Description</th>
</tr>
<tr>
<td><code>tensor ()</code></td>
<td>Constructs an uninitialized <code>tensor</code> that holds zero elements.</td>
</tr>
<tr>
<td><code> tensor (std::initializer_list&lt;size_type&gt; list) </code></td>
<td>Constructs an uninitialized <code>tensor</code> where <code>list</code> specifies the dimension <a href="tensor/extents.html">extents</a>.</td>
</tr>
<tr>
<td><code> tensor (extents_type const& s) </code></td>
<td>Constructs an uninitialized <code>tensor</code> where
<code>s</code> specifies the dimension <a href="tensor/extents.html">extents</a>.</td>
</tr>
<tr>
<td><code> tensor (extents_type const& e, array_type const& a) </code></td>
<td>Constructs an uninitialized <code>tensor</code> where
<code>e</code> specifies the dimension <a href="tensor/extents.html">extents</a> and <code>a</code> the data elements of the tensor.</td>
</tr>

<tr>
<td><code>tensor (tensor&lt;value_type,other_layout&rt; const& other)</code></td>
<td>Constructs tensor by copying elements from <code>other</code> where the layout is different from this layout type.</td>
</tr>

<tr>
<td><code>tensor (tensor const& other)</code></td>
<td>Constructs tensor by copying elements from <code>other</code>.</td>
</tr>

<tr>
<td><code>tensor (tensor && other)</code></td>
<td>Constructs tensor by moving elements from <code>other</code>.</td>
</tr>

<tr>
<td><code>tensor (matrix_type const& other)</code></td>
<td>Constructs tensor by copying elements from <code>other</code> <a href="matrix.html">matrix</a>. The tensor will have the order 2.</td>
</tr>
<tr>
<td><code>tensor (matrix_type && other)</code></td>
<td>Constructs tensor by moving elements from <code>other</code> <a href="matrix.html">matrix</a>. The tensor will have the order 2.</td>
</tr>

<tr>
<td><code>tensor (vector_type const& other)</code></td>
<td>Constructs tensor by copying elements from <code>other</code> <a href="vector.html">vector</a>. The tensor will have the order 1.</td>
</tr>
<tr>
<td><code>tensor (vector_type && other)</code></td>
<td>Constructs tensor by moving elements from <code>other</code> <a href="vector.html">vector</a>. The tensor will have the order 1.</td>
</tr>

<tr>
<td><code>tensor (tensor_expression_type&lt;derived_type&gt; const& expr)</code></td>
<td>Constructs tensor by evaluating the <a href="tensor/tensor_expression.html">tensor expression</a> <code>expr</code> and copying all elements of the result.</td>
</tr>

<tr>
<td><code>tensor (matrix_expression_type&lt;derived_type&gt; const& expr)</code></td>
<td>Constructs tensor by evaluating the <a href="matrix_expression.html">matrix expression</a> <code>expr</code> and copying all elements of the result.</td>
</tr>

<tr>
<td><code>tensor (vector_expression_type&lt;derived_type&gt; const& expr)</code></td>
<td>Constructs tensor by evaluating the <a href="vector_expression.html">vector expression</a> <code>expr</code> and copying all elements of the result.</td>
</tr>

</tbody>
</table>
<!-------------------------------------------->

<h4>Assignment</h4>


<table border="1" style="font-size:100%" summary="constructors">
<tbody style="font-size:100%" >
<tr>
<th>Member function</th>
<th>Description</th>
</tr>
<tr>
<td><code>tensor& operator=(tensor_expression_type&lt;derived_type&gt; const& expr)</code></td>
<td>Evaluates the <a href="tensor/tensor_expression.html">tensor expression</a> <code>expr</code> and copyies all elements of the result.</td>
</tr>

<tr>
<td><code>tensor& operator=(tensor other)</code></td>
<td>Copies or moves elements of <code>other</code>.</td>
</tr>

<tr>
<td><code>tensor& operator=(const_reference v)</code></td>
<td>Initialiates all elements of a tensor with <code>v</code>.</td>
</tr>
</tbody>
</table>
<!-------------------------------------------->

<h4>Capacity</h4>

<table border="1" style="font-size:100%" summary="capacity">
<tbody style="font-size:100%" >
<tr>
<th>Member function</th>
<th>Description</th>
</tr>
<tr>
<td><code>bool empty() const</code></td>
<td>Returns true if a tensor has zero elements.</td>
</tr>

<tr>
<td><code>size_type size() const</code></td>
<td>Returns the number of elements of the tensor.</td>
</tr>

<tr>
<td><code>size_type rank() const</code></td>
<td>Returns the number of dimensions of the tensor.</td>
</tr>

<tr>
<td><code>size_type order() const</code></td>
<td>Returns the number of dimensions of the tensor.</td>
</tr>

<tr>
<td><code>strides_type const& strides() const</code></td>
<td>Returns a constant reference to the <a href="tensor/strides.html">strides</a> of the tensor.</td>
</tr>

<tr>
<td><code>extents_type const& extents() const</code></td>
<td>Returns a constant reference to the <a href="tensor/extents.html">extents</a> of the tensor.</td>
</tr>
</tbody>
</table>

<!-------------------------------------------->

<h4>Element access</h4>

<table border="1" style="font-size:100%" summary="capacity">
<tbody style="font-size:100%" >
<tr>
<th>Member function</th>
<th>Description</th>
</tr>

<tr>
<td><code>pointer data()</code></td>
<td>Returns a <code>pointer</code> the first element of the tensor.</td>
</tr>

<tr>
<td><code>const_pointer data() const</code></td>
<td>Returns a <code>const_pointer</code> the first element of the tensor.</td>
</tr>

<tr>
<td><code>reference operator[](size_type j)</code></td>
<td>Returns a <code>reference</code> to the <code>j</code>-th element of the storage array of the tensor. Corresponds to the function call <code>tensor::data()+j</code></td>
</tr>

<tr>
<td><code>const_reference operator[](size_type j) const</code></td>
<td>Returns a <code>const_reference</code> to the <code>j</code>-th element of the storage array of the tensor. Corresponds to the function call <code>tensor::data()+j</code>.</td>
</tr>


<tr>
<td><code>template&lt;class ... size_types&gt; <br> reference at(size_type i, size_types ... is)</code></td>
<td>Returns a <code>reference</code> to the <code>(i,is...)</code>-th element of the tensor where <code> (i,is...)</code> denotes a multi-index with <code>tensor::order()</code> elements. If <code>sizeof...(is)==0</code>, <code>tensor::operator[i]</code> is called. </td>
</tr>

<tr>
<td><code>template&lt;class ... size_types&gt; <br> const_reference at(size_type i, size_types ... is)</code></td>
<td>Returns a <code>const_reference</code> to the <code>(i,is...)</code>-th element of the tensor where <code> (i,is...)</code> denotes a multi-index with <code>tensor::order()</code> elements. If <code>sizeof...(is)==0</code>, <code>tensor::operator[i]</code> is called. </td>
</tr>

</tbody>
</table>


<!-------------------------------------------->

<h4>Proxy Generation</h4>

<table border="1" style="font-size:100%" summary="capacity">
<tbody style="font-size:100%" >
<tr>
<th>Member function</th>
<th>Description</th>
</tr>

<tr>
<td><code>template&lt;std::size_t I, class ... index_types&gt; <br> tensor_index operator()(indices::Index&lt;I&gt; p, index_types ... ps)</code></td>
<td>Returns a <a href="tensor/tensor_index.html">tensor index</a> instance with index objects <code>(p,ps...)</code> for a tensor contraction where <code>sizeof...(ps)+1</code> must be equal to <code>tensor::order()</code>.</td>
</tr>

</tbody>
</table>


<h4>Iterators</h4>

<table border="1" style="font-size:100%" summary="iterators">
<tbody style="font-size:100%" >
<tr>
<th>Member function</th>
<th>Description</th>
</tr>

<tr>
<td><code>const_iterator begin() const</code></td>
<td>Returns a const_iterator pointing to the first element of the tensor.</td>
</tr>

<tr>
<td><code>const_iterator cbegin() const</code></td>
<td>Returns a const_iterator pointing to the first element of the tensor.</td>
</tr>

<tr>
<td><code>iterator begin()</code></td>
<td>Returns an iterator pointing to the first element of the tensor.</td>
</tr>


<tr>
<td><code>const_iterator end() const</code></td>
<td>Returns a const_iterator pointing to the position after the last element of the tensor.</td>
</tr>

<tr>
<td><code>const_iterator cend() const</code></td>
<td>Returns a const_iterator pointing to the position after the last element of the tensor.</td>
</tr>

<tr>
<td><code>iterator begin()</code></td>
<td>Returns an iterator pointing to the position after the last element of the tensor.</td>
</tr>

</tbody>
</table>


<h4>Modifiers</h4>

<table border="1" style="font-size:100%" summary="modifiers">
<tbody style="font-size:100%" >
<tr>
<th>Member function</th>
<th>Description</th>
</tr>

<tr>
<td><code>void reshape(extents_type const& e, value_type v = value_type{})</code></td>
<td>Reshapes the tensor according to the extents <code>e</code>. If <code>e.product()</code> is greater than <code>tensor::size()</code>, the tensor is resized with <code>v</code>. </td>
</tr>

</tbody>
</table>


<h4>Notes</h4>
<p><a name="tensor_1">[1]</a> Supported parameters
for the storage organization are <code>first_order</code> and
<code>last_order</code>.</p>
<p><a name="tensor_2">[2]</a> Common parameters
for the storage array are <code>std::array&lt;N,T&gt;</code> and
<code>std::vector&lt;T&gt;</code>.</p>
<!-- ----------------------------------------------------
<h2><a name="identity_tensor"></a>Identity Tensor</h2>
<h4>Description</h4>
<p>The templated class <code>identity_tensor&lt;T, ALLOC&gt;</code>
represents identity matrices. For a <em>(m x n</em>)-dimensional
identity tensor and <em>0 &lt;= i &lt; m</em>, <em>0 &lt;= j &lt;
n</em> holds <em>id</em><sub><em>i, j</em></sub> <em>= 0</em>, if
<em>i &lt;&gt; j</em>, and <em>id</em><sub><em>i, i</em></sub><em>=
1</em>.</p>
<h4>Example</h4>
<pre>
#include &lt;boost/numeric/ublas/tensor.hpp&gt;
#include &lt;boost/numeric/ublas/io.hpp&gt;

int main () {
    using namespace boost::numeric::ublas;
    identity_tensor&lt;double&gt; m (3);
    std::cout &lt;&lt; m &lt;&lt; std::endl;
}
</pre>
<h4>Definition</h4>
<p>Defined in the header tensor.hpp.</p>
<h4>Template parameters</h4>
<table border="1" summary="parameters">
<tbody>
<tr>
<th>Parameter</th>
<th>Description</th>
<th>Default</th>
</tr>
<tr>
<td><code>T</code></td>
<td>The type of object stored in the tensor.</td>
<td><code>int</code></td>
</tr>
<tr>
<td><code>ALLOC</code></td>
<td>An STL Allocator for size_type and difference_type.</td>
<td>std::allocator</td>
</tr>
</tbody>
</table>
<h4>Model of</h4>
<p><a href="container_concept.html#tensor">Tensor</a> .</p>
<h4>Type requirements</h4>
<p>None, except for those imposed by the requirements of
<a href="container_concept.html#tensor">Tensor</a> .</p>
<h4>Public base classes</h4>
<p><code>tensor_container&lt;identity_tensor&lt;T&gt;
&gt;</code></p>
<h4>Members</h4>
<table border="1" summary="members">
<tbody>
<tr>
<th>Member</th>
<th>Description</th>
</tr>
<tr>
<td><code>identity_tensor ()</code></td>
<td>Constructs an <code>identity_tensor</code> that holds zero rows
of zero elements.</td>
</tr>
<tr>
<td><code>identity_tensor (size_type size)</code></td>
<td>Constructs an <code>identity_tensor</code> that holds
<code>size</code> rows of <code>size</code> elements.</td>
</tr>
<tr>
<td><code>identity_tensor (const identity_tensor
&amp;m)</code></td>
<td>The copy constructor.</td>
</tr>
<tr>
<td><code>void resize (size_type size, bool preserve =
true)</code></td>
<td>Resizes a <code>identity_tensor</code> to hold
<code>size</code> rows of <code>size</code> elements. Therefore the
existing elements of the <code>itendity_tensor</code> are always
preseved.</td>
</tr>
<tr>
<td><code>size_type size1 () const</code></td>
<td>Returns the number of rows.</td>
</tr>
<tr>
<td><code>size_type size2 () const</code></td>
<td>Returns the number of columns.</td>
</tr>
<tr>
<td><code>const_reference operator () (size_type i, size_type j)
const</code></td>
<td>Returns the value of the <code>j</code>-th element in the
<code>i</code>-th row.</td>
</tr>
<tr>
<td><code>identity_tensor &amp;operator = (const identity_tensor
&amp;m)</code></td>
<td>The assignment operator.</td>
</tr>
<tr>
<td><code>identity_tensor &amp;assign_temporary (identity_tensor
&amp;m)</code></td>
<td>Assigns a temporary. May change the identity tensor
<code>m</code> .</td>
</tr>
<tr>
<td><code>void swap (identity_tensor &amp;m)</code></td>
<td>Swaps the contents of the identity matrices.</td>
</tr>
<tr>
<td><code>const_iterator1 begin1 () const</code></td>
<td>Returns a <code>const_iterator1</code> pointing to the
beginning of the <code>identity_tensor</code>.</td>
</tr>
<tr>
<td><code>const_iterator1 end1 () const</code></td>
<td>Returns a <code>const_iterator1</code> pointing to the end of
the <code>identity_tensor</code>.</td>
</tr>
<tr>
<td><code>const_iterator2 begin2 () const</code></td>
<td>Returns a <code>const_iterator2</code> pointing to the
beginning of the <code>identity_tensor</code>.</td>
</tr>
<tr>
<td><code>const_iterator2 end2 () const</code></td>
<td>Returns a <code>const_iterator2</code> pointing to the end of
the <code>identity_tensor</code>.</td>
</tr>
<tr>
<td><code>const_reverse_iterator1 rbegin1 () const</code></td>
<td>Returns a <code>const_reverse_iterator1</code> pointing to the
beginning of the reversed <code>identity_tensor</code>.</td>
</tr>
<tr>
<td><code>const_reverse_iterator1 rend1 () const</code></td>
<td>Returns a <code>const_reverse_iterator1</code> pointing to the
end of the reversed <code>identity_tensor</code>.</td>
</tr>
<tr>
<td><code>const_reverse_iterator2 rbegin2 () const</code></td>
<td>Returns a <code>const_reverse_iterator2</code> pointing to the
beginning of the reversed <code>identity_tensor</code>.</td>
</tr>
<tr>
<td><code>const_reverse_iterator2 rend2 () const</code></td>
<td>Returns a <code>const_reverse_iterator2</code> pointing to the
end of the reversed <code>identity_tensor</code>.</td>
</tr>
</tbody>
</table>
----------------------------------------------------
-->
<hr/>
<p>Copyright (&copy;) 2018 Cem Bassoy<br />
   Use, modification and distribution are subject to the
   Boost Software License, Version 1.0.
   (See accompanying file LICENSE_1_0.txt
   or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
      http://www.boost.org/LICENSE_1_0.txt
   </a>).
</p>
<script type="text/javascript">
(function($) {
    $('#toc').toc();
})(jQuery);
</script>
</body>
</html>