BunchKaufman-class {Matrix} R Documentation

## Dense Bunch-Kaufman Factorizations

### Description

Classes BunchKaufman and pBunchKaufman represent Bunch-Kaufman factorizations of n \times n real, symmetric matrices A, having 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.

These classes store the nonzero entries of the 2 b_{U} + 1 or 2 b_{L} + 1 factors, which are individually sparse, in a dense format as a vector of length nn (BunchKaufman) or n(n+1)/2 (pBunchKaufman), the latter giving the “packed” representation.

### Slots

Dim, Dimnames

inherited from virtual class MatrixFactorization.

uplo

a string, either "U" or "L", indicating which triangle (upper or lower) of the factorized symmetric matrix was used to compute the factorization and in turn how the x slot is partitioned.

x

a numeric vector of length n*n (BunchKaufman) or n*(n+1)/2 (pBunchKaufman), where n=Dim. The details of the representation are specified by the manual for LAPACK routines dsytrf and dsptrf.

perm

an integer vector of length n=Dim specifying row and column interchanges as described in the manual for LAPACK routines dsytrf and dsptrf.

### Extends

Class BunchKaufmanFactorization, directly. Class MatrixFactorization, by class BunchKaufmanFactorization, distance 2.

### Instantiation

Objects can be generated directly by calls of the form new("BunchKaufman", ...) or new("pBunchKaufman", ...), but they are more typically obtained as the value of BunchKaufman(x) for x inheriting from dsyMatrix or dspMatrix.

### Methods

coerce

signature(from = "BunchKaufman", to = "dtrMatrix"): returns a dtrMatrix, useful for inspecting the internal representation of the factorization; see ‘Note’.

coerce

signature(from = "pBunchKaufman", to = "dtpMatrix"): returns a dtpMatrix, useful for inspecting the internal representation of the factorization; see ‘Note’.

determinant

signature(from = "p?BunchKaufman", logarithm = "logical"): computes the determinant of the factorized matrix A or its logarithm.

expand1

signature(x = "p?BunchKaufman"): see expand1-methods.

expand2

signature(x = "p?BunchKaufman"): see expand2-methods.

solve

signature(a = "p?BunchKaufman", b = .): see solve-methods.

### Note

In Matrix < 1.6-0, class BunchKaufman extended dtrMatrix and class pBunchKaufman extended dtpMatrix, reflecting the fact that the internal representation of the factorization is fundamentally triangular: there are n(n+1)/2 “parameters”, and these can be arranged systematically to form an n \times n triangular matrix. Matrix 1.6-0 removed these extensions so that methods would no longer be inherited from dtrMatrix and dtpMatrix. The availability of such methods gave the wrong impression that BunchKaufman and pBunchKaufman represent a (singular) matrix, when in fact they represent an ordered set of matrix factors.

The coercions as(., "dtrMatrix") and as(., "dtpMatrix") are provided for users who understand the caveats.

### 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. doi:10.56021/9781421407944

Class dsyMatrix and its packed counterpart.

Generic functions BunchKaufman, expand1, and expand2.

### Examples


showClass("BunchKaufman")
set.seed(1)

n <- 6L
(A <- forceSymmetric(Matrix(rnorm(n * n), n, n)))

## With dimnames, to see that they are propagated :
dimnames(A) <- rep.int(list(paste0("x", seq_len(n))), 2L)

(bk.A <- BunchKaufman(A))
str(e.bk.A <- expand2(bk.A, complete = FALSE), max.level = 2L)
str(E.bk.A <- expand2(bk.A, complete =  TRUE), max.level = 2L)

## Underlying LAPACK representation
(m.bk.A <- as(bk.A, "dtrMatrix"))
stopifnot(identical(as(m.bk.A, "matrix"), dim<-(bk.A@x, bk.A@Dim)))

## Number of factors is 2*b+1, b <= n, which can be nontrivial ...
(b <- (length(E.bk.A) - 1L) %/% 2L)

ae1 <- function(a, b, ...) all.equal(as(a, "matrix"), as(b, "matrix"), ...)
ae2 <- function(a, b, ...) ae1(unname(a), unname(b), ...)

## A ~ U DU U', U := prod(Pk Uk) in floating point
stopifnot(exprs = {
identical(names(e.bk.A), c("U", "DU", "U."))
identical(e.bk.A[["U" ]], Reduce(%*%, E.bk.A[seq_len(b)]))
identical(e.bk.A[["U."]], t(e.bk.A[["U"]]))
ae1(A, with(e.bk.A, U %*% DU %*% U.))
})

## Factorization handled as factorized matrix
b <- rnorm(n)
stopifnot(identical(det(A), det(bk.A)),
identical(solve(A, b), solve(bk.A, b)))


[Package Matrix version 1.6-3 Index]