diff options
| -rw-r--r-- | doc/C02_TutorialMatrixArithmetic.dox | 18 | ||||
| -rw-r--r-- | doc/C04_TutorialBlockOperations.dox | 195 | ||||
| -rw-r--r-- | doc/C07_TutorialReductionsVisitorsBroadcasting.dox | 2 | ||||
| -rw-r--r-- | doc/examples/Tutorial_BlockOperations_block_assignment.cpp | 23 | ||||
| -rw-r--r-- | doc/examples/Tutorial_BlockOperations_colrow.cpp | 11 | ||||
| -rw-r--r-- | doc/examples/Tutorial_BlockOperations_corner.cpp | 20 | ||||
| -rw-r--r-- | doc/examples/Tutorial_BlockOperations_print_block.cpp | 20 | ||||
| -rw-r--r-- | doc/examples/Tutorial_BlockOperations_vector.cpp | 20 |
8 files changed, 127 insertions, 182 deletions
diff --git a/doc/C02_TutorialMatrixArithmetic.dox b/doc/C02_TutorialMatrixArithmetic.dox index df2360d40..d076c8048 100644 --- a/doc/C02_TutorialMatrixArithmetic.dox +++ b/doc/C02_TutorialMatrixArithmetic.dox @@ -43,7 +43,7 @@ also have the same \c Scalar type, as Eigen doesn't do automatic type promotion. Example: \include tut_arithmetic_add_sub.cpp </td> <td> -Output: \include tut_arithmetic_add_sub.out +Output: \verbinclude tut_arithmetic_add_sub.out </td></tr></table> \section TutorialArithmeticScalarMulDiv Scalar multiplication and division @@ -59,7 +59,7 @@ Multiplication and division by a scalar is very simple too. The operators at han Example: \include tut_arithmetic_scalar_mul_div.cpp </td> <td> -Output: \include tut_arithmetic_scalar_mul_div.out +Output: \verbinclude tut_arithmetic_scalar_mul_div.out </td></tr></table> @@ -93,7 +93,7 @@ The transpose \f$ a^T \f$, conjugate \f$ \bar{a} \f$, and adjoint (i.e., conjuga Example: \include tut_arithmetic_transpose_conjugate.cpp </td> <td> -Output: \include tut_arithmetic_transpose_conjugate.out +Output: \verbinclude tut_arithmetic_transpose_conjugate.out </td></tr></table> For real matrices, \c conjugate() is a no-operation, and so \c adjoint() is 100% equivalent to \c transpose(). @@ -103,7 +103,7 @@ As for basic arithmetic operators, \c transpose() and \c adjoint() simply return Example: \include tut_arithmetic_transpose_aliasing.cpp </td> <td> -Output: \include tut_arithmetic_transpose_aliasing.out +Output: \verbinclude tut_arithmetic_transpose_aliasing.out </td></tr></table> This is the so-called \ref TopicAliasing "aliasing issue". In "debug mode", i.e., when \ref TopicAssertions "assertions" have not been disabled, such common pitfalls are automatically detected. @@ -112,7 +112,7 @@ For \em in-place transposition, as for instance in <tt>a = a.transpose()</tt>, s Example: \include tut_arithmetic_transpose_inplace.cpp </td> <td> -Output: \include tut_arithmetic_transpose_inplace.out +Output: \verbinclude tut_arithmetic_transpose_inplace.out </td></tr></table> There is also the \link MatrixBase::adjointInPlace() adjointInPlace()\endlink function for complex matrices. @@ -129,7 +129,7 @@ two operators: Example: \include tut_arithmetic_matrix_mul.cpp </td> <td> -Output: \include tut_arithmetic_matrix_mul.out +Output: \verbinclude tut_arithmetic_matrix_mul.out </td></tr></table> Note: if you read the above paragraph on expression templates and are worried that doing \c m=m*m might cause @@ -154,7 +154,7 @@ The above-discussed \c operator* cannot be used to compute dot and cross product Example: \include tut_arithmetic_dot_cross.cpp </td> <td> -Output: \include tut_arithmetic_dot_cross.out +Output: \verbinclude tut_arithmetic_dot_cross.out </td></tr></table> Remember that cross product is only for vectors of size 3. Dot product is for vectors of any sizes. @@ -168,7 +168,7 @@ Eigen also provides some reduction operations to reduce a given matrix or vector Example: \include tut_arithmetic_redux_basic.cpp </td> <td> -Output: \include tut_arithmetic_redux_basic.out +Output: \verbinclude tut_arithmetic_redux_basic.out </td></tr></table> The \em trace of a matrix, as returned by the function \link MatrixBase::trace() trace()\endlink, is the sum of the diagonal coefficients and can also be computed as efficiently using <tt>a.diagonal().sum()</tt>, as we will see later on. @@ -179,7 +179,7 @@ There also exist variants of the \c minCoeff and \c maxCoeff functions returning Example: \include tut_arithmetic_redux_minmax.cpp </td> <td> -Output: \include tut_arithmetic_redux_minmax.out +Output: \verbinclude tut_arithmetic_redux_minmax.out </td></tr></table> diff --git a/doc/C04_TutorialBlockOperations.dox b/doc/C04_TutorialBlockOperations.dox index 70773a463..b45cbfbc8 100644 --- a/doc/C04_TutorialBlockOperations.dox +++ b/doc/C04_TutorialBlockOperations.dox @@ -13,21 +13,22 @@ provided that you let your compiler optimize. \b Table \b of \b contents - \ref TutorialBlockOperationsUsing - - \ref TutorialBlockOperationsSyntax - - \ref TutorialBlockOperationsSyntaxColumnRows - - \ref TutorialBlockOperationsSyntaxCorners + - \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> by using -the following syntax: +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 \b version</td> +<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> +<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 @@ -35,7 +36,15 @@ matrix.block<p,q>(i,j);\endcode </td> </tr> </table> -Therefore, if we want to print the values of a block inside a matrix we can simply write: +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> @@ -44,10 +53,15 @@ 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. -In the previous example the \link DenseBase::block() .block() \endlink function was employed -to read the values inside matrix \p m . Blocks can also be used to perform operations and -assignments within matrices or arrays of different size: +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 @@ -57,55 +71,38 @@ 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. -Blocks can also be combined with matrices and arrays to create more complex expressions: -\code - MatrixXf m(3,3), n(2,2); - MatrixXf p(3,3); - - m.block(0,0,2,2) = m.block(0,0,2,2) * n + p.block(1,1,2,2); -\endcode +\section TutorialBlockOperationsSyntaxColumnRows Columns and rows -It is important to point out that \link DenseBase::block() .block() \endlink is the -general case for a block operation but there are many other useful block operations, -as described in the next section. - -\section TutorialBlockOperationsSyntax Block operation syntax -The following tables show a summary of Eigen's block operations and how they are applied to -fixed- and dynamic-sized Eigen objects. - -\subsection TutorialBlockOperationsSyntaxColumnRows Columns and rows -Other extremely useful block operations are \link DenseBase::col() .col() \endlink and -\link DenseBase::row() .row() \endlink which provide access to a -specific row or column. This is a special case in the sense that the syntax for fixed- and -dynamic-sized objects is exactly the same: +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> +<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 -MatrixXf m; -std::cout << m.row(i);\endcode </td> +matrix.row(i);\endcode </td> <td>\code -Matrix3f m; -std::cout << m.row(i);\endcode </td> +matrix.row(i);\endcode </td> </tr> <tr><td>j<sup>th</sup> column \link DenseBase::col() * \endlink</td> <td>\code -MatrixXf m; -std::cout << m.col(j);\endcode </td> +matrix.col(j);\endcode </td> <td>\code -Matrix3f m; -std::cout << m.col(j);\endcode </td> +matrix.col(j);\endcode </td> </tr> </table> -A simple example demonstrating these feature follows: +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: @@ -113,94 +110,83 @@ C++ code: </td> <td> Output: -\include Tutorial_BlockOperations_colrow.out +\verbinclude Tutorial_BlockOperations_colrow.out </td></tr></table> -\b NOTE: 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. +\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: -\subsection TutorialBlockOperationsSyntaxCorners Corner-related operations <table class="tutorial_code" align="center"> -<tr><td align="center">\b Block \b operation</td> +<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 -MatrixXf m; -std::cout << m.topLeftCorner(p,q);\endcode </td> +matrix.topLeftCorner(p,q);\endcode </td> <td>\code -Matrix3f m; -std::cout << m.topLeftCorner<p,q>();\endcode </td> +matrix.topLeftCorner<p,q>();\endcode </td> </tr> <tr><td>Bottom-left p by q block \link DenseBase::bottomLeftCorner() * \endlink</td> <td>\code -MatrixXf m; -std::cout << m.bottomLeftCorner(p,q);\endcode </td> +matrix.bottomLeftCorner(p,q);\endcode </td> <td>\code -Matrix3f m; -std::cout << m.bottomLeftCorner<p,q>();\endcode </td> +matrix.bottomLeftCorner<p,q>();\endcode </td> </tr> <tr><td>Top-right p by q block \link DenseBase::topRightCorner() * \endlink</td> <td>\code -MatrixXf m; -std::cout << m.topRightCorner(p,q);\endcode </td> +matrix.topRightCorner(p,q);\endcode </td> <td>\code -Matrix3f m; -std::cout << m.topRightCorner<p,q>();\endcode </td> +matrix.topRightCorner<p,q>();\endcode </td> </tr> <tr><td>Bottom-right p by q block \link DenseBase::bottomRightCorner() * \endlink</td> <td>\code -MatrixXf m; -std::cout << m.bottomRightCorner(p,q);\endcode </td> +matrix.bottomRightCorner(p,q);\endcode </td> <td>\code -Matrix3f m; -std::cout << m.bottomRightCorner<p,q>();\endcode </td> +matrix.bottomRightCorner<p,q>();\endcode </td> </tr> -<tr><td>Block containing the first q rows +<tr><td>%Block containing the first q rows \link DenseBase::topRows() * \endlink</td> <td>\code -MatrixXf m; -std::cout << m.topRows(q);\endcode </td> +matrix.topRows(q);\endcode </td> <td>\code -Matrix3f m; -std::cout << m.topRows<q>();\endcode </td> +matrix.topRows<q>();\endcode </td> </tr> -<tr><td>Block containing the last q rows +<tr><td>%Block containing the last q rows \link DenseBase::bottomRows() * \endlink</td> <td>\code -MatrixXf m; -std::cout << m.bottomRows(q);\endcode </td> +matrix.bottomRows(q);\endcode </td> <td>\code -Matrix3f m; -std::cout << m.bottomRows<q>();\endcode </td> +matrix.bottomRows<q>();\endcode </td> </tr> -<tr><td>Block containing the first p columns +<tr><td>%Block containing the first p columns \link DenseBase::leftCols() * \endlink</td> <td>\code -MatrixXf m; -std::cout << m.leftCols(p);\endcode </td> +matrix.leftCols(p);\endcode </td> <td>\code -Matrix3f m; -std::cout << m.leftCols<p>();\endcode </td> +matrix.leftCols<p>();\endcode </td> </tr> -<tr><td>Block containing the last q columns +<tr><td>%Block containing the last q columns \link DenseBase::rightCols() * \endlink</td> <td>\code -MatrixXf m; -std::cout << m.rightCols(q);\endcode </td> +matrix.rightCols(q);\endcode </td> <td>\code -Matrix3f m; -std::cout << m.rightCols<q>();\endcode </td> +matrix.rightCols<q>();\endcode </td> </tr> </table> - -Here is a simple example showing the power of the operations presented above: +Here is a simple example illustrating the use of the operations presented above: <table class="tutorial_code"><tr><td> C++ code: @@ -208,49 +194,38 @@ C++ code: </td> <td> Output: -\include Tutorial_BlockOperations_corner.out +\verbinclude Tutorial_BlockOperations_corner.out </td></tr></table> +\section TutorialBlockOperationsSyntaxVectors Block operations for vectors - - - - - -\subsection TutorialBlockOperationsSyntaxVectors Block operations for vectors -Eigen also provides a set of block operations designed specifically 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> +<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 +<tr><td>%Block containing the first \p n elements \link DenseBase::head() * \endlink</td> <td>\code -VectorXf v; -std::cout << v.head(n);\endcode </td> +vector.head(n);\endcode </td> <td>\code -Vector3f v; -std::cout << v.head<n>();\endcode </td> +vector.head<n>();\endcode </td> </tr> -<tr><td>Block containing the last \p n elements +<tr><td>%Block containing the last \p n elements \link DenseBase::tail() * \endlink</td> <td>\code -VectorXf v; -std::cout << v.tail(n);\endcode </td> +vector.tail(n);\endcode </td> <td>\code -Vector3f m; -std::cout << v.tail<n>();\endcode </td> +vector.tail<n>();\endcode </td> </tr> -<tr><td>Block containing \p n elements, starting at position \p i +<tr><td>%Block containing \p n elements, starting at position \p i \link DenseBase::segment() * \endlink</td> <td>\code -VectorXf v; -std::cout << v.segment(i,n);\endcode </td> +vector.segment(i,n);\endcode </td> <td>\code -Vector3f m; -std::cout << v.segment<n>(i);\endcode </td> +vector.segment<n>(i);\endcode </td> </tr> </table> @@ -262,7 +237,7 @@ C++ code: </td> <td> Output: -\include Tutorial_BlockOperations_vector.out +\verbinclude Tutorial_BlockOperations_vector.out </td></tr></table> \li \b Next: \ref TutorialAdvancedInitialization diff --git a/doc/C07_TutorialReductionsVisitorsBroadcasting.dox b/doc/C07_TutorialReductionsVisitorsBroadcasting.dox index 1930d7a94..93d18f47b 100644 --- a/doc/C07_TutorialReductionsVisitorsBroadcasting.dox +++ b/doc/C07_TutorialReductionsVisitorsBroadcasting.dox @@ -30,7 +30,7 @@ which returns the addition of all the coefficients inside a given matrix or arra Example: \include tut_arithmetic_redux_basic.cpp </td> <td> -Output: \include tut_arithmetic_redux_basic.out +Output: \verbinclude tut_arithmetic_redux_basic.out </td></tr></table> The \em trace of a matrix, as returned by the function \c trace(), is the sum of the diagonal coefficients and can also be computed as efficiently using <tt>a.diagonal().sum()</tt>, as we will see later on. diff --git a/doc/examples/Tutorial_BlockOperations_block_assignment.cpp b/doc/examples/Tutorial_BlockOperations_block_assignment.cpp index 0419a500f..56ca69a6e 100644 --- a/doc/examples/Tutorial_BlockOperations_block_assignment.cpp +++ b/doc/examples/Tutorial_BlockOperations_block_assignment.cpp @@ -6,26 +6,13 @@ using namespace Eigen; int main() { - MatrixXf m(3,3), n(2,2); - + Array33f m; m << 1,2,3, 4,5,6, 7,8,9; - - // assignment through a block operation, - // block as rvalue - n = m.block(0,0,2,2); - - //print n + Array<float,5,5> n = Array<float,5,5>::Constant(0.6); + n.block(1,1,3,3) = m; cout << "n = " << endl << n << endl << endl; - - - n << 1,1, - 1,1; - - // block as lvalue - m.block(0,0,2,2) = n; - - //print m - cout << "m = " << endl << m << endl; + Array33f res = n.block(0,0,3,3) * m; + cout << "res =" << endl << res << endl; } diff --git a/doc/examples/Tutorial_BlockOperations_colrow.cpp b/doc/examples/Tutorial_BlockOperations_colrow.cpp index e639324b2..e98263057 100644 --- a/doc/examples/Tutorial_BlockOperations_colrow.cpp +++ b/doc/examples/Tutorial_BlockOperations_colrow.cpp @@ -1,15 +1,14 @@ #include <Eigen/Dense> #include <iostream> -using namespace Eigen; int main() { - MatrixXf m(3,3); - + Eigen::MatrixXf m(3,3); m << 1,2,3, 4,5,6, 7,8,9; - - std::cout << "2nd Row: " - << m.row(1) << std::endl; + std::cout << "2nd Row: " << m.row(1) << std::endl; + m.col(0) += m.col(2); + std::cout << "m after adding third column to first:\n"; + std::cout << m << std::endl; } diff --git a/doc/examples/Tutorial_BlockOperations_corner.cpp b/doc/examples/Tutorial_BlockOperations_corner.cpp index 96c6df62b..3a31507aa 100644 --- a/doc/examples/Tutorial_BlockOperations_corner.cpp +++ b/doc/examples/Tutorial_BlockOperations_corner.cpp @@ -2,26 +2,16 @@ #include <iostream> using namespace std; -using namespace Eigen; int main() { - MatrixXf m(4,4); - + Eigen::Matrix4f m; m << 1, 2, 3, 4, 5, 6, 7, 8, 9, 10,11,12, 13,14,15,16; - - //print first two columns - cout << "-- leftCols(2) --" << endl - << m.leftCols(2) << endl << endl; - - //print last two rows - cout << "-- bottomRows(2) --" << endl - << m.bottomRows(2) << endl << endl; - - //print top-left 2x3 corner - cout << "-- topLeftCorner(2,3) --" << endl - << m.topLeftCorner(2,3) << endl; + cout << "m.leftCols(2) =" << endl << m.leftCols(2) << endl << endl; + cout << "m.bottomRows<2>() =" << endl << m.bottomRows<2>() << endl << endl; + m.topLeftCorner(1,3) = m.bottomRightCorner(3,1).transpose(); + cout << "After assignment, m = " << endl << m << endl; } diff --git a/doc/examples/Tutorial_BlockOperations_print_block.cpp b/doc/examples/Tutorial_BlockOperations_print_block.cpp index a2d0db864..0fdefecdf 100644 --- a/doc/examples/Tutorial_BlockOperations_print_block.cpp +++ b/doc/examples/Tutorial_BlockOperations_print_block.cpp @@ -1,14 +1,18 @@ #include <Eigen/Dense> #include <iostream> -using namespace Eigen; int main() { - MatrixXf m(3,3); - - m << 1,2,3, - 4,5,6, - 7,8,9; - - std::cout << m.block(0,0,2,2) << std::endl; + Eigen::MatrixXf m(4,4); + m << 1, 2, 3, 4, + 5, 6, 7, 8, + 9,10,11,12, + 13,14,15,16; + std::cout << "Block in the middle" << std::endl; + std::cout << m.block<2,2>(1,1) << std::endl << std::endl; + for (int i = 1; i < 4; ++i) + { + std::cout << "Block of size " << i << std::endl; + std::cout << m.block(0,0,i,i) << std::endl << std::endl; + } } diff --git a/doc/examples/Tutorial_BlockOperations_vector.cpp b/doc/examples/Tutorial_BlockOperations_vector.cpp index 211b55472..4a0b02342 100644 --- a/doc/examples/Tutorial_BlockOperations_vector.cpp +++ b/doc/examples/Tutorial_BlockOperations_vector.cpp @@ -2,23 +2,13 @@ #include <iostream> using namespace std; -using namespace Eigen; int main() { - VectorXf v(6); - + Eigen::ArrayXf v(6); v << 1, 2, 3, 4, 5, 6; - - //print first three elements - cout << "-- head(3) --" << endl - << v.head(3) << endl << endl; - - //print last three elements - cout << "-- tail(3) --" << endl - << v.tail(3) << endl << endl; - - //print between 2nd and 5th elem. inclusive - cout << "-- segment(1,4) --" << endl - << v.segment(1,4) << endl; + cout << "v.head(3) =" << endl << v.head(3) << endl << endl; + cout << "v.tail<3>() = " << endl << v.tail<3>() << endl << endl; + v.segment(1,4) *= 2; + cout << "after 'v.segment(1,4) *= 2', v =" << endl << v << endl; } |