1 namespace Eigen { 2 3 /** \page TutorialAdvancedInitialization Tutorial page 5 - Advanced initialization 4 \ingroup Tutorial 5 6 \li \b Previous: \ref TutorialBlockOperations 7 \li \b Next: \ref TutorialLinearAlgebra 8 9 This page discusses several advanced methods for initializing matrices. It gives more details on the 10 comma-initializer, which was introduced before. It also explains how to get special matrices such as the 11 identity matrix and the zero matrix. 12 13 \b Table \b of \b contents 14 - \ref TutorialAdvancedInitializationCommaInitializer 15 - \ref TutorialAdvancedInitializationSpecialMatrices 16 - \ref TutorialAdvancedInitializationTemporaryObjects 17 18 19 \section TutorialAdvancedInitializationCommaInitializer The comma initializer 20 21 Eigen offers a comma initializer syntax which allows the user to easily set all the coefficients of a matrix, 22 vector or array. Simply list the coefficients, starting at the top-left corner and moving from left to right 23 and from the top to the bottom. The size of the object needs to be specified beforehand. If you list too few 24 or too many coefficients, Eigen will complain. 25 26 <table class="example"> 27 <tr><th>Example:</th><th>Output:</th></tr> 28 <tr><td> 29 \include Tutorial_commainit_01.cpp 30 </td> 31 <td> 32 \verbinclude Tutorial_commainit_01.out 33 </td></tr></table> 34 35 Moreover, the elements of the initialization list may themselves be vectors or matrices. A common use is 36 to join vectors or matrices together. For example, here is how to join two row vectors together. Remember 37 that you have to set the size before you can use the comma initializer. 38 39 <table class="example"> 40 <tr><th>Example:</th><th>Output:</th></tr> 41 <tr><td> 42 \include Tutorial_AdvancedInitialization_Join.cpp 43 </td> 44 <td> 45 \verbinclude Tutorial_AdvancedInitialization_Join.out 46 </td></tr></table> 47 48 We can use the same technique to initialize matrices with a block structure. 49 50 <table class="example"> 51 <tr><th>Example:</th><th>Output:</th></tr> 52 <tr><td> 53 \include Tutorial_AdvancedInitialization_Block.cpp 54 </td> 55 <td> 56 \verbinclude Tutorial_AdvancedInitialization_Block.out 57 </td></tr></table> 58 59 The comma initializer can also be used to fill block expressions such as <tt>m.row(i)</tt>. Here is a more 60 complicated way to get the same result as in the first example above: 61 62 <table class="example"> 63 <tr><th>Example:</th><th>Output:</th></tr> 64 <tr><td> 65 \include Tutorial_commainit_01b.cpp 66 </td> 67 <td> 68 \verbinclude Tutorial_commainit_01b.out 69 </td></tr></table> 70 71 72 \section TutorialAdvancedInitializationSpecialMatrices Special matrices and arrays 73 74 The Matrix and Array classes have static methods like \link DenseBase::Zero() Zero()\endlink, which can be 75 used to initialize all coefficients to zero. There are three variants. The first variant takes no arguments 76 and can only be used for fixed-size objects. If you want to initialize a dynamic-size object to zero, you need 77 to specify the size. Thus, the second variant requires one argument and can be used for one-dimensional 78 dynamic-size objects, while the third variant requires two arguments and can be used for two-dimensional 79 objects. All three variants are illustrated in the following example: 80 81 <table class="example"> 82 <tr><th>Example:</th><th>Output:</th></tr> 83 <tr><td> 84 \include Tutorial_AdvancedInitialization_Zero.cpp 85 </td> 86 <td> 87 \verbinclude Tutorial_AdvancedInitialization_Zero.out 88 </td></tr></table> 89 90 Similarly, the static method \link DenseBase::Constant() Constant\endlink(value) sets all coefficients to \c value. 91 If the size of the object needs to be specified, the additional arguments go before the \c value 92 argument, as in <tt>MatrixXd::Constant(rows, cols, value)</tt>. The method \link DenseBase::Random() Random() 93 \endlink fills the matrix or array with random coefficients. The identity matrix can be obtained by calling 94 \link MatrixBase::Identity() Identity()\endlink; this method is only available for Matrix, not for Array, 95 because "identity matrix" is a linear algebra concept. The method 96 \link DenseBase::LinSpaced LinSpaced\endlink(size, low, high) is only available for vectors and 97 one-dimensional arrays; it yields a vector of the specified size whose coefficients are equally spaced between 98 \c low and \c high. The method \c LinSpaced() is illustrated in the following example, which prints a table 99 with angles in degrees, the corresponding angle in radians, and their sine and cosine. 100 101 <table class="example"> 102 <tr><th>Example:</th><th>Output:</th></tr> 103 <tr><td> 104 \include Tutorial_AdvancedInitialization_LinSpaced.cpp 105 </td> 106 <td> 107 \verbinclude Tutorial_AdvancedInitialization_LinSpaced.out 108 </td></tr></table> 109 110 This example shows that objects like the ones returned by LinSpaced() can be assigned to variables (and 111 expressions). Eigen defines utility functions like \link DenseBase::setZero() setZero()\endlink, 112 \link MatrixBase::setIdentity() \endlink and \link DenseBase::setLinSpaced() \endlink to do this 113 conveniently. The following example contrasts three ways to construct the matrix 114 \f$ J = \bigl[ \begin{smallmatrix} O & I \\ I & O \end{smallmatrix} \bigr] \f$: using static methods and 115 assignment, using static methods and the comma-initializer, or using the setXxx() methods. 116 117 <table class="example"> 118 <tr><th>Example:</th><th>Output:</th></tr> 119 <tr><td> 120 \include Tutorial_AdvancedInitialization_ThreeWays.cpp 121 </td> 122 <td> 123 \verbinclude Tutorial_AdvancedInitialization_ThreeWays.out 124 </td></tr></table> 125 126 A summary of all pre-defined matrix, vector and array objects can be found in the \ref QuickRefPage. 127 128 129 \section TutorialAdvancedInitializationTemporaryObjects Usage as temporary objects 130 131 As shown above, static methods as Zero() and Constant() can be used to initialize variables at the time of 132 declaration or at the right-hand side of an assignment operator. You can think of these methods as returning a 133 matrix or array; in fact, they return so-called \ref TopicEigenExpressionTemplates "expression objects" which 134 evaluate to a matrix or array when needed, so that this syntax does not incur any overhead. 135 136 These expressions can also be used as a temporary object. The second example in 137 the \ref GettingStarted guide, which we reproduce here, already illustrates this. 138 139 <table class="example"> 140 <tr><th>Example:</th><th>Output:</th></tr> 141 <tr><td> 142 \include QuickStart_example2_dynamic.cpp 143 </td> 144 <td> 145 \verbinclude QuickStart_example2_dynamic.out 146 </td></tr></table> 147 148 The expression <tt>m + MatrixXf::Constant(3,3,1.2)</tt> constructs the 3-by-3 matrix expression with all its coefficients 149 equal to 1.2 plus the corresponding coefficient of \a m. 150 151 The comma-initializer, too, can also be used to construct temporary objects. The following example constructs a random 152 matrix of size 2-by-3, and then multiplies this matrix on the left with 153 \f$ \bigl[ \begin{smallmatrix} 0 & 1 \\ 1 & 0 \end{smallmatrix} \bigr] \f$. 154 155 <table class="example"> 156 <tr><th>Example:</th><th>Output:</th></tr> 157 <tr><td> 158 \include Tutorial_AdvancedInitialization_CommaTemporary.cpp 159 </td> 160 <td> 161 \verbinclude Tutorial_AdvancedInitialization_CommaTemporary.out 162 </td></tr></table> 163 164 The \link CommaInitializer::finished() finished() \endlink method is necessary here to get the actual matrix 165 object once the comma initialization of our temporary submatrix is done. 166 167 168 \li \b Next: \ref TutorialLinearAlgebra 169 170 */ 171 172 } 173
