Matrix (version 1.5-1)

BunchKaufman-methods: Bunch-Kaufman Decomposition Methods

Description

The Bunch-Kaufman Decomposition of a square symmetric matrix \(A\) is \(A = P LDL' P'\) where \(P\) is a permutation matrix, \(L\) is unit-lower triangular and \(D\) is block-diagonal with blocks of dimension \(1\times 1\) or \(2\times2\).

This is generalization of a pivoting \(LDL'\) Cholesky decomposition.

Usage

# S4 method for dsyMatrix
BunchKaufman(x, ...)
# S4 method for dspMatrix
BunchKaufman(x, ...)
# S4 method for matrix
BunchKaufman(x, uplo = NULL, ...)

Value

an object of class BunchKaufman, which can also be used as a (triangular) matrix directly. Somewhat amazingly, it inherits its uplo slot from x.

Arguments

x

a symmetric square matrix.

uplo

optional string, "U" or "L" indicating which “triangle” half of x should determine the result. The default is "U" unless x has a uplo slot which is the case for those inheriting from class symmetricMatrix, where x@uplo will be used.

...

potentially further arguments passed to methods.

Methods

Currently, only methods for dense numeric symmetric matrices are implemented. To compute the Bunch-Kaufman decomposition, the methods use either one of two Lapack routines:

x = "dspMatrix"

routine dsptrf(); whereas

x = "dsyMatrix"

, and

x = "matrix"

use dsytrf().

Details

FIXME: We really need an expand() method in order to work with the result!

References

The original LAPACK source code, including documentation; https://netlib.org/lapack/double/dsytrf.f and https://netlib.org/lapack/double/dsptrf.f

See Also

The resulting class, BunchKaufman. Related decompositions are the LU, lu, and the Cholesky, chol (and for sparse matrices, Cholesky).

Examples

data(CAex)
dim(CAex)
isSymmetric(CAex)# TRUE
CAs <- as(CAex, "symmetricMatrix")
if(FALSE) # no method defined yet for *sparse* :
   bk. <- BunchKaufman(CAs)
## does apply to *dense* symmetric matrices:
bkCA <- BunchKaufman(as(CAs, "denseMatrix"))
bkCA
pkCA <- pack(bkCA)
stopifnot(is(bkCA, "triangularMatrix"),
          is(pkCA, "triangularMatrix"),
          is(pkCA, "packedMatrix"))

image(bkCA)# shows how sparse it is, too
str(R.CA <- as(bkCA, "sparseMatrix"))
## an upper triangular 72x72 matrix with only 144 non-zero entries
stopifnot(is(R.CA, "triangularMatrix"), is(R.CA, "CsparseMatrix"))