Matrix Eigensystem Routines - EISPACK Guide Extension (Lecture Notes in Computer Science, Vol. 51)

Lecture Notes ~n Computer Science Edited by G. Goos and J. Hartmanis

51 B. S. Garbow J. M. Boyle J. J. Dongarra C. B. Moler

Matrix Eigensystem Routines EISPACK Guide [~ension

Editorial Board P. Brinch Hansen, O. Gries, C. Moter, G. SeegmfJtter, J. Stoer, N. Wirth

Author Burton S. G a r b o w Applied Mathematics Division A r g o n n e National Laboratory 9 7 0 0 South C a s s A v e n u e Argonne, Illinois 6 0 4 3 9 U S A

Library of Congress Cataloging in Publication Da~a

Main entry under title: Matrix eigensystem routines. (Lecture notes i_n computer science ~ 51) Supplements the 2d. ed of Matrix eigeneystem routines : EISPACK guide. i. EZSPACK (Computer program) I. Garbow~ B. S.~ 1930II. Series. QAI9~.M38 001.6'425 77-2802

AMS Subject Classifications (1970): 15A18, 65F15 CR Subject Classifications (1974): 5.14 ISBN 3-540-08254-9 Springer-Verlag Berlin • Heidelberg • New York ISBN 0-387-08254-9 Springer-Verlag New York • Heidelberg • Berlin This work is subject to copyright. All rights are reserved, whether the whole or part of the material is concerned, specifically those of translation, reprinting, re-use of illustrations, broadcasting, reproduction by photocopying machine or similar means, and storage in data banks. Under § 54 of the German Copyright Law where copies are made for other than private use, a fee is payable to the publisher, the amount of the fee to be determined by agreement with the publisher. © by Springer-Vertag Berlin - Heidelberg 1977 Printed in Germany Printina and bindina: Beltz Offsetdruck, Hemsbach/Bergstr.

PREFACE

This volume supplements the earlier Volume 6 in this series [i0]; together they provide guidance for the complete second release of the EISPACK Eigensystem Package. classes:

The stress in this book is on four additional problem

the sylmnetric band eigenproblem, the generalized symmetric elgen-

problem, the generalized real eigenproblem, and the singular value decomposition of a rectangular matrix and solution of an associated linear least squares problem. The organization of material in this volume follows closely that of [i0].

Several of the newer problems transform to problems covered earlier

in [i0]; reference should be made there for details that apply after the problem has been transformed.

Towards achieving a certain degree of self-

sufficiency, however, the documentation for seven earlier subroutines that recur here in the various recommended paths of Section 2 has been recopied in Section 7.1 of this volume. The EISPAC control program, available with the IBM version of EISPACK, extends to each of the newer problem classes except Singular Value Decomposition; the discussion of its usage, where applicable, is integrated into the various sections of this volume.

Its documentation, earlier provided

in [I0], has been recopied in Section 7.2 of this volume. EISPACK is a product of the NATS (N__ationalActivity to ~est ~oftware) Project ([3],[4],[5]) which has been guided by the principle that the effort to produce high quality mathematical software is justified by the wide use of that software in the scientific community.

EISPACK has been

distributed to several hundred computer centers throughout the world since the package was first released in May, 1972, and now the second release is available as described in Section 5.

Building a systematized collection of mathematical software is necessarily a collaborative undertaking demanding the interplay of a variety of skills; we wish to acknowledge a few whose roles were especially crucial during the preparation of the second release.

J. Wilkinson persisted in his encourage-

ment of the project and his counsel was often sought during his frequent visits to North Americas J. Pool.

Organization and direction came from W. Cowell and

B. Smith and V. Klema provided highly valued consultation.

The

field testing was carried out at the installations listed in Section 5 through the sustained efforts of M. Berg, A. Cline, D. Dodson, B. Einarsson, S. Eisenstat, I. Farkas, P. Fox, F. Fritsch, C. Frymann, G. Haigler, H. Happ, L. Harding, M. Havens, H. Hull, D. Kincaid, P. Messina, M. Overton, R. Raffenetti, J. Stein, J. Walsh, and J. Wang.

Additional assistance in providing the timing informa-

tion for the tables of Section 4 was given by T. Pinter.

Appreciation is also

expressed for the very important feedback received from users not formally associated with the testing effort.

Finally, we acknowledge the skill and

cooperation of our typist, J. Beumer.

Work performed under the auspices of the United States Energy Research and Development Administration and the National Science Foundation.

iV

TABLE OF CONTENTS

SECTION i INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i.

Organization

of the guide . . . . . . . . . . . . . . . . . . . . .

2.

Accuracy of the EISPACK subroutines

................

SECTION 2 HOW TO USE EISPACK . . . . . . . . . . . . . . . . . . . . . . . . . . .

i.

Recommended basic paths in EISPACK . . . . . . . . . . . . . . . . . i.I

13 15

1.2

All eigenvalues of a real symmetric hand matrix

1.3

Some eigenvalues and corresponding eigenvectors of a real symmetric band matrix . . . . . . . . . . . . . . .

17

1.4

Some eigenvalues

20

1.5

All eigenvalues and corresponding eigenvectors of a generalized real symmetric matrix system . . . . . . . .

22

All eigenvalues of a generalized real symmetric matrix system . . . . . . . . . . . . . . . . .

24

Some eigenvalues and corresponding eigenvectors of a generalized real symmetric matrix system . . . . . . . .

26

Some eigenvalues of a generalized real symmetric matrix system . . . . . . . . . . . . . . . . .

28

All eigenvalues and corresponding eigenvectors of a generalized real matrix system . . . . . . . . . . . . .

30

All eigenvalues

32

1.6

1.7

1.8

1.9

1.10

2.

All eigenvalues and corresponding eigenvectors of a real symmetric band matrix . . . . . . . . . . . . . . .

Variations

.......

of a real symmetric band matrix . . . . . . .

of a generalized

real matrix system . . . . .

of the recommended EISPACK paths

............

2.1

The QR algorithm for real symmetric band matrices

2.2

Variants of the real symmetric generalized

V

34

......

eigenproblem

35 . . .

37

3.

. . . . . . . . . . . . . . . .

40

The representation of the eigenvalues of a generalized real matrix system . . . . . . . . . . . . .

41

Unpacking the eigenvectors of a generalized real matrix system . . . . . . . . . . . . . . . .

43

3.3

The EPSI parameter . . . . . . . . . . . . . . . . . . . . . .

45

3.4

Possible ill-condition of the generalized real symmetric eigenproblem paths . . . . . . . . . . . . . .

48

3.5

Higher degree eigenvalue problems

49

3.6

The use of BANDV in solving band systems of linear equations . . . . . . . . . . . . . . . . . . . . .

51

3.7

Additional facilities of the EISPAC control program . . . . .

52

3.8

Non-zero values of IERR . . . . . . . . . . . . . . . . . . .

58

3.9

Examples illustrating the use of the EISPACK subroutines and the control program . . . . . . . . . . . . .

60

Singular Value Decomposition with EISPACK . . . . . . . . . . . . .

69

4.1

The Singular Value Decomposition and rank estimation . . . . .

70

4,2

Subroutines SVD and MINFIT . . . . . . . . . . . . . . . . . .

72

4.3

The pseudo-inverse of a rectangular matrix . . . . . . . . . .

74

4.4

Least squares solutions of minimal norm . . . . . . . . . . .

75

4.5

Homogeneous linear equations . . . . . . . . . . . . . . . . .

76

Additional information and examples 3.1

3.2

4.

. . . . . . . . . . . . . .

SECTION 3 VALIDATION OF EISPACK . . . . . . . . . . . . . . . . . . . . . . . . .

77

SECTION 4 EXECUTION TIMES FOR EISPACK . . . . . . . . . . . . . . . . . . . . . .

80

!.

Tables of execution times . . . . . . . . . . . . . . . . . . . . .

81

2.

Repeatability and reliability of the measured execution times , . .

121

3.

Dependence of the execution times upon the matrix system . . . . . .

122

VI

4.

E x t r a p o l a t i o n of timing results to other m a c h i n e s and compilers

5.

Timing c o n s i d e r a t i o n s for band p r o b l e m s and singular value decomposition . . . . . . . . . . . . . . . . . . . .

126

The sample m a t r i c e s for the timing results . . . . . . . . . . . . .

129

6.

. .

124

SECTION 5 C E R T I F I C A T I O N A N D A V A I L A B I L I T Y OF E I S P A C K . . . . . . . . . . . . . . .

131

SECTION 6 D I F F E R E N C E S B E T W E E N THE E I S P A C K SUBROUTINES A N D THE H A N D B O O K A L G O L P R O C E D U R E S . . . . . . . . . . . . . . . . . . .

133

SECTION 7 D O C U M E N T A T I O N AND SOURCE L I S T I N G S

. . . . . . . . . . . . . . . . . . .

135

i.

EISPACK subroutines

. . . . . . . . . . . . . . . . . . . . . . . .

137

2.

EISPAC control p r o g r a m . . . . . . . . . . . . . . . . . . . . . . .

314

Vii

L I S T OF TABLES i.

S e c t i o n s d e s c r i b i n g the r e c o m m e n d e d b a s i c paths in E I S P A C K o . .

12

2.

ISUBNO v a l u e s and p a r a m e t e r names for s u b r o u t i n e calls f r o m EISPAC . . . . . . . . . . . . . . . . . .

56

3.

Summary of v a l u e s of IERR . . . . . . . . . . . . . . . . . . . .

59

4-5.

E x e c u t i o n times o n the I B M 370/195 at Argonne National Laboratory . . . . . . . . . . . . . . . . . . .

84

6-7.

E x e c u t i o n times on the IBM 360/75 at U n i v e r s i t y of Illinois,

8-9.

E x e c u t i o n times o n the I B M 360/65 at A m e s L a b o r a t o r y

. .

86 88

......

I0-ii.

E x e c u t i o n times on the I B M 370/165 at The U n i v e r s i t y of Toronto.

90

12-13.

E x e c u t i o n times on the IBM 370/168 M o d 3 at Stanford University.

92

14-15.

E x e c u t i o n times on the B u r r o u g h s 6700 at U n i v e r s i t y of C a l i f o r n i a , San D i e g o . . . . . . . . . . . . . . .

94

16-17.

E x e c u t i o n times o n the CDC 6600 at K i r t l a n d A i r F o r c e B a s e . . .

96

18-19.

E x e c u t i o n times on the CDC C Y B E R 175 at N A S A L a n g l e y R e s e a r c h Center . . . . . . . . . . . . . . . . . .

98

20-21.

E x e c u t i o n times on the CDC 7600 at N a t i o n a l C e n t e r for A t m o s p h e r i c R e s e a r c h

100

. . . . . . . . . . . .

22-23.

E x e c u t i o n times on the CDC 7600 at Lawrence Livermore Laboratory . . . . . . . . . . . . . . . . . .

102

24-25.

E x e c u t i o n times o n the CDC 6400 at N o r t h w e s t e r n U n i v e r s i t y

104

26-27.

E x e c u t i o n times o n the CDC 6 4 0 0 / 6 5 0 0 at P u r d u e U n i v e r s i t y . . . .

28-29.

E x e c u t i o n times on the CDC 6 6 0 0 / 6 4 0 0 at T h e U n i v e r s i t y of Texas.

30-31.

E x e c u t i o n times on the H o n e y w e l l 6070 at Bell L a b o r a t o r i e s

32-33.

E x e c u t i o n times on the U n i v a c IIi0 at The University of Wisconsin . . . . . . . . . . . . . . . . . . .

34-35.

E x e c u t i o n times o n the DEC K A - P D P - 1 0 at Y a l e U n i v e r s i t y . . . . .

36-37.

E x e c u t i o n times on the A m d a h l 470V/6 at U n i v e r s i t y of M i c h i g a n

. . .

106

. . .

108 110

112 114 .

116

38.

E x e c u t i o n times for the E I S P A C K d r i v e r subroutines, SVD and M I N F I T over v a r i o u s c o m p u t e r systems . . . . . . . . . .

118

39.

E x e c u t i o n times for the E I S P A C control p r o g r a m on the IBM 370/195 at A r g o n n e N a t i o n a l L a b o r a t o r y . . . . . . . . . . .

120

VIII

1.0-i

Section i INTRODUCTION

The subset of the EISPACK package of Fortran IV programs included within this volume is a systematized collection of subroutines which compute the eigenvalues and/or eigenvectors for three special classes of matrix problems and the singular value decomposition of an arbitrary matrix.

The three

problem classes are real symmetric band, generalized real symmetric, and generalized real.

The singular value decomposition, in turn, enables the

solution of certain linear least squares problems.

The subroutines are

based mainly upon Algol procedures published in the Handbook series of Springer-Verlag by Wilkinson and Reinsch [i] and the QZ algorithm of Moler and Stewart [8] as extended by Ward [9]. They have been adapted and thoroughly tested on several different machines, and have been certified and are supported by the NATS project [3,4,5].

The machines for which they are

certified include IBM 360-370, CDC 6000-7000, Univac iii0, Honeywell 6070, DEC PDP-10, and Burroughs 6700. This manual is a user guide to these newer capabilities of EISPACK (complementing [i0]) and to a control program EISPAC available with the IBM version of the package.

It contains program segments which illustrate

each of the basic computations with EISPACK and discusses variants of these that provide mild tradeoffs of efficiency, storage, and accuracy. Other sections of the guide discuss the validation procedures used for testing EISPACK, report execution times of the EISPACK subroutines on several machines, advertise the certified status and availability of EISPACK, and describe the major differences between the published Algol procedures in [i] and their Fortran counterparts.

The final section includes detailed

documentation with Fortran listings of each EISPACK subroutine referenced herein and the document for the control program.

I.i-i

Section i.I ORGANIZATION OF THE GUIDE

This guide is organized for the convenience,

hopefully, of the user.

Material most pertinent to the basic uses of the package and the control program appears in the early sections and references the more detailed and specific information in later sections.

Here follows a brief description

of the organization of the guide. The remaining subsection of this introduction is a general statement with regard to the expected accuracy of the results from EISPACK.

This

statement is based upon the careful and detailed analyses of Wilkinson and others.

Only a brief overview is provided in this subsection and the

interested reader is directed to [I] and [2] for more detailed statements of accuracy. Section 2 is divided into a prologue and four major subsections.

The

prologue introduces the concept of an EISPACK path, discusses the economies that can be realized with the use of the control program if available, instructs on the selection among the I0 basic paths of this volume. first subsection establishes several conventions fying the discussions of the paths.

and

The

that are useful in clari-

It then details the i0 basic paths

and associated control program calls in the form of program segments.

Each

program segment is introduced by a brief description of the problem it solves and any specific considerations needed for the path, and is followed by a summary of array storage requirements for the path and sample execution times on the IBM 370/195 computer.

The next subsection describes possible

variants of the i0 basic paths, focusing on those conditions for which the variants are to be preferred.

The third subsection provides further infor-

mation about specific details of EISPACK and the control program and

i.i-2

suggests several additional applications of the package.

Complete sample

programs illustrating the use of EISPACK and EISPAC to solve a specified eigenproblem appear at the end of this subsection.

The last subsection

describes the EISPACK capabilities to compute the singular value decomposition of a matrix and to solve an associated linear least squares problem. Section 3 outlines the validation procedures for EISPACK that led to the certification of the package.

Section 4 reports sample execution

times of the individual subroutines and of several of the program segments of Section 2 and also discusses such considerations as the dependence of the execution times upon the matrix and the computer.

The statement of

certification for EISPACK, the machines and operating systems on which it has been certified, and its availability appear in Section 5.

Section 6

itemizes the principal differences between the referenced Fortran subroutines and their Algol antecedents published in [i]. Finally, the documentation and Fortran listing for each subroutine appear in edited form in Section 7.

1.2-1

Section

1.2

ACCURACY OF THE EISPACK SUBROUTINES

The most useful statement of the EISPACK subroutines numerically

stable;

that can be made with regard to the accuracy

is that they are based on algorithms which are

that is, for every computed eigenpair

(%,z) associated

with a matrix A, there exists a matrix E with norm small compared of A for which % and z are an exact eigenpair problems,

the corresponding

the accuracy of the subroutines

properties

of the problem which,

approach also applies, For these problems

is necessitated

in general,

preclude

by the inherent

the more familiar

for real syrmnetric band matrices

and indeed is a consequence

the eigenvalues

also with

This backward or inverse approach in

describing

However,

For generalized

claim can be made after associating

B a matrix of small relative norm.

forward approach.

of A+E.

to that

the forward

of the backward analysis.

computed by EISPACK must be close to the

exact ones, but a similar claim for the eigenvectors

is not possible.

What

is true in this case is that the computed eigenvectors will be closely orthogonal if the subroutines

that accumulate

The size of E, of course, accuracy,

is crucial

the transformations to a meaningful

are used.

statement of

and the reader is referred to the detailed error analyses

Wilkinson and others

([i],[2]).

In our many tests of EISPACK,

of

we have sel-

dom observed an E with norm larger than a small multiple of the product of the order of the matrix or system, an appropriate norm, and the precision of the machine.

2.0-1

Section 2 HOW TO USE EISPACK

This section is designed to provide, in readily accessible form, the basic information you need to correctly use subroutines from EISPACK to solve an eigenproblem.

The way in which this information is presented

is influenced by the design of the eigensystem package; hence we will first consider briefly the global structure of EISPACK. EISPACK is capable of performing 32 different basic computations (22 of them described in [I0]), plus several variations of them.

If each of

these computations (and variations) were performed completely within a single EiSPACK subroutine, the package would be unwieldy indeed.

It also would

be highly redundant, since the same steps appear in many of the computations. To avoid these problems, the subroutines in EISPACK are designed so that each performs a basic step which appears in one or more of the computations. (See [7] for an introduction to the modularization of EISPACK.)

Consequently,

the redundancy (hence the size) of the package is minimized. Another consequence is that, in general, more than one subroutine from EISPACK is required to perform a given computation.

These subroutines must

of course be called in the correct order and with the proper parameters; in addition, some computations also require certain auxiliary actions, e.g., initializing parameters and testing for errors.

Throughout the re-

mainder of this book such an ordered set of subroutine calls and associated auxiliary actions will be called an EISPACK

path.

As a result of this structure the documentation for the use of EISPACK comprises two main parts:

a description of the basic paths and their var-

iations, and a description of the individual subroutines in EISPACK. information about the paths constitutes the remainder of this section

The

2.0-2

while the subroutine documentation The path descriptions

is collected

in Section 7.

are divided into three parts.

Section 2.1

describes

the i0 basic paths and includes a table to facilitate

to them.

Section 2.2 describes

suggests when such variations tain additional

some of the variations

might be useful.

zero error indicators

and the descriptions

it in Section 2.3.

Section 7.

Section 2.3 contains cer-

of the basic paths and their variants

have omitted much of the detailed information

may be obtained

of these paths and

information about and examples of the use of EISPACK.

keep the descriptions

collected

Detailed

will be sufficient

basic eigenproblems

simple, we

(e.g., the meanings

of certain parameters)

for the individual

that the information

to permit you to correctly

The detail of path information

is a driver subroutine

solve most eigenproblems.

is limited

driver sub-

only are desired.

There

for each class of problems handled by the package; to six of the i0 basic paths are

of the paths in this section.

further reduction in the detail of path information

you must know to solve an eigenprob!em, achieved by use of a control program,

with wider applicability,

[6].

this control program on those computing

quately support execution-time straightforward

that

can be

called EISPAC, which is available

with the IBM version of the eigensystem package

relatively

Applica-

to those problems where all

or all eigenvalues

given as part of the discussion

to implement

in

that you must know to solve certain

driver subroutine calls corresponding

Substantial

and

given in this section

routine to build the desired path from other EISPACK members.

and eigenvectors

of non-

subroutines

can be reduced by using an appropriate

bility of the driver subroutines

To

information about each subroutine

from the documentation

We hope, however,

eigenvalues

reference

(It is only practical systems which ade-

loading of subroutines.)

problem description

EISPAC accepts a

stated in terms of the

2.0-3

properties

of the input matrix or system and the kinds of results required.

It checks this description for consistency,

automatically

selects and

executes the appropriate path, and then returns the results to your program.

Thus EISPAC not only simplifies the use of the eigensystem package,

but also enhances

its robustness by eliminating

errors in transcribing

the possibility

of making

a path.

To use EISPAC, you call it with a set of parameters which describes the problem you wish to solve, and which enables EISPAC to choose the appropriate

path.

EISPAC calls corresponding

most of their variations)

to the i0 basic paths

