mirror/eigen
2
0
Fork 0
mirror of https://gitlab.com/libeigen/eigen.git synced 2025-01-24 14:45:14 +08:00
Code Issues Packages Projects Releases Wiki Activity

improve ref tables

Browse Source
This commit is contained in:
Gael Guennebaud 2010-06-26 22:19:03 +02:00
parent e078bb2637
commit f3c64c7cce
1 changed files with 83 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

158
doc/QuickReference.dox
View File

@ -75,11 +75,11 @@ Conversion between the matrix and array worlds:
\code \code
Array44f a1, a1; Array44f a1, a1;
Matrix4f m1, m2; Matrix4f m1, m2;
m1 = a1 * a2; // OK, coeffwise product m1 = a1 * a2; // coeffwise product, implicit conversion from array to matrix.
a1 = m1 * m2; // OK, matrix product a1 = m1 * m2; // matrix product, implicit conversion from matrix to array.
a2 = a1 + m1.array(); a2 = a1 + m1.array(); // mixing array and matrix is forbidden
m2 = a1.matrix() + m1; m2 = a1.matrix() + m1; // and explicit conversion is required.
ArrayWrapper<Matrix4f> m1a(m1); // m1a is an alias for m1.array(), they share the same coefficients ArrayWrapper<Matrix4f> m1a(m1); // m1a is an alias for m1.array(), they share the same coefficients
MatrixWrapper<Array44f> a1m(a1); MatrixWrapper<Array44f> a1m(a1);
\endcode \endcode
@ -99,7 +99,7 @@ Vector2f v1(x, y);
Array3i v2(x, y, z); Array3i v2(x, y, z);
Vector4d v3(x, y, z, w); Vector4d v3(x, y, z, w);
VectorXf v5; VectorXf v5; // empty object
ArrayXf v6(size); ArrayXf v6(size);
\endcode</td><td>\code \endcode</td><td>\code
Matrix4f m1; Matrix4f m1;
@ -107,11 +107,10 @@ Matrix4f m1;
MatrixXf m5; MatrixXf m5; // empty object
MatrixXf m6(nb_rows, nb_columns); MatrixXf m6(nb_rows, nb_columns);
\endcode</td><td> \endcode</td><td class="note">
The coeffs are left uninitialized \n \n By default, the coefficients \n are left uninitialized</td></tr>
\n \n Empty object \n The coeffs are left uninitialized</td></tr>
<tr><td>Comma initializer</td> <tr><td>Comma initializer</td>
<td>\code <td>\code
Vector3f v1; v1 << x, y, z; Vector3f v1; v1 << x, y, z;
@ -145,7 +144,7 @@ matrix.rows(); matrix.cols();
matrix.innerSize(); matrix.outerSize(); matrix.innerSize(); matrix.outerSize();
matrix.innerStride(); matrix.outerStride(); matrix.innerStride(); matrix.outerStride();
matrix.data(); matrix.data();
\endcode</td><td>\n Inner/Outer* are storage order dependent</td></tr> \endcode</td><td class="note">\n Inner/Outer* are storage order dependent</td></tr>
<tr><td>Compile-time info</td> <tr><td>Compile-time info</td>
<td colspan="2">\code <td colspan="2">\code
ObjectType::Scalar ObjectType::RowsAtCompileTime ObjectType::Scalar ObjectType::RowsAtCompileTime
@ -165,7 +164,7 @@ matrix.resize(Eigen::NoChange, nb_cols);
matrix.resize(nb_rows, Eigen::NoChange); matrix.resize(nb_rows, Eigen::NoChange);
matrix.resizeLike(other_matrix); matrix.resizeLike(other_matrix);
matrix.conservativeResize(nb_rows, nb_cols); matrix.conservativeResize(nb_rows, nb_cols);
\endcode</td><td></td>no-op if the new sizes match,\n otherwise data are lost \n \n resizing with data preservation</tr> \endcode</td><td class="note">no-op if the new sizes match,\n otherwise data are lost \n \n resizing with data preservation</td></tr>
<tr><td>Coeff access with \n range checking</td> <tr><td>Coeff access with \n range checking</td>
<td>\code <td>\code
@ -175,7 +174,7 @@ vector[i] vector.y()
vector.w() vector.w()
\endcode</td><td>\code \endcode</td><td>\code
matrix(i,j) matrix(i,j)
\endcode</td><td><em class="note">Range checking is disabled if \n NDEBUG or EIGEN_NO_DEBUG is defined</em></td></tr> \endcode</td><td class="note">Range checking is disabled if \n NDEBUG or EIGEN_NO_DEBUG is defined</td></tr>
<tr><td>Coeff access without \n range checking</td> <tr><td>Coeff access without \n range checking</td>
<td>\code <td>\code
@ -190,7 +189,7 @@ matrix.coeffRef(i,j)
<td colspan="2">\code <td colspan="2">\code
object = expression; object = expression;
object_of_float = expression_of_double.cast<float>(); object_of_float = expression_of_double.cast<float>();
\endcode</td><td>the destination is automatically resized (if possible)</td></tr> \endcode</td><td class="note">the destination is automatically resized (if possible)</td></tr>
</table> </table>
@ -289,27 +288,27 @@ VectorXf::Unit(4,1) == Vector4f(0,1,0,0)
\subsection QuickRef_Map Map \subsection QuickRef_Map Mapping external arrays
<table class="tutorial_code"> <table class="tutorial_code">
<tr> <tr>
<td>Contiguous memory</td> <td>Contiguous \n memory</td>
<td>\code <td>\code
float data[] = {1,2,3,4}; float data[] = {1,2,3,4};
Map<Vector3f> v1(data); // uses v1 as a Vector3f object Map<Vector3f> v1(data); // uses v1 as a Vector3f object
Map<ArrayXf> v2(data,3); // uses v2 as a ArrayXf object Map<ArrayXf> v2(data,3); // uses v2 as a ArrayXf object
Map<Array22f> m1(data); // uses m1 as a Array22f object Map<Array22f> m1(data); // uses m1 as a Array22f object
Map<MatrixXf> m2(data,2,2); // uses m2 as a MatrixXf object Map<MatrixXf> m2(data,2,2); // uses m2 as a MatrixXf object
\endcode</td> \endcode</td>
</tr> </tr>
<tr> <tr>
<td>Typical usage of strides</td> <td>Typical usage \n of strides</td>
<td>\code <td>\code
float data[] = {1,2,3,4,5,6,7,8,9}; float data[] = {1,2,3,4,5,6,7,8,9};
Map<VectorXf,0,InnerStride<2> > v1(data,3); // == [1,3,5] Map<VectorXf,0,InnerStride<2> > v1(data,3); // = [1,3,5]
Map<VectorXf,0,InnerStride<> > v2(data,3,InnerStride<>(3)); // == [1,4,7] Map<VectorXf,0,InnerStride<> > v2(data,3,InnerStride<>(3)); // = [1,4,7]
Map<MatrixXf,0,OuterStride<> > m1(data,2,3,OuterStride<>(3)); // == |1,4,7| Map<MatrixXf,0,OuterStride<3> > m2(data,2,3); // both lines |1,4,7|
Map<MatrixXf,0,OuterStride<3> > m2(data,2,3); // |2,5,8| Map<MatrixXf,0,OuterStride<> > m1(data,2,3,OuterStride<>(3)); // are equal to: |2,5,8|
\endcode</td> \endcode</td>
</tr> </tr>
</table> </table>
@ -320,32 +319,32 @@ Map<MatrixXf,0,OuterStride<3> > m2(data,2,3); // |2,5,8|
<table class="tutorial_code"> <table class="tutorial_code">
<tr><td> <tr><td>
add/subtract</td><td>\code add \n subtract</td><td>\code
mat3 = mat1 + mat2; mat3 += mat1; mat3 = mat1 + mat2; mat3 += mat1;
mat3 = mat1 - mat2; mat3 -= mat1;\endcode mat3 = mat1 - mat2; mat3 -= mat1;\endcode
</td></tr> </td></tr>
<tr><td> <tr><td>
scalar product</td><td>\code scalar product</td><td>\code
mat3 = mat1 * s1; mat3 = s1 * mat1; mat3 *= s1; mat3 = mat1 * s1; mat3 *= s1; mat3 = s1 * mat1;
mat3 = mat1 / s1; mat3 /= s1;\endcode mat3 = mat1 / s1; mat3 /= s1;\endcode
</td></tr> </td></tr>
<tr><td> <tr><td>
matrix/vector product \matrixworld</td><td>\code matrix/vector \n products \matrixworld</td><td>\code
col2 = mat1 * col1; col2 = mat1 * col1;
row2 = row1 * mat1; row1 *= mat1; row2 = row1 * mat1; row1 *= mat1;
mat3 = mat1 * mat2; mat3 *= mat1; \endcode mat3 = mat1 * mat2; mat3 *= mat1; \endcode
</td></tr> </td></tr>
<tr><td> <tr><td>
transpose et adjoint \matrixworld</td><td>\code transposition \n adjoint \matrixworld</td><td>\code
mat1 = mat2.transpose(); mat1.transposeInPlace(); mat1 = mat2.transpose(); mat1.transposeInPlace();
mat1 = mat2.adjoint(); mat1.adjointInPlace(); mat1 = mat2.adjoint(); mat1.adjointInPlace();
\endcode \endcode
</td></tr> </td></tr>
<tr><td> <tr><td>
\link MatrixBase::dot() dot \endlink \& inner products \matrixworld</td><td>\code \link MatrixBase::dot() dot \endlink product \n inner product \matrixworld</td><td>\code
scalar = vec1.dot(vec2);
scalar = col1.adjoint() * col2; scalar = col1.adjoint() * col2;
scalar = (col1.adjoint() * col2).value(); scalar = (col1.adjoint() * col2).value();\endcode
scalar = vec1.dot(vec2);\endcode
</td></tr> </td></tr>
<tr><td> <tr><td>
outer product \matrixworld</td><td>\code outer product \matrixworld</td><td>\code
@ -353,7 +352,7 @@ mat = col1 * col2.transpose();\endcode
</td></tr> </td></tr>
<tr><td> <tr><td>
\link MatrixBase::norm() norm \endlink and \link MatrixBase::normalized() normalization \endlink \matrixworld</td><td>\code \link MatrixBase::norm() norm \endlink \n \link MatrixBase::normalized() normalization \endlink \matrixworld</td><td>\code
scalar = vec1.norm(); scalar = vec1.squaredNorm() scalar = vec1.norm(); scalar = vec1.squaredNorm()
vec2 = vec1.normalized(); vec1.normalize(); // inplace \endcode vec2 = vec1.normalized(); vec1.normalize(); // inplace \endcode
</td></tr> </td></tr>
@ -400,7 +399,7 @@ array1 < array2 array1 > array2 array1 < scalar array1 > scalar
array1 <= array2 array1 >= array2 array1 <= scalar array1 >= scalar array1 <= array2 array1 >= array2 array1 <= scalar array1 >= scalar
array1 == array2 array1 != array2 array1 == scalar array1 != scalar array1 == array2 array1 != array2 array1 == scalar array1 != scalar
\endcode</td></tr> \endcode</td></tr>
<tr><td>Special functions \n and STL variants</td><td>\code <tr><td>Trigo, power, and \n misc functions \n and the STL variants</td><td>\code
array1.min(array2) std::min(array1,array2) array1.min(array2) std::min(array1,array2)
array1.max(array2) std::max(array1,array2) array1.max(array2) std::max(array1,array2)
array1.abs2() array1.abs2()
@ -424,7 +423,8 @@ array1.tan() std::tan(array1)
Eigen provides several reduction methods such as: Eigen provides several reduction methods such as:
\link DenseBase::minCoeff() minCoeff() \endlink, \link DenseBase::maxCoeff() maxCoeff() \endlink, \link DenseBase::minCoeff() minCoeff() \endlink, \link DenseBase::maxCoeff() maxCoeff() \endlink,
\link DenseBase::sum() sum() \endlink, \link MatrixBase::trace() trace() \endlink \matrixworld, \link DenseBase::sum() sum() \endlink, \link DenseBase::prod() prod() \endlink,
\link MatrixBase::trace() trace() \endlink \matrixworld,
\link MatrixBase::norm() norm() \endlink \matrixworld, \link MatrixBase::squaredNorm() squaredNorm() \endlink \matrixworld, \link MatrixBase::norm() norm() \endlink \matrixworld, \link MatrixBase::squaredNorm() squaredNorm() \endlink \matrixworld,
\link DenseBase::all() all() \endlink \redstar,and \link DenseBase::any() any() \endlink \redstar. \link DenseBase::all() all() \endlink \redstar,and \link DenseBase::any() any() \endlink \redstar.
All reduction operations can be done matrix-wise, All reduction operations can be done matrix-wise,
@ -444,14 +444,21 @@ mat = 2 7 8
\endcode</td></tr> \endcode</td></tr>
</table> </table>
Also note that maxCoeff and minCoeff can takes optional arguments returning the coordinates of the respective min/max coeff: \link DenseBase::maxCoeff(int*,int*) const maxCoeff(int* i, int* j) \endlink, \link DenseBase::minCoeff(int*,int*) const minCoeff(int* i, int* j) \endlink. Special versions of \link DenseBase::minCoeff(int*,int*) minCoeff \endlink and \link DenseBase::maxCoeff(int*,int*) maxCoeff \endlink:
\code
<span class="note">\b Side \b note: The all() and any() functions are especially useful in combination with coeff-wise comparison operators.</span> int i, j;
s = vector.minCoeff(&i); // s == vector[i]
s = matrix.maxCoeff(&i, &j); // s == matrix(i,j)
\endcode
Typical use cases of all() and any():
\code
if((array1 > 0).all()) ... // if all coefficients of array1 are greater than 0 ...
if((array1 < array2).any()) ... // if there exist a pair i,j such that array1(i,j) < array2(i,j) ...
\endcode
<a href="#" class="top">top</a>\section QuickRef_Blocks Sub-matrices
<a href="#" class="top">top</a>\section QuickRef_Blocks Matrix blocks
Read-write access to a \link DenseBase::col(int) column \endlink Read-write access to a \link DenseBase::col(int) column \endlink
or a \link DenseBase::row(int) row \endlink of a matrix (or array): or a \link DenseBase::row(int) row \endlink of a matrix (or array):
@ -501,7 +508,7 @@ Read-write access to sub-matrices:</td><td></td><td></td></tr>
mat1.bottomRows<rows>() mat1.bottomRows<rows>()
mat1.leftCols<cols>() mat1.leftCols<cols>()
mat1.rightCols<cols>()\endcode mat1.rightCols<cols>()\endcode
<td>specialized versions of block() when the block fit two corners</td></tr> <td>specialized versions of block() \n when the block fit two corners</td></tr>
</table> </table>
@ -514,7 +521,7 @@ Read-write access to sub-matrices:</td><td></td><td></td></tr>
<table class="tutorial_code"> <table class="tutorial_code">
<tr><td> <tr><td>
\link MatrixBase::asDiagonal() make a diagonal matrix \endlink \n from a vector </td><td>\code view a vector \link MatrixBase::asDiagonal() as a diagonal matrix \endlink \n </td><td>\code
mat1 = vec1.asDiagonal();\endcode mat1 = vec1.asDiagonal();\endcode
</td></tr> </td></tr>
<tr><td> <tr><td>
@ -522,13 +529,13 @@ Declare a diagonal matrix</td><td>\code
DiagonalMatrix<Scalar,SizeAtCompileTime> diag1(size); DiagonalMatrix<Scalar,SizeAtCompileTime> diag1(size);
diag1.diagonal() = vector;\endcode diag1.diagonal() = vector;\endcode
</td></tr> </td></tr>
<tr><td>Access \link MatrixBase::diagonal() the diagonal and super/sub diagonals of a matrix \endlink as a vector (read/write)</td> <tr><td>Access the \link MatrixBase::diagonal() diagonal \endlink and \link MatrixBase::diagonal(int) super/sub diagonals \endlink of a matrix as a vector (read/write)</td>
<td>\code <td>\code
vec1 = mat1.diagonal(); mat1.diagonal() = vec1; // main diagonal vec1 = mat1.diagonal(); mat1.diagonal() = vec1; // main diagonal
vec1 = mat1.diagonal(+n); mat1.diagonal(+n) = vec1; // n-th super diagonal vec1 = mat1.diagonal(+n); mat1.diagonal(+n) = vec1; // n-th super diagonal
vec1 = mat1.diagonal(-n); mat1.diagonal(-n) = vec1; // n-th sub diagonal vec1 = mat1.diagonal(-n); mat1.diagonal(-n) = vec1; // n-th sub diagonal
vec1 = mat1.diagonal<1>(); mat1.diagonal<1>() = vec1; // first super diagonal vec1 = mat1.diagonal<1>(); mat1.diagonal<1>() = vec1; // first super diagonal
vec1 = mat1.diagonal<-2>(); mat1.diagonal<-2>() = vec1; // second sub diagonal vec1 = mat1.diagonal<-2>(); mat1.diagonal<-2>() = vec1; // second sub diagonal
\endcode</td> \endcode</td>
</tr> </tr>
@ -545,13 +552,12 @@ mat3 = mat1 * diag1.inverse()
\subsection QuickRef_TriangularView Triangular views \subsection QuickRef_TriangularView Triangular views
TriangularView allows to get views on a triangular part of a dense matrix and perform optimized operations on it. The opposite triangular is never referenced and can be TriangularView 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.
used to store other information.
<table class="tutorial_code"> <table class="tutorial_code">
<tr><td> <tr><td>
Reference a read/write triangular part of a given \n Reference to a triangular with optional \n
matrix (or expression) m with optional unit diagonal: unit or null diagonal (read/write):
</td><td>\code </td><td>\code
m.triangularView<Xxx>() m.triangularView<Xxx>()
\endcode \n \endcode \n
@ -574,19 +580,21 @@ m3 += s1 * m1.adjoint().triangularView<Eigen::UnitUpper>() * m2
m3 -= s1 * m2.conjugate() * m1.adjoint().triangularView<Eigen::Lower>() \endcode m3 -= s1 * m2.conjugate() * m1.adjoint().triangularView<Eigen::Lower>() \endcode
</td></tr> </td></tr>
<tr><td> <tr><td>
Solving linear equations:\n(\f$ m_2 := m_1^{-1} m_2 \f$) Solving linear equations:\n
</td><td>\code \f$ M_2 := L_1^{-1} M_2 \f$ \n
m1.triangularView<Eigen::UnitLower>().solveInPlace(m2) \f$ M_3 := {L_1^*}^{-1} M_3 \f$ \n
m1.adjoint().triangularView<Eigen::Upper>().solveInPlace(m2)\endcode \f$ M_4 := M_3 U_1^{-1} \f$
</td><td>\n \code
L1.triangularView<Eigen::UnitLower>().solveInPlace(M2)
L1.triangularView<Eigen::Lower>().adjoint().solveInPlace(M3)
U1.triangularView<Eigen::Upper>().solveInPlace<OnTheRight>(M4)\endcode
</td></tr> </td></tr>
</table> </table>
\subsection QuickRef_SelfadjointMatrix Symmetric/selfadjoint views \subsection QuickRef_SelfadjointMatrix Symmetric/selfadjoint views
Just as for triangular matrix, you can reference any triangular part of a square matrix to see it a selfadjoint Just as for triangular matrix, you can reference any triangular part of a square matrix to see it as a selfadjoint
matrix and perform special and optimized operations. Again the opposite triangular is never referenced and can be matrix and perform special and optimized operations. Again the opposite triangular part is never referenced and can be
used to store other information. used to store other information.
<table class="tutorial_code"> <table class="tutorial_code">
@ -602,26 +610,26 @@ m3 = s1 * m1.conjugate().selfadjointView<Eigen::Upper>() * m3;
m3 -= s1 * m3.adjoint() * m1.selfadjointView<Eigen::Lower>();\endcode m3 -= s1 * m3.adjoint() * m1.selfadjointView<Eigen::Lower>();\endcode
</td></tr> </td></tr>
<tr><td> <tr><td>
Rank 1 and rank K update: Rank 1 and rank K update: \n
</td><td>\code \f$ upper(M_1) += s1 M_2^* M_2 \f$ \n
// fast version of m1 += s1 * m2 * m2.adjoint(): \f$ lower(M_1) -= M_2 M_2^* \f$
m1.selfadjointView<Eigen::Upper>().rankUpdate(m2,s1); </td><td>\n \code
// fast version of m1 -= m2.adjoint() * m2: M1.selfadjointView<Eigen::Upper>().rankUpdate(M2,s1);
m1.selfadjointView<Eigen::Lower>().rankUpdate(m2.adjoint(),-1); \endcode m1.selfadjointView<Eigen::Lower>().rankUpdate(m2.adjoint(),-1); \endcode
</td></tr> </td></tr>
<tr><td> <tr><td>
Rank 2 update: (\f$ m += s u v^* + s v u^* \f$) Rank 2 update: (\f$ M += s u v^* + s v u^* \f$)
</td><td>\code </td><td>\code
m.selfadjointView<Eigen::Upper>().rankUpdate(u,v,s); M.selfadjointView<Eigen::Upper>().rankUpdate(u,v,s);
\endcode \endcode
</td></tr> </td></tr>
<tr><td> <tr><td>
Solving linear equations:\n(\f$ m_2 := m_1^{-1} m_2 \f$) Solving linear equations:\n(\f$ M_2 := M_1^{-1} M_2 \f$)
</td><td>\code </td><td>\code
// via a standard Cholesky factorization // via a standard Cholesky factorization
m1.selfadjointView<Eigen::Upper>().llt().solveInPlace(m2); m2 = m1.selfadjointView<Eigen::Upper>().llt().solve(m2);
// via a Cholesky factorization with pivoting // via a Cholesky factorization with pivoting
m1.selfadjointView<Eigen::Upper>().ldlt().solveInPlace(m2); m2 = m1.selfadjointView<Eigen::Lower>().ldlt().solve(m2);
\endcode \endcode
</td></tr> </td></tr>
</table> </table>