mirror of
https://gitlab.com/libeigen/eigen.git
synced 2024-12-15 07:10:37 +08:00
b0bd1cfa05
Use \verbinclude for output text to disable syntax highlighting. Give tables consistent look.
248 lines
8.6 KiB
Plaintext
248 lines
8.6 KiB
Plaintext
namespace Eigen {
|
|
|
|
/** \page TutorialBlockOperations Tutorial page 4 - %Block operations
|
|
\ingroup Tutorial
|
|
|
|
\li \b Previous: \ref TutorialArrayClass
|
|
\li \b Next: \ref TutorialAdvancedInitialization
|
|
|
|
This tutorial page explains the essentials of block operations.
|
|
A block is a rectangular part of a matrix or array. Blocks expressions can be used both
|
|
as rvalues and as lvalues. As usual with Eigen expressions, this abstraction has zero runtime cost
|
|
provided that you let your compiler optimize.
|
|
|
|
\b Table \b of \b contents
|
|
- \ref TutorialBlockOperationsUsing
|
|
- \ref TutorialBlockOperationsSyntaxColumnRows
|
|
- \ref TutorialBlockOperationsSyntaxCorners
|
|
- \ref TutorialBlockOperationsSyntaxVectors
|
|
|
|
|
|
\section TutorialBlockOperationsUsing Using block operations
|
|
|
|
The most general block operation in Eigen is called \link DenseBase::block() .block() \endlink.
|
|
This function returns a block of size <tt>(p,q)</tt> whose origin is at <tt>(i,j)</tt>.
|
|
There are two versions, whose syntax is as follows:
|
|
|
|
<table class="tutorial_code" align="center">
|
|
<tr><td align="center">\b %Block \b operation</td>
|
|
<td align="center">Default version</td>
|
|
<td align="center">Optimized version when the<br>size is known at compile time</td></tr>
|
|
<tr><td>%Block of size <tt>(p,q)</tt>, starting at <tt>(i,j)</tt></td>
|
|
<td>\code
|
|
matrix.block(i,j,p,q);\endcode </td>
|
|
<td>\code
|
|
matrix.block<p,q>(i,j);\endcode </td>
|
|
</tr>
|
|
</table>
|
|
|
|
The default version is a method which takes four arguments. It can always be used. The optimized version
|
|
takes two template arguments (the size of the block) and two normal arguments (the position of the block).
|
|
It can only be used if the size of the block is known at compile time, but it may be faster than the
|
|
non-optimized version, especially if the size of the block is small. Both versions can be used on fixed-size
|
|
and dynamic-size matrices and arrays.
|
|
|
|
The following program uses the default and optimized versions to print the values of several blocks inside a
|
|
matrix.
|
|
|
|
<table class="tutorial_code"><tr><td>
|
|
\include Tutorial_BlockOperations_print_block.cpp
|
|
</td>
|
|
<td>
|
|
Output:
|
|
\verbinclude Tutorial_BlockOperations_print_block.out
|
|
</td></tr></table>
|
|
|
|
In the above example the \link DenseBase::block() .block() \endlink function was employed
|
|
to read the values inside matrix \p m . However, blocks can also be used as lvalues, meaning that you can
|
|
assign to a block.
|
|
|
|
This is illustrated in the following example, which uses arrays instead of matrices. The coefficients of the
|
|
5-by-5 array \c n are first all set to 0.6, but then the 3-by-3 block in the middle is set to the values in
|
|
\c m . The penultimate line shows that blocks can be combined with matrices and arrays to create more complex
|
|
expressions. Blocks of an array are an array expression, and thus the multiplication here is coefficient-wise
|
|
multiplication.
|
|
|
|
<table class="tutorial_code"><tr><td>
|
|
\include Tutorial_BlockOperations_block_assignment.cpp
|
|
</td>
|
|
<td>
|
|
Output:
|
|
\verbinclude Tutorial_BlockOperations_block_assignment.out
|
|
</td></tr></table>
|
|
|
|
The \link DenseBase::block() .block() \endlink method is used for general block operations, but there are
|
|
other methods for special cases. These are described in the rest of this page.
|
|
|
|
|
|
\section TutorialBlockOperationsSyntaxColumnRows Columns and rows
|
|
|
|
Individual columns and rows are special cases of blocks. Eigen provides methods to easily access them:
|
|
\link DenseBase::col() .col() \endlink and \link DenseBase::row() .row()\endlink. There is no syntax variant
|
|
for an optimized version.
|
|
|
|
<table class="tutorial_code" align="center">
|
|
<tr><td align="center">\b %Block \b operation</td>
|
|
<td align="center">Default version</td>
|
|
<td align="center">Optimized version when the<br>size is known at compile time</td></tr>
|
|
<tr><td>i<sup>th</sup> row
|
|
\link DenseBase::row() * \endlink</td>
|
|
<td>\code
|
|
matrix.row(i);\endcode </td>
|
|
<td>\code
|
|
matrix.row(i);\endcode </td>
|
|
</tr>
|
|
<tr><td>j<sup>th</sup> column
|
|
\link DenseBase::col() * \endlink</td>
|
|
<td>\code
|
|
matrix.col(j);\endcode </td>
|
|
<td>\code
|
|
matrix.col(j);\endcode </td>
|
|
</tr>
|
|
</table>
|
|
|
|
The argument for \p col() and \p row() is the index of the column or row to be accessed, starting at
|
|
0. Therefore, \p col(0) will access the first column and \p col(1) the second one.
|
|
|
|
<table class="tutorial_code"><tr><td>
|
|
C++ code:
|
|
\include Tutorial_BlockOperations_colrow.cpp
|
|
</td>
|
|
<td>
|
|
Output:
|
|
\verbinclude Tutorial_BlockOperations_colrow.out
|
|
</td></tr></table>
|
|
|
|
|
|
\section TutorialBlockOperationsSyntaxCorners Corner-related operations
|
|
|
|
Eigen also provides special methods for blocks that are flushed against one of the corners or sides of a
|
|
matrix or array. For instance, \link DenseBase::topLeftCorner() .topLeftCorner() \endlink can be used to refer
|
|
to a block in the top-left corner of a matrix. Use <tt>matrix.topLeftCorner(p,q)</tt> to access the block
|
|
consisting of the coefficients <tt>matrix(i,j)</tt> with \c i < \c p and \c j < \c q. As an other
|
|
example, blocks consisting of whole rows flushed against the top side of the matrix can be accessed by
|
|
\link DenseBase::topRows() .topRows() \endlink.
|
|
|
|
The different possibilities are summarized in the following table:
|
|
|
|
<table class="tutorial_code" align="center">
|
|
<tr><td align="center">\b %Block \b operation</td>
|
|
<td align="center">Default version</td>
|
|
<td align="center">Optimized version when the<br>size is known at compile time</td></tr>
|
|
<tr><td>Top-left p by q block \link DenseBase::topLeftCorner() * \endlink</td>
|
|
<td>\code
|
|
matrix.topLeftCorner(p,q);\endcode </td>
|
|
<td>\code
|
|
matrix.topLeftCorner<p,q>();\endcode </td>
|
|
</tr>
|
|
<tr><td>Bottom-left p by q block
|
|
\link DenseBase::bottomLeftCorner() * \endlink</td>
|
|
<td>\code
|
|
matrix.bottomLeftCorner(p,q);\endcode </td>
|
|
<td>\code
|
|
matrix.bottomLeftCorner<p,q>();\endcode </td>
|
|
</tr>
|
|
<tr><td>Top-right p by q block
|
|
\link DenseBase::topRightCorner() * \endlink</td>
|
|
<td>\code
|
|
matrix.topRightCorner(p,q);\endcode </td>
|
|
<td>\code
|
|
matrix.topRightCorner<p,q>();\endcode </td>
|
|
</tr>
|
|
<tr><td>Bottom-right p by q block
|
|
\link DenseBase::bottomRightCorner() * \endlink</td>
|
|
<td>\code
|
|
matrix.bottomRightCorner(p,q);\endcode </td>
|
|
<td>\code
|
|
matrix.bottomRightCorner<p,q>();\endcode </td>
|
|
</tr>
|
|
<tr><td>%Block containing the first q rows
|
|
\link DenseBase::topRows() * \endlink</td>
|
|
<td>\code
|
|
matrix.topRows(q);\endcode </td>
|
|
<td>\code
|
|
matrix.topRows<q>();\endcode </td>
|
|
</tr>
|
|
<tr><td>%Block containing the last q rows
|
|
\link DenseBase::bottomRows() * \endlink</td>
|
|
<td>\code
|
|
matrix.bottomRows(q);\endcode </td>
|
|
<td>\code
|
|
matrix.bottomRows<q>();\endcode </td>
|
|
</tr>
|
|
<tr><td>%Block containing the first p columns
|
|
\link DenseBase::leftCols() * \endlink</td>
|
|
<td>\code
|
|
matrix.leftCols(p);\endcode </td>
|
|
<td>\code
|
|
matrix.leftCols<p>();\endcode </td>
|
|
</tr>
|
|
<tr><td>%Block containing the last q columns
|
|
\link DenseBase::rightCols() * \endlink</td>
|
|
<td>\code
|
|
matrix.rightCols(q);\endcode </td>
|
|
<td>\code
|
|
matrix.rightCols<q>();\endcode </td>
|
|
</tr>
|
|
</table>
|
|
|
|
Here is a simple example illustrating the use of the operations presented above:
|
|
|
|
<table class="tutorial_code"><tr><td>
|
|
C++ code:
|
|
\include Tutorial_BlockOperations_corner.cpp
|
|
</td>
|
|
<td>
|
|
Output:
|
|
\verbinclude Tutorial_BlockOperations_corner.out
|
|
</td></tr></table>
|
|
|
|
|
|
\section TutorialBlockOperationsSyntaxVectors Block operations for vectors
|
|
|
|
Eigen also provides a set of block operations designed specifically for vectors and one-dimensional arrays:
|
|
|
|
<table class="tutorial_code" align="center">
|
|
<tr><td align="center">\b %Block \b operation</td>
|
|
<td align="center">Default version</td>
|
|
<td align="center">Optimized version when the<br>size is known at compile time</td></tr>
|
|
<tr><td>%Block containing the first \p n elements
|
|
\link DenseBase::head() * \endlink</td>
|
|
<td>\code
|
|
vector.head(n);\endcode </td>
|
|
<td>\code
|
|
vector.head<n>();\endcode </td>
|
|
</tr>
|
|
<tr><td>%Block containing the last \p n elements
|
|
\link DenseBase::tail() * \endlink</td>
|
|
<td>\code
|
|
vector.tail(n);\endcode </td>
|
|
<td>\code
|
|
vector.tail<n>();\endcode </td>
|
|
</tr>
|
|
<tr><td>%Block containing \p n elements, starting at position \p i
|
|
\link DenseBase::segment() * \endlink</td>
|
|
<td>\code
|
|
vector.segment(i,n);\endcode </td>
|
|
<td>\code
|
|
vector.segment<n>(i);\endcode </td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
An example is presented below:
|
|
<table class="tutorial_code"><tr><td>
|
|
C++ code:
|
|
\include Tutorial_BlockOperations_vector.cpp
|
|
</td>
|
|
<td>
|
|
Output:
|
|
\verbinclude Tutorial_BlockOperations_vector.out
|
|
</td></tr></table>
|
|
|
|
\li \b Next: \ref TutorialAdvancedInitialization
|
|
|
|
*/
|
|
|
|
}
|