\Header{chol}{The Choleski Decomposition}
\keyword{algebra}{chol}
\keyword{array}{chol}
\begin{Description}\relax
Compute the Choleski factorization of a symmetric (Hermitian),
positive definite square matrix.\end{Description}
\begin{Usage}
\begin{verbatim}
chol(x, pivot = FALSE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] a symmetric, positive definite matrix
\item[\code{pivot}] Should pivoting be used?
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Note that only the upper triangular part of \code{x} is used, so
that \eqn{R'R = x}{} when \code{x} is symmetric.

If \code{pivot = FALSE} and \code{x} is not non-negative definite an
error occurs.  If \code{x} is positive semi-definite (i.e. some zero
eigenvalues) an error may or may not occur, depending on
finite precision numerical errors.

If \code{pivot = TRUE}, then the Choleski decomposition of a positive
semi-definite \code{x} can be computed.  The rank of \code{x} is
returned as \code{attr(Q, "rank")}, subject to numerical errors.
The pivot is returned as \code{attr(Q, "pivot")}.  It is no longer
the case that \code{t(Q) \%*\% Q} equals \code{x}.  However, setting
\code{pivot <- attr(Q, "pivot")} and \code{oo <- order(pivot)}, it
is true that \code{t(Q[, oo]) \%*\% Q[, oo]} equals \code{x},
or, alternatively, \code{t(Q) \%*\% Q} equals \code{x[pivot,
  pivot]}.  See the examples.\end{Details}
\begin{Value}
The upper triangular factor of the Choleski decomposition, i.e., the
matrix \eqn{R}{} such that \eqn{R'R = x}{} (see example).

If pivoting is used, then two additional attributes
\code{"pivot"} and \code{"rank"} are also returned.\end{Value}
\begin{Section}{Warning}
The code does not check for symmetry or for non-negative
definiteness.  If \code{pivot = TRUE} and \code{x} is not non-negative
definite then there will be no error message but a meaningless
result will occur.  So only use \code{pivot = TRUE} when \code{x} is
non-negative definite by construction.\end{Section}
\begin{References}\relax
Dongarra, J. J., Bunch, J. R., Moler, C. B. and Stewart, G. W. (1978)
\emph{LINPACK Users Guide.}  Philadelphia: SIAM Publications.\end{References}
\begin{SeeAlso}\relax
\code{\Link{chol2inv}} for its \emph{inverse} (without pivoting),
\code{\Link{backsolve}} for solving linear systems with upper
triangular left sides.

\code{\Link{qr}}, \code{\Link{svd}} for related matrix factorizations.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
( m <- matrix(c(5,1,1,3),2,2) )
( cm <- chol(m) )
t(cm) %*% cm  #-- = 'm'
all(abs(m  -  t(cm) %*% cm) < 100* .Machine$double.eps) # TRUE


x <- matrix(c(1:5, (1:5)^2), 5, 2)
m <- crossprod(x)
Q <- chol(m)
all.equal(t(Q) %*% Q, m) # TRUE

Q <- chol(m, pivot = TRUE)
pivot <- attr(Q, "pivot")
oo <- order(pivot)
all.equal(t(Q[, oo]) %*% Q[, oo], m) # TRUE
all.equal(t(Q) %*% Q, m[pivot, pivot]) # TRUE

# now for something positive semi-definite
x <- cbind(x, x[, 1]+3*x[, 2])
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.
test <- try(Q <- chol(m))     

(Q <- chol(m, pivot = TRUE)) # NB wrong rank here ... you have been warned!
pivot <- attr(Q, "pivot")
oo <- order(pivot)
all.equal(t(Q[, oo]) %*% Q[, oo], m) # TRUE
all.equal(t(Q) %*% Q, m[pivot, pivot]) # TRUE
\end{ExampleCode}
\end{Examples}

