# BunchKaufman-methods: Bunch-Kaufman Decomposition Methods In Matrix: Sparse and Dense Matrix Classes and 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 x 1 or 2 x 2.

This is generalization of a pivoting LDL' Cholesky decomposition.

## Usage

 ```1 2 3 4 5 6``` ```## S4 method for signature 'dsyMatrix' BunchKaufman(x, ...) ## S4 method for signature 'dspMatrix' BunchKaufman(x, ...) ## S4 method for signature 'matrix' BunchKaufman(x, uplo = NULL, ...) ```

## 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.

## Details

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

## 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`.

## 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()`.

## References

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

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

## Examples

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13``` ```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 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 ```

### Example output

```[1] 72 72
[1] TRUE
'Bunch-Kaufman' factorization of Formal class 'BunchKaufman' [package "Matrix"] with 6 slots
..@ perm    : int [1:72] 1 2 3 4 5 6 7 8 9 10 ...
..@ x       : num [1:5184] 4.16e-16 0.00 0.00 0.00 0.00 ...
..@ Dim     : int [1:2] 72 72
..@ Dimnames:List of 2
.. ..\$ : NULL
.. ..\$ : NULL
..@ uplo    : chr "U"
..@ diag    : chr "N"
Formal class 'dtCMatrix' [package "Matrix"] with 7 slots
..@ i       : int [1:144] 0 1 2 3 4 5 6 7 8 9 ...
..@ p       : int [1:73] 0 1 2 3 4 5 6 7 8 9 ...
..@ Dim     : int [1:2] 72 72
..@ Dimnames:List of 2
.. ..\$ : NULL
.. ..\$ : NULL
..@ x       : num [1:144] 4.16e-16 -7.77e-16 -4.16e-16 -2.78e-16 -5.00e-16 ...
..@ uplo    : chr "U"
..@ diag    : chr "N"
```

Matrix documentation built on June 11, 2021, 3 p.m.