\HeaderA{chol}{Choleski Decomposition - 'Matrix' S4 Generic}{chol}
\aliasA{chol,ddenseMatrix-method}{chol}{chol,ddenseMatrix.Rdash.method}
\aliasA{chol,ddiMatrix-method}{chol}{chol,ddiMatrix.Rdash.method}
\aliasA{chol,dgeMatrix-method}{chol}{chol,dgeMatrix.Rdash.method}
\aliasA{chol,dpoMatrix-method}{chol}{chol,dpoMatrix.Rdash.method}
\aliasA{chol,dppMatrix-method}{chol}{chol,dppMatrix.Rdash.method}
\aliasA{chol,dsCMatrix-method}{chol}{chol,dsCMatrix.Rdash.method}
\methaliasA{chol,dsCMatrix-method}{chol}{chol,dsCMatrix.Rdash.method}
\aliasA{chol,dsparseMatrix-method}{chol}{chol,dsparseMatrix.Rdash.method}
\aliasA{chol,ldiMatrix-method}{chol}{chol,ldiMatrix.Rdash.method}
\aliasA{chol,lsCMatrix-method}{chol}{chol,lsCMatrix.Rdash.method}
\methaliasA{chol,lsCMatrix-method}{chol}{chol,lsCMatrix.Rdash.method}
\aliasA{chol,Matrix-method}{chol}{chol,Matrix.Rdash.method}
\aliasA{chol,nsCMatrix-method}{chol}{chol,nsCMatrix.Rdash.method}
\methaliasA{chol,nsCMatrix-method}{chol}{chol,nsCMatrix.Rdash.method}
\aliasA{chol-methods}{chol}{chol.Rdash.methods}
\keyword{algebra}{chol}
\keyword{array}{chol}
\begin{Description}\relax
Compute the Choleski factorization of a real symmetric
positive-definite square matrix.
\end{Description}
\begin{Usage}
\begin{verbatim}
chol(x, ...)
## S4 method for signature 'dsCMatrix':
chol(x, pivot = FALSE, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] a (sparse or dense) square matrix, here inheriting from class
\code{\LinkA{Matrix}{Matrix.Rdash.class}}; if \code{x} is not positive definite,
an error is signalled.
\item[\code{pivot}] logical indicating if pivoting is used.
\item[\code{...}] potentially further arguments passed to methods.
\end{ldescription}
\end{Arguments}
\begin{Value}
a matrix of class \code{\LinkA{Cholesky}{Cholesky.Rdash.class}},
i.e., upper triangular: \eqn{R}{} such that \eqn{R R' = x}{}.
\end{Value}
\begin{Section}{Methods}
Use \code{\LinkA{showMethods}{showMethods}(chol)} to see all; some are worth
mentioning here:
\describe{
\item[chol] \code{signature(x = "dgeMatrix")}: works via
\code{"dpoMatrix"}, see class \code{\LinkA{dpoMatrix}{dpoMatrix.Rdash.class}}.

\item[chol] \code{signature(x = "dpoMatrix")}:
Returns (and stores) the Cholesky decomposition of \code{x}, via
LAPACK routines \code{dlacpy} and \code{dpotrf}.

\item[chol] \code{signature(x = "dppMatrix")}:
Returns (and stores) the Cholesky decomposition via LAPACK routine
\code{dpptrf}.

\item[chol] \code{signature(x = "dsCMatrix", pivot = "logical")}:
Returns (and stores) the Cholesky decomposition of \code{x}.  If
\code{pivot} is \code{TRUE} (the default) Metis is used to create
a reordering of the rows and columns of \code{x} so as to minimize
fill-in.

}
\end{Section}
\begin{SeeAlso}\relax
The default from \pkg{base}, \code{\LinkA{chol}{chol}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
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
\end{ExampleCode}
\end{Examples}

