From 2632b3446cf687e9e3feff2850d53f7928837474 Mon Sep 17 00:00:00 2001 From: Gael Guennebaud Date: Fri, 9 Oct 2015 12:10:58 +0200 Subject: [PATCH] Improve documentation of TriangularView. --- Eigen/src/Core/SolveTriangular.h | 28 ----------- Eigen/src/Core/TriangularMatrix.h | 81 ++++++++++++++++++++++++++----- Eigen/src/Core/util/Constants.h | 4 +- 3 files changed, 71 insertions(+), 42 deletions(-) diff --git a/Eigen/src/Core/SolveTriangular.h b/Eigen/src/Core/SolveTriangular.h index ded42e0e8..f8bb4b314 100644 --- a/Eigen/src/Core/SolveTriangular.h +++ b/Eigen/src/Core/SolveTriangular.h @@ -161,13 +161,6 @@ struct triangular_solver_selector { * TriangularView methods ***************************************************************************/ -/** "in-place" version of TriangularView::solve() where the result is written in \a other - * - * \warning The parameter is only marked 'const' to make the C++ compiler accept a temporary expression here. - * This function will const_cast it, so constness isn't honored here. - * - * See TriangularView:solve() for the details. - */ template template void TriangularViewImpl::solveInPlace(const MatrixBase& _other) const @@ -188,27 +181,6 @@ void TriangularViewImpl::solveInPlace(const MatrixBase template const internal::triangular_solve_retval,Other> diff --git a/Eigen/src/Core/TriangularMatrix.h b/Eigen/src/Core/TriangularMatrix.h index e9b34ebdf..438dd4dc9 100644 --- a/Eigen/src/Core/TriangularMatrix.h +++ b/Eigen/src/Core/TriangularMatrix.h @@ -222,18 +222,23 @@ template class TriangularView TriangularView& operator=(const TriangularView &other) { return Base::operator=(other); } + /** \copydoc EigenBase::rows() */ EIGEN_DEVICE_FUNC inline Index rows() const { return m_matrix.rows(); } + /** \copydoc EigenBase::cols() */ EIGEN_DEVICE_FUNC inline Index cols() const { return m_matrix.cols(); } + /** \returns a const reference to the nested expression */ EIGEN_DEVICE_FUNC const NestedExpression& nestedExpression() const { return m_matrix; } + + /** \returns a reference to the nested expression */ EIGEN_DEVICE_FUNC NestedExpression& nestedExpression() { return *const_cast(&m_matrix); } - /** \sa MatrixBase::conjugate() const */ typedef TriangularView ConjugateReturnType; + /** \sa MatrixBase::conjugate() const */ EIGEN_DEVICE_FUNC inline const ConjugateReturnType conjugate() const { return ConjugateReturnType(m_matrix.conjugate()); } @@ -279,19 +284,28 @@ template class TriangularView using Base::solve; #endif - EIGEN_DEVICE_FUNC - const SelfAdjointView selfadjointView() const - { - EIGEN_STATIC_ASSERT((Mode&UnitDiag)==0,PROGRAMMING_ERROR); - return SelfAdjointView(m_matrix); - } + /** \returns a selfadjoint view of the referenced triangular part which must be either \c #Upper or \c #Lower. + * + * This is a shortcut for \code this->nestedExpression().selfadjointView<(*this)::Mode>() \endcode + * \sa MatrixBase::selfadjointView() */ EIGEN_DEVICE_FUNC SelfAdjointView selfadjointView() { - EIGEN_STATIC_ASSERT((Mode&UnitDiag)==0,PROGRAMMING_ERROR); + EIGEN_STATIC_ASSERT((Mode&(UnitDiag|ZeroDiag))==0,PROGRAMMING_ERROR); return SelfAdjointView(m_matrix); } + /** This is the const version of selfadjointView() */ + EIGEN_DEVICE_FUNC + const SelfAdjointView selfadjointView() const + { + EIGEN_STATIC_ASSERT((Mode&(UnitDiag|ZeroDiag))==0,PROGRAMMING_ERROR); + return SelfAdjointView(m_matrix); + } + + + /** \returns the determinant of the triangular matrix + * \sa MatrixBase::determinant() */ EIGEN_DEVICE_FUNC Scalar determinant() const { @@ -341,12 +355,16 @@ template class TriangularViewImpl<_Mat Flags = internal::traits::Flags }; + /** \returns the outer-stride of the underlying dense matrix + * \sa DenseCoeffsBase::outerStride() */ EIGEN_DEVICE_FUNC inline Index outerStride() const { return derived().nestedExpression().outerStride(); } + /** \returns the inner-stride of the underlying dense matrix + * \sa DenseCoeffsBase::innerStride() */ EIGEN_DEVICE_FUNC inline Index innerStride() const { return derived().nestedExpression().innerStride(); } - /** \sa MatrixBase::operator+=() */ + /** \sa MatrixBase::operator+=() */ template EIGEN_DEVICE_FUNC TriangularViewType& operator+=(const DenseBase& other) { @@ -364,7 +382,7 @@ template class TriangularViewImpl<_Mat /** \sa MatrixBase::operator*=() */ EIGEN_DEVICE_FUNC TriangularViewType& operator*=(const typename internal::traits::Scalar& other) { return *this = derived().nestedExpression() * other; } - /** \sa MatrixBase::operator/=() */ + /** \sa DenseBase::operator/=() */ EIGEN_DEVICE_FUNC TriangularViewType& operator/=(const typename internal::traits::Scalar& other) { return *this = derived().nestedExpression() / other; } @@ -408,21 +426,26 @@ template class TriangularViewImpl<_Mat EIGEN_DEVICE_FUNC TriangularViewType& operator=(const TriangularBase& other); + /** Shortcut for\code *this = other.other.triangularView<(*this)::Mode>() \endcode */ template EIGEN_DEVICE_FUNC TriangularViewType& operator=(const MatrixBase& other); +#ifndef EIGEN_PARSED_BY_DOXYGEN EIGEN_DEVICE_FUNC TriangularViewType& operator=(const TriangularViewImpl& other) { return *this = other.derived().nestedExpression(); } + /** \deprecated */ template EIGEN_DEVICE_FUNC void lazyAssign(const TriangularBase& other); + /** \deprecated */ template EIGEN_DEVICE_FUNC - void lazyAssign(const MatrixBase& other); + void lazyAssign(const MatrixBase& other); +#endif /** Efficient triangular matrix times vector/matrix product */ template @@ -442,11 +465,39 @@ template class TriangularViewImpl<_Mat return Product(lhs.derived(),rhs.derived()); } + /** \returns the product of the inverse of \c *this with \a other, \a *this being triangular. + * + * This function computes the inverse-matrix matrix product inverse(\c *this) * \a other if + * \a Side==OnTheLeft (the default), or the right-inverse-multiply \a other * inverse(\c *this) if + * \a Side==OnTheRight. + * + * The matrix \c *this must be triangular and invertible (i.e., all the coefficients of the + * diagonal must be non zero). It works as a forward (resp. backward) substitution if \c *this + * is an upper (resp. lower) triangular matrix. + * + * Example: \include Triangular_solve.cpp + * Output: \verbinclude Triangular_solve.out + * + * This function returns an expression of the inverse-multiply and can works in-place if it is assigned + * to the same matrix or vector \a other. + * + * For users coming from BLAS, this function (and more specifically solveInPlace()) offer + * all the operations supported by the \c *TRSV and \c *TRSM BLAS routines. + * + * \sa TriangularView::solveInPlace() + */ template EIGEN_DEVICE_FUNC inline const internal::triangular_solve_retval solve(const MatrixBase& other) const; + /** "in-place" version of TriangularView::solve() where the result is written in \a other + * + * \warning The parameter is only marked 'const' to make the C++ compiler accept a temporary expression here. + * This function will const_cast it, so constness isn't honored here. + * + * See TriangularView:solve() for the details. + */ template EIGEN_DEVICE_FUNC void solveInPlace(const MatrixBase& other) const; @@ -456,15 +507,21 @@ template class TriangularViewImpl<_Mat void solveInPlace(const MatrixBase& other) const { return solveInPlace(other); } + /** Swaps the coefficients of the common triangular parts of two matrices */ template EIGEN_DEVICE_FUNC +#ifdef EIGEN_PARSED_BY_DOXYGEN + void swap(TriangularBase &other) +#else void swap(TriangularBase const & other) +#endif { EIGEN_STATIC_ASSERT_LVALUE(OtherDerived); call_assignment(derived(), other.const_cast_derived(), internal::swap_assign_op()); } - // TODO: this overload is ambiguous and it should be deprecated (Gael) + /** \deprecated + * Shortcut for \code (*this).swap(other.triangularView<(*this)::Mode>()) \endcode */ template EIGEN_DEVICE_FUNC void swap(MatrixBase const & other) diff --git a/Eigen/src/Core/util/Constants.h b/Eigen/src/Core/util/Constants.h index 8fcde07d3..ddb1cf6f4 100644 --- a/Eigen/src/Core/util/Constants.h +++ b/Eigen/src/Core/util/Constants.h @@ -189,8 +189,8 @@ const unsigned int HereditaryBits = RowMajorBit */ /** \ingroup enums - * Enum containing possible values for the \p Mode parameter of - * MatrixBase::selfadjointView() and MatrixBase::triangularView(). */ + * Enum containing possible values for the \c Mode or \c UpLo parameter of + * MatrixBase::selfadjointView() and MatrixBase::triangularView(), and selfadjoint solvers. */ enum { /** View matrix as a lower triangular matrix. */ Lower=0x1,