BunchKaufman-methods: Methods for Bunch-Kaufman Factorization

Description

Computes the Bunch-Kaufman factorization of an $n \times n$ real, symmetric matrix $A$, which has the general form $$A = U D_{U} U' = L D_{L} L'$$ where $D_{U}$ and $D_{L}$ are symmetric, block diagonal matrices composed of $b_{U}$ and $b_{L}$ $1 \times 1$ or $2 \times 2$ diagonal blocks; $U = \prod_{k = 1}^{b_{U}} P_{k} U_{k}$ is the product of $b_{U}$ row-permuted unit upper triangular matrices, each having nonzero entries above the diagonal in 1 or 2 columns; and $L = \prod_{k = 1}^{b_{L}} P_{k} L_{k}$ is the product of $b_{L}$ row-permuted unit lower triangular matrices, each having nonzero entries below the diagonal in 1 or 2 columns.

Methods are built on LAPACK routines dsytrf and dsptrf.

Usage

BunchKaufman(x, ...)
# S4 method for dsyMatrix
BunchKaufman(x, warnSing = TRUE, ...)
# S4 method for dspMatrix
BunchKaufman(x, warnSing = TRUE, ...)
# S4 method for matrix
BunchKaufman(x, uplo = "U", ...)

Value

An object representing the factorization, inheriting from virtual class BunchKaufmanFactorization. The specific class is BunchKaufman unless

x inherits from virtual class packedMatrix, in which case it is pBunchKaufman.

Arguments

x: a finite symmetric matrix or Matrix to be factorized. If x is square but not symmetric, then it will be treated as symmetric; see uplo.
warnSing: a logical indicating if a warning should be signaled for singular x.
uplo: a string, either "U" or "L", indicating which triangle of x should be used to compute the factorization.
...: further arguments passed to or from methods.

References

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

Golub, G. H., & Van Loan, C. F. (2013). Matrix computations (4th ed.). Johns Hopkins University Press. tools:::Rd_expr_doi("10.56021/9781421407944")

Examples

Run this code

 
library(utils, pos = "package:base", verbose = FALSE)

showMethods("BunchKaufman", inherited = FALSE)
set.seed(0)

data(CAex, package = "Matrix")
class(CAex) # dgCMatrix
isSymmetric(CAex) # symmetric, but not formally

A <- as(CAex, "symmetricMatrix")
class(A) # dsCMatrix

## Have methods for denseMatrix (unpacked and packed),
## but not yet sparseMatrix ...
if (FALSE) {
(bk.A <- BunchKaufman(A))
}
(bk.A <- BunchKaufman(as(A, "unpackedMatrix")))

## A ~ U DU U' in floating point
str(e.bk.A <- expand2(bk.A), max.level = 2L)
stopifnot(all.equal(as(A, "matrix"), as(Reduce(`%*%`, e.bk.A), "matrix")))