(and

are given as a further part of the discussion

of the paths in this section.

Note that in order to use EISPAC, you must

provide system control cards defining the file from which the EISPACK subroutines

are to be loaded;

this and other detailed information on the

use of EISPAC can be found in its subroutine document in Section 7.2.

2.1-1

Section 2.1 RECOMMENDED

BASIC PATHS IN EISPACK

This section describes how to use EISPACK to compute some or all of the eigenvalues,

or some or all of the eigenvalues

ing eigenvectors,

for the three classes of problems mentioned

The paths recommended eigenproblems variations

and their correspond-

here provide accurate

using a minimum of storage.

of these paths

(using different

solutions

in Section I.

for their respective

Under some circumstances, subroutines)

slightly more accurate or speedier solutions;

may provide

these variations

are dis-

cussed in Section 2.2. To determine problem,

the recommended

path to solve your particular

consult Table 1 at the end of this section.

eigen-

First, decide to

which of the three classes listed across the top of the table your problem belongs.

In general,

the computation will be more accurate and efficient

if you use any known special properties it in the most specialized which is real symmetric is better classified the other hand,

of the matrix or system to place

applicable class.

Thus a generalized

(both A and B symmetric

problem

and B positive definite)

so, than as just real (but see Section 2.3.4).

some special properties

cannot be utilized;

On

for example,

advantage cannot be taken of the band form of a matrix unless it is symmetric as well. Next, determine which of the problem classifications left side of Table I most closely matches eigenvectors

you wish to find.

the subsection which describes variations

of the path exist,

listed down the

the subset of eigenvalues

The table entry so determined

and

indicates

the recormnended path for your problem.

(If

the subsection will refer you to Section

2.2 for them or to the corresponding

section of [i0].)

For example,

if

2.1-2

you have a real symmetric band matrix and you wish to find all its eigenvalues and their corresponding

eigenvectors,

the table directs you to Section 2.1.1.

Each subsection to which the table refers provides just the information you need to use the described path correctly. ment of the problem and an identification variables.

It begins with a state-

of the main input and result

The subroutine calls and auxiliary statements

the path are given and are followed by the corresponding call, if applicable, tional parameters the disposition

and the EISPAC call.

of addi-

(if any) appearing in the path and a brief summary of

for the arrays appearing of array s t o r a g e u s e d

4.)

driver subroutine

Next is a description

of the results of the computation.

timing results.

consttuting

Dimension

information

in the path and a summary of the total amount

is then given.

These are followed by indicative

(Timing considerations

are discussed more fully in Section

The subsection concludes with references

to applicable

subsections

of

Section 2.2 (or to !i0]). We have employed a few conventions the presentation parameters.

of information.

All parameters

in these subsections

One of these concerns the types of the

have their Fortran implied type:

ginning with I, J, K, L, M, or N are type INTEGER, will be called

working precision,

to streamline

those be-

and the others are what

which denotes either type REAL or type

DOUBLE PRECISION depending on the version of EISPACK being used. A second convention concerns certain parameters which are used only to pass intermediate

results from one subroutine to another.

of these parameters are not described in the subsections,

since only their

type and dimension need be known to execute a path correctly. tate recognition

of these parameters,

employing a systematic nomenclature.

The roles

To facili-

they are written in lower case, Their names are composed of f or i

2.1-3

to indicate type (working precision or integer), dimensionality

(scalar, vector,

or matrix),

is used for the first working precision

s, v, or m to indicate

and a serial number.

Thus

fvl

temporary vector to appear in a

given path. A third convention is used to indicate how the array parameters path are dimensioned. must be replaced stants.

It employs

three "variables"

in array declarator

to array declarator

statements

mb.

the values of these

It is of utmost importance

that whenever a path otherwise un-

errors will occur.

An example may help clarify using the path described

W(~),

the use of ~w and ~ .

in Section 2.1.7.

A, B, W, and Z, the dimension B(~,~),

there-

M M set to that used for ~ ,

is executed, N and, if used, M, satisfy N ~r~n and M i n ; predictable

mb, which

in the EISPACK subroutines;

fore NM must be set to the constant used for ~ , and MB to that used for

and

statements by Fortran integer con-

The parameters NM, Mi~, and MB communicate

constants

r~n, ~ ,

in a

and Z ( ~ , ~ ) .

information

Considering

Suppose you are only the parameters

is stated there as A ( ~ , ~ ) ,

If the largest system for which you intend

to use this path is of order 50, and if you do not expect to compute more than I0 eigenvalues

and eigenvectors,

you might use the array declarator

statement

DIMENSION A(50,50),B(50,50),W(10),Z(50,10)

together with

NM=

50

MM=

!0

You would,

of course,

set N to the actual order of the system for each

execution of the path; it must satisfy N ~ 50.

10

Similarly,

M will be set

2.1-4

(by the path)

to the number of eigenvalues

determined;

it must satisfy

M < i0. The surmnary of the total amount of array storage used by a path is given in terms of the order parameters N and M, rather than in terms of and ~ °

Thus it represents

the minimum array storage required to

execute the path for a given order matrix or system, achieved when r~ is equal to N and

mm

is equal to M.

Note that when using the EISPAC control

program you need not dimension any parameters which do not appear in the call to EISPAC

(i.e., those named according

since it allocates

them for you.

to the second convention above)

This does not, however,

reduce the minimum

storage required, which remains as indicated in the surmnary. A fourth convention eigenveetor

relates to the calls to subroutines

option, when eigenvalues

the formal parameter corresponding required,

is not referenced

only are computed.

that have an

In such a case

to the eigenvector matrix Z, although

in the subroutine;

appear instead at the corresponding

the variable name DUMMY will

position in the calling statement.

A final convention concerns the handling of execution errors in a path.

Certain EISPACK subroutines may fail to satisfactorily

their step of the computation;

in this case an error parameter,

sally denoted by IERR, is set to a non-zero value indicating error which occurred.

perform univer-

the type of

In many cases the execution of a path must not be

allowed to continue after such an error; hence a conditional branch to statement number 99999 is inserted in each path after each subroutine call which may set the parameter IERR. might be to print IERR and stop.

Appropriate

action at statement 99999

Each distinct error that can occur in

EISPACK produces one of a unique set of values for IERR. values of IERR and their meanings,

The possible

together with an indication of whether

or not any partial results have been correctly computed,

11

are summarized

in

2.1-5

Section 2.3.8; more detailed information on IERR can be obtained by consulting the documents for the individual subroutines.

If you are using EISPAC,

it will print a message describing any errors which occur and terminate execution, unless you elect to examine IERR as discussed in Section 2.3.7 and in the EISPAC document. In summary, to select the recommended EISPACK path to solve your eigenproblem, consult Table I and then read the subsection to which it refers in light of the above conventions.

Note that in order to ensure correct

execution of the path, you must, in addition to providing input data and result storage, do the following:

provide arrays for storage of inter-

mediate or temporary results, call the subroutines in the path in the correct order, pass parameters from one call to the next exactly as described, and perform certain auxiliary actions.

Alternatively,

if the

control program EISPAC is included in your version of EISPACK, you may simply call it and let it perform these tasks for you.

TABLE 1 SECTIONS DESCRIBING THE RECOMMENDED BASIC PATHS IN EISPACK

Class of Matrix or em

All Eigenvalues & Corresponding Eisenvectors All Eigenvalues Some Eigenvalues & Corresponding Eigenvectors Some Eigenvalues

Real Symmetric Band

Real Real Symmetric Generalized Generalized

2.1.1

2.1.5

2.1.9

2.1.2

2.1.6

2.1.10

2.1.3

2.1.7

--

2.1.4

2.1.8

--

12

2.1-6

Section 2.1.1 ALL EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A REAL SYMMETRIC BAND MATRIX

A real symmetric band matrix of order N and (half) band width MB can be presented to EISPACK as an MB-column array, with the lowest subdiagonal stored in the last N+I-MB positions of the first column, the next higher subdiagonal in the last N+2-MB positions of the second column, further subdiagonals similarly, and finally the principal diagonal in the last column.

Contents of storage locations not part of the matrix are arbitrary.

For example, when N = 5 and MB = 3, the array (designated A) should contain

*

*

A(I,I)

*

A(2,1)

A(2,2)

A(3,1)

A(3,2)

A(3,3)

A(4,2)

A(4,3)

A(4,4)

A(5,3)

A(5,4)

A(5,5)

where the subscripts for each element refer to the row and column of the element in the standard two-dimensional representation, and '*' denotes an arbitrary value. To determine all the eigenvalues W and their corresponding eigenvectors Z of a real symmetric band matrix A of order N and (half) band width MB, the recommended EISPACK path is:

CALL

BANDR(NM,N,MB,A,W,fvT,fvT,.TRUE.,Z)

CALL TQL2(NM,N,W,fvI,Z,IERR) IF (IERR .NE. O) GO TO 99999

or, using driver subroutine RSB:

CALL RSB (N-M,N,MB,A,W, I, Z,fvl ,fvl, IERR) IF (IERR .NE. O) GO TO 99999 13

2.1-7

or, using EISPAC:

CALL EISPAC(NM, N,MATRIX('REAL',A,'SYMMETRIC'),BAND(MB),VALUES(W),VECTOR(Z))

This path returns the eigenvalues in ascending order and a set of orthonormal eigenvectors; A is destroyed except for its last two columns which retain a copy of the tridiagonal matrix produced in the initial reduction. Note that if the hand matrix is already tridiagonal (MB = 2), EISPAC selects the more specialized tridiagonal path and may return slightly different eigenvalues and eigenvectors than the EISPACK path or driver subroutine RSB. Suitable dimensions for the arrays are:

A(r~n,mb), W(nm), Z(nm,~n), and

fvl (~). The array storage required to execute this path is N 2 + N(MB+2) working precision words. Indicative execution times for this path (run on an IBM 370/195) are .006, .033, .22, and 1.5 seconds for sample matrices of order and (half) band width (10,3), (20,6), (40,12), and (80,24) respectively.

Extrapolation

of these execution times for matrices of different (half) band widths is discussed in Section 4.5. A variant of this path substitutes the implicit for the explicit QL shift; see Section 2.2.3 of [i0].

14

2.1-8

Section 2.1.2 ALL EIGENVALUES OF A REAL SYMMETRIC BAND MATRIX

A real symmetric band matrix of order N and (half) band width MB can be presented to EISPACK as an MB-column array, with the lowest subdiagonal stored in the last N+I-MB positions of the first column, the next higher subdiagonal in the last N+2-MB positions of the second column, further subdiagonals similarly, and finally the principal diagonal in the last column.

Contents of storage locations not part of the matrix are arbitrary.

For example, when N = 5 and MB = 3, the array (designated A) should contain m

*

A(I,I)

*

*

A(2,1)

A(2,2)

A(3,1)

A(3,2)

A(3,3)

A(4,2)

A(4,3)

A(4,4)

A(5,3)

A(5,4)

A(5,5)

where the subscripts for each element refer to the row and column of the element in the standard two-dimensional representation, and '*' denotes an arbitrary value. To determine all the eigenvalues W of a real symmetric band matrix A of order N and (half) band width MB, the recommended EISPACK path is:

CALL BANDR(NM,N,MB,A,W,fVl,fv2,.FALSE. ,DUMMY) CALL TQLRAT(N,W,fv2,1ERR) IF (IERR .NE. 0) GO TO 99999

or, using driver subroutine RSB:

CALL RSB (NM,N ,MB ,A,W ,O ,DUMMY ,fv l ,fv 2 ,1ERR ) IF (IERR .NE. O) GO TO 99999

15

2. i-9

or, using EISPAC:

CALL EISPAC(NM,N,MATRIX('REAL',A,'SYMMETRIC'),BAND(MB),VALUES(W))

This path returns the eigenvalues in ascending order; A is destroyed except for its last two columns which retain a copy of the tridiagonal matrix produced in the initial reduction. Note that if the band matrix is already tridiagonal (MB = 2), EISPAC selects the more specialized tridiagonal path and may return slightly different eigenvalues than the EISPACK path or driver subroutine RSB. Suitable dimensions for the arrays are: and

A(nm,mb), W(nm),

fv1(nm),

fv2(~). The array storage required to execute this path is N(MB+3) working

precision words. Indicative execution times for this path (run on an IBM 370/195) are .002, o011, .061, and .38 seconds for sample matrices of order and (half) band width (10,3), (20,6), (40,12), and (80,24) respectively.

Extrapolation

of these execution times for matrices of different (half) band widths is discussed in Section 4.5. Variants of this path substitute the explicit or implicit for the rational QL shift; see Section 2.2.3 of [i0].

16

2. I-I0

Section 2.1.3 SOME EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A REAL SYMMETRIC BAND MATRIX

A real symmetric band matrix of order N and (half) band width MB can be presented to EISPACK as an MB-column array, with the lowest subdiagonal stored in the last N+I-MB positions of the first column, the next higher subdiagonal in the last N+2-MB positions of the second column, further subdiagonals similarly, and finally the principal diagonal in the last column.

Contents of storage locations not part of the matrix are arbitrary.

For example, when N = 5 and MB = 3, the array (designated A) should contain

*

*

A(I,I)

*

A(2,1)

A(2,2)

A(3,1)

A(3,2)

A(3,3)

A(4,2)

A(4,3)

A(4,4)

A(5,3)

A(5,4)

A(5,5)

where the subscripts for each element refer to the row and column of the element in the standard two-dimensional representation, and '*' denotes an arbitrary value. To determine the eigenvalues W in an interval ~xtending from P~LB to RUB, together with their corresponding eigenvectors Z, of a real symmetric band matrix A of order N and (half) band width MB, the recommended EISPACK path is:

17

2.1-11

DO I00 J = I, MB DO 50 1 = i, N fm2(l,J) 50

= A(I,J)

CONTINUE

I00 CONTIh~UE CALL

BANDR(NM,N,MB,A,fvl,fv2,fv3,.FALSE.,DUMMY)

EPSI = 0.0 CALL

BISECT(N,EPSI,fvl,fv2,fv3,RLB,RUB,MM,M,W, ivl,IEP~,~4,fv5)

IF (IERR .NE. 0) GO TO 99999 CALL

BANDV(NM,N,MB,fmI,0.O,M,W,Z,IERR,NV,fv6,fv5)

IF (IERR .NE. 0) GO TO 99999

or, using EISPAC:

