From b0bd1cfa059983925456630c02fbaf0a76db8aae Mon Sep 17 00:00:00 2001 From: Jitse Niesen Date: Wed, 14 Jul 2010 10:16:12 +0100 Subject: Tutorial page 4: add some text, diversify examples. Use \verbinclude for output text to disable syntax highlighting. Give tables consistent look. --- doc/C02_TutorialMatrixArithmetic.dox | 18 +- doc/C04_TutorialBlockOperations.dox | 195 +++++++++------------ doc/C07_TutorialReductionsVisitorsBroadcasting.dox | 2 +- .../Tutorial_BlockOperations_block_assignment.cpp | 23 +-- doc/examples/Tutorial_BlockOperations_colrow.cpp | 11 +- doc/examples/Tutorial_BlockOperations_corner.cpp | 20 +-- .../Tutorial_BlockOperations_print_block.cpp | 20 ++- 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 -Output: \include tut_arithmetic_add_sub.out +Output: \verbinclude tut_arithmetic_add_sub.out \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 -Output: \include tut_arithmetic_scalar_mul_div.out +Output: \verbinclude tut_arithmetic_scalar_mul_div.out @@ -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 -Output: \include tut_arithmetic_transpose_conjugate.out +Output: \verbinclude tut_arithmetic_transpose_conjugate.out 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 -Output: \include tut_arithmetic_transpose_aliasing.out +Output: \verbinclude tut_arithmetic_transpose_aliasing.out 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 a = a.transpose(), s Example: \include tut_arithmetic_transpose_inplace.cpp -Output: \include tut_arithmetic_transpose_inplace.out +Output: \verbinclude tut_arithmetic_transpose_inplace.out 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 -Output: \include tut_arithmetic_matrix_mul.out +Output: \verbinclude tut_arithmetic_matrix_mul.out 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 -Output: \include tut_arithmetic_dot_cross.out +Output: \verbinclude tut_arithmetic_dot_cross.out 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 -Output: \include tut_arithmetic_redux_basic.out +Output: \verbinclude tut_arithmetic_redux_basic.out 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 a.diagonal().sum(), 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 -Output: \include tut_arithmetic_redux_minmax.out +Output: \verbinclude tut_arithmetic_redux_minmax.out 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 (p,q) whose origin is at (i,j) by using -the following syntax: +This function returns a block of size (p,q) whose origin is at (i,j). +There are two versions, whose syntax is as follows: - - + + - +
\b Block \b operationDefault \b version
\b %Block \b operationDefault version Optimized version when the
size is known at compile time
Block of size (p,q), starting at (i,j)
%Block of size (p,q), starting at (i,j) \code matrix.block(i,j,p,q);\endcode \code @@ -35,7 +36,15 @@ matrix.block(i,j);\endcode
-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. + @@ -44,10 +53,15 @@ Output: \verbinclude Tutorial_BlockOperations_print_block.out
\include Tutorial_BlockOperations_print_block.cpp
+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.
\include Tutorial_BlockOperations_block_assignment.cpp @@ -57,55 +71,38 @@ Output: \verbinclude Tutorial_BlockOperations_block_assignment.out
+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. - + +matrix.row(i);\endcode +matrix.row(i);\endcode +matrix.col(j);\endcode +matrix.col(j);\endcode
\b Block \b operation
\b %Block \b operation Default version Optimized version when the
size is known at compile time
ith row \link DenseBase::row() * \endlink \code -MatrixXf m; -std::cout << m.row(i);\endcode \code -Matrix3f m; -std::cout << m.row(i);\endcode
jth column \link DenseBase::col() * \endlink \code -MatrixXf m; -std::cout << m.col(j);\endcode \code -Matrix3f m; -std::cout << m.col(j);\endcode
-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.
C++ code: @@ -113,94 +110,83 @@ C++ code: Output: -\include Tutorial_BlockOperations_colrow.out +\verbinclude Tutorial_BlockOperations_colrow.out
-\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 matrix.topLeftCorner(p,q) to access the block +consisting of the coefficients matrix(i,j) 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 - + +matrix.topLeftCorner(p,q);\endcode +matrix.topLeftCorner();\endcode +matrix.bottomLeftCorner(p,q);\endcode +matrix.bottomLeftCorner();\endcode +matrix.topRightCorner(p,q);\endcode +matrix.topRightCorner();\endcode +matrix.bottomRightCorner(p,q);\endcode +matrix.bottomRightCorner();\endcode - +matrix.topRows(q);\endcode +matrix.topRows();\endcode - +matrix.bottomRows(q);\endcode +matrix.bottomRows();\endcode - +matrix.leftCols(p);\endcode +matrix.leftCols

