\HeaderA{Schur}{Schur Decomposition of a Matrix}{Schur}
\aliasA{Schur,dgeMatrix,logical-method}{Schur}{Schur,dgeMatrix,logical.Rdash.method}
\aliasA{Schur,dgeMatrix,missing-method}{Schur}{Schur,dgeMatrix,missing.Rdash.method}
\aliasA{Schur,diagonalMatrix,logical-method}{Schur}{Schur,diagonalMatrix,logical.Rdash.method}
\aliasA{Schur,diagonalMatrix,missing-method}{Schur}{Schur,diagonalMatrix,missing.Rdash.method}
\aliasA{Schur,dsyMatrix,ANY-method}{Schur}{Schur,dsyMatrix,ANY.Rdash.method}
\aliasA{Schur,generalMatrix,ANY-method}{Schur}{Schur,generalMatrix,ANY.Rdash.method}
\aliasA{Schur,symmetricMatrix,ANY-method}{Schur}{Schur,symmetricMatrix,ANY.Rdash.method}
\aliasA{Schur,triangularMatrix,logical-method}{Schur}{Schur,triangularMatrix,logical.Rdash.method}
\aliasA{Schur,triangularMatrix,missing-method}{Schur}{Schur,triangularMatrix,missing.Rdash.method}
\keyword{algebra}{Schur}
\begin{Description}\relax
Computes the Schur decomposition and eigenvalues of a square matrix;
see the BACKGROUND information below.
\end{Description}
\begin{Usage}
\begin{verbatim}
Schur(x, vectors, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] numeric (or complex, in future) square Matrix (inheriting from class
\code{"Matrix"}). Missing values (NAs) are not allowed.

\item[\code{vectors}] logical.  When \code{TRUE} (the default), the Schur
vectors are computed, and the result is a proper
\code{\LinkA{MatrixFactorization}{MatrixFactorization.Rdash.class}} of class
\code{\LinkA{Schur}{Schur.Rdash.class}}.

\item[\code{...}] further arguments passed to or from other methods.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Based on the Lapack subroutine \code{dgees}.
\end{Details}
\begin{Value}
If \code{vectors} are \code{TRUE}, as per default,
an object of class \code{\LinkA{Schur}{Schur.Rdash.class}}.

If \code{vectors} are \code{FALSE}, a list with components
\begin{ldescription}
\item[\code{T}] the upper quasi-triangular (square) matrix of the Schur decomposition.
\item[\code{EValues}] the vector of \code{\LinkA{numeric}{numeric}} or
\code{\LinkA{complex}{complex}} eigen values of \eqn{T}{} or \eqn{A}{}.
\end{ldescription}
\end{Value}
\begin{Section}{BACKGROUND}
If \code{A} is a square matrix, then \code{A = Q T t(Q)}, where
\code{Q} is orthogonal, and \code{T} is upper block-triangular
(nearly triangular with either 1 by 1 or 2 by 2 blocks on the
diagonal) where the 2 by 2 blocks correspond to (non-real) complex
eigenvalues.
The eigenvalues of \code{A} are the same as those of \code{T},
which are easy to compute.  The Schur form is used most often for
computing non-symmetric eigenvalue decompositions, and for computing
functions of matrices such as matrix exponentials.
\end{Section}
\begin{References}\relax
Anderson, E., et al. (1994).
\emph{LAPACK User's Guide,}
2nd edition, SIAM, Philadelphia.
\end{References}
\begin{Examples}
\begin{ExampleCode}
Schur(Hilbert(9))              # Schur factorization (real eigenvalues)

(A <- Matrix(round(rnorm(5*5, sd = 100)), nrow = 5))
(Sch.A <- Schur(A))

eTA <- eigen(Sch.A@T)
str(SchA <- Schur(A, vectors=FALSE))# no 'T' ==> simple list
stopifnot(all.equal(eTA$values, eigen(A)$values, tol = 1e-13),
          all.equal(eTA$values,
                    local({z <- Sch.A@EValues
                           z[order(Mod(z), decreasing=TRUE)]}), tol = 1e-13),
          identical(SchA$T, Sch.A@T),
          identical(SchA$EValues, Sch.A@EValues))
\end{ExampleCode}
\end{Examples}