CALL EISPAC(hrM, N,MATRIX(~REAL',A,'SYMMETRIC'), BAND(~),VALUES(W,MM,M,RLB,RUB),VECTOR(Z))

NV communicates

the dimension of the scratch array

fv6

and must be at

least N(2M~-I). The parameter computation.

EPSI is used to control

the accuracy of the eigenvalue

Setting it to zero or calling EISPAC without

the use of a default value suitable for most matrices.

supplying

it causes

Further information

about the use of EPSI can be found in Section 2.3.3 and in the BISECT and EISPAC documents. eigenvalues vided M ! M M ,

Upon completion

determined

to lie in the interval defined by RLB and RUB and, pro-

the eigenvalues

ing orthonormal

of the path~ M is set to the number of

eigenvectors

are in ascending

order in W and their correspond-

are in the first M columns of Z.

Note that,

should the computed M be greater than MM, BISECT sets IERR non-zero and does not compute any eigenvalues.

This path destroys A except for its last two

18

2.1-12 columns which retain a copy of the tridiagonal matrix produced in the initial reduction. Note that if the band matrix is already tridiagonal (MB = 2), EISPAC selects the more specialized tridiagonal path and may return slightly different eigenvalues and eigenvectors than the EISPACK path. Suitable dimensions for the arrays are:

fm1(~,mb),

fvT(~),

A(nm,mb), W ( ~ ) ,

Z(~,~),

fv2(~), fv3(~), fv4(~), fv5(~), fv6(nv),

and iv1(~).

The array storage required to execute this path is 4N(MB+I) + M(N+I) working precision words and M integer words. could be saved by transmitting

fv6

(N working precision words

to BISECT in place of

fv4.)

Indicative execution times for this path (run on an IBM 370/195), when computing all N eigenvalues and eigenvectors~ are .025, .13, 1.1, and ii seconds for sample matrices of order and (half) band width (10,3), (20,6), (40,12), and (80,24) respectively.

Extrapolation of these execution times

for cases where M is less than N or for matrices of different (half) band widths is discussed in Sections 4.1 and 4.5. A variant of this path substitutes the band symmetric QR algorithm for the tridiagonalization and bisection steps of BANDR and BISECT; see Section 2.2.1.

Other variants substitute the rational QR method for the bisection

process or allow the specification of boundary eigenvalue indices instead of an interval to the bisection process; see Sections 2.2.4 and 2.2.8 of

[10].

19

2.1-13

Section 2.1.4 SOME EIGENVALUES

OF A REAL SYMMETRIC BAND MATRIX

A real symmetric band matrix of order N and (half) band width MB can be presented

to EISPACK as an MB-column array, with the lowest subdiagonal

stored in the last N+I-MB positions subdiagonal subdiagonals column.

of the first column,

in the last N+2-MB positions similarly,

the next higher

of the second column,

and finally the principal

further

diagonal in the last

Contents of storage locations not part of the matrix are arbitrary.

For example~ when N = 5 and MB = 3, the array (designated A) should contain

where the subscripts

*

*

A(I,I)

*

A(2,1)

A(2,2)

A(3,1)

A(3,2)

A(3,3)

A(4,2)

A(4,3)

A(4,4)

A(5,3)

A(5,4)

A(5,5)

for each element refer to the row and column of the

element in the standard two-dimensional

representation,

and '*' denotes an

arbitrary value. To determine

the eigenvalues W in an interval extending

from RLB to

RUB of a real symmetric band matrix A of order N and (half) band width MB, the recommended

CALL

EISPACK path is:

BAI~DR(NM,N,MB,A,fvl,fv2,fv3,.FALSE.,DUMMY)

EPSI = 0°0 CALL

BISECT(N,EPSI,fvl,fv2,fv3,RLB,RUB,MM,M,W,ivi,IERR,fv4,fv5)

IF (IERR .NE. 0) GO TO 99999

or, using EISPAC:

20

2.1-14

CALL EISPAC(NM,N,MATRIX('REAL',A,'SYMMETRIC'), BAND (MB), VALUES (W,MM, M, RLB, RUB ))

The parameter EPSI is used to control the accuracy of the eigenvalue computation.

Setting it to zero or calling EISPAC without supplying it

causes the use of a default value suitable for most matrices.

Further infor-

mation about the use of EPSI can be found in Section 2.3.3 and in the BISECT and EISPAC documents.

Upon completion of the path, M is set to the number

of eigenvalues determined to lie in the interval defined by RLB and RUB and, provided M ! M M ,

the eigenvalues are in ascending order in W.

Note that,

should the computed M be greater than MM, BISECT sets IERR non-zero and does not compute any eigenvalues.

This path destroys A except for its last

two columns which retain a copy of the tridiagonal matrix produced in the initial reduction. Suitable dimensions for the arrays are:

fv2(nm), fv3(nm), fv4(nm), fv5(nm),

and

A(~,mb), W ( ~ ) , f v l ( ~ ) ,

ivl(rr~).

The array storage required to execute this path is N(MB+5) + M working precision words and M integer words. Indicative execution times for this path (run on an IBM 370/195), when computing all N eigenvalues, are .017, .061, .25, and 1.0 seconds for sample matrices of order and (half) hand width (10,3), (20,6), (40,12), and (80,24) respectively.

Extrapolation of these execution times for cases

where M is less than N or for matrices of different (half) band widths is discussed in Sections 4.1 and 4.5. A variant of this path substitutes the band symmetric QR algorithm for the tridiagonalization and bisection steps of BANDR and BISECT; see Section 2.2.1.

Other variants substitute the rational QR method for the bisection

process or allow the specification of boundary eigenvalue indices instead of an interval to the bisection process; see Sections 2.2.4 and 2.2.8 of [i0].

21

2.1-15

Section 2.1.5 ALL EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A GENERALIZED REAL SYMMETRIC MATRIX SYSTEM

The real generalized eigenproblem Az = lBz is further characterized as symmetric if both A and B are symmetric and B is positive definite (all positive eigenvalues).

To determine all the eigenvalues W and their corres-

ponding eigenvectors Z for the real symmetric generalized eigenproblem Az = hBz of order N, the recommended EISPACK path is:

CALL

REDUC(NM,N,A,B,fV2,1ERR)

IF (IERR °NE. 0) GO TO 99999 CALL

TRED2(NM,N,A,W,fvl,Z)

CALL

TQL2(NM,N,W,fvl,Z,IERR)

IF (IERR .NE. 0) GO TO 99999 CALL

REBAK(NM,N,B,fv2,N,Z)

or, using driver subroutine RSG:

CALL

RSG(NM, N,A,B,W,I,Z,2~I,fv2,1ERR)

IF (IERR ~NE. 0) GO TO 99999

or, using EISPAC:

CALL EISPAC(NM,N,MATA('REAL',A,'SYMMETRIC'),MATB('REAL',B,'SYMMETRIC', 'POSITIVE DEFINITE'),VALUES(W),VECTOR(Z))

This path returns the eigenvalues in ascending order and a set of eigenvectors normalized so that zTBz = I; it preserves the full upper triangle of B and the strict upper triangle of A. Suitable dimensions for the arrays are: Z(~,~),

fvl(nm),

and

fv2(r~).

22

A(~,~),

B(~,r~), W(~),

2.1-16

The array storage required to execute this path is 3N 2 + 3N working precision words.

However, for this particular path the eigenvectors can

overwrite the A matrix if the same array parameter is used for both A and Z, thereby reducing the storage required to 2N 2 + 3N working precision words. Indicative execution times for this path (run on an IBM 370/195) are .009, .049, .30, and 2.0 seconds for sample systems of order I0, 20, 40, and 80 respectively. A variant of this path substitutes the implicit for the explicit QL shift; see Section 2.2.3 of [I0]. Variants of the problem itself are discussed in Section 2.2.2 of this volume.

23

2.1-17

Section 2.1~6 ALL EIGENVALUES OF A GENEP~IIZED REAL SYMMETRIC MATRIX SYSTEM

The real generalized eigenproblem Az = hBz is further characterized as symmetric if both A and B are symmetric and B is positive definite (all positive eigenvalues).

To determine all the eigenvalues W for the real

symmetric generalized eigenproblem Az = hBz of order N, the recommended EISPACK path is:

CALL

REDUC(NM,N,A,B,fv2,1ERR)

IF (IERR .NE. 0) GO TO 99999 CALL

TREDI(NM,N,A,W,fVl,fv2)

CALL TQLRAT(N,W,fV2,1ERR) IF (IERR .NE. 0) GO TO 99999

or, using driver subroutine RSG:

CALL

RSG(NM,N,A,B,W,O,DUMMY,fvf,fv2,1ERR)

IF (IERR .NE. 0) GO TO 99999

or, using EISPAC:

CALL EISPAC(NM,N,MATA('REAL',A,'SYMMETRIC'),MATB('REAL',B,'SYMMETRIC ' , 'POSITIVE DEFINITE'),VALUES(W))

This path returns the eigenvalues in ascending order; it preserves the full upper triangle of B and the strict upper triangle of A. Suitable dimensions for the arrays are:

fvl(~),

and

A(~,r~n), B ( ~ , ~ ) ,

W(~),

fv2(~).

The array storage required to execute this path is 2N 2 + 3N working precision words.

24

2.1-18

Indicative execution times for this path (run on an IBM 370/195) are .004, .019, .Ii, and .64 seconds for sample systems of order i0, 20, 40, and 80 respectively. Variants of this path substitute the explicit or implicit for the rational QL shift; see Section 2.2.3 of [i0]. Variants of the problem itself are discussed in Section 2.2.2 of this volume.

25

2.1-19

Section 2.1.7 SOME EIGENVALUES AND CORRESPONDING SYMMETRIC MATRIX SYSTEM

The real generalized symmetric

EIGENVECTORS

To determine

and B is positive definite

for the real syn~netrie generalized

CALL

as

(all

the eigenvalues W in an interval ex-

tending from F~B to RUB, together with their corresponding

recommended

REAL

eigenproblem Az = %Bz is further characterized

if both A and B are symmetric

positive eigenvalues).

OF A GENERALIZED

eigenvectors

Z,

eigenproblem Az = %Bz of order N, the

EISPACK path is:

REDUC(NM,N,A,B,fNg,IERR)

IF (IERR .NE. 0) GO TO 99999 CALL

TREDI(NM,N,A,fvl,fv2,fv3)

EPSI = 0.0 CALL

BISECT(N,EPSI,fvl,fv2,fV3,RLB,RUB,MM,M,W,iVI,IERR,fv4,fv5)

IF (IERR .NE. 0) GO TO 99999 CALL

TiNVIT(NM,N,fVT,fv2,fV3,M,W,ivl,Z,IERR,fv4,fv5,fv6,fvT,fv8)

IF (IERR .NE. 0) GO TO 99999 CALL

TRBAKI(NM,N,A,fv2,M,Z)

CALL

REBAK(NM,N,B,fv9,M,Z)

or, using EISPAC:

CALL EISPAC(NM,N,MATA('REAL',A,'SYMMETRIC'),MATB('REAL',B,'SYMMETRIC', 'POSITIVE DEFINITE'),VALUES(W,MM,M,RLB,RUB),VECTOR(Z))

The parameter computation.

EPSI is used to control

the accuracy of the eigenvalue

Setting it to zero or calling EISPAC without supplying

causes the use of a default value suitable for most matrices.

it

Further in-

formation about the use of EPSI can be found in Section 2.3.3 and in the BISECT and EISPAC documents.

Upon completion of the path, M is set to the

26

2.1-20

number of eigenvalues determined to lie in the interval defined by RLB and RUB and, provided M ! M M ,

the eigenvalues are in ascending order in W and

their corresponding eigenvectors, normalized so that zTBz = 1.0, are in the first M columns of Z.

Note that, should the computed M be greater than MM,

BISECT sets IERRnon-zero and does not compute any eigenvalues.

This path

preserves the full upper triangle of B and the strict upper triangle of A. Suitable dimensions for the arrays are: Z(nm,mm),

f~,8(mn),

A(nm,~), B(n~t,nm), W(mm),

fvl(rbm), fv2(nm), fv3(ro~), fv4(~), fv5(r~m), fv6(row), fvT(rom), fvg(nm), and

ivl(mm).

The array storage required to execute this path is 2N 2 + 9N + M(N+I) working precision words and M integer words. Indicative execution times for this path (run on an IBM 370/195), when computing all N eigenvalues and eigenvectors, are .023, .088, .41, and 2.1 seconds for sample systems of order I0, 20, 40, ~nd 80 respectively. Extrapolation of these execution times for cases where M is less than N is discussed in Section 4.1. Variants of this path substitute the rational QR method or the implicit QL method for the bisection process, allow the specification of boundary eigenvalue indices instead of an interval to the bisection process, or combine the determination of the eigenvalues and eigenvectors of the tridiagonal form into a single subroutine; see Sections 2.2.4, 2.2.7, 2.2.8, and 2.2.5 of [i0]. Variants of the problem itself are discussed in Section 2.2.2 of this volume.

27

2.1-21

Section 2.1.8 SOME EIGENVALUES

OF A GENERALIZED REAL SYMMETRIC MATRIX SYSTEM

The real generalized as symmetric

eigenproblemAz

= hBz is further characterized

if both A and B are symmetric and B is positive definite

positive eigenvalues).

To determine

(all

the eigenvalues W in an interval ex-

tending from RLB to RUB for the real symmetric generalized

eigenproblem

Az = hBz of order N, the recommended EISPACK path is:

CALL

REDUC(NM,N,A,B,fV2,1ERR)

IF (IERR ~NE. 0) GO TO 99999 CALL

TREDI(NM,N,A,fvf,fv2,fv3)

EPSI = 0.0 CALL

BISECT(N,EPSI,fvl,fv2,fV3,RLB,RUB,~,M,W,ivI,IERR,fv4,fvS)

IF (IERR .NE. 0) GO TO 99999

or, using EISPAC:

CALL EISPAC(NM,N,MATA('REAL',A,'SYMMETRIC'),MATB('REAL',B,'SYMMETRIC', 'POSITIVE DEFINITE'),VALUES(W,MM,M,RLB,RUB))

The parameter EPSI is used to control the accuracy of the eigenvalue computation.

Setting it to zero or calling EISPAC without supplying

causes the use of a default value suitable for most matrices. information

it

Further

about the use of EPSI can be found in Section 2.3.3 and in the

BISECT and EISPAC documents. number of eigenvalues

Upon completion

determined

RUB and, provided M ! M M ,

of the path, M is set to the

to lie in the interval defined by RLB and

the eigenvalues

are in ascending order in W.

Note that~ should the computed M be greater than MM, BISECT sets IERR non-zero and does not compute any eigenvalues.

This path preserves

full upper triangle of B and the strict upper triangle of A.

28

the

2.1-22

Suitable dimensions for the arrays are:

fvl(nm), fv2(nm), fv3(nm), fv4(r~), fvS(n~),

A(nm,nm), B(nm,nm), W(mm), and

ivl(m~).

The array storage required to execute this path is 2N 2 + 5N + M working precision words and M integer words. Indicative execution times for this path (run on an IBM 370/195), when computing all N eigenvalues, are .019, .069, .29, and 1.3 seconds for sample systems of order I0, 20, 40, and 80 respectively.

Extrapolation of

these execution times for cases where M is less than N is discussed in Section 4.1. Variants of this path substitute the rational QR method for the bisection process or allow the specification of boundary eigenvalue indices instead of an interval to the bisection process; see Sections 2.2.4 and 2.2.8 of [i0]. Variants of the problem itself are discussed in Section 2.2.2 of this volume.

29

2.1-23

Section 2.1.9 ALL EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A GENERALIZED REAL MATRIX SYSTEM

To determine all the eigenvalues (ALFR,ALFI,BETA) and their corresponding eigenvectors Z for the real generalized eigenproblem Az = %Bz of order N, the r e c o ~ e n d e d EISPACK path is:

CALL QZHES(NM,N,A,B, oTRUE.,Z) CALL QZIT(NM,N,A,B,EPSi,oTRUE.,Z,IERR) CALL QZVAL(NM,N,A,B,ALFR,ALFI,BETA,.TRUE.,Z) IF (IERR .NE. 0) GO TO 99999 CALL QZVEC(NM, N,A,B,ALFR,ALFI,BETA, Z)

or, using driver subroutine RGG:

CALL RGG(NM,N,A,B,ALFR,ALFI,BETA, I,Z,IERR) IF (IERR .NE. 0) GO TO 99999

or, using EISPAC:

CALL EISPAC(NM,N,MATA(~REAL',A),MATB('REAL',B), VALUES(ALFR,ALFI,BETA),VECTOR(Z))

BETA is always non-negative~

The triplet (ALFR,ALFI,BETA) returned by

the path can be transformed to the eigenvalue itself by two divisions, ALFR/BETA to produce the real part and ALFI/BETA to produce the imaginary part.

The divisions are not performed within the programs because of the

possible loss of information content in those situations where B or both A and B are nearly singular or even singular (see Section 2~3.1). The parameter EPSI is used to control the accuracy of the eigenvalue computation.

Setting it to zero or calling EISPAC without supplying it

30

2.1-24

causes the use of a default value suitable for most systems.

Further

information about the use of EPSI can be found in Section 2.3.3 and in the QZIT and EISPAC documents. Pairs of complex eigenvalues are stored in consecutive elements of (ALFR,ALFI,BETA) with that member of the pair with positive imaginary part first.

The corresponding columns of Z contain the real and imaginary parts,

respectively, of the eigenvector associated with the eigenvalue of positive imaginary part.

See Section 2.3.2 for a discussion of the eigenvector

packing into Z. Each eigenvector of Z is normalized so that the modulus of its largest component is 1.0.

This path destroys A and B.

Suitable dimensions for the arrays are:

A(~,~),

B(~,r~), ALFR(~n),

ALFI(~), BETA(r~w), and Z(~,r~). The array storage required to execute this path is 3N 2 + 3N working precision words. Indicative execution times for this path (run on an IBM 370/195) are .026, .17, 1.0, and 7.0 seconds for sample systems of order i0, 20, 40, and 80 respectively.

31

2.1-25

Section 2.1.10 ALL EIGENVALUES

OF A GENERALIZED REAL MATRIX SYSTEM

To determine generalized

all the eigenvalues

(ALFR,ALFI,BETA)

for the real

eigenproblem Az = %Bz of order N, the recommended

EISPACK path

is:

CALL QZHES(NM,N,A,B,.FALSE.,DUMMY) CALL QZIT(NM,N,A,B,EPSI,.FALSE.,DUMMY,IERR) CALL QZVAL(NrM,N,A,B,ALFR,ALFI,BETA,.FALSE.,DUM~) IF (!ERR .NE. 0) C~ TO 99999

or, using driver subroutine RGG:

CALL RGG(NM,N,A,B~ALFR,ALFI,BETA,O,DUMMY,IERR) IF (IERR .NE. O) GO TO 99999

or, using EISPAC:

CALL EISPAC(NM,N,MATA('REAL',A),MATB('REAL',B),VALUES(ALFR,ALFI,BETA))

BETA is always non-negative. by the path can be transformed ALFR/BETA part~

(ALFR,ALFI,BETA)

returned

to the eigenvalue

itself by two divisions,

to produce the real part and ALFI/BETA

to produce the imaginary

The divisions

possible

The triplet

are not performed within the programs because of the

loss of information

content in those situations where B or both A

and B are nearly singular or even singular

(see Section 2.3.1).

The parameter EPSI is used to control the accuracy of the eigenvalue computation.

Setting it to zero or calling EISPAC without

supplying

causes the use of a default value suitable for most systems.

it

Further in-

formation about the use of EPSI can be found in Section 2.3.3 and in the QZIT and EISPAC documents.

32

2.1-26

Pairs of complex eigenvalues are stored in consecutive elements of (ALFR, ALFI,BETA) with that member of the pair with positive imaginary part first. This path destroys A and B. Suitable dimensions for the arrays are:

A(~,r~),

B(~,~),

ALFR(~),

ALFI(r~), and BETA(n). The array storage required to execute this path is 2N 2 + 3N working precision words. Indicative execution times for this path (run on an IBM 370/195) are .020, .II, .63, and 4.2 seconds for sample systems of order I0, 20, 40, and 80 respectively.

33

2.2-1

Section 2.2 VARIATIONS OF THE RECOMMENDED EISPACK PATHS

This section describes variants of the recommended paths given in Section 2.1,

These variants are obtained by modifying one or more of the

call or ancillary statements in the reco~nended paths; they provide some additional or alternate capability.

The variant paths are related to:

the

use of the QR algorithm for finding a few eigenvalues of real sy~mnetric band matrices; and the capacity for solving alternate representations of the real symmetric generalized eigenproblem.

The variant paths are described

in terms of modifications to the recommended paths; to illustrate the modifications,

examples of each of the variant paths are given,

34

2.2-2

Section 2.2.1 THE QR ALGORITHM FOR REAL SYMMETRIC BAND MATRICES

The recommended paths of Sections 2.1.1-2.1.4 for real symmetric band matrices all employ subroutine BANDR to first reduce the matrix to tridiagonal form, followed by an iterative step to determine the eigenvalues.

When the

problem requires only the determination of the eigenvalue nearest to a prescribed number and possibly a few neighbors, it may be advantageous to use subroutine BQR which applies the QR algorithm directly to the input matrix, thus telescoping the otherwise separate reduction and iterative steps. Subroutine BQR determines exactly one eigenvalue when called, but in so doing deflates the problem such that a further call can easily be made to determine another value.

In fact, the only action that the user needs to

take after storing the returned eigenvalue is to decrement the parameter specifying the order of the matrix and call BQR again. BQRwill matrix.

usually find the eigenvalue of smallest modulus of the input

If, more generally, the eigenvalue nearest to a prescribed number

T is desired, BQR can be presented an input matrix derived from the original matrix by shifting (diminishing) the diagonal elements by T; when T is added back to the eigenvalue of smallest modulus of the shifted matrix, one obtains the eigenvalue of the original matrix nearest to T.

In the execution of BQR,

further shifting is done, with accumulation of the shift into T, until the resultant matrix has a zero eigenvalue -- indeed has a zero final row and column, thus simultaneously isolating an eigenvalue and deflating to next lower order. As an example of the use of BQR, to find the two eigenvalues W(1) and W(2) nearest to 4.0 of a real symmetric band matrix A of order N and (half) band width MB, the following program segment might be used:

35

2.2-3

T=4.0 DO i00 i = i, N i00 A(I,I)

= A(I,Z) - T

R=0.O CALL

BQR(NM,N,MB,A,T,R, IERR,NV,fvl)

W(1) = T CALL BQR(NM,N-I ,MB ,A, T, R, IERR, NV, fvT) W(2) = T

R is used to decide when the last row and column of the current formed band matrix can be regarded

as negligible.

trans-

It should be set to zero

for the initial call and is reset in BQR to a value suitable for the subsequent call~ NV communicates

the dimension of the temporary array

at least 2 ~ 2 + 4 ~

fvl

which must be

- 3.

Suitable dimensions

for the arrays are A(~zn,mb)

The array storage required

and f v 7 ( 2 ~ 2 + 4 ~ - 3 ) .

to execute this path is MB(N+2MB+4)

- 3 work-

ing precision words. Indicative when computing are ~011, band width

~055,

execution

times for this subroutine

the single eigenvalue

(run on an IBM 370/195),

of a random matrix nearest

.30, and 2.0 seconds for sample matrices

(10,3),

of these execution

(20,6),

of order and (half)

(40,12), and (80,24) respectively.

times for matrices

of different

to T = 0.0

Extrapolation

(half) band widths is dis-

cussed in Section 4.5. If eigenvectors

corresponding

to the computed

eigenvalues

subroutine BANDV can be called exactly as in the recommended Section 2.1~3.

are desired,

path of

Here also the input matrix would have to be saved initially,

since BQR destroys

it.

The control program EISPAC does not use BQR. 36

2.2-4

Section 2.2.2 VARIANTS OF THE REAL SYMMETRIC GENERALIZED EIGENPROBLEM

The real symmetric generalized

eigenproblem Az = IBz, for which the

recommended basic paths of Sections 2.1.5-2.1.8 that can be solved with EISPACK;

namely,

apply, has two variants

the problems ABz = Iz and BAz = Iz.

Indeed, only two additional EISPACK members are invoked as can be seen from the following discussion. Since B is symmetric and positive definite, B = LL T exists, then transformed

enabling the problem Az = IBz to be rewritten Az = ILLTz and to an equivalent

A 1 = L-IAL -T and y = LTz. problem, tines, for z.

its Cholesky factorization

the generalized

standard symmetric problem AlY = ly with

Thus, given the capacity to solve the standard problem can be solved with two additional

subrou-

one to determine and compose L-IAL -T and the other to solve LTz = y In EISPACK these subroutines

employed in the paths of Sections

are REDUC and REBAK, respectively,

2.1.5-2.1.8.

If the problem arises instead in the form ABz = Iz, then again proceeding from the Cholesky factorization

of B, it can be transformed

to the

standard problem A2Y = ly with A 2 = LTAL and y, although different, to z by y = LTz as before. LTAL and thus, with REBAK, Finally,

related

The additional EISPACK subroutine REDUC2 forms enables the solution of this variant problem.

the problem BAz = Iz can be transformed

to the standard problem

A2x = Ix with A 2 = LTAL as for the variant ABz = Iz, and x = L-iz.

The one

further EISPACK subroutine REBAKB forms z = Lx and thus, with REDUC2,

enables

the solution of this variant problem. Corresponding

to each of the paths of Sections

explicit subroutine,

driver subroutine

calls for these variant problems.

(RSGAB and RSGBA),

For example,

37

2.1.5-2.1.8,

there are

and control program

to determine

all the eigenvalues

2.2-5

W and their corresponding eigenvectors Z for the real symmetric generalized eigenproblem ABz = hz of order N, the recommended EISPACK path is (cf. Section 2.1.5):

CALL REDUC2(NM,N,A,B,fV2,1EIIR) IF (IERR oNE. O) GO TO 99999 CALL

TRED2(NM,N,A,W,fvl,Z)

CALL

TQL2(NM,N,W,fvl,Z,IERR)

IF (IERR .NE. 0) GO TO 99999 CALL

REBAK(NM,N,B,fv2,N,Z)

or, using driver subroutine RSGAB:

CALL

RSGAB(NM,N,A,B,W,I,Z,fvl,fv~,IERR)

IF (IERR ~NE. 0) GO TO 99999

or, using EISPAC:

CALL EISPAC(NM, N,MATA('REAL',A,'SYMMETRIC'),MATB('REAL',B,'SYMMETRIC', 'POSITIVE DEFINITE','ABX=LX'),VALUES(W),VECTOR(Z))

The eigenvectors here, as in the path of Section 2.1.5, are normalized so that zTBz = I. As a second example, to determine the eigenvalues W in an interval extending from RLB to RUB, together with their corresponding eigenvectors Z, for the real symmetric generalized eigenproblem BAz = hz of order N, the recommended EISPACK path is (cf. Section 2.1.7):

38

2.2-6

CALL

REDUC2(NM, N,A,B,fv9,1ERR)

IF (IERR .NE. O) GO TO 99999 CALL

TREDI(NM, N,A,fvl,fv2,fv3)

EPSI = 0.0 CALL

BISECT(N,EPSI,fvl,fv2,fv3,RLB,RUB,MM,M,W,ivl,IERR,fv4,fv5)

IF (IERR .NE. 0) GO TO 99999 CALL TINVIT(NM,N,fVl

,fv2,fv3,M,W,ivl ,Z, IERR,fv4,fv5,fv6,fvT,fvS)

IF (IERR .NE. 0) GO TO 99999 CALL

TRBAKI(NM,N,A,fV2,M,Z)

CALL

REBAKB(NM,N,B,fv9,M,Z)

or, using EISPAC:

CALL EISPAC(NM,N,MATA(' REAL' ,A, 'SYMMETRIC') ,MATB ('REAL' ,B, 'SYMMETRIC', 'POSITIVE DEFINITE','BAX=LX'),VALUES(W,MM,M,RLB,RUB),VECTOR(Z))

The eigenvectors here are normalized so that zTB-iz = 1.0. The paths for the variant problems share the characteristics of the corresponding paths of Sections 2.1.5-2.1.8 with respect to extent of input array preservation, suitable array dimensions, and required array storage.

The indicative execution times of Sections 2.1.5-2.1.8 extend

to the paths for the variant problems as well; more precise timing information is provided in Section 4.

39

2.3-1

Section 2.3 ADDITIONAL INFORMATION AND EXAMPLES

This section contains additional information about and examples of the use of EISPACK and the control program which are either too detailed to be included in the discussion of a particular path, or which apply to more than one path.

The specific topics covered include the representation of

the eigenvalues of generalized real matrix systems; the packing of the eigenvectors of generalized real matrix systems; considerations regarding the user-supplied error tolerance in the computation of the eigenvalues; possible ill-condition of the generalized real symmetric eigenproblem paths; higher degree eigenvalue problems; the solution of band systems of linear equations; the examination of the IERR parameter and intermediate results when using the control program EISPAC; and a s u m a r y of the possible values of IERR and their meanings.

The section concludes with two complete example

driver programs illustrating the use of EISPACK and the control program EISPAC.

40

2.3-2

Section 2.3.1 THE REPRESENTATION

OF THE EIGENVALUES

OF A GENERALIZED REAL MATRIX SYSTEM

The EISPACK routines which compute the eigenvalues

for the generalized

real matrix problem Az = %Bz do not return the %'s directly; singularity

or near singularity

of the eigenvalues

possible

of A and B dictate a different representation

that maximizes

their informational

content.

No special problems are posed when A is singular with B non-singular; the eigenvalues

are all finite with some of them zero.

singular with A non-singular, infinite.

But when B is

some of the eigenvalues must be thought of as

And finally, when both A and B are singular there may again be

infinite eigenvalues,

and in some extreme situations,

for example when A and

B have a common null space (non-zero vectors z for which Az = 0 and Bz = 0), the matrix A - %B will be singular for any choice of %. In practice with inexact data and imprecise arithmetic, to avoid making decisions about exact singularity. is reformulated

it is desirable

Consequently

the problem

to find pairs of scalars ~ and B for which

BAz = aBz .

The algorithm used in EISPACK determines

two unitary matrices Q and Z such

that QAZ and QBZ are both upper triangular.

Then the desired ~.j and Bj are

simply the diagonal elements of the two triangular matrices,

and it is

these quantities which are returned by the subroutine. Because the algorithm uses only unitary transformations, information %j = e./B.. JJ

there is more

in the individual ~. and B. than there is in the ratios ] 3 The errors in aj and $. are all about the same absolute size, J

namely the size of the errors in the input data (or of roundoff errors in the computation).

Consequently,

if an ~j or Bj is obtained which is about

41

2.3-3

the same size as the original matrix elements, determined by the data and the computation.

it can be regarded as accurately

If, however, it is smaller

than the input data, it must be regarded as having a correspondingly higher relative error. For example, about 1.0.

suppose the general size of the elements in A and B is

If ~. = 1,0 and 8. = 2.0, then %. = 0.5 to about the accuracy J J J

of the data; if instead ~.j = 1.0~i0 -6 and ~j = 2.0o10 -6 , then again %. = 0.5 but this time to six fewer figures of accuracy. J

In the extreme

case where e. and 8. are both about the size of the errors in the data or J ] of roundoff errors in the computation, singular to working accuracy.

then any value of % makes A - %B

If $, is very small but ~. is not, then %, J J J

should be regarded as infinite. These statements about accuracy are further complicated in the presence of multiple eigenvalues.

If %. is a zero of det(A-%B) J

of multiplicity m or

if it is an element of a cluster of m nearly equal zeros, and if c is the relative accuracy of the data, the order of c I/m."

then e. and 8. may have relative errors on J J

For example,

if %. is a double eigenvalue, J

then pertur-

bations on the order of 10 -6 in the data may cause perturbations on the order of 10 -3 in the corresponding ~. and B.. J J

42

2.3-4

Section 2.3.2 UNPACKING THE EIGENVECTORS OF A GENERALIZED REAL MATRIX SYSTEM

Since for a generalized real matrix system the complex eigenvalues and their corresponding eigenvectors occur as conjugate pairs and therefore both members of such a pair are determined once the real and imaginary parts of one member are known, only N 2 real numbers are required to recover all the eigenvectors of such a system.

The EISPACK routines which compute the eigen-

vectors of generalized real matrix systems take advantage of this fact (and so save storage) by packing both real and complex eigenvectors into one N by N matrix. In order to determine whether a given column of the matrix of eigenvectors represents a real eigenvector~ the real part of a complex eigenvector, or the imaginary part of a complex eigenvector, the imaginary part of the corresponding eigenvalue must be examined.

Perhaps the clearest way to describe

how this packing is done is to present a program segment which unpacks the matrix of eigenvectors into two separate matrices representing the real and imaginary parts of the eigenvectors. First, suppose that you have computed all the eigenvalues and eigenvectors of a generalized real matrix system according to Section 2.1.9.

The following

program segment unpacks the matrix Z of eigenvectors into matrices ZR and ZI, dimensioned ZR(~,r~) and Z I ( ~ , ~ ) .

Note that this program segment

utilizes the property of the EISPACK programs that for generalized real matrix systems the eigenvalues of each complex conjugate pair are ordered so that the eigenvalue of positive imaginary part appears first in (ALFR,ALFI, BETA).

43

2.3-5

DO 150 K = I, N IF (ALF!(K)

.hE. 0.0) GO TO ii0

DO I00 J = i, N

i00

ZR(J,K)

= Z(J,K)

ZI(J,K)

= 0.0

CONTINUE GO TO 150

ii0

IF (ALFI(K)

.LT. 0.0) GO TO 130

DO 120 J = i, N

120

ZR(J,K)

= Z(J,K)

ZI(J,K)

= Z(J,K+i)

CONTINUE GO TO 150

130

140

DO 140 J = I, N ZR(J,K)

= ZR(J,K-I)

ZI(J,K)

= -ZI(J,K-I)

CONTINUE

150 CONTINUE

Note

that this p r o g r a m segment has been designed

the same matrix;

if they are,

so that Z and ZR can be

then the fourth and tenth statements

be omitted.

44

can

2.3-6

Section 2.3.3 THE EPSI PARAMETER

As discussed in Section i, the various versions of the subroutines in EISPACK are designed to provide the best accuracy possible given the working precisions of the particular machines for which they are available.

For

most of the subroutines, accuracy is controlled by an internal variable, MACHEP ("machine epsilon"), whose value reflects the precision of the machine arithmetic and should not be altered.

However, user control of accuracy

is possible with subroutines BISECT and QZIT.

This accuracy control is

provided by the parameter EPSI, which principally affects the precision of the eigenvalues, and thus the eigenvectors as well, but which also has some effect on computation time.

Some of the considerations helpful in choosing

EPSI are discussed briefly below; further information can be found in the respective documents for the subroutines and in the Handbook ([i], pp. 249-256). In subroutine BISECT, the computation of an eigenvalue is considered to have converged when the refined interval [XU,X0] known to contain the eigenvalue satisfies the condition:

X0 - XU ~ 2 x MACHEP ×

(Ix01 + IxuI) +

EPSI

This condition has the character of a relative accuracy test for eigenvalues whose magnitudes are large with respect to EPSI/MACHEP, and that of an absolute accuracy test for eigenvalues of small magnitude.

EPSI is thus

an absolute error tolerance. When the input value of EPSI is zero (or negative) as in the recommended paths, BISECT automatically resets it to an appropriate default value for each submatrix; this default value is MACHEP times the larger (in magnitude)

45

2.3-7

Gerschgorin

bound for the eigenvalues

the above termination criterion

of that submatrix.

from requiring

in the eigenvalues which are near zero.

This value prevents

"unreasonably"

high accuracy

(In the implementation

of BISECT,

EPSI is actually set negative when the default value is requested. serves as a flag to cause the recomputation submatrix;

This

of the default value for each

the returned value of EPSI is this negative default value for

the final submatrix.) A positive positive

input value for EPSI will not be reset in BISECT.

input value of EPSI exceeds

is less stringent for eigenvalues tends to be reduced.

the default value,

the convergence

test

of smaller magnitude,

and computation

time

If EPSI is smaller than its default value,

gence test becomes more stringent and computation Care should be taken, however, the small eigenvalues input matrix;

though computation relationship

the additional

time tends to increase.

to perturbations

in the

precision will be meaningless.

Al-

time tends to increase with decreasing EPSI, the exact

is highly dependent

When eigenvectors

on the particular matrix.

are computed by the method of inverse iteration,

success of the computation puted eigenvalues.

the conver-

not to specify a smaller value for EPSI unless

are known to be insensitive

otherwise

When the

the

depends critically on the accuracy of the com-

Thus, when TINVIT follows BISECT, use of an EPSI larger

than the default value may result in failure of the eigenvector

calculation

to converge. In subroutine QZIT, an element of either A or B is considered

negligi-

ble if it is smaller than the product of EPSI and the respective matrix norm.

In particular,

an eigenvalue has converged when the lowest subdiagonal

element of A becomes negligible. EPSI requests

the default;

As with BISECT,

in QZIT, however,

46

a zero or negative value of

EPSI itself is not reset.

2.3-8

To use a value of EPSI other than the default,

the statement

EPSI = 0.0

in the paths should be replaced by a statement setting EPSI to the desired value.

When using the control program EISPAC, EPSI can be supplied for the

recommended

paths only by adding EPSI as the last subparameter

parameter.

Thus the VALUES parameter becomes:

...VALUES(W,MM,M,RLB,RUB,EPSI),...

as appropriate.

With EISPAC,

to the VALUES

or ...VALUES(ALFR,ALFI,BETA,EPSI),...

the input value of EPSI is not altered,

though the default value may be used in the computation.

47

even

2.3-9

Section 2.3.4 POSSIBLE

ILL-CONDITION

OF THE GENERALIZED

The solution of the generalized by the paths of Sections 2.1.5-2ol.8 definite and proceeds

REAL SYMMETRIC EIGENPROBLEM PATHS

real symmetric

eigenproblem Az = %Bz

demands that the matrix B be positive

from the Cholesky factorization

B = LL T.

The problem

is then reduced to the standard symmetric problem AiY = %y, where A I = L-IAL -T and y = LTz. is measured

The computed eigenvalues relative

to the size of the elements of A I.

and hence A 1 have large elements, tive errors~

are obtained with an accuracy which

the small eigenvalues

Consequently

if L -I

may have high rela-

This occurs when B is close to an indefinite matrix and is

indicated by the presence of eigenvalues

~ which are much larger than the

elements of A and B. The alternative

approach

in this situation is to ignore the symmetry and

simply use the paths of Sections 2.1.9-2.1.10 problem.

In addition to increased costs,

which are normalized non-zero

this approach produces

real eigeneigenvectors

in a different way and may produce eigenvalnes with

imaginary parts.

more accurate

for the generalized

However,

than those produced

the small eigenvalues will usually be

in the sy~m~etric

paths.

Furthermore,

the

size of the ~. and B~ give some indication of the accuracy obtained. 3 3 It is difficult to give precise guidelines for the choice among these two approaches.

The symmetric path is certainly preferable

if B is well conditioned

with respect to inversion and hence there are no large eigenvalues. badly conditioned,

or its properties

since it always produces programming,

are unknown,

accurate eigenva!ues.

but the increase in execution

duce eigenvalues

with non-zero

If B is

then the real path is safer

It requires little additional

time and the fact that it may pro-

imaginary parts means that it should probably be

used only for small problems or as a check on the accuracy of the symmetric path.

48

2.3-10

Section 2.3.5 HIGHER DEGREE EIGENVALUE PROBLEMS

EISPACK can be used to solve problems of the form

(lrc 0 + lr-ic I +...+ lCr_ 1 + Cr)X = 0

where C0,...,C r are given real matrices of order m. the scalars %j which make the matrix in parentheses to find the corresponding

null vectors x.. J

It is desired to find singular and possibly

In general,

the approach to this

problem involves forming two matrices A and B of order n = m-r, illustrated for the case r = 3, by

Iic2i -C I

A =

-C 3

0

I

Co B=

° I 0

The original problem is then equivalent

to the generalized

real eigenproblem

Az = ~Bz where

This can be solved using the paths of Sections

2.1.9-2.1.10.

there will be n values of ~, counting multiplicities. singular,

some of these values will be infinite

49

In general,

However,

if C O is

(see Section 2.3.1).

2,3-II

In particular,

if C O is the identity matrix,

then the problem is equi-

valent to the standard problem

Az = %z

which can be solved using the EISPACK subroutines Sections

2.!~8-2.1.I0

of [i0].

50

and paths described

in

2.9-12

Section 2.3.6 THE USE OF BANDV IN SOLVING BAND SYSTEMS OF LINEAR EQUATIONS Subroutine BANDV has appeared earlier in the recommended path of Section 2.1.3 that determines

some eigenvalues

and corresponding

eigenvectors

of a real symmetric band matrix.

BANDV can also be used to solve systems of

linear equations in band f o r m - -

in this usage the coefficient matrix may be

either symmetric or non-symmetric. of BANDV for determining non-symmetric

The extendibility an awareness

eigenvectors

band matrices

EISPACK for determining

is not fundamental;

towards the use

no allowance

the corresponding

eigenvalues.)

of BANDV to systems of linear equations derives from of an eigenvector associated with a speci-

itself depends on the solution of a linear system,

case a homogeneous

system.

where % is an approximate of an eigenvector,

for

is made simply because no capability exists in

that the determination

fied eigenvalue

(The symmetry requirement

in this

That is, BANDV solves the linear system (A-~l)x = b, eigenvalue and b the zero vector in the determination

and where % is a parameter

(commonly zero) and b a pre-

scribed constant vector in the solution of a system of linear equations. To signal the usage of BANDV to solve band systems of linear equations, set parameter E21 to 1.0 if the matrix is symmetric and to -I.0 if not (for eigenvectors, matrix~

E21 is set to 0.0 or 2.0), and transmit the band coefficient

the constant matrix, and parameters

tion for BANDV in Section 7.1. matrix;

that near singularity

in the documenta-

The solution matrix overwrites

the input band matrix is unaltered.

indicates

~ as described

The error parameter,

if set,

of the input matrix has been detected.

Execution time for BANDV in solving systems of linear equations approximate

the constant

the time for its use in eigenvector

Section 4.

51

determination,

should closely reported in

2.3-13

Section 2.3.7 ADDITIONAL

FACILITIES OF THE EISPAC CONTROL PROGRAM

The EISPAC control program has two facilities which increase its flexibility and range of application.

The first provides

the opportunity

to

examine the IERR parameter values returned by the EISPACK subroutines; second provides computation

the opportunity

proceeds,

to examine intermediate

the

results as the

much as can be done when the EISPACK subroutines

are

called explicitly. The facility integer variable,

to examine the value of IERR is invoked by setting an say IERROR,

to zero and supplying

it as the subparameter

of the keyword parameter ERROR in the call to EISPAC.

For example,

the path

of Section 2.1.10 becomes

IERROR = 0 CALL EISPAC(NM, N,MATA('REAL',A),MATB('REAL',B), VALUES(ALFR,ALFI,BETA) ,ERROR(IERROR))

To understand

the effect of supplying

of EISPAC when it is not supplied.

the ERROR keyword,

consider

When one of the subroutines

non-zero value of IERR, EISPAC prints a message describing terminates

execution of your program.

EISPAC behaves returns

instead as follows:

When ERROR(IERROR)

the behavior

returns a

the error and is supplied,

If no execution errors occur, EISPAC

to your program after execution of the path, and IERROR is still

equal to zero.

If one of the routines returns a positive value of IERR

(a "fatal error),

EISPAC terminates

(unless suppressed by initializing described

the path, prints the error message IERROR to a machine dependent value as

in Section 7.2), and then returns

equal to IERR.

Finally,

of IERR (a "non-fatal"

to your program with IERROR

if one of the routines returns a negative value

error), EISPAC completes

52

execution of the path in

2.3-14

order to produce some useful results, prints the error message, to your program with IERROR equal to IERR. IERR examination

and returns

Thus the principal use of the

facility is to enable you to retrieve useful partial

results when a non-fatal

error occurs; which results are useful is des-

cribed in the discussion of the particular path in Section 2.1 or 2.2 and is summarized in Table 3 of Section 2.3.8. The EISPAC facility to examine intermediate mode of operation

results is provided by a

in which EISPAC calls a user-supplied

subroutine just

before execution of the path begins,

and again after execution of each sub-

routine and auxiliary action in it.

You are free to choose the name of the

subroutine, correspond

say USUB, but the parameter list and declaration

statements must

to:

SUBROUTINE USUB(ISUBNO,NM,N,AR,AI,WR,WI,ZR,

ZI,MM,M,RLB,RUB,EPSI,

X

SELECT,IDEF,TYPE,IERR,LOW,IGH,BND,D,E,E2,1ND,INT,ORTR,SCALE,

X

TAU,ORTI,MII,NV,MB,BR,DL,ALFR,ALFI,BETA) REAL*8 AR(NM,NM),AI(NM,NM),WR(NM),WI(NM),ZR(NM,NM),ZI(NM,NM),

X

RLB,RUB,EPSI,BND(N),D(N),E(N),E2(N),ORTR(N),SCALE(N),

X

TAU(2,N),ORTI(N),BR(NM,NM),DL(N),ALFR(NM),ALFI(NM),BETA(NM) INTEGER ISUBNO,NM,N,MM,M,IDEF,IERR,LOW,IGN,IND(N),INT(N),MII,NV,MB LOGICAL SELECT(NM),TYPE

In order to avoid Fortran errors it is important dimensioned

as indicated

(except that M M m a y

of WR and of ZR and ZI, where appropriate),

that the array parameters be

be used for the last dimension even though some arrays might

not appear relevant to a particular path. You inform EISPAC that you wish to use the intermediate tion facility by inserting

the keyword parameter

53

result examina-

SUBR with subparameter

USUB

2.3-15

in the EISPAC call.

Note that the statement EXTERNAL USUB must also appear

in your calling program. When USUB is called by EISPAC,

the value of the integer parameter

ISUBNO is set to indicate which EISPACK subroutine

call or auxiliary action

has just been completed.

It is zero when USUB is called just before execu-

tion of the path begins.

IS~NO

the preceding

values in the range 100-299 signify that

action allocated or freed temporary storage,

range 300-499 indicate auxiliary actions for example)~

(initializing

and those beyond 500 correspond

routines as indicated

in Table 2.

those in the

or copying arrays,

to calls to the EISPACK sub-

Thus the value of ISUBNO indicates where

in the execution of a path USUB has been called, mine what action USUB is to take in examining

and can be used to deter-

the intermediate

results.

Table 2 also indicates which of the parameters passed to USUB appeared in the just-completed

call to the E!SPACK subroutine.

As an example of the use of this facility,

suppose you wish to inter-

rupt the path of Section 2.1.2 and use a subroutine TRDIAG to print the tridiagonal matrix produced eigenvalues

from the first step in the determination

of a real symmetric band matrix.

of the

Your driver program must con-

tain the statements

EXTERNAL TRDIAG o

'SYMMETRIC'),BAND(MB),VALUES(W),SUBR(TRDIAG))

CALL EISPAC(NM,N,MATRIX(VREAL',A,

To determine how to write TRDIAG,

consult the definition of the path in

Section 2.1.2 in conjunction with Table 2. from BANDR and is overwritten

The tridiagonal matrix is returned

in the subsequent

execution of TQLRAT,

interruption must be made immediately after the call to BANDR. cates that this call in this path has an associated

54

so the

Table 2 indi-

ISUBNO of 545, and

2.3-16

inspection of the parameters in the BANDR call (see BANDR documentation in Section 7) shows that the diagonal elements are in WR and the subdiagonal elements are in E.

Hence the subroutine might be written as follows:

SUBROUTINE TRDIAG (ISUBNO, NM, N, AR, AI,WR,WI, ZR, ZI, MM, M, RLB, RUB, EPS 1, X

SELECT, IDEF, TYPE, IERR,LOW, IGH, BND,D,E, E2, IND, INT, ORTR, SCALE,

X

TAU, ORTI ,MI 1 ,NV,MB, BR, DL,ALFR, ALFI, BETA) REAL*8 AR(NM,NM) ,AI(NM,NM) ,WR(NM) ,WI (NM) ,ZR(NM,NM) ,ZI(NM,NM),

X

RLB,RUB,EPSI ,BND (N) ,D(N) ,E(N) ,E2 (N) ,ORTR(N) ,SCALE(N),

X

TAU(2 ,N) ,ORTI (N) ,BR(NM,NM) ,DL (N) ,ALFR(NM) ,ALFI (NM) ,BETA (NM) INTEGER ISUBNO, NM, N,MM, M, IDEF, IERR, LOW, IGH, IND (N), INT (N) ,MI i, NV,MB LOGICAL SELECT (NM), TYPE IF (ISUBNO .RE. 545) RETURN WRITE(6, i000) (WR(1) ,E(1),I=I,N)

i000 FORMAT (19HITRIDIAGONAL MATRIX//(1X, IP2DI6.8) ) RETURN END TRDIAG immediately returns after every call from EISPAC except when ISUBNO is 545 (after BANDR); then it writes out the diagonal and subdiagonal elements of the reduced tridiagonal matrix from BANDR.

55

2.3-17

TABLE 2 ISUBNO VALUES AND PARAMETER NAMES FOR SUBROUTINE CALLS FROM EISPAC

Subroutine Call*

ISUBNO Value

544

BANDR (NM,N ,MB, AR,WR, E ,E,. TRUE. ,ZR) in path for all values and vectors

545

BANDR (NM,N,MB,AR,WR,E,E2, .FALSE. ,-) in path for all values, no vectors

546

(2.1.i)

(2.1.2)

BANJOR (NM,N,MB,AR,D,E,E2, .FALSE. ,-) in paths for some values (2.1.3, 2.1.4)

547

BANDV (NM,N,MB,-,E2(1) ,M,WR,ZR,IERR,NV,-,-)

526

BISECT (N ,EPS 1, D, E ,E2, RLB ,RUB ,MM,M,WR, IND, IERR,-, BND)

(not used)

BQR

(not used)

MINFIT

568

QZHES (NM,N,AR,BR, .TRUE. ,ZR) in path for all values and vectors (2.1.9)

572

QZHES (NM,N,AR,BR, .FALSE. ,-) in path for all values, no vectors (2.1.10)

569

QZIT (NM,N,AR,BR,EPSI, .TRUE. ,ZR,IERR) in path for all values and vectors

573

(2.1.9)

QZIT (NM,N,AR,BR,EPSI,oFALSE. ,-,IERR) in path for all values, no vectors (2.1.10)

570

QZVAL (NM,N,AR,BR,ALFR,ALFI,BETA, .TRUE. ,ZR) •n path for all values and vectors (2.1.9)

574

QZVAL (NM,N,AR,BR,ALFR,ALFI,BETA, .FALSE. ,-) in path for all values, no vectors (2.1.10)

571

QZVEC (NM,N,AR,BR,ALFR,ALFI, BETA, ZR)

551

REBAK (NM,N,BR,DL ,M,ZR)

550

~BAF~

548

REDUC (NM,N,AR,BR,DL, IERR)

(NM,N, BR,DL,M, ZR)

56

2.3-18

TABLE 2 (Contd.) ISUBNO VALUES AND PARAMETER NAMES FOR SUBROUTINE CALLS FROM EISPAC

ISUBNO Value 549 (not used)

Subroutine Call* REDUC2 (NM,N,AR,BR,DL, IERR) SVD

528

TINVIT (NM,N,D, E, E2 ,M,WR, IND, ZR, IERR,- ,- ,- ,-, BND)

543

TQLRAT (N,WR,E2,IERR)

542

TQL2 (NM,N,WR,E, ZR,IERR)

536

TRBAKI (NM,N,AR,E,M, ZR)

534

TREDI (NM,N,AR,WR,E ,E2) in path for all values, no vectors (2.1.6)

535

TREDI (NM,N,AR,D,E,E2) in paths for some values (2.1.7, 2.1.8)

533

TRED2 (NM,N,AR,WR,E, ZR)

A dash at some position in a parameter list indicates a temporary storage array which is not passed to the user subroutine by EISPAC.

57

2.3-19

Section 2.3.8 NON-ZERO VALUES OF IERR

This section summarizes

the non-zero values of the error parameter

IERR that can be returned by the EISPACK subroutines,

either directly or

via the control program (see Section 2.3.7), when an execution error is detected.

Such execution errors are classified

path-terminating

errors,

into two categories:

indicated by positive values of IERR and signifying

that although some possibly useful results have been obtained, execution of the path is meaningless;

second, non-terminating

cated by negative values of IERR and signifying already occurred,

some further meaningful

remaining part of the path is executed. in EISPACK corresponds

first,

continued errors,

indi-

that although errors have

results may be obtained Each distinct

if the

error that can occur

to one of a unique set of values for IERR, that one

being a function of the order of the matrix. The non-zero values of IERR are summarized this section.

To determine

the significance

in Table 3 at the end of

of a particular value of IERR,

scan the column headed IERR for the expression with the value of your particular

error.

The name of the subroutine

that set the error parameter

is included in the list to the right; also given is the EISPAC error message number and a brief description

of the significance

of the error.

tailed information may be obtained from the documentation subroutine

in Section 7.

58

More de-

for the particular

2.3-20

TABLE 3 SUMMARY OF VALUES OF IERR EISPAC MESSAGE

IERR

SUBROUTINES

i, l~ .GE. D M I N ) G O TO 6 5 0 MAXL = MAXO(I,MB+I-J)

610

DO 6 1 0 A(J,L)

L = MAXL, M1 = DMINRT * A(J,L)

IF (J .EQ. N) GO TO MAXL = MINO(MI,N-J)

630

DO

620

6 2 0 L = I, M A X L Ii = J + L 12 = M B - L A(II,12) = DMINRT CONTINUE

630

IF

640

DO 640 Z(L,J)

(.NOT.

MATZ)

GO

TO

* A(II,12)

645

L = I, N = DMINRT * Z(L,J)

144

OR

OVERFLOW

*********~

7.1-9

A(J,MB) = DMIN * A(J,MB) D(J) = D(J) / DMIN CONTINUE

645 650 700 800 810

CONTINUE ********** FORM SQUARE DO 8 1 0 J = 2, N E(J) = SQRT(D(J)) IF

(.NOT.

DO

830

J =

DO 820 Z(J,K)

820 830

CONTINUE

840

U =

MATZ) i, K

=

GO

TO

ROOT

840

N 2,

= E(K)

N

* Z(J,E)

1.0

DO

850

8 5 0 J = 2, N A(J,MI) = U * E(J) * A(J,MI) U = E(J) E2(J) = A(J,MI) ** 2 A(J,MB) = D(J) * A(J,MB) D(J) = A(J,MB) E(J) = A(J,MI) CONTINUE D(1) = A(I,MB) E(1) = 0.0 E2(1) = 0.0 GO T O i 0 0 1

900

950 i001

OF

DO

9 5 0 J = I, N D(J) = A(J,MB) E(J) = 0.0 E2(J) = 0.0 CONTINUE

RETURN END

145

SCALING

MATRIX

**********

7.1-I0

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F227

PACKAGE

(EiSPACK)

BANDV

A F o r t r a n IV S u b r o u t i n e to D e t e r m i n e S o m e E i g e n v e c t o r s of a R e a l S y m m e t r i c B a n d M a t r i x or S o l v e B a n d E q u a t i o n s .

July,

1975

I. P U R P O S E . T h e F o r t r a n IV s u b r o u t i n e BANDV determines those e i g e n v e c t o r s of a real s y m m e t r i c b a n d m a t r i x c o r r e s p o n d i n g to a set of o r d e r e d a p p r o x i m a t e e i g e n v a l u e s , u s i n g i n v e r s e iteration. It c a n a l s o be u s e d to s o l v e a s y s t e m of l i n e a r e q u a t i o n s w i t h a s y m m e t r i c or n o n - s y m m e t r i c b a n d c o e f f i c i e n t m a t r i x , or a s u c c e s s i o n of r e l a t e d s y s t e m s .

2. U S A G E . A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

BANDV(NM,N,MBW,A,E21,M,W,Z, IERR,NV,RV,RV6)

T h e p a r a m e t e r s are d i s c u s s e d b e l o w and the i n t e r p r e t a t i o n of w o r k i n g p r e c i s i o n for v a r i o u s m a c h i n e s is g i v e n in the s e c t i o n d i s c u s s i n g c e r t i f i c a t i o n . NM

is a n i n t e g e r i n p u t v a r i a b l e set e q u a l to the r o w d i m e n s i o n of the t w o - d i m e n s i o n a l arrays A and Z as s p e c i f i e d in the D I M E N S I O N s t a t e m e n t s for A and Z in the calling program. is an i n t e g e r i n p u t v a r i a b l e the o r d e r of the m a t r i x A. greater than NM.

MBW

set e q u a l to N m u s t be n o t

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to the n u m b e r of c o l u m n s of the a r r a y A used t o s t o r e the b a n d m a t r i x . If the m a t r i x is symmetric, MBW is its (half) b a n d w i d t h ,

146

7.1-11

denoted MB and defined as the number of adjacent diagonals, including the p r i n c i p a l diagonal, required to specify the non-zero portion of the lower triangle of the matrix. If BANDV is being used to solve systems of linear equations and the c o e f f i c i e n t m a t r i x is not symmetric, it must have the same number of adjacent diagonals above the main diagonal as below, and so in this case MBW=2*MB-I. MB

must

be not

greater

than

N.

is a working p r e c i s i o n real input twod i m e n s i o n a l v a r i a b l e with row d i m e n s i o n NM and column d i m e n s i o n at least MBW . If the band m a t r i x is symmetric, A contains its lower triangle of order N and (half) band width MB. Its lowest s u b d i a g o n a l is stored in the last N+I-MB positions of the first column, its next s u b d i a g o n a l in the last N+2-MB p o s i t i o n s of the second column, further s u b d i a g o n a l s similarly, and finally its principal diagonal in the N positions of the last column. Contents of storage locations not part of the m a t r i x are arbitrary. For example, when N=5 and MB=3, A should contain ( * ( * (A(3,1) (A(4,2)

* A(2,1) A(3,2) A(4,3)

A(I,I) A(2,2) A(3,3) A(4,4)

(A(5,3)

A(5,4)

A(5,5) )

where the subscripts for to the row and column of standard t w o - d i m e n s i o n a l (*) denotes an arbitrary

) ) ) )

each element refer the element in the r e p r e s e n t a t i o n , and value.

If BANDV is being used to solve Systems of linear equations and the c o e f f i c i e n t m a t r i x is not symmetric, A is N by 2*MB-I instead with lower triangle as above and with its first s u p e r d i a g o n a l stored in the first N-I p o s i t i o n s of column MB+I, its second s u p e r d i a g o n a l in the first N-2 positions of column MB+2, further s u p e r d i a g o n a l s similarly, and finally its h i g h e s t s u p e r - d i a g o n a l in the first N+I-MB positions of the last column. In the example above, A would be a u g m e n t e d with two additional columns containing

t47

7.1-12

(A(I,2) (A(2,3) (A(3,4) (A(4,5) ( * E21

A(I,3) A(2,4) A(3,5) * ,

) ) ) ) ).

is a w o r k i n g p r e c i s i o n real input v a r i a b l e s p e c i f y i n g the o r d e r i n g of the e i g e n v a l u e s . E21 should c o n t a i n 0.0 if the e i g e n v a l u e s are in a s c e n d i n g order and 2.0 if the e i g e n v a l u e s are in d e s c e n d i n g order. If BANDV is being used to solve systems of linear e q u a t i o n s , E21 should c o n t a i n 1.0 if the c o e f f i c i e n t m a t r i x is s y m m e t r i c and -i.0 if not. is an i n t e g e r input v a r i a b l e set equal to the n u m b e r of s p e c i f i e d e i g e n v a l u e s for w h i c h the c o r r e s p o n d i n g e i g e n v e c t o r s are to be d e t e r m i n e d . If BANDV is being used to solve systems of linear e q u a t i o n s , M is equal to the n u m b e r of systems.

W

is a w o r k i n g p r e c i s i o n real input oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least M c o n t a i n i n g the M specified eigenvalues of the s y m m e t r i c band matrix. The e i g e n v a l u e s must be in either a s c e n d i n g or d e s c e n d i n g order in W. The o r d e r i n g is r e q u i r e d to insure the d e t e r m i n a t i o n of independent orthogonal eigenvectors a s s o c i a t e d w i t h close e i g e n v a l u e s . If BANDV is being used to solve systems of linear e q u a t i o n s , W contains M p a r a m e t e r s (commonly zero) which, together with A, d e f i n e the c o e f f i c i e n t m a t r i c e s A-W(J)*I, J=I,2,...,M of the s u c c e s s i v e systems, w h e r e I is the i d e n t i t y matrix. is a w o r k i n g p r e c i s i o n real t w o - d i m e n s i o n a l v a r i a b l e w i t h row d i m e n s i o n NM and column d i m e n s i o n at least M. On output, it contains M o r t h o n o r m a l e i g e n v e c t o r s of the s y m m e t r i c band m a t r i x c o r r e s p o n d i n g to the M e i g e n v a l u e s in W.

148

7.1-13

If BANDV is b e i n g u s e d to s o l v e s y s t e m s of linear equations, t h e n on i n p u t , Z contains the M associated constant vectors of t h e s u c c e s s i v e systems (A-W*I)*X=Z and on o u t p u t , Z contains the corresponding solution vectors X. IERR

B.

Error

is an i n t e g e r o u t p u t v a r i a b l e set equal an error completion code described in s e c t i o n 2B. The normal completion code zero,

to is

NV

is a n i n t e g e r input variable s e t e q u a l to the dimension of t h e a r r a y RV as s p e c i f i e d in t h e D I M E N S I O N statement for RV in the calling program. NV m u s t be n o t l e s s t h a n N* ( 2 * M B - I ) .

RV

is a w o r k i n g precision real temporary array variable of d i m e n s i o n at l e a s t N*(2*MB-I) u s e d to s t o r e t h e u p p e r t r i a n g u l a r matrix produced in t h e i n v e r s e iteration process.

RV6

is a w o r k i n g precision real temporary onedimensional variable of d i m e n s i o n at l e a s t N u s e d to h o l d t h e a p p r o x i m a t e elgenvectors or s o l u t i o n vectors in t h e i n v e r s e i t e r a t i o n process.

Conditions

and

Returns.

If n o n e of t h e i n i t i a l v e c t o r s for the inverse iteration process produces an a c c e p t a b l e approximation to an eigenvector, BANDV terminates the computation for that eigenvector and sets IERR to -R where R is t h e i n d e x of the e i g e n v e c t o r . If t h i s f a i l u r e occurs for more than one eigenvector, the last occurrence is recorded in IERR. T h e c o l u m n s of Z corresponding to failures of the a b o v e s o r t a r e set to z e r o v e c t o r s . If BANDV is b e i n g u s e d to s o l v e s y s t e m s of l i n e a r equations and near singularity of t h e c o e f f i c i e n t matrix is d e t e c t e d , BANDV continues the c o m p u t a t i o n but sets IERR to -R where R is t h e i n d e x of t h e l i n e a r system. If t h i s f a i l u r e o c c u r s f o r m o r e t h a n o n e system, the l a s t o c c u r r e n c e is r e c o r d e d in IERR. If t h e a b o v e e r r o r c o n d i t i o n sets IERR to z e r o .

149

does

not

occur,

BANDV

7.1-14

C. A p p l i c a b i l i t y

and R e s t r i c t i o n s .

To d e t e r m i n e some of the e i g e n v a l u e s and e i g e n v e c t o r s of a s y m m e t r i c b a n d matrix, BANDV should be p r e c e d e d by B A N D R (F226) to p r o v i d e a s u i t a b l e s y m m e t r i c t r i d i a g o n a l m a t r i x for BISECT (F294) or T R I D ! B (F237) w h i c h can then be used to d e t e r m i n e the e i g e n v a l u e s . If MACHEP d e n o t e s the r e l a t i v e m a c h i n e p r e c i s i o n , then the c o m p u t a t i o n of the e i g e n v e c t o r s by i n v e r s e i t e r a t i o n r e q u i r e s that the p r e c i s i o n of the e i g e n v a l u e s he c o m m e n s u r a t e w i t h small r e l a t i v e p e r t u r b a t i o n s of the order of MACHEP in the m a t r i x elements. For m o s t s y m m e t r i c band m a t r i c e s , it is e n o u g h that the a b s o l u t e error in the e i g e n v a l u e s for which e i g e n v e c t o r s are d e s i r e d be a p p r o x i m a t e l y MACHEP times a n o r m of the matrix. But some m a t r i c e s r e q u i r e a s m a l l e r a b s o l u t e error~ p e r h a p s as small as MACHEP times the e i g e n v a l u e of s m a l l e s t m a g n i t u d e .

3. D I S C U S S I O N

OF M E T H O D

AND A L G O R I T H M .

The e i g e n v e c t o r s of the m a t r i x are c o m p u t e d by inverse iteration. First, the LU d e c o m p o s i t i o n of the m a t r i x with an a p p r o x i m a t e e i g e n v a l u e s u b t r a c t e d from its d i a g o n a l e l e m e n t s is a c h i e v e d by G a u s s i a n e l i m i n a t i o n using p a r t i a l pivoting. The upper t r i a n g u l a r m a t r i x is stored in the t e m p o r a r y array RV. An a p p r o x i m a t e vector, stored in RV6, is c o m p u t e d s t a r t i n g f r o m an i n i t i a l v e c t o r , and the n o r m of the a p p r o x i m a t e v e c t o r is c o m p a r e d w i t h a n o r m of the m a t r i x to d e t e r m i n e w h e t h e r the g r o w t h is s u f f i c i e n t to a c c e p t it as an e i g e n v e c t o r . If this v e c t o r is accepted, its E u c l i d e a n norm is m a d e I. At m o s t N o r t h o g o n a l initial v e c t o r s are tried to o b t a i n the r e q u i r e d growth. If no v e c t o r is accepted, the p a r a m e t e r IERR is set to i n d i c a t e this f a i l u r e and BANDV p r o c e e d s to c o m p u t e the next e i g e n v e c t o r . E i g e n v e c t o r s c o m p u t e d in the above way c o r r e s p o n d i n g to well s e p a r a t e d e i g e n v a l u e s of the m a t r i x will be orthogonal. However, e i g e n v e c t o r s c o r r e s p o n d i n g to close e i g e n v a l u e s of the m a t r i x may not be s a t i s f a c t o r i l y orthogonal, Hence, to insure o r t h o g o n a l e i g e n v e c t o r s , each a p p r o x i m a t e v e c t o r is made o r t h o g o n a l to those p r e v i o u s l y c o m p u t e d e i g e n v e c t o r s w h o s e e i g e n v a l u e s are close to the c u r r e n t eigenvalue. The g r o w t h test is made after the o r t h o g o n a l i z a t i o n process. I d e n t i c a l e i g e n v a l u e s are p e r t u r b e d s l i g h t l y in an a t t e m p t to obtain independent eigenvectors. T h e s e p e r t u r b a t i o n s are not r e c o r d e d in the e i g e n v a l u e array W.

150

7. 1-15

If BANDV is being used to solve systems of linear equations, the p r o c e d u r e described above is followed (omitting the growth test and o r t h o g o n a l i z a t i o n process), choosing as initial vector the a p p r o p r i a t e constant vector. Upon return from BANDV, the d e t e r m i n a n t (up to sign) of A-W(M)*I can be computed, if desired, by forming the product of the first N elements of RV. This subroutine is patterned after the e i g e n v e c t o r d e t e r m i n a t i o n portion of the Fortran subroutine TSTURM (F293), with initial vectors chosen as in INVIT (F288). These latter subroutines are translations of the Algol procedures TRISTURM and INVIT, respectively, w r i t t e n and d i s c u s s e d in detail by Peters and W i l k i n s o n (I).

4. REFERENCES.

i)

Peters, G. and Wilkinson, J.H., The C a l c u l a t i o n of Specified E i g e n v e c t o r s by Inverse Iteration, H a n d b o o k A u t o m a t i c Computation, V o l u m e II, Linear Algebra, J. H. W i l k i n s o n - C. Reinsch, C o n t r i b u t i o n 11/18, 418-439, Springer-Verlag, 1971.

for

5. CHECKOUT. A.

Test Cases. See the section discussing testing real symmetric band matrices.

of the codes

for

B. Accuracy. The accuracy of BANDV can best be described in terms of its role in those paths of EISPACK which find eigenvalues and e i g e n v e c t o r s of real symmetric band matrices. In these paths, this subroutine is n u m e r i c a l l y stable (I). This stability contributes to the property of these paths that the computed e i g e n v a l u e s are the exact eigenvalues of a m a t r i x close to the original m a t r i x and the computed e i g e n v e c t o r s are close (but not n e c e s s a r i l y equal) to the e i g e n v e c t o r s of that matrix.

1,51

7,1-16

SUBROUTINE

BANDV(NM,N~MBW,A,E21,M,W,Z,IERR,NV,RV,RV6)

INTEGER

X

I,J,K,M,N,R,II,IJ,JJ,KJ,MB,MI,NM,NV,IJI,ITS,KJI,MBW,M21, IERR,MAXJ,MAXK,GROUP REAL A(NM,MBW),W(M),Z(NM,M),RV(NV),RV6(N) REAL U,V,UK,XU,X0,XI,E21,EPS2,EPS3,EPS4,NORM,ORDER,MACHEP REAL SQRT,ABS,FLOAT,SIGN INTEGER MIN0 **********

MACHEP

=

MACHEP IS A M A C H I N E DEPENDENT PARAMETER SPECIFYING THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.

?

IERR = 0 I F (M . E Q . 0) G O T O i 0 0 1 MB = MBW I F ( E 2 1 .LT. 0 . 0 ) M B = ( M B W + I) / 2 M1 = MB - I M21 = M1 + MB ORDER = 1.0 - ABS(E21) ********** FIND VECTORS BY INVERSE ITERATION D O 9 2 0 R = i, M ITS = I

Xl

= W(R)

I F (R .NE. i) G O T O i 0 0 ********** COMPUTE NORM OF NORM = 0.0 DO

**********

60 JJ KJ IJ

J = Ix M B = MB + 1 = JJ + MI = i

MATRIX

**********

J

DO

40 60

40 1 = JJ, N NORM = NORM + ABS(A(I,J)) IF (E21 .GE. 0.0) GO TO 40 NORM = NORM + ABS(A(IJ,KJ)) IJ = IJ + I CONTINUE

CONTINUE IF (E21 **********

°LT. 0.0) NORM = 0.5 * NORM EPS2 IS T H E C R I T E R I O N FOR GROUPING, EPS3 REPLACES ZERO PIVOTS AND EQUAL ROOTS ARE MODIFIED BY EPS3, EPS4 IS TAKEN VERY SMALL TO AVOID OVERFLOW IF ( N O R M .EQ. 0.0) NORM = 1.0 EPS2 = I.OE-3 * NORM * ABS(ORDER) EPS3 = MACHEP * NORM UK = SQRT(FLOAT(N)) EPS4 = UK * EPS3

152

**********

7.1-17 80 C !00

C C

120

GROUP = 0 GO TO 120 ***~*****~ LOOK FOR CLOSE OR COINCIDENT ROOTS *~******** IF ( A B S ( X I - X O ) .GE. E P S 2 ) G O T O 80 GROUP = GROUP + I I F ( O R D E R * (XI - X O ) .LE. 0 . 0 ) X I = X 0 + O R D E R * E P S 3 *******~** EXPAND MATRIX, SUBTRACT EIGENVALUE, AND INITIALIZE VECTOR ********** D O 2 0 0 1 = i, N IJ = I + M I N 0 ( 0 , I - M I ) * N K J = IJ + M B * N IJl = KJ + M1 * N IF (MI .EQ. 0) G O T O 1 8 0

C DO

125 130

140 150

1 5 0 J = I, M I IF (IJ .GT. M I ) G O T O 125 IF (IJ .GT. 0) G O T O 1 3 0 RV(IJI) = 0.0 IJl = IJl + N GO TO 130 RV(IJ) = A(I,J) IJ = IJ + N II = I + J IF (II .GT. N) G O T O 1 5 0 JJ = MB - J IF ( E 2 1 .GE. 0 . 0 ) G O T O 1 4 0 II = I JJ = M B + J RV(KJ) = A(II,JJ) KJ = KJ + N CONTINUE

C 180

200

RV(IJ) = A(I,MB) - X1 RV6(1) = EPS4 IF ( O R D E R .EQ. 0 . 0 ) R V 6 ( 1 ) CONTINUE

=

Z(I,R)

C IF (MI .EQ. 0) G O T O 6 0 0 ~********* ELIMINATION WITH D O 5 8 0 1 = I, N II = I + I MAXK = MIN0(I+MI-I,N) MAXJ = MIN0(N-I,M21-2)

C

INTERCHANGES

C DO

3 6 0 K = I, M A X K KJI = K J = KJI + N JJ = J + MAXJ

C DO

340

3 4 0 K J = J, J J, N RV(KJI) = RV(KJ) KJI = KJ CONTINUE

153

* N

*******~**

7.1-18

RV(KJI) CONTINUE

360

=

0.0

C IF (I o E Q . N) G O T O 5 8 0 U = 0.0 MAXK = MIN0(I+MI,N) MAXJ = MIN0(N-II,M21-2)

* N

C DO

4 5 0 J = I, M A X K IF (ABS(RV(J)) .LT. u

=

ABS(U))

GO

TO

450

RV(J)

K = J CONTINUE

450 C

J = I + N JJ = J + MAXJ I F (K . E Q . I) KJ = K

GO

TO

520

C DO

500

5 0 0 I J = I, J J , V = R V (I J) RV(IJ) = RV(KJ) RV(KJ) = V KJ = KJ + N CONTINUE

N

520

IF (ORDER .NE. 0.0) GO TO V = R V 6 (I) RV6(1) = RV6(K) R V 6 (K) = V I F (U . E Q . 0 . 0 ) G O T O 5 8 0

C 520

C DO

560 K = II, MAXK V = RV(K) / U KJ = K

C DO

5 4 0 I J = J, J J, KJ = KJ + N RV(KJ) = RV(KJ) CONT-INUE

540

N - V

* RV(IJ)

C IF (ORDER CONTINUE

560

.EQ.

0.0)

RV6(K)

=

RV6(K)

- V

* RV6(1)

C 580 C

CONTINUE ******4***

C

600

DO

BACK SUBSTITUTION FOR I=N STEP -i UNTIL 6 3 0 I I = I, N I = N + i - ii MAXJ = MIN0(II,M21) IF (MAXJ . E Q . i) G O T O 6 2 0 !Jl = I J = IJl + N

t54

I DO

--

**********

7.1-19 JJ

= J +

(MAXJ

-

2)

DO

6 1 0 I J = J, J J , IJl = IJl + 1 RV6(1) = RV6(1) CONTINUE

610 620

625 630

* N N - RV(IJ)

v = RV(I) IF (ABS(V) .GE. EPS3) GO ********** SET ERROR -- NEARLY IF (ORDER .EQ. 0.0) IERR V = SIGN(EPS3,V) RV6(1) = RV6(1) / V CONTINUE

* RV6(IJI)

TO 625 SINGULAR = -R

XU = 1.0 IF ( O R D E R .EQ. 0.0) GO TO 870 ****~***** ORTHOGONAL!ZE WITH RESPECT MEMBERS OF GROUP ********** IF (GROUP . E Q . 0) G O T O 7 0 0 DO

6 8 0 J J = i, G R O U P J = R - GROUP - i + XU = 0.0

640

DO XU

6 4 0 1 = i, N = XU + RV6(I)

660

DO 660 RV6(1)

1

=

i,

TO

JJ

N

= RV6(1)

- XU

CONTINUE

700

NORM

720

D O 7 2 0 1 = i, N NORM = NORM + ABS(RV6(1))

* Z(I,J)

0.0

IF (NORM .GE. 1.0E-I) GO TO 840 ********** IN-LINE PROCEDURE FOR CHOOSING A NEW STARTING VECTOR ********** I F ( I T S .GE. N) G O T O 8 3 0 ITS = ITS + 1 XU = EPS4 / (UK + 1.0) RV6(1) = EPS4

760

DO 760 RV6(1)

1 = 2, = XU

N

RV6(ITS) = RV6(ITS) GO TO 600

- EPS4

155

* UK

SYSTEM

PREVIOUS

* Z(I,J)

680

=

LINEAR

**********

7.1-20 C 830

C C 840

******~*** SET ERROR -!ERR = -R XU = 0.0 GO TO 870 ********** NORMALIZE SO i AND EXPAND U = 0,0

NON-CONVERGED

THAT SUM OF SQUARES IS TO FULL ORDER **********

C 860

D O 8 6 0 1 = I, N U = U + RV6(1)**2

C XU

=

1.0

/

SQRT(U)

C 870 900

DO 900 Z(I,R)

1 = i, N = RV6(1)

* XU

C 920

X0 = XI CONTINUE

C I001

EiGENVECTOR

RETURN END

156

********~*

7.1-21

NATS

PROJECT

EIGENSYSTEM.SUBROUTINE F294-2 A Fortran

PACKAGE BISECT

IV S u b r o u t i n e to D e t e r m i n e of a S y m m e t r i c T r i d i a g o n a l

May, February,

(EISPACK)

Some E i g e n v a l u e s Matrix.

1972 1977

I. P U R P O S E . The F o r t r a n IV s u b r o u t i n e BISECT determines e i g e n v a l u e s of a s y m m e t r i c t r i d i a g o n a l m a t r i x interval using Sturm sequencing.

those in a s p e c i f i e d

2. USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

BISECT(N,EPSI,D,E,E2,LB,UB, MM,M,W,!ND,IERR,RV4,RV5)

T h e p a r a m e t e r s are d i s c u s s e d b e l o w a n d the i n t e r p r e t a t i o n of w o r k i n g p r e c i s i o n for v a r i o u s m a c h i n e s is g i v e n in the s e c t i o n d i s c u s s i n g c e r t i f i c a t i o n . is an i n t e g e r i n p u t v a r i a b l e the o r d e r of the m a t r i x . EPSI

set e q u a l

to

is a w o r k i n g p r e c i s i o n r e a l v a r i a b l e . On input, it s p e c i f i e s an a b s o l u t e e r r o r t o l e r a n c e for the c o m p u t e d e i g e n v a l u e s . If the i n p u t EPSI is n o n - p o s i t i v e , it is r e s e t to a d e f a u l t v a l u e d e s c r i b e d in s e c t i o n 2C. is a w o r k i n g p r e c i s i o n r e a l i n p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g the d i a g o n a l e l e m e n t s of the symmetric tridiagonal matrix. is a w o r k i n g p r e c i s i o n r e a l i n p u t o n e d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g , in its last N-I positions, the s u b d i a g o n a l e l e m e n t s of the s y m m e t r i c tridiagonal matrix. E(1) is a r b i t r a r y .

157

7.1-22

E2

is a w o r k i n g p r e c i s i o n r e a l o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N. On input, the l a s t N-I p o s i t i o n s in this a r r a y c o n t a i n the s q u a r e s of the s u b d i a g o n a l e l e m e n t s of the s y m m e t r i c t r i d i a g o n a l matrix. E2(1) is a r b i t r a r y . On o u t p u t , E2(1) is set to zero. If a n y of the e l e m e n t s in E are r e g a r d e d as n e g l i g i b l e , the c o r r e s p o n d i n g e l e m e n t s of E2 are set to zero, a n d so the m a t r i x s p l i t s i n t o a d i r e c t s u m of s u b m a t r i c e s .

LB,UB

are working precision real input variables s p e c i f y i n g the l o w e r and u p p e r e n d p o i n t s , r e s p e c t i v e l y , of the i n t e r v a l to be s e a r c h e d for the e i g e n v a l u e s . If LB is n o t less than UB, BISECT c o m p u t e s no e i g e n v a l u e s . See s e c t i o n 2C for f u r t h e r d e t a i l s .

MM

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to a n u p p e r b o u n d for the n u m b e r of e i g e n v a l u e s in the i n t e r v a l (LB,UB). is an i n t e g e r o u t p u t v a r i a b l e set e q u a l to the n u m b e r of e i g e n v a l u e s d e t e r m i n e d to lie in the i n t e r v a l (LB,UB). is a w o r k i n g p r e c i s i o n r e a l o u t p u t o n e d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t MM c o n t a i n i n g the M e i g e n v a l u e s of the s y m m e t r i c t r i d i a g o n a l m a t r i x in the i n t e r v a l (LB,UB). T h e e i g e n v a l u e s a r e in a s c e n d i n g o r d e r in W.

IND

is an i n t e g e r o u t p u t o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t MM c o n t a i n i n g the s u b m a t r i x i n d i c e s a s s o c i a t e d w i t h the c o r r e s p o n d i n g M e i g e n v a l u e s in W. E i g e n v a l u e s b e l o n g i n g to the f i r s t submatrix have index I, t h o s e b e l o n g i n g to the s e c o n d s u b m a t r i x h a v e i n d e x 2, etc.

IERR

is a n i n t e g e r o u t p u t v a r i a b l e set e q u a l an e r r o r c o m p l e t i o n c o d e d e s c r i b e d in s e c t i o n 2B. The normal completion code zero.

RV4,RV5

to is

are w o r k i n g p r e c i s i o n r e a l t e m p o r a r y oned i m e n s i o n a l v a r i a b l e s of d i m e n s i o n at l e a s t N u s e d to h o l d the l o w e r a n d u p p e r b o u n d s for the e i g e n v a l u e s in the b i s e c t i o n process.

158

7.1-23

B. Error

Conditions

and Returns.

If M exceeds MM~ BISECT terminates with no eigenvalues computed, and IERR is set to 3*N+I. Upon this error exit, M contains the n u m b e r of e i g e n v a l u e s d e t e r m i n e d to lie in (LB,UB). If

M

does not

C. A p p l i c a b i l i t y

exceed

MM,

IERR

is set

to zero.

and Restrictions.

To d e t e r m i n e some of the eigenvalues of a full symmetric matrix, BISECT should be preceded by TREDI (F277) to provide a suitable symmetric tridiagonal m a t r i x for BISECT. To d e t e r m i n e some of the e i g e n v a l u e s of a complex H e r m i t i a n matrix, BISECT should be preceded by HTRIDI (F284) to provide a suitable real symmetric tridiagonal m a t r i x for BISECT. Some of the eigenvalues of certain n o n - s y m m e t r i c tridiagonal matrices can be computed using the c o m b i n a t i o n of FIGI (F280) and BISECT. See F280 for the d e s c r i p t i o n of this special class of matrices. For these matrices, BISECT should be preceded by FIGI to p r o v i d e a suitable symmetric m a t r i x for BISECT. To determine e i g e n v e c t o r s a s s o c i a t e d with the computed eigenvalues, BISECT should be followed by TINVlT (F223) and the a p p r o p r i a t e back t r a n s f o r m a t i o n s u b r o u t i n e -TRBAKI (F279) after TREDI, HTRIBK (F285) after HTRIDI, or BAKVEC (F281) after FIGI. The subroutines TQLI (F289) and IMTQLI (F291) d e t e r m i n e all the eigenvalues of a symmetric tridiagonal m a t r i x faster than BISECT determines 25 percent of them. Hence, if more than 25 p e r c e n t of them are desired, it is r e c o m m e n d e d that TQLI or IMTQLI be used. The interval (LB,UB) is formally half-open, not including the upper endpoint UB. However, because of rounding errors, the true e i g e n v a l u e s very close to the endpoints of the interval may be e r r o n e o u s l y counted or missed. The input interval (LB,UB) may be refined i n t e r n a l l y to a smaller interval known to contain all the eigenvalues in (LB,UB). This insures that BISECT will not p e r f o r m u n n e c e s s a r y b i s e c t i o n steps to d e t e r m i n e the eigenvalues in (LB,UB).

159

7.1-24

T h e p r e c i s i o n of the c o m p u t e d e i g e n v a l u e s is c o n t r o l l e d t h r o u g h the p a r a m e t e r EPS1. To o b t a i n e i g e n v a l u e s a c c u r a t e to w i t h i n a c e r t a i n a b s o l u t e e r r o r , EPSI s h o u l d be set to that e r r o r . In p a r t i c u l a r , if MACHEP d e n o t e s the r e l a t i v e m a c h i n e p r e c i s i o n , then to o b t a i n the e i g e n v a l u e s to a n a c c u r a c y c o m m e n s u r a t e w i t h s m a l l relative perturbations of the o r d e r of MACHEP in the m a t r i x e l e m e n t s , it is e n o u g h for m o s t t r i d i a g o n a l m a t r i c e s that EPSI be a p p r o x i m a t e l y MACHEP times a n o r m of the m a t r i x . But s o m e m a t r i c e s r e q u i r e a s m a l l e r EPSI for this a c c u r a c y , p e r h a p s as s m a l l as MACHEP times the e i g e n v a l u e of s m a l l e s t m a g n i t u d e in (LB,UB). N o t e , h o w e v e r , that if EPSI is s m a l l e r t h a n r e q u i r e d , BISECT w i l l p e r f o r m u n n e c e s s a r y b i s e c t i o n s t e p s to d e t e r m i n e the e i g e n v a l u e s . F o r f u r t h e r d i s c u s s i o n of EPSI, see r e f e r e n c e (i). If the i n p u t EPSI is n o n - p o s i t i v e , BISECT r e s e t s it, for each s u b m a t r i x , to -MACHEP t i m e s the l - n o r m of the s u b m a t r i x and u s e s its m a g n i t u d e . T h i s v a l u e is t e n t a t i v e l y c o n s i d e r e d a d e q u a t e for c o m p u t i n g the e i g e n v a l u e s to an a c c u r a c y c o m m e n s u r a t e w i t h s m a l l relative perturbations of the o r d e r of MACHEP in the matrix elements.

3. D I S C U S S I O N

OF M E T H O D

AND

ALGORITHM.

The eigenvalues are determined a p p l i e d to the S t u r m s e q u e n c e .

by

the m e t h o d

of b i s e c t i o n

T h e c a l c u l a t i o n s p r o c e e d as f o l l o w s . F i r s t , the s u b d i a g o n a l e l e m e n t s are t e s t e d for n e g l i g i b i l i t y . If an e l e m e n t is c o n s i d e r e d n e g l i g i b l e , its s q u a r e is set to zero, and so the m a t r i x s p l i t s into a d i r e c t sum of s u b m a t r i c e s . T h e n , the S t u r m s e q u e n c e for the e n t i r e m a t r i x is e v a l u a t e d at UB and LB g i v i n g the n u m b e r of e i g e n v a l u e s of the m a t r i x less t h a n UB and LB respectively. T h e d i f f e r e n c e is the n u m b e r of e i g e n v a l u e s in (LE,UB). N e x t , a s u b m a t r i x is e x a m i n e d for its e i g e n v a l u e s in the interval (LB,UB). T h e G e r s c h g o r i n i n t e r v a l , k n o w n to c o n t a i n a l l the e i g e n v a l u e s , is d e t e r m i n e d a n d u s e d to r e f i n e the i n p u t i n t e r v a l (LB,UB). If the i n p u t EPSI is n o n p o s i t i v e , it is r e s e t to the d e f a u l t v a l u e d e s c r i b e d in s e c t i o n 2C. T h e n , s u b i n t e r v a l s , e a c h e n c l o s i n g an e i g e n v a l u e in (LB,UB), a r e s h r u n k u s i n g a b i s e c t i o n p r o c e s s u n t i l the e n d p o i n t s of e a c h s u b i n t e r v a l are c l o s e e n o u g h to be a c c e p t e d as an e i g e n v a l u e of the s u b m a t r i x . H e r e the e n d p o i n t s of each s u b i n t e r v a l are c l o s e e n o u g h w h e n they d i f f e r by less than MACHEP t i m e s t w i c e the sum of the m a g n i t u d e s of the e n d p o i n t s p l u s the a b s o l u t e e r r o r t o l e r a n c e EPSI.

160

7.1-25

The submatrix eigenvalues are then merged found e i g e n v a l u e s into an ordered set. The above steps are repeated eigenvalues in the interval

on each (LB,UB)

with

previously

s u b m a t r i x until are computed~

all

the

This s u b r o u t i n e is a subset (except for the section m e r g i n g eigenvalues of submatrices) of the F o r t r a n s u b r o u t i n e TSTURM (F293), which is a t r a n s l a t i o n of the Algol p r o c e d u r e TRISTURM w r i t t e n and d i s c u s s e d in detail by Peters and W i l k i n s o n (2). A similar Algol procedure BISECT is d i s c u s s e d in detail by Barth, Martin, and W i l k i n s o n (i).

4. REFERENCES.

i)

Barth, W., Martin, R.S., and Wilkinson, J.H., of the E i g e n v a l u e s of a Symmetric T r i d i a g o n a l the M e t h o d of Bisection, Num. Math. 9,386-393

2)

