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