• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1namespace Eigen {
2
3/** \eigenManualPage QuickRefPage Quick reference guide
4
5\eigenAutoToc
6
7<hr>
8
9<a href="#" class="top">top</a>
10\section QuickRef_Headers Modules and Header files
11
12The Eigen library is divided in a Core module and several additional modules. Each module has a corresponding header file which has to be included in order to use the module. The \c %Dense and \c Eigen header files are provided to conveniently gain access to several modules at once.
13
14<table class="manual">
15<tr><th>Module</th><th>Header file</th><th>Contents</th></tr>
16<tr><td>\link Core_Module Core \endlink</td><td>\code#include <Eigen/Core>\endcode</td><td>Matrix and Array classes, basic linear algebra (including triangular and selfadjoint products), array manipulation</td></tr>
17<tr class="alt"><td>\link Geometry_Module Geometry \endlink</td><td>\code#include <Eigen/Geometry>\endcode</td><td>Transform, Translation, Scaling, Rotation2D and 3D rotations (Quaternion, AngleAxis)</td></tr>
18<tr><td>\link LU_Module LU \endlink</td><td>\code#include <Eigen/LU>\endcode</td><td>Inverse, determinant, LU decompositions with solver (FullPivLU, PartialPivLU)</td></tr>
19<tr><td>\link Cholesky_Module Cholesky \endlink</td><td>\code#include <Eigen/Cholesky>\endcode</td><td>LLT and LDLT Cholesky factorization with solver</td></tr>
20<tr class="alt"><td>\link Householder_Module Householder \endlink</td><td>\code#include <Eigen/Householder>\endcode</td><td>Householder transformations; this module is used by several linear algebra modules</td></tr>
21<tr><td>\link SVD_Module SVD \endlink</td><td>\code#include <Eigen/SVD>\endcode</td><td>SVD decomposition with least-squares solver (JacobiSVD)</td></tr>
22<tr class="alt"><td>\link QR_Module QR \endlink</td><td>\code#include <Eigen/QR>\endcode</td><td>QR decomposition with solver (HouseholderQR, ColPivHouseholderQR, FullPivHouseholderQR)</td></tr>
23<tr><td>\link Eigenvalues_Module Eigenvalues \endlink</td><td>\code#include <Eigen/Eigenvalues>\endcode</td><td>Eigenvalue, eigenvector decompositions (EigenSolver, SelfAdjointEigenSolver, ComplexEigenSolver)</td></tr>
24<tr class="alt"><td>\link Sparse_modules Sparse \endlink</td><td>\code#include <Eigen/Sparse>\endcode</td><td>%Sparse matrix storage and related basic linear algebra (SparseMatrix, DynamicSparseMatrix, SparseVector)</td></tr>
25<tr><td></td><td>\code#include <Eigen/Dense>\endcode</td><td>Includes Core, Geometry, LU, Cholesky, SVD, QR, and Eigenvalues header files</td></tr>
26<tr class="alt"><td></td><td>\code#include <Eigen/Eigen>\endcode</td><td>Includes %Dense and %Sparse header files (the whole Eigen library)</td></tr>
27</table>
28
29<a href="#" class="top">top</a>
30\section QuickRef_Types Array, matrix and vector types
31
32
33\b Recall: Eigen provides two kinds of dense objects: mathematical matrices and vectors which are both represented by the template class Matrix, and general 1D and 2D arrays represented by the template class Array:
34\code
35typedef Matrix<Scalar, RowsAtCompileTime, ColsAtCompileTime, Options> MyMatrixType;
36typedef Array<Scalar, RowsAtCompileTime, ColsAtCompileTime, Options> MyArrayType;
37\endcode
38
39\li \c Scalar is the scalar type of the coefficients (e.g., \c float, \c double, \c bool, \c int, etc.).
40\li \c RowsAtCompileTime and \c ColsAtCompileTime are the number of rows and columns of the matrix as known at compile-time or \c Dynamic.
41\li \c Options can be \c ColMajor or \c RowMajor, default is \c ColMajor. (see class Matrix for more options)
42
43All combinations are allowed: you can have a matrix with a fixed number of rows and a dynamic number of columns, etc. The following are all valid:
44\code
45Matrix<double, 6, Dynamic>                  // Dynamic number of columns (heap allocation)
46Matrix<double, Dynamic, 2>                  // Dynamic number of rows (heap allocation)
47Matrix<double, Dynamic, Dynamic, RowMajor>  // Fully dynamic, row major (heap allocation)
48Matrix<double, 13, 3>                       // Fully fixed (usually allocated on stack)
49\endcode
50
51In most cases, you can simply use one of the convenience typedefs for \ref matrixtypedefs "matrices" and \ref arraytypedefs "arrays". Some examples:
52<table class="example">
53<tr><th>Matrices</th><th>Arrays</th></tr>
54<tr><td>\code
55Matrix<float,Dynamic,Dynamic>   <=>   MatrixXf
56Matrix<double,Dynamic,1>        <=>   VectorXd
57Matrix<int,1,Dynamic>           <=>   RowVectorXi
58Matrix<float,3,3>               <=>   Matrix3f
59Matrix<float,4,1>               <=>   Vector4f
60\endcode</td><td>\code
61Array<float,Dynamic,Dynamic>    <=>   ArrayXXf
62Array<double,Dynamic,1>         <=>   ArrayXd
63Array<int,1,Dynamic>            <=>   RowArrayXi
64Array<float,3,3>                <=>   Array33f
65Array<float,4,1>                <=>   Array4f
66\endcode</td></tr>
67</table>
68
69Conversion between the matrix and array worlds:
70\code
71Array44f a1, a1;
72Matrix4f m1, m2;
73m1 = a1 * a2;                     // coeffwise product, implicit conversion from array to matrix.
74a1 = m1 * m2;                     // matrix product, implicit conversion from matrix to array.
75a2 = a1 + m1.array();             // mixing array and matrix is forbidden
76m2 = a1.matrix() + m1;            // and explicit conversion is required.
77ArrayWrapper<Matrix4f> m1a(m1);   // m1a is an alias for m1.array(), they share the same coefficients
78MatrixWrapper<Array44f> a1m(a1);
79\endcode
80
81In the rest of this document we will use the following symbols to emphasize the features which are specifics to a given kind of object:
82\li <a name="matrixonly"></a>\matrixworld linear algebra matrix and vector only
83\li <a name="arrayonly"></a>\arrayworld array objects only
84
85\subsection QuickRef_Basics Basic matrix manipulation
86
87<table class="manual">
88<tr><th></th><th>1D objects</th><th>2D objects</th><th>Notes</th></tr>
89<tr><td>Constructors</td>
90<td>\code
91Vector4d  v4;
92Vector2f  v1(x, y);
93Array3i   v2(x, y, z);
94Vector4d  v3(x, y, z, w);
95
96VectorXf  v5; // empty object
97ArrayXf   v6(size);
98\endcode</td><td>\code
99Matrix4f  m1;
100
101
102
103
104MatrixXf  m5; // empty object
105MatrixXf  m6(nb_rows, nb_columns);
106\endcode</td><td class="note">
107By default, the coefficients \n are left uninitialized</td></tr>
108<tr class="alt"><td>Comma initializer</td>
109<td>\code
110Vector3f  v1;     v1 << x, y, z;
111ArrayXf   v2(4);  v2 << 1, 2, 3, 4;
112
113\endcode</td><td>\code
114Matrix3f  m1;   m1 << 1, 2, 3,
115                      4, 5, 6,
116                      7, 8, 9;
117\endcode</td><td></td></tr>
118
119<tr><td>Comma initializer (bis)</td>
120<td colspan="2">
121\include Tutorial_commainit_02.cpp
122</td>
123<td>
124output:
125\verbinclude Tutorial_commainit_02.out
126</td>
127</tr>
128
129<tr class="alt"><td>Runtime info</td>
130<td>\code
131vector.size();
132
133vector.innerStride();
134vector.data();
135\endcode</td><td>\code
136matrix.rows();          matrix.cols();
137matrix.innerSize();     matrix.outerSize();
138matrix.innerStride();   matrix.outerStride();
139matrix.data();
140\endcode</td><td class="note">Inner/Outer* are storage order dependent</td></tr>
141<tr><td>Compile-time info</td>
142<td colspan="2">\code
143ObjectType::Scalar              ObjectType::RowsAtCompileTime
144ObjectType::RealScalar          ObjectType::ColsAtCompileTime
145ObjectType::Index               ObjectType::SizeAtCompileTime
146\endcode</td><td></td></tr>
147<tr class="alt"><td>Resizing</td>
148<td>\code
149vector.resize(size);
150
151
152vector.resizeLike(other_vector);
153vector.conservativeResize(size);
154\endcode</td><td>\code
155matrix.resize(nb_rows, nb_cols);
156matrix.resize(Eigen::NoChange, nb_cols);
157matrix.resize(nb_rows, Eigen::NoChange);
158matrix.resizeLike(other_matrix);
159matrix.conservativeResize(nb_rows, nb_cols);
160\endcode</td><td class="note">no-op if the new sizes match,<br/>otherwise data are lost<br/><br/>resizing with data preservation</td></tr>
161
162<tr><td>Coeff access with \n range checking</td>
163<td>\code
164vector(i)     vector.x()
165vector[i]     vector.y()
166              vector.z()
167              vector.w()
168\endcode</td><td>\code
169matrix(i,j)
170\endcode</td><td class="note">Range checking is disabled if \n NDEBUG or EIGEN_NO_DEBUG is defined</td></tr>
171
172<tr class="alt"><td>Coeff access without \n range checking</td>
173<td>\code
174vector.coeff(i)
175vector.coeffRef(i)
176\endcode</td><td>\code
177matrix.coeff(i,j)
178matrix.coeffRef(i,j)
179\endcode</td><td></td></tr>
180
181<tr><td>Assignment/copy</td>
182<td colspan="2">\code
183object = expression;
184object_of_float = expression_of_double.cast<float>();
185\endcode</td><td class="note">the destination is automatically resized (if possible)</td></tr>
186
187</table>
188
189\subsection QuickRef_PredefMat Predefined Matrices
190
191<table class="manual">
192<tr>
193  <th>Fixed-size matrix or vector</th>
194  <th>Dynamic-size matrix</th>
195  <th>Dynamic-size vector</th>
196</tr>
197<tr style="border-bottom-style: none;">
198  <td>
199\code
200typedef {Matrix3f|Array33f} FixedXD;
201FixedXD x;
202
203x = FixedXD::Zero();
204x = FixedXD::Ones();
205x = FixedXD::Constant(value);
206x = FixedXD::Random();
207x = FixedXD::LinSpaced(size, low, high);
208
209x.setZero();
210x.setOnes();
211x.setConstant(value);
212x.setRandom();
213x.setLinSpaced(size, low, high);
214\endcode
215  </td>
216  <td>
217\code
218typedef {MatrixXf|ArrayXXf} Dynamic2D;
219Dynamic2D x;
220
221x = Dynamic2D::Zero(rows, cols);
222x = Dynamic2D::Ones(rows, cols);
223x = Dynamic2D::Constant(rows, cols, value);
224x = Dynamic2D::Random(rows, cols);
225N/A
226
227x.setZero(rows, cols);
228x.setOnes(rows, cols);
229x.setConstant(rows, cols, value);
230x.setRandom(rows, cols);
231N/A
232\endcode
233  </td>
234  <td>
235\code
236typedef {VectorXf|ArrayXf} Dynamic1D;
237Dynamic1D x;
238
239x = Dynamic1D::Zero(size);
240x = Dynamic1D::Ones(size);
241x = Dynamic1D::Constant(size, value);
242x = Dynamic1D::Random(size);
243x = Dynamic1D::LinSpaced(size, low, high);
244
245x.setZero(size);
246x.setOnes(size);
247x.setConstant(size, value);
248x.setRandom(size);
249x.setLinSpaced(size, low, high);
250\endcode
251  </td>
252</tr>
253
254<tr><td colspan="3">Identity and \link MatrixBase::Unit basis vectors \endlink \matrixworld</td></tr>
255<tr style="border-bottom-style: none;">
256  <td>
257\code
258x = FixedXD::Identity();
259x.setIdentity();
260
261Vector3f::UnitX() // 1 0 0
262Vector3f::UnitY() // 0 1 0
263Vector3f::UnitZ() // 0 0 1
264\endcode
265  </td>
266  <td>
267\code
268x = Dynamic2D::Identity(rows, cols);
269x.setIdentity(rows, cols);
270
271
272
273N/A
274\endcode
275  </td>
276  <td>\code
277N/A
278
279
280VectorXf::Unit(size,i)
281VectorXf::Unit(4,1) == Vector4f(0,1,0,0)
282                    == Vector4f::UnitY()
283\endcode
284  </td>
285</tr>
286</table>
287
288
289
290\subsection QuickRef_Map Mapping external arrays
291
292<table class="manual">
293<tr>
294<td>Contiguous \n memory</td>
295<td>\code
296float data[] = {1,2,3,4};
297Map<Vector3f> v1(data);       // uses v1 as a Vector3f object
298Map<ArrayXf>  v2(data,3);     // uses v2 as a ArrayXf object
299Map<Array22f> m1(data);       // uses m1 as a Array22f object
300Map<MatrixXf> m2(data,2,2);   // uses m2 as a MatrixXf object
301\endcode</td>
302</tr>
303<tr>
304<td>Typical usage \n of strides</td>
305<td>\code
306float data[] = {1,2,3,4,5,6,7,8,9};
307Map<VectorXf,0,InnerStride<2> >  v1(data,3);                      // = [1,3,5]
308Map<VectorXf,0,InnerStride<> >   v2(data,3,InnerStride<>(3));     // = [1,4,7]
309Map<MatrixXf,0,OuterStride<3> >  m2(data,2,3);                    // both lines     |1,4,7|
310Map<MatrixXf,0,OuterStride<> >   m1(data,2,3,OuterStride<>(3));   // are equal to:  |2,5,8|
311\endcode</td>
312</tr>
313</table>
314
315
316<a href="#" class="top">top</a>
317\section QuickRef_ArithmeticOperators Arithmetic Operators
318
319<table class="manual">
320<tr><td>
321add \n subtract</td><td>\code
322mat3 = mat1 + mat2;           mat3 += mat1;
323mat3 = mat1 - mat2;           mat3 -= mat1;\endcode
324</td></tr>
325<tr class="alt"><td>
326scalar product</td><td>\code
327mat3 = mat1 * s1;             mat3 *= s1;           mat3 = s1 * mat1;
328mat3 = mat1 / s1;             mat3 /= s1;\endcode
329</td></tr>
330<tr><td>
331matrix/vector \n products \matrixworld</td><td>\code
332col2 = mat1 * col1;
333row2 = row1 * mat1;           row1 *= mat1;
334mat3 = mat1 * mat2;           mat3 *= mat1; \endcode
335</td></tr>
336<tr class="alt"><td>
337transposition \n adjoint \matrixworld</td><td>\code
338mat1 = mat2.transpose();      mat1.transposeInPlace();
339mat1 = mat2.adjoint();        mat1.adjointInPlace();
340\endcode
341</td></tr>
342<tr><td>
343\link MatrixBase::dot() dot \endlink product \n inner product \matrixworld</td><td>\code
344scalar = vec1.dot(vec2);
345scalar = col1.adjoint() * col2;
346scalar = (col1.adjoint() * col2).value();\endcode
347</td></tr>
348<tr class="alt"><td>
349outer product \matrixworld</td><td>\code
350mat = col1 * col2.transpose();\endcode
351</td></tr>
352
353<tr><td>
354\link MatrixBase::norm() norm \endlink \n \link MatrixBase::normalized() normalization \endlink \matrixworld</td><td>\code
355scalar = vec1.norm();         scalar = vec1.squaredNorm()
356vec2 = vec1.normalized();     vec1.normalize(); // inplace \endcode
357</td></tr>
358
359<tr class="alt"><td>
360\link MatrixBase::cross() cross product \endlink \matrixworld</td><td>\code
361#include <Eigen/Geometry>
362vec3 = vec1.cross(vec2);\endcode</td></tr>
363</table>
364
365<a href="#" class="top">top</a>
366\section QuickRef_Coeffwise Coefficient-wise \& Array operators
367Coefficient-wise operators for matrices and vectors:
368<table class="manual">
369<tr><th>Matrix API \matrixworld</th><th>Via Array conversions</th></tr>
370<tr><td>\code
371mat1.cwiseMin(mat2)
372mat1.cwiseMax(mat2)
373mat1.cwiseAbs2()
374mat1.cwiseAbs()
375mat1.cwiseSqrt()
376mat1.cwiseProduct(mat2)
377mat1.cwiseQuotient(mat2)\endcode
378</td><td>\code
379mat1.array().min(mat2.array())
380mat1.array().max(mat2.array())
381mat1.array().abs2()
382mat1.array().abs()
383mat1.array().sqrt()
384mat1.array() * mat2.array()
385mat1.array() / mat2.array()
386\endcode</td></tr>
387</table>
388
389It is also very simple to apply any user defined function \c foo using DenseBase::unaryExpr together with std::ptr_fun:
390\code mat1.unaryExpr(std::ptr_fun(foo))\endcode
391
392Array operators:\arrayworld
393
394<table class="manual">
395<tr><td>Arithmetic operators</td><td>\code
396array1 * array2     array1 / array2     array1 *= array2    array1 /= array2
397array1 + scalar     array1 - scalar     array1 += scalar    array1 -= scalar
398\endcode</td></tr>
399<tr><td>Comparisons</td><td>\code
400array1 < array2     array1 > array2     array1 < scalar     array1 > scalar
401array1 <= array2    array1 >= array2    array1 <= scalar    array1 >= scalar
402array1 == array2    array1 != array2    array1 == scalar    array1 != scalar
403\endcode</td></tr>
404<tr><td>Trigo, power, and \n misc functions \n and the STL variants</td><td>\code
405array1.min(array2)
406array1.max(array2)
407array1.abs2()
408array1.abs()                  abs(array1)
409array1.sqrt()                 sqrt(array1)
410array1.log()                  log(array1)
411array1.exp()                  exp(array1)
412array1.pow(exponent)          pow(array1,exponent)
413array1.square()
414array1.cube()
415array1.inverse()
416array1.sin()                  sin(array1)
417array1.cos()                  cos(array1)
418array1.tan()                  tan(array1)
419array1.asin()                 asin(array1)
420array1.acos()                 acos(array1)
421\endcode
422</td></tr>
423</table>
424
425<a href="#" class="top">top</a>
426\section QuickRef_Reductions Reductions
427
428Eigen provides several reduction methods such as:
429\link DenseBase::minCoeff() minCoeff() \endlink, \link DenseBase::maxCoeff() maxCoeff() \endlink,
430\link DenseBase::sum() sum() \endlink, \link DenseBase::prod() prod() \endlink,
431\link MatrixBase::trace() trace() \endlink \matrixworld,
432\link MatrixBase::norm() norm() \endlink \matrixworld, \link MatrixBase::squaredNorm() squaredNorm() \endlink \matrixworld,
433\link DenseBase::all() all() \endlink, and \link DenseBase::any() any() \endlink.
434All reduction operations can be done matrix-wise,
435\link DenseBase::colwise() column-wise \endlink or
436\link DenseBase::rowwise() row-wise \endlink. Usage example:
437<table class="manual">
438<tr><td rowspan="3" style="border-right-style:dashed;vertical-align:middle">\code
439      5 3 1
440mat = 2 7 8
441      9 4 6 \endcode
442</td> <td>\code mat.minCoeff(); \endcode</td><td>\code 1 \endcode</td></tr>
443<tr class="alt"><td>\code mat.colwise().minCoeff(); \endcode</td><td>\code 2 3 1 \endcode</td></tr>
444<tr style="vertical-align:middle"><td>\code mat.rowwise().minCoeff(); \endcode</td><td>\code
4451
4462
4474
448\endcode</td></tr>
449</table>
450
451Special versions of \link DenseBase::minCoeff(IndexType*,IndexType*) const minCoeff \endlink and \link DenseBase::maxCoeff(IndexType*,IndexType*) const maxCoeff \endlink:
452\code
453int i, j;
454s = vector.minCoeff(&i);        // s == vector[i]
455s = matrix.maxCoeff(&i, &j);    // s == matrix(i,j)
456\endcode
457Typical use cases of all() and any():
458\code
459if((array1 > 0).all()) ...      // if all coefficients of array1 are greater than 0 ...
460if((array1 < array2).any()) ... // if there exist a pair i,j such that array1(i,j) < array2(i,j) ...
461\endcode
462
463
464<a href="#" class="top">top</a>\section QuickRef_Blocks Sub-matrices
465
466Read-write access to a \link DenseBase::col(Index) column \endlink
467or a \link DenseBase::row(Index) row \endlink of a matrix (or array):
468\code
469mat1.row(i) = mat2.col(j);
470mat1.col(j1).swap(mat1.col(j2));
471\endcode
472
473Read-write access to sub-vectors:
474<table class="manual">
475<tr>
476<th>Default versions</th>
477<th>Optimized versions when the size \n is known at compile time</th></tr>
478<th></th>
479
480<tr><td>\code vec1.head(n)\endcode</td><td>\code vec1.head<n>()\endcode</td><td>the first \c n coeffs </td></tr>
481<tr><td>\code vec1.tail(n)\endcode</td><td>\code vec1.tail<n>()\endcode</td><td>the last \c n coeffs </td></tr>
482<tr><td>\code vec1.segment(pos,n)\endcode</td><td>\code vec1.segment<n>(pos)\endcode</td>
483    <td>the \c n coeffs in the \n range [\c pos : \c pos + \c n - 1]</td></tr>
484<tr class="alt"><td colspan="3">
485
486Read-write access to sub-matrices:</td></tr>
487<tr>
488  <td>\code mat1.block(i,j,rows,cols)\endcode
489      \link DenseBase::block(Index,Index,Index,Index) (more) \endlink</td>
490  <td>\code mat1.block<rows,cols>(i,j)\endcode
491      \link DenseBase::block(Index,Index) (more) \endlink</td>
492  <td>the \c rows x \c cols sub-matrix \n starting from position (\c i,\c j)</td></tr>
493<tr><td>\code
494 mat1.topLeftCorner(rows,cols)
495 mat1.topRightCorner(rows,cols)
496 mat1.bottomLeftCorner(rows,cols)
497 mat1.bottomRightCorner(rows,cols)\endcode
498 <td>\code
499 mat1.topLeftCorner<rows,cols>()
500 mat1.topRightCorner<rows,cols>()
501 mat1.bottomLeftCorner<rows,cols>()
502 mat1.bottomRightCorner<rows,cols>()\endcode
503 <td>the \c rows x \c cols sub-matrix \n taken in one of the four corners</td></tr>
504 <tr><td>\code
505 mat1.topRows(rows)
506 mat1.bottomRows(rows)
507 mat1.leftCols(cols)
508 mat1.rightCols(cols)\endcode
509 <td>\code
510 mat1.topRows<rows>()
511 mat1.bottomRows<rows>()
512 mat1.leftCols<cols>()
513 mat1.rightCols<cols>()\endcode
514 <td>specialized versions of block() \n when the block fit two corners</td></tr>
515</table>
516
517
518
519<a href="#" class="top">top</a>\section QuickRef_Misc Miscellaneous operations
520
521\subsection QuickRef_Reverse Reverse
522Vectors, rows, and/or columns of a matrix can be reversed (see DenseBase::reverse(), DenseBase::reverseInPlace(), VectorwiseOp::reverse()).
523\code
524vec.reverse()           mat.colwise().reverse()   mat.rowwise().reverse()
525vec.reverseInPlace()
526\endcode
527
528\subsection QuickRef_Replicate Replicate
529Vectors, matrices, rows, and/or columns can be replicated in any direction (see DenseBase::replicate(), VectorwiseOp::replicate())
530\code
531vec.replicate(times)                                          vec.replicate<Times>
532mat.replicate(vertical_times, horizontal_times)               mat.replicate<VerticalTimes, HorizontalTimes>()
533mat.colwise().replicate(vertical_times, horizontal_times)     mat.colwise().replicate<VerticalTimes, HorizontalTimes>()
534mat.rowwise().replicate(vertical_times, horizontal_times)     mat.rowwise().replicate<VerticalTimes, HorizontalTimes>()
535\endcode
536
537
538<a href="#" class="top">top</a>\section QuickRef_DiagTriSymm Diagonal, Triangular, and Self-adjoint matrices
539(matrix world \matrixworld)
540
541\subsection QuickRef_Diagonal Diagonal matrices
542
543<table class="example">
544<tr><th>Operation</th><th>Code</th></tr>
545<tr><td>
546view a vector \link MatrixBase::asDiagonal() as a diagonal matrix \endlink \n </td><td>\code
547mat1 = vec1.asDiagonal();\endcode
548</td></tr>
549<tr><td>
550Declare a diagonal matrix</td><td>\code
551DiagonalMatrix<Scalar,SizeAtCompileTime> diag1(size);
552diag1.diagonal() = vector;\endcode
553</td></tr>
554<tr><td>Access the \link MatrixBase::diagonal() diagonal \endlink and \link MatrixBase::diagonal(Index) super/sub diagonals \endlink of a matrix as a vector (read/write)</td>
555 <td>\code
556vec1 = mat1.diagonal();        mat1.diagonal() = vec1;      // main diagonal
557vec1 = mat1.diagonal(+n);      mat1.diagonal(+n) = vec1;    // n-th super diagonal
558vec1 = mat1.diagonal(-n);      mat1.diagonal(-n) = vec1;    // n-th sub diagonal
559vec1 = mat1.diagonal<1>();     mat1.diagonal<1>() = vec1;   // first super diagonal
560vec1 = mat1.diagonal<-2>();    mat1.diagonal<-2>() = vec1;  // second sub diagonal
561\endcode</td>
562</tr>
563
564<tr><td>Optimized products and inverse</td>
565 <td>\code
566mat3  = scalar * diag1 * mat1;
567mat3 += scalar * mat1 * vec1.asDiagonal();
568mat3 = vec1.asDiagonal().inverse() * mat1
569mat3 = mat1 * diag1.inverse()
570\endcode</td>
571</tr>
572
573</table>
574
575\subsection QuickRef_TriangularView Triangular views
576
577TriangularView gives a view on a triangular part of a dense matrix and allows to perform optimized operations on it. The opposite triangular part is never referenced and can be used to store other information.
578
579\note The .triangularView() template member function requires the \c template keyword if it is used on an
580object of a type that depends on a template parameter; see \ref TopicTemplateKeyword for details.
581
582<table class="example">
583<tr><th>Operation</th><th>Code</th></tr>
584<tr><td>
585Reference to a triangular with optional \n
586unit or null diagonal (read/write):
587</td><td>\code
588m.triangularView<Xxx>()
589\endcode \n
590\c Xxx = ::Upper, ::Lower, ::StrictlyUpper, ::StrictlyLower, ::UnitUpper, ::UnitLower
591</td></tr>
592<tr><td>
593Writing to a specific triangular part:\n (only the referenced triangular part is evaluated)
594</td><td>\code
595m1.triangularView<Eigen::Lower>() = m2 + m3 \endcode
596</td></tr>
597<tr><td>
598Conversion to a dense matrix setting the opposite triangular part to zero:
599</td><td>\code
600m2 = m1.triangularView<Eigen::UnitUpper>()\endcode
601</td></tr>
602<tr><td>
603Products:
604</td><td>\code
605m3 += s1 * m1.adjoint().triangularView<Eigen::UnitUpper>() * m2
606m3 -= s1 * m2.conjugate() * m1.adjoint().triangularView<Eigen::Lower>() \endcode
607</td></tr>
608<tr><td>
609Solving linear equations:\n
610\f$ M_2 := L_1^{-1} M_2 \f$ \n
611\f$ M_3 := {L_1^*}^{-1} M_3 \f$ \n
612\f$ M_4 := M_4 U_1^{-1} \f$
613</td><td>\n \code
614L1.triangularView<Eigen::UnitLower>().solveInPlace(M2)
615L1.triangularView<Eigen::Lower>().adjoint().solveInPlace(M3)
616U1.triangularView<Eigen::Upper>().solveInPlace<OnTheRight>(M4)\endcode
617</td></tr>
618</table>
619
620\subsection QuickRef_SelfadjointMatrix Symmetric/selfadjoint views
621
622Just as for triangular matrix, you can reference any triangular part of a square matrix to see it as a selfadjoint
623matrix and perform special and optimized operations. Again the opposite triangular part is never referenced and can be
624used to store other information.
625
626\note The .selfadjointView() template member function requires the \c template keyword if it is used on an
627object of a type that depends on a template parameter; see \ref TopicTemplateKeyword for details.
628
629<table class="example">
630<tr><th>Operation</th><th>Code</th></tr>
631<tr><td>
632Conversion to a dense matrix:
633</td><td>\code
634m2 = m.selfadjointView<Eigen::Lower>();\endcode
635</td></tr>
636<tr><td>
637Product with another general matrix or vector:
638</td><td>\code
639m3  = s1 * m1.conjugate().selfadjointView<Eigen::Upper>() * m3;
640m3 -= s1 * m3.adjoint() * m1.selfadjointView<Eigen::Lower>();\endcode
641</td></tr>
642<tr><td>
643Rank 1 and rank K update: \n
644\f$ upper(M_1) \mathrel{{+}{=}} s_1 M_2 M_2^* \f$ \n
645\f$ lower(M_1) \mathbin{{-}{=}} M_2^* M_2 \f$
646</td><td>\n \code
647M1.selfadjointView<Eigen::Upper>().rankUpdate(M2,s1);
648M1.selfadjointView<Eigen::Lower>().rankUpdate(M2.adjoint(),-1); \endcode
649</td></tr>
650<tr><td>
651Rank 2 update: (\f$ M \mathrel{{+}{=}} s u v^* + s v u^* \f$)
652</td><td>\code
653M.selfadjointView<Eigen::Upper>().rankUpdate(u,v,s);
654\endcode
655</td></tr>
656<tr><td>
657Solving linear equations:\n(\f$ M_2 := M_1^{-1} M_2 \f$)
658</td><td>\code
659// via a standard Cholesky factorization
660m2 = m1.selfadjointView<Eigen::Upper>().llt().solve(m2);
661// via a Cholesky factorization with pivoting
662m2 = m1.selfadjointView<Eigen::Lower>().ldlt().solve(m2);
663\endcode
664</td></tr>
665</table>
666
667*/
668
669/*
670<table class="tutorial_code">
671<tr><td>
672\link MatrixBase::asDiagonal() make a diagonal matrix \endlink \n from a vector </td><td>\code
673mat1 = vec1.asDiagonal();\endcode
674</td></tr>
675<tr><td>
676Declare a diagonal matrix</td><td>\code
677DiagonalMatrix<Scalar,SizeAtCompileTime> diag1(size);
678diag1.diagonal() = vector;\endcode
679</td></tr>
680<tr><td>Access \link MatrixBase::diagonal() the diagonal and super/sub diagonals of a matrix \endlink as a vector (read/write)</td>
681 <td>\code
682vec1 = mat1.diagonal();            mat1.diagonal() = vec1;      // main diagonal
683vec1 = mat1.diagonal(+n);          mat1.diagonal(+n) = vec1;    // n-th super diagonal
684vec1 = mat1.diagonal(-n);          mat1.diagonal(-n) = vec1;    // n-th sub diagonal
685vec1 = mat1.diagonal<1>();         mat1.diagonal<1>() = vec1;   // first super diagonal
686vec1 = mat1.diagonal<-2>();        mat1.diagonal<-2>() = vec1;  // second sub diagonal
687\endcode</td>
688</tr>
689
690<tr><td>View on a triangular part of a matrix (read/write)</td>
691 <td>\code
692mat2 = mat1.triangularView<Xxx>();
693// Xxx = Upper, Lower, StrictlyUpper, StrictlyLower, UnitUpper, UnitLower
694mat1.triangularView<Upper>() = mat2 + mat3; // only the upper part is evaluated and referenced
695\endcode</td></tr>
696
697<tr><td>View a triangular part as a symmetric/self-adjoint matrix (read/write)</td>
698 <td>\code
699mat2 = mat1.selfadjointView<Xxx>();     // Xxx = Upper or Lower
700mat1.selfadjointView<Upper>() = mat2 + mat2.adjoint();  // evaluated and write to the upper triangular part only
701\endcode</td></tr>
702
703</table>
704
705Optimized products:
706\code
707mat3 += scalar * vec1.asDiagonal() * mat1
708mat3 += scalar * mat1 * vec1.asDiagonal()
709mat3.noalias() += scalar * mat1.triangularView<Xxx>() * mat2
710mat3.noalias() += scalar * mat2 * mat1.triangularView<Xxx>()
711mat3.noalias() += scalar * mat1.selfadjointView<Upper or Lower>() * mat2
712mat3.noalias() += scalar * mat2 * mat1.selfadjointView<Upper or Lower>()
713mat1.selfadjointView<Upper or Lower>().rankUpdate(mat2);
714mat1.selfadjointView<Upper or Lower>().rankUpdate(mat2.adjoint(), scalar);
715\endcode
716
717Inverse products: (all are optimized)
718\code
719mat3 = vec1.asDiagonal().inverse() * mat1
720mat3 = mat1 * diag1.inverse()
721mat1.triangularView<Xxx>().solveInPlace(mat2)
722mat1.triangularView<Xxx>().solveInPlace<OnTheRight>(mat2)
723mat2 = mat1.selfadjointView<Upper or Lower>().llt().solve(mat2)
724\endcode
725
726*/
727}
728