Peters, G. and Wilkinson, J.H., The C a l c u l a t i o n of Specified E i g e n v e c t o r s by Inverse Iteration, H a n d b o o k A u t o m a t i c Computation~ Volume II~ Linear Algebra~ J. H. W i l k i n s o n - C. Reinsch, C o n t r i b u t i o n 11/18, 418-439, Springer-Verlag, 1971.

Calculation M a t r i x by (1967).

for

5. CHECKOUT. A. Test

Cases.

See the section d i s c u s s i n g testing of the codes for complex Hermitian, real symmetric, real symmetric tridiagonal, and certain real n o n - s y m m e t r i c t r i d i a g o n a l matrices.

B. Accuracy. The subroutine BISECT is n u m e r i c a l l y stable (1,2); that is, the computed eigenvalues are close to those of the original matrix. In addition, they are the exact eigenvalues of a matrix close to the original real symmetric tridiagonal matrix.

t61

7.1-26

SUBROUTINE

BiSECT(N,EPSI,D,E,E2,LB,UB,MM,M,W,

IND,IERR,RV4,RV5)

INTEGER I,J,K,L,M,N,P,Q,R,S,II,MM,MI,M2,TAG,IERR,ISTURM REAL D(N),E(N),E2(N),W(MM),RV4(N),RV5(N) REAL U,V,LB,TI,T2,UB,XU,XO,XI~EPSI,MACHEP REAL ABS,AMAXI,AMINI,FLOAT INTEGER IND(MM) **********

