From f3c64c7cce6f8d61c68b608a91f38544bddaa94d Mon Sep 17 00:00:00 2001 From: Gael Guennebaud Date: Sat, 26 Jun 2010 22:19:03 +0200 Subject: improve ref tables --- doc/QuickReference.dox | 158 ++++++++++++++++++++++++++----------------------- 1 file changed, 83 insertions(+), 75 deletions(-) (limited to 'doc/QuickReference.dox') diff --git a/doc/QuickReference.dox b/doc/QuickReference.dox index 47939e67b..fd08a4be0 100644 --- a/doc/QuickReference.dox +++ b/doc/QuickReference.dox @@ -75,11 +75,11 @@ Conversion between the matrix and array worlds: \code Array44f a1, a1; Matrix4f m1, m2; -m1 = a1 * a2; // OK, coeffwise product -a1 = m1 * m2; // OK, matrix product -a2 = a1 + m1.array(); -m2 = a1.matrix() + m1; -ArrayWrapper m1a(m1); // m1a is an alias for m1.array(), they share the same coefficients +m1 = a1 * a2; // coeffwise product, implicit conversion from array to matrix. +a1 = m1 * m2; // matrix product, implicit conversion from matrix to array. +a2 = a1 + m1.array(); // mixing array and matrix is forbidden +m2 = a1.matrix() + m1; // and explicit conversion is required. +ArrayWrapper m1a(m1); // m1a is an alias for m1.array(), they share the same coefficients MatrixWrapper a1m(a1); \endcode @@ -99,7 +99,7 @@ Vector2f v1(x, y); Array3i v2(x, y, z); Vector4d v3(x, y, z, w); -VectorXf v5; +VectorXf v5; // empty object ArrayXf v6(size); \endcode\code Matrix4f m1; @@ -107,11 +107,10 @@ Matrix4f m1; -MatrixXf m5; +MatrixXf m5; // empty object MatrixXf m6(nb_rows, nb_columns); -\endcode -The coeffs are left uninitialized \n \n - \n \n Empty object \n The coeffs are left uninitialized +\endcode +By default, the coefficients \n are left uninitialized Comma initializer \code Vector3f v1; v1 << x, y, z; @@ -145,7 +144,7 @@ matrix.rows(); matrix.cols(); matrix.innerSize(); matrix.outerSize(); matrix.innerStride(); matrix.outerStride(); matrix.data(); -\endcode\n Inner/Outer* are storage order dependent +\endcode\n Inner/Outer* are storage order dependent Compile-time info \code ObjectType::Scalar ObjectType::RowsAtCompileTime @@ -165,7 +164,7 @@ matrix.resize(Eigen::NoChange, nb_cols); matrix.resize(nb_rows, Eigen::NoChange); matrix.resizeLike(other_matrix); matrix.conservativeResize(nb_rows, nb_cols); -\endcodeno-op if the new sizes match,\n otherwise data are lost \n \n resizing with data preservation +\endcodeno-op if the new sizes match,\n otherwise data are lost \n \n resizing with data preservation Coeff access with \n range checking \code @@ -175,7 +174,7 @@ vector[i] vector.y() vector.w() \endcode\code matrix(i,j) -\endcodeRange checking is disabled if \n NDEBUG or EIGEN_NO_DEBUG is defined +\endcodeRange checking is disabled if \n NDEBUG or EIGEN_NO_DEBUG is defined Coeff access without \n range checking \code @@ -190,7 +189,7 @@ matrix.coeffRef(i,j) \code object = expression; object_of_float = expression_of_double.cast(); -\endcodethe destination is automatically resized (if possible) +\endcodethe destination is automatically resized (if possible) @@ -289,27 +288,27 @@ VectorXf::Unit(4,1) == Vector4f(0,1,0,0) -\subsection QuickRef_Map Map +\subsection QuickRef_Map Mapping external arrays - + - +
Contiguous memoryContiguous \n memory \code float data[] = {1,2,3,4}; -Map v1(data); // uses v1 as a Vector3f object -Map v2(data,3); // uses v2 as a ArrayXf object -Map m1(data); // uses m1 as a Array22f object -Map m2(data,2,2); // uses m2 as a MatrixXf object +Map v1(data); // uses v1 as a Vector3f object +Map v2(data,3); // uses v2 as a ArrayXf object +Map m1(data); // uses m1 as a Array22f object +Map m2(data,2,2); // uses m2 as a MatrixXf object \endcode
Typical usage of stridesTypical usage \n of strides \code float data[] = {1,2,3,4,5,6,7,8,9}; -Map > v1(data,3); // == [1,3,5] -Map > v2(data,3,InnerStride<>(3)); // == [1,4,7] -Map > m1(data,2,3,OuterStride<>(3)); // == |1,4,7| -Map > m2(data,2,3); // |2,5,8| +Map > v1(data,3); // = [1,3,5] +Map > v2(data,3,InnerStride<>(3)); // = [1,4,7] +Map > m2(data,2,3); // both lines |1,4,7| +Map > m1(data,2,3,OuterStride<>(3)); // are equal to: |2,5,8| \endcode
@@ -320,32 +319,32 @@ Map > m2(data,2,3); // |2,5,8| @@ -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 \endcode -
-add/subtract\code -mat3 = mat1 + mat2; mat3 += mat1; -mat3 = mat1 - mat2; mat3 -= mat1;\endcode +add \n subtract\code +mat3 = mat1 + mat2; mat3 += mat1; +mat3 = mat1 - mat2; mat3 -= mat1;\endcode
scalar product\code -mat3 = mat1 * s1; mat3 = s1 * mat1; mat3 *= s1; -mat3 = mat1 / s1; mat3 /= s1;\endcode +mat3 = mat1 * s1; mat3 *= s1; mat3 = s1 * mat1; +mat3 = mat1 / s1; mat3 /= s1;\endcode
-matrix/vector product \matrixworld\code +matrix/vector \n products \matrixworld\code col2 = mat1 * col1; -row2 = row1 * mat1; row1 *= mat1; -mat3 = mat1 * mat2; mat3 *= mat1; \endcode +row2 = row1 * mat1; row1 *= mat1; +mat3 = mat1 * mat2; mat3 *= mat1; \endcode
-transpose et adjoint \matrixworld\code +transposition \n adjoint \matrixworld\code mat1 = mat2.transpose(); mat1.transposeInPlace(); mat1 = mat2.adjoint(); mat1.adjointInPlace(); \endcode
-\link MatrixBase::dot() dot \endlink \& inner products \matrixworld\code +\link MatrixBase::dot() dot \endlink product \n inner product \matrixworld\code +scalar = vec1.dot(vec2); scalar = col1.adjoint() * col2; -scalar = (col1.adjoint() * col2).value(); -scalar = vec1.dot(vec2);\endcode +scalar = (col1.adjoint() * col2).value();\endcode
outer product \matrixworld\code @@ -353,7 +352,7 @@ mat = col1 * col2.transpose();\endcode
-\link MatrixBase::norm() norm \endlink and \link MatrixBase::normalized() normalization \endlink \matrixworld\code +\link MatrixBase::norm() norm \endlink \n \link MatrixBase::normalized() normalization \endlink \matrixworld\code scalar = vec1.norm(); scalar = vec1.squaredNorm() vec2 = vec1.normalized(); vec1.normalize(); // inplace \endcode
Special functions \n and STL variants\code +
Trigo, power, and \n misc functions \n and the STL variants\code array1.min(array2) std::min(array1,array2) array1.max(array2) std::max(array1,array2) array1.abs2() @@ -424,7 +423,8 @@ array1.tan() std::tan(array1) Eigen provides several reduction methods such as: \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 DenseBase::all() all() \endlink \redstar,and \link DenseBase::any() any() \endlink \redstar. All reduction operations can be done matrix-wise, @@ -444,14 +444,21 @@ mat = 2 7 8 \endcode
-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. - -\b Side \b note: The all() and any() functions are especially useful in combination with coeff-wise comparison operators. - +Special versions of \link DenseBase::minCoeff(int*,int*) minCoeff \endlink and \link DenseBase::maxCoeff(int*,int*) maxCoeff \endlink: +\code +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 -top\section QuickRef_Blocks Matrix blocks +top\section QuickRef_Blocks Sub-matrices Read-write access to a \link DenseBase::col(int) column \endlink or a \link DenseBase::row(int) row \endlink of a matrix (or array): @@ -501,7 +508,7 @@ Read-write access to sub-matrices: mat1.bottomRows() mat1.leftCols() mat1.rightCols()\endcode - specialized versions of block() when the block fit two corners + specialized versions of block() \n when the block fit two corners @@ -514,7 +521,7 @@ Read-write access to sub-matrices: - + @@ -545,13 +552,12 @@ mat3 = mat1 * diag1.inverse() \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 -used to store other information. +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.
-\link MatrixBase::asDiagonal() make a diagonal matrix \endlink \n from a vector \code +view a vector \link MatrixBase::asDiagonal() as a diagonal matrix \endlink \n \code mat1 = vec1.asDiagonal();\endcode
@@ -522,13 +529,13 @@ Declare a diagonal matrix\code DiagonalMatrix diag1(size); diag1.diagonal() = vector;\endcode
Access \link MatrixBase::diagonal() the diagonal and super/sub diagonals of a matrix \endlink as a vector (read/write)
Access the \link MatrixBase::diagonal() diagonal \endlink and \link MatrixBase::diagonal(int) super/sub diagonals \endlink of a matrix as a vector (read/write) \code -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 sub 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(); 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 sub diagonal +vec1 = mat1.diagonal<1>(); mat1.diagonal<1>() = vec1; // first super diagonal +vec1 = mat1.diagonal<-2>(); mat1.diagonal<-2>() = vec1; // second sub diagonal \endcode
-Reference a read/write triangular part of a given \n -matrix (or expression) m with optional unit diagonal: +Reference to a triangular with optional \n +unit or null diagonal (read/write): \code m.triangularView() \endcode \n @@ -574,19 +580,21 @@ m3 += s1 * m1.adjoint().triangularView() * m2 m3 -= s1 * m2.conjugate() * m1.adjoint().triangularView() \endcode
-Solving linear equations:\n(\f$ m_2 := m_1^{-1} m_2 \f$) -\code -m1.triangularView().solveInPlace(m2) -m1.adjoint().triangularView().solveInPlace(m2)\endcode +Solving linear equations:\n +\f$ M_2 := L_1^{-1} M_2 \f$ \n +\f$ M_3 := {L_1^*}^{-1} M_3 \f$ \n +\f$ M_4 := M_3 U_1^{-1} \f$ +\n \code +L1.triangularView().solveInPlace(M2) +L1.triangularView().adjoint().solveInPlace(M3) +U1.triangularView().solveInPlace(M4)\endcode
- - \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 -matrix and perform special and optimized operations. Again the opposite triangular is never referenced and can be +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 part is never referenced and can be used to store other information. @@ -602,26 +610,26 @@ m3 = s1 * m1.conjugate().selfadjointView() * m3; m3 -= s1 * m3.adjoint() * m1.selfadjointView();\endcode
-Rank 1 and rank K update: -\code -// fast version of m1 += s1 * m2 * m2.adjoint(): -m1.selfadjointView().rankUpdate(m2,s1); -// fast version of m1 -= m2.adjoint() * m2: +Rank 1 and rank K update: \n +\f$ upper(M_1) += s1 M_2^* M_2 \f$ \n +\f$ lower(M_1) -= M_2 M_2^* \f$ +\n \code +M1.selfadjointView().rankUpdate(M2,s1); m1.selfadjointView().rankUpdate(m2.adjoint(),-1); \endcode
-Rank 2 update: (\f$ m += s u v^* + s v u^* \f$) +Rank 2 update: (\f$ M += s u v^* + s v u^* \f$) \code -m.selfadjointView().rankUpdate(u,v,s); +M.selfadjointView().rankUpdate(u,v,s); \endcode
-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$) \code // via a standard Cholesky factorization -m1.selfadjointView().llt().solveInPlace(m2); +m2 = m1.selfadjointView().llt().solve(m2); // via a Cholesky factorization with pivoting -m1.selfadjointView().ldlt().solveInPlace(m2); +m2 = m1.selfadjointView().ldlt().solve(m2); \endcode
-- cgit v1.2.3