eigs

Arguments

A

a full or sparse, real or complex, symmetric or non-symmetric square matrix

Af

a function

n

a scalar, defined only if A is a function

B

a sparse, real or complex, square matrix with same dimensions as A

k

an integer, number of eigenvalues to be computed

sigma

a real scalar or a string of length 2

opts

a structure

d

a real or complex eigenvalues vector or diagonal matrix (eigenvalues along the diagonal)

v

real or complex eigenvector matrix

Description

The purpose of the eigs function is to compute the largest eigenvalues of sparse, large matrices.

d = eigs(A) or d = eigs(Af, n)

solves the eigenvalue problem A * v = lambda * v. This calling returns a vector d containing the six largest magnitude eigenvalues. A is either a square matrix, which can be symmetric or non-symmetric, real or complex, full or sparse.

A should be represented by a function Af. In this instance, a scalar n designating the length of the vector argument, must be defined. It must have the following header :

function y=A(x)

This function Af must return one of the four following expressions :

• A * x

  if sigma is not given or is a string other than 'SM'.

• A \ x

  if sigma is 0 or 'SM'.

• (A - sigma * I) \ x

  for the standard eigenvalue problem, where I is the identity matrix.

• (A - sigma * B) \ x

  for the generalized eigenvalue problem.

[d, v] = eigs(A) or [d, v] = eigs(Af, n)

returns a diagonal matrix d containing the six largest magnitude eigenvalues on the diagonal. v is a n by six matrix whose columns are the six eigenvectors corresponding to the returned eigenvalues.

d = eigs(A, B)

solves the generalized eigenvalue problem A * v = lambda * B * v with positive, definite matrix B.

• if B is not specified, B = [] is used.

• if B is specified, B must be the same size as A.

d = eigs(A, B, k)

returns in vector d the k eigenvalues. If k is not specified, k = min(n, 6), where n is the row number of A.

d = eigs(A, B, k, sigma)

returns in vector d the k eigenvalues determined by sigma. sigma can be either a real or complex including 0 scalar or string. If sigma is a string of length 2, it takes one of the following values :

• 'LM' compute the k largest in magnitude eigenvalues (by default).

• 'SM' compute the k smallest in magnitude eigenvalues (same as sigma = 0).

• 'LA' compute the k Largest Algebraic eigenvalues, only for real symmetric problems.

• 'SA' compute the k Smallest Algebraic eigenvalues, only for real symmetric problems.

• 'BE' compute k eigenvalues, half from each end of the spectrum, only for real symmetric problems.

• 'LR' compute the k eigenvalues of Largest Real part, only for real non-symmetric or complex problems.

• 'SR' compute the k eigenvalues of Smallest Real part, only for real non-symmetric or complex problems.

• 'LI' compute the k eigenvalues of Largest Imaginary part, only for real non-symmetric or complex problems.

• 'SI' compute the k eigenvalues of Smallest Imaginary part, only for real non-symmetric or complex problems.

d = eigs(A, B, k, sigma, opts)

If the opts structure is specified, different options can be used to compute the k eigenvalues :

• tol

  required convergence tolerance. By default, tol = %eps.

• maxiter

  maximum number of iterations. By default, maxiter = 300.

• ncv

  number of Lanzcos basis vectors to use. For real non-symmetric problems, the ncv value must be greater or equal than 2 * k + 1 and, by default, ncv = min(max(2 * k + 1, 20), nA). For real symmetric or complex problems, ncv must be greater or equal 2 * k and, by default, ncv = min(max(2 * k, 20), nA) with nA = size(A, 2).

• resid

  starting vector whose contains the initial residual vector, possibly from a previous run. By default, resid is a random initial vector.

• cholB

  if chol(B) is passed rather than B. By default, cholB is %f.

• isreal

  if Af is given, isreal can be defined. By default, isreal is %t. This argument must not be indicated if A is a matrix.

• issym

  if Af is given, issym can be defined. By default, issym is %f. This argument must not be indicated if A is a matrix.

References

This function is based on the ARPACK package written by R. Lehoucq, K. Maschhoff, D. Sorensen, and C. Yang.

• DSAUPD and DSEUPD routines for real symmetric problems,

• DNAUPD and DNEUPD routines for real non-symmetric problems.

• ZNAUPD and ZNEUPD routines for complex problems.

Example for real symmetric problems

