chol {Matrix} | R Documentation

## Choleski Decomposition - 'Matrix' S4 Generic

### Description

Compute the Choleski factorization of a real symmetric positive-definite square matrix.

### Usage

    chol(x, ...)
    ## S4 method for signature 'dsCMatrix'
    chol(x, pivot = FALSE, ...)

### Arguments

`x` | a (sparse or dense) square matrix, here inheriting from class `Matrix`; if `x` is not positive definite, an error is signalled.
`pivot` | logical indicating if pivoting is used.
`...` | potentially further arguments passed to methods.

### Value

a matrix of class `Cholesky`, i.e., upper triangular: R such that R'R = x.

### Methods

Use `showMethods(chol)` to see all; some are worth mentioning here:

chol

  `signature(x = "dgeMatrix")`: works via `"dpoMatrix"`, see class `dpoMatrix`.

chol

  `signature(x = "dpoMatrix")`: Returns (and stores) the Cholesky decomposition of `x`, via LAPACK routines `dlacpy` and `dpotrf`.

chol

  `signature(x = "dppMatrix")`: Returns (and stores) the Cholesky decomposition via LAPACK routine `dpptrf`.

chol

  `signature(x = "dsCMatrix", pivot = "logical")`: Returns (and stores) the Cholesky decomposition of `x`. If `pivot` is `TRUE` (the default) the Approximate Minimal Degree (AMD) algorithm is used to create a reordering of the rows and columns of `x` so as to reduce fill-in.

### References

Timothy A. Davis (2006) Direct Methods for Sparse Linear Systems, SIAM Series “Fundamentals of Algorithms”.

Tim Davis (1996), An approximate minimal degree ordering algorithm, SIAM J. Matrix Analysis and Applications, 17, 4, 886–905.

### See Also

The default from base, `chol`.

### Examples

    showMethods(chol, inherited = FALSE) # show different methods

    sy2 <- new("dsyMatrix", Dim = as.integer(c(2,2)), x = c(14, NA,32,77))
    (c2 <- chol(sy2))#-> "Cholesky" matrix
    stopifnot(all.equal(c2, chol(as(sy2, "dpoMatrix")), tol= 1e-13))
    str(c2)

    ## An example where chol() can't work
    (sy3 <- new("dsyMatrix", Dim = as.integer(c(2,2)), x = c(14, -1, 2, -7)))
    try(chol(sy3)) # error, since it is not positive definite

    ## A sparse example --- exemplifying 'pivot'
    (mm <- Matrix(toeplitz(c(10, 0, 1, 0, 3)), sparse = TRUE)) # 5 x 5
    (R <- chol(mm)) ## default:  pivot = FALSE
    R2 <- chol(mm, pivot=FALSE)
    stopifnot( identical(R, R2), all.equal(crossprod(R), mm) )
    (R. <- chol(mm, pivot=TRUE))# nice band structure,
    ## but of course crossprod(R.) is *NOT* equal to mm
    ## --> see Cholesky() and its examples, for the pivot structure & factorization
    stopifnot(all.equal(sqrt(det(mm)), det(R)),
              all.equal(prod(diag(R)), det(R)),
              all.equal(prod(diag(R.)), det(R)))

[Package Matrix version 1.0-9 Index]