diff options
author | Jitse Niesen <jitse@maths.leeds.ac.uk> | 2010-07-22 15:53:21 +0100 |
---|---|---|
committer | Jitse Niesen <jitse@maths.leeds.ac.uk> | 2010-07-22 15:53:21 +0100 |
commit | 403e672587826873e8b13bd21b727cdc53256ee2 (patch) | |
tree | c6ef20738bbcc65f1ec57b2f32b19fbb58c6bc03 /doc | |
parent | 96ba7cd6557769e01778441cdf7855295542aad0 (diff) |
Extend tutorial page 5: Advanced initialization.
Diffstat (limited to 'doc')
7 files changed, 174 insertions, 13 deletions
diff --git a/doc/C05_TutorialAdvancedInitialization.dox b/doc/C05_TutorialAdvancedInitialization.dox index 1e048d4b2..96105f6a6 100644 --- a/doc/C05_TutorialAdvancedInitialization.dox +++ b/doc/C05_TutorialAdvancedInitialization.dox @@ -6,26 +6,133 @@ namespace Eigen { \li \b Previous: \ref TutorialBlockOperations \li \b Next: \ref TutorialLinearAlgebra -\section TutorialMatrixArithmCommaInitializer Comma initializer +This page discusses several advanced methods for initializing matrices. It gives more details on the +comma-initializer, which was introduced before. It also explains how to get special matrices such as the +identity matrix and the zero matrix. -Eigen offers a comma initializer syntax which allows to set all the coefficients -of any dense objects (matrix, vector, array, block, etc.) to specific values: -\include Tutorial_commainit_01.cpp +\b Table \b of \b contents + - \ref TutorialAdvancedInitializationCommaInitializer + - \ref TutorialAdvancedInitializationSpecialMatrices + - \ref TutorialAdvancedInitializationTemporaryObjects + + +\section TutorialAdvancedInitializationCommaInitializer The comma initializer + +Eigen offers a comma initializer syntax which allows the user to easily set all the coefficients of a matrix, +vector or array. Simply list the coefficients, starting at the top-left corner and moving from left to right +and from the top to the bottom. The size of the object needs to be specified beforehand. If you list too few +or too many coefficients, Eigen will complain. + +<table class="tutorial_code"><tr><td> +Example: \include Tutorial_commainit_01.cpp +</td> +<td> Output: \verbinclude Tutorial_commainit_01.out +</td></tr></table> + +The comma initializer can also be used to fill block expressions such as <tt>m.row(i)</tt>. Here is a more +complicated way to get the same result as above: + +<table class="tutorial_code"><tr><td> +Example: \include Tutorial_commainit_01b.cpp +</td> +<td> +Output: \verbinclude Tutorial_commainit_01b.out +</td></tr></table> + +Moreover, the elements of the initialization list may themselves be matrices. Thus, we can use them to +initialize matrices with a block structure. + +<table class="tutorial_code"><tr><td> +Example: \include Tutorial_AdvancedInitialization_Block.cpp +</td> +<td> +Output: \verbinclude Tutorial_AdvancedInitialization_Block.out +</td></tr></table> + + +\section TutorialAdvancedInitializationSpecialMatrices Special matrices and arrays + +The Matrix and Array classes have static methods like \link DenseBase::Zero() Zero()\endlink, which can be +used to initialize all coefficients to zero. There are three variants. The first variant takes no arguments +and can only be used for fixed-size objects. If you want to initialize a dynamic-size object to zero, you need +to specify the size. Thus, the second variant requires one argument and can be used for one-dimensional +dynamic-size objects, while the third variant requires two arguments and can be used for two-dimensional +objects. All three variants are illustrated in the following example: + +<table class="tutorial_code"><tr><td> +Example: \include Tutorial_AdvancedInitialization_Zero.cpp +</td> +<td> +Output: \verbinclude Tutorial_AdvancedInitialization_Zero.out +</td></tr></table> + +Similarly, the static method \link DenseBase::Constant() Constant\endlink(value) sets all coefficients to \c +value. If the size of the object needs to be specified, the additional arguments go before the \c value +argument, as in <tt>MatrixXd::Constant(rows, cols, value)</tt>. The method \link DenseBase::Random() Random() +\endlink fills the matrix or array with random coefficients. The identity matrix can be obtained by calling +\link MatrixBase::Identity() Identity()\endlink; this method is only available for Matrix, not for Array, +because "identity matrix" is a linear algebra concept. The method +\link DenseBase::LinSpaced LinSpaced\endlink(low, high, size) is only available for vectors and +one-dimensional arrays; it yields a vector of the specified size whose coefficients are equally spaced between +\c low and \c high. The method \c LinSpaced() is illustrated in the following example, which prints a table +with angles in degrees, the corresponding angle in radians, and their sine and cosine. + +<table class="tutorial_code"><tr><td> +Example: \include Tutorial_AdvancedInitialization_LinSpaced.cpp +</td> +<td> +Output: \verbinclude Tutorial_AdvancedInitialization_LinSpaced.out +</td></tr></table> + +This example shows that objects like the ones returned by LinSpaced() can be assigned to variables (and +expressions). Eigen defines utility functions like \link DenseBase::setZero() setZero()\endlink, +\link MatrixBase::setIdentity() \endlink and \link DenseBase:setLinSpaced() \endlink to do this +conveniently. The following example contrasts three ways to construct the matrix +\f$ J = \bigl[ \begin{smallmatrix} O & I \\ I & O \end{smallmatrix} \bigr] \f$: using static methods and +assignment, using static methods and the comma-initializer, or using the setXxx() methods. + +<table class="tutorial_code"><tr><td> +Example: \include Tutorial_AdvancedInitialization_ThreeWays.cpp +</td> +<td> +Output: \verbinclude Tutorial_AdvancedInitialization_ThreeWays.out +</td></tr></table> + +A summary of all pre-defined matrix, vector and array objects can be found in the \ref QuickRefPage. + + +\section TutorialAdvancedInitializationTemporaryObjects Temporary matrices and arrays + +As shown above, static methods as Zero() and Constant() can be used to initialize to variables at the time of +declaration or at the right-hand side of an assignment operator. You can think of these methods as returning a +matrix or array (in fact, they return a so-called \ref TopicEigenExpressionTemplates "expression object" which +evaluates to a matrix when needed). This matrix can also be used as a temporary object. The second example in +the \ref GettingStarted guide, which we reproduced here, already illustrates this. -Moreover, the elements of the initialization list may themselves be Eigen expressions: -\include Tutorial_commainit_02.cpp -Output: \verbinclude Tutorial_commainit_02.out +<table class="tutorial_code"><tr><td> +Example: \include QuickStart_example2_dynamic.cpp +</td> +<td> +Output: \verbinclude QuickStart_example2_dynamic.out +</td></tr></table> -<span class="note">\b Side \b note: here \link CommaInitializer::finished() .finished() \endlink -is used to get the actual matrix object once the comma initialization -of our temporary submatrix is done. Note that despite the apparent complexity of such an expression, -Eigen's comma initializer usually compiles to very optimized code without any overhead.</span> +The expression <tt>m + MatrixXf::Constant(3,3,1.2)</tt> constructs the 3-by-3 matrix with all its coefficients +equal to 1.2 and adds it to \c m ; in other words, it adds 1.2 to all the coefficients of \c m . The +comma-initializer can also be used to construct temporary objects. The following example constructs a random +matrix of size 2-by-3, and then multiplies this matrix on the left with +\f$ \bigl[ \begin{smallmatrix} 0 & 1 \\ 1 & 0 \end{smallmatrix} \bigr] \f$. +<table class="tutorial_code"><tr><td> +Example: \include Tutorial_AdvancedInitialization_CommaTemporary.cpp +</td> +<td> +Output: \verbinclude Tutorial_AdvancedInitialization_CommaTemporary.out +</td></tr></table> -TODO mention using the comma initializer to fill a block xpr like m.row(i) << 1,2,3; +The \link CommaInitializer::finished() finished() \endlink method is necessary here to get the actual matrix +object once the comma initialization of our temporary submatrix is done. -TODO add more sections about Identity(), Zero(), Constant(), Random(), LinSpaced(). \li \b Next: \ref TutorialLinearAlgebra diff --git a/doc/snippets/Tutorial_AdvancedInitialization_Block.cpp b/doc/snippets/Tutorial_AdvancedInitialization_Block.cpp new file mode 100644 index 000000000..96e40acfb --- /dev/null +++ b/doc/snippets/Tutorial_AdvancedInitialization_Block.cpp @@ -0,0 +1,5 @@ +MatrixXf matA(2, 2); +matA << 1, 2, 3, 4; +MatrixXf matB(4, 4); +matB << matA, matA/10, matA/10, matA; +std::cout << matB << std::endl; diff --git a/doc/snippets/Tutorial_AdvancedInitialization_CommaTemporary.cpp b/doc/snippets/Tutorial_AdvancedInitialization_CommaTemporary.cpp new file mode 100644 index 000000000..50cff4cb6 --- /dev/null +++ b/doc/snippets/Tutorial_AdvancedInitialization_CommaTemporary.cpp @@ -0,0 +1,4 @@ +MatrixXf mat = MatrixXf::Random(2, 3); +std::cout << mat << std::endl << std::endl; +mat = (MatrixXf(2,2) << 0, 1, 1, 0).finished() * mat; +std::cout << mat << std::endl; diff --git a/doc/snippets/Tutorial_AdvancedInitialization_LinSpaced.cpp b/doc/snippets/Tutorial_AdvancedInitialization_LinSpaced.cpp new file mode 100644 index 000000000..c6a73ab8c --- /dev/null +++ b/doc/snippets/Tutorial_AdvancedInitialization_LinSpaced.cpp @@ -0,0 +1,7 @@ +ArrayXXf table(10, 4); +table.col(0) = ArrayXf::LinSpaced(10, 0, 90); +table.col(1) = M_PI / 180 * table.col(0); +table.col(2) = table.col(1).sin(); +table.col(3) = table.col(1).cos(); +std::cout << " Degrees Radians Sine Cosine\n"; +std::cout << table << std::endl; diff --git a/doc/snippets/Tutorial_AdvancedInitialization_ThreeWays.cpp b/doc/snippets/Tutorial_AdvancedInitialization_ThreeWays.cpp new file mode 100644 index 000000000..cb7457652 --- /dev/null +++ b/doc/snippets/Tutorial_AdvancedInitialization_ThreeWays.cpp @@ -0,0 +1,20 @@ +const int size = 6; +MatrixXd mat1(size, size); +mat1.topLeftCorner(size/2, size/2) = MatrixXd::Zero(size/2, size/2); +mat1.topRightCorner(size/2, size/2) = MatrixXd::Identity(size/2, size/2); +mat1.bottomLeftCorner(size/2, size/2) = MatrixXd::Identity(size/2, size/2); +mat1.bottomRightCorner(size/2, size/2) = MatrixXd::Zero(size/2, size/2); +std::cout << mat1 << std::endl << std::endl; + +MatrixXd mat2(size, size); +mat2.topLeftCorner(size/2, size/2).setZero(); +mat2.topRightCorner(size/2, size/2).setIdentity(); +mat2.bottomLeftCorner(size/2, size/2).setIdentity(); +mat2.bottomRightCorner(size/2, size/2).setZero(); +std::cout << mat2 << std::endl << std::endl; + +MatrixXd mat3(size, size); +mat3 << MatrixXd::Zero(size/2, size/2), MatrixXd::Identity(size/2, size/2), + MatrixXd::Identity(size/2, size/2), MatrixXd::Zero(size/2, size/2); +std::cout << mat3 << std::endl; + diff --git a/doc/snippets/Tutorial_AdvancedInitialization_Zero.cpp b/doc/snippets/Tutorial_AdvancedInitialization_Zero.cpp new file mode 100644 index 000000000..76a36a319 --- /dev/null +++ b/doc/snippets/Tutorial_AdvancedInitialization_Zero.cpp @@ -0,0 +1,13 @@ +std::cout << "A fixed-size array:\n"; +Array33f a1 = Array33f::Zero(); +std::cout << a1 << "\n\n"; + + +std::cout << "A one-dimensional dynamic-size array:\n"; +ArrayXf a2 = ArrayXf::Zero(3); +std::cout << a2 << "\n\n"; + + +std::cout << "A two-dimensional dynamic-size array:\n"; +ArrayXXf a3 = ArrayXXf::Zero(3, 4); +std::cout << a3 << "\n"; diff --git a/doc/snippets/Tutorial_commainit_01b.cpp b/doc/snippets/Tutorial_commainit_01b.cpp new file mode 100644 index 000000000..2adb2e213 --- /dev/null +++ b/doc/snippets/Tutorial_commainit_01b.cpp @@ -0,0 +1,5 @@ +Matrix3f m; +m.row(0) << 1, 2, 3; +m.block(1,0,2,2) << 4, 5, 7, 8; +m.col(2).tail(2) << 6, 9; +std::cout << m; |