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