ground/gcs/src/libs/eigen/doc/TutorialMatrixClass.dox

   1 namespace Eigen {
   2
   3 /** \eigenManualPage TutorialMatrixClass The Matrix class
   4
   5 \eigenAutoToc
   6
   7 In Eigen, all matrices and vectors are objects of the Matrix template class.
   8 Vectors are just a special case of matrices, with either 1 row or 1 column.
   9
  10 \section TutorialMatrixFirst3Params The first three template parameters of Matrix
  11
  12 The Matrix class takes six template parameters, but for now it's enough to
  13 learn about the first three first parameters. The three remaining parameters have default
  14 values, which for now we will leave untouched, and which we
  15 \ref TutorialMatrixOptTemplParams "discuss below".
  16
  17 The three mandatory template parameters of Matrix are:
  18 \code
  19 Matrix<typename Scalar, int RowsAtCompileTime, int ColsAtCompileTime>
  20 \endcode
  21 \li \c Scalar is the scalar type, i.e. the type of the coefficients.
  22     That is, if you want a matrix of floats, choose \c float here.
  23     See \ref TopicScalarTypes "Scalar types" for a list of all supported
  24     scalar types and for how to extend support to new types.
  25 \li \c RowsAtCompileTime and \c ColsAtCompileTime are the number of rows
  26     and columns of the matrix as known at compile time (see
  27     \ref TutorialMatrixDynamic "below" for what to do if the number is not
  28     known at compile time).
  29
  30 We offer a lot of convenience typedefs to cover the usual cases. For example, \c Matrix4f is
  31 a 4x4 matrix of floats. Here is how it is defined by Eigen:
  32 \code
  33 typedef Matrix<float, 4, 4> Matrix4f;
  34 \endcode
  35 We discuss \ref TutorialMatrixTypedefs "below" these convenience typedefs.
  36
  37 \section TutorialMatrixVectors Vectors
  38
  39 As mentioned above, in Eigen, vectors are just a special case of
  40 matrices, with either 1 row or 1 column. The case where they have 1 column is the most common;
  41 such vectors are called column-vectors, often abbreviated as just vectors. In the other case
  42 where they have 1 row, they are called row-vectors.
  43
  44 For example, the convenience typedef \c Vector3f is a (column) vector of 3 floats. It is defined as follows by Eigen:
  45 \code
  46 typedef Matrix<float, 3, 1> Vector3f;
  47 \endcode
  48 We also offer convenience typedefs for row-vectors, for example:
  49 \code
  50 typedef Matrix<int, 1, 2> RowVector2i;
  51 \endcode
  52
  53 \section TutorialMatrixDynamic The special value Dynamic
  54
  55 Of course, Eigen is not limited to matrices whose dimensions are known at compile time.
  56 The \c RowsAtCompileTime and \c ColsAtCompileTime template parameters can take the special
  57 value \c Dynamic which indicates that the size is unknown at compile time, so must
  58 be handled as a run-time variable. In Eigen terminology, such a size is referred to as a
  59 \em dynamic \em size; while a size that is known at compile time is called a
  60 \em fixed \em size. For example, the convenience typedef \c MatrixXd, meaning
  61 a matrix of doubles with dynamic size, is defined as follows:
  62 \code
  63 typedef Matrix<double, Dynamic, Dynamic> MatrixXd;
  64 \endcode
  65 And similarly, we define a self-explanatory typedef \c VectorXi as follows:
  66 \code
  67 typedef Matrix<int, Dynamic, 1> VectorXi;
  68 \endcode
  69 You can perfectly have e.g. a fixed number of rows with a dynamic number of columns, as in:
  70 \code
  71 Matrix<float, 3, Dynamic>
  72 \endcode
  73
  74 \section TutorialMatrixConstructors Constructors
  75
  76 A default constructor is always available, never performs any dynamic memory allocation, and never initializes the matrix coefficients. You can do:
  77 \code
  78 Matrix3f a;
  79 MatrixXf b;
  80 \endcode
  81 Here,
  82 \li \c a is a 3-by-3 matrix, with a plain float[9] array of uninitialized coefficients,
  83 \li \c b is a dynamic-size matrix whose size is currently 0-by-0, and whose array of
  84 coefficients hasn't yet been allocated at all.
  85
  86 Constructors taking sizes are also available. For matrices, the number of rows is always passed first.
  87 For vectors, just pass the vector size. They allocate the array of coefficients
  88 with the given size, but don't initialize the coefficients themselves:
  89 \code
  90 MatrixXf a(10,15);
  91 VectorXf b(30);
  92 \endcode
  93 Here,
  94 \li \c a is a 10x15 dynamic-size matrix, with allocated but currently uninitialized coefficients.
  95 \li \c b is a dynamic-size vector of size 30, with allocated but currently uninitialized coefficients.
  96
  97 In order to offer a uniform API across fixed-size and dynamic-size matrices, it is legal to use these
  98 constructors on fixed-size matrices, even if passing the sizes is useless in this case. So this is legal:
  99 \code
 100 Matrix3f a(3,3);
 101 \endcode
 102 and is a no-operation.
 103
 104 Finally, we also offer some constructors to initialize the coefficients of small fixed-size vectors up to size 4:
 105 \code
 106 Vector2d a(5.0, 6.0);
 107 Vector3d b(5.0, 6.0, 7.0);
 108 Vector4d c(5.0, 6.0, 7.0, 8.0);
 109 \endcode
 110
 111 \section TutorialMatrixCoeffAccessors Coefficient accessors
 112
 113 The primary coefficient accessors and mutators in Eigen are the overloaded parenthesis operators.
 114 For matrices, the row index is always passed first. For vectors, just pass one index.
 115 The numbering starts at 0. This example is self-explanatory:
 116
 117 <table class="example">
 118 <tr><th>Example:</th><th>Output:</th></tr>
 119 <tr><td>
 120 \include tut_matrix_coefficient_accessors.cpp
 121 </td>
 122 <td>
 123 \verbinclude tut_matrix_coefficient_accessors.out
 124 </td></tr></table>
 125
 126 Note that the syntax <tt> m(index) </tt>
 127 is not restricted to vectors, it is also available for general matrices, meaning index-based access
 128 in the array of coefficients. This however depends on the matrix's storage order. All Eigen matrices default to
 129 column-major storage order, but this can be changed to row-major, see \ref TopicStorageOrders "Storage orders".
 130
 131 The operator[] is also overloaded for index-based access in vectors, but keep in mind that C++ doesn't allow operator[] to
 132 take more than one argument. We restrict operator[] to vectors, because an awkwardness in the C++ language
 133 would make matrix[i,j] compile to the same thing as matrix[j] !
 134
 135 \section TutorialMatrixCommaInitializer Comma-initialization
 136
 137 %Matrix and vector coefficients can be conveniently set using the so-called \em comma-initializer syntax.
 138 For now, it is enough to know this example:
 139
 140 <table class="example">
 141 <tr><th>Example:</th><th>Output:</th></tr>
 142 <tr>
 143 <td>\include Tutorial_commainit_01.cpp </td>
 144 <td>\verbinclude Tutorial_commainit_01.out </td>
 145 </tr></table>
 146
 147
 148 The right-hand side can also contain matrix expressions as discussed in \ref TutorialAdvancedInitialization "this page".
 149
 150 \section TutorialMatrixSizesResizing Resizing
 151
 152 The current size of a matrix can be retrieved by \link EigenBase::rows() rows()\endlink, \link EigenBase::cols() cols() \endlink and \link EigenBase::size() size()\endlink. These methods return the number of rows, the number of columns and the number of coefficients, respectively. Resizing a dynamic-size matrix is done by the \link PlainObjectBase::resize(Index,Index) resize() \endlink method.
 153
 154 <table class="example">
 155 <tr><th>Example:</th><th>Output:</th></tr>
 156 <tr>
 157 <td>\include tut_matrix_resize.cpp </td>
 158 <td>\verbinclude tut_matrix_resize.out </td>
 159 </tr></table>
 160
 161 The resize() method is a no-operation if the actual matrix size doesn't change; otherwise it is destructive: the values of the coefficients may change.
 162 If you want a conservative variant of resize() which does not change the coefficients, use \link PlainObjectBase::conservativeResize() conservativeResize()\endlink, see \ref TopicResizing "this page" for more details.
 163
 164 All these methods are still available on fixed-size matrices, for the sake of API uniformity. Of course, you can't actually
 165 resize a fixed-size matrix. Trying to change a fixed size to an actually different value will trigger an assertion failure;
 166 but the following code is legal:
 167
 168 <table class="example">
 169 <tr><th>Example:</th><th>Output:</th></tr>
 170 <tr>
 171 <td>\include tut_matrix_resize_fixed_size.cpp </td>
 172 <td>\verbinclude tut_matrix_resize_fixed_size.out </td>
 173 </tr></table>
 174
 175
 176 \section TutorialMatrixAssignment Assignment and resizing
 177
 178 Assignment is the action of copying a matrix into another, using \c operator=. Eigen resizes the matrix on the left-hand side automatically so that it matches the size of the matrix on the right-hand size. For example:
 179
 180 <table class="example">
 181 <tr><th>Example:</th><th>Output:</th></tr>
 182 <tr>
 183 <td>\include tut_matrix_assignment_resizing.cpp </td>
 184 <td>\verbinclude tut_matrix_assignment_resizing.out </td>
 185 </tr></table>
 186
 187 Of course, if the left-hand side is of fixed size, resizing it is not allowed.
 188
 189 If you do not want this automatic resizing to happen (for example for debugging purposes), you can disable it, see
 190 \ref TopicResizing "this page".
 191
 192
 193 \section TutorialMatrixFixedVsDynamic Fixed vs. Dynamic size
 194
 195 When should one use fixed sizes (e.g. \c Matrix4f), and when should one prefer dynamic sizes (e.g. \c MatrixXf)?
 196 The simple answer is: use fixed
 197 sizes for very small sizes where you can, and use dynamic sizes for larger sizes or where you have to. For small sizes,
 198 especially for sizes smaller than (roughly) 16, using fixed sizes is hugely beneficial
 199 to performance, as it allows Eigen to avoid dynamic memory allocation and to unroll
 200 loops. Internally, a fixed-size Eigen matrix is just a plain array, i.e. doing
 201 \code Matrix4f mymatrix; \endcode
 202 really amounts to just doing
 203 \code float mymatrix[16]; \endcode
 204 so this really has zero runtime cost. By contrast, the array of a dynamic-size matrix
 205 is always allocated on the heap, so doing
 206 \code MatrixXf mymatrix(rows,columns); \endcode
 207 amounts to doing
 208 \code float *mymatrix = new float[rows*columns]; \endcode
 209 and in addition to that, the MatrixXf object stores its number of rows and columns as
 210 member variables.
 211
 212 The limitation of using fixed sizes, of course, is that this is only possible
 213 when you know the sizes at compile time. Also, for large enough sizes, say for sizes
 214 greater than (roughly) 32, the performance benefit of using fixed sizes becomes negligible.
 215 Worse, trying to create a very large matrix using fixed sizes inside a function could result in a
 216 stack overflow, since Eigen will try to allocate the array automatically as a local variable, and
 217 this is normally done on the stack.
 218 Finally, depending on circumstances, Eigen can also be more aggressive trying to vectorize
 219 (use SIMD instructions) when dynamic sizes are used, see \ref TopicVectorization "Vectorization".
 220
 221 \section TutorialMatrixOptTemplParams Optional template parameters
 222
 223 We mentioned at the beginning of this page that the Matrix class takes six template parameters,
 224 but so far we only discussed the first three. The remaining three parameters are optional. Here is
 225 the complete list of template parameters:
 226 \code
 227 Matrix<typename Scalar,
 228        int RowsAtCompileTime,
 229        int ColsAtCompileTime,
 230        int Options = 0,
 231        int MaxRowsAtCompileTime = RowsAtCompileTime,
 232        int MaxColsAtCompileTime = ColsAtCompileTime>
 233 \endcode
 234 \li \c Options is a bit field. Here, we discuss only one bit: \c RowMajor. It specifies that the matrices
 235       of this type use row-major storage order; by default, the storage order is column-major. See the page on
 236       \ref TopicStorageOrders "storage orders". For example, this type means row-major 3x3 matrices:
 237       \code
 238       Matrix<float, 3, 3, RowMajor>
 239       \endcode
 240 \li \c MaxRowsAtCompileTime and \c MaxColsAtCompileTime are useful when you want to specify that, even though
 241       the exact sizes of your matrices are not known at compile time, a fixed upper bound is known at
 242       compile time. The biggest reason why you might want to do that is to avoid dynamic memory allocation.
 243       For example the following matrix type uses a plain array of 12 floats, without dynamic memory allocation:
 244       \code
 245       Matrix<float, Dynamic, Dynamic, 0, 3, 4>
 246       \endcode
 247
 248 \section TutorialMatrixTypedefs Convenience typedefs
 249
 250 Eigen defines the following Matrix typedefs:
 251 \li MatrixNt for Matrix<type, N, N>. For example, MatrixXi for Matrix<int, Dynamic, Dynamic>.
 252 \li VectorNt for Matrix<type, N, 1>. For example, Vector2f for Matrix<float, 2, 1>.
 253 \li RowVectorNt for Matrix<type, 1, N>. For example, RowVector3d for Matrix<double, 1, 3>.
 254
 255 Where:
 256 \li N can be any one of \c 2, \c 3, \c 4, or \c X (meaning \c Dynamic).
 257 \li t can be any one of \c i (meaning int), \c f (meaning float), \c d (meaning double),
 258       \c cf (meaning complex<float>), or \c cd (meaning complex<double>). The fact that typedefs are only
 259     defined for these five types doesn't mean that they are the only supported scalar types. For example,
 260     all standard integer types are supported, see \ref TopicScalarTypes "Scalar types".
 261
 262
 263 */
 264
 265 }