clear opts
A            = diag(10*ones(10,1));
A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6*ones(9,1));
A(2:$,1:$-1) = A(2:$,1:$-1) + diag(6*ones(9,1));

B = eye(10,10);
k = 8;
sigma = 'SM';
opts.cholB = %t;

d = eigs(A)
[d, v] = eigs(A)

d = eigs(A, B, k, sigma)
[d, v] = eigs(A, B, k, sigma)

d = eigs(A, B, k, sigma, opts)
[d, v] = eigs(A, B, k, sigma, opts)

// With sparses
AS = sparse(A);
BS = sparse(B);

d = eigs(AS)
[d, v] = eigs(AS)

d = eigs(AS, BS, k, sigma)
[d, v] = eigs(AS, BS, k, sigma)

d = eigs(AS, BS, k, sigma, opts)
[d, v] = eigs(AS, BS, k, sigma, opts)

// With function
clear opts
function y=fn(x)
   y = A * x;
endfunction

opts.isreal = %t;
opts.issym = %t;

d = eigs(fn, 10, [], k, 'LM', opts)

function y=fn(x)
   y = A \ x;
endfunction

d = eigs(fn, 10, [], k, 'SM', opts)

function y=fn(x)
   y = (A - 4 * eye(10,10)) \ x;
endfunction

d = eigs(fn, 10, [], k, 4, opts)

Example for real non-symmetric problems

clear opts
   A            = diag(10*ones(10,1));
   A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6*ones(9,1));
   A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6*ones(9,1));

   B = eye(10,10);
   k = 8;
   sigma = 'SM';
   opts.cholB = %t;
   
   d = eigs(A)
[d, v] = eigs(A)
   
   d = eigs(A, B, k, sigma)
   [d, v] = eigs(A, B, k, sigma) 

   d = eigs(A, B, k, sigma, opts)
   [d, v] = eigs(A, B, k, sigma, opts)

// With sparses
   AS = sparse(A);
   BS = sparse(B);

d = eigs(AS)
[d, v] = eigs(AS)
   d = eigs(AS, BS, k, sigma)
   [d, v] = eigs(AS, BS, k, sigma)

   d = eigs(AS, BS, k, sigma, opts)
   [d, v] = eigs(AS, BS, k, sigma, opts)
   
   // With function
clear opts
function y=fn(x)
  y = A * x;
endfunction

opts.isreal = %t;
opts.issym = %f;

d = eigs(fn, 10, [], k, 'LM', opts)

function y=fn(x)
  y = A \ x;
endfunction

d = eigs(fn, 10, [], k, 'SM', opts)

function y=fn(x)
  y = (A - 4 * eye(10,10)) \ x;
endfunction

d = eigs(fn, 10, [], k, 4, opts)

Example for complex problems

clear opts
   A            = diag(10*ones(10,1) + %i * ones(10,1));
   A(1:$-1,2:$) = A(1:$-1,2:$) + diag(6*ones(9,1));
   A(2:$,1:$-1) = A(2:$,1:$-1) + diag(-6*ones(9,1));

   B = eye(10,10);
   k = 8;
   sigma = 'LM';
   opts.cholB = %t;
   
   d = eigs(A)
[d, v] = eigs(A)

   d = eigs(A, B, k, sigma)
   [d, v] = eigs(A, B, k, sigma)
   d = eigs(A, B, k, sigma, opts)
   [d, v] = eigs(A, B, k, sigma, opts)
   
   // With sparses
   AS = sparse(A);
   BS = sparse(B);
   
   d = eigs(AS)
[d, v] = eigs(AS)

   d = eigs(AS, BS, k, sigma)
   [d, v] = eigs(AS, BS, k, sigma)

   d = eigs(AS, BS, k, sigma, opts)
   [d, v] = eigs(AS, BS, k, sigma, opts)
   
   // With function
clear opts
function y=fn(x)
  y = A * x;
endfunction

opts.isreal = %f;
opts.issym = %f;

d = eigs(fn, 10, [], k, 'LM', opts)

function y=fn(x)
  y = A \ x;
endfunction

d = eigs(fn, 10, [], k, 'SM', opts)

function y=fn(x)
  y = (A - 4 * eye(10,10)) \ x;
endfunction

d = eigs(fn, 10, [], k, 4, opts)

See Also

• spec — eigenvalues of matrices and pencils

History