irbleigs:

A MATLAB program for omputing a

few eigenpairs of a large sparse Hermitian matrix

J. Baglama
University of Rhode Island
D. Calvetti
Case Western Reserve University
and
L. Rei hel
Kent State University

irbleigs is a MATLAB program for omputing a few eigenvalues and asso iated eigenve tors of

a sparse Hermitian matrix of large order n. The matrix is a essed only through the evaluation
of matrix-ve tor produ ts. Working spa e of only a few n-ve tors is required. The program
implements a restarted blo k-Lan zos method. Judi ious hoi es of a eleration polynomials make
it possible to ompute approximations of a few of the largest eigenvalues, a few of the smallest
eigenvalues, or a few eigenvalues in the vi inity of a user-spe ied point on the real axis. irbleigs
also an be applied to ertain large generalized eigenproblems as well as to the omputation of a
few nearby singular values and asso iated right and left singular ve tors of a large general matrix.

Categories and Subje t Des riptors: G.1.3 [Numeri al Analysis: Numeri al Linear Algebra;
G.4 [Mathemati al Software: Do umentation
General Terms: Algorithms, Do umentation
Additional Key Words and Phrases: blo k Lan zos method, eigenvalue omputation, generalized
eigenproblem, singular values, polynomial a eleration

1.

INTRODUCTION

Let A be a large, possibly sparse, Hermitian matrix with real or omplex elements.
Let n denote the order of A. irbleigs is a MATLAB implementation of an impli itly restarted blo k-Lan zos algorithm for the omputation of approximations
of a few, say k , eigenvalues and asso iated eigenve tors of A, where we assume that
k  n. The program is designed to determine approximations of the k largest eigenvalues, the k smallest eigenvalues, or k eigenvalues in the vi inity of a user-spe ied
This resear h was supported in part by a BSU New Fa ulty Resear h Grant and by NSF grants
DMS-0107841 and DMS-0107858.
James Baglama, Department of Mathemati s, University of Rhode Island, Kingston, RI 02881,
jbaglamamath.uri.edu. Daniela Calvetti, Department of Mathemati s, Case Western Reserve
University, Cleveland, OH 44106, dx 57po. wru.edu. Lothar Rei hel, Department of Mathemati al S ien es, Kent State University, Kent, OH 44242, rei helmath.kent.edu.
Permission to make digital/hard opy of all or part of this material without fee for personal
or lassroom use provided that the opies are not made or distributed for prot or ommer ial
advantage, the ACM opyright/server noti e, the title of the publi ation, and its date appear, and
noti e is given that opying is by permission of the ACM, In . To opy otherwise, to republish,
to post on servers, or to redistribute to lists requires prior spe i permission and/or a fee.
20TBD ACM 0098-3500/20TBD/1200-0001 $5.00

??.

ACM Transa tions on Mathemati al Software, Vol. TBD, No. TBD, TBD 20TBD, Pages 1{0

J. Baglama, D. Calvetti, and L. Rei hel

point on the real axis.

irbleigs requires only moderate omputer storage in addition to storage of the
omputed eigenve tor approximations. The matrix A is a essed via a user-supplied
fun tion for the evaluation of matrix-ve tor produ ts. In parti ular, A does not have
to be stored. Moreover, matri es of the form A sI , for s 2 R and I the identity
matrix, do not have to be stored or fa tored; irbleigs does not require that linear
systems of equations with matri es of this form be solved. Storage of only a few
n-ve tors is required, in addition to the storage of the omputed eigenve tors. This
design of irbleigs makes it appli able to omputing a few eigenpairs of large
matri es on personal omputers and workstations with not very large fast storage.
irbleigs implements an impli itly restarted blo k-Lan zos algorithm. This algorithm is presented in detail in [Baglama et al. 2003, and is a development of
an impli itly restarted blo k-Lan zos algorithm des ribed in [Baglama et al. 1998.
The latter algorithm, in turn, is an extension of the impli itly restarted Lan zos
algorithms presented in [Calvetti et al. 1994; Sorensen 1992.
Impli itly restarted Arnoldi and Lan zos algorithms were rst proposed by Sorensen [Sorensen 1992, who advo ated the use of a eleration polynomials determined
by so- alled exa t shifts. ARPACK [Lehou q et al. 1998 implements the impli itly
restarted Arnoldi and Lan zos algorithms based on these a eleration polynomials. The MATLAB fun tion eigs is a MATLAB interfa e to ARPACK. ARPACK
and eigs an be used to ompute approximations of a few eigenpairs of general
n  n non-Hermitian matri es. By spe ializing irbleigs to Hermitian matri es,
and by basing the program on a restarted blo k-Lan zos method, we obtain a ode
that often determines the orre t number of eigenvalues near a multiple eigenvalue
(somewhat more often than eigs). Moreover, irbleigs performs better than eigs
when storage limitations permit only a few steps of the Lan zos or blo k-Lan zos algorithms to be arried out between restarts; see [Baglama et al. 2003 for omputed
examples.
The hoi e of a eleration polynomial is important for the performan e of impli itly restarted methods for eigenvalue omputation. The spe ialization to Hermitian
matri es allows a dierent hoi e of a eleration polynomials than in ARPACK.
Numeri al examples that illustrate the performan e of irbleigs are presented in
[Baglama et al. 2003. Further omputed examples and omparisons with several
methods for the omputation of a few eigenpairs of large Hermitian matri es are
reported in [Baglama et al. 1996; Baglama et al. 1998; Calvetti et al. 1994.
Se tion 2 outlines the impli itly restarted blo k-Lan zos algorithm on whi h the
ode is based, Se tion 3 dis usses user-spe ied parameters of irbleigs, and Se tion 4 des ribes a few sample uses of the program.
2.

THE IMPLICITLY RESTARTED BLOCK-LANCZOS METHOD

irbleigs implements an impli itly restarted blo k-Lan zos method. Let r  1
denote the blo k-size. Given an n  r matrix Vr with orthonormal olumns, m
steps of the blo k-Lan zos method yield the blo k-Lan zos de omposition

(1)
mr = Vmr Tmr + Fr Er ;
n

mr

n

r
where Vmr 2 C
, Vmr Imrr = Vr , Vmr Vmr = Imr and Fr 2 C
satises
 Fr = 0. Here Imr 2 Rmrmr denotes the
Vmr
identity matrix, the matrix Imrr 2
AV

ACM Transa tions on Mathemati al Software, Vol. TBD, No. TBD, TBD 20TBD.

irbleigs:

A program for omputing a few eigenpairs of a large Hermitian matrix

mrr onsists of the rst r olumns of Imr , and the matrix Er 2 Rmrr onsists
R
of the last r olumns of Imr . The supers ript  denotes transposition and, when
appli able, omplex onjugation. Finally, Tmr is an mr  mr Hermitian blo ktridiagonal matrix with upper triangular nonsingular subdiagonal r  r blo ks. To
se ure numeri al orthogonality of the olumns of Vmr , they are reorthogonalized.
We ta itly assume that the de omposition (1) with the spe ied properties exists.
A dis ussion of how irbleigs handles situations when su h a de omposition does
not exist is provided in [Baglama 2000; Baglama et al. 2003.
Let f; y g be an eigenvalue-eigenve tor pair of the matrix Tmr and dene the
ve tor x := Vmr y . Then  and x are ommonly referred to as a Ritz value and a
Ritz ve tor of A, respe tively. It follows from (1) that the residual error Ax x
asso iated with the Ritz pair f; xg satises

kAx

x

k = k(AVmr

mr Tmr )yk = kFr Er yk;

(2)

where k
k denotes the Eu lidean ve tor norm or the asso iated indu ed matrix
norm. Thus, the norm of the residual error an be omputed without expli itly
omputing the Ritz ve tor x by evaluating the right-hand side of (2). When

kFr Er yk  (A);

(3)

for a user-spe ied value of , the Ritz value  is a epted as an approximate

eigenvalue of A. Here  (A) denotes an inexpensively omputable approximation of
kAk. In irbleigs, (A) is the absolute value of the Ritz value of largest magnitude
determined thus far during the omputation.
Assume that the blo k-Lan zos de omposition (1) has been omputed by m steps
of the blo k-Lan zos algorithm, and let m be the largest number of blo k-Lan zos
steps that we wish to arry out between restarts. Let the norm of the residual error
(2) be larger than a spe ied toleran e for the Ritz pairs of interest. We then apply
re ursion formulas derived in [Baglama et al. 1998 to ompute the matrix
U

r := pm (A)Vr ;

(4)

where pm is a polynomial of degree m, to be spe ied below. We refer to pm as an

a eleration polynomial. Given the blo k-Lan zos de omposition (1), the matrix Ur
an be omputed without the evaluation of any additional matrix-ve tor produ ts
with A; see [Baglama et al. 1998 for details. Orthogonalization of the olumns of
Ur yields the matrix Vr+ ; thus,
+
nr ;
+
rr ;
Vr 2 C
Rr 2 C
r = Vr+ Rr+ ;
where (Vr+ ) Vr+ = Ir and Rr+ is upper triangular. The omputations that determined the matrix Vr+ from Vr are now repeated with the matrix Vr+ repla ing Vr .

Thus, appli ation of m steps of the blo k-Lan zos method to

r yields the blo k-Lan zos de omposition

V+

AV

with initial blo k

+
+
+
+ 
= Vmr
Tmr + Fr Er :
mr

If the desired Ritz values have not been determined with su ient a ura y by this
de omposition, then a new a eleration polynomial p+
m of degree m is hosen and
the matrix
Ur+ := p+
(5)
m (A)Vr+
ACM Transa tions on Mathemati al Software, Vol. TBD, No. TBD, TBD 20TBD.

J. Baglama, D. Calvetti, and L. Rei hel

is evaluated in the same way as the matrix Ur in (4) without additional matrixve tor produ t evaluations with the matrix A. Combining (4) and (5) yields

r = p+m (A)pm (A)Vr (Rr+ ) 1 :

Orthogonalization of the olumns of Ur+ now gives the matrix Vr++ . New blo kU+

Lan zos de ompositions are evaluated in this manner until approximations of all
desired eigenvalues and eigenve tors have been omputed with su ient a ura y.
The performan e of the IRBL method ru ially depends on the hoi e of the
sequen e of a eleration polynomials pm ; p+
m ; : : : . We determine these polynomials
by spe ifying their zeros so that the produ t of the omputed a eleration polynomials is of large magnitude in a vi inity of the eigenvalues that we wish to ompute
and of small magnitude on the remaining part of the spe trum of A.
The zeros of the a eleration polynomials pm ; p+
m; : : : are allo ated on sets K
that ontain some of the undesired eigenvalues of A and none of the desired ones.
For instan e, if we wish to ompute a few of the largest eigenvalues of A, then the
sets K are intervals on the real axis to the left of the desired eigenvalues. When
we wish to determine a few non-extreme eigenvalues, the sets K generally onsist
of two real intervals, one on ea h side of the set of desired eigenvalues. How the
sets K are determined from the blo k-tridiagonal matri es Tmr , and from losely
related matri es, evaluated during the omputations is des ribed in [Baglama et al.
2003. The zeros are distributed like Leja points for the sets K, and we refer to
the zeros as weighted fast Leja points or as mapped fast Leja points, depending on
how they are allo ated; see [Baglama et al. 2003 for details. The arithmeti work
to determine the zeros is typi ally negligible.
We remark that in addition to omputing a few eigenvalues and eigenve tors of
a Hermitian matrix A, irbleigs an also be used to determine a few eigenvalues
and eigenve tors of generalized eigenvalue problems of the form
Ax

= M x;

(6)

where A is a Hermitian matrix and M is a Hermitian positive denite matrix, su h

that its Cholesky fa torization an be omputed. We denote the upper triangular
Cholesky fa tor of M by R; thus M = R R.
Finally, we note that irbleigs an ompute a few singular values and asso iated
right and left singular ve tors of a general n1  n2 matrix C by determining a few
eigenvalues and asso iated eigenve tors of the Hermitian matrix


0 C
A=
2 C(n1 +n2 )(n1 +n2 ) ;
(7)
C 0
see [Baglama et al. 2003 for a omputed example. We remark that the svds
fun tion in MATLAB also an be applied to the omputation of a few singular values
and singular ve tors of a general matrix. However, svds uses a shift-and-invert
approa h to determine non-extreme eigenvalues of the matrix (7), and therefore is
not well suited for solving very large problems.
3.

PARAMETERS

irbleigs allows a user to set parameters that spe ify the approximate lo ation of

the desired eigenvalues, determine the omputer storage required and the hoi e
ACM Transa tions on Mathemati al Software, Vol. TBD, No. TBD, TBD 20TBD.

irbleigs:

A program for omputing a few eigenpairs of a large Hermitian matrix

of a eleration polynomial, and ae t the output produ ed. This se tion ontains
a brief des ription of these parameters. We begin with the input parameters in
alphabeti al order, followed by the output parameters. All parameters are assumed
to take on numeri al values, unless otherwise spe ied. The default value of ea h
parameter is provided. The names of parameters are in itali s. For instan e, n
denotes the parameter, whose value is the order n of the matrix A.
blsz
holM

dispr
eigve

endpt

funpar

k
maxit
maxdpol

Blo k-size of the blo k-Lan zos method. The parameter spe ies the
value of r in (1). Default value: blsz = 3.
Indi ates whether the upper triangular Cholesky fa tor R of the matrix
M in the generalized eigenvalue problem (6) is available. If it is, then
let holM = 1 and repla e the input matrix M by R, otherwise let
holM = 0. Default value: holM = 0.
When dispr > 0, the k desired Ritz values along with the orresponding residual errors (2) are displayed ea h iteration; dispr = 0 inhibits
display of these quantities. Default value: dispr = 0.
A matrix of onverged eigenve tors. When the matrix eigve is
nonempty, the omputed eigenve tors are for ed to be orthogonal to
the olumns of the matrix eigve . No internal he king is performed to
determine if the olumns of eigve are mutually orthogonal or if they
are eigenve tors of the input matrix. Default value: eigve = [ .
A three-letter string spe ifying the strategy for sele ting the endpoint(s)
losest to the desired eigenvalues. Admissible values for endpt are:
'FLT' - endpoint(s) losest to the desired eigenvalues are sele ted at
ea h iteration independently of its (their) previous value(s).
The endpoints are allowed to \ oat."
'MON' - all endpoints vary monotoni ally, so that the dampening
intervals that make up the sets K are nested.
More details on how the parameter endpt ae ts the hoi e of the sets
K an be found in [Baglama et al. 2003. Default values: endpt = 'FLT'
if the parameter sigma has a numeri al value, and endpt = 'MON' if
sigma = 'SE' or sigma = 'LE'.
If an M-le is provided for the evaluation of matrix-ve tor produ ts
with the matrix A, then additional parameters that may be required to
ompute the matrix-ve tor produ ts an be provided by the parameter
funpar. This parameter an be numeri al, a hara ter, or a MATLAB
stru ture. The parameters for the M-le for the evaluation of matrixve tor produ ts must be given in the order (X; n; blsz; funpar ). The
M-le, alled Afun .m below, determines the output Y = AX . Default
value: funpar = [ .
Number of desired eigenvalues. Default value: k = 3.
Maximum number of restarts of the blo k-Lan zos method. Default
value: maxit = 100.
Maximum degree of the a eleration polynomial. Default values:
maxdpol = n if sigma has a numeri al value, and maxdpol = 200 if
sigma = 'SE' or sigma = 'LE'.
ACM Transa tions on Mathemati al Software, Vol. TBD, No. TBD, TBD 20TBD.

nbls

permM

sigma

sizint

tol
v0

zertyp

J. Baglama, D. Calvetti, and L. Rei hel

Number of steps of the blo k-Lan zos method between restarts at the
beginning of the omputations. The parameter spe ies the value of
m in (1). The value may be adjusted during the omputations, so
that better sets K, on whi h zeros of the a eleration polynomials are
allo ated, an be determined. The value of nbls may also be hanged
to redu e the storage requirement of the program; see [Baglama et al.
2003 for a dis ussion of the latter. Default value: nbls = 3. A larger
value of nbls may, but is not guaranteed to, redu e the number of
matrix-ve tor produ t evaluations required to satisfy the termination
riterion.
Permutation ve tor for the rows and olumns of the Hermitian positive denite matrix M in the generalized eigenvalue problem (6). The
Cholesky fa tor R of the matrix M (permM; permM ) is omputed, i.e.,
M (permM; permM ) = R R. Permutation of the rows and olumns of
M may redu e the ll-in produ ed during the Cholesky fa torization.
For instan e, the ve tor permM an be determined by the MATLAB
fun tion symamd. Default value: permM = 1: n, whi h gives no permutation.
A two letter string or a numeri al value spe ifying the lo ation of the
desired eigenvalues. Admissible values for the string are:
'LE' - irbleigs seeks to ompute the k largest eigenvalues,
'SE' - irbleigs seeks to ompute the k smallest eigenvalues.
When sigma has a numeri al value, irbleigs seeks to ompute k eigenvalues in a vi inity of this value. Default value: sigma = 'LE'.
Size of the intervals that ontain zeros of the a eleration polynomials.
The intervals are smallest when sizint = 1 and largest when sizint =
(nbls 1)blsz k . The length of the intervals grows with the integervalued parameter sizint 2 [1; (nbls 1)blsz k . The exa t sizes of the
intervals depends on the distribution of omputed Ritz and harmoni
Ritz values of A. More details on how the parameter sizint ae ts the
length of the intervals an be found in [Baglama et al. 2003. Default
value: sizint = 1.
Toleran e used for onvergen e he k. The value of tol spe ies the
value of  in (3). Default value: tol = 1
10 6 .
A matrix of blsz orthonormal starting ve tors. By default, the blsz
olumns of v0 are determined by orthogonalizing the olumns generated
by the MATLAB fun tion randn(n; blsz). This fun tion determines an
n  blsz matrix whose entries are random numbers from the standard
normal distribution.
A two-letter string that spe ies how the zeros of the a eleration polynomial are sele ted. Admissible values for the string are:
'WL' - weighted fast Leja points,
'ML' - mapped fast Leja points. Fast Leja points are omputed for
the interval [ 2; 2 and mapped to the interval K. This
option is not available when sigma has a numeri al value.
Default values: 'ML' if sigma = 'SE' or sigma = 'LE', and 'WL' if
sigma has a numeri al value.

ACM Transa tions on Mathemati al Software, Vol. TBD, No. TBD, TBD 20TBD.

irbleigs:

A program for omputing a few eigenpairs of a large Hermitian matrix

The parameter values for irbleigs an be supplied via a MATLAB stru ture
with the eld values as parameter names. This allows a user to supply and hange
parameter values easily; see Se tion 4 for examples. The input order is
(A; M; OPTS )

or

('Afun '; n; M; OPTS );

(8)

where the rst input argument is either an n  n Hermitian matrix, here denoted
by A, or the name of an M-le, here alled Afun .m, for the evaluation of matrixve tor produ ts with the matrix A. Note that if the rst argument is the name of
an M-le, then the se ond argument must be the order n of the matrix.
The parameter denoted by M in (8) is optional; if it is omitted then eigenpairs
of the matrix A are omputed. If the parameter M is in luded and the input
parameter holM = 0, then eigenpairs of the generalized eigenvalue problem (6)
are determined, where M is a Hermitian positive denite matrix. In the latter
ase, irbleigs omputes the Cholesky fa torization of M by alling the MATLAB
fun tion hol; see also the dis ussion of the parameter permM. Finally, if the
parameter M is in luded and holM > 0, then M is assumed be the Cholesky fa tor
R of the Hermitian positive denite matrix in the right-hand side of (6).
The input argument OPTS in (8) is optional. If supplied, it is a MATLAB
stru ture that ontains some or all of the input parameters in arbitrary order; see
Se tion 4 for illustrations.
The M-le Afun .m for evaluating the matrix-ve tor produ ts with the matrix A
an be written in MATLAB, C or FORTRAN. In the latter ases, it is interfa ed
with MATLAB using MEX les; see [MathWorks 1998. The M-le Afun .m must
take an n  blsz matrix X as the rst input argument, the integer n as the se ond
input argument, blsz as the third input argument and funpar as an optional fourth
argument; see the dis ussion related to the parameter funpar. Afun .m must return
the produ t AX .
There are four available output options:
irbleigs(A; M; OPTS ): Displays the desired eigenvalues.
e

= irbleigs(A; M; OPTS ): Returns the desired eigenvalues in the ve tor e.

[V; D = irbleigs(A; M; OPTS ): Returns the matri es V and D, where D is

a diagonal matrix that ontains the desired eigenvalues along the diagonal and the
olumns of the matrix V ontain the orresponding orthonormal eigenve tors, su h
that AV = V D.
[V; D; EXITINFO = irbleigs(A; M; OPTS ): Returns the matri es V and D des ribed above, as well as the array EXITINFO with two entries. EXITINFO(1) = 0
signals normal exit from irbleigs; k eigenpairs have been omputed with desired
a ura y. The number of matrix-ve tor produ t evaluations with the matrix A is reported in EXITINFO(2). One evaluation of the produ t AX , where X is an n  blsz
matrix, ounts as blsz matrix-ve tor produ t evaluations. If EXITINFO(1) = 1,
then the maximum number of iterations, spe ied by the parameter maxit, have
been arried out, but the k desired eigenpairs have not been omputed with spe ied a ura y. In this situation, the matri es V and D ontain Ritz pairs that
ACM Transa tions on Mathemati al Software, Vol. TBD, No. TBD, TBD 20TBD.

J. Baglama, D. Calvetti, and L. Rei hel

approximate wanted eigenpairs, but not all of them have been determined with
spe ied a ura y. We remark that the parameter nbls might in rease or de rease
during the iterations and therefore the number of matrix-ve tor produ t evaluations
with the matrix A might not be equal to the number of iterations times the input
parameters nbls and blsz. Thus, if the program exits with EXITINFO(1) = 1, then
the number of matrix-ve tor produ t evaluations reported in EXITINFO(2) might
not equal maxit  nbls  blsz be ause nbls might have hanged during the iterations.
The rst three output options listed above return empty arrays if the maximum
number of iterations, spe ied by the parameter maxit, is rea hed before k eigenpairs have been determined with desired a ura y. Only the last output option,
whi h in ludes the array EXITINFO, yields Ritz pairs when the maximum number of iterations is rea hed before all wanted Ritz pairs have been omputed with
desired a ura y. These Ritz pairs an be used in a subsequent run of irbleigs to
improve their a ura y; see Se tion 4 for an illustration.
4.

SAMPLE EXPERIMENTS

In this se tion we present a few alling sequen es for irbleigs and the orresponding output. All experiments were arried out using MATLAB version 6.0, with
pat hes from The MathWorks to remedy the memory leakage, on a Gateway E5200 workstation with two 450 MHz (512k a he) Pentium III pro essors and 128
MB (100 MHz) of memory. In all experiments reported below, A is a 100  100
matrix obtained by dis retizing the 2-dimensional negative Lapla e operator on the
unit square by the standard 5-point sten il with Diri hlet boundary onditions.
This matrix an be generated in MATLAB with the ommand
>> A = delsq(numgrid('S',12));

Note that MATLAB stores the matrix A in sparse format. The ommand
>> irbleigs(A)

makes irbleigs ompute the 3 largest eigenvalues of

for all parameters. The output is

using the default values

eigenvalues =
7.8380
7.6015
7.6016

The parameter values an be hanged by using the stru ture OPTS, whose eld
values are the parameter names. For example, to ompute the smallest eigenvalues
of A, the value of sigma should be set to 'SE'. This an be done by the ommand
>> OPTS = stru t('sigma','SE');

or by setting
>> OPTS.sigma = 'SE';

Subsequently, the ommand

>> irbleigs(A,OPTS)
ACM Transa tions on Mathemati al Software, Vol. TBD, No. TBD, TBD 20TBD.

irbleigs:

A program for omputing a few eigenpairs of a large Hermitian matrix

yields the 3 smallest eigenvalues of A:

eigenvalues =
0.1620
0.3985
0.3985

Other parameters may be hanged similarly. For instan e, to determine 4 eigenvalues near 2 using a blo k-size of 2 with, in general, 8 onse utive steps by the
blo k-Lan zos method between restarts, the following sequen e of ommands an
be used:
>>
>>
>>
>>

OPTS.sigma = 2;
OPTS.k = 4;
OPTS.blsz = 2;
OPTS.nbls = 8;

Then the ommand

>> irbleigs(A,OPTS)

yields
eigenvalues =
1.8594
1.8594
2.0329
2.0329

If both eigenvalues and eigenve tors are desired, then irbleigs should be alled as
follows:
>> [V,D = irbleigs(A,OPTS);

The omputed eigenvalues make up the diagonal entries of the diagonal matrix D
and the orresponding omputed orthonormal eigenve tors are the olumns of the
matrix V .
Assume for the moment that an M-le alled Afun .m is available that takes as
input (X; 100; blsz), where X is a 100  blsz matrix, and yields the matrix Y = AX
as output. The ommand
>> [V,D = irbleigs('Afun ',100,OPTS);

yields the eigenpairs of A spe ied by the stru ture OPTS.

In order to ompute a few eigenpairs of a generalized eigenvalue problem (6) a
user must provide the matri es A and M . The Hermitian matrix A an be supplied
as des ribed above. The matrix M must be Hermitian and positive denite. Either
the matrix M or its Cholesky fa tor are supplied in numeri al format, with the
parameter holM hosen a ordingly. For instan e, the ommands
>> M = diag(1:100);
>> irbleigs(A,M)

yield the output

ACM Transa tions on Mathemati al Software, Vol. TBD, No. TBD, TBD 20TBD.

10

J. Baglama, D. Calvetti, and L. Rei hel

eigenvalues =
4.2525
2.0466
1.3617
irbleigs returns the 3 largest eigenvalues of the generalized eigenvalue problem

using default parameter values. If we instead would like to ompute 5 eigenvalues

near 0:2, then we issue the ommands
>> OPTS.sigma = 0.2;
>> OPTS.k = 5;
>> irbleigs(A,M,OPTS)

and obtain the output

eigenvalues =
[

The missing output indi ates that irbleigs did not nd the desired eigenvalues
of the generalized eigenvalue problem with the spe ied values of the parameters
k and sigma, and the default values of the remaining input parameters. Changing
the output option to [V; D; EXITINFO allows irbleigs to output approximate
Ritz pairs in the matri es D and V . Thus,
>> [V,D,EXITINFO = irbleigs(A,M,OPTS);
>> EXITINFO

yields
EXITINFO =
1 1191

The value 1 of EXITINFO(1) shows that the maximum number of iterations have
been arried out, and the value 1191 of EXITINFO(2) displays the number of
matrix-ve tor produ t evaluations with the matrix A that have been arried out
before exit. Note that EXITINFO(2) is larger than maxit  nbls  blsz = 900,
be ause in order to determine a suitable set K, irbleigs in reased the value of
nbls from 3 to 4 at the 4th restart of the blo k-Lan zos pro ess.
The matri es V and D ontain approximate eigenpairs. In reasing the value of
blsz to 5 and letting the parameter v0 be equal to the matrix V ,
>> OPTS.blsz = 5;
>> OPTS.v0 = V;
>> irbleigs(A,M,OPTS)

yields the desired output

eigenvalues =
0.1758
0.1803
0.1882
0.2065
0.2099
ACM Transa tions on Mathemati al Software, Vol. TBD, No. TBD, TBD 20TBD.

irbleigs:

A program for omputing a few eigenpairs of a large Hermitian matrix

11

Note that blsz must be in reased to 5, otherwise an error message will be printed
saying that the starting matrix is of the wrong size, followed by program exit. An
alternate approa h to determining the desired eigenpairs is to in rease the values
of the parameters nbls and maxit.
A knowledgement. We would like to thank Ri hard Lehou q, Axel Ruhe and
Mike Saunders for valuable omments.
REFERENCES
2000. Dealing with linear dependen e during the iterations of the restarted blo k
Lan zos methods. Numer. Algorithms 25, 23{36.
Baglama, J., Calvetti, D., and Rei hel, L. 1996. Iterative methods for the omputation of a
few eigenvalues of a large symmetri matrix. BIT 36, 400{421.
Baglama, J., Calvetti, D., and Rei hel, L. 2003. IRBL: An impli itly restarted blo k Lan zos
method for large-s ale Hermitian eigenproblems. SIAM J. S i. Comput. 24, 1650{1677.
Baglama, J., Calvetti, D., Rei hel, L., and Ruttan, A. 1998. Computation of a few small
eigenvalues of a large matrix with appli ations to liquid rystal modeling. J. Comput. Phys. 146,
203{226.
Calvetti, D., Rei hel, L., and Sorensen, D. C. 1994. An impli itly restarted Lan zos method
for large symmetri eigenvalue problems. Ele . Trans. Numer. Anal. 2, 1{21.
Lehou q, R. B., Sorensen, D. C., and Yang, C. 1998. ARPACK Users' Guide: Solution of
Large-S ale Eigenvalue Problems with Impli itly Restarted Arnoldi Methods. SIAM, Philadelphia. Code available at web site http://www. aam.ri e.edu/software/ARPACK.
MathWorks. 1998. MATLAB Appli ation Program Interfa e Guide, Version 5.
Sorensen, D. C. 1992. Impli it appli ation of polynomial lters in a k -step Arnoldi method.
SIAM J. Matrix Anal. Appl. 13, 357{385.
Baglama, J.

ACM Transa tions on Mathemati al Software, Vol. TBD, No. TBD, TBD 20TBD.