();\endcode

- +matrix.rightCols(q);\endcode +matrix.rightCols();\endcode
\b Block \b operation
\b %Block \b operation Default version Optimized version when the
size is known at compile time
Top-left p by q block \link DenseBase::topLeftCorner() * \endlink \code -MatrixXf m; -std::cout << m.topLeftCorner(p,q);\endcode \code -Matrix3f m; -std::cout << m.topLeftCorner();\endcode
Bottom-left p by q block \link DenseBase::bottomLeftCorner() * \endlink \code -MatrixXf m; -std::cout << m.bottomLeftCorner(p,q);\endcode \code -Matrix3f m; -std::cout << m.bottomLeftCorner();\endcode
Top-right p by q block \link DenseBase::topRightCorner() * \endlink \code -MatrixXf m; -std::cout << m.topRightCorner(p,q);\endcode \code -Matrix3f m; -std::cout << m.topRightCorner();\endcode
Bottom-right p by q block \link DenseBase::bottomRightCorner() * \endlink \code -MatrixXf m; -std::cout << m.bottomRightCorner(p,q);\endcode \code -Matrix3f m; -std::cout << m.bottomRightCorner();\endcode
Block containing the first q rows +
%Block containing the first q rows \link DenseBase::topRows() * \endlink \code -MatrixXf m; -std::cout << m.topRows(q);\endcode \code -Matrix3f m; -std::cout << m.topRows();\endcode
Block containing the last q rows +
%Block containing the last q rows \link DenseBase::bottomRows() * \endlink \code -MatrixXf m; -std::cout << m.bottomRows(q);\endcode \code -Matrix3f m; -std::cout << m.bottomRows();\endcode
Block containing the first p columns +
%Block containing the first p columns \link DenseBase::leftCols() * \endlink \code -MatrixXf m; -std::cout << m.leftCols(p);\endcode \code -Matrix3f m; -std::cout << m.leftCols

();\endcode

Block containing the last q columns +
%Block containing the last q columns \link DenseBase::rightCols() * \endlink \code -MatrixXf m; -std::cout << m.rightCols(q);\endcode \code -Matrix3f m; -std::cout << m.rightCols();\endcode
- -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:
C++ code: @@ -208,49 +194,38 @@ C++ code: Output: -\include Tutorial_BlockOperations_corner.out +\verbinclude Tutorial_BlockOperations_corner.out
+\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: - + - +vector.head(n);\endcode +vector.head();\endcode - +vector.tail(n);\endcode +vector.tail();\endcode - +vector.segment(i,n);\endcode +vector.segment(i);\endcode
\b Block \b operation
\b %Block \b operation Default version Optimized version when the
size is known at compile time
Block containing the first \p n elements +
%Block containing the first \p n elements \link DenseBase::head() * \endlink \code -VectorXf v; -std::cout << v.head(n);\endcode \code -Vector3f v; -std::cout << v.head();\endcode
Block containing the last \p n elements +
%Block containing the last \p n elements \link DenseBase::tail() * \endlink \code -VectorXf v; -std::cout << v.tail(n);\endcode \code -Vector3f m; -std::cout << v.tail();\endcode
Block containing \p n elements, starting at position \p i +
%Block containing \p n elements, starting at position \p i \link DenseBase::segment() * \endlink \code -VectorXf v; -std::cout << v.segment(i,n);\endcode \code -Vector3f m; -std::cout << v.segment(i);\endcode
@@ -262,7 +237,7 @@ C++ code: Output: -\include Tutorial_BlockOperations_vector.out +\verbinclude Tutorial_BlockOperations_vector.out \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 -Output: \include tut_arithmetic_redux_basic.out +Output: \verbinclude tut_arithmetic_redux_basic.out 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 a.diagonal().sum(), 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 n = Array::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 #include -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 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 #include -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 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; } -- cgit v1.2.3