[136] | 1 | namespace Eigen {
|
---|
| 2 |
|
---|
| 3 | /** \eigenManualPage TutorialBlockOperations Block operations
|
---|
| 4 |
|
---|
| 5 | This page explains the essentials of block operations.
|
---|
| 6 | A block is a rectangular part of a matrix or array. Blocks expressions can be used both
|
---|
| 7 | as rvalues and as lvalues. As usual with Eigen expressions, this abstraction has zero runtime cost
|
---|
| 8 | provided that you let your compiler optimize.
|
---|
| 9 |
|
---|
| 10 | \eigenAutoToc
|
---|
| 11 |
|
---|
| 12 | \section TutorialBlockOperationsUsing Using block operations
|
---|
| 13 |
|
---|
| 14 | The most general block operation in Eigen is called \link DenseBase::block() .block() \endlink.
|
---|
| 15 | There are two versions, whose syntax is as follows:
|
---|
| 16 |
|
---|
| 17 | <table class="manual">
|
---|
| 18 | <tr><th>\b %Block \b operation</td>
|
---|
| 19 | <th>Version constructing a \n dynamic-size block expression</th>
|
---|
| 20 | <th>Version constructing a \n fixed-size block expression</th></tr>
|
---|
| 21 | <tr><td>%Block of size <tt>(p,q)</tt>, starting at <tt>(i,j)</tt></td>
|
---|
| 22 | <td>\code
|
---|
| 23 | matrix.block(i,j,p,q);\endcode </td>
|
---|
| 24 | <td>\code
|
---|
| 25 | matrix.block<p,q>(i,j);\endcode </td>
|
---|
| 26 | </tr>
|
---|
| 27 | </table>
|
---|
| 28 |
|
---|
| 29 | As always in Eigen, indices start at 0.
|
---|
| 30 |
|
---|
| 31 | Both versions can be used on fixed-size and dynamic-size matrices and arrays.
|
---|
| 32 | These two expressions are semantically equivalent.
|
---|
| 33 | The only difference is that the fixed-size version will typically give you faster code if the block size is small,
|
---|
| 34 | but requires this size to be known at compile time.
|
---|
| 35 |
|
---|
| 36 | The following program uses the dynamic-size and fixed-size versions to print the values of several blocks inside a
|
---|
| 37 | matrix.
|
---|
| 38 |
|
---|
| 39 | <table class="example">
|
---|
| 40 | <tr><th>Example:</th><th>Output:</th></tr>
|
---|
| 41 | <tr><td>
|
---|
| 42 | \include Tutorial_BlockOperations_print_block.cpp
|
---|
| 43 | </td>
|
---|
| 44 | <td>
|
---|
| 45 | \verbinclude Tutorial_BlockOperations_print_block.out
|
---|
| 46 | </td></tr></table>
|
---|
| 47 |
|
---|
| 48 | In the above example the \link DenseBase::block() .block() \endlink function was employed as a \em rvalue, i.e.
|
---|
| 49 | it was only read from. However, blocks can also be used as \em lvalues, meaning that you can assign to a block.
|
---|
| 50 |
|
---|
| 51 | This is illustrated in the following example. This example also demonstrates blocks in arrays, which works exactly like the above-demonstrated blocks in matrices.
|
---|
| 52 |
|
---|
| 53 | <table class="example">
|
---|
| 54 | <tr><th>Example:</th><th>Output:</th></tr>
|
---|
| 55 | <tr><td>
|
---|
| 56 | \include Tutorial_BlockOperations_block_assignment.cpp
|
---|
| 57 | </td>
|
---|
| 58 | <td>
|
---|
| 59 | \verbinclude Tutorial_BlockOperations_block_assignment.out
|
---|
| 60 | </td></tr></table>
|
---|
| 61 |
|
---|
| 62 | While the \link DenseBase::block() .block() \endlink method can be used for any block operation, there are
|
---|
| 63 | other methods for special cases, providing more specialized API and/or better performance. On the topic of performance, all what
|
---|
| 64 | matters is that you give Eigen as much information as possible at compile time. For example, if your block is a single whole column in a matrix,
|
---|
| 65 | using the specialized \link DenseBase::col() .col() \endlink function described below lets Eigen know that, which can give it optimization opportunities.
|
---|
| 66 |
|
---|
| 67 | The rest of this page describes these specialized methods.
|
---|
| 68 |
|
---|
| 69 | \section TutorialBlockOperationsSyntaxColumnRows Columns and rows
|
---|
| 70 |
|
---|
| 71 | Individual columns and rows are special cases of blocks. Eigen provides methods to easily address them:
|
---|
| 72 | \link DenseBase::col() .col() \endlink and \link DenseBase::row() .row()\endlink.
|
---|
| 73 |
|
---|
| 74 | <table class="manual">
|
---|
| 75 | <tr><th>%Block operation</th>
|
---|
| 76 | <th>Method</th>
|
---|
| 77 | <tr><td>i<sup>th</sup> row
|
---|
| 78 | \link DenseBase::row() * \endlink</td>
|
---|
| 79 | <td>\code
|
---|
| 80 | matrix.row(i);\endcode </td>
|
---|
| 81 | </tr>
|
---|
| 82 | <tr><td>j<sup>th</sup> column
|
---|
| 83 | \link DenseBase::col() * \endlink</td>
|
---|
| 84 | <td>\code
|
---|
| 85 | matrix.col(j);\endcode </td>
|
---|
| 86 | </tr>
|
---|
| 87 | </table>
|
---|
| 88 |
|
---|
| 89 | The argument for \p col() and \p row() is the index of the column or row to be accessed. As always in Eigen, indices start at 0.
|
---|
| 90 |
|
---|
| 91 | <table class="example">
|
---|
| 92 | <tr><th>Example:</th><th>Output:</th></tr>
|
---|
| 93 | <tr><td>
|
---|
| 94 | \include Tutorial_BlockOperations_colrow.cpp
|
---|
| 95 | </td>
|
---|
| 96 | <td>
|
---|
| 97 | \verbinclude Tutorial_BlockOperations_colrow.out
|
---|
| 98 | </td></tr></table>
|
---|
| 99 |
|
---|
| 100 | That example also demonstrates that block expressions (here columns) can be used in arithmetic like any other expression.
|
---|
| 101 |
|
---|
| 102 |
|
---|
| 103 | \section TutorialBlockOperationsSyntaxCorners Corner-related operations
|
---|
| 104 |
|
---|
| 105 | Eigen also provides special methods for blocks that are flushed against one of the corners or sides of a
|
---|
| 106 | matrix or array. For instance, \link DenseBase::topLeftCorner() .topLeftCorner() \endlink can be used to refer
|
---|
| 107 | to a block in the top-left corner of a matrix.
|
---|
| 108 |
|
---|
| 109 | The different possibilities are summarized in the following table:
|
---|
| 110 |
|
---|
| 111 | <table class="manual">
|
---|
| 112 | <tr><th>%Block \b operation</td>
|
---|
| 113 | <th>Version constructing a \n dynamic-size block expression</th>
|
---|
| 114 | <th>Version constructing a \n fixed-size block expression</th></tr>
|
---|
| 115 | <tr><td>Top-left p by q block \link DenseBase::topLeftCorner() * \endlink</td>
|
---|
| 116 | <td>\code
|
---|
| 117 | matrix.topLeftCorner(p,q);\endcode </td>
|
---|
| 118 | <td>\code
|
---|
| 119 | matrix.topLeftCorner<p,q>();\endcode </td>
|
---|
| 120 | </tr>
|
---|
| 121 | <tr><td>Bottom-left p by q block
|
---|
| 122 | \link DenseBase::bottomLeftCorner() * \endlink</td>
|
---|
| 123 | <td>\code
|
---|
| 124 | matrix.bottomLeftCorner(p,q);\endcode </td>
|
---|
| 125 | <td>\code
|
---|
| 126 | matrix.bottomLeftCorner<p,q>();\endcode </td>
|
---|
| 127 | </tr>
|
---|
| 128 | <tr><td>Top-right p by q block
|
---|
| 129 | \link DenseBase::topRightCorner() * \endlink</td>
|
---|
| 130 | <td>\code
|
---|
| 131 | matrix.topRightCorner(p,q);\endcode </td>
|
---|
| 132 | <td>\code
|
---|
| 133 | matrix.topRightCorner<p,q>();\endcode </td>
|
---|
| 134 | </tr>
|
---|
| 135 | <tr><td>Bottom-right p by q block
|
---|
| 136 | \link DenseBase::bottomRightCorner() * \endlink</td>
|
---|
| 137 | <td>\code
|
---|
| 138 | matrix.bottomRightCorner(p,q);\endcode </td>
|
---|
| 139 | <td>\code
|
---|
| 140 | matrix.bottomRightCorner<p,q>();\endcode </td>
|
---|
| 141 | </tr>
|
---|
| 142 | <tr><td>%Block containing the first q rows
|
---|
| 143 | \link DenseBase::topRows() * \endlink</td>
|
---|
| 144 | <td>\code
|
---|
| 145 | matrix.topRows(q);\endcode </td>
|
---|
| 146 | <td>\code
|
---|
| 147 | matrix.topRows<q>();\endcode </td>
|
---|
| 148 | </tr>
|
---|
| 149 | <tr><td>%Block containing the last q rows
|
---|
| 150 | \link DenseBase::bottomRows() * \endlink</td>
|
---|
| 151 | <td>\code
|
---|
| 152 | matrix.bottomRows(q);\endcode </td>
|
---|
| 153 | <td>\code
|
---|
| 154 | matrix.bottomRows<q>();\endcode </td>
|
---|
| 155 | </tr>
|
---|
| 156 | <tr><td>%Block containing the first p columns
|
---|
| 157 | \link DenseBase::leftCols() * \endlink</td>
|
---|
| 158 | <td>\code
|
---|
| 159 | matrix.leftCols(p);\endcode </td>
|
---|
| 160 | <td>\code
|
---|
| 161 | matrix.leftCols<p>();\endcode </td>
|
---|
| 162 | </tr>
|
---|
| 163 | <tr><td>%Block containing the last q columns
|
---|
| 164 | \link DenseBase::rightCols() * \endlink</td>
|
---|
| 165 | <td>\code
|
---|
| 166 | matrix.rightCols(q);\endcode </td>
|
---|
| 167 | <td>\code
|
---|
| 168 | matrix.rightCols<q>();\endcode </td>
|
---|
| 169 | </tr>
|
---|
| 170 | </table>
|
---|
| 171 |
|
---|
| 172 | Here is a simple example illustrating the use of the operations presented above:
|
---|
| 173 |
|
---|
| 174 | <table class="example">
|
---|
| 175 | <tr><th>Example:</th><th>Output:</th></tr>
|
---|
| 176 | <tr><td>
|
---|
| 177 | \include Tutorial_BlockOperations_corner.cpp
|
---|
| 178 | </td>
|
---|
| 179 | <td>
|
---|
| 180 | \verbinclude Tutorial_BlockOperations_corner.out
|
---|
| 181 | </td></tr></table>
|
---|
| 182 |
|
---|
| 183 |
|
---|
| 184 | \section TutorialBlockOperationsSyntaxVectors Block operations for vectors
|
---|
| 185 |
|
---|
| 186 | Eigen also provides a set of block operations designed specifically for the special case of vectors and one-dimensional arrays:
|
---|
| 187 |
|
---|
| 188 | <table class="manual">
|
---|
| 189 | <tr><th> %Block operation</th>
|
---|
| 190 | <th>Version constructing a \n dynamic-size block expression</th>
|
---|
| 191 | <th>Version constructing a \n fixed-size block expression</th></tr>
|
---|
| 192 | <tr><td>%Block containing the first \p n elements
|
---|
| 193 | \link DenseBase::head() * \endlink</td>
|
---|
| 194 | <td>\code
|
---|
| 195 | vector.head(n);\endcode </td>
|
---|
| 196 | <td>\code
|
---|
| 197 | vector.head<n>();\endcode </td>
|
---|
| 198 | </tr>
|
---|
| 199 | <tr><td>%Block containing the last \p n elements
|
---|
| 200 | \link DenseBase::tail() * \endlink</td>
|
---|
| 201 | <td>\code
|
---|
| 202 | vector.tail(n);\endcode </td>
|
---|
| 203 | <td>\code
|
---|
| 204 | vector.tail<n>();\endcode </td>
|
---|
| 205 | </tr>
|
---|
| 206 | <tr><td>%Block containing \p n elements, starting at position \p i
|
---|
| 207 | \link DenseBase::segment() * \endlink</td>
|
---|
| 208 | <td>\code
|
---|
| 209 | vector.segment(i,n);\endcode </td>
|
---|
| 210 | <td>\code
|
---|
| 211 | vector.segment<n>(i);\endcode </td>
|
---|
| 212 | </tr>
|
---|
| 213 | </table>
|
---|
| 214 |
|
---|
| 215 |
|
---|
| 216 | An example is presented below:
|
---|
| 217 | <table class="example">
|
---|
| 218 | <tr><th>Example:</th><th>Output:</th></tr>
|
---|
| 219 | <tr><td>
|
---|
| 220 | \include Tutorial_BlockOperations_vector.cpp
|
---|
| 221 | </td>
|
---|
| 222 | <td>
|
---|
| 223 | \verbinclude Tutorial_BlockOperations_vector.out
|
---|
| 224 | </td></tr></table>
|
---|
| 225 |
|
---|
| 226 | */
|
---|
| 227 |
|
---|
| 228 | }
|
---|