

   SSppeeccttrraall DDeeccoommppoossiittiioonn ooff aa MMaattrriixx

        eigen(x, symmetric, only.values=FALSE)

   AArrgguummeennttss::

          x: a matrix whose spectral decomposition is to be
             computed.

   symmetric: if `TRUE', the matrix is assumed to be symmetric
             (or Hermitian if complex) and only its lower tri-
             angle is used.  If `symmetric' is not specified,
             the matrix is inspected for symmetry.

   only.values: if `TRUE', only the eigenvalues are computed
             and returned, otherwise both eigenvalues and
             eigenvectors are returned.

   DDeessccrriippttiioonn::

        This function provides an interface to the EISPACK rou-
        tines `RS', `RG', `CH' and `CG'.

   VVaalluuee::

        The spectral decomposition of `x' is returned as compo-
        nents of a list.

     values: a vector containing the eigenvalues of `x', sorted
             decreasingly, according to `Mod(values)' if they
             are complex.

    vectors: a matrix whose columns contain the eigenvectors of
             `x'.

   RReeffeerreenncceess::

        Smith, B. T, J. M. Boyle, J. J. Dongarra, B. S. Garbow,
        Y. Ikebe, V. Klema, C. B. Moler (1976).  Matrix Eigen-
        systems Routines - EISPACK Guide.  Springer-Verlag Lec-
        ture Notes in Computer Science.

   SSeeee AAllssoo::

        `svd', a generalization of `eigen'; `qr', and `chol'
        for related decompositions.

   EExxaammpplleess::

        eigen(cbind(c(1,-1),c(-1,1)))
        eigen(cbind(c(1,-1),c(-1,1)), symmetric = FALSE)# same (different algorithm).

        eigen(cbind(1,c(1,-1)), only.values = TRUE)
        eigen(cbind(-1,2:1)) # complex values
        eigen(print(cbind(c(0,1i), c(-1i,0))))# Hermite ==> real Eigen values
        ## 3 x 3:
        eigen(cbind( 1,3:1,1:3))
        eigen(cbind(-1,c(1:2,0),0:2)) # complex values

        m <- matrix(rnorm(25),5,5) ; m <- m + t(m) #- a symmetric matrix
        em <- eigen(m); V <- em$vect; lam <- em$values
        all(c(    m     - V %*% diag(lam) %*% t(V)) < 60*.Machine$double.eps)
        all(c(m %*% V - V %*% diag(lam))            < 60*.Machine$double.eps)

