Eigen: Eigen::BunchKaufman< MatrixType_, UpLo

Searching...

No Matches

#include <Eigen/src/Cholesky/BunchKaufman.h>

Detailed Description

template<typename MatrixType_, int UpLo_>
class Eigen::BunchKaufman< MatrixType_, UpLo_ >

Bunch-Kaufman factorization of a symmetric / Hermitian indefinite matrix.

Template Parameters

MatrixType_	the type of the matrix of which to compute the Bunch-Kaufman factorization
UpLo_	the triangular part that will be used for the decomposition: Lower (default) or Upper. The other triangular part won't be read.

Perform a symmetric-indefinite factorization of a real symmetric or complex Hermitian matrix \( A \) using the Bunch-Kaufman diagonal pivoting method, such that \( P A P^T = L D L^* \) (or \( P A P^T = U^* D U \) for the upper variant), where \( P \) is a permutation matrix, \( L \) is unit lower triangular and \( D \) is block diagonal with 1x1 and 2x2 diagonal blocks.

Unlike LLT and LDLT, this factorization is numerically stable (backward stable, with a bounded element-growth factor) for indefinite symmetric / Hermitian matrices. It is the dense analog of LAPACK's xSYTRF / xHETRF routines. For positive- or negative-(semi)definite matrices LLT / LDLT are cheaper and should be preferred.

The diagonal-pivoting threshold \( \alpha = (1+\sqrt{17})/8 \) and the pivot-selection logic follow:

J. R. Bunch and L. Kaufman, "Some stable methods for calculating inertia and solving symmetric linear systems", Math. Comp. 31 (1977), pp. 163-179.
G. H. Golub and C. F. Van Loan, "Matrix Computations", 4th ed., section 4.4.
N. J. Higham, "Accuracy and Stability of Numerical Algorithms", 2nd ed., chapter 11.

The blocked (level-3 BLAS) variant follows the panel/trailing-update structure of LAPACK's xSYTRF / xLASYF.

This factorization also reveals the inertia of \( A \) (the number of positive, negative and zero eigenvalues) by Sylvester's law of inertia, accessible through isPositive() / isNegative().

This class supports the inplace decomposition mechanism.

See also: MatrixBase::bunchKaufman(), SelfAdjointView::bunchKaufman(), class LDLT, class LLT

Inheritance diagram for Eigen::BunchKaufman< MatrixType_, UpLo_ >:

Public Member Functions
RealScalar	absDeterminant () const

const BunchKaufman &	adjoint () const

	BunchKaufman ()
	Default Constructor.

template<typename InputType>
	BunchKaufman (const EigenBase< InputType > &matrix)
	Constructor with decomposition.

template<typename InputType>
	BunchKaufman (EigenBase< InputType > &matrix)
	Constructs a Bunch-Kaufman factorization from a given matrix.

	BunchKaufman (Index size)
	Default Constructor with memory preallocation.

template<typename InputType>
BunchKaufman< MatrixType, UpLo_ > &	compute (const EigenBase< InputType > &a)

Scalar	determinant () const

ComputationInfo	info () const
	Reports whether previous computation was successful.

bool	isNegative () const

bool	isPositive () const

RealScalar	logAbsDeterminant () const

Traits::MatrixL	matrixL () const

const MatrixType &	matrixLDLT () const

Traits::MatrixU	matrixU () const

RealScalar	rcond () const

MatrixType	reconstructedMatrix () const

Scalar	signDeterminant () const

template<typename Rhs>
Solve< BunchKaufman, Rhs >	solve (const MatrixBase< Rhs > &b) const

const TmpVectorType &	subDiagonal () const

const TranspositionType &	transpositionsP () const

Diagonal< const MatrixType >	vectorD () const

Public Member Functions inherited from Eigen::SolverBase< BunchKaufman< MatrixType_, UpLo_ > >
const AdjointReturnType	adjoint () const

constexpr BunchKaufman< MatrixType_, UpLo_ > &	derived ()

