chol
The Choleski Decomposition
Compute the Choleski factorization of a real symmetric positivedefinite square matrix.
Usage
chol(x, ...)
"chol"(x, pivot = FALSE, LINPACK = FALSE, tol = 1, ...)
Arguments
 x
 an object for which a method exists. The default method applies to numeric (or logical) symmetric, positivedefinite matrices.
 ...
 arguments to be based to or from methods.
 pivot
 Should pivoting be used?
 LINPACK
 logical. Should LINPACK be used (which is deprecated)?
 tol
 A numeric tolerance for use with
pivot = TRUE, LINPACK = FALSE)
.
Details
chol
is generic: the description here applies to the default
method.
Note that only the upper triangular part of x
is used, so
that $R'R = x$ when x
is symmetric.
If pivot = FALSE
and x
is not nonnegative definite an
error occurs. If x
is positive semidefinite (i.e., some zero
eigenvalues) an error will also occur as a numerical tolerance is used.
If pivot = TRUE
, then the Choleski decomposition of a positive
semidefinite x
can be computed. The rank of x
is
returned as attr(Q, "rank")
, subject to numerical errors.
The pivot is returned as attr(Q, "pivot")
. It is no longer
the case that t(Q) %*% Q
equals x
. However, setting
pivot < attr(Q, "pivot")
and oo < order(pivot)
, it
is true that t(Q[, oo]) %*% Q[, oo]
equals x
,
or, alternatively, t(Q) %*% Q
equals x[pivot,
pivot]
. See the examples.
Use of chol(pivot = FALSE, LINPACK = TRUE)
was deprecated in R
1.7.0. Pivoting with LAPACK requires LAPACK >= 3.2 and was added in R
2.15.2. The value of tol
is passed to LAPACK, with negative
values selecting the default tolerance of (usually) nrow(x) *
.Machine$double.neg.eps * max(diag(x)
. The algorithm terminates once
the pivot is less than tol
.
The LINPACK interface is restricted to matrices x
with less
than $2^31$ elements.
Value

The upper triangular factor of the Choleski decomposition, i.e., the
matrix $R$ such that $R'R = x$ (see example).If pivoting is used, then two additional attributes
"pivot"
and "rank"
are also returned.
Note
LINPACK = TRUE, pivot = FALSE
(for compatibility with R <
1.7.0) was formally deprecated in R 2.15.2.
Warning
The code does not check for symmetry. If pivot = TRUE
and x
is not nonnegative definite then
there will be a warning message but a meaningless result will occur.
So only use pivot = TRUE
when x
is nonnegative definite
by construction.
Source
This is an interface to the LAPACK routines DPOTRF
and
DPSTRF
and the LINPACK routines DPOFA
and DCHDC
. LAPACK and LINPACK are from http://www.netlib.org/lapack and
http://www.netlib.org/linpack and their guides are listed
in the references.
References
Anderson. E. and ten others (1999) LAPACK Users' Guide. Third Edition. SIAM. Available online at http://www.netlib.org/lapack/lug/lapack_lug.html.
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.
Dongarra, J. J., Bunch, J. R., Moler, C. B. and Stewart, G. W. (1978) LINPACK Users Guide. Philadelphia: SIAM Publications.
See Also
chol2inv
for its inverse (without pivoting),
backsolve
for solving linear systems with upper
triangular left sides.
Examples
library(base)
( m < matrix(c(5,1,1,3),2,2) )
( cm < chol(m) )
t(cm) %*% cm # = 'm'
crossprod(cm) # = 'm'
# now for something positive semidefinite
x < matrix(c(1:5, (1:5)^2), 5, 2)
x < cbind(x, x[, 1] + 3*x[, 2])
colnames(x) < letters[20:22]
m < crossprod(x)
qr(m)$rank # is 2, as it should be
# chol() may fail, depending on numerical rounding:
# chol() unlike qr() does not use a tolerance.
try(chol(m))
(Q < chol(m, pivot = TRUE))
## we can use this by
pivot < attr(Q, "pivot")
crossprod(Q[, order(pivot)]) # recover m
## now for a nonpositivedefinite matrix
( m < matrix(c(5,5,5,3), 2, 2) )
try(chol(m)) # fails
(Q < chol(m, pivot = TRUE)) # warning
crossprod(Q) # not equal to m