\HeaderA{svd}{Singular Value Decomposition of a Matrix}{svd}
\aliasA{La.svd}{svd}{La.svd}
\keyword{algebra}{svd}
\keyword{array}{svd}
\begin{Description}\relax
Compute the singular-value decomposition of a rectangular matrix.
\end{Description}
\begin{Usage}
\begin{verbatim}
svd(x, nu = min(n, p), nv = min(n, p), LINPACK = FALSE)

La.svd(x, nu = min(n, p), nv = min(n, p),
       method = c("dgesdd", "dgesvd"))
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] a real or complex matrix whose SVD decomposition is to be computed.
\item[\code{nu}] the number of left  singular vectors to be computed.
This must be one of \code{0}, \code{nrow(x)} and \code{ncol(x)},
except for the default options for real matrices.
\item[\code{nv}] the number of right singular vectors to be computed.
This must be one of \code{0} and \code{ncol(x)}.
\item[\code{LINPACK}] logical. Should LINPACK be used (for compatibility with
\R{} < 1.7.0)?
\item[\code{method}] The LAPACK routine to use in the real case.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The singular value decomposition plays an important role in many
statistical techniques.  \code{svd} and \code{La.svd} provide two
slightly different interfaces.  The main functions used are
the LAPACK routines DGESDD and ZGESVD; \code{svd(LINPACK=TRUE)}
provides an interface to the LINPACK routine DSVDC, purely for
backwards compatibility.

\code{La.svd} provides an interface to both the LAPACK routines
DGESVD and DGESDD.  The latter is usually substantially faster
if singular vectors are required: see
\url{http://www.cs.berkeley.edu/~demmel/DOE2000/Report0100.html}.
Most benefit is seen with an optimized BLAS system.  As from
\R{} 2.3.0, using \code{method="dgesvd"} is deprecated.

Computing the singular vectors is the slow part for large matrices.

Unsuccessful results from the underlying LAPACK code will result in an
error giving a positive error code: these can only be interpreted by
detailed study of the FORTRAN code.
\end{Details}
\begin{Value}
The SVD decomposition of the matrix as computed by LINPACK,
\deqn{ \bold{X = U D V'},}{} where \eqn{\bold{U}}{} and \eqn{\bold{V}}{} are
orthogonal, \eqn{\bold{V'}}{} means \emph{V transposed}, and
\eqn{\bold{D}}{} is a diagonal matrix with the singular
values \eqn{D_{ii}}{D[i,i]}.  Equivalently, \eqn{\bold{D = U' X V}}{},
which is verified in the examples, below.

The returned value is a list with components
\begin{ldescription}
\item[\code{d}] a vector containing the singular values of \code{x}.
\item[\code{u}] a matrix whose columns contain the left singular vectors of
\code{x}, present if \code{nu > 0}
\item[\code{v}] a matrix whose columns contain the right singular vectors of
\code{x}, present if \code{nv > 0}.
\end{ldescription}


For \code{La.svd} the return value replaces \code{v} by \code{vt}, the
(conjugated if complex) transpose of \code{v}.
\end{Value}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.

Dongarra, J. J., Bunch, J. R., Moler, C. B. and Stewart, G. W. (1978)
\emph{LINPACK Users Guide.}  Philadelphia: SIAM Publications.

Anderson. E. and ten others (1999)
\emph{LAPACK Users' Guide}. Third Edition. SIAM.\\
Available on-line at
\url{http://www.netlib.org/lapack/lug/lapack_lug.html}.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{eigen}{eigen}}, \code{\LinkA{qr}{qr}}.

\code{\LinkA{capabilities}{capabilities}} to test for IEEE 754 arithmetic.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
hilbert <- function(n) { i <- 1:n; 1 / outer(i - 1, i, "+") }
X <- hilbert(9)[,1:6]
(s <- svd(X))
D <- diag(s$d)
s$u %*% D %*% t(s$v) #  X = U D V'
t(s$u) %*% X %*% s$v #  D = U' X V
\end{ExampleCode}
\end{Examples}