constexpr const BunchKaufman< MatrixType_, UpLo_ > &	derived () const

Solve< BunchKaufman< MatrixType_, UpLo_ >, Rhs >	solve (const MatrixBase< Rhs > &b) const

	SolverBase ()=default

const ConstTransposeReturnType	transpose () const

Public Member Functions inherited from Eigen::EigenBase< BunchKaufman< MatrixType_, UpLo_ > >
constexpr Index	cols () const noexcept

constexpr BunchKaufman< MatrixType_, UpLo_ > &	derived ()

constexpr const BunchKaufman< MatrixType_, UpLo_ > &	derived () const

constexpr Index	rows () const noexcept

constexpr Index	size () const noexcept

Additional Inherited Members
Public Types inherited from Eigen::EigenBase< BunchKaufman< MatrixType_, UpLo_ > >
using	Index
	The interface type of indices.

Constructor & Destructor Documentation

◆ BunchKaufman() [1/4]

template<typename MatrixType_, int UpLo_>

Eigen::BunchKaufman< MatrixType_, UpLo_ >::BunchKaufman ( )

inline

Default Constructor.

The default constructor is useful in cases in which the user intends to perform decompositions via BunchKaufman::compute(const MatrixType&).

◆ BunchKaufman() [2/4]

template<typename MatrixType_, int UpLo_>

Eigen::BunchKaufman< MatrixType_, UpLo_ >::BunchKaufman ( Index size )

inlineexplicit

Default Constructor with memory preallocation.

Like the default constructor but with preallocation of the internal data according to the specified problem size.

See also: BunchKaufman()

◆ BunchKaufman() [3/4]

template<typename MatrixType_, int UpLo_>

template<typename InputType>

Eigen::BunchKaufman< MatrixType_, UpLo_ >::BunchKaufman ( const EigenBase< InputType > & matrix )

inlineexplicit

Constructor with decomposition.

This calculates the decomposition for the input matrix.

See also: BunchKaufman(Index size)

◆ BunchKaufman() [4/4]

template<typename MatrixType_, int UpLo_>

template<typename InputType>

Eigen::BunchKaufman< MatrixType_, UpLo_ >::BunchKaufman ( EigenBase< InputType > & matrix )

inlineexplicit

Constructs a Bunch-Kaufman factorization from a given matrix.

This overloaded constructor is provided for inplace decomposition when MatrixType is a Eigen::Ref.

See also: BunchKaufman(const EigenBase&)

Member Function Documentation

◆ absDeterminant()

template<typename MatrixType, int UpLo_>

BunchKaufman< MatrixType, UpLo_ >::RealScalar Eigen::BunchKaufman< MatrixType, UpLo_ >::absDeterminant ( ) const

Returns: the absolute value of the determinant of the matrix of which *this is the Bunch-Kaufman decomposition.

It has only linear complexity (that is, O(n) where n is the dimension of the square matrix) as the decomposition has already been computed.

Warning: a determinant can be very big or small, so for matrices of large enough dimension, there is a risk of overflow/underflow. One way to work around that is to use logAbsDeterminant() instead.

See also: determinant(), logAbsDeterminant(), signDeterminant(), MatrixBase::determinant()

◆ adjoint()

template<typename MatrixType_, int UpLo_>

const BunchKaufman & Eigen::BunchKaufman< MatrixType_, UpLo_ >::adjoint ( ) const

inline

Returns: the adjoint of *this, that is, a const reference to the decomposition itself as the underlying matrix is self-adjoint.

This method is provided for compatibility with other matrix decompositions, thus enabling generic code such as:

x = decomposition.adjoint().solve(b)

◆ compute()

template<typename MatrixType_, int UpLo_>

template<typename InputType>

BunchKaufman< MatrixType, UpLo_ > & Eigen::BunchKaufman< MatrixType_, UpLo_ >::compute ( const EigenBase< InputType > & a )

