2010-07-09 18:46:07 +08:00
|
|
|
namespace Eigen {
|
|
|
|
|
Big changes in Eigen documentation:
- Organize the documentation into "chapters".
- Each chapter include many documentation pages, reference pages organized as modules, and a quick reference page.
- The "Chapters" tree is created using the defgroup/ingroup mechanism, even for the documentation pages (i.e., .dox files for which I added an \eigenManualPage macro that we can switch between \page or \defgroup ).
- Add a "General topics" entry for all pages that do not fit well in the previous "chapters".
- The highlevel struture is managed by a new eigendoxy_layout.xml file.
- remove the "index" and quite useless pages (namespace list, class hierarchy, member list, file list, etc.)
- add the javascript search-engine.
- add the "treeview" panel.
- remove \tableofcontents (replace them by a custom \eigenAutoToc macro to be able to easily re-enable if needed).
- add javascript to automatically generate a TOC from the h1/h2 tags of the current page, and put the TOC in the left side panel.
- overload various javascript function generated by doxygen to:
- remove the root of the treeview
- remove links to section/subsection from the treeview
- automatically expand the "Chapters" section
- automatically expand the current section
- adjust the height of the treeview to take into account the TOC
- always use the default .css file, eigendoxy.css now only includes our modifications
- use Doxyfile to specify our logo
- remove cross references to unsupported modules (temporarily)
2013-01-05 23:37:11 +08:00
|
|
|
/** \eigenManualPage TopicAliasing Aliasing
|
2010-07-09 18:46:07 +08:00
|
|
|
|
2010-08-01 04:37:29 +08:00
|
|
|
In Eigen, aliasing refers to assignment statement in which the same matrix (or array or vector) appears on the
|
|
|
|
left and on the right of the assignment operators. Statements like <tt>mat = 2 * mat;</tt> or <tt>mat =
|
|
|
|
mat.transpose();</tt> exhibit aliasing. The aliasing in the first example is harmless, but the aliasing in the
|
|
|
|
second example leads to unexpected results. This page explains what aliasing is, when it is harmful, and what
|
|
|
|
to do about it.
|
2010-07-09 18:46:07 +08:00
|
|
|
|
Big changes in Eigen documentation:
- Organize the documentation into "chapters".
- Each chapter include many documentation pages, reference pages organized as modules, and a quick reference page.
- The "Chapters" tree is created using the defgroup/ingroup mechanism, even for the documentation pages (i.e., .dox files for which I added an \eigenManualPage macro that we can switch between \page or \defgroup ).
- Add a "General topics" entry for all pages that do not fit well in the previous "chapters".
- The highlevel struture is managed by a new eigendoxy_layout.xml file.
- remove the "index" and quite useless pages (namespace list, class hierarchy, member list, file list, etc.)
- add the javascript search-engine.
- add the "treeview" panel.
- remove \tableofcontents (replace them by a custom \eigenAutoToc macro to be able to easily re-enable if needed).
- add javascript to automatically generate a TOC from the h1/h2 tags of the current page, and put the TOC in the left side panel.
- overload various javascript function generated by doxygen to:
- remove the root of the treeview
- remove links to section/subsection from the treeview
- automatically expand the "Chapters" section
- automatically expand the current section
- adjust the height of the treeview to take into account the TOC
- always use the default .css file, eigendoxy.css now only includes our modifications
- use Doxyfile to specify our logo
- remove cross references to unsupported modules (temporarily)
2013-01-05 23:37:11 +08:00
|
|
|
\eigenAutoToc
|
2010-07-09 18:46:07 +08:00
|
|
|
|
2010-08-01 04:37:29 +08:00
|
|
|
|
|
|
|
\section TopicAliasingExamples Examples
|
|
|
|
|
2010-08-09 04:20:14 +08:00
|
|
|
Here is a simple example exhibiting aliasing:
|
2010-08-01 04:37:29 +08:00
|
|
|
|
2010-10-19 20:42:49 +08:00
|
|
|
<table class="example">
|
|
|
|
<tr><th>Example</th><th>Output</th></tr>
|
|
|
|
<tr><td>
|
|
|
|
\include TopicAliasing_block.cpp
|
2010-08-01 04:37:29 +08:00
|
|
|
</td>
|
|
|
|
<td>
|
2010-10-19 20:42:49 +08:00
|
|
|
\verbinclude TopicAliasing_block.out
|
2010-08-01 04:37:29 +08:00
|
|
|
</td></tr></table>
|
|
|
|
|
2010-08-09 04:20:14 +08:00
|
|
|
The output is not what one would expect. The problem is the assignment
|
2010-08-01 04:37:29 +08:00
|
|
|
\code
|
2010-08-09 04:20:14 +08:00
|
|
|
mat.bottomRightCorner(2,2) = mat.topLeftCorner(2,2);
|
2010-08-01 04:37:29 +08:00
|
|
|
\endcode
|
2010-08-24 00:23:30 +08:00
|
|
|
This assignment exhibits aliasing: the coefficient \c mat(1,1) appears both in the block
|
|
|
|
<tt>mat.bottomRightCorner(2,2)</tt> on the left-hand side of the assignment and the block
|
|
|
|
<tt>mat.topLeftCorner(2,2)</tt> on the right-hand side. After the assignment, the (2,2) entry in the bottom
|
|
|
|
right corner should have the value of \c mat(1,1) before the assignment, which is 5. However, the output shows
|
|
|
|
that \c mat(2,2) is actually 1. The problem is that Eigen uses lazy evaluation (see
|
|
|
|
\ref TopicEigenExpressionTemplates) for <tt>mat.topLeftCorner(2,2)</tt>. The result is similar to
|
2010-08-09 04:20:14 +08:00
|
|
|
\code
|
|
|
|
mat(1,1) = mat(0,0);
|
|
|
|
mat(1,2) = mat(0,1);
|
|
|
|
mat(2,1) = mat(1,0);
|
|
|
|
mat(2,2) = mat(1,1);
|
|
|
|
\endcode
|
2010-08-24 00:23:30 +08:00
|
|
|
Thus, \c mat(2,2) is assigned the \e new value of \c mat(1,1) instead of the old value. The next section
|
2010-08-09 04:20:14 +08:00
|
|
|
explains how to solve this problem by calling \link DenseBase::eval() eval()\endlink.
|
2010-08-01 04:37:29 +08:00
|
|
|
|
2010-08-10 18:37:23 +08:00
|
|
|
Note that if \c mat were a bigger, then the blocks would not overlap, and there would be no aliasing
|
2010-08-09 04:20:14 +08:00
|
|
|
problem. This means that in general aliasing cannot be detected at compile time. However, Eigen does detect
|
|
|
|
some instances of aliasing, albeit at run time. The following example exhibiting aliasing was mentioned in
|
|
|
|
\ref TutorialMatrixArithmetic :
|
2010-08-01 04:37:29 +08:00
|
|
|
|
2010-10-19 20:42:49 +08:00
|
|
|
<table class="example">
|
|
|
|
<tr><th>Example</th><th>Output</th></tr>
|
|
|
|
<tr><td>
|
|
|
|
\include tut_arithmetic_transpose_aliasing.cpp
|
2010-08-01 04:37:29 +08:00
|
|
|
</td>
|
|
|
|
<td>
|
2010-10-19 20:42:49 +08:00
|
|
|
\verbinclude tut_arithmetic_transpose_aliasing.out
|
2010-08-01 04:37:29 +08:00
|
|
|
</td></tr></table>
|
|
|
|
|
2010-08-09 04:20:14 +08:00
|
|
|
Again, the output shows the aliasing issue. However, by default Eigen uses a run-time assertion to detect this
|
|
|
|
and exits with a message like
|
|
|
|
|
2010-08-10 18:37:23 +08:00
|
|
|
\verbatim
|
2010-08-09 04:20:14 +08:00
|
|
|
void Eigen::DenseBase<Derived>::checkTransposeAliasing(const OtherDerived&) const
|
|
|
|
[with OtherDerived = Eigen::Transpose<Eigen::Matrix<int, 2, 2, 0, 2, 2> >, Derived = Eigen::Matrix<int, 2, 2, 0, 2, 2>]:
|
2010-10-25 22:15:22 +08:00
|
|
|
Assertion `(!internal::check_transpose_aliasing_selector<Scalar,internal::blas_traits<Derived>::IsTransposed,OtherDerived>::run(internal::extract_data(derived()), other))
|
2010-08-09 04:20:14 +08:00
|
|
|
&& "aliasing detected during tranposition, use transposeInPlace() or evaluate the rhs into a temporary using .eval()"' failed.
|
2010-08-10 18:37:23 +08:00
|
|
|
\endverbatim
|
2010-08-09 04:20:14 +08:00
|
|
|
|
|
|
|
The user can turn Eigen's run-time assertions like the one to detect this aliasing problem off by defining the
|
2010-12-27 23:07:11 +08:00
|
|
|
EIGEN_NO_DEBUG macro, and the above program was compiled with this macro turned off in order to illustrate the
|
2010-08-09 04:20:14 +08:00
|
|
|
aliasing problem. See \ref TopicAssertions for more information about Eigen's run-time assertions.
|
2010-08-01 04:37:29 +08:00
|
|
|
|
|
|
|
|
|
|
|
\section TopicAliasingSolution Resolving aliasing issues
|
|
|
|
|
2010-08-24 00:23:30 +08:00
|
|
|
If you understand the cause of the aliasing issue, then it is obvious what must happen to solve it: Eigen has
|
|
|
|
to evaluate the right-hand side fully into a temporary matrix/array and then assign it to the left-hand
|
|
|
|
side. The function \link DenseBase::eval() eval() \endlink does precisely that.
|
|
|
|
|
|
|
|
For example, here is the corrected version of the first example above:
|
|
|
|
|
2010-10-19 20:42:49 +08:00
|
|
|
<table class="example">
|
|
|
|
<tr><th>Example</th><th>Output</th></tr>
|
|
|
|
<tr><td>
|
|
|
|
\include TopicAliasing_block_correct.cpp
|
2010-08-24 00:23:30 +08:00
|
|
|
</td>
|
|
|
|
<td>
|
2010-10-19 20:42:49 +08:00
|
|
|
\verbinclude TopicAliasing_block_correct.out
|
2010-08-24 00:23:30 +08:00
|
|
|
</td></tr></table>
|
|
|
|
|
|
|
|
Now, \c mat(2,2) equals 5 after the assignment, as it should be.
|
|
|
|
|
|
|
|
The same solution also works for the second example, with the transpose: simply replace the line
|
|
|
|
<tt>a = a.transpose();</tt> with <tt>a = a.transpose().eval();</tt>. However, in this common case there is a
|
|
|
|
better solution. Eigen provides the special-purpose function
|
|
|
|
\link DenseBase::transposeInPlace() transposeInPlace() \endlink which replaces a matrix by its transpose.
|
|
|
|
This is shown below:
|
|
|
|
|
2010-10-19 20:42:49 +08:00
|
|
|
<table class="example">
|
|
|
|
<tr><th>Example</th><th>Output</th></tr>
|
|
|
|
<tr><td>
|
|
|
|
\include tut_arithmetic_transpose_inplace.cpp
|
2010-08-24 00:23:30 +08:00
|
|
|
</td>
|
|
|
|
<td>
|
2010-10-19 20:42:49 +08:00
|
|
|
\verbinclude tut_arithmetic_transpose_inplace.out
|
2010-08-24 00:23:30 +08:00
|
|
|
</td></tr></table>
|
|
|
|
|
2010-10-19 20:42:49 +08:00
|
|
|
If an xxxInPlace() function is available, then it is best to use it, because it indicates more clearly what you
|
2010-08-24 00:23:30 +08:00
|
|
|
are doing. This may also allow Eigen to optimize more aggressively. These are some of the xxxInPlace()
|
|
|
|
functions provided:
|
|
|
|
|
2010-10-19 21:25:00 +08:00
|
|
|
<table class="manual">
|
2010-10-19 20:42:49 +08:00
|
|
|
<tr><th>Original function</th><th>In-place function</th></tr>
|
2010-08-24 00:23:30 +08:00
|
|
|
<tr> <td> MatrixBase::adjoint() </td> <td> MatrixBase::adjointInPlace() </td> </tr>
|
2010-10-19 21:25:00 +08:00
|
|
|
<tr class="alt"> <td> DenseBase::reverse() </td> <td> DenseBase::reverseInPlace() </td> </tr>
|
2010-08-24 00:23:30 +08:00
|
|
|
<tr> <td> LDLT::solve() </td> <td> LDLT::solveInPlace() </td> </tr>
|
2010-10-19 21:25:00 +08:00
|
|
|
<tr class="alt"> <td> LLT::solve() </td> <td> LLT::solveInPlace() </td> </tr>
|
2010-08-24 00:23:30 +08:00
|
|
|
<tr> <td> TriangularView::solve() </td> <td> TriangularView::solveInPlace() </td> </tr>
|
2010-10-19 21:25:00 +08:00
|
|
|
<tr class="alt"> <td> DenseBase::transpose() </td> <td> DenseBase::transposeInPlace() </td> </tr>
|
2010-08-24 00:23:30 +08:00
|
|
|
</table>
|
2010-08-01 04:37:29 +08:00
|
|
|
|
|
|
|
|
|
|
|
\section TopicAliasingCwise Aliasing and component-wise operations
|
|
|
|
|
2010-11-17 01:28:59 +08:00
|
|
|
As explained above, it may be dangerous if the same matrix or array occurs on both the left-hand side and the
|
|
|
|
right-hand side of an assignment operator, and it is then often necessary to evaluate the right-hand side
|
|
|
|
explicitly. However, applying component-wise operations (such as matrix addition, scalar multiplication and
|
|
|
|
array multiplication) is safe.
|
|
|
|
|
|
|
|
The following example has only component-wise operations. Thus, there is no need for .eval() even though
|
|
|
|
the same matrix appears on both sides of the assignments.
|
|
|
|
|
|
|
|
<table class="example">
|
|
|
|
<tr><th>Example</th><th>Output</th></tr>
|
|
|
|
<tr><td>
|
|
|
|
\include TopicAliasing_cwise.cpp
|
|
|
|
</td>
|
|
|
|
<td>
|
|
|
|
\verbinclude TopicAliasing_cwise.out
|
|
|
|
</td></tr></table>
|
|
|
|
|
|
|
|
In general, an assignment is safe if the (i,j) entry of the expression on the right-hand side depends only on
|
|
|
|
the (i,j) entry of the matrix or array on the left-hand side and not on any other entries. In that case it is
|
|
|
|
not necessary to evaluate the right-hand side explicitly.
|
2010-08-01 04:37:29 +08:00
|
|
|
|
|
|
|
|
|
|
|
\section TopicAliasingMatrixMult Aliasing and matrix multiplication
|
|
|
|
|
2010-12-27 23:06:55 +08:00
|
|
|
Matrix multiplication is the only operation in Eigen that assumes aliasing by default. Thus, if \c matA is a
|
|
|
|
matrix, then the statement <tt>matA = matA * matA;</tt> is safe. All other operations in Eigen assume that
|
|
|
|
there are no aliasing problems, either because the result is assigned to a different matrix or because it is a
|
|
|
|
component-wise operation.
|
|
|
|
|
|
|
|
<table class="example">
|
|
|
|
<tr><th>Example</th><th>Output</th></tr>
|
|
|
|
<tr><td>
|
|
|
|
\include TopicAliasing_mult1.cpp
|
|
|
|
</td>
|
|
|
|
<td>
|
|
|
|
\verbinclude TopicAliasing_mult1.out
|
|
|
|
</td></tr></table>
|
|
|
|
|
|
|
|
However, this comes at a price. When executing the expression <tt>matA = matA * matA</tt>, Eigen evaluates the
|
|
|
|
product in a temporary matrix which is assigned to \c matA after the computation. This is fine. But Eigen does
|
|
|
|
the same when the product is assigned to a different matrix (e.g., <tt>matB = matA * matA</tt>). In that case,
|
|
|
|
it is more efficient to evaluate the product directly into \c matB instead of evaluating it first into a
|
|
|
|
temporary matrix and copying that matrix to \c matB.
|
|
|
|
|
|
|
|
The user can indicate with the \link MatrixBase::noalias() noalias()\endlink function that there is no
|
|
|
|
aliasing, as follows: <tt>matB.noalias() = matA * matA</tt>. This allows Eigen to evaluate the matrix product
|
|
|
|
<tt>matA * matA</tt> directly into \c matB.
|
|
|
|
|
|
|
|
<table class="example">
|
|
|
|
<tr><th>Example</th><th>Output</th></tr>
|
|
|
|
<tr><td>
|
|
|
|
\include TopicAliasing_mult2.cpp
|
|
|
|
</td>
|
|
|
|
<td>
|
|
|
|
\verbinclude TopicAliasing_mult2.out
|
|
|
|
</td></tr></table>
|
|
|
|
|
|
|
|
Of course, you should not use \c noalias() when there is in fact aliasing taking place. If you do, then you
|
|
|
|
may get wrong results:
|
|
|
|
|
|
|
|
<table class="example">
|
|
|
|
<tr><th>Example</th><th>Output</th></tr>
|
|
|
|
<tr><td>
|
|
|
|
\include TopicAliasing_mult3.cpp
|
|
|
|
</td>
|
|
|
|
<td>
|
|
|
|
\verbinclude TopicAliasing_mult3.out
|
|
|
|
</td></tr></table>
|
2010-08-01 04:37:29 +08:00
|
|
|
|
|
|
|
|
|
|
|
\section TopicAliasingSummary Summary
|
|
|
|
|
|
|
|
Aliasing occurs when the same matrix or array coefficients appear both on the left- and the right-hand side of
|
|
|
|
an assignment operator.
|
|
|
|
- Aliasing is harmless with coefficient-wise computations; this includes scalar multiplication and matrix or
|
|
|
|
array addition.
|
|
|
|
- When you multiply two matrices, Eigen assumes that aliasing occurs. If you know that there is no aliasing,
|
|
|
|
then you can use \link MatrixBase::noalias() noalias()\endlink.
|
|
|
|
- In all other situations, Eigen assumes that there is no aliasing issue and thus gives the wrong result if
|
|
|
|
aliasing does in fact occur. To prevent this, you have to use \link DenseBase::eval() eval() \endlink or
|
|
|
|
one of the xxxInPlace() functions.
|
2010-07-09 18:46:07 +08:00
|
|
|
|
|
|
|
*/
|
|
|
|
}
|