spec eigenvalues, and eigenvectors of a matrix or a pencil

## Syntax

                evals          = spec(A)
                [R, diagevals] = spec(A)

                evals               = spec(A, B)
                [alpha, beta]       = spec(A, B)
                [alpha, beta, Z]    = spec(A, B)
                [alpha, beta, Q, Z] = spec(A, B)

## Arguments

A, B
  Square matrices of real or complex numbers, of same sizes.

evals
  Real or complex vector: The eigenvalues.

diagevals
  Real or complex diagonal matrix: Eigenvalues along the diagonal.

R
  Real or complex invertible square matrix: Matrix right eigenvectors.

alpha, beta
  Vectors of same size: Generalized eigenvalues of the matrix pencil `A - s.B` (s is the variable). alpha./beta gives the usual eigenvalues. `alpha` are real or complex values. `beta` are real values.

Q
  Real or complex invertible square matrix: Generalized left eigenvectors of the pencil.

Z
  Real or complex invertible square matrix: Generalized right eigenvectors of the pencil.

## Description

evals = spec(A) computes the eigenvalues and returns them in the vector `evals`.

[R, diagevals] = spec(A) returns the eigenvalues through the diagonal matrix `diagevals`, and the right eigenvectors in `R`. See also `bdiag(…)`.

When using a `spec(A)` syntax with a single matrix, the realness of results is as it follows:

A matrix | Real | Complex
| Symmetric | Asymmetric | Hermitian | Non-hermitian
Eigenvalues | real | complex | real | complex
Eigenvectors | real | complex | complex | complex

A complex hermitian matrix is equal to its own conjugate transposed.

### Matrix Pencil A - s.B

evals = spec(A, B) returns the eigenvalues of the matrix pencil, i.e. the roots of the polynomial matrix `s.B - A`.

[alpha, beta] = spec(A, B) returns the generalized eigenvalues `alpha` and `beta` of the matrix pencil `A - s.B`. They are such that the usual eigenvalues of the pencil are given by `alpha./beta`. The matrix `A - alpha./beta × B` is then singular. If `beta(i) = 0`, the ith eigenvalue is infinite.

For `B = eye(A)`, `alpha./beta` are equal to `spec(A)`. It is usually represented as the pair (alpha,beta), as there is a reasonable interpretation for `beta=0`, even when both are zero.

[alpha, beta, Z] = spec(A, B) returns in addition the matrix `Z` of the generalized right eigenvectors of the pencil.

[alpha, beta, Q, Z] = spec(A, B) returns in addition the matrix `Q` of generalized left eigenvectors of the pencil.

For large dense or sparse matrices, the eigs() function can be used.

## Used routines

Matrix eigenvalues computations are based on the Lapack routines

- DSYEV and ZHEEV, when the matrix is symmetric or hermitian.

- DGEEV and ZGEEV, when the matrix is neither symmetric nor hermitian.

Pencil eigenvalues computations are based on the Lapack routines DGGEV and ZGGEV.

## Examples

    // MATRIX EIGENVALUES
    A = diag([1,2,3]);
    X = rand(3,3);
    A = inv(X)*A*X;
    spec(A)

    x = poly(0,'x');
    pol = det(x*eye(3,3)-A)
    roots(pol)

    [S,X] = bdiag(A);
    clean(inv(X)*A*X)

    // PENCIL EIGENVALUES
    A = rand(3,3);
    [al, be, R] = spec(A, eye(A));
    al ./ be
    clean(inv(R)*A*R)    // displaying the eigenvalues (generic matrix)
    A = A + %i*rand(A);
    E = rand(A);
    roots(det(A-%s*E))   // complex case

## See also

- eigs
- bdiag
- schur
- colcomp
- det
- poly