MACHEP IS A THE RELATIVE

MACHINE DEPENDENT PARAMETER SPECIFYING PRECISION OF FLOATING POINT ARITHMETIC.

********** MACHEP

C

20 40 C

C

60

80

C

C i00

=

?

IERR = 0 TAG = 0 T1 = LB T2 = UB ********** LOOK FOR SMALL SUB-DIAGONAL ENTRIES ********** D O 4 0 I = I, N I F (I . E Q . i) G O T O 2 0 IF (ABS(E(1)) .GT. MACHEP * (ABS(D(1)) + ABS(D(I-I)))) X GO TO 40 E2(1) = 0.0 CONTINUE ********** DETERMINE THE NUMBER OF EIGENVALUES IN THE INTERVAL ********** P = 1 Q = N X1 = UB ISTURM = I GO TO 320 M = S X1 = LB ISTURM = 2 GO TO 320 M = M - S I F (M . G T . M M ) G O T O 9 8 0 Q = 0 R = 0 ********** ESTABLISH AND PROCESS NEXT SUBMATRIX, REFINING INTERVAL BY T H E G E R S C H G O R I N BOUNDS ********** I F (R . E Q . M ) G O T O I 0 0 1 TAG = TAG + i P = Q * I XU = D (P) X0 = D(P) U = 0.0

