\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)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] a symmetric, positive definite matrix.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Note that only the upper triangular part of \code{x} is
used such that the above only holds when \code{x} \emph{is} symmetric.

If the matrix is not positive-definite an error is generated.
A non-negative definite but not strictly positive-definite matrix
may or may not give an error depending on the numerical errors.\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).\end{Value}
\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},
\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
\end{ExampleCode}
\end{Examples}

