mirror of
https://gitlab.com/libeigen/eigen.git
synced 2024-12-15 07:10:37 +08:00
417 lines
11 KiB
Plaintext
417 lines
11 KiB
Plaintext
namespace Eigen {
|
|
|
|
/** \page QuickStartGuide
|
|
<a name="top"></a>
|
|
|
|
<h1>Quick start guide</h1>
|
|
|
|
\b Table \b of \b contents
|
|
- \ref SimpleExampleFixedSize
|
|
- \ref SimpleExampleDynamicSize
|
|
- \ref MatrixTypes
|
|
- \ref MatrixInitialization
|
|
- \ref BasicLinearAlgebra
|
|
- \ref Reductions
|
|
- \ref SubMatrix
|
|
- \ref MatrixTransformations
|
|
- \ref Geometry
|
|
- \ref Performance
|
|
- \ref AdvancedLinearAlgebra
|
|
- \ref LinearSolvers
|
|
- \ref LU
|
|
- \ref Cholesky
|
|
- \ref QR
|
|
- \ref EigenProblems
|
|
|
|
</br>
|
|
<hr>
|
|
|
|
|
|
\section SimpleExampleFixedSize Simple example with fixed-size matrices and vectors
|
|
|
|
By fixed-size, we mean that the number of rows and columns are known at compile-time. In this case, Eigen avoids dynamic memory allocation and unroll loops. This is useful for very small sizes (typically up to 4x4).
|
|
|
|
<table><tr><td>
|
|
\include Tutorial_simple_example_fixed_size.cpp
|
|
</td>
|
|
<td>
|
|
output:
|
|
\include Tutorial_simple_example_fixed_size.out
|
|
</td></tr></table>
|
|
|
|
<a href="#" class="top">top</a>\section SimpleExampleDynamicSize Simple example with dynamic-size matrices and vectors
|
|
|
|
Dynamic-size means that the number of rows and columns are not known at compile-time. In this case, they are stored as runtime variables and the arrays are dynamically allocated.
|
|
|
|
<table><tr><td>
|
|
\include Tutorial_simple_example_dynamic_size.cpp
|
|
</td>
|
|
<td>
|
|
output:
|
|
\include Tutorial_simple_example_dynamic_size.out
|
|
</td></tr></table>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<a href="#" class="top">top</a>\section MatrixTypes Matrix and vector types
|
|
|
|
In Eigen, all kinds of dense matrices and vectors are represented by the template class Matrix. In most cases you can simply use one of the several convenient typedefs (\ref matrixtypedefs).
|
|
|
|
The template class Matrix takes a number of template parameters, but for now it is enough to understand the 3 first ones (and the others can then be left unspecified):
|
|
|
|
\code Matrix<Scalar, RowsAtCompileTime, ColsAtCompileTime> \endcode
|
|
|
|
\li \c Scalar is the scalar type, i.e. the type of the coefficients. That is, if you want a vector of floats, choose \c float here.
|
|
\li \c RowsAtCompileTime and \c ColsAtCompileTime are the number of rows and columns of the matrix as known at compile-time.
|
|
|
|
For example, \c Vector3d is a typedef for \code Matrix<double, 3, 1> \endcode
|
|
|
|
What if the matrix has dynamic-size i.e. the number of rows or cols isn't known at compile-time? Then use the special value Eigen::Dynamic. For example, \c VectorXd is a typedef for \code Matrix<double, Dynamic, 1> \endcode
|
|
|
|
|
|
|
|
|
|
|
|
<a href="#" class="top">top</a>\section MatrixInitialization Matrix and vector creation and initialization
|
|
|
|
To get a matrix with all coefficients equals to a given value you can use the Matrix::Constant() function, e.g.:
|
|
<table><tr><td>
|
|
\code
|
|
int rows=2, cols=3;
|
|
cout << MatrixXf::Constant(rows, cols, sqrt(2));
|
|
\endcode
|
|
</td>
|
|
<td>
|
|
output:
|
|
\code
|
|
1.41 1.41 1.41
|
|
1.41 1.41 1.41
|
|
\endcode
|
|
</td></tr></table>
|
|
|
|
To set all the coefficients of a matrix you can also use the setConstant() variant:
|
|
\code
|
|
MatrixXf m(rows, cols);
|
|
m.setConstant(rows, cols, value);
|
|
\endcode
|
|
|
|
Eigen also offers variants of these functions for vector types and fixed-size matrices or vectors, as well as similar functions to create matrices with all coefficients equal to zero or one, to create the identity matrix and matrices with random coefficients:
|
|
|
|
<table>
|
|
<tr>
|
|
<td>Fixed-size matrix or vector</td>
|
|
<td>Dynamic-size matrix</td>
|
|
<td>Dynamic-size vector</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
\code
|
|
Matrix3f x;
|
|
|
|
x = Matrix3f::Zero();
|
|
x = Matrix3f::Ones();
|
|
x = Matrix3f::Constant(6);
|
|
x = Matrix3f::Identity();
|
|
x = Matrix3f::Random();
|
|
|
|
x.setZero();
|
|
x.setOnes();
|
|
x.setIdentity();
|
|
x.setConstant(6);
|
|
x.setRandom();
|
|
\endcode
|
|
</td>
|
|
<td>
|
|
\code
|
|
MatrixXf x;
|
|
|
|
x = MatrixXf::Zero(rows, cols);
|
|
x = MatrixXf::Ones(rows, cols);
|
|
x = MatrixXf::Constant(rows, cols, 6);
|
|
x = MatrixXf::Identity(rows, cols);
|
|
x = MatrixXf::Random(rows, cols);
|
|
|
|
x.setZero(rows, cols);
|
|
x.setOnes(rows, cols);
|
|
x.setConstant(rows, cols, 6);
|
|
x.setIdentity(rows, cols);
|
|
x.setRandom(rows, cols);
|
|
\endcode
|
|
</td>
|
|
<td>
|
|
\code
|
|
VectorXf x;
|
|
|
|
x = VectorXf::Zero(size);
|
|
x = VectorXf::Ones(size);
|
|
x = VectorXf::Constant(size, 6);
|
|
x = VectorXf::Identity(size);
|
|
x = VectorXf::Random(size);
|
|
|
|
x.setZero(size);
|
|
x.setOnes(size);
|
|
x.setConstant(size, 6);
|
|
x.setIdentity(size);
|
|
x.setRandom(size);
|
|
\endcode
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
Finally, all the coefficients of a matrix can be set to specific values using the comma initializer syntax:
|
|
<table><tr><td>
|
|
\include Tutorial_commainit_01.cpp
|
|
</td>
|
|
<td>
|
|
output:
|
|
\verbinclude Tutorial_commainit_01.out
|
|
</td></tr></table>
|
|
|
|
Eigen's comma initializer also allows you to set the matrix per block:
|
|
<table><tr><td>
|
|
\include Tutorial_commainit_02.cpp
|
|
</td>
|
|
<td>
|
|
output:
|
|
\verbinclude Tutorial_commainit_02.out
|
|
</td></tr></table>
|
|
|
|
Here .finished() is used to get the actual matrix object once the comma initialization
|
|
of our temporary submatrix is done. Note that despite the appearant complexity of such an expression
|
|
Eigen's comma initializer usually yields to very optimized code without any overhead.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<a href="#" class="top">top</a>\section BasicLinearAlgebra Basic Linear Algebra
|
|
|
|
In short all mathematically well defined operators can be used right away as in the following example:
|
|
\code
|
|
mat4 -= mat1*1.5 + mat2 * mat3/4;
|
|
\endcode
|
|
which includes two matrix scalar products ("mat1*1.5" and "mat3/4"), a matrix-matrix product ("mat2 * mat3/4"),
|
|
a matrix addition ("+") and substraction with assignment ("-=").
|
|
|
|
<table>
|
|
<tr><td>
|
|
matrix/vector product</td><td>\code
|
|
col2 = mat1 * col1;
|
|
row2 = row1 * mat1; row1 *= mat1;
|
|
mat3 = mat1 * mat2; mat3 *= mat1; \endcode
|
|
</td></tr>
|
|
<tr><td>
|
|
add/subtract</td><td>\code
|
|
mat3 = mat1 + mat2; mat3 += mat1;
|
|
mat3 = mat1 - mat2; mat3 -= mat1;\endcode
|
|
</td></tr>
|
|
<tr><td>
|
|
scalar product</td><td>\code
|
|
mat3 = mat1 * s1; mat3 = s1 * mat1; mat3 *= s1;
|
|
mat3 = mat1 / s1; mat3 /= s1;\endcode
|
|
</td></tr>
|
|
<tr><td>
|
|
\link MatrixBase::dot() dot product \endlink (inner product)</td><td>\code
|
|
scalar = vec1.dot(vec2);\endcode
|
|
</td></tr>
|
|
<tr><td>
|
|
outer product</td><td>\code
|
|
mat = vec1 * vec2.transpose();\endcode
|
|
</td></tr>
|
|
<tr><td>
|
|
\link MatrixBase::cross() cross product \endcode</td><td>\code
|
|
#include <Eigen/Geometry>
|
|
vec3 = vec1.cross(vec2);\endcode</td></tr>
|
|
</table>
|
|
|
|
|
|
In Eigen only mathematically well defined operators can be used right away,
|
|
but don't worry, thanks to the \link Cwise .cwise() \endlink operator prefix,
|
|
Eigen's matrices also provide a very powerful numerical container supporting
|
|
most common coefficient wise operators:
|
|
|
|
<table>
|
|
|
|
<tr><td>Coefficient wise product</td>
|
|
<td>\code mat3 = mat1.cwise() * mat2; \endcode
|
|
</td></tr>
|
|
<tr><td>
|
|
Add a scalar to all coefficients</td><td>\code
|
|
mat3 = mat1.cwise() + scalar;
|
|
mat3.cwise() += scalar;
|
|
mat3.cwise() -= scalar;
|
|
\endcode
|
|
</td></tr>
|
|
<tr><td>
|
|
Coefficient wise division</td><td>\code
|
|
mat3 = mat1.cwise() / mat2; \endcode
|
|
</td></tr>
|
|
<tr><td>
|
|
Coefficient wise reciprocal</td><td>\code
|
|
mat3 = mat1.cwise().inverse(); \endcode
|
|
</td></tr>
|
|
<tr><td>
|
|
Coefficient wise comparisons \n
|
|
(support all operators)</td><td>\code
|
|
mat3 = mat1.cwise() < mat2;
|
|
mat3 = mat1.cwise() <= mat2;
|
|
mat3 = mat1.cwise() > mat2;
|
|
etc.
|
|
\endcode
|
|
</td></tr>
|
|
<tr><td>
|
|
Trigo:\n sin, cos, tan</td><td>\code
|
|
mat3 = mat1.cwise().sin();
|
|
etc.
|
|
\endcode
|
|
</td></tr>
|
|
<tr><td>
|
|
Power:\n pow, square, cube, sqrt, exp, log</td><td>\code
|
|
mat3 = mat1.cwise().square();
|
|
mat3 = mat1.cwise().pow(5);
|
|
mat3 = mat1.cwise().log();
|
|
etc.
|
|
\endcode
|
|
</td></tr>
|
|
<tr><td>
|
|
min, max, absolute value</td><td>\code
|
|
mat3 = mat1.cwise().min(mat2);
|
|
mat3 = mat1.cwise().max(mat2);
|
|
mat3 = mat1.cwise().abs(mat2);
|
|
mat3 = mat1.cwise().abs2(mat2);
|
|
\endcode</td></tr>
|
|
</table>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<a href="#" class="top">top</a>\section Reductions Reductions
|
|
|
|
Reductions can be done matrix-wise,
|
|
\link MatrixBase::colwise() column-wise \endlink or
|
|
\link MatrixBase::rowwise() row-wise \endlink, e.g.:
|
|
<table>
|
|
<tr><td>\code mat \endcode
|
|
</td><td>\code
|
|
5 3 1
|
|
2 7 8
|
|
9 4 6
|
|
\endcode
|
|
</td></tr>
|
|
|
|
<tr><td>\code mat.minCoeff(); \endcode</td><td>\code 1 \endcode</td><td></td>
|
|
<td>\code mat.maxCoeff(); \endcode</td><td>\code 9 \endcode</td></tr>
|
|
<tr><td>\code mat.colwise().minCoeff(); \endcode</td><td>\code 2 3 1 \endcode</td><td></td>
|
|
<td>\code mat.colwise().maxCoeff(); \endcode</td><td>\code 9 7 8 \endcode</td></tr>
|
|
<tr><td>\code mat.rowwise().minCoeff(); \endcode</td><td>\code
|
|
1
|
|
2
|
|
4
|
|
\endcode</td><td></td>
|
|
<td>\code mat.rowwise().maxCoeff(); \endcode</td><td>\code
|
|
5
|
|
8
|
|
9
|
|
\endcode</td></tr>
|
|
</table>
|
|
|
|
Eigen provides several other reduction methods such as \link Cwise::sum() sum() \endlink,
|
|
\link Cwise::norm() norm() \endlink, \link Cwise::norm2() norm2() \endlink,
|
|
\link Cwise::all() all() \endlink, and \link Cwise::any() any() \endlink.
|
|
The all() and any() functions are especially useful in combinaison with coeff-wise comparison operators.
|
|
|
|
|
|
|
|
|
|
|
|
<a href="#" class="top">top</a>\section SubMatrix Sub matrices
|
|
|
|
Read-write access to a \link MatrixBase::col(int) column \endlink
|
|
or a \link MatrixBase::row(int) row \endlink of a matrix:
|
|
\code
|
|
mat1.row(i) = mat2.col(j);
|
|
mat1.col(j1).swap(mat1.col(j2));
|
|
\endcode
|
|
|
|
Read-write access to sub-vector:
|
|
<table>
|
|
<tr>
|
|
<td>Default versions</td>
|
|
<td>Optimized versions when the size is known at compile time</td></tr>
|
|
<td></td>
|
|
|
|
<tr><td>\code vec1.start(n)\endcode</td><td>\code vec1.start<n>()\endcode</td><td>the first \c n coeffs </td></tr>
|
|
<tr><td>\code vec1.end(n)\endcode</td><td>\code vec1.end<n>()\endcode</td><td>the last \c n coeffs </td></tr>
|
|
<tr><td>\code vec1.block(pos,n)\endcode</td><td>\code vec1.block<n>(pos)\endcode</td>
|
|
<td>the \c size coeffs in the range [\c pos : \c pos + \c n [</td></tr>
|
|
</table>
|
|
|
|
Read-write access to sub-matrices:
|
|
<table>
|
|
<tr><td>Default versions</td>
|
|
<td>Optimized versions when the size is known at compile time</td><td></td></tr>
|
|
|
|
<tr>
|
|
<td>\code mat1.block(i,j,rows,cols)\endcode
|
|
\link MatrixBase::block(int,int,int,int) (more) \endlink</td>
|
|
<td>\code mat1.block<rows,cols>(i,j)\endcode
|
|
\link MatrixBase::block(int,int) (more) \endlink</td>
|
|
<td>the \c rows x \c cols sub-matrix starting from position (\c i,\c j) </td>
|
|
</tr>
|
|
<tr>
|
|
<td>\code
|
|
mat1.corner(TopLeft,rows,cols)
|
|
mat1.corner(TopRight,rows,cols)
|
|
mat1.corner(BottomLeft,rows,cols)
|
|
mat1.corner(BottomRight,rows,cols)\endcode
|
|
\link MatrixBase::corner(CornerType,int,int) (more) \endlink</td>
|
|
<td>\code
|
|
mat1.corner<rows,cols>(TopLeft)
|
|
mat1.corner<rows,cols>(TopRight)
|
|
mat1.corner<rows,cols>(BottomLeft)
|
|
mat1.corner<rows,cols>(BottomRight)\endcode
|
|
\link MatrixBase::corner(CornerType) (more) \endlink</td>
|
|
<td>the \c rows x \c cols sub-matrix \n taken in one of the four corners</td></tr>
|
|
</table>
|
|
|
|
|
|
|
|
|
|
|
|
<a href="#" class="top">top</a>\section MatrixTransformations Matrix transformations
|
|
|
|
transpose, adjoint, etc...
|
|
|
|
|
|
|
|
|
|
|
|
<a href="#" class="top">top</a>\section Geometry Geometry features
|
|
|
|
maybe a second tutorial for that
|
|
|
|
|
|
|
|
|
|
|
|
<a href="#" class="top">top</a>\section Performance Notes on performances
|
|
|
|
|
|
<a href="#" class="top">top</a>\section AdvancedLinearAlgebra Advanced Linear Algebra
|
|
|
|
\subsection LinearSolvers Solving linear problems
|
|
\subsection LU LU
|
|
\subsection Cholesky Cholesky
|
|
\subsection QR QR
|
|
\subsection EigenProblems Eigen value problems
|
|
|
|
*/
|
|
|
|
}
|