162

7.1-27

DO

it0

120 140

C

180

200

220 C

1 2 0 Q = P, N X1 = U U = 0.0 V = 0.0 I F (Q . E Q . N) G O T O i i 0 U = ABS(E(Q+I)) V = E2 ( q + l ) XU = AMINI(D(Q)-(XI+U) ,XU) X0 = AMAXI(D(Q)+(XI+U) ,X0) I F (V .EQ. 0 . 0 ) G O T O 1 4 0 CONTINUE

XI = AMAXI(ABS(XU),ABS(X0)) * MACHEP IF (EPSI .LE. 0.0) EPSI = -XI I F (P . N E . Q) G O T O 1 8 0 ********** CHECK FOR ISOLATED ROOT WITHIN INTERVAL I F (TI . G T . D ( P ) .OR. D(P) .GE. T2) GO TO 940 MI = P M2 = P RVB(P) = D(P) GO TO 900 XI = XI * FLOAT(Q-P+I) LB = AMAXI(TI,XU-XI) UB = AMINI(T2,X0+XI) X1 = LB ISTURM = 3 GO TO 320 MI = S + I XI = UB ISTURM = 4 GO TO 320 M2 = S IF (MI .GT. M2) GO TO 940 ********** FIND ROOTS BY BISECTION ********~* X0 = UB ISTURM = 5

