\HeaderA{kappa}{Compute or Estimate the Condition Number of a Matrix}{kappa}
\methaliasA{kappa.default}{kappa}{kappa.default}
\methaliasA{kappa.lm}{kappa}{kappa.lm}
\methaliasA{kappa.qr}{kappa}{kappa.qr}
\methaliasA{kappa.tri}{kappa}{kappa.tri}
\aliasA{rcond}{kappa}{rcond}
\keyword{math}{kappa}
\begin{Description}\relax
The condition number of a regular (square) matrix is the product of
the \emph{norm} of the matrix and the norm of its inverse (or
pseudo-inverse), and hence depends on the kind of matrix-norm.

\code{kappa()} computes an estimate of the 2-norm condition number of
a   matrix or of the \eqn{R}{} matrix of a  \eqn{QR}{} decomposition,
perhaps of a linear fit.  The 2-norm condition number can be shown to
be the ratio of the largest to the smallest \emph{non-zero} singular
value of the matrix.
\end{Description}
\begin{Usage}
\begin{verbatim}
kappa(z, ...)
## Default S3 method:
kappa(z, exact = FALSE,
      norm = NULL, method = c("qr", "direct"), ...)
## S3 method for class 'lm':
kappa(z, ...)
## S3 method for class 'qr':
kappa(z, ...)

kappa.tri(z, exact = FALSE, LINPACK = TRUE, norm=NULL, ...)

rcond(x, norm = c("O","I","1"), triangular = FALSE, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{z,x}] A matrix or a the result of \code{\LinkA{qr}{qr}} or a fit from a class
inheriting from \code{"lm"}.
\item[\code{exact}] logical. Should the result be exact?
\item[\code{norm}] character string, specifying the matrix norm wrt to which
the condition number is to be computed.  \code{"O"}, the default,
means the \bold{O}ne- or 1-norm.  The (currently only) other
possible value is \code{"I"} for the infinity norm.
\item[\code{method}] character string, specifying the method to be used;
\code{"qr"} is default for back-compatibility, mainly.
\item[\code{triangular}] logical.  If true, the matrix used is just the lower
triangular part of \code{z}.
\item[\code{LINPACK}] logical.  If true and \code{z} is not complex, the
Linpack routine \code{dtrco()} is called; otherwise the relevant
Lapack routine is.
\item[\code{...}] further arguments passed to or from other methods.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
For \code{kappa()}, if \code{exact = FALSE} (the default) the
2-norm condition number is estimated by a cheap approximation.
Following S, by default, this uses the LINPACK routine \code{dtrco()}.
However, in \R{} (or S) the exact calculation (via \code{\LinkA{svd}{svd}}) is
also likely to be quick enough.

Note that the 1- and Inf-norm condition numbers are much faster to
calculate, and \code{rcond()} computes these \emph{\bold{r}eciprocal}
condition numbers, also for complex matrices, using standard Lapack
routines.

\code{kappa.tri} is an internal function called by \code{kappa.qr}.
\end{Details}
\begin{Value}
The condition number, \eqn{kappa}{}, or an approximation if
\code{exact = FALSE}.
\end{Value}
\begin{Author}\relax
The design was inspired by (but differs considerably from)
the S function of the same name described in Chambers (1992).
\end{Author}
\begin{References}\relax
Chambers, J. M. (1992)
\emph{Linear models.}
Chapter 4 of \emph{Statistical Models in S}
eds J. M. Chambers and T. J. Hastie, Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{svd}{svd}} for the singular value decomposition and
\code{\LinkA{qr}{qr}} for the \eqn{QR}{} one.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
kappa(x1 <- cbind(1,1:10))# 15.71
kappa(x1, exact = TRUE)        # 13.68
kappa(x2 <- cbind(x1,2:11))# high! [x2 is singular!]

hilbert <- function(n) { i <- 1:n; 1 / outer(i - 1, i, "+") }
sv9 <- svd(h9 <- hilbert(9))$ d
kappa(h9)# pretty high!
kappa(h9, exact = TRUE) == max(sv9) / min(sv9)
kappa(h9, exact = TRUE) / kappa(h9) # .677 (i.e., rel.error = 32%)
\end{ExampleCode}
\end{Examples}