Compute / recompute the Bunch-Kaufman factorization \( P A P^T = L D L^* \) (or \( U^* D U \) for the upper variant) of a.

◆ determinant()

template<typename MatrixType, int UpLo_>

BunchKaufman< MatrixType, UpLo_ >::Scalar Eigen::BunchKaufman< MatrixType, UpLo_ >::determinant ( ) const

Returns: the determinant of the matrix of which *this is the Bunch-Kaufman decomposition.

It has only linear complexity (that is, O(n) where n is the dimension of the square matrix) as the decomposition has already been computed.

Warning: a determinant can be very big or small, so for matrices of large enough dimension, there is a risk of overflow/underflow. One way to work around that is to use logAbsDeterminant() and signDeterminant() instead. Also, do not rely on the determinant being exactly zero for testing singularity or rank-deficiency.

See also: absDeterminant(), logAbsDeterminant(), signDeterminant(), MatrixBase::determinant()

◆ info()

template<typename MatrixType_, int UpLo_>

ComputationInfo Eigen::BunchKaufman< MatrixType_, UpLo_ >::info ( ) const

inline

Reports whether previous computation was successful.

Returns: Success if computation was successful, NumericalIssue if the factorization failed because of a zero pivot (the matrix is singular) or because a 2x2 pivot block has no representable inverse (a NaN entry, or an off-diagonal so much smaller than the diagonal that the scaled inverse overflows).

◆ isNegative()

template<typename MatrixType_, int UpLo_>

bool Eigen::BunchKaufman< MatrixType_, UpLo_ >::isNegative ( ) const

inline

Returns: true if the matrix is negative semidefinite (has no strictly positive eigenvalues).

◆ isPositive()

template<typename MatrixType_, int UpLo_>

bool Eigen::BunchKaufman< MatrixType_, UpLo_ >::isPositive ( ) const

inline

Returns: true if the matrix is positive semidefinite (has no strictly negative eigenvalues).

◆ logAbsDeterminant()

template<typename MatrixType, int UpLo_>

BunchKaufman< MatrixType, UpLo_ >::RealScalar Eigen::BunchKaufman< MatrixType, UpLo_ >::logAbsDeterminant ( ) const

Returns: the natural log of the absolute value of the determinant of the matrix of which *this is the Bunch-Kaufman decomposition.

It has only linear complexity (that is, O(n) where n is the dimension of the square matrix) as the decomposition has already been computed.

Note: This method is useful to work around the risk of overflow/underflow that's inherent to determinant computation. The 2x2 blocks of D are scaled by their off-diagonal entry before their determinant is formed, so a block whose own determinant is out of range still contributes a finite term.

See also: determinant(), absDeterminant(), signDeterminant(), MatrixBase::determinant()

◆ matrixL()

template<typename MatrixType_, int UpLo_>

Traits::MatrixL Eigen::BunchKaufman< MatrixType_, UpLo_ >::matrixL ( ) const

inline

Returns: a view of the unit lower triangular matrix L

◆ matrixLDLT()

template<typename MatrixType_, int UpLo_>

const MatrixType & Eigen::BunchKaufman< MatrixType_, UpLo_ >::matrixLDLT ( ) const

inline

Returns: the internal Bunch-Kaufman decomposition matrix

The strictly lower (resp. upper) triangular part holds the unit triangular factor L (resp. U); the diagonal holds the main diagonal of D. The sub/super-diagonal entries of the 2x2 blocks of D are stored separately, in subDiagonal().

◆ matrixU()

template<typename MatrixType_, int UpLo_>

Traits::MatrixU Eigen::BunchKaufman< MatrixType_, UpLo_ >::matrixU ( ) const

inline

Returns: a view of the unit upper triangular matrix U

◆ rcond()

template<typename MatrixType_, int UpLo_>

RealScalar Eigen::BunchKaufman< MatrixType_, UpLo_ >::rcond ( ) const

inline

Returns: an estimate of the reciprocal condition number of the matrix of which *this is the Bunch-Kaufman decomposition.