**********

DO

240

250

260

240 1 = MI, M2 R V 5 (I) -- U B RV4(1) = LB CONTINUE ********** LOOP FOR K-TH EIGENVALUE FOR K=M2 STEP -I UNTIL MI DO -(-DO- NOT USED TO LEGALIZE -COMPUTED GO TO-) K = M2 XU = LB ********** FOR I=K STEP -i UNTIL MI DO -- ********** DO 260 II = MI, K I = M1 + K - II IF (XU .GE. RV4(1)) GO TO 260 XU = RV4(1) GO TO 280 CONTINUE

163

**********

7.1-28

280

IF (X0 .GT. R V 5 ( K ) ) X0 = R V 5 ( K ) ********** NEXT BISECTION STEP ********** 300 X1 = (XU + X0) * 0 . 5 IF ( ( X 0 - XU) .LE. (2.0 * M A C H E P * X (ABS(XU) + ABS(X0)) + ABS(EPSI))) G O TO 420 ********** IN-LINE PROCEDURE FOR STURM SEQUENCE ********** 320 S = P - 1 U=I.0 DO

325 330

u

380

400

420

900

=

D(I)

IF (U CONTINUE

340

360

340 I = P, Q IF (U .NE. 0 . 0 ) GO TO 3 2 5 V = ABS(E(1)) / MACHEP IF ( E 2 ( 1 ) .EQ. 0 . 0 ) V = 0 . 0 GO TO 3 3 0 V = E2(1) / U -

Xl

.LT.

-

0.0)

V

S = S +

I

GO TO ( 6 0 , 8 0 , 2 0 0 , 2 2 0 , 3 6 0 ) , ISTURM ********** REFINE INTERVALS ********** IF (S .GE. K) GO TO 4 0 0 XU = X1 IF (S .GE. M I ) GO TO 3 8 0 RV4(MI) = X1 GO TO 3 0 0 RV4(S+I) = XI IF ( R V 5 ( S ) .GT. XI) R V 5 ( S ) = XI GO TO 3 0 0 X0 = X1 GO TO 3 0 0 ********** K-TH EIGENVALUE FOUND ********** R V 5 ( K ) = XI K = K - 1 IF (K .GE. MI) G O T O 2 5 0 ********** ORDER EIGENVALUES TAGGED WITH THEIR SUBMATRIX ASSOCIATIONS ********** S = R R

=

R

+

M2

-

M1

+

1

J = 1 K = MI DO

9 2 0 L = I, IF (J .GTo IF (K .GT. IF ( R V 5 ( K )

R S) GO TO 9 1 0 M2) GO TO 9 4 0 .GE. W ( L ) ) GO

DO

905

9 0 5 II = J, S I = L + S - !I W(I+1) = W(i) IND(I+I) = IND(1) CONTINUE

164

TO

915

7.1-29

910

915 920 940

W(L) = RVS(K) IND(L) = TAG K = K + 1 GO TO 920 J = J + 1 CONTINUE I F (Q . L T . GO TO i001 **********

980 IERR = I001LB = T1 UB = T2 RETURN END

N)

GO

TO

I00

SET ERROR -- UNDERESTIMATE OF NUMBER EIGENVALUES IN INTERVAL ********** 3 * N + 1

165

OF

7.1-30

NATS

EiGENSYSTEM

PROJECT

SUBROUTINE F236

A Fortran

PACKAGE

(EISPACK)

BQR

IV S u b r o u t i n e to D e t e r m i n e S o m e E i g e n v a l u e s of a R e a l S y m m e t r i c Band M a t r i x .

July,

1975

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e BQR d e t e r m i n e s s o m e of the e i g e n v a l u e s of a r e a ! s y m m e t r i c b a n d m a t r i x u s i n g the QR a l g o r i t h m w i t h s h i f t s of o r i g i n . It d e t e r m i n e s one e i g e n v a l u e for e a c h call, d e f l a t i n g the m a t r i x b e f o r e returning. T h e s u b r o u t i n e c o u l d be u s e d to d e t e r m i n e all of the e i g e n v a l u e s ; h o w e v e r , m o r e e f f i c i e n t r o u t i n e s e x i s t in this c a s e (see s e c t i o n 2C).

2. U S A G E . A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

BQR(NM,N,MB~A,TjR,IERR,NV,RV)

T h e p a r a m e t e r s are d i s c u s s e d b e l o w and the i n t e r p r e t a t i o n of w o r k i n g p r e c i s i o n for v a r i o u s m a c h i n e s is g i v e n in the s e c t i o n d i s c u s s i n g c e r t i f i c a t i o n . NM

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to the row d i m e n s i o n of the t w o - d i m e n s i o n a l array A as s p e c i f i e d in the D I M E N S I O N s t a t e m e n t for A in the c a l l i n g p r o g r a m . is an i n t e g e r i n p u t v a r i a b l e the o r d e r of the m a t r i x A. greater than NM.

MB

set e q u a l to N m u s t be n o t

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to the (half) b a n d w i d t h of the m a t r i x A, d e f i n e d as the n u m b e r of a d j a c e n t d i a g o n a l s , i n c l u d i n g the p r i n c i p a l d i a g o n a l , r e q u i r e d to s p e c i f y the n o n - z e r o p o r t i o n of the l o w e r t r i a n g l e of the m a t r i x . ME m u s t be not g r e a t e r than N for the f i r s t c a l l of BQR (see s e c t i o n 2C).

166

7.1-31

is a w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t MB. On i n p u t , A c o n t a i n s the l o w e r t r i a n g l e of the s y m m e t r i c b a n d m a t r i x of o r d e r N a n d (half) b a n d width MB w h i c h w i t h the s h i f t p a r a m e t e r T d e f i n e s the m a t r i x w h o s e e i g e n v a l u e s a r e sought. Its l o w e s t s u b d i a g o n a l is s t o r e d in the l a s t N+I-MB p o s i t i o n s of the f i r s t c o l u m n , its n e x t s u b d i a g o n a l in the l a s t N+2-MB p o s i t i o n s of the s e c o n d c o l u m n , f u r t h e r s u b d i a g o n a l s s i m i l a r l y , and f i n a l l y its p r i n c i p a l d i a g o n a l in the N positions of the last c o l u m n . C o n t e n t s of s t o r a g e l o c a t i o n s n o t p a r t of the m a t r i x are arbitrary. For example, when N=5 and MB=3, A should contain ( * ( * (A(3,1) (A(4,2) (A(5,3)

* A(2,1) A(3,2) A(4,3) A(5,4)

A(I,I) A(2,2) A(3,3) A(4,4) A(5,5)

) ) ) ) )

w h e r e the s u b s c r i p t s for e a c h e l e m e n t r e f e r to the r o w a n d c o l u m n of the e l e m e n t in the s t a n d a r d t w o - d i m e n s i o n a l r e p r e s e n t a t i o n , and (*) d e n o t e s an a r b i t r a r y v a l u e . On o u t p u t , A has the same f o r m as on input, e x c e p t h a v i n g b e e n d e f l a t e d (by a z e r o e d last row) to n e x t l o w e r order. It is thus s u i t a b l e as an i n p u t p a r a m e t e r for a f u r t h e r call of BQR if an a d d i t i o n a l e i g e n v a l u e is s o u g h t . is a w o r k i n g p r e c i s i o n r e a l v a r i a b l e . On input, T s p e c i f i e s the s h i f t a p p l i e d to the d i a g o n a l e l e m e n t s of A; the m a t r i x w h o s e e i g e n v a l u e is to b e d e t e r m i n e d is thus A+TI where I is the i d e n t i t y m a t r i x . The o u t p u t v a l u e of T is s i m u l t a n e o u s l y an e i g e n v a l u e of A + T I ( g e n e r a l l y that one n e a r e s t to the i n p u t T) and the s h i f t a p p l i e d to the d i a g o n a l e l e m e n t s of the output A matrix. It is thus s u i t a b l e as an i n p u t p a r a m e t e r (along w i t h A) for a f u r t h e r c a l l of BQR if an a d d i t i o n a l e i g e n v a l u e is s o u g h t .

167

7.1-32

B.

Error

R

is a w o r k i n g p r e c i s i o n r e a l v a r i a b l e u s e d to d e t e r m i n e w h e n the l a s t r o w (and c o l u m n ) of the current transformed b a n d m a t r i x in A c a n be r e g a r d e d as n e g l i g i b l e . It s h o u l d be set to zero for the f i r s t c a l l of BQR and w i l l be r e s e t by the s u b r o u t i n e at e a c h c a l l to a v a l u e s u i t a b l e as i n p u t for the subsequent c a l l (see s e c t i o n 3).

IERR

is an i n t e g e r o u t p u t v a r i a b l e set e q u a l an e r r o r c o m p l e t i o n c o d e d e s c r i b e d in s e c t i o n 2B. The normal completion code zero.

is

NV

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to the d i m e n s i o n of the a r r a y RV as s p e c i f i e d in the D I M E N S I O N statement for RV in the calling program. NV m u s t be n o t less t h a n 2*MB**2+4*MB-3.

RV

is a w o r k i n g p r e c i s i o n real temporary array variable of d i m e n s i o n at l e a s t 2*MB**2+4*MB-3. The first 3*MB-2 locations are used for auxiliary storage~ thereby permitting the t r a n s f o r m e d elements of A to be s t o r e d b a c k i n t o A. The next 2*MB-I l o c a t i o n s a r e u s e d to s t o r e the s c a l a r (half) l e n g t h s of the v e c t o r s that d e f i n e the e l e m e n t a r y Hermitians at e a c h s t a g e of t h e u n i t a r y r e d u c t i o n p r o c e s s . The final MB*(2*MB-I) l o c a t i o n s a r e u s e d to store these vectors themselves.

Conditions

and

If m o r e t h a n 30 the e i g e n v a l u e ,

Returns°

iterations are BQR terminates

If the e i g e n v a l u e is d e t e r m i n e d IERR is set to zero.

C.

to

Applicability

and

r e q u i r e d to with IERR within

30

determine set to N. iterations,

Restrictions.

To d e t e r m i n e some of the e i g e n v a l u e s of a b a n d s y m m e t r i c matrix, BQR s h o u l d be c a l l e d s u c c e s s i v e l y for each eigenvalue, transmitting the output parameters f r o m the previous c a l l e x c e p t for r e p l a c e m e n t of N by N-I. N o t e that MB s h o u l d n o t be a l t e r e d e v e n w h e n it e x c e e d s the c u r r e n t N. The eigenvalues determined will u s u a l l y be t h o s e n e a r e s t to the i n p u t v a l u e of T.

168

7.1-33

To d e t e r m i n e a l l the e i g e n v a l u e s of a b a n d s y m m e t r i c matrix, subroutine B A N D R (F226) s h o u l d be u s e d i n s t e a d , f o l l o w e d by TQLI ( F 2 8 9 ) , I M T Q L I (F291), or r Q L R A T (F235) . To d e t e r m i n e e i g e n v e c t o r s a s s o c i a t e d w i t h the c o m p u t e d eigenvalues, BQR s h o u l d be f o l l o w e d by B A N D V (F227). Note, h o w e v e r , that the m a t r i x A+TI d e f i n e d by the original A and T p a r a m e t e r s m u s t be s a v e d b e f o r e BQR for its l a t e r u s e by BANDV. If the m a t r i x has e l e m e n t s of w i d e l y v a r y i n g m a g n i t u d e s , the l a r g e r ones s h o u l d be in the top l e f t - h a n d c o r n e r .

3. D I S C U S S I O N

OF M E T H O D

AND ALGORITHM.

T h e aim of the a l g o r i t h m is to o b t a i n the e i g e n v a l u e of A of s m a l l e s t m a g n i t u d e ; i.e., the e i g e n v a l u e of A+TI nearest to T. T h e e i g e n v a l u e is d e t e r m i n e d by the QR method. The e s s e n c e of this m e t h o d is a p r o c e s s w h e r e b y a s e q u e n c e of s y m m e t r i c b a n d m a t r i c e s , u n i t a r i l y s i m i l a r to the o r i g i n a l s y m m e t r i c b a n d m a t r i x w i t h s h i f t e d o r i g i n is f o r m e d w h i c h c o n v e r g e s to a m a t r i x w i t h a zero last r o w (and c o l u m n ) . The sum of the o r i g i n s h i f t s is t h e n t a k e n as a n e i g e n v a l u e of A, and this n u m b e r a d d e d to the i n p u t T is r e t u r n e d as the d e s i r e d e i g e n v a l u e of A+TI. S h i f t i n g is d e f e r r e d u n t i l the o f f - d l a g o n a l e l e m e n t s of the last row of the t r a n s f o r m e d A b e c o m e s m a l l e n o u g h that t h e i r s u m m e d m a g n i t u d e s does not e x c e e d 1/4 of the tolerance quantity R. S h i f t i n g s o o n e r than this c o u l d l o s e s i g h t of the d e s i r e d e i g e n v a l u e , w h i l e s h i f t i n g too l a t e w o u l d a p p r e c i a b l y s l o w the a l g o r i t h m . R is r e s e t at e a c h call to the m a x i m u m of its c u r r e n t v a l u e a n d the s u m m e d m a g n i t u d e s of the o f f - d i a g o n a l e l e m e n t s of the c u r r e n t last row of A. The s h i f t i n g c r i t e r i o n a d o p t e d is e f f e c t i v e as long as the rows of A are n o t r a p i d l y i n c r e a s i n g f r o m top to b o t t o m . W h e n an o r i g i n s h i f t f i n a l l y takes p l a c e , it is c h o s e n as the e i g e n v a l u e of the l o w e s t 2x2 p r i n c i p a l m i n o r c l o s e r to the s e c o n d d i a g o n a l e l e m e n t of this m i n o r . W h e n the last r o w (and c o l u m n ) of the m a t r i x b e c o m e n e g l i g i b l e , then the s u m of the o r i g i n s h i f t s a d d e d to the i n p u t T is r e t u r n e d in T as the e i g e n v a l u e of A+TI and the m a t r i x is d e f l a t e d by d e l e t i n g (zeroing) its last row (and c o l u m n ) . T h i s s u b r o u t i n e is a t r a n s l a t i o n of the A l g o l p r o c e d u r e w r i t t e n and d i s c u s s e d in d e t a i l by M a r t i n , R e i n s c h , and W i l k i n s o n (i).

169

BQR

7.1-34

4. REFERENCES. I)

Martin, R.S., Reinsch, C., and Wilkinson, J.H., The QR A l g o r i t h m for Band Symmetric M a t r i c e s , Num. Math. 16,85-92 (1970). (Reprinted in H a n d b o o k for A u t o m a t i c C o m p u t a t i o n , V o l u m e II, Linear Algebra, J. H. W i l k i n s o n - C. Relnsch, C o n t r i b u t i o n II/7, 266-272j Springer-Verlag, 1971.)

5. CHECKOUT. A.

Test

Cases.

See the section d i s c u s s i n g testing real symmetric band matrices.

of

the codes

for

B. Accuracy~ The s u b r o u t i n e BQR is n u m e r i c a l l y stable (i); that the computed e i g e n v a l u e s are close to those of the original matrix. In a d d i t i o n s they are the exact e i g e n v a l u e s of a m a t r i x close to the original real symmetric band matrix.

170

is,

7.1-35

SUBROUTINE

B Q R (NM, N , M B , A, T, R, I E R R , NV, RV)

C INTEGER

X

I, J , K , L , M , N, II, IK, JK, JM, KJ, KK, KM, L L , M B , M K , M N , M Z , MI ,M2,M3,M4,NI,NM,NV, ITS,KJI,M2 I,M31, IERR, IMULT R E A L A ( N M , M B ) , R V (NV) R E A L F , G , Q , R , S,T, S C A L E REAL SQRT,ABS, SIGN INTEGER MAX0,MIN0

C

C

IERR = 0 MI = M I N 0 ( M B , N ) M = MI - i M2 = M + M M21 = M2 + 1 M3 = M21 + M M31 = M3 + 1 M4 = M31 + M2 MN = M+ N MZ = MB M I ITS = 0 ********** TEST FOR 40 G = A ( N , M B ) IF (M .EQ. O) G O TO F = 0.0

CONVERGENCE

**********

360

C DO

50

50 K = i, M MK = K + MZ F = F + ABS(A(N,MK)) CONTINUE

C

C

IF (ITS .EQ. 0 .AND. F .GT. R) R = F IF (R + F .LE. R) G O TO 3 6 0 IF (ITS .EQ. 30) GO T O 1 0 0 0 ITS = ITS + 1 ********** FORM SHIFT FROM BOTTOM 2 BY 2 M I N O R IF (F .GT. 0 . 2 5 * R .AND. ITS .LT. 5) GO T O 90 F = A(N,MB-I) IF (F .EQ. 0.0) GO T O 70 Q = (A(N-I,MB) - G) / (2.0 * F) S = SQRT(Q*Q+I.0) G = G F / (Q + S I G N ( S , Q ) ) 70 T = T + G

C 80

D O 80 I = i, N A(I,MB) = A(I,MB)

- G

C 90 i00

DO i00 K = M 3 1 , RV(K) = 0.0

M4

C DO

3 5 0 II = I, M N I = II - M NI = N - II IF (NI .LT. 0)

GO

TO

230

171

**********

7. 1 - 3 6

********** FORM COLUMN n = MAX0(I,2-I)

ii0

D O i i 0 K = I, RV(K) = 0.0

OF

SHIFTED

MATRIX

A-G*I

**********

M3

DO

120

