\HeaderA{Cholesky}{Cholesky Decomposition of a Sparse Matrix}{Cholesky}
\aliasA{Cholesky,CsparseMatrix-method}{Cholesky}{Cholesky,CsparseMatrix.Rdash.method}
\aliasA{Cholesky,dsCMatrix-method}{Cholesky}{Cholesky,dsCMatrix.Rdash.method}
\aliasA{Cholesky,Matrix-method}{Cholesky}{Cholesky,Matrix.Rdash.method}
\aliasA{Cholesky,nsparseMatrix-method}{Cholesky}{Cholesky,nsparseMatrix.Rdash.method}
\aliasA{Cholesky,sparseMatrix-method}{Cholesky}{Cholesky,sparseMatrix.Rdash.method}
\keyword{array}{Cholesky}
\keyword{algebra}{Cholesky}
\begin{Description}\relax
Computes the Cholesky decomposition of a sparse, symmetric,
positive-definite matrix.  However, typically \code{\LinkA{chol}{chol}()}
should rather be used unless you are interested in the different kinds
of sparse Cholesky decompositions.
\end{Description}
\begin{Usage}
\begin{verbatim}
Cholesky(A, perm = TRUE, LDL = !super, super = FALSE, Imult = 0, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{A}] sparse symmetric matrix.  No missing values or IEEE special
values are allowed.
\item[\code{perm}] logical scalar indicating if a fill-reducing permutation
should be computed and applied to the rows and columns of \code{A}.
Default is \code{TRUE}.
\item[\code{LDL}] logical scalar indicating if the decomposition should be
computed as LDL' where \code{L} is a unit lower triangular matrix.
The alternative is LL' where \code{L} is lower triangular with
arbitrary diagonal elements.  Default is \code{TRUE}.  Setting it to
\code{\LinkA{NA}{NA}} leaves the choice to a CHOLMOD-internal heuristic.
\item[\code{super}] logical scalar indicating is a supernodal decomposition
should be created.  The alternative is a simplicial decomposition.
Default is \code{FALSE}.  Setting it to \code{\LinkA{NA}{NA}} leaves the
choice to a CHOLMOD-internal heuristic.
\item[\code{Imult}] numeric scalar which defaults to zero. The matrix that is
decomposed is \eqn{A+m*I}{} where \eqn{m}{} is the value of \code{Imult}
and \code{I} is the identity matrix of order \code{ncol(A)}.
\item[\code{...}] further arguments passed to or from other methods.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
This is a generic function with special methods for different types
of matrices.  Use \code{\LinkA{showMethods}{showMethods}("Cholesky")} to list all
the methods for the \code{\LinkA{Cholesky}{Cholesky}} generic.

The method for class \code{\LinkA{dsCMatrix}{dsCMatrix.Rdash.class}} of sparse matrices
--- the only one available currently ---
is based on functions from the CHOLMOD library.

Again: If you just want the Cholesky decomposition of a matrix, you
should probably rather use \code{\LinkA{chol}{chol}(.)}.
\end{Details}
\begin{Value}
an object inheriting from either
\code{"\LinkA{CHMsuper}{CHMsuper.Rdash.class}"}, or
\code{"\LinkA{CHMsimpl}{CHMsimpl.Rdash.class}"}, depending on the \code{super}
argument; both classes extend \code{"\LinkA{CHMfactor}{CHMfactor.Rdash.class}"} which
extends \code{"\LinkA{MatrixFactorization}{MatrixFactorization.Rdash.class}"}.

In other words, the result of \code{Cholesky()} is \emph{not} a
matrix, and if you want one, you should probably rather use
\code{\LinkA{chol}{chol}()}.
\end{Value}
\begin{References}\relax
Tim Davis (2005)
\emph{{CHOLMOD}: sparse supernodal {Cholesky} factorization and
update/downdate}
\url{http://www.cise.ufl.edu/research/sparse/cholmod/}

Timothy A. Davis (2006)
\emph{Direct Methods for Sparse Linear Systems}, SIAM Series
\dQuote{Fundamentals of Algorithms}.
\end{References}
\begin{SeeAlso}\relax
Class definitions \code{\LinkA{CHMfactor}{CHMfactor.Rdash.class}} and
\code{\LinkA{dsCMatrix}{dsCMatrix.Rdash.class}} and function \code{\LinkA{expand}{expand}}.
Note the extra \code{\LinkA{solve}{solve}(*, system = . )} options in
\code{\LinkA{CHMfactor}{CHMfactor.Rdash.class}}.

Note that \code{\LinkA{chol}{chol}()} returns matrices (inheriting from
\code{"\LinkA{Matrix}{Matrix.Rdash.class}"}) whereas \code{Cholesky()} returns a
\code{"\LinkA{CHMfactor}{CHMfactor.Rdash.class}"} object, and hence a typical user
will rather use \code{chol(A)}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
data(KNex)
mtm <- with(KNex, crossprod(mm))
str(mtm@factors) # empty list()
(C1 <- Cholesky(mtm))             # uses show(<MatrixFactorization>)
str(mtm@factors) # 'sPDCholesky' (simpl)
(Cm <- Cholesky(mtm, super = TRUE))
c(C1 = isLDL(C1), Cm = isLDL(Cm))
str(mtm@factors) # 'sPDCholesky'  *and* 'SPdCholesky'
str(cm1  <- as(C1, "sparseMatrix"))
str(cmat <- as(Cm, "sparseMatrix"))# hmm: super is *less* sparse here
cm1[1:20, 1:20]

b <- matrix(c(rep(0, 711), 1), nc = 1)
## solve(Cm, b) by default solves  Ax = b, where A = Cm'Cm !
x <- solve(Cm, b)
stopifnot(identical(x, solve(Cm, b, system = "A")),
          all.equal(x, solve(mtm, b)))

Cn <- Cholesky(mtm, perm = FALSE)# no permutation -- much worse:
sizes <- c(simple = object.size(C1),
           super  = object.size(Cm),
           noPerm = object.size(Cn))
format(cbind(100 * sizes / sizes[1]), digits=4)

## Visualize the sparseness:
dq <- function(ch) paste('"',ch,'"', sep="") ## dQuote(<UTF-8>) gives bad plots
image(mtm, main=paste("crossprod(mm) : Sparse", dq(class(mtm))))
image(cm1, main= paste("as(Cholesky(crossprod(mm)),\"sparseMatrix\"):",
                        dq(class(cm1))))

\end{ExampleCode}
\end{Examples}

