1namespace 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 9This tutorial page explains the essentials of block operations. 10A block is a rectangular part of a matrix or array. Blocks expressions can be used both 11as rvalues and as lvalues. As usual with Eigen expressions, this abstraction has zero runtime cost 12provided 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 23The most general block operation in Eigen is called \link DenseBase::block() .block() \endlink. 24There 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 32matrix.block(i,j,p,q);\endcode </td> 33 <td>\code 34matrix.block<p,q>(i,j);\endcode </td> 35</tr> 36</table> 37 38As always in Eigen, indices start at 0. 39 40Both versions can be used on fixed-size and dynamic-size matrices and arrays. 41These two expressions are semantically equivalent. 42The only difference is that the fixed-size version will typically give you faster code if the block size is small, 43but requires this size to be known at compile time. 44 45The following program uses the dynamic-size and fixed-size versions to print the values of several blocks inside a 46matrix. 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 57In the above example the \link DenseBase::block() .block() \endlink function was employed as a \em rvalue, i.e. 58it was only read from. However, blocks can also be used as \em lvalues, meaning that you can assign to a block. 59 60This 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 71While the \link DenseBase::block() .block() \endlink method can be used for any block operation, there are 72other methods for special cases, providing more specialized API and/or better performance. On the topic of performance, all what 73matters 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, 74using the specialized \link DenseBase::col() .col() \endlink function described below lets Eigen know that, which can give it optimization opportunities. 75 76The rest of this page describes these specialized methods. 77 78\section TutorialBlockOperationsSyntaxColumnRows Columns and rows 79 80Individual 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 89matrix.row(i);\endcode </td> 90</tr> 91<tr><td>j<sup>th</sup> column 92 \link DenseBase::col() * \endlink</td> 93 <td>\code 94matrix.col(j);\endcode </td> 95</tr> 96</table> 97 98The 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 109That 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 114Eigen also provides special methods for blocks that are flushed against one of the corners or sides of a 115matrix or array. For instance, \link DenseBase::topLeftCorner() .topLeftCorner() \endlink can be used to refer 116to a block in the top-left corner of a matrix. 117 118The 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 126matrix.topLeftCorner(p,q);\endcode </td> 127 <td>\code 128matrix.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 133matrix.bottomLeftCorner(p,q);\endcode </td> 134 <td>\code 135matrix.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 140matrix.topRightCorner(p,q);\endcode </td> 141 <td>\code 142matrix.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 147matrix.bottomRightCorner(p,q);\endcode </td> 148 <td>\code 149matrix.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 154matrix.topRows(q);\endcode </td> 155 <td>\code 156matrix.topRows<q>();\endcode </td> 157</tr> 158<tr><td>%Block containing the last q rows 159 \link DenseBase::bottomRows() * \endlink</td> 160 <td>\code 161matrix.bottomRows(q);\endcode </td> 162 <td>\code 163matrix.bottomRows<q>();\endcode </td> 164</tr> 165<tr><td>%Block containing the first p columns 166 \link DenseBase::leftCols() * \endlink</td> 167 <td>\code 168matrix.leftCols(p);\endcode </td> 169 <td>\code 170matrix.leftCols<p>();\endcode </td> 171</tr> 172<tr><td>%Block containing the last q columns 173 \link DenseBase::rightCols() * \endlink</td> 174 <td>\code 175matrix.rightCols(q);\endcode </td> 176 <td>\code 177matrix.rightCols<q>();\endcode </td> 178</tr> 179</table> 180 181Here 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 195Eigen 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 204vector.head(n);\endcode </td> 205 <td>\code 206vector.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 211vector.tail(n);\endcode </td> 212 <td>\code 213vector.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 218vector.segment(i,n);\endcode </td> 219 <td>\code 220vector.segment<n>(i);\endcode </td> 221</tr> 222</table> 223 224 225An 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