1 2 0 K = L, M 1 KM = K + M MK = K + MZ RV(KM) = A(II,MK) CONTINUE LL IF

= MIN0(M,NI) ( L L . E Q . 0)

GO

TO

DO

130 135

140

1 3 0 K = i, L L KM = K + M21 IK = II + K M K = MB K RV(KM) = A(IK,MK) CONTINUE ********** PRE-MULT!PLY LL = M2 !MULT = 0 ****e***** MULTIPLICATION KJ = M4 - M1

135

DO

1 7 0 J = I~ L L KJ = KJ + M I JM = J + M3 IF (RV(JM) .EQ. F = 0.0

WITH

HOUSEHOLDER

PROCEDURE

0.0)

1 5 0 K = i, M I KJ = KJ + i JK = J + K - I F = F + RV(EJ) CONTINUE

GO

TO

**********

170

DO

150

*

RV(JK)

F = F / RV(JM) KJ = KJ - M I 1 6 0 K = I, M 1 KJ = KJ + 1 JK = J + K - 1 RV(JK) = RV(JK) CONTINUE

DO

160

170

KJ = CONTINUE IF

(IMULT

KJ

-

RV(KJ)

- MI

.NE.

0)

GO

TO

280

172

REFLECTIONS

*

F

**********

7.1-37

C

*********e HOUSEHOLDER F = RV(M21) S = 0.0 RV(M4) = 0.0 SCALE = O. 0

REFLECTION

*~********

C 180

DO 180 K = M21, SCALE = SCALE +

M3 ABS(RV(K))

C IF

(SCALE

.EQ.

0.0)

GO

TO

210

C 190

DO 190 K = M21, M3 S = S + (RV(K)/SCALE)**2

C S = SCALE * SCALE * G = -SIGN(SQRT(S),F) RV(M21) = g RV(M4) = S - F * G KJ = M4 + M2 * M1 + RV(KJ) = F - G

S

i

C DO

200 C 210

220

2 0 0 K = 2, M I KJ = KJ + I KM = K +M2 R V ( K J ) -- R V ( K M ) CONTINUE ********** SAVE COLUMN D O 2 2 0 K = L, M 1 KM = K+M MK = K + MZ A(II,MK) = RV(KM) CONTINUE

OF

TRIANGULAR

FACTOR

R

**********

C 230 C 240

L = MAXO(I,MI+I-I) I F (I . L E o 0) G O T O 3 0 0 ********** PERFORM ADDITIONAL D O 2 4 0 K = i, M 2 1 RV(K) = 0.0

STEPS

**********

C C

250 C

LL = MIN0(MI,NI+MI) ********** GET ROW OF TRIANGULAR FACTOR R D O 2 5 0 K K = i, L L K = KK - i KM = K +MI IK = I + K M K = MB K RV(KM) = A(IK,ME) CONTINUE ********** POST-MULTIPLY WITH HOUSEHOLDER LL = MI IMULT = 1 GO TO 140

173

**********

REFLECTIONS

**********

7.1-38

C 280

290 C 300

********** STORE COLUMN OF NEW A MATRIX ********** D O 2 9 0 K = L, M 1 MK = K + MZ A(I,MK) = RV(K) CONTINUE ********** UPDATE HOUSEHOLDER REFLECTIONS ********** I F (L . G T . i) L = L 1 KJI = M4 + L * M1

C DO

3 2 0 J = L, M 2 JM = J + M3 RV(JM) = RV(JM+I)

C DO

3 2 0 K = I, M I KJI = KJI + I KJ = K J1 - M1 RV(KJ) = RV(KJI) CONTINUE

320 350

CONTINUE

360

GO TO 40 • ********* T = T + G

380

DO 380 A(I,MB)

CONVERGENCE

1 = I, N = A(I,MB)

**********

- G

C DO

400

4 0 0 K = i, M I MK = K + MZ A(N,MK) = 0.0 CONTINUE

C GO TO i001 **********

C C i000 i001

IERR = RETURN END

SET ERROR EIGENVALUE

-- NO CONVERGENCE TO AFTER 30 ITERATIONS

N

174

**********

7.1-39

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F233

PACKAGE

(EISPACK)

MINFIT

A F o r t r a n IV S u b r o u t i n e to C o m p u t e the S i n g u l a r V a l u e D e c o m p o s i t i o n of an A r b i t r a r y R e a l R e c t a n g u l a r M a t r i x and the S o l u t i o n of a R e l a t e d L i n e a r L e a s t S q u a r e s P r o b l e m .

July,

1975

I. P U R P O S E . T h e F o r t r a n IV s u b r o u t i n e MINFIT c o m p u t e s the s i n g u l a r v a l u e s and c o m p l e t e o r t h o g o n a l d e c o m p o s i t i o n of the r e a l rectangular coefficient matrix A of the l i n e a r s y s t e m AX = B. A is d e c o m p o s e d into T U * DIAG(S)

* V

T with U itself, minimal are the square

T T U = V V = I. U B is f o r m e d r a t h e r than U e n a b l i n g a d e t e r m i n a t i o n of the s o l u t i o n X of n o r m (see s e c t i o n 2C). The d i a g o n a l e l e m e n t s of s i n g u l a r v a l u e s of A, e q u a l to the n o n - n e g a t i v e T r o o t s of the e i g e n v a l u e s of A A.

2. U S A G E , A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

MINFIT(NM,M,N,A,W,

IP,B,IERR,RVl)

The p a r a m e t e r s are d i s c u s s e d b e l o w and the i n t e r p r e t a t i o n of w o r k i n g p r e c i s i o n for v a r i o u s m a c h i n e s is g i v e n in the s e c t i o n d i s c u s s i n g c e r t i f i c a t i o n . NM

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to the row d i m e n s i o n of the t w o - d i m e n s i o n a l arrays A and B as s p e c i f i e d in the D I M E N S I O N s t a t e m e n t s for A and B in the calling program. Note that A and B are

175

7,1-40

overwritten by N - r o w e d a r r a y s V T U B; h e n c e , NM m u s t be at l e a s t as the m a x i m u m of M and N. is an i n t e g e r the n u m b e r of A and B. M

and as

large

input variable set e q u a l to r o w s of r e c t a n g u l a r matrices m u s t be n o t g r e a t e r t h a n NM.

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to the n u m b e r of c o l u m n s of A a n d the o r d e r of the s q u a r e m a t r i x V which overwrites A. N m u s t be n o t g r e a t e r t h a n NM. is a w o r k i n g p r e c i s i o n real two-dimensional variable with row dimension NM and column dimension at l e a s t N. On input, A contains the rectangular (coefficient) m a t r i x to b e d e c o m p o s e d . On output, A has been overwritten by the o r t h o g o n a l V m a t r i x in the d e c o m p o s i t i o n . W

is a w o r k i n g p r e c i s i o n real output onedimensional v a r i a b l e of d i m e n s i o n at l e a s t N containing the s i n g u l a r v a l u e s of A.

IP

is an i n t e g e r the n u m b e r of zero.

input variable c o l u m n s of B.

set IP

e q u a l to c a n be

is a w o r k i n g p r e c i s i o n real two-dimensional variable with row dimension NM and c o l u m n dimension at l e a s t IP. If IP is not z e r o ~ t h e n on i n p u t , B c o n t a i n s the c o n s t a n t m a t r i x of the s y s t e m . On output, T B has been overwritten by U B. If IP is zero, t h e n B is n o t r e f e r e n c e d and can be a d u m m y ( w o r k i n g p r e c i s i o n ) variable. IERR

RVI

is an i n t e g e r o u t p u t v a r i a b l e set e q u a l an e r r o r c o m p l e t i o n code described in s e c t i o n 2B. The normal completion code zero.

to is

is a w o r k i n g p r e c i s i o n real temporary onedimensional variable of d i m e n s i o n at l e a s t N u s e d to h o l d the o f f - d l a g o n a l e l e m e n t s of the b i d i a g o n a l form.

176

7.1-41

B.

Error

Conditions

and

Returns.

If m o r e t h a n 30 i t e r a t i o n s a r e r e q u i r e d to d e t e r m i n e a s i n g u l a r v a l u e , this s u b r o u t i n e terminates with IERR set to the i n d e x of the s i n g u l a r v a l u e for w h i c h the failure occurs. T h e s i n g u l a r v a l u e s in the W array s h o u l d be c o r r e c t f o r i n d i c e s IERR+I,IERR+2,...,N, as w e l l as the c o r r e s p o n d i n g c o l u m n s of V (in A) a n d r o w s T of U B (in B). If a l l the s i n g u l a r v a l u e s a r e d e t e r m i n e d iterations, IERR is set to zero.

C.

Applicability

and

30

Restrictions.

T h e m i n i m a l n o r m s o l u t i o n of AX = B f r o m the d e c o m p o s i t i o n in MINFIT by + V

within

* DIAG(S

c a n be o b t a i n e d forming

T ) * U

B

+ w h e r e e a c h e l e m e n t of S is the r e c i p r o c a l of the corresponding e l e m e n t of S w h e r e n o n - z e r o and z e r o where S is zero. Some zero t h r e s h o l d w o u l d h a v e to be employed (for e x a m p l e , the p r o d u c t of the s q u a r e r o o t of the m a c h i n e p r e c i s i o n a n d a n o r m of the m a t r i x ) . Sample c o d i n g to p e r f o r m this c o m p u t a t i o n m i g h t be: DO

i00

200 300 C

I00 1 = I, N DO I00 J = I, IP X(I,J) = 0.OD0 DO 300 K = I, N IF (W(K) .LT. T H R E S H ) G O TO 300 DO 200 1 = i, N DO 200 J = I, IP X(I,J) = X(I,J)+A(I,K)*B(K,J)/W(K) CONTINUE THE C O L U M N S OF X A R E T H E M I N I M A L N O R M S O L U T I O N S .

S o l u t i o n s of a s y s t e m of h o m o g e n e o u s linear equations with coefficient matrix A can be o b t a i n e d as t h o s e c o l u m n s of V (or l i n e a r c o m b i n a t i o n s of them) w h i c h correspond to zero e l e m e n t s of S.

177

7.1-42

3. D I S C U S S I O N

OF M E T H O D

AND

ALGORITHM.

T The s i n g u l a r v a l u e d e c o m p o s i t i o n A = U * DIAG(S) * V is a c c o m p l i s h e d in two steps. A is f i r s t r e d u c e d to the bidiagonal form J by two s e q u e n c e s of H o u s e h o l d e r transformations, t h o s e on the left r e d u c i n g c o l u m n s of A and B, a n d t h o s e on the r i g h t r e d u c i n g r o w s of A. Because the t r a n s f o r m a t i o n s are o r t h o g o n a l , J has the same s i n g u l a r T v a l u e s as A, that is J = G * DIAG(S) * H F u r t h e r , if the p r o d u c t of the l e f t t r a n s f o r m a t i o n s is d e n o t e d P and the p r o d u c t of the r i g h t t r a n s f o r m a t i o n s Q, so that T J = P * A * Q, t h e n U = PG and V = QH. The bidiagonal form J is t h e n d e c o m p o s e d by a v a r i a n t of the QR m e t h o d a p p l i e d to the s y m m e t r i c t r i d i a g o n a l m a t r i x T J J. (The s i n g u l a r v a l u e s of J are the n o n - n e g a t i v e T s q u a r e r o o t s of the e i g e n v a l u e s of J J.) T h e e s s e n c e of this m e t h o d is a p r o c e s s w h e r e b y a s e q u e n c e of s y m m e t r i c T t r i d i a g o n a ! m a t r i c e s , u n i t a r i l y s i m i l a r to J J~ is f o r m e d w h i c h c o n v e r g e s to a d i a g o n a l m a t r i x . The r a t e of c o n v e r g e n c e of this s e q u e n c e is i m p r o v e d by s h i f t i n g the o r i g i n at e a c h i t e r a t i o n . B e f o r e the i t e r a t i o n s for e a c h e i g e n v a l u e , the s y m m e t r i c t r i d i a g o n a l m a t r i x is c h e c k e d for a p o s s i b l e s p l i t t i n g into s u b m a t r i c e s . If a s p l i t t i n g o c c u r s , o n l y the l o w e r m o s t s u b m a t r i x p a r t i c i p a t e s in the n e x t iteration. T h e left ( t r a n s p o s e d ) and r i g h t t r a n s f o r m a t i o n s T u s e d in e a c h i t e r a t i o n a r e a c c u m u l a t e d in the U B (in B) and V (in A) a r r a y s . T h e o r i g i n s h i f t at e a c h i t e r a t i o n is an e i g e n v a l u e of the current lowermost 2x2 principal minor. W h e n e v e r the lowermost ixl p r i n c i p a l s u b m a t r i x f i n a l l y s p l i t s f r o m the r e s t of the m a t r i x ~ its e l e m e n t is t a k e n to be a n e i g e n v a l u e of t h e o r i g i n a l m a t r i x a n d the a l g o r i t h m p r o c e e d s w i t h the remaining submatrix. T h i s p r o c e s s is c o n t i n u e d u n t i l the m a t r i x has s p l i t c o m p l e t e l y into s u b m a t r i c e s of o r d e r i. T h e t o l e r a n c e s in the s p l i t t i n g t e s t s are p r o p o r t i o n a l to the relative machine precision. This s u b r o u t i n e MINFIT written R e i n s c h (i).

is a t r a n s l a t i o n of the A l g o l p r o c e d u r e and d i s c u s s e d in d e t a i l by G o l u b and

178

7.1-43

4. REFERENCES.

i)

Golub, G.H. and Reinsch, C., Singular Value D e c o m p o s i t i o n and Least Squares Solutions, Num. Math. 14,403-420 (1970). (Reprinted in H a n d b o o k for A u t o m a t i c Computation, Volume II, Linear Algebra, J. H. W i l k i n s o n - C. Reinsch, C o n t r i b u t i o n I/i0~ 134-151, Springer-Verlag, 1971.)

5. CHECKOUT. A. Test Cases. See the section discussing testing of the codes for singular value decomposition.

B. Accuracy. The subroutine MINFIT is n u m e r i c a l l y stable (I); that is each computed singular value is exact for a m a t r i x close to the original real rectangular matrix.

179

7.1-44

SUBROUTINE

MINFIT(NM,M,N,A,W,!P,B,IERR,RVI)

INTEGER I,J,K,L,M,N,II,IP,II,KK,KI,LL,LI,MI,NM, R E A L A ( N M , N ) , W ( N ) , B (NM, IP) , R V I (N) REAL C,F,G,H~S,X,Y,Z,EPS,SCALE,MACHEP REAL SQRT,AMAXI~ABS,SIGN **********

MACHEP

=

MACHEP IS A M A C H I N E DEPENDENT PARAMETER SPECIFYING THE RELATIVE PRECISION OF F L O A T I N G POINT ARITHMETIC.

?

IERR = 0 ********** HOUSEHOLDER G=0.0 SCALE = 0.0 X=0.0 DO

120

300 1 L = ! + RVI(1) G=0.0 S=O.O SCALE IF (I

= I

I, =

SCALE

= 0.0 .GT. M)

(SCALE

REDUCTION

TO

BIDIAGONAL

N

DO 120 K = I, SCALE = SCALE IF

* G

GO

TO

210

M + ABS(A(K,I))

,EQo

0.0)

GO

TO

210

DO

130

130 K = I, M A(K,!) = A(K,I) / SCALE S = S + A(K,I)**2 CONTINUE F = A(I,I) G = -SlGN(SQRT(S),F) H = F * G - S A(I,I) = F - G IF (I .EQ. N) G O TO DO

!50

J = L,

160

N

S=0.0

140

DO 140 K = I, M S = S + A(K,I) * A(K,J) F

= S

/ H

DO

150

ITS,IERR

150 K = I, M A(K,J) = A(K,J) CONTINUE

+ F

180

* A(K,I)

FORM

**********

7.1-45

160

IF

(IP

.EQ.

DO

180 J = S=O.0

O) I,

GO

TO

190

IP

DO 170 K = I, M S = S + A(K,I) * B(K,J)

170

F=S/H DO

180

180 K = I, M B(K,J) = B(K,J) CONTINUE

190 200

DO 2 0 0 A(K,I)

210

W(1) = SCALE G = 0.0 S = 0.0 SCALE = 0.0 IF (I .GT. M

220

K

=

I,

(SCALE

* A(K,I)

M

= SCALE

* A(K,I)

* G

.OR.

D O 2 2 0 K = L, SCALE = SCALE IF

+ F

I

.EQ.

N)

GO

TO

N + ABS(A(I,K))

.EQ.

0.0)

GO

TO

290

DO

230

2 3 0 K = L, N A(I,K) = A(I,K) / SCALE S = S + A(I,K)**2 CONTINUE

F = A(I,L) g = -SIGN(SQRT(S),F) H = F * G - S A(I,L) = F - G

240

250

DO 2 4 0 RVI(K)

K = L, N = A(I,K)

IF

(I

.EQ.

M)

DO

2 6 0 J = L, S=0.0

GO

/ H TO

270

M

DO 250 K = L, N S = S + A(J,K) * A(I,K) DO

260

260 K = L, N A(J,K) = A(J,K) CONTINUE

+

181

S * RVI(K)

290

7.1-46

270 280

DO 280 A(I,K)

K =

= L~ N SCALE * A(I,K)

C 290 300 C C

X = AMAX!(X,ABS(W(I))+ABS(RVI(I))) CONTINUE ***~****** ACCUMULATION OF RIGHT-HAND F O R I = N S T E P -i U N T I L I DO D O 4 0 0 I I = i, N I = N+ 1 - II I F (I , E Q . N) G O T O 3 9 0 I F (G . E Q , 0 . 0 ) G O T O 3 6 0

TRANSFORMATIONS. -- **********

C C 320

DO 320 ********** A(J,I)

J

= L, N DOUBLE DIVISION AVOIDS = (A(I,J) / A(I,L)) / G

POSSIBLE

UNDERFLOW

**********

C DO

3 5 0 J = L, S = 0.0

N

C DO 3 4 0 K = L , S = S + A(I,K)

340

N *

A(K,J)

C

DO

350

3 5 0 K = L, N A(K,J) = A(K,J) CONTINUE

360

DO

+

S

* A(K,I)

C 3 8 0 J = L, N A(I,J) = 0.0 A(J,I) = 0.0 CONTINUE

380 C 390

A(I,I) G

400

=

=

1.0

RVI(I)

L = I CONTINUE

C IF MI

(M . G E . N = M + i

DO

500

.OR.

IP

.EQ.

0)

GO

TO

510

C I = MI,

N

C DO

500 C 510 C

5 0 0 J = i, I P B(I,J) = 0.0 CONTINUE ********** DIAGONALIZATION EPS = MACHEP * X ********** FOR K=N STEP -I D O 7 0 0 K K = i, N K 1 -- N - K K K = K1 + ! ITS = 0

OF

THE

UNTIL

~82

BIDIAGONAL i DO

--

FORM

**********

**e*******

7.1-47

C C

********** 520

C C 530 C 540

TEST FOR SPLITTING. FOR L=K STEP -I UNTIL 1 DO D O 5 3 0 L L = I, K LI = K - LL L = L1 + i IF (ABS(RVI(L)) .LE. E P S ) G O T O ********** RVI(1) IS A L W A Y S ZERO, SO THROUGH THE BOTTOM OF THE IF (ABS(W(LI)) .LE. E P S ) G O T O CONTINUE ********** CANCELLATION OF RVI(L) IF C = 0.0

--

**********

565 THERE IS NO EXIT LOOP ********** 540 L

GREATER

THAN

1 **********

S=l.O DO

5 6 0 1 = L, K F = S * RVI(1) RVI(1) = C * RVI(1) IF ( A B S ( F ) .LE. E P S ) G = w(I) H = SQRT (F*F+G*G) w(1) -C = g / H S = -F / H I F (IP .EQ. 0) G O T O 5 5 0 J -- i, I P Y = B(LI,J) Z = B(I,J) B(LI,J) = Y * C + B(I,J) = -Y * S + CONTINUE

GO

TO

565

560

DO

550 560

565

Z * S Z * C

CONTINUE ********** TEST FOR CONVERGENCE ********** Z = W(K) I F (L .EQ. K) G O T O 6 5 0 ********** SHIFT FROM BOTTOM 2 BY 2 MINOR IF ( I T S .EQ. 30) G O T O 1 0 0 0 ITS = ITS + 1 X = w(n) Y = W(KI) G = R V I (KI)

**********

= ~ V l (K) = ( ( Y - Z) * (Y + Z) + (G - H) * (G + H ) ) / ( 2 . 0 * H * Y) G = SQRT(F*F+I.0) F = ( ( X - Z) * (X + Z) + H * (Y / (F + S I G N ( G , F ) ) - H)) / X ********** NEXT QR TRANSFORMATION ********** C = 1.0 S = 1.0 H F

183

7.1-48

DO

600 I = G =

Ii = L, II + 1 RVl