◆ reconstructedMatrix()

template<typename MatrixType, int UpLo_>

MatrixType Eigen::BunchKaufman< MatrixType, UpLo_ >::reconstructedMatrix ( ) const

Returns: the matrix represented by the decomposition, i.e., the product \( P^T L D L^* P \). This function is provided for debug purposes.

◆ signDeterminant()

template<typename MatrixType, int UpLo_>

BunchKaufman< MatrixType, UpLo_ >::Scalar Eigen::BunchKaufman< MatrixType, UpLo_ >::signDeterminant ( ) const

Returns: the sign of the determinant of the matrix of which *this is the Bunch-Kaufman decomposition, that is, 1, -1, or 0 if the matrix is singular.

The sign is read off the inertia rather than computed from a product, so it is exact and cannot overflow: \( \mathrm{sign}(\det A) = (-1)^{n_-} \), with \( n_- \) the number of negative eigenvalues, which congruence leaves invariant (Sylvester's law of inertia).

See also: determinant(), absDeterminant(), logAbsDeterminant(), MatrixBase::determinant()

◆ solve()

template<typename MatrixType_, int UpLo_>

template<typename Rhs>

Solve< BunchKaufman, Rhs > Eigen::BunchKaufman< MatrixType_, UpLo_ >::solve ( const MatrixBase< Rhs > & b ) const

inline

Returns: a solution x of \( A x = b \) using the current decomposition of A.

This function also supports in-place solves using the syntax x = decompositionObject.solve(x) .

This method just tries to find as good a solution as possible. If you want to check whether a solution exists or if it is accurate, just call this function to get a result and then compute the error of this result, or use MatrixBase::isApprox() directly, for instance like this:

bool a_solution_exists = (A*result).isApprox(b, precision);

This method avoids dividing by zero, so that the non-existence of a solution doesn't by itself mean that you'll get inf or nan values.

See also: MatrixBase::bunchKaufman(), SelfAdjointView::bunchKaufman()

◆ subDiagonal()

template<typename MatrixType_, int UpLo_>

const TmpVectorType & Eigen::BunchKaufman< MatrixType_, UpLo_ >::subDiagonal ( ) const

inline

Returns: the sub-diagonal of the block-diagonal matrix D.

Entry k is non-zero if and only if a 2x2 diagonal block of D occupies rows/columns k and k+1; it then holds \( D_{k+1,k} \). All other entries are zero.

See also: vectorD()

◆ transpositionsP()

template<typename MatrixType_, int UpLo_>

const TranspositionType & Eigen::BunchKaufman< MatrixType_, UpLo_ >::transpositionsP ( ) const

inline

Returns: the permutation matrix P as a transposition sequence.

◆ vectorD()

template<typename MatrixType_, int UpLo_>

Diagonal< const MatrixType > Eigen::BunchKaufman< MatrixType_, UpLo_ >::vectorD ( ) const

inline

Returns: the main diagonal of the block-diagonal matrix D.

The block-diagonal matrix D is fully described by vectorD() (its main diagonal) together with subDiagonal() (the sub-diagonal entries of its 2x2 blocks).

The documentation for this class was generated from the following file:

/builds/libeigen/eigen/Eigen/src/Cholesky/BunchKaufman.h

Detailed Description

Public Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ BunchKaufman() [1/4]

◆ BunchKaufman() [2/4]

◆ BunchKaufman() [3/4]

◆ BunchKaufman() [4/4]

Member Function Documentation

◆ absDeterminant()

◆ adjoint()

◆ compute()

◆ determinant()

◆ info()

◆ isNegative()

◆ isPositive()

◆ logAbsDeterminant()

◆ matrixL()

◆ matrixLDLT()

◆ matrixU()

◆ rcond()

◆ reconstructedMatrix()

◆ signDeterminant()

◆ solve()

◆ subDiagonal()

◆ transpositionsP()

◆ vectorD()