\HeaderA{rcond}{Estimate the Reciprocal Condition Number}{rcond}
\aliasA{rcond,ANY,missing-method}{rcond}{rcond,ANY,missing.Rdash.method}
\aliasA{rcond,ldenseMatrix,character-method}{rcond}{rcond,ldenseMatrix,character.Rdash.method}
\aliasA{rcond,Matrix,character-method}{rcond}{rcond,Matrix,character.Rdash.method}
\aliasA{rcond,matrix,character-method}{rcond}{rcond,matrix,character.Rdash.method}
\aliasA{rcond,ndenseMatrix,character-method}{rcond}{rcond,ndenseMatrix,character.Rdash.method}
\keyword{array}{rcond}
\keyword{algebra}{rcond}
\begin{Description}\relax
Estimate the reciprocal of the condition number of a matrix.

This is a generic function with several methods, as seen by
\code{\LinkA{showMethods}{showMethods}(rcond)}.
\end{Description}
\begin{Usage}
\begin{verbatim}
rcond(x, norm, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] an \R{} object that inherits from the \code{Matrix} class.
\item[\code{norm}] Character indicating the type of norm to be used in the estimate.
The default is \code{"O"} for the 1-norm (\code{"O"} is equivalent
to \code{"1"}).  The other possible value is \code{"I"} for the
infinity norm, see also \code{\LinkA{norm}{norm}}.

\item[\code{...}] further arguments passed to or from other methods.
\end{ldescription}
\end{Arguments}
\begin{Value}
An estimate of the reciprocal condition number of \code{x}.
\end{Value}
\begin{Section}{BACKGROUND}
The condition number of a regular (square) matrix is the product of
the \code{\LinkA{norm}{norm}} of the matrix and the norm of its inverse (or
pseudo-inverse).

More generally, the condition number is defined (also for
non-square matrices \eqn{A}{}) as
\deqn{\kappa(A) = \frac{\max_{\|v\| = 1} \|A v\|}{\min_{\|v\| = 1} \|A v\|}.}{}
Whenever \code{x} is \emph{not} a square matrix, in our method
definitions, this is typically computed via \code{rcond(qr.R(qr(X)), ...)}
where \code{X} is \code{x} or \code{t(x)}.

The condition number takes on values between 1 and infinity,
inclusive, and can be viewed as a factor by which errors in solving
linear systems with this matrix as coefficient matrix could be
magnified.

\code{rcond()} computes the \emph{reciprocal} condition number
\eqn{1/\kappa}{} with values in \eqn{[0,1]}{} and can be viewed as a
scaled measure of how close a matrix is to being rank deficient (aka
\dQuote{singular}).

Condition numbers are usually estimated, since exact computation is
costly in terms of floating-point operations.  An (over) estimate of
reciprocal condition number is given, since by doing so overflow is
avoided.  Matrices are well-conditioned if the reciprocal condition
number is near 1 and ill-conditioned if it is near zero.
\end{Section}
\begin{References}\relax
Golub, G., and Van Loan, C. F. (1989).
\emph{Matrix Computations,}
2nd edition, Johns Hopkins, Baltimore.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{norm}{norm}}, \code{\LinkA{kappa}{kappa}()} from package
\pkg{base} computes an \emph{approximate} condition number of a
\dQuote{traditional} matrix, even non-square ones, with respect to the
\eqn{p=2}{} (Euclidean) \code{\LinkA{norm}{norm}}.
\code{\LinkA{solve}{solve}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
x <- Matrix(rnorm(9), 3, 3)
rcond(x)
## typically "the same" (with more computational effort):
1 / (norm(x) * norm(solve(x)))
rcond(Hilbert(9))  # should be about 9.1e-13

## For non-square matrices:
rcond(x1 <- cbind(1,1:10))# 0.05278
rcond(x2 <- cbind(x1, 2:11))# practically 0, since x2 does not have full rank

## sparse
(S1 <- Matrix(rbind(0:1,0, diag(3:-2))))
rcond(S1)
m1 <- as(S1, "denseMatrix")
all.equal(rcond(S1), rcond(m1))

## wide and sparse
rcond(Matrix(cbind(0, diag(2:-1))))
\end{ExampleCode}
\end{Examples}

