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