Schur Decomposition of a Matrix

DESCRIPTION:
Computes the Schur decomposition and eigenvalues of a square matrix.

USAGE:
schur.Matrix(x, vectors=T, rcond=F, threshold=0, tune=<see below>,
             workspace=<see below>)

REQUIRED ARGUMENTS:
x:
numeric or complex square Matrix inheriting from class "Matrix". Missing values (NAs) are not allowed.

OPTIONAL ARGUMENTS:
vectors:
a logical value telling whether or not to compute the Schur vectors. The default is to compute them.
rcond:
either a logical value or a logical vector of length 2 telling whether or not to compute reciprocal condition numbers for the eigenvalues and Schur vectors, respectively, and return them as attributes. By default, neither is computed.
threshold:
a numeric value. A diagonal block associated with a particular eigenvalue will appear in the top left portion of the Schur decomposition if it is greater than or equal to threshold in magnitude. By default, threshold is zero, so that eigenvalues are unordered. Further ordering can be obtained by applying schurmod to an existing Schur decomposition.
tune:
a integer vector or list of named tuning parameters that may affect computational efficiency. The relevant parameters are NB, NBMIN, NX, NS, and MAXB, as described in .laenv. The default is to use the settings in .laenv, which are initialized in S-Plus but may be changed by the user.
workspace:
workspace provided to the underlying software. The default is to use the minimum allowed value. The optimal workspace for the problem (for the given tune specifications) is included as part of the output attributes.

VALUE:
The result is an object of class c("schur.Matrix", "decomp"). Attributes include eigenvalues, condition numbers (if requested via rcond), and workspace information, and a copy of the call to schur.Matrix.

DETAILS:
Based on the functions dgeesx and zgeesx from LAPACK (Anderson et al. 1994). Parameters in tune may affect performance and workspace requirements, but the optimal settings are both machine and problem dependent. Users may want to experiment with tune (see Anderson et al., p. 72-74) to obtain improved performance.

BUGS:
The condition numbers are not computed correctly. A bug report has been filed with LAPACK.

REFERENCES:
Anderson, E., et al. (1994). LAPACK User's Guide, 2nd edition, SIAM, Philadelphia.

SEE ALSO:
schur.Matrix.object , schurmod , eigen.Matrix , .laenv

EXAMPLES:
 n <- 9
 A <- Matrix( rnorm(n*n,sd = 100), nrow = n, ncol = n)
 schur.A <- schur(A)                                 # schur factorization
 mod.eig <- Mod(attr( schur.A, "eigenvalues"))       # eigenvalue modulus
 schur.A <- schur(schur.A)                           # reordered factorization