\Header{chol}{The Choleski Decomposition}
\keyword{algebra}{chol}
\keyword{array}{chol}
\begin{Usage}
\begin{verbatim}
chol(x)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\texttt{x}] a symmetric positive-definite matrix.
\end{ldescription}
\end{Arguments}
\begin{Value}
This function computes the Choleski factorization
of the square matrix \texttt{x}.  It returns the upper triangular
factor of the decomposition, i.e., the matrix \eqn{R}{} such that
\eqn{R'R = x}{} (see example).

Note that effectively, only the upper triangular part of \texttt{x} is
used such that the above only holds when \texttt{x} \emph{is} symmetric.\end{Value}
\begin{References}
Dongarra, J. J., J. R. Bunch, C. B. Moler and G. W. Stewart (1978).
\emph{LINPACK Users Guide}.  Philadelphia: SIAM Publications.\end{References}
\begin{SeeAlso}
\texttt{\Link{chol2inv}} for its \emph{inverse},
\texttt{\Link{backsolve}} for solving linear systems with upper
triangular left sides.

\texttt{\Link{qr}}, \texttt{\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}

