\HeaderA{lu}{Triangular Decomposition of a Square Matrix}{lu}
\aliasA{lu,dgeMatrix-method}{lu}{lu,dgeMatrix.Rdash.method}
\keyword{array}{lu}
\keyword{algebra}{lu}
\begin{Description}\relax
Computes triangular decompositions of square matrices.
\end{Description}
\begin{Usage}
\begin{verbatim}
lu(x, ...)
## S4 method for signature 'dgeMatrix':
lu(x, warnSing = TRUE, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] a matrix of square dimension.  No missing values or IEEE
special values are allowed.
\item[\code{warnSing}] (when \code{x} is a
\code{"\LinkA{denseMatrix}{denseMatrix.Rdash.class}"}) logical specifying if a \code{\LinkA{warning}{warning}}
should be signalled when \code{x} is singular.
\item[\code{...}] further arguments passed to or from other methods.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{lu()} is a generic function with special methods for different types
of matrices.  Use \code{\LinkA{showMethods}{showMethods}("lu")} to list all the methods
for the \code{\LinkA{lu}{lu}} generic.

The method for class \code{\LinkA{dgeMatrix}{dgeMatrix.Rdash.class}} (and all dense
matrices) is based on LAPACK's \code{"dgetrf"} subroutine.  It returns
a decomposition also for singular matrices.

The method for class \code{\LinkA{dgCMatrix}{dgCMatrix.Rdash.class}} (and all sparse
matrices) is based on functions from the CSparse library.  It signals
an error when the decomposition algorithm fails, as when \code{x} is
(too close to) singular.
\end{Details}
\begin{Value}
An object of class \code{"LU"}, i.e., \code{"\LinkA{denseLU}{denseLU.Rdash.class}"}
or \code{"sparseLU"}, see \code{\LinkA{sparseLU}{sparseLU.Rdash.class}}; this is
a representation of a triangular decomposition of \code{x}.
\end{Value}
\begin{References}\relax
Golub, G., and Van Loan, C. F. (1989).
\emph{Matrix Computations,}
2nd edition, Johns Hopkins, Baltimore.

Tim Davis (2005)
\url{http://www.cise.ufl.edu/research/sparse/CSparse/}

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{LU}{LU.Rdash.class}} and \code{\LinkA{sparseLU}{sparseLU.Rdash.class}}
and function \code{\LinkA{expand}{expand}};
\code{\LinkA{qr}{qr}}, \code{\LinkA{chol}{chol}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}

##--- Dense  -------------------------
x <- Matrix(rnorm(9), 3, 3)
lu(x)

##--- Sparse ------------------------

pm <- as(readMM(system.file("external/pores_1.mtx",
                            package = "Matrix")),
         "CsparseMatrix")
str(pmLU <- lu(pm))             # p is a 0-based permutation of the rows
                                # q is a 0-based permutation of the columns
## permute rows and columns of original matrix
ppm <- pm[pmLU@p + 1L, pmLU@q + 1L]
pLU <- pmLU@L %*% pmLU@U
## equal up to "rounding"
ppm[1:14, 1:5]
pLU[1:14, 1:5]  # product can have extra zeros
## "prove" consistency (up to rounding):
i0 <- ppm != pLU & ppm == 0
iN <- ppm != pLU & ppm != 0
stopifnot(all(abs((ppm - pLU)[i0]) < 1e-7), # absolute error for true 0
          all(abs((ppm - pLU)[iN]/ppm[iN]) < 1e-9)) # relative error
\end{ExampleCode}
\end{Examples}

