ebooksclub.org matrix eigensystem routines eispack guide lecture notes in computer science vol 6

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

6

B. T. Smith. J. M. Boyle B. S. Garbow. Y. Ikebe C. B. Moler

• J. J. Dongarra • V. C. Klema

Matrix Eigensystem EISPACK Guide Second Edition

Routines -

I I I II III

Springer-Verlag Berlin.Heidelberg. New York 19 76

Editorial Board P. Brinch Hansen ° D. Gries • C. Moler . G. SeegmLiller o J. Stoer N. Wirth

Dr. Brian T. Smith Applied Mathematics Division Argonne National Laboratory 9700 South Cass Avenue Argonne, IL 60439/USA

Library of Congress Cataloging in Publication Data

Main entry under title:

Matrix eigensystem r~atines.

(Lectures notes in computer science ; 6) includes bibliog#aphi es. i. EZSPACK (Computer program) Z. Smith~

B~ian T. ZL Series. QA193. M57 1976 512.9'43' 0285425 76-2662

AMS Subject Classif icat ions (1970): 15A18, 65F15 CR Subject Classif icat ions (1974): 5.14

ISBN 3-540-07546q 2. Aufiage Springer-Verlag Berlin • Heidelberg • New York ISBN 0-387-07546-1 2nd edition Springer-Verlag New York • Heidelberg • Berlin ISBN 3-540-06710-8 1, Aufiage Springer-Verlag Berl in. Heidelberg. New York ISBN 0-387-06710-8 1st edition Springer-Vedag 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, re- printing, 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 1976 Printed in Germany Printing and binding: Beltz Offsetdruck, Hemsbach/Bergstr.

PREFACE TO THE SECOND EDITION

The EISPACK eigensystem package as documented in the first edition of

this guide has expanded in both depth and breadth in its second release.

A set of subroutines affording additional variants for the six problem

classes encompassed in the first release has been added. Another set of

additional subroutines has extended the applicability of EISPACK to new

problem classes; prominent among these are the real symmetric band

standard eigenproblem, the symmetric and non-symmetric real generalized

eigenproblems, and the singular value decomposition of an arbitrary matrix.

The EISPAC control program has also been extended to include most of the

newer capability afforded by the additional subroutines in the package.

However, except for the documentation of the EISPAC control program, the

scope of this edition of the guide is still limited to the original six

problem classes and therefore includes additionally only the first of the

two sets of newer subroutines added to EISPACK. Restricting the scope in

this manner has markedly reduced both the time otherwise required to produce

the book and its potential size. It has also enabled timely updating of

the listings and documents of those earlier subroutines that have been

improved in this release. A subsequent volume in this series is planned

that will include the other new subroutines and cover the additional problem

classes that can now be handled by the package.

EISPACK is a product of the NATS (N_ational Activity to T_est S_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 dis-

tributed to several hundred computer centers throughout the world since

the package was first released in May, ]972, 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 per-

sisted in his encouragement of the project and his counsel was often sought

during his frequent visits to North America. Organization and direction

came from W. Cowell and J. Pool, utilizing funds provided by the National

Science Foundation and the Energy Research and Development Administration.

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, C. Frymann, H. Happ, L. Harding, H. Hull,

D. Kincaid, P. Messina, M. Overton, R. Raffenetti, J. Stein, J. Walsh, and

J. Wang. 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.

iV

TABLE OF CONTENTS

SECTION 1

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 All eigenvalues and corresponding eigenvectors of a

complex general matrix . . . . . . . . . . . . . . . . . . .

1.2 All eigenvalues of a complex general matrix .........

1.3 All eigenvalues and selected eigenvectors of a complex general matrix . . . . . . . . . . . . . . . . . . . . . . .

1.4 All eigenvalues and corresponding eigenvectors of a complex Hermitian matrix . . . . . . . . . . . . . . . . . .

1.5 All eigenvalues of a complex Hermitian matrix ........

1.6 Some eigenvalues and corresponding eigenvectors of a complex Hermitian matrix . . . . . . . . . . . . . . . . . .

1.7 Some eigenvalues of a complex Hermitian matrix .......

1.8 All eigenvalues and corresponding eigenvectors of a real general matrix . . . . . . . . . . . . . . . . . . . . . . .

1.9 All eigenvalues of a real general matrix ..........

i. I0 All eigenvalues and selected eigenvectors of a real general matrix . . . . . . . . . . . . . . . . . . . . . . .

I.ii All eigenvalues and corresponding eigenvectors of a real symmetric matrix . . . . . . . . . . . . . . . . . . . . . .

1.12 All eigenvalues of a real symmetric matrix .........

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

1.14 Some eigenvalues of a real symmetric matrix .........

14

16

17

19

21

22

24

26

28

30

32

34

35

37

1.15 All eigenvalues and corresponding eigenvectors of a real symmetric tridiagonal matrix . . . . . . . . . . . . . . . .

1.16 All eigenvalues of a real symmetric tridiagonal matrix . . .

1.17 Some eigenvalues and corresponding eigenvectors of a real symmetric tridiagonal matrix . . . . . . . . . . . . . . . .

1.18 Some eigenvalues of a real symmetric tridiagonal matrix. . ,

1.19 All eigenvalues and corresponding eigenvectors of a special

real tridiagonal matrix . . . . . . . . . . . . . . . . . . .

1.20 All eigenvalues of a special real tridiagonal matrix ....

1o21 Some eigenvalues and corresponding eigenvectors of a special

real tridiagonal matrix . . . . . . . . . . . . . . . . . . .

1.22 Some eigenvalues of a special real tridiagonal matrix ....

2. Variations of the recommended EISPACK paths . . . . . . . . . . . .

2.1 Non-balancing of complex and real general matrices .....

2.2 Orthogonal reduction transformations to real Hessenberg

form . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.3 The implicit and explicit QL algorithms . . . . . . . . . . .

2.4 The rational QR algorithm for finding a few extreme

eigenvalues . . . . . . . . . . . . . . . . . . . . . . . . .

2.5 The use of TSTURM as an alternate to BISECT-TINVIT .....

2.6 Elementary similarity transformations for complex

general matrices . . . . . . . . . . . . . . . . . . . . . .

2.7 IMTQLV-TINVIT pairing in paths for partial eigensystems. .

2.8 Specification of boundary eigenvalue indices to the

bisection process . . . . . . . . . . . . . . . . . . . . . .

2,9 Packed representations of real symmetric and complex

Hermitian matrices . . . . . . . . . . . . . . . . . . . . .

3. Additional information and examples . . . . . . . . . . . . . . . .

3.1 Selecting the eigenvectors of real and complex general

matrices . . . . . . . . . . . . . . . . . . . . . . . . . .

3.2 Unpacking the eigenvectors of a real general matrix .....

39

41

43

46

48

50

52

55

57

59

62

65

68

71

74

76

78

80

83

84

88

VI

3.3 The EPSI parameter . . . . . . . . . . . . . . . . . . . . . 91

3.4 Relative efficiencies of computing partial and complete

eigensystems . . . . . . . . . . . . . . . . . . . . . . . . 95

3.5 Determination of the signs of the eigenvalues ........ 98

3.6 Orthogonal similarity reduction of a real matrix to

quasi-triangular form . . . . . . . . . . . . . . . . . . . . 100

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

3.8 Non-zero values of IERR . . . . . . . . . . . . . . . . . . . 111

3.9 Examples illustrating the use of the EISPACK subroutines

and the control program . . . . . . . . . . . . . . . . . . . 115

SECTION 3

VALIDATION OF EISPACK . . . . . . . . . . . . . . . . . . . . . . . . . 124

SECTION 4

EXECUTION TIMES FOR EISPACK . . . . . . . . . . . . . . . . . . . . . . 127

i. Tables of execution times . . . . . . . . . . . . . . . . . . . . . 128

2. Repeatability and reliability of the measured execution times. . . 177

3. Dependence of the execution times upon the matrix ......... 178

4. Extrapolation of timing results to other machines and compilers. 180

5. The sample matrices for the timing results . . . . . . . . . . . . 182

SECTION 5

CERTIFICATION AND AVAILABILITY OF EISPACK . . . . . . . . . . . . . . . 185

SECTION 6

DIFFERENCES BETWEEN THE EISPACK SUBROUTINES AND THE HANDBOOK ALGOL

PROCEDURES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

SECTION 7

DOCUMENTATION AFD SOURCE LISTINGS . . . . . . . . . . . . . . . . . . . 194

i. EISPACK subroutines . . . . . . . . . . . . . . . . . . . . . . . . 196

2. EISPAC control program . . . . . . . . . . . . . . . . . . . . . . 524

VII

LIST OF TABLES

7-9°

10-12.

13-15.

16-18.

19-21.

22-24.

25-27.

28-30.

31-33.

34-36.

37-39.

40-42.

43-45.

46-48.

49.

i. Sections describing the recommended basic paths in EISPACK . . . 13

2. ISUBNO values and parameter names for subroutine calls from

EISPAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

3. Summary of values of IERR . . . . . . . . . . . . . . . . . . . . 112

4-6. Execution times on the IBM 370/195 at Argonne National

Laboratory . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Execution times on the IBM 360/75 at University of Illinois. . . 133

Execution times on the IBM 370/168 at University of Michigan . . 136

Execution times on the IBM 370/165 at The University of Toronto. 139

Execution times on the Burroughs 6700 at University of

California, San Diego . . . . . . . . . . . . . . . . . . . . . . 142

Execution times on the CDC 6600 at Kirtland Air Force Base . . . 145

Execution times on the CDC 6600 at NASA Langley Research Center. 148

Execution times on the CDC 7600 at National Center for

Atmospheric Research . . . . . . . . . . . . . . . . . . . . . . 151

Execution times on the CDC 6400 at Northwestern University . . 154

Execution times on the CDC 6400/6500 at Purdue University. . . 157

Execution times on the CDC 6600/6400 at The University of Texas. 160

Execution times on the Honeywell 6070 at Bell Laboratories . 163

Execution times on the Univac 1110 at The University of

Wisconsin . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Execution times on the DEC PDP-10 at Yale University ...... 169

Execution times on the Amdahl 470V/6 at University of Michigan . 172

Execution times for the EISPACK driver subroutines over various

computer systems . . . . . . . . . . . . . . . . . . . . . . . . 175

50. Execution times for the EISPAC control program on the

IBM 370/195 at Argonne National Laboratory . . . . . . . . . . . 176

REFERENCES

i°

2.

3.

4.

5.

6.

7.

Wilkinson, J. H. and Reinsch, C., Handbook for Automatic Computation,

Volume II, Linear Algebra, Part 2, Springer-Verlag, New York,

Heidelberg, Berlin, 1971.

Wilkinson, J. _~., The Algebraic Eigenvalue Problem, Clarendon Press,

Oxford, 1965.

Boyle, J. M., Cody, W. J., Cowell, W. R., Garbow, B. S., Ikebe, Y.,

Moler, C. B°, and Smith, B. T., NATS, A Collaborative Effort to Cer-

tify and Disseminate Mathematical Software, Proceedings 1972 National

ACM Conference, Volume II, Association for Computing Machinery,

New York, 1972, pp. 630-635.

Smith, B. T., The NATS Project, A National Activity to Test Software,

SHARE SSD 228, October, 1972, item C-5732, pp. 35-42.

Smith, B. T., Boyle, J. M., Cody, W. J., The NATS Approach to Quality

Software, Software for Numerical Mathematics, D. J. Evans, ed., Academic

Press, London, New York, 1974, pp. 393-405.

Boyle, J. M. and Grau, A. A., Modular Design of a User-Oriented

Control Program for EISPACK, Technical Memorandum No. 242, Applied

Mathematics Division, Argonne National Laboratory, 1973.

Garbow, B. S., E!SPACK - A Package of Matrix Eigensystem Routines,

Computer Physics Co~nunications, North-Holland, Amsterdam, Vol. 7,

1974, pp. 179-184.

1.0-i

Section i

INTRODUCTION

The package of Fortran IV programs given the acronym EISPACK is a

systematized collection of subroutines which compute the eigenvalues

and/or eigenveetors of six classes of matrices; namely, complex general,

complex Hermitian, real general, real symmetric, real symmetric tridiagonal,

and special real tridiagonal matrices. The subroutines are based mainly

upon Algol procedures published in the Handbook series of Springer-Verlag

by Wilkinson and Reinsch [i], 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 in-

clude IBM 360-370, CDC 6000-7000, Univac iii0, Honeywell 6070, DEC PDP-10,

and Burroughs 6700.

This manual is a user guide to EISPACK and to a control program

EISPAC available with the IBM version of the package. It contains pro-

gram 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 avail-

ability 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 sub-

routine and the document for the control program.

Section !.i

ORGANIZATION OF THE GUIDE

i.i-I

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 descrip-

tion 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 three 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 avail

able, and instructs on the selection among the 22 basic paths. The first

subsection establishes several conventions that are useful in clarifying

the discussions of the paths. It then details the 22 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 22 basic paths, focusing on those con-

ditions for which the variants are to be preferred. The last subsection

provides further information about specific details of EISPACK and the

1.1-2

control program and 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.

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 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-i

Section 1.2

ACCURACY OF THE EISPACK SUBROUTINES

The most useful statement that can be made with regard to the accuracy

of the EISPACK subroutines is that they are based on algorithms which are

numerically stable; that is~ for every computed eigenpair (%,z) asso-

ciated with a matrix A, there exists a matrix E with norm small compared

to that of A for which % and z are an exact eigenpair of A+E. This back-

ward or inverse approach in describing the accuracy of the subroutines is

necessitated by the inherent properties of the problem which, in general,

preclude the more familiar forward approach. However, for real symmetric

and complex Hermitian matrices the forward approach also applies, and in-

deed is a consequence of the backward analysis. For these matrices the

eigenvalues 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 transformations are used.

The size of E, of course, is crucial to a meaningful statement of

accuracy, and the reader is referred to the detailed error analyses of

Wilkinson and others ([1],[2]). In our many tests of EISPACK, we have

seldom observed an E with norm larger than a small multiple of the product

of the order of the matrix A, its 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 22 different basic computations,

plus several variations of them. If each of these computations (and var-

iations) 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. The

information about the paths constitutes the remainder of this section

while the subroutine documentation is collected in Section 7.

2.0-2

The path descriptions are divided into three parts. Section 2.1

describes the 22 basic paths and includes a table to facilitate reference

to them. Section 2.2 describes some of the variations of these paths and

suggests when such variations might be useful. Section 2.3 contains cer-

tain additional information about and examples of the use of EISPACK. To

keep the descriptions of the basic paths and their variants simple~ we

have omitted much of the detailed information (e.g., the meanings of non-

zero error indicators and the descriptions of certain parameters) and

collected it in Section 2.3. Detailed information about each subroutine

may be obtained from the documentation for the individual subroutines in

Section 7. We hope, however, that the information given in this section

will be sufficient to permit you to correctly solve most eigenproblems.

The detail of path information that you must know to solve certain

basic eigenproblems can be reduced by using an appropriate driver sub-

routine to build the desired path from other EISPACK members. Applica-

bility of the driver subroutines is limited to those problems where all

eigenvalues and eigenvectors or all eigenvalues only are desired. There

is a driver subroutine for each class of matrices handled by the package;

driver subroutine calls corresponding to twelve of the 22 basic paths are

given as part of the discussion of the paths in this section.

Substantial further reduction in the detail of path information

that you must know to solve an eigenproblem, with wider applicability,

can be achieved by use of a control program, called EISPAC, which is

available with the IBM version of the eigensystem package [6]. (It is

only practical to implement this control program on those computing sys-

tems which adequately support execution-time loading of subroutines.)

EISPAC accepts a relatively straightforward problem description stated

2.0-3

in terms of the properties of the input matrix 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 eigen-

system package, but also enhances its robustness by eliminating the

possibility of making errors in transcribing 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 to the 22 basic paths (and

most of their variations) 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-I

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 and their correspond-

ing eigenvectors, for the six classes of matrices mentioned in Section I.

The paths recommended here provide accurate solutions for their respective

eigenproblems using a minimum of storage. Under some circumstances,

variations of these paths (using different subroutines) may provide

slightly more accurate or speedier solutions; these variations are dis-

cussed in Section 2.2.

To determine the recommended path to solve your particular eigen-

problem, consult Table I at the end of this section. First, decide to

which of the six classes of matrices listed across the top of the table

your matrix belongs. In general, the computation will be more accurate

and efficient if you use any known special properties of the matrix to

place it in the most specialized applicable class. Thus a matrix which

is real symmetric is better classified so, than as real general or complex.

On the other hand, some special properties cannot be utilized; for example,

a complex matrix, even though known to be symmetric (not Hermitian), must

be classified as complex general.

Next, determine which of the problem classifications listed down the

left side of Table 1 most closely matches the subset of eigenvalues and

eigenvectors you wish to find. The table entry so determined indicates

the subsection which describes the recommended path for your problem.

(If variations of the path exist, the subsection will refer you to Sec-

tion 2.2 for them.) For example, if you have a full (not tridiagonal)

2.1-2

real symmetric matrix and you wish to find all its eigenvalues and their

corresponding eigenvectors, the table directs you to Section 2.1.11.

Each subsection to which the table refers provides just the infor-

mation you need to use the described path correctly. It begins with a

statement of the problem and an identification of the main input and

result variables. The subroutine calls and auxiliary statements consti-

tuting the path are given and are followed by the corresponding driver

subroutine call, if applicable, and the EISPAC call. Next is a descrip-

tion of additional parameters (if any) appearing in the path and a brief

summary of the disposition of the results of the computation. Dimension

information for the arrays appearing in the path and a summary of the

total amount of array storage used is then given. These are followed by

indicative timing results. (Timing considerations are discussed more

fully in Section 4.) The subsection concludes with references to appli-

cable subsections of Section 2.2.

We have employed a few conventions in these subsections to streamline

the presentation of information. One of these concerns the types of the

parameters. Except for SELECT (and TYPE in Section 2.2.4), to which type

LOGICAL applies, all parameters have their Fortran implied type: those

beginning with I, J, K, L, M, or N are type INTEGER, and the others are

what will be called working preci~on~ 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. The roles

of these parameters are not described in the subsections, since only their

type and dimension need be known to execute a path correctly. To facili-

tate recognition of these parameters, they are written in lower case~

2.1-3

employing a systematic nomenclature. Their names are composed of f or i

to indicate type (working precision or integer), s, v, or m to indicate

dimensionality (scalar, vector, or matrix), and a serial number. Thus

fv2 is used for the first working precision temporary vector to appear

in a given paths

A third convention is used to indicate how the array parameters in

a path are dimensioned. It employs two "variables" ~ and ~, which must

be replaced in array declarator statements by Fortran integer constants.

The parameters NM and MM communicate the values of these constants to

array declarator statements in the EISPACK subroutines; therefore NMmust

be set to the constant used for ~ and MM set to that used for ~. It

is of utmost importance that whenever a path is executed, N and, if used~

M, satisfy N ~r~ and M in; otherwise unpredictable errors will occur.

An example may help clarify the use of ~ and ~. Suppose you are

using the path described in Section 2.1.13. Considering only the parameters

Aj W, and Z, the dimension information is stated there as A(~,~), W(~),

and Z(nm,~). If the largest matrix for which you intend to use this

paah is of order 50, and if you do not expect to compute more than i0

eigenvalues and eigenvectors, you might use the array deelarator statement

DIMENSION A(50,50) ,W(IO) ,Z(50, i0)

together with

NM= 50

MM= i0

You would, of course~ set N to the actual order of the matrix A for each

execution of the path; it must satisfy N ~ 50. Similarly, M will be set

10

2.1-4

(by the path) to the number of eigenvalues determined; it must satisfy

M< i0.

The summary 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

nm and turn. Thus it represents the minimum array storage required to

execute the path for a given order matrix, achieved when ~ is equal to

N and ~ 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 to the second convention above) since

it allocates them for you. This does not, however, reduce the minimum

storage required, which remains as indicated in the summary.

A fourth convention relates to the calls to driver subroutines when

eigenvalues only are computed. In such a case the formal parameter(s)

corresponding to the eigenvector matrix Z or (ZR, ZI), although required,

is(are) not referenced in the subroutine; the variable name DUMMY will

appear instead at the corresponding position(s) in the calling statement.

A final convention concerns the handling of execution errors in a

path. Certain EISPACK subroutines may fail to satisfactorily perform

their step of the computation; in this case an error parameter, universally

denoted by IERR, is set to a non-zero value indicating the type of error

which occurred. 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. Appropriate action at statement 99999 might

be to print IERR and stop. Each distinct error that can occur in EISPACK

produces one of a unique set of values for IERR. The possible values of

IERR and their meanings, together with an indication of whether or not any

11

2. i-5

partial results have been correctly computed, are summarized in 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 !ERR 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

intermediate 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.

12

2.1-6

TABLE 1

SECTIONS DESCRIBING THE RECOMMENDED BASIC PATHS IN EISPACK

lass of X

Classification~

All Eigenvalues & Corresponding Eigenvectors

All Eigenvalues

All Eigenvalues & Selected Eigenvectors

Some Eigenvalues & Corresponding Eigenvectors

Some Eigenvalues

Real Complexl Complex Real Real Symmetric GeneraliHemitianGeneral Symmetric Tridiagonali

2.1.1 2.1.4 2.1.8 2.1.11

2.1.2 2.1.5

2.1.3

Special Real

Tridiagonal

2.1.6

2.1.7

2.1.9

2.1.10

2.1.12

2.1.13

2.1.14

2.1.15 2.1.19

2.1.16 2.1.20

2.1.17 2.1.21

2. I. 18 2.1.22

13

2.1-7

Section 2.1.i

ALL EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A COMPLEX GENERAL MATRIX

To determine all the eigenvalues (WR,WI) and their corresponding

eigenvectors (ZR,ZI) of a complex general matrix (AR,AI) of order N, the

recommended E!SPACK path is:

CALL CBAL(NM,N,AR,AI,isl,is2,fvl)

CALL CORTH(N~M,N,isl,is2,AR,AI,fv2,fv3)

CALL COMQR2(NM,N,isl,is2,fv2,fv3,AR,AI,WR,WI,ZR,ZI,IERR)

IF (IERR .NE. 0) GO TO 99999

CALL CBABK2(NM,N,is!,is2,fvI,N,ZR,ZI)

or, using driver subroutine CG:

CALL CG(NM,N,AR,AI,WR,WI, I,ZR,ZI,fV2 ,fv2,fv3 ,IERR)


or, using EISPAC:

CALL EISPAC(NM,N,MATRIX('COMPLEX',AR,AI),VALUES(WR,WI),VECTOR(ZR, ZI))

This path destroys AR and AI.

Suitable dimensions for the arrays are: AR(nm,~m), Al(~,nm), WR(nm),

Wl(r~n), ZR(~,ryn), Zi(r~m,r~m), fv1(r~), fv2(~n), and fv3(r~).

The array storage required to execute this path is 4N 2 + 5N working

precision words.

Indicative execution times for this path (run on an IBM 370/195) are

.038, .24, 1.7, and 13 seconds for sample matrices of order I0, 20, 40, and

80 respectively.

14

2.1-8

Variants of this path omit the balancing of the input matrix or sub

stitute elementary for unitary transformations; see Sections 2.2.1 and

2.2.6.

15

2.1-9

Section 2ol.2

ALL EIGENVALUES OF A COMPLEX GENERAL MATRIX

To determine all the eigenvalues (WR, WI) of a complex general matrix

(AR,A!) of order N, the recommended EISPACK path is:


CALL CORTH(I~i,N,isl,is2,AR,AI,fv2,fv3)

CALL COMQR(NM, N,isl,is2,AR,AI,WR,WI,IERR)


or~ using driver subroutine CG:

CALL CG(NM,N,AR,AI,WR,WI,O,DUMMY,DUMMY,fvl,fv2,fv3,1ERR)


or, using EiSPAC:

CALL EISPAC(NM, N,MATR!X('COMPLEX',AR,AI),VALUES(WR,WI))

This path destroys AR and AI.

Suitable dimensions for the arrays are: AR(z~n,nm), Al(nm,~), WR(nm),

Wl(nm), fv1(r~), fv2(nm), and fv3(nm).


precision words~ (2N working precision words could be saved by using

WR and WI for fv2 and fv3; another N working precision words could be

saved by identifying ~1 and fv2.)


.022, .12, °78, and 5.7 seconds for sample matrices of order I0, 20, 40, and

80 respectively.

Variants of this path omit the balancing of the input matrix or sub-

stitute elementary for unitary transformations; see Sections 2.2.1 and 2.2.6.

16

2. i-i0

Section 2.1.3

ALL EIGENVALUES AND SELECTED EIGENVECTORS OF A COMPLEX GENERAL MATRIX

To determine all the eigenvalues (WR,WI) and certain eigenveetors

(ZR, ZI) (those corresponding to eigenvalues flagged by .TRUE. elements

in the LOGICAL array SELECT) of a complex general matrix (AR,AI) of

order N, the reco~ended EISPACK path is:


CALL CORTH(NM, N,isl,is2,AR,AI,fv2,fv3)

DO i00 1 = i, N

DO 50 J = I, N

fm/(I,J) = AR(I,J)

~m2(l,J) = AI(I,J)

50 CONTINUE

i00 CONTINUE

CALL COMQR(NM,N,isl,i82,~l,fm2,WR,WI,IERR)


CALL CINVIT(NM, N,~m,AI,WR,WI,SELECT,MM, M, ZR, ZI,IERR,fml,fm2,fv4,fv5)


CALL CORTB(NM, isl,is2,AR,AI,fv2,fv3,M, ZR, ZI)

CALL CBABK2(NM,N,isl,is2,fvl,M,ZR,ZI)

or, using EISPAC:

CALL EISPAC(NM,N,MATRIX('COMPLEX',AR,AI),VALUES(WR,WI),

VECTOR(ZR,ZI,MM,M, SELECT))

See Section 2.3.1 for a discussion of the SELECT array. Upon comple

tion of the path, M is set to the number of columns of ZR and ZI used,

17

2.1-11

and provided MM is sufficiently large, the computed eigenvectors corres-

ponding to the flagged eigenvalues are stored in the first M columns of

ZR and ZI. If MM is not sufficiently large, then IERR is set non-zero,

M is set to MM, and only the first M selected vectors are computed

provided that the interrupted path is completed. (IERR is also set non-

zero if a vector fails to converge.) This path destroys AR and AI.

Suitable dimensions for the arrays are: AR(~,~), AI(~,~),

WR(nm), Wl(nJn), ZR(nm,mm), Zl(nm,mm), SELECT(nm), fml(nm,nm), fm2(nm,nm),

fvl(nm), fv2(nm), fv3(n~m), fv4(nm), and ~5(nm).

The array storage required to execute this path is 4N 2 + N(2M+7)

working precision words and N logical words.

Indicative execution times for this path (run on an IBM 370/195),

when computing all N eigenvectors, are .040, .22, 1.3, and 9.7 seconds for

sample matrices 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.


stitute elementary for unitary transformations; see Sections 2.2.1 and

2.2.6.

18

2.1-12

Section 2.1.4

ALL EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A COMPLEX HERMITIAN MATRIX

To determine all the eigenvalues W and their corresponding eigenvectors

(ZR,ZI) of a complex Hermitian matrix (AR,AI) of order N, the recommended

EISPACK path is:

CALL HTRIDI (NM,N,AR,AI ,W,fv2 ,fv l ,fml)

DO i00 1 = I, N

DO 50 J = i, N

ZR(I,J) = 0.0

50 CONTINUE

ZR(I,I) = 1.0

i00 CONTINUE

CALL TQL2(NM,N,W,fv2,ZR,IERR)

IF (IERR .NE. O) GO TO 99999

CALL HTRIBK(NM,N,AR,AI,fm2,N,ZR,ZI)

or, using driver subroutine CH:

CALL CH(NM,N,AR,AI,W,I,ZR,ZI,fv2,fvJ,fmI,IERR)


or, using EISPAC:

CALL EISPAC(NM,N,MATRIX('COMPLEX',AR,AI,'HERMITIAN'),VALUES(~),VECTOR(ZR,ZI))

This path returns the eigenvalues in ascending order and a set of complex

orthonormal eigenvectors; it preserves the full upper triangle of All and

the strict upper triangle of AI.

19

2.1-13

Suitable dimensions for the arrays are: AR(r~n,~), Al(~,r~n), W(~),

ZR(n~n,nm), ZI (nm,nm), fvl (nm), and fml(2,nm).

The array storage required to execute this path is 4N 2 . 4N working

precision words.


.011, .065, °44, and 3.2 seconds for sample matrices of order i0, 20, 40,

and 80 respectively.

Variants of this path substitute the implicit for the explicit QL

shift or proceed from a packed form representation of the input matrix;

see Sections 2.2.3 and 2.2.9.

20

2.1-14

Section 2.1.5

ALL EIGENVALUES OF A COMPLEX HERMITIAN MATRIX

To determine all the eigenvalues W of a complex Hermitian matrix (AR,AI)

of order N, the recommended EISPACK path is:

CALL HTRIDI(NM, N,AR,AI,W,fvl,fv2,fm2)

CALL TQLRAT(N,W,fv2,1ERR)


or, using driver subroutine CH:

CALL CH(NM,N,AR,AI,W,O,DUMMY,DUMMY,fvl,fv2,fmT,IERR)


or, using EISPAC:

CALL EISPAC(NM,N,MATRIX('COMPLEX',AR,AI,'HERMITIAN'),VALUES(W))

This path returns the eigenvalues in ascending order; it preserves the

full upper triangle of AR and the strict upper triangle of AI.

Suitable dimensions for the arrays are: AR(n~n,nm), AI(mm,nm), W(nm),

fvl(nm), fv2(nm), and fml(2,nm).


precision words.


.005, .022, .14, and 1.0 seconds for sample matrices of order I0, 20, 40,


Variants of this path substitute the explicit or implicit for the

rational QL shift or proceed from a packed form representation of the

input matrix; see Sections 2.2.3 and 2.2.9.

2~

2.1-15

Section 2.1.6

SOME EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A COMPLEX HERMiTIAN MATRIX

To determine the eigenvalues W in an interval extending from RLB to

RUB, together with their corresponding eigenvectors (ZR,ZI), of a complex

Hermitian matrix (AR,AI) of order N, the recommended EISPACK path is:

CALL HTRIDI (NM,N ,AR,AI ~7 ,fv2 ,fv 3 ,fml )

EPSI = 0~0

CALL BISECT (N, EPS 1 ,fvi ,fv2 ,fv3 ,RLB ,RUB ,MM,M ,w,ivl, IERR,fv4 ,fvS)

IF (IERR ~NE. 0) GO TO 99999

CALL TINVIT(NM,N,fvl,fv2,fv3,M,W,ivl ,ZR,!ERR,fv4,fv5,fv6,fv7,fvS)


CALL HTRIBK(NM,N,AR,AI ,fml ,M,ZR, ZI)

or, using EISPAC:

CALL EISPAC(I~M,N,MATRIX('COMPLEX',AR,AI,'HERMITIANI),

VALUES(W,MM,M,RLB,RUB),VECTOR(ZR,ZI))

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 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 number of eigenvalues determined to lie in the interval defined by

RLB and RUB and, provided M !MM, the eigenvalues are in ascending order

in W and their corresponding complex orthonormal eigenvectors are in the

first M columns of ZR and ZI. Note that, should the computed M be greater

than MM, BISECT sets iERR non-zero and does not compute any eigenvalues.

22

2.1-16

This path preserves the full upper triangle of AR and the strict upper tri-

angle of AI.

Suitable dimensions for the arrays are: AR(~,~), AI(~,r~n), W(~),

ZR(~w,~), ZI(~,~), fv1(r~), fv2Ozw), fv3(nm), fv4(r~w), fv5(~), fv6(r~n),

fv?(~), fv8(~), fml(2,~), and ivl(~).

The array storage required to execute this path is 2N 2 + I0N + M(2N+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, .I0, .52, and 3.2

seconds for sample matrices 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.

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, combine

the determination of the eigenvalues and eigenveetors of the symmetric

tridiagonal form into a single subroutine, or proceed from a packed form

representation of the input matrix; see Sections 2.2.4, 2.2.7, 2.2.8, 2.2.5,

and 2.2.9.

23

2.1-17

Section 2.1.7

SOME EiGENVALUES OF A COMPLEX HERMITIAN ~TRIX

To determine the eigenvalues W in an interval extending from RLB to RUB

of a complex Hermitian matrix (AR,AI) of order N, the recommended EISPACK

path is:

CALL HTRIDl(mi,N,AR,Al,~1,fv2,fv3,fm2)

EPSI = 0.0

CALL BISECT(N,EPSI,fv2,fv2,fv3,RLB,RUB,MM,M,W,iv2,1ERR,fv4,fv5)

IF (IERi oNE. 0) GO TO 99999

or, using EISPAC:

CALL EISPAC (NM~N ,MATRIX( ~ COMPLEX I ,AR,AI , ' HEP~MITIAN ' ) ,VALUES (W,~I,M,_R~B ,RUB) )


computation. Setting it to zero or calling EISPAC without supplying it

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

nmtion 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 ~MM, 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 the full upper

triangle of AR and the strict upper triangle of AI.

Suitable dimensions for the arrays are: AR(nm,nm), Al(nm,~), W(mm),

fv1(nm), fv2(nm), fv3(nm), fv4(nm), fv5(nm), fm1(2,nm), and ivl(mm).

The array storage required to execute this path is 2N 2 + 7N + M working

precision words and M integer words.

24

2.1-18


computing all N eigenvalues, are .019, .072, .32, and 1.7 seconds for sample

matrices 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.

Variants of this path substitute the rational QR method for the bi-

section process, allow the specification of boundary eigenvalue indices

instead of an interval to the bisection process, or proceed from a packed

form representation of the input matrix; see Sections 2.2.4, 2.2.8, and 2.2.9.

25

2.1-19

Section 2~1.8

ALL EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A REAL GENERAL MATRIX

To determine all the eigenvalues (WR,WI) and their corresponding eigen-

vectors Z of a real general matrix A of order N, the recommended EISPACK

path is:

CALL BALANC (NM,N ,A,isl ,is2,fvl)

CALL ELMHES (NM,N ,is I ,is 2 ,A,ivl )

CALL ELTRAN(NM,N,isl,is2,A,ivl ,Z)

CALL HQR2 (NM,N ,is I ,is2 ,A,WR,WI, Z, IERR)


CALL BALBAK(NM,N,isl ,is2 ,fvl ,N,Z)

or, using driver subroutine RG:

CALL RG(NM,N,A,WR,WI,I,Z,ivl,fvI,IERR)

IF (IERR oNE. 0) GO TO 99999

or, using EISPAC:

CALL EISPAC(NM,N,MATRIX('REAL',A),VALUES(WR,WI),VECTOR(Z))

Pairs of complex eigenvalues are stored in consecutive elements of (WR,WI)

with that member of the pair with positive imaginary part first. The corres-

ponding 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 eigenveetor packing into Z. This

path destroys A.

Suitable dimensions for the arrays are: A(~n,~), WR(~), WI(~),

Z (~,~) , fvl (~), and ivl (nm).

26

2.1-20

The array storage required to execute this path is 2N 2 + 3N working pre

cision words and N integer words.


.019, .I0, .66, and 4.6 seconds for sample matrices of order I0, 20, 40,



stitute orthogonal for elementary reduction transformations; see Sections

2.2.1 and 2.2.2.

27

2.1-21

Section 2.1.9

ALL EIGENVALUES OF A REAL GENERAL MATRIX

To determine all the eigenvalues (WR,WI) of a real general matrix A of

order N, the recommended EISPACK path is:

CALL BALANC (NM,N ,A,isl ,is2 ,fvl )

CALL ELMHES (NM,N,isl ,is2,A,ivl)

CALL HQR(NM,N,isl ,is2 ,A,WR,WI ,IERR)


or, using driver subroutine RG:

CALL RG(NM,N,A,WR,WI,O,DUMMY,iVl,fu2,!ERR)


or, using EISPAC:

CALL EISPAC (NM,N ,MATRIX ( ' REAL ' ,A) ,VALUES (WR,WI))

Complex eigenvalue pairs are stored in consecutive elements of (WR,WI)

with that member of the pair with positive imaginary part first. This path

destroys A.

Suitable dimensions for the arrays are: A(r~n,r~n), WR(~), WI(~),

fvl (~), and iv1(~) °

The array storage required to execute this path is N 2 + 3N working pre-

cision words and N integer words. (N working precision words could be saved

by using WR or WI for fvl.)


.012, .056, o31, and 1.9 seconds for sample matrices of order I0, 20, 40,


28

2.1-22



2.2.1 and 2.2.2.

29

2.1-23

Section 2.1.10

ALL EIGENVALUES AND SELECTED EIGENVECTORS OF A REAL GENERAL MATRIX

To determine all the eigenvalues (WR,WI) and certain eigenvectors Z

(those corresponding to eigenvalues flagged by .TRUE. elements in the LOGICAL

array SELECT) of a real general matrix A of order N, the recommended EISPACK

path is:

CALL BALANC(NM,N,A,is2,is2,fvl)

CALL ELMHES(NM,N,is2,is2,A,iv2)

DO i00 1 = I, N

DO 50 J = I, N

fml(l,J) = A(I,J)

50 CONTINUE

I00 CONTINUE

CALL HQR(NM,N,isl,is2,fm2,WR,WI,IERR)

IF (IERR ,NE. 0) GO TO 99999

CALL INVIT(NM,N,A,WR,WI,SELECT,MM,M,Z,IERR,fmi,fv2,fv3)


CALL ELMBAK(NM,isl,i82,A,iVI,M,Z)

CALL BALBAK(NM,N,isi,is2,fvl,M,Z)

or, using EISPAC:

CALL EISPAC(NM,N,MATRIX('REAL',A),VALUES(WR,WI),VECTOR(Z,MM,M,SELECT))

Complex eigenvalue pairs are stored in consecutive elements of (WR,WI)

with that member of the pair with positive imaginary part first. See Section

2.3.1 for a discussion of the SELECT array. Note in particular that if both

elements of SELECT corresponding to a pair of complex (conjugate) eigenvalues

30

2.1-24

are set to .TRUE., the second element will be reset to .FALSE.

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

used, and provided MM is sufficiently large, the computed eigenvectors cor-

responding to the flagged eigenvalues are stored in the first M columns of

Z. Note that the real and imaginary parts, respectively, of an eigenvector

corresponding to a complex eigenvalue occupy two consecutive columns of Z.

If MM is not sufficiently large, then IERR is set non-zero, M is set to MM

or MM-I, and only the selected vectors that can be stored in M columns of

Z are computed provided that the interrupted path is completed. (IERR is

also set non-zero if a vector fails to converge.) See Section 2.3.2 for a

discussion of the eigenvector packing into Z. This path destroys A.

Suitable dimensions for the arrays are: A(nm,nm), WR(nm), Wl(nm),

Z (~,mm), SELECT (nm), fro1 (nm,~), fvl (~), fv2 (nm), fv3 (r~m), and iv1 (nm).

The array storage required to execute this path is 2N 2 + N(M+5) work-

ing precision words, N logical words, and N integer words.


computing all possible (M=N) eigenvectors, are .019, .093, .53, and 3.5

seconds for sample matrices 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.



2.2oi and 2.2.2.

31

2.1-25

Section 2.1.11

ALL EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A REAL SYMMETRIC MATRIX

To determine all the eigenvalues W and their corresponding eigenvectors

Z of a full real symmetric matrix A of order N, the recommended EISPACK path

is:

CALL TRED2(NM,N,A,W,fV2 ,Z)

CALL TQL2 (NM,N ,W,fV2 ,Z, IERR)

IF (iERR .NE. O) GO TO 99999

or, using driver subroutine RS:

CALL RS(NM,N,A~W,I,Z,fvi,fv2,1ERR)

IF (IERR oNE. O) GO TO 99999

or, using EISPAC:

CALL EISPAC(NM,N,Y~TRIX('REAL',A,'SYMMETRIC'),VALUES(W),VECTOR(Z))

This path returns the eigenvalues in ascending order and a set of ortho-

normal eigenvectors; it leaves A unaltered.

Suitable dimensions for the arrays are: A(nm,nm), W(r~), Z(~,nm),

a n d fvi (nm)~


precision words. However, for this particular path the eigenvectors can

overwrite the input matrix if the same array parameter is used for both A

and Z, thereby reducing the storage required to N 2 + 2N working precision

words.


~007, ~036, .22, and 1.5 seconds for sample matrices of order i0, 20, 40,


32

2.1-26

A variant of this path substitutes the implicit for the explicit QL

shift; see Section 2.2.3.

33

2.1-27

Section 2.1.12

ALL EIGENVALUES OF A REAL SYMMETRIC MATRIX

To determine ali the eigenvalues W of a full real symmetric matrix A

of order N~ the recommended EISPACK path is:

CALL TREDI(NM,N,A,W,fvl,fv2)

CALL TQLRAT(N,W,~,IERR)

IF (IERR 0NE. 0) GO TO 99999

or, using driver subroutine RS:

CALL RS(NM, N,A,W,O,DUMMY,fv2,fv2,1ERR)


or, using EISPAC:

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

This path returns the eigenvalues in ascending order; it preserves the

full upper triangle of A~

Suitable dimensions for the arrays are: A(~,n~), W(~), fvi(nm),

and fv2 (rim).

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

precision words~


.003, .011, ~055, and .33 seconds for sample matrices of order i0, 20, 40,


Variants of this path substitute the explicit or implicit for the

rational QL shift or proceed from a packed form representation of the

input matrix; see Sections 2.2.3 and 2.2.9.

34

2.1-28

Section 2.1.13

SOME EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A REAL SYMMETRIC MATRIX


RUB, together with their corresponding eigenvectors Z, of a full real

symmetric matrix A of order N, the recommended EISPACK path is:

CALL TREDI (NM,N,A,fN2 ,fv2 ,fv3)

EPSI = 0.0

CALL BISECT(N,EPSI,fvl,fv2,fv3,RLB,RUB,MM,M,W,iv2,1ERR,fv4,fv5)


CALL TINVIT (NM,N ,fv2 ,fv2 ,fv3 ,M,W ,iv2, Z, IERR ,fv4 ,fv5 ,fv6 ,fvf ,fvS)


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

or, using EISPAC:

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



causes the use of a default value suitable for most matrices. 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

number of eigenvalues determined to lie in the interval defined by RLB and

RUB and, provided M !MM, the eigenvalues are in ascending order in W and

their corresponding orthonormal eigenvectors 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 preserves the

full upper triangle of A.

35

2.1-29

Suitable dimensions for the arrays are: A(nm,nm), W(m~n), Z(nm,m3n),

fvl(n~n), fv2(nm), fv3(nm), fv4(nm), fv5(nm), ~6(nm), fvF(~n), fv8(nm),

and ivl(~n).

The array storage required to execute this path is N 2 + 8N + M(N+I)



computing all N eigenvalues and eigenvectors, are .020, .075, .33, and 1.6

seconds for sample matrices 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.



eigenvalue indices instead of an interval to the bisection process, combine

the determination of the eigenvalues and eigenvectors of the tridiagonal

form into a single subroutine, or proceed from a packed form representation

of the input matrix; see Sections 2.2.4, 2.2.7, 2.2.8, 2.2.5, and 2.2.9.

36

2.1-30

Section 2.1.14

SOME EIGENVALUES OF A REAL SYMMETRIC MATRIX


RUB of a full real symmetric matrix A of order N, the recommended EISPACK

path is:

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

EPSI = 0.0

CALL BISECT (N,EPS 1 ,fv l ,fv2 ,fv3 ,RLB ,RUB ,MM,M,W ,iVl ,IERR,fv4 ,fv5)


or, using EISPAC:

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



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

information 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 !MM, 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

the full upper triangle of A.

Suitable dimensions for the arrays are: A(nm,rm0, W(mm), fvl (rim),

fv2(nm), fv3(nm), fv4(nm), fv5(nm), and ivl(mm).

The array storage required to execute this path is N 2 + 5N + M


37

2.1-31


when computing all N eigenvalues, are .017, .061, .24, and 1.0 seconds for

sample matrices 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 4o


section process, allow the specification of boundary eigenvalue indices

instead of an interval to the bisection process~ or proceed from a packed

form representation of the input matrix; see Sections 2.2.4~ 2.2.8, and 2.2.9.

38

2.1-32

Section 2.1.15

ALL EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A REAL SYMMETRIC TRIDIAGONAL MATRIX

A real symmetric tridiagonal matrix of order N can be presented to

EISPACK as a two-column array (or as two N-component vectors), the sub-

diagonal elements in the last N-I positions of the first column and the

diagonal elements in the second column. The first element in the first

column is arbitrary.

To determine all the eigenvalues W and their corresponding eigen-

vectors Z of a real symmetric tridiagonal matrix A of order N, the

recommended EISPACK path is:

DO i00 1 = i, N

DO 50 J = i, N

Z(l,J) = 0.0

50 CONTINUE

Z(I,I) = 1.0

W(1) = A(I,2)

fv2(i) = A(I,I)

I00 CONTINUE

CALL IMTQL2 (NM,N ,W,fv 2, Z, IERR)


or, using driver subroutine RST:

CALL RST(NM,N,W,fu2, I,Z,IERR)


39

2 .1 -33

or, using EISPAC:

CALL EISPAC (NM,N ,MATRIX ( v REAL v ,A, T SY~iETRIC ' , ' TR!D!AGONAL ' ) ,

VALUES(W),VECTOR(Z))

This path returns the eigenvalues in ascending order and a set of

orthonormal eigenvectors. Copying A into W and fvl preserves A of

course which would otherwise be destroyed. EISPAC, however, preserves

only the second column (diagonal elements) of A.

Suitable dimensions for the arrays are: A(nm,2), W(nm), Z(nm,nm),

and fvl (rim)°


precision words. (2N working precision words could be saved by trans-

mitting the columns of A itself in place of fvl and W. Similarly, A(I,2)

could be transmitted to EISPAC in place of W.)


.005, .026, o15, and .97 seconds for sample matrices of order I0, 20, 40,


A variant of this path substitutes the explicit for the implicit QL


40

2.1-34

Section 2.1.16

ALL EIGENVALUES OF A REAL SYMMETRIC TRIDIAGONAL MATRIX






To determine all the eigenvalues W of a real symmetric tridiagonal

matrix A of order N, the recommended EISPACK path is:

DO i00 1 = i, N

W(1) = A(I,2)

fv1(~) = A(I,I)

i00 CONTINUE

CALL IMTQLI(N,W,fv2,1ERR)


or, using driver subroutine RST:

CALL RST(NM,N,W,fV2,0,DUMMY,IERR)


or, using EISPAC:

CALL EISPAC(NM,N,MATRIX('REAL',A,'SYMMETR!C','TRIDIAGONAL'),VALUES(W))

This path returns the eigenvalues in ascending order. Copying A into

W and fvl preserves A of course which would otherwise be destroyed. EISPAC,

however, preserves only the second column (diagonal elements) of A.

Suitable dimensions for the arrays are: A(nm,2), W(nm), and fv1(nm).

41

2.1-35

The array storage required to execute this path is 4N working preci-

sion words° (2N working precision words could be saved by transmitting

the columns of A itself in place of fvl and W, Similarly, A(I,2) could

be transmitted to EISPAC in place of W.)


.003, .011, .042, and .16 seconds for sample matrices of order i0, 20, 40,


Variants of this path substitute the explicit or its rational refor-

mulation for the implicit QL shift; see Section 2.2.3.

42

2.1-36

Section 2.1.17

SOME EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A REAL SYMMETRIC TRIDIAGONAL MATRIX







RUB, together with their corresponding eigenvectors Z, of a real symmetric

tridiagonal matrix A of order N, the recommended EISPACK path is:

DO i00 1 = I, N

f~1(1) = A(I,2)

IF (I .EQ. i) GO TO i00

fv~(i) = k(I,1)

fv3(1) = A(I,I)**2

i00 CONTINUE

EPSI = 0.0

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

IF (IEILR .NE. 0) GO TO 99999

CALL TINVIT (NM,N ,fv 2 ,fv2 ,fv3 ,M,W,ivl ,Z ,IERR,fv4 ,fv5 ,fv6 ,fv7 ,fvS)


or, using EISPAC:

CALL EISPAC(NM,N,MATRIX('REAL',A,'SYMMETRIC','TRIDIAGONAL'),

VALUES(W,MM,M,RLB,RUB),VECTOR(Z))

43

2.1-37

The parameter EPSi is used to control the accuracy of the eigenvalue





to the number of eigenvalues determined to lie in the interval defined

by RLB and RUB and, provided M ! ~i, the eigenvalues are in ascending

order in W and their corresponding orthonormal eigenvectors 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 leaves A unaltered.

Suitable dimensions for the arrays are: A(nm,2), W(mm), Z(nm,~wn),

fvl(nm), fv2(nm), fv3(nm), fv4(n~), fv5(nm), fv6(nm), fvT(nm), fvS(nrn),

and ivi (~)o

The array storage required to execute this path is I0N + M(N+I)

working precision words and M integer words. (2N working precision words

could be saved by transmitting the columns of A itself in place of fvN

and fv2, still preserving A.)


computing all N eigenvalues and eigenvectors, are .017, .059, .22, and

.84 seconds for sample matrices of order I0, 20, 40, and 80 respectively.





eigenvalue indices instead of an interval to the bisection process, or

44

2.1-38

cosine the determination of the eigenvalues and eigenvectors of the

matrix into a single s~routine; see Sections 2.2.4, 2.2.7, 2.2.8, and

2.2.5.

45

2.1-39

Section 2.1o18

SOME EIGENVALb~S OF A REAL SYMMETRIC TRIDIAGONAL .MATRIX




diagonal elements in the second column~ The first element in the first



RUB of a real symmetric tridiagonal matrix A of order N, the recommended

EISPACK path is:

DO i00 1 = i, N

fvl(1) = A(I,2)

IF (I .EQ. I) GO TO I00

fv~(1) = A(~,I)

fv3(I) = A(I,I)**2

i00 CONTINUE

EPSI = 0.0

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


or, using EISPAC:

CALL EISPAC (NM,N,MATRIX( 'REAL v ,A, 'SYMMETRIC' , 'TRIDIAGONAL' ) ,

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




46

2.1-40




by RLB and RUB and, provided M~MM, the eigenvalues are in ascending

order in W. Note that, should the computed M be greater than MMj BISECT

sets IERRnon-zero and does not compute any eigenvalues. This path

leaves A unaltered.

Suitable dimensions for the arrays are: A(~n,2), W(mm), fv2(nm),

fv2(n~), fv3(n~m), fv4(nm), fv5(r~), and ivl (~).

The array storage required to execute this path is 7N + M working

precision words and M integer words. (2N working preciaion words could

be saved by transmitting the columns of A itself in place of fv2 and fvl,

still preserving A.)


when computing all N eigenvalues, are .016, .055, .20, and .76 seconds

for sample matrices of order I0, 20, 40, and 80 respectively. Extrapola-

tion of these execution times for cases where M is less than N is dis-

cussed in Section 4.


section 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.

47

2.1-41

Section 2.1o19

ALL EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A SPECIAL REAL TRIDIAGONAL MATRIX

A real tridiagona! matrix of order N which, although not symmetric,

has the property that products of pairs of corresponding off-diagonal

elements are all non-negative~ and zero only when both factors are zero,

can be presented to EISPACK as a three-column array. The subdiagonal

elements are stored in the last N-I positions of the first column, the

diagonal elements in the second column, and the superdiagonal elements in

the first N-I positions of the third column. The first element in the

first column and the last element in the third column are arbitrary.

To determine all the eigenvalues W and their corresponding eigen-

vectors Z of such a real tridiagonal matrix A of order N, the recommended

EISPACK path is:

CALL FIGI2(NM,N,A,W,fVi,Z,IERR)


CALL IMTQLe(NM,N,W,fvI,Z,IERR)


or, using driver subroutine RT:

CALL RT(NM,N,A,W,I,Z,~i,IERR)

IF (IERR .h~. 0) GO TO 99999

or, using EISPAC:

CALL EiSPAC(NM,N,MATRIX('REAL',A,'TRIDIAGONAL'),VALUES(W),VECTOR(Z))

This path returns the eigenvalues in ascending order and a set of (non-

orthonorma!) eigenvectors; it leaves A unaltered. Note that a non-zero

48

2.1-42

value of IERR from FIGI2 is indicative of an input matrix which lacks the

required property.

Suitable dimensions for the arrays are: A(nm,3), W(nm), Z(nm,nm),

and fvl (rim).


precision words.


.006, .027, .15, and .97 seconds for sample matrices of order I0, 20, 40,


A variant of this path substitutes the explicit for the implicit QL


49

2.1-43

Section 2.1.20

ALL EIGENVALUES OF A SPECIAL REAL TRiDIAGONAL MATRIX

A real tridiagonal matrix of order N which, although not symmetric,


elements are all non-negative, can be presented to EISPACK as a three-

column array. The subdiagonal elements are stored in the last N-I

positions of the first column, the diagonal elements in the second column,

and the superdiagonal elements in the first N-I positions of the third

column. The first element in the first column and the last element in

the third column are arbitrary.

To determine all the eigenvalues W of such a real tridiagonal matrix

A of order N, the recommended EISPACK path is:

CALL FiGI(NM,N,A,W,fv2,fv2,1ERR)


CALL IP~QLI (N,W,fv2 ,IERR)

IF (IERR oNE. O) GO TO 99999

or, using driver subroutine RT:

CALL RT(~I,N,A,W,0,DU~Y,fv2,1ERR)


or, using EISPAC:

CALL El SPAC (NM, N, MATRIX (' REAL ' ,A ,' TRID IAGONAL ' ) ,VALUE S (W))

This path returns the eigenvalues in ascending order; it leaves A

unaltered. Note that a non-zero value of IERR from FiGI is indicative

of an input matrix which lacks the required property.

50

2.1-44

Suitable dimensions for the arrays are: A(rtm,3), W(nm), and fvl(nm).

The array storage required to execute this path is 5N working pre-

cision words.


.003, .012, .044, and .16 seconds for sample matrices of order i0, 20, 40,


Variants of this path substitute the explicit or its rational refor-

mulation for the implicit QL shift; see Section 2.2.3.

51

2.1-45

Section 2.1.21

SOME EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A SPECIAL REAL TRiDIAGONAL MATRIX



elements are all non-negative, and zero only when both factors are zero,

can be presented to EISPACK as a three-column array. The subdiagonal

elements are stored in the last N-I positions of the first column, the

diagonal elements in the second column, and the superdiagonal elements

in the first N-! positions of the third column. The first element in

the first column and the last element in the third column are arbitrary.


RUB 9 together with their corresponding eigenvectors Z, of such a real

tridiagonal matrix A of order N, the recommended EISPACK path is:

CALL FIGI(NM,N,A,fvl,fv2,fv3,1ERR)


EPSI = 0.0

CALL BISECT(N,EPSI,ful,f~2,fv3,RLB,RUB,MM,M,W,iVI,IERR,fv4,fv5)

IF (iERR ~NE. O) GO TO 99999

CALL TINVIT(NM,N,fv2,fu2,fv3,M,w,iv2,Z,IERR,fu4,fv5,fv6,fv?,fvS)


CALL BAKVEC(hrM,N,A,fv2,M,Z,IERR)

IF (lEER ~NE. 0) GO TO 99999

or, using EISPAC:

CALL EISPAC(NM,N,MATRIX('REAL~,A,'TRIDIAGONALT),

VALUES(W,MM,M,RLB,RUB),VECTOR(Z))

52

2.1-46







by RLB and RUB and, provided M ! ~, the eigenvalues are in ascending

order in W and their corresponding (non-orthonormal) eigenvectors 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 leaves A unaltered. Note that a non-zero value of IERR from

either FIGI or BAKVEC is indicative of an input matrix which lacks the

required property.

Suitable dimensions for the arrays are: A(nm,3), W(n~n), Z(nm,mm),

fv1(nm), fv2(nm), fv3(n~), fv4(nm), fv5(nm), fv6(nm), fvT(nm), fv8(nm),

and ivl(~).

The array storage required to execute this path is IIN + M(N+I)



when computing all N eigenvalues and eigenvectors, are .018, .060, .22, and

.84 seconds for sample matrices of order i0, 20, 40, and 80 respectively.



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

53

2.1-47

of the s~-mmetrized matrix into a single subroutine; see Sections 2.2.4,

2.2.7, 2.2.8, and 2.2.5.

54

2.1-48

Section 2.1.22

SOME EIGENVALUES OF A SPECIAL REAL TRIDIAGONAL MATRIX



elements are all non-negative, can be presented to EISPACK as a three-

column array. The subdiagonal elements are stored in the last N-I

positions of the first column, the diagonal elements in the second

column, and the superdiagonal elements in the first N-I positions of

the third column. The first element in the first column and the last

element in the third column are arbitrary.

To determine the eigenvalues W in an interval extending from RLB

to RUB of such a real tridiagonal matrix A of order N, the recommended

EISPACK path is:

CALL FIGI(NM,N,A,fvl,fv2,fv3,1ERR)


EPSI = 0.0

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


or, using EISPAC:

CALl EISPAC(NM,N,MATRIX('REAL',A,'TRIDIAGONAL'),VALUES(W,MM,M,RLB,RUB))




information 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

55

2.1-49

number of eigenva!ues determined to lie in the interval defined by RLB

and RUB and, provided M ~MM, the eigenvalues are in ascending order

in W. Note that, should the computed M be greater than ~, BISECT sets

IERRnon-zero and does not compute any eigenvalues. This path leaves A

unaltered. Note that a non-zero value of IERR from FIGI is indicative

of an input matrix which lacks the required property.

Suitable dimensions for the arrays are: A(nm,3), W(~v~), fv2(nm),

fv2(~), fv3(nm), fv4(nm), fv5(nm), and ivl(mm).

The array storage required to execute this path is 8N + M working

precision words and M integer words.


when computing all N eigenvalues, are .016, .055, .20, and °76 seconds for

sample matrices 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.


section 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.

58

2.2-I

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 recommended paths; they provide

some additional or alternate capability. The variant paths are related

to considerations of: whether or not complex and real general matrices

should be balanced; the use of orthogonal similarities in place of

elementary similarities for reducing a real general matrix to upper

Hessenberg form; choosing between the implicit and explicit versions of

the QL algorithm for finding all eigenvalues and eigenvectors, or all

eigenvalues only, of matrices which can be reduced to real symmetric tri-

diagonal form; the use of the rational QR algorithm for finding a few

extreme eigenvalues of matrices which can be reduced to real symmetric

tridiagonal form; the use of the single subroutine TSTURM to find some

eigenvalues and their corresponding eigenvectors of matrices which can be

reduced to real symmetric tridiagonal form; the use of elementary simi-

larities in place of unitary similarities for a complex general matrix;

possible economies realizable with a variant of the implicit QL algorithm

when partial eigensystems are determined; specification of boundary

eigenvalue indices to the bisection process instead of an interval; and

availability of storage economies when algorithms that proceed from packed

representations of real symmetric and complex Hermitian matrices are used.

Each of the subsections describing these variations discusses the

advantages and disadvantages of using the variant instead of the recom-

mended paths and includes an indication of why the routines used in the

recommended paths were chosen. The descriptions of the variant paths

57

2.2-2

differ from those of the recommended paths in Section 2.1 in that the

variants are described in terms of modifications to the recommended

paths; differences in storage requirements are similarly described. In

order to illustrate the modifications, one example of the several variant

paths is also given in each subsection~

58

2.2-3

Section 2.2.1

NON-BALANCING OF COMPLEX AND REAL GENERAL MATRICES

All of the recommended paths in EISPACK for complex general and real

general matrices employ the subroutines CBAL and BALANC, respectively, to

"balance" the matrix before computing its eigensystem ([i], pp. 315-326).

This operation includes two distinct functions: Permutation of the rows

and columns of the matrix to display any isolated eigenvalues, and equili-

bration of the remaining portion of the matrix.

The first part of the operation attempts to permute the rows and

columns of the matrix in such a way as to render portions of the matrix

triangular (column-wise at the top or row-wise at the bottom) so that

some eigenvalues are isolated on the diagonal. Any eigenvalues so iso-

lated are available without further computation and the order of the

remaining eigenproblem is reduced.

The equilibration process is then applied to the part of the matrix

(rows and columns is1 through is2) remaining after any isolated eigen-

values have been displayed. It consists of exact diagonal similarity

transformations chosen to make the sums of the magnitudes of the elements

in corresponding rows and columns more nearly equal. (Note that real

symmetric and complex Hermitian matrices are by nature balanced.) This

process may reduce the norm of the matrix thereby placing tighter bounds

on the rounding errors that can be made by the routines which follow.

The choice of whether to balance or not depends on several factors,

some of which are hard to assess a priori. Clearly balancing costs some

time. However, it is an N 2 process and becomes less significant as N

increases; in no case have we observed it to constitute more than 7% of

the time for an entire path (see Section 4.3). It may also happen that

59

2.2-4

the eigenvalues computed for an already nearly-equilibrated matrix are

slightly more accurate if balancing is omitted; however, balancing can

never increase the error bounds predicted by the backward error analysis.

Moreover, balancing obtains isolated eigenvalues exactly whatever be

their condition numbers, and their isolation reduces the effective order

of the matrix passed to the N 3 algorithms which follow. Beyond this,

the equilibration process can make dramatic improvements in the accuracy

of the computed eigenvalues for certain matrices. It is for these reasons

that balancing is used in the recommended paths.

To use the paths of Sections 2.1.1-2.1.3 and 2.1.8-2.1.10 without

balancing the matrix, the calls to CBAL or BALANC should be replaced by

the two statements

is1 = I

is2 = N

Also, calls to B~BAK or CBABK2, which transform the eigenvectors of the

balanced matrix into eigenvectors of the original matrix, should be re-

moved altogether~ To use the control program EISPAC without balancing,

the keyword parameter METHOD with alphanumeric subparameters vNO~,

'BALANCE' should be inserted into the calls to EISPAC given in these

sections.

For example (of. Section 2.1.1), to determine all of the eigenvalues

(WR,WI) and their corresponding eigenvectors (ZR,ZI) of a complex general

matrix (AR,AI) of order N without balancing, the EISPACK path is:

60

2 . 2 - 5

isl = 1

is2 = N

CALL CORTH(NM,N,isl,is2,AR,AI,fv2,fv3)

CALL COMQR2(NM,N,isl,is2,fv2,fv3,AR,AI,WR,WI,ZR,ZI,IERR)


or, using EISPAC:

CALL EISPAC(NI4,N,MATRIX('COMPLEX',AR,AI),VALUES(WR,WI),

VECTOR(ZR,ZI),METHOD('NO','BALANCE'))

The storage requirements for each of the paths without balancing is

reduced from that of the corresponding path with balancing by N working

precision words (array parameter fv2). The reduction in computation time

from not balancing has never exceeded 7% of the total path time in our

experiments. On the other hand, a substantial increase in total path

time from not balancing could occur in cases where balancing would iso-

late some eigenvalues, since isolation of values reduces the effective

order of the eigensystem to be solved.

61

2.2-6

Section 2.2.2

ORTHOGONAL REDUCTION TRANSFORMATIONS TO REAL HESSENBERG FORM

EISPACK contains two sets of subroutines which transform a real

general matrix to upper Hessenberg form~ accumulate the transformations,

and backtransform the eigenvectors. These sets consist of ELMHES,

ELTRAN, and ELMBAK~ which employ elementary similarity transformations,

and 0RTHES, ORTRAN, and ORTBAK, which employ orthogonal similarity

transformations~

The use of orthogona! similarities to reduce a matrix to upper

Hessenberg form may be valuable in two respects. First, they preserve

the Frobenius norm of the matrix and the condition numbers of the eigen-

values ([i], ppo 339-358), whereas elementary similarities do not. Thus,

elementary similarities may increase the norm of the reduced matrix,

which in turn increases the bounds on the rounding errors that can be

made by the eigenvalue-finding routines HQR and HQR2; in this case, use

of orthogonal similarities will guarantee a tighter bound on the errors.

Matrices for which orthogonal similarities improve the accuracies of the

computed eigenvalues, however, occur rarely in practice.

A second application of the routines which employ orthogonal simi-

larities is their possible use with a modified version of HQR2 to compute

the orthogona! similarity transformation which reduces a real general

matrix to quasi-triangular form; this application is discussed in Section

2.3.6.

The disadvantage of the routines which implement orthogonal similar-

ities is their longer execution time. ORTHES requires more than twice as

much time as ELMHES (on the IBM 370/195), and ORTBAK takes about half

again as long as ELMBAK. ORTRAN requires about one-fourth the time of

62

2.2-7

ORTHES, while the time for ELTRAN, never large, becomes negligible with

increasing order (see Section 4). For this reason, elementary similarities

are used in the recommended paths of Sections 2.1.8-2.1.10. Note, however,

that although the orthogonal subroutines individually take more time, only

a small increase in total path time usually results and occasionally even

a decrease in total path time attributable to a decrease in the execution

time for HQR or HQR2. Experiments using orthogonal similarities have

resulted in increases as much as 20% but some decreases of 5% were also

observed.

To use orthogonal instead of elementary similarities in these paths,

replace the names ELMIIES, ELTRAN, and ELMBAK with ORTHES, ORTRAN, and

ORTBAK, respectively, wherever they appear, substituting the array

parameter fv4 for ivl. To use the control program EISPAC with orthogonal

similarities, the keyword parameter METHOD with alphanumeric subparameter

'ORTHOGONAL' should be inserted into the calls to EISPAC given in these

sections.

For example (cf. Section 2.1.8), to determine all of the eigenvalues

(WR,WI) and their corresponding eigenvectors Z of a real general matrix A

of order N using orthogonal transformations, the EISPACK path is:

CALL BALANC(NM,N,A,isl,is2,fvl)

CALL ORTHES(NM, N,isl,is2,A,fv4)

CALL ORTRAN(NM,N,isl,is2,A,fv4,Z)

CALL HQR2(NM, N,isi,is2,A,WR,WI,Z,IERR)


CALL BALBAK(NM,N,is2,is2,fv2,N,Z)

or, using EISPAC:

63

2.2-8

CALL EISPAC(NM,N,MATRIX('REAL',A),VALUES(WR,WI),VECTOR(Z),

METHOD('ORTHOGONALT))

Suitable dimensions for the arrays are as given in Sections 2.1.8-

2.1.10 with fv4(r~) replacing iv1(r~). The array storage requirements

are thus decreased by N integer words and increased by N working pre-

cision words.

64

2.2-9

Section 2.2.3

THE IMPLICIT AND EXPLICIT QL ALGORITHMS

EISPACK contains two pairs of subroutines plus one unpaired subrou-

tine which can be used to compute all eigenvalues, or all eigenvalues

and eigenvectors, of a matrix which is in real symmetric tridiagonal form.

One pair of programs, TQLI and TQL2, is based on the QL algorithm with

explicit shifts; the other pair, IMTQLI and IMTQL2, is based on essen-

tially the same algorithm, but with implicit shifts. Corresponding

members of these pairs are functionally identical and may be substituted

for one another in a path without changing either the parameter list or

the rest of the path.

The unpaired subroutine is TQLRAT, used in the recommended paths that

determine all eigenvalues only of a complex Hermitian or real symmetric

matrix. TQLRAT is a rational reformulation of TQLI; it is formally equivalent

to TQLI, employing explicit shifts, but requires many fewer arithmetic

operations and, in particular, eliminates the calculation of most of the

square roots.

Although functionally identical, the subroutines based on the implicit

and explicit algorithms do differ, however, in the way rounding errors

affect the computed results. These differences are most pronounced for

matrices whose elements vary in a regular way over several orders of mag-

nitude, and one sometimes wants to compute the small eigenvalues to high

accuracy relative to themselves, rather than relative to the norm of the

matrix. To insure that this high accuracy is achieved, the rows and

columns of such matrices should be permuted (if possible) so that the

matrix (aij) is "graded increasingly," i.e., so that laij I approximately

increases as i and j increase, as in the 7 x 7 tridiagonal matrix:

85

2.2-10

a.~ = !02(i-I), i = 1,2,~..,7 11

= = 10 2i-1, ai~i+ 1 ai+l, i i = 1,2,.o.~6

a.. = 0 otherwise. lj

When a tridiagonal matrix is presented so that it is graded increas-

ingly, the routines based on both the implicit and explicit algorithms

compute the eigenvalues with high accuracy relative to themselves. How-

ever, if the matrix is presented so that it is graded decreasingly, the

routines based on the implicit algorithm may still compute the eigenvalues

with fairly high relative accuracy, whereas the routines based on the ex-

plicit algorithm will almost certainly produce large relative errors in

the smaller eigenvalues. Examples of the performance of the algorithms

on graded matrices are given in ([i], pp. 227-248). The paired subroutines

are nearly equal in speed, since the amount of work for a single iteration

is essentially the same in both; however, for graded matrices the implicit

algorithm may require a few more iterations to obtain its greater accuracy.

Because of their more consistent performance on graded matrices, IMTQLI

and IMTQL2 are recommended for tridiagonal matrices.

What of full complex Hermitian and real symmetric matrices? It is

not clear that the algorithms which reduce such matrices to tridiagonal

form always preserve grading; furthermore, in such matrices they may

introduce errors large enough to prevent either the implicit or explicit

algorithm from finding the smaller eigenvalues with high relative accuracy.

Historically, the explicit algorithm was introduced first and was con-

siderably faster than early versions of the implicit algorithm; hence it

was favored for use in the paths for full matrices. Although further

testing may show that the implicit algorithm has superior reliability,

66

2.2-11

especially for graded full matrices, the advantage is not yet clear

enough to cause replacement of the codes based on the explicit algorithm

in the full-matrix paths.

The calling sequence for TQLI differs from that of TQLRAT only in

transmitting array parameter fvl instead of fv2. This difference

though makes it possible to conserve N working precision words in the

path by not allocating fv2. For example, to find all the eigenvalues W

of a full real symmetric matrix A of order N using TQLI (compare Section

2.1.12), the EISPACK path is:

CALL TREDI(NM,N,A,W,~I,fv2)

CALL TQLI(N,W,fV2,1ERR)


To interchange QL algorithms in the recommended paths of Sections

2.1.4-2.1.5, 2.1.11-12, 2.1.15-16, and 2.1.19-20 (after formal replace-

ment of TQLRAT by TQLI) you need only interchange the names in the call

statements. For instance, to find all the eigenvalues W of a full real

symmetric matrix A of order N using the implicit QL algorithm (compare

with above), the EISPACK path is:

CALL TREDI (NM, N,A,W,fvI ,fvl )

CALL IMTQLI(N,W,fVI,!ERR)


It is not possible to interchange QL algorithms when using the control

program EISPAC. Storage requirements for the implicit paths are identical

and indicative timings closely similar (see Section 4) to those for the

explicit paths.

67

2.2-12

Section 2.2.4

THE RATIONAL QR ALGORITHM FOR FINDING A FEW EXTREME EIGENVALUES

All of the recommended EISPACK paths that determine a subset of the

eigenvalues of a matrix employ subroutine BISECT, which computes those

eigenvalues of a real symmetric tridiagonal matrix which lie in an inter-

val determined by the values of the parameters RLB and RUB. EISPACK

contains an alternate subroutine which can be used, with minor modifica-

tions to these paths, in place of BISECT. This subroutine, called RATQR,

computes a specified number of the smallest or largest eigenvalues. Be-

cause of this difference in the method of specifying the selected eigen-

values, BISECT and RATQR are not directly interchangeable. (See Section

2.2.8 for a discussion of another alternate subroutine to BISECT whose

capability includes that of RATQR with better stability and which is

directly interchangeable with BISECT.)

Although RATQRmight appear to be easier to use than BISECT when

some of the extreme eigenvalues are desired, the accumulation of rounding

errors with the determination of each successive eigenvalue may render

the later eigenvalues insufficiently accurate for some applications.

For instance, this accumulation of error can be particularly troublesome

if corresponding eigenvectors are to be computed by subroutine TINVIT,

for even when maximum accuracy is requested from RATQR (by setting

EPSI = 0.0, see Section 2.3.3), an eigenvalue may not be accurate enough

to satisfy TINVIT~s rather strict convergence test for the corresponding

eigenvector iteration~ This problem is especially likely to occur if too

many eigenvalues are requested from RATQR, or if some of the requested

values are tightly clustered.

68

2.2-13

To use RATQR to compute the M smallest (say) eigenvalues of a matrix

which has been reduced to symmetric tridiagonal form, calls to BISECT of

the form:

CALL BISECT(N,EPSI,fv2,fvZ,fv3,RLB,RUB,I~4,M,W,ivl,!ERR,fv4,fv5)

in the recommended paths in EISPACK should be replaced by:

TYPE = .TRUE.

IDEF = 0

CALL RATQR(N, EPS 1 ,fvl ,fu2,fu 3,M,W, ivl ,fv4, TYPE, IDEF, IERR)

Here TYPE is a LOGICAL variable which specifies whether the M smallest or

M largest eigenvalues are desired, according as it is .TRUE. or .FALSE.

IDEF can be used to specify that the matrix is known to be positive or

negative definite, according as it is +i or -I; a value of 0 is used to

indicate either that the definiteness of the matrix is not known, or that

it is not definite. Specifying the matrix to be definite will save some

computation time when IDEF is +i and TYPE is .TRUE. or when IDEF is -i

and TYPE is .FALSE.; however, if later the matrix turns out not to be

definite as specified, RATQR will terminate with IERR non-zero and with-

out computing any eigenvalues. Upon successful return from RATQR, the

computed eigenvalues are to be found in W in increasing order if TYPE is

.TRUE. and in decreasing order if TYPE is .FALSE.

To request the control program EISPAC to employ RATQR in place of

BISECT, modify the illustrated calls for the recommended paths by adding

the keyword parameter METHOD with alphanumeric subparameter 'RATQR' and

by changing the subparameters to the VALUES keyword to W, M, and 'SMALLEST ~

or 'LARGEST' as desired. To specify the definiteness of the input matrix,

69

2.2-14

insert the alphanumeric subparameter 'POSITIVE DEFINITE' or 'NEGATIVE

DEFINITE ~ in the IIATRIX keyword anywhere after A (or AI).

For exmmple, to determine the M smallest eigenvalues W of a full

real symmetric positive definite matrix A of order N, the path of Section

2.1.14 becomes:

CALL TREDI (m~,N ,A,fvl ,fv2 ,fv3)

EPSI = 0.0

TYPE = .TRUE.

IDEF = i

CALL RATQR(N,EPSI,fvl,fv2,fv3,M,W,iv2,fv4,TYPE,IDEF,IERR)


or, using EISPAC:

CALL EISPAC(NM,N,MATRIX(~REAL',A,'SYMMETRIC','POSITIVE DEFINITE'),

VALUES(W,M,'SMALLEST'),METNOD('RATQR'))

Suitable dimensions for the arrays are: A(~m,nm), W(nm), fv1(nm),

fv2(~), fv3(r~n), fv4(~), and ivl(nm). Note that storage for W and iv1

must be of length nm, even though only M eigenvalues are requested,

The array- storage required to execute this path is N 2 + 5N working

precision words and N integer words. The arrays fvl and fv3 may be

identified with W and fv4 respectively, thereby reducing the working

precision storage required to N 2 + 3N words.

70

2.2-15

Section 2.2.5

THE USE OF TSTURMAS AN ALTERNATE TO BISECT-TINVlT

Those recommended paths of Section 2.1 which at some stage compute

some eigenvalues and eigenvectors of symmetric tridiagonal matrices all

call subroutine BISECT followed by subroutine TINVIT. Alternatively,

calls to these two subroutines can be replaced by a single call of sub-

routine TSTURMwhich combines their two separate functions. TSTURM is

the translation of the corresponding Handbook algorithm ([I], pp. 418-439);

TINVIT was additionally written to extend the capability of eigenvector

determination by inverse iteration to matrices whose eigenvalues have been

computed by subroutines other than BISECT. Thus paths including RATQR

(see Section 2.2.4), I~QLV (see Section 2.2.7), and TRIDIB (see Section

2.2.8) were made available.

Substitution of TSTURM for BISECT and TINVIT in the paths has only a

negligible effect on execution time. Three possible differences in the

computed results may occur, however: The ordering of the eigenvalues (and

eigenvectors) may differ, there may be tiny differences in the eigenvector

components, and the action taken upon the occurrence of an eigenvector

convergence failure is different. The difference in ordering can occur

only if the symmetric tridiagonal matrix breaks into submatrices; TSTURM

orders the eigenvalues locally within submatrices, while BISECT orders the

eigenvalues globally for the entire matrix. Differences in the eigenvec-

tors can result only from the different order in which the eigenvectors

associated with close eigenvalues are orthogonalized in TSTURM and TINVIT;

for such differences to exist there would have to be at least three close

eigenvalues within the same submatrix. Finally, TSTURM returns immediately

upon failure of an eigenvector to converge; in contrast, TINVIT sets the

71

2.2-16

vector to zero and continues. On balance, it thus appears that there is

really no reason to choose TSTUIhM over BISECT-TINVIT, except that only

one subroutine call has to be written instead of two.

To use TSTURM to determine the eigenvalues W in an interval extend-

ing from RLB to RUB, together with their corresponding eigenvectors Z, of

any matrix of order N which can be reduced to a symmetric tridiagonal

matrix, the section of coding of the form:

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


CALL TINVIT (NM,N,fvl ,fv2 ,fv3,M,W,ivl ,Z,IERR,fv4 ,fv5,fv6 ,fvf ,fvS)


in the recommended paths in EISPACK should be replaced by:

CALL TSTURM(NM,N,EPSI,fv2 ,fv2,fv3,RLB,RUB,MM,M,W,Z,iERR,

fv4,fvS ,fv6 ,fv7 ,fv8 ,fv9)

IF (iERR .NE. 0) GO TO 99999

Thus, for example, the recommended path of Section 2.1.13 for some

eigenvalues and eigenvectors of a real symmetric matrix A of order N using

TSTURMbecomes:

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

EPSI = 0.0

CALL TSTURM(NM,N ,EPSI ,fvl ,fv2 ,fv3,RLB ,RUB ,MM,M,W,Z ,IERR,

fv4 ,fvS ,fv6 ,fv7 ,fvS ,fv9 )


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

72

2.2-17

The control program EISPAC does not utilize TSTURM.

The error parameter IERR from TSTURM combines the separate roles

of the error parameters from BISECT and TINVIT. Note that one addi-

tional working precision array fvg, dimensioned fvg(~), is required but

that the integer array ivl is not required, thus increasing the minimum

storage requirements by N working precision words while releasing M

integer words.

73

2 .2 -18

Section 2.2.6

ELEMENTARY SIMILARITY TRANSFORMATIONS FOR COMPLEX GENERAL MATRICES

EiSPACK contains two sets of subroutines which transform a complex

general matrix to upper Hessenberg form, determine all its eigenvalues

and eigenvectors or all eigenvalues only and, in the case where only

selected eigenvectors of the Hessenberg matrix have been determined,

backtransform these eigenvectors. One set consists of CORTH, COMQR,

COMQR2, and CORTB, which employ unitary similarity transformations,

and the other set consists of COMHES, COMLR, COMLR2, and COMBAK, which

employ stabilized elementary similarity transformations. In particular,

COMQR and COMQR2 implement the QR algorithm, while COMLR and COIo~R2

implement the LR algorithm.

Elementary transformations are faster than unitary transformations

(see Section 4), but their use can increase the norm of the matrix

which in turn increases the bounds on the rounding errors that can be

made in the determination of the eigenvalues and eigenvectors. This

increase of norm and rounding errors has been occasionally observed in

the LR iterative step; the tendency in these instances has been for the

more pronounced growth to occur away from the subdiagonal and diagonal

of the (Hessenberg) matrix, causing little o~ no deterioration in the

eigenvalues but sometimes substantial loss of accuracy in the eigen-

vectors. (The IERR parameter gives no warning unless an eigenva!ue

fails to converge.)

Since loss of accuracy, when it occurs, is associated with increase

of norm, subroutine CO}~R2 arranges to compute and return the norm of

the final reduced (triangular) matrix for inspection by the user. If

the norm has grown by several orders of magnitude, the user should be

wary of possible significant loss of accuracy.

74

2.2-19

To use elementary instead of unitary similarities in these paths,

replace the names CORTH, COMQR, COMQR2, and CORTB with COMHES, COMLR,

COMLR2, and COMBAK, respectively, wherever they appear, substituting the

array parameter iv2 for the pair fv2, fv3. To use the control program

EISPAC with elementary similarities, the keyword parameter METHOD with

alphanumeric subparameter 'ELEMENTARY' should be inserted into the calls

to EISPAC given in these sections.

For example (cf. Section 2.1.1), to determine all the eigenvalues

(WR,WI) and their corresponding eigenvectors (ZR,ZI) of a complex general

matrix (AR,AI) of order N using elementary transformations, the EISPACK

path is:


CALL COMHES(N~.i,N,isT,is2,AR,AI,iv2)

CALL COMLR2(NM,N,isl,is2,ivl,AR.AI,WR,WI,ZR,ZI,IERR)


CALL CBABK2(NM,N,is2,is2,fV2,N,ZR,ZI)

or, using EISPAC:

CALL EISPAC(NM,N,MATRIX('COMPLEX',AR,AI),VALUES(~,WI),

VECTOR(ZR,ZI),METHOD('ELEMENTARY'))

Suitable dimensions for the arrays are as given in Sections 2.1.1 -

2.1.3 with iv1(nm) replacing fv2(~),fv3(~). The array storage require-

ments are thus decreased by 2N working precision words and increased by

N integer words.

75

2.2-20

Section 2.2.7

IMTQLV-TINVIT PAIRING IN PATHS FOR PARTIAL EIGENSYSTEMS

Each of the recommended paths of Section 2.1 that determine some

eigenvalues and corresponding eigenvectors of a matrix that has been

reduced to real symmetric tridiagonal form include a pairing of subrou-

tines BISECT and TINVIT, BISECT to determine the eigenvalues and TINVIT

to determine the corresponding eigenvectors. But with the awareness

that the several subroutines in EISPACK based on the QL algorithm can

compute all the eigenvalues in about the time required for BISECT to

compute 25% of them, it would seem that users could improve efficiency

in certain problem situations by computing all the eigenvalues with a

faster subroutine and then specifying a subset of eigenvalues for which

the corresponding eigenvectors would then be determined with TINVIT.

This faster subroutine, however, must additionally be able to

detect and communicate possible blocking of the tridiagonal form, as

does BISECT, to enable TINVIT to determine independent and orthogonal

eigenvectors corresponding to possibly multiple eigenvalues.

It turns out that the implicit QL algorithm as implemented in sub-

routine IMTQLI was readily extendible to detect the blocking, and thus

was born subroutine IMTQLV for inclusion in paths that determine the

partial eigensystem of a matrix that has been reduced to real symmetric

tridiagonal form.

For example (cf. Section 2.1.13), to determine the three smallest

eigenvalues W, together with their corresponding eigenvectors Z, of a

full real symmetric matrix A of order N, one possible EISPACK path is:

76

2.2-21

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

CALL LMTQLV(N,fvl,fv2,fv3,W,ivl,IERR,fv4)


CALL TINVIT(NM, N,fvl,fv2,fv3,3,W,ivl,Z,IERR,fv4,fv5,fv6,fvF,fv8)


CALL TRBAKI(NM,N,A,fu2,3,Z)

The control program EISPAC does not utilize IMTQLV.

The parameter list to IMTQLV is a subset of the corresponding

parameter list to BISECT and, similarly to BISECT and in contrast to

IMTQLI, the input tridiagonal matrix is preserved. The array storage

required to execute this variant path is the same as that for the path

of Section 2.1.13.

77

2 .2 -22

Section 2.2.8

SPECIFICATION OF BOUNDARY EIGENVALUE INDICES TO THE BISECTION PROCESS

All of the recommended paths of Section 2.1 that determine a subset

of the eigenvalues of a matrix require the specification of an interval

(RLB,RUB) containing the eigenvalues of interest to subroutine BISECT.

It may sometimes be preferred to specify the eigenvaiues by their

indices in the ordered set; e.g., the three smallest eigenvalues or the

second largest eigenvalue. Substitution of subroutine TRIDIB for BISECT

enables this option~ In particular, TRIDiB includes the capability for

which subroutine RATQR was designed (cf. Section 2.2.4); although slower,

TRIDIB is numerically stable and is therefore recommended generally in

preference to RATQR.

The parameter list for TRID!B is the same as that for BISECT with

the exception of RLB, RUB, MM, and M. RLB, RUB, and M are still present

with reversed roles -- M now specifies the number of eigenvalues desired

and RLB and RUB are output parameters which define an interval containing

exactly the desired eigenvalues. MM is replaced by MII which specifies

the index of the smallest desired eigenvalue.

To request the control program EISPAC to employ TRIDIB in place of

BISECT, change the subparameters to the VALUES keyword from (W,MM,M, RLB,

RUB) to (W,MII,M).

So, for example (cf. Section 2.1.14), to determine exactly M eigen-

values W, starting from the Mll-th smallest one, of a full real symmetric

matrix A of order N, the EISPACK path is:

78

2.2-23

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

EPSI = 0.0

CALL TRIDIB(N,EPSI,fv2,fv2,fv3,RLB,RUB,MII,M,W,ivI,IERR,fv4,fv5)


or, using EISPAC:

CALL EISPAC(NM,N,MATRIX('REAL',A,'SYMMETRIC'),VALUES(W,MII,M))

Array storage requirements for paths with TRIDIB are identical to

those for the corresponding paths with BISECT; execution times are very

little different (see Section 4).

79

2.2-24

Section 2.2~9

PACKED REPRESENTATIONS OF REAL SYMMETRIC AND COMPLEX HERMITIAN MATRICES

The algorithms implemented in EISPACK for real symmetric and complex

Hermitian matrices access only the full lower triangles of the matrices;

in order to best take advantage of the storage savings realizable since

the upper triangles are not required, subroutines are included in EISPACK

that proceed from packed representations of the input matrices.

In the real symmetric case, the lower triangle of the matrix is

packed row-wise into a one-dimensional array; subroutines TRED3 and TRBAK3

replace TREDI and TRBAKI, respectively, in the corresponding explicit

paths, driver subroutine RSP replaces RS where applicable, or 'PACKED'

is specified to EISPAC. For example (cf. Section 2.1.13), to determine

some eigenvalues W and corresponding eigenvectors Z of a real symmetric

matrix A of order N in packed representation, the EISPACK path is:

CALL TRED3 (N, NV,A,fvl ,fv2 ,fv3)

EPSI = 0.0

CALL BISECT(N,EPSI,fvl ,fv2,fu3,RLB,RUB,MM,M,W,iV2 ,IERR,fu4,fv5)


CALL TINVIT(NM,N,fvl,fv2,fv3,M,W,ivl,Z,IERR,fv4,fv5,fv6,fv7,fvS)


CALL TRBAK3 (NM, N, NV,A,M, Z)

or, using EISPAC:

CALL EISPAC (NM,N,MATRiX(~ REAL ' ,A, 'SYMMETRIC', 'PACKED' ),

VALUES (W,MM,M,RLB, RUB), VECTOR(Z) )

NV communicates the dimension of A and therefore must be at least

N (N+I)/2.

80

2.2-25

The array storage required to execute this path is N2/2 + 17N/2 +

M(N+I) working precision words and M integer words. Driver subroutine

RSP can be used with real symmetric matrices in packed representation

in the corresponding paths to where RS is used with matrices in standard

representation. Its calling sequence is identical to that of RS except

for the inclusion of NV in the position after N. But for the case where

all eigenvalues and eigenvectors are determined, RS is preferred because

it affords optimal consolidation of storage when the eigenvectors over-

write the input matrix and, further, implements a more efficient algorithm

than does RSP.

In the complex Hermitian case, the lower triangle of the matrix is

packed into a single two-dimensional array, the real parts of the elements

in the full lower triangle and the imaginary parts of the elements in the

transposed positions of the strict upper triangle. Subroutines HTRID3

and HTRIB3 replace HTRIDI and HTRIBK, respectively, in the corresponding

paths or 'PACKED' is specified to EISPAC. For example (cf. Section 2.1.4),

to determine all eigenvalues and corresponding eigenvectors of a complex

Hermitian matrix in packed representation, the EISPACK path is:

CALL HTRID3 (NM,N,A,W, fv2 ,fvl ,fml )

DO i00 I = i, N

DO 50 J = I, N

ZR(I,J) = 0.0

50 CONTINUE

ZR(I,I) = 1.0

I00 CONTINUE

CALL TQL2(NM,N,W,fVI,ZR, IERR)


CALL HTRIB3(NM,N,A,fml,N,ZR,ZI)

81

2 .2-26

or, using EISPAC:

CALL EISPAC(NM,N,MATRIX('COMPLEX',A,A,'HERMITIAN','PACKED~),

VALUES(W)~VECTOR(ZR,ZI))


precision words.

There is no driver subroutine in EISPACK for use with packed

complex Hermitian matrices. Execution times for the packed real

symmetric and complex Hermitian subroutines are not markedly different

from those of their standard counterparts; see Section 4.

82

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 setting of

the LOGICAL vector SELECT used in the paths for computing selected

eigenvectors of real and complex general matrices; the packing of the

eigenvectors of real general matrices; considerations regarding the user-

supplied error tolerance in the computation of the eigenvalues of matrices

which can be reduced to real symmetric tridiagonal form; the relative

efficiencies of computing partial and complete eigensystems; two special

computations: a determination of the number of positive (or negative)

eigenvalues of matrices which can be reduced to real symmetric tridiagonal

form; and the orthogonal similarity reduction of a real matrix to quasi-

triangular form; the examination of the IERR parameter and intermediate

results when using the control program EiSPAC; and a summary of the possi-

ble 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.

83

2.3-2

Section 2.3.1

SELECTING THE EIGENVECTORS OF REAL AND COMPLEX GENERAL MATRICES

The computation of selected eigenvectors of real and complex general

matrices by the subroutines INVIT and CINVIT is controlled by the LOGICAL

array parameter SELECT and to some extent by the parameter MM. The con-

siderations involved in setting SELECT and determining ~ (MM = ~), the

column dimension of the eigenvector arrays, are discussed separately for

real and complex matrices.

For complex matrices, the elements of SELECT are in one-to-one cor-

respondence with the computed eigenvalues. They are examined in order

and the eigenvectors corresponding to the eigenvalues tagged by .TRUE.

elements in SELECT are computed. These complex eigenvectors are stored

in successive columns of the eigenvector arrays ZR and ZI; hence the number

of .TRUE. elements in SELECT must not exceed the column dimension rf~ of

the arrays ZR and ZI. The parameter MM communicates this column dimension;

should more than MM columns be required, the computation stops when the

arrays are full and IERR is set non-zeros In any event, when the eigen-

vector subroutine (CINVIT) returns to the calling program, M is set to the

number of columns actually used to store the eigenvectors.

For real matrices, setting SELECT and determining a suitable value for

ff~a priori are complicated by the convention used to pack the eigenvectors

into Z, discussed in detail in Section 2.3.2. It is assumed that conjugate

pairs of complex eigenvalues are consecutive in WR and WI. Again, the ele-

ments of SELECT are in one-to-one correspondence with the computed eigen-

values but the number of columns used in the eigenvector matrix Z may be

more than the number of .TRUE. elements of SELECT.

84

2.3-3

The elements of SELECT are examined in order and the eigenvectors

corresponding to the eigenvalues flagged by .TRUE. elements are computed,

except as restricted below. If a flagged eigenvalue is real, the corres-

ponding real eigenvector is stored in one column of Z. If the flagged

eigenvalue is complex, and its flagged conjugate does not precede it, the

real and imaginary parts of the corresponding eigenvector are stored in

two consecutive columns of Z with the real part first. If the flagged

eigenvalue is complex and its flagged conjugate precedes it, no eigenvector

is computed and the corresponding element of SELECT is reset .FALSE. This

convention guarantees that no more than N columns of Z are required to store

the eigenvectors; it is not a serious restriction since the eigenvector

corresponding to the conjugate value is the conjugate of the computed

eigenvectoro

Because of the complicated algorithm for selecting eigenvectors and

packing them into Z, the a priori determination of the column dimension

~rl of Z is difficult. If the number of .TRUE. elements in SELECT is

known, then a safe choice for ~ is the smaller of twice this number and

N. Again MM must be set to ~ and communicates the column dimension of

Z; should more than MM columns be required, the computation in INVlT stops

when no more eigenvectors can be stored and IERR is set non-zero. In any

event, when INVIT returns to the calling program, M is set to the number

of columns of Z actually used to store the eigenvectors. Note that when

MM is too small, the returned value of M can be either MM-I or MM.

The chief complication towards setting the elements of SELECT to

compute the required eigenvectors is that the eigenvalues of a real or

complex general matrix are not generally computed in a predictable order.

Hence one cannQt decide a priori which elements of SELECT should be set.

85

2.3-4

Two possibilities exist: One is to execute the eigenvalues-only path,

examine the computed eigenvalues, set SELECT as required and then (with

a further run) execute the path for all eigenvalues and some eigenvectors.

The other is to interrupt the all-eigenvalues-some-eigenvectors path after

the computation of the eigenvalues, to set SELECT at that point using a

program segment, and to resume execution of the path.

As an example of this latter possibility, suppose that for a real

general matrix you wish to compute the eigenvectors corresponding to those

eigenvalues the sum of whose real and imaginary parts is non-negative and

you know that there are no more than five such values. Then the path with

interruption becomes:

CALL BALANC(NM,N,A,isl,is2,fvl)

CALL ELMHES(NM,N,isl,is2,A,ivl)

DO 200 I = i, N

DO I00 J = I, N

ym1(I,J) = A(I,J)

i00 CONTINUE

200 CONTINUE

CALL HQR(N~,N,isi,is2,f~2,WR,WI,IERR)

IF (IERR .NEo 0) GO TO 99999

DO 300 I = I, N

SELECT(1) = (WR(1)+WI(I)) .GE. 0.0

300 CONTINUE

CALL INVIT(NM, N,A,WR,WI,SELECT,MM,M,Z,IERR,fml,fv2,fv3)


CALL ELMBAK(NM, isl,is2,A,iv2,M,Z)

CALL BALBAK(NM,N,isi,is2,fvI,M,Z)

86

2.3-5

An example illustrating the corresponding interruption of the path

when using EISPAC is given in Section 2.3.7; the unpacking of the eigen-

vectors in Z is discussed in Section 2.3.2. Note that in the above

example no attempt is made to avoid flagging both eigenvalues of a complex

conjugate pair; as discussed above, INVIT will automatically reset the

flag corresponding to the second eigenvalue in the pair. Unless it is

known that some of the five possible eigenvalues are real, Z should be

dimensioned Z(~,I0) and MM set to i0.

87

2.3-6

Section 2.3.2

UNPACKING THE EIGENVECTORS OF A REAL GENERAL MATRIX

Since for a real general matrix 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 matrix. The EISPACK routines which com-

pute the eigenvectors of real general matrices 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 eigen-

vectors represents a real eigenvector, the real part of a complex eigen-

vector, or the imaginary part of a complex eigenvector, the imaginary

part of the corresponding eigenvalue must be examined. In addition, the

flags in the SELECT array must also be taken into account if only some

eigenvectors have been computed. Perhaps the clearest way to describe

how this packing is done is to present program segments which unpack 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 eigen-

vectors of a real general matrix according to Section 2.1.8. The following

program segment unpacks the matrix Z of eigenvectors into matrices ZR and

ZI, dimensioned ZR(~,nm) and ZI(r~,nm). Note that this program segment

utilizes the property of the EISPACK programs that for real general

matrices the eigenvalues of each complex conjugate pair are ordered so

that the eigenvalue of positive imaginary part appears first in (WR,WI).

88

2.3-7

DO 150 K = i, N

IF (WI(K) .NE. 0.0) GO TO ii0

DO I00 J = i, N

ZR(J,K) = Z(J,K)

ZI(J,K) = 0.0

i00 CONTINUE

GO TO 150

ii0 IF (WI(K) .LT. 0.0) GO TO 130

DO 120 J = i, N

ZR(J,K) = Z(J,K)

ZI(J,K) = Z(J,K+I)

120 CONTINUE

GO TO 150

130 DO 140 J = I, N

ZR(J,K) = ZR(J,K-I)

ZI(J,K) = -ZI(J,K-I)

140 CONTINUE

150 CONTINUE

Note that this program segment has been designed so that Z and ZR can be

the same matrix; if they are, then the fourth and tenth statements can

be omitted.

When only some of the eigenvectors have been computed, the packed

form of storage is somewhat more complicated than when all the eigenvectors

have been computed because of its interaction with the SELECT array (see

Section 2.3.1). The following program segment illustrates one way to

unpack the eigenvectors from the M columns of Z. It places each selected

eigenvector into the columns of full square matrices ZR and ZI whose index

89

2.3-8

is that of the corresponding eigenvalue; the remaining columns are not

set.

I= i

DO 130 K = I, N

IF (.NOT. SELECT(K)) GO TO 130

IF (WI(K) oNE. 0.0) GO TO II0

DO i00 J = !, N

ZR(J,K) = Z(J,I)

ZI(J,K) = 0.0

i00 CONTINUE

I=I+l

GO TO 130

ii0 DO 120 J = I, N

ZR(J,K) = Z(J,I)

ZI(J,K) = Z(J,I+i)

120 CONTINUE

I=I+2

130 CONTINUE

Note that if both members of a pair of complex eigenvalues were flagged

by .TRUE. elements in SELECT, subroutine INVIT resets the flag corres-

ponding to the second member of the pair to .FALSE. (see Section 2.3.1);

thus additional program must be supplied to store the eigenvector corres

ponding to the second member.

90

2.3-9

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 avail-

able. 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 con-

trol of accuracy is possible with four of the subroutines in EISPACK

which are used in those paths that compute some eigenvalues (with or

without eigenvectors) of matrices which can be reduced to real symmetric

tridiagonal form. 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). Note in the

discussion below that any property described for subroutine BISECT also

applies to subroutine TRIDIB.

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:

xo - x~ ! 2 × ~mCHEe × (ix01 + Ix~I) + EPSl

This condition has the character of a relative accuracy test for eigen-

values whose magnitudes are large with respect to EPSI/>~CHEP, and that of

91

2.3-10

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 de-

fault value for each submatrix; this default value is MACHEP times the

larger (in magnitude) Gerschgorin bound for the eigenvalues of that sub-

matrix. This value prevents the above termination criterion from

requiring ~'unreasonably" high accuracy in the eigenvalues which are near

zero. (In the implementation of BISECT, EPSI is actually set negative

when the default value is requested. This serves as a flag to cause the

recomputation of the default value for each submatrix; the returned value

of EPSI is this negative default value for the final submatrix.)

A positive input value for EPSI will not be reset in BISECT. When

the positive input value of EPSI exceeds the default value, the convergence

test is less stringent for eigenvalues of smaller magnitude, and computa-

tion time tends to be reduced. If EPSI is smaller than its default value,

the convergence test becomes more stringent and computation time tends to

increase. Care should be taken, however, not to specify a smaller value

for EPSI unless the small eigenvalues are known to be insensitive to

perturbations in the input matrix; otherwise the additional precision

will be meaningless. Although computation time tends to increase with

decreasing EPSI, the exact relationship is highly dependent on the particu-

lar matrix.

The eigenvalue calculation in subroutine TSTURM is essentially the

same as in BISECT~ and EPSI has the same role. However, choice of an

input value of EPSI larger than the default value may jeopardize the eigen-

vector calculation~ as discussed below.

92

2.3-11

The role of EPSI in subroutine RATQR is different than in BISECT and

TSTURM. Here the convergence condition is simply

DELTA < EPSI

where DELTA is a byproduct of each iterative step in the computation of

the k th eigenvalue and kxEPSI is an estimate for the absolute error in

the current estimate of the eigenvalue. (The factor k in this bound

accounts for the accumulation of error in successive eigenvalues alluded

to in Section 2.2.4; see also [I], pp. 257-265.)

RATQR also chooses a default value of EPSI. It varies from iteration

to iteration and is MACHEP times the estimate of the smallest eigenvalue

of the current shifted matrix. If a positive value of EPSI is provided

as input, it will be used as long as it is larger than the default value

which represents the maximum relative accuracy reasonably attainable. An

EPSI larger than the default value may result in fewer iterations and

reduced computation time; you should choose it small enough so that you

are willing to tolerate an error of kxEPSI in the k th eigenvalue. (The

value of EPSI actually used for the final eigenvalue computed can be

found in EPSI upon return from RATQR.)

When eigenvectors are computed by the method of inverse iteration,

the success of the computation depends critically on the accuracy of the

computed eigenvalues. Thus, when this method is used in conjunction with

one of the above eigenva!ue finders, as in TSTURM or when TINVIT follows

BISECT or RATQR, use of an EPSI larger than the default value may result

in failure of the eigenvector calculation to converge. Such failure

occasionally occurs even with the default value (especially in RATQR,

when a large number of eigenvalues is requested); for BISECT and TSTURM

93

2.3-12

only, this may be avoided by choosing an input value of EPSI smaller than

its default value.

The role of EPSI may be summarized as follows. All four of the

subroutines discussed employ a convergence criterion which combines a

relative error test using MACHEP and an absolute error test using the

specified EPSI (or a default). In BISECT, TRIDIB, and TSTURM, this combi-

nation is the sum of the two tolerances, while in RATQR it is the maximum.

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 to the

VALUES parameter° Thus the VALUES parameter becomes:

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

With EISPAC, the input value of EPSI is not altered, even though the default

value may be used in the computation.

2.3-13

Section 2.3.4

RELATIVE EFFICIENCIES OF COMPUTING PARTIAL AND COMPLETE EIGENSYSTEMS

In this section, we compare the paths which compute complete eigen-

systems with those which compute partial eigensystems. Considering timing,

array storage, and accuracy requirements, the central issue is when it is

preferable to compute the complete eigensystem even when not required.

There are three cases: Eigenvalue-only paths for matrices that can be

reduced to real symmetric tridiagonal form, eigenvalue-eigenvector paths

for such matrices, and eigenvalue-eigenvector paths for general real or

complexmatrices.

For eigenvalues of matrices reduced to symmetric tridiagonal form,

the principal comparison is between subroutines BISECT and TQLRAT (or

TQLI). When the default value of EPSI is used in BISECT, TQLRAT is

faster to the point of computing all the values as fast as BISECT can

compute 25% of them. If less stringent accuracy requirements allow EPSI

to be specified larger (see Section 2.3.3), then the execution time for

BISECT decreases; at half accuracy, BISECT would be faster than TQLRAT

unless 50% or more of the eigenvalues were desired. Also, BISECT requires

the larger amount of working array storage (cf. Sections 2.1.16 and

2.1.18). Note, however, that the timing and storage d~fferences in these

individual subroutines may be small compared with the total requirements

of the path.

When eigenvectors of such matrices are also desired, then the prin-

cipal comparison is between the subroutine pair BISECT-TINVIT and TQL2.

(See Section 2.2.7 for the comparison between BISECT-TINVIT and variant

IMTQLV-TINVIT.) Here a factor in the timing is the identity of the

machine; the parallelism of the IBM 370/195 appears much better suited to

95

2.3-14

the algorithm of TQL2 than to BISECT-TINVIT. Consultation of the path

times in Section 4 is recommended towards choosing the faster path;

generally, paths with TQL2 are relatively more efficient at lower orders

than paths with BISECT-TINVIT and less efficient at higher orders. Array

storage for a partial set of eigenvectors is clearly less with TINVIT

than for the complete set of vectors with TQL2. However, it must also

be remembered that working array requirements for BISECT-TiNVIT exceed

those for TQL2 (of. Sections 2.1.15 and 2.1.17), and further, that if TQL2

follows TRED2 for a real symmetric matrix, the eigenvectors may overwrite

the input matrix (see Section 2.1.11).

The comparisons of the preceding paragraphs involving TQLRAT (or TQLI)

and TQL2 extend to IMTQLI and IMTQL2 as well, since their performances

and storage requirements are so closely similar. The execution times of

Section 4 also suggest RATQR as a viable replacement for BISECT in the

BISECT-TINVIT path. However, this is misleading in that the cited TINVIT

times are in paths with BISECT, and the corresponding timings with RATQR

could be significantly longer. This owes to the generally poorer accuracy

of the eigenvalues from RATQR, forcing extra, often futile iterations in

TINVIT.

Finally for general real and complex (Hessenberg) matrices, the prin-

cipal comparisons are between HQR-INVIT and HQR2, and between COMQR-CINVIT

and COMQR2. Here considerations are similar to the symmetric case;

inverse iteration is relatively more efficient with increasing order in

comparison to accumulation of transformations, and array storage compari-

sons depend vitally on the number of selected eigenvectors. Working array

requirements for the partial eigensystem paths are especially severe (cf.

Sections 2.1.1 and 2.1.3; also 2.1.8 and 2.1.10).

96

2.3-15

With regard to considerations of accuracy and reliability, the partial

eigensystem paths fall short of the complete eigensystem paths, but the

differences in performance are generally marginal. The weakest such path

is the variant RATQR-TINVIT for real symmetric matrices generally due to

the inaccuracies of the eigenvalues (see Section 2.2.4). Eigenvectors

from TINVITmay fail in their last few digits of being as precisely ortho-

gonal as from TQL2. Extreme sensitivity to the accuracy of the eigenvalues

ia a shortcoming of these paths, but on the other hand affords an a

posteriori check on the accuracy of the eigenvalues.

Thus, a recommendation with regard to the best path when only a

partial eigensystem is required involves a number of considerations.

Generally, we recorm~end the simpler-structured complete eigensystem paths

unless the penalty in time or storage is severe.

97

2.3-16

Section 2.3.5

DETERMINATION OF THE SIGNS OF THE EIGENVALUES

In the stability analysis of dynamic systems, one is frequently in-

terested in knowing the number of positive (or negative) eigenvalues rather

than the eigenvalues themselves. For real general and complex general

matrices the regular EISPACK paths must be used and the eigenvalues

actually computed; however, for nmtrices that can be reduced to real

symmetric tridiagonal form, time can be saved in realizing this objective

hy judicious choice of the EPSI accuracy-control parameter discussed in

Section 2.3.3.

This computation is available from the recommended paths for comput-

ing some eigenvalues of matrices which can be reduced to real symmetric

tridiagonal form as given in Sections 2.1.7, 2.1.14, 2.1.18, and 2.1.22,

when P~B~ RUB, and EPSI are set appropriately. It makes use of two prop-

erties of subroutine BISECT: (I) The first action in BISECT is to deter-

mine the number of eigenvalues in the interval from RLB to RUB and to set

M to that number, and (2) as soon as BISECT has determined intervals

containing eigenvalues which jointly satisfy the convergence criterion

discussed in Section 2.3.3, it terminates. Since EPSI appears as a term

in the right hand side of this criterion, termination will occur at least

as soon as the lengths of the intervals become less than EPSI. One need

only choose an initial value of EPSI which is as large as the length of

the interval from RLB to RUB, and BISECT will return almost immediately

with M set to the number of eigenvalues in the interval.

For examp!e~ suppose you wish to compute the number of eigenvalues

of a real symmetric matrix A of order N which lie on the non-negative real

axis and that you know that all the eigenvalues of A are less than

98

2.3-17

1.0 x 1035 . Then you might use the following path based on that of

Section 2.1.14.

RLB = 0.0

RUB = 1.0E35

EPSI = 1.0E35

CALL TRED 1 (NM,N ,A ,fvl ,fv2 ,fv3)

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

Upon completion of the path, the value of M is the number of non-negative

eigenvalues. Note that this number is accurately determined despite the

high "error" tolerance EPSI, since it is obtained from a Sturm sequence

count which does not itself involve any convergence test.

99

2.3-18

Section 2.3.6

ORTHOGONAL SIMILARITY REDUCTION OF A REAL MATRIX TO QUASI-TRIANGULAR FORM

Schur~s Lemma asserts the existence of a unitary similarity trans-

formation which reduces any matrix to triangular form. For real matrices,

it may be of interest to compute the part of this transformation which can

be carried out without resort to complex arithmetic, that is, to compute

the matrix of the orthogonal transformation which reduces a real matrix

to quasi-triangular form. Quasi-triangular form falls short of triangular

form because it retains 2 × 2 blocks on the main diagonal which correspond

to complex conjugate pairs of eigenvalues.

The orthogonal quasi-triangularization of a real matrix can frequently

-I be used in place of the usual decomposition PJP (where J is a Jordan

canonical matrix) and is faster. As an example of its application, con-

sider the following problem in control theory. Suppose an m × n matrix X

is sought which satisfies the equation

AX+XB = C

where A, B and C are real m x m, n × n and m × n matrices respectively.

If the orthogonal (upper) quasi-triangularizations of A T = uLTu T and

B = VRV T are computed, and substituted into the equation, then the simpler

equation for Y

LY + YR = E

results where L and R are respectively lower and upper quasi-triangular

matrices and

X = UYV T and E = uTcv.

100

2.3-19

The columns of Y can now be determined successively by a process of for-

ward substitution, which is only sli~ntly complicated by the presence of

the 2 x 2 blocks on the diagonals of L and R.

The quasi-triangularization is carried out on the unbalanced matrix

A using the routines for orthogonal similarity reduction discussed in

Section 2.2.2 and a modified version of subroutine HQR2. It begins with

the use of ORTHES to reduce the matrix to upper-Hessenberg form followed

by ORTRAN to accumulate the transformations. The modified version of

HQR2, say HQRORT, completes the orthogonal reduction to quasi-triangular

form and accumulates the remaining transformations. It can be obtained

by changing tile statement labeled 60 in HQR2 (see Section 7) to:

60 IF (EN .LT. LOW) GO TO i001

(The statements beginning with that labeled 340 and ending with that im-

mediately preceding the statement labeled i000 may be deleted, if desired.)

The "path" for this computation is then:

isl = 1

is2 = N

CALL ORTHES (NM,N,isl ,is2,A,fvl)

CALL ORTRAN(NM,N,isl ,is2,A,fvl ,Z)

CALL HQRORT(NM,N,isl ,is2,A,WR,WI,Z,IERR)

Upon completion of this path, the eigenvalues are in (WR,WI) and the ortho-

gonal matrix which reduces A to quasi-triangular form is in Z.

2.3-20

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;

the second provides the opportunity to examine intermediate results as

the computation proceeds, much as can be done when the EISPACK subroutines

are called explicitly.

The facility to examine the value of IERR is invoked by setting an

integer variable, 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.9 becomes

IERROR = 0

CALL EISPAC(NM,N,MATRIX('REAL',A),VALUES(WR,WI),ERROR(IERROR))

To understand the effect of supplying the ERROR keyword, consider the be-

havior of EiSPAC when it is not supplied. When one of the subroutines

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

error and terminates execution of your program. When ERROR(IEPdlOR) is

supplied, EiSPAC behaves instead as follows: If no execution errors occur,

EISPAC returns 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 the path, prints the error

message (unless suppressed by initializing IERROR to a machine dependent

value as described in Section 7.2), and then returns to your program with

IERROR equal to IERR~ Finally, if one of the routines returns a negative

value of IERR (a ~'non-fatal" error), EISPAC completes execution of the path

102

2.3-21

in order to produce some useful results, prints the error message, and

returns to your program with IERROR equal to IERR. Thus the principal

use of the IERR examination facility is to enable you to retrieve useful

partial results when a non-fatal error occurs; which results are useful

is described 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 results is provided by

a mode of operation in which EISPAC calls a user-supplied subroutine just

before execution of the path begins, and again after execution of each

subroutine and auxiliary action in it. One important application of

this facility occurs in those paths which compute selected eigenvectors

of real or complex general matrices, where the facility can be used to

examine the computed eigenvalues and to set the elements of the SELECT

array controlling which eigenvectors are computed.

To use this facility you must first create a subroutine to examine

the intermediate results. You are free to choose the name of the subrou-

tine, say USUB, but the parameter list and declaration statements must

correspond to:

SUBROUTINE USUB(ISUBNO,NrM, N,AR,AI,WR,WI,ZR,ZI,MM,M,RLB,RUB,EPSI,

X SELECT,IDEF,TYPE,IERR,LOW, IGH,BND,D,E,E2,IN~,INT,ORT,SCALE,TAU)

REAL*8 AR(NM,NM) ,AI(NM,NM) ,WR(NM) ,WI(NM) ,ZR(NM,NM) ,ZI (NM,NM) ,RLB,RUB,

X EPS i, BND(N) ,D(N) ,E(N) ,E2 (N), ORT (N) ,SCALE(N) ,TAU (2,N)

INTEGER ISUBNO,NM,N,MM,M, IDEF,IERR,LOW, iGH,IND(N),INT(N)

LOGICAL SELECT(NM),TYPE

In order to avoid Fortran errors it is important that the array parameters

be dimensioned as indicated (except that MMmay be used for the last

103

2.3-22

dimension of WR and of ZR and ZI, where appropriate), even though some

arrays might not appear relevant to a particular path.

You inform EISPAC that you wish to use the intermediate result

examination facility by inserting the keyword parameter SUBR with sub-

parameter USUB 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 ac-

tion has just been completed. It is zero when USUB is called just before

execution of the path begins. ISUBNO values in the range 100-299 signify

that the preceding action allocated or freed temporary storage, those in

the range 300-499 indicate auxiliary actions (initializing or copying

arrays, for example), and those beyond 500 correspond to calls to the

EISPACK subroutines as indicated in Table 2. Thus the value of ISUBNO

indicates where in the execution of a path USUB has been called, and can

be used to determine what action USUB is to take in examining the inter-

mediate results. Table 2 also indicates which of the parameters passed

to USUB appeared in the just-completed call to the EISPACK subroutine.

As an example of the use of this facility, suppose you wish to

interrupt the path of Section 2.1.10 and use a subroutine SETSEL to examine

the eigenvalues computed for a real general matrix and to set the SELECT

array to compute the eigenvectors corresponding to those eigenvalues with

sum of real and imaginary parts greater than or equal to zero. (This

example corresponds to that in Section 2.3.1.) Your driver program must

contain the statements

104

2.3-23

EXTERNAL SETSEL

CALL EISPAC(NM,N,MATRIX('REAL',A),VALUES(WR,WI),VECTOR(Z,MM,M, SELECT),

SUBR(SETSEL))

To determine how to write SETSEL, consult the definition of the path in

Section 2.1.10 in conjunction with Table 2. The eigenvalues are available

for examination after HQR and the logical array SELECT must be initialized

before INVIT (see Section 2.3.1), so the interruption must be made imme-

diately after the call to HQR. Table 2 indicates that this call in this

path has an associated ISUBNO of 517, and comparison of the HQR and INVIT

calls with those in Section 2.1.10 shows that the eigenvalues are in

(WR,WI) and the logical array is parameter SELECT. Hence the subroutine

might be written as follows:

SUBROUTINE SETSEL(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,ORT,SCALE~TAU)

REAL*8 AR (NM,NM) ,AI (NM,NM) ,WR(NM) ,WI (h~M), ZR(NM,MM), ZI (NM,MM) ,RLB ,RUB,

X EPS I,BND (N) ,D(N) ,E(N) ,E2 (N) ,ORT(N) ,SCALE(N) ,TAN (2,N)

INTEGER ISUBNO,NM,N,MM,M, IDEF,IERR,LOW,IGH,IND(N)~INT(N)

LOGICAL SELECT(NM),TYPE

IF (ISUBNO .NE. 517) RETURN

DO i0 1 = I, N

SELECT(l) = (WR(1)+WI(1)) .GE. 0.0DO

i0 CONTINUE

RETUPd~

END

105

2.3-24

SETSEL immediately returns after every call from EISPAC except when

ISUBNO is 517 (after HQR); then it examines the computed eigenvalues to

set SELECT. (Considerations regarding the setting of SELECT and choice

of MM are discussed in detail in Section 2.3.1.)

106

ISUBNO Value

532

509

515

539

526

504

501

507

508

502

505

506

503

565

566

564

567

563

2.3-25

TABLE 2

ISUBNO VALUES AND PARAMETER NAMES FOR SUBROUTINE CALLS FROM EISPAC

Subroutine Call*

BAKVEC (NM,N,AR,E,M, ZR,IERR)

BALANC (NM, N,AR,LOW,IGH, SCALE)

BALBAK (NM, N,LOW, IGH,SCALE,M,ZR)

BISECT (N,EPSI,AR(I,2),AR(I,I),E2,RLB,RUB,~I,M,WR, IND,

IERR,-,BND) in real symmetric tridiagonal paths

(2.1.17, 2.1.18)

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

in other paths

CBABK2 (IfM,N,LOW,IGH, SCALE,M,ZR,ZI)

CBAL (NM,N~AR,AI,LOW,IGH,SCALE)

CINVIT (NM,N,AR,AI,WR,WI,SELECT,MM,M,ZR,ZI,IERR,-,-,-,-)

COMBAK (NM, LOW, IGH,AR,AI,INT,M,ZR,ZI)

COMHES (NM,N,LOW,IGH,AR,AI,INT)

COMLR (NM,N,LOW,IGH,AR,AI,WR,WI,IERR)

in path for all values, no vectors (2.1.2), modified

COMLR (N,N,LOW,IGH,-,-,WR,WI,IERR)

in path for all values, selected vectors (2.1.3),

modified

COMLR2(NM,N,LOW,IGH,INT,AR,AI,WR,WI,ZR,ZI,IERR)

COMQR (NM,N,LOW,IGII,AR,AI,WR,WI,IERR)

in path for all values, no vectors (2.1.2)

COMQR (N,N,LOW,IGH,-,-,WR,WI,IERR)

in path for all values, selected vectors (2.1.3)

COMQR2 (NM,N,LOW,IGH,ORTR,ORTI,AR,AI,WR,WI~ZR,ZI,IERR)

CORTB (NM,LOW, IGH~AR,AI,ORTR,ORTI,M,ZR,ZI)

CORTH'(NM,N,LOW~IGH,AR,AI,ORTR,ORTI)

107

ISUBNO Value

519

510

512

530

531

529

516

517

514

523

553

521

525

560

552

554

2.3-26

TABLE 2 (Contd.)


Subroutine Call*

ELMBAK (NM,LOW, IGH,AR, INT,M,ZR)

ELMHES (NM,N,LOW,!GH,AR, INT)

ELTRAN (NM,N,LOW,IGH,AR,INT,ZR)

FIGI (NM,N,AR,WR,E,E,IERR)


F!GI (NM,N,AR,D,E,E2~IERR)

in paths for some values (2.1.21, 2.1.22)

FIGI2 (NM,N,AR,WR,E,ZR, IERR)

HQR (NM,N,LOW,IGH,AR,WR,WI,IERR)


HQR (N,N~LOW,IGH,-,WR,WI,IERR)

in path for all values, selected vectors (2.1.10)

HQR2 (NM,N,LOW,IGH,AR,WR,WI,ZR,IERR)

HTRIBK (NM~N,AR,AI,TAU,M,ZR,ZI)

HTRIB3 (NM,N,AR,TAU,M, ZR,ZI)

HTRIDI (NM,N,AR,AI,WR,E,E,TAU)

in path for all values and vectors (2.1.4)

HTRIDI (h~M,N,AR,AI,D,E,E2,TAU)


HTRIDI (NM~N,AR,AI,WR,E,E2,TAU)


HTRID3 (NM, N,AR,WR,E,E,TAU)

in path for all values and vectors (2.1.4), modified

HTRID3 (NM,N,AR,D,E,E2,TAU)

in paths for some values (2.1.6, 2.1.7), modified

108

ISUBNO Value

561

(not used)

524

538

522

537

518

520

511

513

540

527

541

528

543

(not used)

2.3-27

TABLE 2 (Contd.)


Subroutine Call*

HTRID3 (NM, N,AR jWR,E ~ E2,TAU)


IMTQLV

IMTQL 1 (N,WR,E, IERR)

in certain real tridiagonal path (2.1.20)

IMTQLI (N,WR,AR(I, I) ,IERR)

in real symmetric tridiagonal path (2. I. 16)

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

in certain real tridiagonal path (2.1.19)

l~ffQL2 (NM,N,WR,AR(I, I),ZR,IERR)

in real symmetric tridiagonal path (2. I. 15)

INVIT (NM~N,AR~WR~WI, SELECT ~MM,M 9 ZR~ IERR~ -,-,-)

ORTBAK (NM, LOW, IGH, AR, ORTR, M, ZR)

ORTHES (NM,N,LOW, IGH~AR,ORTR)

ORTRAN (NM, N, LOW, IGH,AR, ORTR, ZR)

RATQR (N,EPSI,AR(I, 2) ,AR(I, I) ,E2,M,WR, IND,BND,TYPE,IDEF,IERR)

in real symmetric tridiagonal paths (2. i. 17, 2. I. 18),

modified

RATQR (N, EPS I, D, E, E2,M,WR, IND, BND, TYPE, IDEF, IERR)

in other paths

TINVlT (NM,N,AR(I,2),AR(I,I),E2,M, WR,IND,ZR, IERR, , , , ,BND)

in real symmetric tridiagonal path (2.1.17)

TINVIT (NM,N~D~E~E2,MjWR~IND~ZR~IERR, , , , ~BND)

in other paths

TQLRAT (N,WR, E2, IERR)

TQLI

109

ISUBNO Value

542

536

557

534

535

533

555

556

562

559

558

(not used)

2.3-28

TABLE 2 (Contd.)

!SUBNO VALUES AND PARAMETER NAMES FOR SUBROUTINE CALLS FROM EISPAC

Subroutine Call*

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

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

TRBAK3 (NM,N,NV,AR,M, ZR)

TREDI (NM, N,AR,WR,E,E2)


TREDI (NM,N,AR, D,E,E2)


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

TRED3 (N,NV,AR,WR,E,E)

in path for all values and vectors (2.1.11), modified

TRED3 (N,NV,AR,D,E,E2)

in paths for some values (2.1.13, 2.1.14), modified

TRED3 (N,NV,AR,WR,E,E2)


TRIDIB (N,EPSI,AR(I,2),AR(I,I),E2,RLB,RUB,MII,M,WR, IND,IERR,BND,-)

in real symmetric tridiagonal paths (2.1.17, 2.1.18), modified

TRIDIB (N,EPSI,D,E,E2,RLB,RUB,MII,M,WR, IND,IERR, BND,-)

in other paths

TSTURM

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

1t0

2.3-29

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 into two categories:

first, path-terminating errors, indicated by positive values of IERR and

signifying that although some possibly useful results have been obtained~

continued execution of the path is meaningless; second, non-terminating

errors, indicated by negative values of IERR and signifying that although

errors have already occurred, some further meaningful results may be ob-

tained if the remaining part of the path is executed. Each distinct error

that can occur in EISPACK corresponds 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 in Table 3 at the end of

this section. To determine the significance 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. More detailed information may be obtained from the documentation

for the particular subroutine in Section 7.

111

2.3- 30

TABLE 3

SUM21~RY OF VALUES OF IERR

IERR

i, INi~N

N+i, 2AiSN

2N+i, 2~iAN

3N+I

SUBROUTINES

CG,CH,COMLR~ COMLR2,COMQR, COMQR2,HQR, HQR2,1MTQLV, IMTQLI,IMTQL2, RG,RS,RSP,RST, RT,TQLRAT, TQLI,TQL2

FIGI,FIGI2

BAKVEC, FIGI2

BISECT, TRIDIB, TSTURM

EISPAC MESSAGE

00

Ol

02

03

SIGNIFICANCE OF THE ERROR

th The calculation of the i eigenvalue failed to converge. If CG, COMLR, COMLR2, COMQR, COMQR2, HQR, HQR2, or RG was being used, the eigenvalues i+l,i+2,...,N should be correct; otherwise, the eigenvalues 1,2,...,i-i should be correct. In neither case are any eigenvectors correct.

For a real non-symmetric tridiagonal matrix (aij), the

product of ai,i_ 1 and ai_l, i

is negative, violating the restriction for special tridiagonal matrices discussed in Sections 2.1.19-2.1.22. No useful results are produced.

For a real non-symmetric tridiagonal matrix (aij) , one but

not both of ai,i_ 1 and ai_l, i

are zero. If FIGI2 was being used, no useful results are produced. If BAKVEC was being used, the eigenvalues computed earlier are correct, but the eigenvectors are not correct.

If BISECT or TSTURMwas being used, the parameter MM specified insufficient storage to hold all the eigenvalues in the interval (RLB,RUB). The only useful result is M, which is set to the number of eigenvalues in this interval. If TRIDIB was being used, it is not possible to compute exactly M eigenvalues (starting from the Mll-th) because of exact multiplicity at index MII. No useful results are produced.

I12

2.3-31

IERR

3N+2

4N+i, l~i~N

5N+i, l~i_<M

6N+I

-i, l~i~N

-N-i, l~i-<N

TABLE 3 (Contd.)

SUMMARY OF VALUES OF IERR

SUBROUTINES

TRIDIB

EISPAC MESSAGE SIGNIFICANCE OF THE ERROR

TSTURM

RATQR

RATQR

CINVIT, INVIT, TINVIT

C INV IT, INVIT

04

05

06

50

50,52

It is not possible to compute exactly M eigenvalues (starting from the Mll-th) because of exact multiplicity at index MII+M-I. No useful results are produced.

The calculation of the i th eigenvector failed to converge. The eigenvalues 1,2,...,i-i and corresponding eigenvectors should be correct.

The calculation of one or more of the eigenvalues including the i th value failed to converge. All eigenvalues probably have some accuracy, but no stronger statement can be made.

The input matrix was specified as positive or negative definite (IDEF=±I) but the subroutine does not find it so; the subroutine should be re-entered specifying IDEF=0. No useful results are produced.

The calculation of one or more of the eigenvectors including the i th vector failed to converge; these vectors are set to zero. These failures may be caused by insufficient accuracy of the corresponding eigenvalues. All non-zero eigenvectors and their corresponding eigenvalues should be correct.

Both the error above (non- convergence) and the error below (insufficient storage) occurred with their respective results.

113

2.3-32

IERR SUBROUTINES

-2N-I CINVIT, INVIT

-3N-i, 2~i~N FIGI

TABLE 3 (Contd.)

SUMMARY OF VALUES OF IERR

EISPAC MESSAGE SIGNIFICANCE OF THE ERROR

52 The parameter MM specified insufficient columns to hold the selected eigenvectors. All eigenvalues and the first M columns of (ZR, ZI) or of Z should be correct.

For a real non-symmetric tridiagonal matrix (aij), one but not both of

ai,i_ 1 and ai_l, i are zero. This

does not jeopardize the calculation of the eigenva!ues but invalidates any eigenvectors computed in this path. The error~ therefore~ acts here as a warning but becomes a path-terminating error in BAKVEC if it is subsequently called. (No error message is triggered here from EISPAC, but error message no. 02 will finally result if the VECTOR parameter has been supplied.)

I14

2 .3-33

Section 2.3.9

EXAMPLES ILLUSTRATING THE USE OF THE EISPACK SUBROUTINES AND THE CONTROL PROGRAM

We illustrate the use of Section 2 in preparing two programs to solve

the same eigenproblems, one program calling the EISPACK subroutines directly

and the other using the control program EISPAC. The problems are to find the

eigenvalues in the interval (0,3) and the corresponding eigenvectors of two

real symmetric matrices of orders 3 and 4, chosen to exhibit, respectively,

normal and abnormal path termination. The purpose of choosing these problems

is to illustrate the use of this publication in following a somewhat compli-

cated path; in practice, for such low order matrices, it is probably easier to

use the paths that compute the complete eigensystem.

The two sample programs are complete in that they contain input and out-

put statements; the data for each case and the computed results accompany the

program listing. For both programs, it is assumed that the EISPACK subroutines

are available in compiled form and that appropriate control cards are provided.

Note that the EISPAC sample program also assumes that the compiled form of

EISPAC is available, and may require additional control statements that point

to EISPAC and the EISPACK subroutines.

The EISPACK sample program is written in standard single precision

Fortran IV, while the EISPAC sample program is written in IBM's long precision

Fortran IV. Both programs use Fortran logical unit 5 for input and Fortran

logical unit 6 for output.

For these sample programs, we assume more generally that the order of

the input matrix will not exceed 20 and that the number of eigenvalues in the

interval (0,3) will not exceed 3. Thus the integer constants ~ and ~ dis-

cussed in Section 2.1 have the values 20 and 3 respectively.

115

2.3-34

Given the above eigenproblems, we are directed by Table 1 to Section

2.1.13. There, the appropriate calls to the EISPACK subroutines and to

EISPAC are displayed. Dimensions for the array variables in the sample pro-

grams depend upon ~ and mm and hence from the above discussion, the

declaration statements must be

workir~precision A(20,20),W(3),Z(20,3)

working precision FVI(20),FV2(20),FV3(20),FV4(20),FV5(20),FV6(20),

FV7(20),FVS(20)

INTEGER IV1(3)

To communicate these dimensions to the EISPACK subroutines and to EISPAC, the

parameters NM and MM are set to 20 and 3 respectively. Finally, variables

RLB and RUB are set to 0.0 and 3.0 respectively, specifying the interval to

be searched for the eigenvalues°

The matrices are read row-wise from unit 5 and printed row-wise on unit

6. The first sample matrix has one eigenvalue in the interval (0,3), which

with its corresponding eigenvector are printed on unit 6. The second sample

matrix has more than three eigenvalues in (0,3) and the path is terminated

after BISECT with IERR set to 13 = 3N+I. For this matrix, the EISPACK sample

program distinguishes this error at statement 99999 from other possible

errors~ prints the appropriate message on unit 6 and continues execution

(until a matrix of order zero is specified on unit 5). The EISPAC sample

program also distinguishes this error value from other possible error values,

prints a message numbered 03 on unit 6 and terminates execution. (See

Section 2.3.7 for use of the ERROR keyword parameter to continue execution.)

116

2.3-35

LISTING OF THE EISPACK SAMPLE PROGRAM

C C C

C

C

SAMPLE PROGRAM ILLUSTRATING THE USE OF THE EISPACK SUBROUTINES.

THIS PROGRAM READS A REAL SYN~METRIC MATRIX A FROM FORTRAN LOGICAL UNIT 5 AND COMPUTES EIGENVALUES W IN THE INTERVAL (0,3) AND THE ASSOCIATED ORTHONORMAL EIGENVECTORS SEE SECTION 2.1.13.

Z.

REAL SYMMETRIC MATRIX Aj NO LARGER THAN ORDER 20. REAL EIGENVALUES W, AT MOST 3 OF THEM. ORTHONORMAL EIGENVECTORS Z, AT MOST 3 OF THEM.

REAL A(20,20),W(3),Z(20,3) REAL RLB, RUB, EPS1

TEMPORARY STORAGE ARRAYS.

REAL FVI(20),FV2(20),FV3(20),FV4(20),FV5(20),FV6(20), + FV7(20),FV8(20) INTEGER IV1(3)

ROW AND COLUMN DIMENSION PARAMETERS ASSIGNED.

NM = 20 MM= 3

READ IN THE REAL SYMMETRIC MATRIX OF ORDER N ROW-WISE.

10 READ(5,20) N 20 FORMAT(I4)

IF (N .LE. 0) STOP

DO 40 I = i, N READ(5, 30) (A(I,J),J=I,N)

30 FORMAT(4Ei6.8) 40 CONTINUE

WRITE(6,50) N 50 FORMAT(///23H ORDER OF THE MATRIX IS, 14//16H MATRIX ELEMENTS)

DO 70 I = I, N WRITE(6,60) (A(I,J),J=I,N)

60 FORMAT(1X, 1P4E16.8) 70 CONTINUE

INITIALIZE THE INTERVAL (RLB, RUB).

RLB = 0.0 RUB = 3.0

117

2.3-36

LISTING OF THE EISPACK SAMPLE PROGRAM (Contd.)

90

THE FOLLOWING PATH IS COPIED FROM SECTION 2.1.13.

CALL TREDI(NM, N,A, FV1, FV2, FV3) EPSI : 0.0 CALL BISECT(N, EPSIp FVI, FV2, FV3, RLB, RUB, MM, M, W, IVl, IERR, FV4, FV5) IF (IERR .NE. 0) GO TO 99999 CALL TINVIT(NM, N~ FV1, FV2, FV3,M, W, IV1, Z, IERR, FV4, FV5, FV6, FV7, FVS) IF (IERR .ME. 0) GO TO 99999 CALL TRBAK I(NM, N, A, FV2, M, Z)

PRINT THE M EIGENVALUES AND CORRESPONDING EIGENVECTORS.

IF (M .EQ. 0) GO TO 88888 WRITE(6,90) M FORMAT(/47H NUMBER OF EIGENVALUES IN THE INTERVAL (0,3) IS,14)

DO ii0 I = i, M WRITE(6,100) W(I ) , (Z(J , I ) ,J=I ,N)

100 FORNAT(/11H EIGENVALUE/1X, 1PE16.8//14H CORRESPONDING, + 12H EIGENVECTOR/(1X, 3E16.8))

110 CONTINUE

C C C 88888 88100

C C C 99999

GO TO 10

THERE ARE NO EIGENVALUES IN (0,3).

WRITE(6,88100) FORMAT(43HONO EIGENVALUES OF A IN THE INTERVAL (0,3).) GO TO i0

HANDLING OF IERR PARAMETER

IF (IERR .GT. 0) GO TO 99200 IERR = -IERR WRITE(6,99100) IERR

99100 FORMAT(52HOAT LEAST ONE EIGENVECTOR FAILED TO CONVERGE, NAMELY, 15) GO TO 10

C 99200 WRITE(6,99300) M 99300 FORMAT(/35H NOT ENOUGH SPACE ALLOCATED FOR THE, 14,

+ 35H EIGENVALUES IN THE INTERVAL (0,3).) GO TO 10 END

1t8

2.3-37

LISTING OF THE EISPAC SAMPLE PROGRAM

SAMPLE PROGRAM ILLUSTRATING THE USE OF THE CONTROL PROGRAM EISPAC.

THIS PROGRAM READS A REAL SYMMETRIC MATRIX A FROM FORTRAN LOGICAL UNIT 5 AND COMPUTES EIGENVALUES W IN THE INTERVAL (0,3) AND THE ASSOCIATED ORTHONORMAL EIGENVECTORS SEE SECTION 2.1.13.

Z.

REAL SYMMETRIC MATRIX A, NO LARGER THAN ORDER 20. REAL EIGENVALUES W, AT MOST 3 OF THEM. ORTHONORMAL EIGENVECTORS Z, AT MOST 3 OF THEM.

REAL*8 A(20,20),W(3),Z(20,3) REAL*8 RLB, RUB~EPS1

ROW AND COLUMN DIMENSION PARAMETERS ASSIGNED.

NM=20 MM=3

READ IN THE REAL SYMMETRIC MATRIX OF ORDER N ROW-WISE.

10 REJ~D(5,20) N 20 FORMAT(I4)

IF (N .LE. 0) STOP

DO 40 I = 1, N READ(5,30) (A(I,J),J=I,N)

30 FORMAT(4D16.8) 40 CONTINUE

WRITE(6,50) N 50 FORMAT(///23H ORDER OF THE MATRIX IS,14//16H MATRIX ELEMENTS)

DO 70 1 = 1, N WRITE(6,60) (A(I,J),J=I,N)

60 FORMAT(1X, 1P4D16.8) 70 CONTINUE

INITIALIZE THE INTERVAL (RLB,RUB).

RLB = 0.0D0 RUB = 3.0D0

THE FOLLOWING CALL IS COPIED FROM SECTION 2.1.13.

CALL E I SPAC(NM, N, MATRI X( ' REAL ' ,A, ' SYMMETRIC ' ), + VALUES(W,MM, M, RLB, RUB),VECTOR(Z))

119

2.3-38

LISTING OF THE EISPAC SAMPLE PROGRAM (Contd.)

C C PRINT THE M EIGENVALUES AND CORRESPONDING EIGENVECTORS. C C ARE THERE ANY EIGENVALUES IN (0,3)? C

IF (M oNE. 0) GO TO 90 C C NO. C

WRITE(6,80) 80 FORMAT(43HONO EIGENVALUES OF A IN THE INTERVAL (0,3).)

GO TO 10 C C YES. C

90 WRITE(6pI00) M 100 FORMAT(/47H NUMBER OF EIGENVALUES IN THE INTERVAL (0,3) IS,14)

C DO 120 I=1, M

WRITE(6,110) W(1) , (Z (J , I ) , J= I ,N) 110 FORMAT(/11H EIGENVALUE/1X, 1PD16.8//14H CORRESPONDING,

+ 12H EIGENVECTOR/(1X,3D16.8)) 120 CONTINUE

C GO TO i0 END

120

2 ,3-39

DATA FOR THE SAMPLE PROGRAMS READ FROM UNIT 5

3 -i.0 1.0 -i.0 1.0 1.0 -i.0

-I.0 -i.0 1.0 4

1.875 -0.5 0.375 -0.5 2.25 -0.25 0.375 -0.25 2.125

-0.25 -0.375 -0.125 0

-0.25 -0. 375 -0.125 2. 125

121

OUTPUT FROM THE EISPACK SAMPLE PROGRAM PRINTED ON UNIT 6

ORDER OF THE MATRIX IS

3

MATRIX ELEMENTS

-1.00000000E 00

1.00000000E 00 -I.00000000E 00

1.00000000E 00

1.00000000E 00 -I.00000000E 00

-1.00000000E 00 -1.00000Q00E 00

1.00000000E 00

NUMBER OF EIGENVALUES IN THE INTERVAL (0,3) IS

1

EIGENVALUE

2.56154823E 00

CORRESPONDING EIGENVECTOR

-3.69047642E-01 -6.57192111E-01

6.57192290E-01

GQ

! O


4

MATRIX ELEMENTS

1.87500000E 00 -5.00000000E-01

3.75000000E-01 -2.50000000E-01

-5.00000000E-01

2.25000000E 00 -2.50000000E-01 -3.75000000E-01

3.75000000E-01 -2.50000000E-01

2.12500000E 00 -1.25000000E-01

-2.50000000E-01 -3.75000000E-01 -1.25000000E-01

2.12500000E 00

NOT ENOUGH SPACE ALLOCATED FOR THE

4 EIGENVALUES IN THE INTERVAL (0,3).

OUTPUT FROM THE EISPAC SAMPLE PROGRAM PRINTED ON UNIT 6

CO


3

MATRIX ELEMENTS

-I.00000000D 00

1.00000000D 00 -1.00000000D 00

1.00000000D 00

1.00000000D 00 -1.00000000D 00

-I.00000000D 00 -1.00000000D 00

1.00000000D 00

NUMBER OF EIGENVALUES IN THE INTERVAL (0,3) IS

EIGENVALUE

2.56155281D 00

CORRESPONDING EIGENVECTOR

-3.69048184D-01 -6.57192300D-01

6.57192300D-01


4

MATRIX ELEMENTS

1.87500000D 00 -5.00000000D-01

3.75000000D-01 -2.50000000D-01

-5.00000000D-01

2.25000000D 00 -2.50000000D-01 -3.75000000D-01

3.75000000D-01 -2.50000000D-01

2.12500000D 00 -1.25000000D-01

-2.50000000D-01 -3.75000000D-01 -1.25000000D-01

2.12500000D 00

EISPAC EXECUTION PHASE ERROR(S)...

03 PARAMETER MM SPECIFIED INSUFFICIENT STORAGE TO HOLD ALL EIGENVALUES IN THE INTERVAL LB TO UB.

EXECUTION TERMINATED.

I

3.0-1

Section 3

VALIDATION OF EISPACK

As part of its original development, EISPACK was subjected to thorough

testing designed to exercise every statement in each subroutine and path

in the package° Before a version of EISPACK is declared certified, however,

it must also be validated at one or more test sites not involved in the

adaptation. This validation has two important goals. One is to insure

that the adaptation has been carried out successfully and that EISPACK

performs as anticipated on that computer system. The second has been of

major importance in the development of EISPACK; it is to provide feedback

on the ease of use of EISPACK and its documentation. The procedures

included in and the philosophy behind this validation are discussed in

further detail in ([3],[5]).

Thus~ validation at test sites includes two kinds of testing. The

first employs tes~ drivers and a collection of 82 matrices supplied with

EISPACK; its purpose is to verify that the subroutines have been adapted

to the machine and system properly, and to obtain data which can later be

used as a check at other locations having the same computer system. These

test drivers and matrices are included on the tape from the distribution

center as described in Section 5.

The second kind of testing is the more informal; it seeks to employ

EISPACK in actual scientific computations to measure the ease of use of

the routines and their documentation. By its very nature, of course, this

informal testing is not repeatable.

In order to simplify the communication of the results of the formal

testing, a measure of performance for EISPACK, based on the backward error

analysis of Wilkinson and Reinsch ([1],[2]), was defined. It is computed as:

124

3.0-2

= max iNi!N

11Az i - Xizill 10.N.~.llAl[.llzill

where each pair %'i and z i is an eigenvalue and corresponding eigenvector

computed by EISPACK for the matrix A of order N, and where e is the pre-

cision of arithmetic on the test machine (called MACHEP in the subroutines).

The factor i0 in the formula for ~ was chosen empirically to obtain

the following criterion for the performance of EISPACK:

If ~ is less than i, EISPACK has performed satisfactorily (as well as

can be expected according to the backward error analysis for the particular

precision of arithmetic). If ~ is greater than i00, the performance is

deemed poor. Finally, if ~ is between 1 and I00, the performance is pro-

gressively marginal, and further investigation might be in order to verify

that no error has occurred.

This measure of performance is also useful as a check on the correct

installation of EISPACK; the residuals Az i - %izi are very sensitive to

small perturbations in I i and zi, and hence so is ~. ~ may thus reflect

small changes in the performance of EISPACK caused either by changes in the

subroutines themselves or by the hardware, operating system, compiler, or

library with which they are used. Hence it provides an excellent "quick

check" of the correct installation of E~SPACK on a hardware-software system.

If the values of ~ obtained from the test cases exactly duplicate those

obtained at the test site, it is virtually certain that EISPACK has been

correctly installed. If, however, the values of ~ differ, an error may

have occurred in the transmission or implementation of EISPACK, or the

hardware-software system may differ from that on which it was tested; such

differences should probably be investigated.

125

3.0-3

The collection of 82 test matrices has been accumulated from various

sources and provides a wide spectrum of test cases from trivial to patho-

logical. Most values of the performance index ~ for these test cases

were less than i for the systems on which EISPACK has been certified. The

weaker performances were generally observed in the paths where some eigen-

vectors were computed; that is, where the inverse iteration subroutines

(INVIT, CINVIT, TINVIT) were called.

126

4.0-I

Section 4

EXECUTION TIMES FOR EISPACK

In this section we display approximate execution times of the indi-

vidual subroutines and various paths in EISPACK measured with sample

matrices on many of the computer systems for which the subroutines have

been certified. The elements of the sample matrices are random numbers

sampled from uniform distributions. Tables of execution times appear

in the first subsection, and considerations regarding the reliability of

the timing measurements, their dependence upon the elements of the

matrices, and the extrapolation of these results to other machines are

discussed in later subsections. The section concludes with listings of

the program segments that generate the sample matrices.

127

4.1-1

Section 4.1

TABLES OF EXECUTION TIMES

For each of 15 computer systems there follow three tables displaying

sample execution times respectively for complex general matrices, real

general matrices~ and those matrices that can be reduced to real symmetric

tridiagonal form. A further table follows comparing the performances of

the computer systems with each other. Finally, one additional table is

included reporting path timings on the IBM 370/195 when the control program

EISPAC is used.

The tables report execution times both for the individual subroutines

and for many of the recommended paths. Each column of a table reports times

for a matrix of different order. The entries in any column are expressed

as multiples of the time unit that appears at the head of the column. The

time unit chosen is the absolute time for subroutine COMHES, ELMHES, or

TREDI as appropriate. A dash appears in place of an entry representing

an execution time too small to be measured within the resolution of the

clock.

For a subroutine that computes some eigenvalues or eigenvectors, the

tabulated time represents that required for the subroutine to compute

all eigenvalues or eigenvectors. The times for the eigenvector subroutines

INVIT~ CINVIT, and TINVIT are measured when the eigenvalues are provided

by the subroutines HQR, COMLR, and BISECT respectively; these times

could be significantly longer if less accurate eigenvalue subroutines

were substituted.

For paths where a driver subroutine exists, the time for the actual

call of the driver subroutine is recorded. For other paths, the entries

are built by summing the times for the separate suhroutines. The entries

128

4.1-2

for those paths that compute partial eigensystems are expressed as the

sum of two terms: the first term is the base time for the path and the

second term is that part which depends upon the number of eigenvalues

and eigenvectors computed. For complex general matrices, this latter

term is the product of the estimated time to compute one eigenvector and

M, the number of eigenvectors computed. For real general matrices, it

is the product of the estimated time to compute one column of the eigen-

vector matrix and M, the number of columns required to store the requested

eigenvectors. For matrices that can be reduced to real symmetric tri-

diagonal form, it is either the product of the estimated time to compute

one eigenvalue-eigenvector pair and M, the number of pairs computed, or

the product of the estimated time to compute one eigenvalue and M, the

number of eigenvalues computed. Program segments that generate the

sample matrices are listed in Section 4.5.

129

4.1-3

TABLE 4

SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR

COMPLEX GENERAL MATRICES

MACHINE: IBM 370/195, Fortran H, OPT=2 ARGONNE NATIONAL LABORATORY

SUBROUTINE

Time Unit (See)

CBAL CBABK2

COMHES COMBAK

CORTH CORTB

COMQR2 COMLR2

COMQR COMLR

CINVIT

ORDER OF MATRIX

N=I0 N=20 N=40 N=60 N=80

.002 .014 .099 .33 °86

o 17 .07 .03 .02 ~01 . II .05 .03 .02 .01

i i i 1 I .46 .53 .61 .66 .91

2.3 2.6 3,0 3.0 2.8 i,I 1.3 1.4 1.5 1.3

15 14 !4 14 13 ii i0 9.3 9,1 8.0

7.7 5.8 4.8 4.4 3.8 6.9 4.9 3.5 3.1 2.6

7.4 5.5 4.3 3.7 3.4

PATHS

CG (CBAL,CORTH,COMQR2,CBABK2)

CG (CBAL,CORTH,COMQR)

CBAL,CORTH,COMQR,CINVIT, CORTB~CBABK2

18

i0

I0+.86M

17 17 17 15

8.5 7.8 7.5 6.7

8.5+o34M 7.8+.14M 7.5+.09M 6.6+.06M

130

4. I-4

SUBROUTINE

Time Unit (Sec)

BALANC BALBAK

ELMHES ELTRAN ELMBAK

ORTHES ORTRAN ORTBAK

HQR2

HQR

INVIT

TABLE 5

SUMMARY OF EXECUTION TIM~S FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR

REAL GENERAL MATRICES


ORDER OF MATRIX

N= i0 N=20 N=40 N=60 N=80

.001 .006 .047 .15 .36

.40 .13 .05 .03 .02

.17 .07 .03 .02 .02

1 1 i 1 i .28 .13 .06 .04 .03 .63 .59 .60 .60 .64

2.6 2.7 2.7 2.6 2.6 .72 .60 .54 .52 .51

1.0 .91 .83 .79 .78

19 15 13 12 12

12 7.9 5.4 4.7 4.2

6.3 5.2 4.3 3.9 3.7

PATHS

RG (BALANC, ELMHES, ELTRAN, HQR2, BALBAK)

RG (BALANC,ELMHES,HQR)

BALANC, ELMHES, HQR, INVIT, ELMBAK ~ BALBAK

20

13

13+.71M

17 14 14 13

9.0 6.6 5.8 5.2

9 . 0+. 29M 6 . 5+. 12M 5.8+. 08M 5.3+. 05M

131

4. I-5

TABLE 6

SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT

REDUCE FULL MATRICES TO REAL SYMMETRIC TRIDIAGONAL FORM


SUBROUTINE

Time Unit (Sec)

N=IO

.001

ORDER OF MATRIX N=20 N=40 N=60

,007 .041 .12

N=80

.27

TREDI TRED2 TRED3 TRBAKI TRBAK3

1 1 1 1 1

1.6 1.8 2.0 2.1 2.2 ,98 i.i i.I 1.2 1.2

1.2 1.4 1.6 1.7 1.8 .85 I.i 1.3 1.5 1.5

HTRIDI HTRID3 HTRIBK HTRIB3

2.1 2.6 3.0 3.2 3.4 2.2 2.8 3.3 3.6 3.8 2.3 3.4 4.3 4.9 5.1 2.6 4.0 5.1 5.7 6,0

FIGI FIGI2 BAKVEC

13 ~05 °02 .01 °00 18 .i0 ~05 .03 ,02 I0 .05 ~03 .02 .01

TQL2 IMTQL2

TQLRAT TQLI IMTQLI

BISECT TRIDiB IMTQLV RATQR

TINVIT TSTURM

3.4 3.5 3.3 3.2 3.2 3,8 3.8 3.7 3.5 3.5

1.2 .67 °36 .24 ,18 2.1 1.5 ,94 .66 ,52 2.2 1.6 1.0 ,73 ,57

12 8.1 4.9 3.5 2.7 12 7.7 4.6 3.3 2.5 2.4 1.7 I. 1 .77 .60 2.6 2.2 1.5 1.2 .93

.95 ,64 ~40 .30 .30 13 8.6 5.3 3.8 3.0

PATHS

RS (TRED2,TQL2) RS (TREDI,TQLRAT) TREDI,BISECT,TINVIT,TRBAKI TREDI,BISECT

CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,TINVIT~HTRiBK HTRIDI,BISECT

5.0 5.3 5.3 5.3 5.3 2.2 1.7 1.3 1.2 1.2

I+i . 4M i+. 5 IM I+. 17M I+. 09M i+. 06M i+i. 2M i+. 40M I+. 12M I+. 06M i+. 03M

8.1 9.5 Ii II 12 3.3 3.3 3.3 3.5 3.6

2.1+1.5M 2.6+.61M 3.0+.24M 3.2+.15M 3.4+.IOM 2.1+1.2M 2.6+.40M 3.0+.12M 3.2+.06M 3.4+.03M

132

4.1-6

TABLE 7



MACHINE: IBM 360/75, Fortran H, OPT=2 UNIVERSITY OF ILLINOIS

SUBROUTINE

Time Unit (See)

CBAL CBABK2

COMIIES COMBAK

CORTH CORTB

COMQR2 COMLR2

COMQR COMLR

CINVlT

ORDER OF MATRIX

N=20 N=40 N=60 N=80

.20 1.6 5.2 12

.04 .02 .01 .01

.05 .01 .01 .01

1 i i 1 .48 .52 .55 .55

2.2 2.3 2.3 2.4 1.2 1.2 1.2 1.3

15 14 14 14 7.7 6.6 6.5 6.3

5.7 4.7 4.5 4.4 3.5 2.4 2.3 2.1

3.2 2.4 2.2 2.1

PATHS

CG (CBAL, CORTH, COMQR2, CBABK2 )

CG (CBAL, CORTH, COMQR)

CBAL, CORTH, COMQR, CINVlT, CORTB, CBABK2

17 17 16 16

7.9 7.1 6.8 6.7

7.9+.22M 7.1+.09M 6.8+.06M 6.7+.04M

133

4.1-7

TABLE 8

Sb~MARY OF EXECUTION TIMES FOR THE E!SPACK SUBROUTINES INCLUDED IN THE PATHS FOR

HEAL GENERAL MATRICES


SUBROUTINE

Time Unit (Sec)

BALANC BALBAK



HQR2

HQR

INVIT

ORDER OF MATRIX

N=20 N=40 N=60 N=80

.063 .49 1.6 3.9

. II .04 .02 .02 ~03 .02 .02 °01

I 1 1 i .05 .03 .02 .01 .65 .60 .61 .60

2.5 2.4 2.3 2.3 .78 .69 .68 .67

I.i i.i I.i 1.0

17 14 14 13

8.0 5.8 5.2 4.6

3.7 3.1 2.9 2.7

PATHS

RG (BALANC,ELMIIES ,ELTRAN, NQR2, BALBAK)

RG (BALANC, ELMHES, HQR)

BALANC, ELMHES, HQR, INVIT, ELMBAK, BALBAK

18 15 15 14

9.1 6.8 6.2 5.7

9.1+.22M 6.8+.09M 6.2+.06M 5.7+.04M

134

4. i-8

TABLE 9




SUBROUTINE ORDER OF MATRIX

N=20 N=40 N=60 N=80

Time Unit (See) .072 .48 1.6 3.5

TRED 1 TRED2 TRED3 TRBAKI TRBAK3

1 1 1 1 1.8 1.9 1.9 2.0 .96 .93 1.0 1.0

1.3 1.5 1.5 1.5 1.2 1.3 1.4 1.4


2.9 3.2 3.4 3.5 3.0 3.3 3.6 3.7 4.1 4.6 5.0 5.1 4.4 5.0 5.5 5.6

FIGI FIGI2 BAKVEC

.01 .00

.01 .01

.02 .01

TQL2 IMTQL2

4.9 5.0 4.8 4.8 5.0 5.0 4.9 4.9

TQLRAT TQLI IMTQLI

.58 .32 .21 .15 1.3 .70 .47 .36 1.2 .71 .50 .38

BISECT TRIDIB IMTQLV RATQR

4.9 2.7 1.8 1.4 5.2 2.8 1.9 1.5 1.3 .75 .49 .38 2.2 1.4 .99 .79

TINVIT TSTURM

• 49 .34 .25 .28 5.5 3.1 2.2 1.7

PATHS

RS (TRED2,TQL2) RS (TREDI, TQLRAT) TREDI,BISECT,TINVIT,TRBAKI TREDI,BISECT

6.7 6.9 6.8 6.8 1.4 1.3 1.2 i.I

i+. 33M I+. 1 IM i+. 06M I+. 04M i+. 24M I+. 07M I+. 03M I+. 02M

CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,TINVlT,HTRIBK HTRIDI,BISECT

12 12 13 13 3.5 3.5 3.6 3.7

2.9+.47M 3.2+.19M 3.4+.12M 3.5+.09M 2.9+.24M 3.2+.07M 3.4+.03M 3.5+.02M

~85

4. i-9

TABLE i0



MACHINE: IBM 370/168, Fortran H, OPT=2 UNIVERSITY OF MICHIGAN

SUBROUTINE

Time Unit (Sec)

CBAL CBABK2

COMHES COMBAK

CORTH CORTB

COMQR2 COMLR2

COMQR COMLR

CINVIT

ORDER OF MATRIX

N=I0 N=20 N=40 N=60 N=80

.008 °070 .57 2.0 4.7

.08 .03 .01 .01 .01 • 07 .03 ~01 .01 .01

! 1 1 1 1 • 47 .52 ,54 .55 ,58

2 .3 2 .3 2 .2 2 .2 2 .2 1.3 1.3 1.2 1.2 1.2

19 16 15 14 14 9.1 7.7 6.5 6.3 6.1

8.1 5.9 4.8 4.6 4.3 4.9 3.3 2.3 2.1 1.9

4.5 3.0 2.2 2.0 1.9

PATHS

CG (CBAL, CORTH~COMQR2,CBABK2)



21

Ii

1 i+. 58M

19 17 17 16

8.1 7.0 6.7 6.4

8.2+.21M 7~O+.09M 6.7+.05M 6o4+.04M

136

4.1-10

TABLE Ii




SUBROUTINE

Time Unit (Sec)

BALANC BALBAK


ORTHE S ORTRAN ORTBAK

HQR2

HQR

INVIT

ORDER OF MATRIX

N=I0 N=20 N=40 N=60 N=80

.003 .020 .16 .56 1.4

.20 .07 .03 .02 .01

.14 .06 .03 .02 .01

i 1 i I 1 • 12 .05 .02 .01 .01 .56 .58 .59 .59 .60

2.7 2.5 2.4 2.3 2.3 .87 .81 .78 .77 . 76

1.4 1.3 1.2 1.2 1.2

23 18 15 15 14

13 8.8 6.1 5.5 4.9

4.7 3.6 2.8 2.6 2.4

PATHS

RG (BALANC~ELMIIES~ELTRAN~ HQR2,BALBAK)


BAL~NC,ELMHES,HQR~INVlT~ ELMBAK, BALBAK

25

14

14+.54M

19 16 16 15

9.8 7.2 6.5 5.9

9.8+.21M 7.2+.09M 6.5+.05M 5.9+.04M

137

4.1-11

TABLE 12





N=I0 N=20 N=40 N=60 N=80

Time Unit (See) ~004 .023 .16 .50 1,2


1 I i 1 i 1,6 1.8 1.9 2.0 2.0 .98 °99 1.0 1.0 1.0

i.i 1.3 1.5 1.5 1,5 .99 1.2 1.4 1.5 1.5


2.8 3.1 3.4 3.6 3.7 2.7 3.1 3.5 3.6 3.7 3.3 4.3 5.0 5.2 5.3 3.4 4.5 5.2 5.4 5.5

FiGI FIGI2 BAKVEC

.09 .03 .01 .00 ,00 ,12 .04 .02 ,01 .01 .i0 .05 .03 .02 .02

TQL2 IMTQL2

5.4 5.8 5.7 5.6 5.4 5.4 5.5 5.6 5.3 5.3

TQLRAT TQLI IMTQLI

1.2 .66 .34 .22 .16 2,3 1.4 .81 .55 ,42 2,3 1.5 .83 .56 .42


TINVIT TSTUPd<

8.0 4.9 2.7 1.8 1.4 8.4 5.0 2.7 1.8 1.4 2.4 1.5 .85 .57 .44 2.8 2,1 1.4 1.0 ,80

.86 .54 .31 .23 °26 8,8 5.3 2.9 2.0 1.6

PATHS

RS (TRED2,TQL2) RS (TREDI,TQLRAT) TREDI,BISECT,TINVIT,TRBAKI

TREDI,BISECT

CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,TINVIT~HTRIBK HTRIDI,BISECT

7.0 7.6 7.6 7.6 7.4 2.2 1,7 1.3 1.2 1.2 I+I.0M i+. 34M i+. IIM I+.06M 1+. 04M I+. 80M I+. 24M i+. 07M I+. 03M I+. 02M

ii 13 14 14 14 4.1 3.8 3.8 3.8 3.8

2.8+1.2M 3.1+.48M 3.4+.20M 3.6+,12M 3.7+.09M 2.8+.80M 3.1+,24N 3.4+.07M 3.6+.03M 3.7+.02M

138

4.1-12

TABLE 13



MACHINE: IBM 370/165, Fortran H Extended, OPTIMIZE(2) THE UNIVERSITY OF TORONTO

SUBROUTINE

Time Unit (Sec)

CBAL CBABK2

COMHES COMBAK

CORTH CORTB

COMQR2 COMLR2

COMQR COMLR

CINVIT

ORDER OF MATRIX

N=I0 N=20 N=40 N=60 N=80

.006 .043 .39 1.5 4.0

- .06 .03 .02 .01 - - .02 .02 .01

1 1 1 1 1

1 .53 .62 .71 .98

2 2.2 2.0 1.9 1.7 1 1.2 I. 1 .95 .85

17 16 13 12 i0 ii 9.3 7.5 6.5 5.9

8 5.9 4.3 3.7 3.2

6 4.1 2.7 2.2 1.9

7 4.8 3.3 2.6 2.5

PATHS



CBAL,CORTH,COMQR,CINViT, CORTB,CBABK2

20 18 15 13 12

ii 8.2 6.4 5.6 4.9

10+.8M 8.2+.30M 6.4+.IIM 5.6+.06M 4.9+.04M

139

4.1-13

TABLE 14

SUMY~RY OF EXECUTION TIMES FOR THE E!SPACK SUBROUTINES INCLUDED IN THE PATHS FOR



SUBROUTINE

Time Unit (Sec)

BALANC BALBAK



HQR2

HQR

INVIT

ORDER OF MATRIX

N=20 N=40 N=60 N=80

.016 .12 .43 i.i

- .05 .03 .02

- . 0 3 . 0 2 . 0 2

1 1 1 1 - . 0 7 . 0 4 . 0 3

.62 .63 .66 .80

2.3 2.4 2.2 2.1 • 83 .75 .71 .64

1.2 I.i i.i .95

16 15 13 ii

8.5 5.9 4.9 4.1

4,2 3.7 3.1 2,8

PATHS




18 16 14 12

9.1 6.8 5.9 5.1

9.5+.24M 7.0+.IIM 5.9+.06M 5.1+.05M

140

4.1-14

TABLE 15





N=I0 N=20 N=40 N=60 N=80

Time Unit (Sec) .003 .017 .ii .35 .84


i i i i 1 2 1.7 1.9 2.0 2.0 I .92 1.0 1.0 1.0 i 1.5 1.6 1.7 1.6 i i.i 1.3 1.3 1.3


2 2.7 3.1 3.6 4.1 3 2.7 3.2 3.4 3.5 3 3.7 4.7 5.0 5.5 4 4.0 5.1 5.1 5.1

FIGI FIGI2 BAKVEC

- .01 .00 .04 .03 .02 .03 .02 .02

TQL2 IMTQL2

4 4.8 4.7 4.8 4.4 4 4.9 4.8 4.7 4.6

TQLRAT TQLI IMTQLI

2 .80 .42 .27 .19 2 1.5 .92 .61 .46 2 1.7 .96 .63 .47


i0 6.7 3.9 2.6 1.9 9 6.5 3.8 2.6 1.9 3 1.7 .98 .64 .48 2 2.3 1.6 i.i .86

TiNVIT TSTURM

i . 76 .42 . 30 . 30 i0 7.3 4.2 2.9 2.2

PATHS

RS (TRED2,TQL2) RS (TRED i, TQLRAT) TREDI,BISECT,TINVIT,TRBAKI TREDI,BISECT

6 6.8 6.6 6.7 6.3 3 1.8 1.4 1.3 1.2

i+ 1 . 2M i+. 45M I+. 15M i+. 08M i+. 05M I+i. 0M i+. 34M i+. 10M i+. 04M i+. 02M

CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,TINVIT~HTRIBK HTRIDI,BISECT

ii 4

4+i. 4M 4+1.0M

ii 13 13 14 3.4 3.6 3.9 4.3

2.7+.56M 3.1+.22M 3.6+.13M 4.1+.IOM 2.7+.34M 3.1+.IOM 3.6+.04M 4.1+.02M

141

4.1-15

TABLE 16



MACHINE: Burroughs 6700, Fortran IV (2.6) UNIVERSITY OF CALIFORNIA~ SAN DIEGO

SUBROUTINE

Time Unit (Sec)

CBAL CBABK2

COMHES COMBAK

CORTH CORTB

COMQR2 COMLR2

COMQR COMLR

CINVlT

ORDER OF MATRIX

N=I0 N=20 N=40 N=60

.27 2.1 17 59

. i0 .04 °02 .01

.05 .02 .01 .01

i 1 1 I .58 .56 .59 .59

1.7 1.6 1.6 1.6 .92 1.0 .99 .94

13 Ii i0 9.6 8.6 7.9 6.8 6.8

5.0 3.9 3.3 3.1 4.3 3.1 2.4 2.3

3.3 2.6 2.3 2.2

PATHS

CG (CBAL~CORTH,COMQR2,CBABK2)

CG (CBAL,CORTH, COMQR)

CBAL~CORTH,COMQR~CINVIT, CORTB~CBABK2

14 13 12 Ii

6.7 5.6 4.9 4.6

6.8+. 43M 5.5+. 18M 4.9+. 08M 4.8+. 05M

142

4.1-16

TABLE 17

SIIMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR


MACHINE: Burroughs 6700, Fortran IV (2.6) UNIVERSITY OF CALIFORNIA, SAN DIEGO

SUBROUTINE

Time Unit (Sec)

BALANC BALBAK

ELMHES ELTR2uN ELMBAK


HQR2

HQR

INVIT

ORDER OF MATRIX

N=I0 N=20 N=40 N=60

.095 .79 6.3 20

.18 .06 .03 .02

.08 .04 .02 .01

1 1 i 1 .17 .07 .04 .03 • 57 .58 .59 .60

1.7 1.7 1.6 1.7 .83 .70 .66 .66

i.i .99 .94 1.0

12 9.9 8.9 8.8

6.3 4.3 3.6 3.1

3.1 2.4 2.1 2.1

PATHS

RG (BALANC,ELMHES,ELTRAN, HQR2,BALBAK)


BALANC, ELMHES, HQR, INVIT ELMBAK, BALBAK

14 11 I0 9.9

7.8 5.4 4.5 4.3

7.5+. 38M 5.4+. 15M 4.6+. 07M 4. i+. 04M

143

4.1-17

TABLE 18



MACHINE: Burroughs 6700, Fortran IV (2.6) UNIVERSITY OF CALIFORNIA, SAN DIEGO


N=IO N=20 N=40 N=60

Time Unit (Sec) .093 ~56 4.1 13

TRED i TRED2 TRED3 TRBAKI TRBAK3

i 1 1 I 1.6 1.9 2.0 2.2 .77 .82 .76 .80

I.I 1.5 1.6 1.8 I.i 1.4 1,5 1.6


2.5 2.9 3.1 3.1 2.4 2.8 3.0 3.1 3.5 4.6 5.1 5.3 3.7 4.9 5.1 5.3

FIGI FIGI2 BAKVEC

.05 .01 .00 .00

.12 ,05 .03 .02

.09 .06 .03 .02

TQL2 IMTQL2

4.2 4,7 4.6 4.7 4.4 5.1 4.8 5.2

TQLRAT TQLI IMTQLI

.77 .38 .19 .13 i.I .68 .36 .25 1.2 .69 .37 .25

BISECT TRIDIB IMTQLV HATQR

3.7 2.1 I.I ,73 4.1 2.5 1.2 .83 i. 1 .61 .31 .22 1.4 I.I .62 ,46

TINVlT TSTURM

.68 o 43 .24 .19

5.0 3.0 1.5 i.I

PATHS

RS (TRED2,TQL2) RS (TREDI,TQLRAT) TREDI,BISECT,TINVlT,TRBAKI TREDI~BISECT

5.8 6.9 6.6 6.9 1.5 1.3 i.I i.i

I+. 55M i+. 20M I+. 07M I+. 04M I+. 37M i+. IIM i+. 03M I+.01M

CH (HTRIDI,TQL2,HTRiBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,TINVIT,HTRIBK HTRIDI,BISECT

ii 12 13 13 3.2 3.2 3.3 3,3

2.5+.79M 2,9+.35M 3.1+.16M 3.1+.IOM 2.5+.37M 2.9+.IIM 3.1+.03M 3.1+.OIM

144

4.1-18

TABLE 19



MACHINE: CDC 6600, FTN (4.2) Compiler KIRTLAND AIR FORCE BASE

SUBROUTINE

Time Unit (Sec)

CBAL CBABK2

COMHES COMBAK

CORTH CORTB

COMQR2 COMLR2

COMQR COMLR

CINVIT

ORDER OF MATRIX

N=40 N=50 N=60 N=70 N=80

.52 1.0 1.8 2.8 4.2

1 1 1 1 1 .72 .57 .55 .56 .56

2.8 2.6 2.7 2.7 2.7 1.0 .96 .93 .95 .97

14 12 12 12 12 7.5 6.9 6.6 6.5 6.6

4.9 4.5 4.3 4.2 4.2 3.1 2.7 2.5 2.4 2.4

2.6 2.3 2.2 2.2 2.2

PATHS

CC (CBAL,CORTH,COMQR2,CBABK2)

CC (CBAL,CORTH,COMQR)

CBAL,CORTH,COMQR,CINVIT, CORTB,CBABK2

16 15 15 14 15

7.8 7.1 6,9 6.8 7.0

7.7+.09M 7.1+.07M 6.9+.05M 6.8+.04M 6.9+.04M

145

4.1-19

TABLE 20



MACHINE: CDC 6600, FTN (4.2) Compiler KIRTLAND AIR FORCE BASE

SUBROUTINE

Time Unit (Sec)

BALANC BALBAK


0RTHES ORTRAN ORTBAK

HQR2

HQR

INVIT

ORDER OF MATRIX

N=40 N=50 N=60 N=70 N=80

.25 .49 .80 1.4 2.0

1 1 1 1 1

.46 .59 °59 .61 °58

2.6 2.6 2.6 2.5 2.5 • 92 .81 •81 .76 .75

1.2 1.2 1.2 1.2 1.2

12 12 12 ii i0

5.1 4.9 4.6 4.0 3.8

2.8 2.7 2.7 2.5 2.4

PATHS



BALANC, ELMHES ,HQR, INVIT, ELMBAK, BALBAK

13 13 13 12 12

6.1 5.7 5.7 5.0 4.7

6.1+.08M 5.8+.07M 5.6+.05M 5.0+.04M 4.8+.04M

146

4.1-20

TABLE 21

Sb~MMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT

REDUCE FULL MATRICES TO REAL SY~fl~ETRIC TRIDIAGONAL FORM

MACHINE: CDC 6600, FTN (4.2) Compiler KIRTLANDAIR FORCE BASE


N=40 N=50 N=60 N=70 N=80

Time Unit (Sec) .19 .37 .60 .92 1.3


1 1 1 1 1 2.2 2ol 2.1 2.2 2.2 1.8 1.8 1.7 1.8 1.7 1.7 1.7 1.7 1.8 1.8 1.9 1.9 2.0 2.1 2.0


2.2 1.9 2.2 2.3 2.1 1.9 2.1 2.2 2.3 2.0 3.4 3.0 3.5 3.7 3.3 3.0 3.1 3.4 3.6 3.4

FIGI FIGI2 BAKVEC

TQL2 IMTQL2

4.2 4.0 4.0 4.2 4.0 4.5 4.3 4.4 4.4 4.4

TQLRAT TQLI IMTQLI

.39 .28 .25 .21 .19 • 63 .49 .42 .37 .32 .68 .56 .50 .44 .38

BISECT TRIDiB IMTQLV RATQR

6.2 4.9 4.2 3.7 3.2 6.0 4.8 4.2 3.6 3.2 .76 .62 .54 .47 .42

2.0 1.6 1.4 1.3 i.i

TINViT TSTURM

.52 .40 .39 .36 .40 6.6 5.3 4.6 4.1 3.7

PATHS


6.3 6.0 6.1 6.2 6.2 1.4 1.3 1.2 1.2 1.2

I+.21M I+. 14M I+. IIM I+.08M I+.07M

i+. 16M i+. IOM I+. 07M i+. 05M i+. 04M

CH (HTRIDI,TQL2,HTRIBK) CH (H~RIDI, TQLRAT) HTRIDI,BISECT,TINVIT,HTRIBK HTRIDI,BISECT

8.8 8.9 9.7 i0 9.2 2.1 2.3 2.5 2.6 2.3

2.2+.25M 2.~.15M 2.1+.11M 2.3+.09M 2.I+.07M 2.2+.16M 2.~.IOM 2.1+.07M 2.~.05M 2.1+.04M

147

4.1-21

TABLE 22

SUMMARY OF EXECUTION TIMES FOR ~IE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR


MACHINE: CDC 6600, FTN 4.3+P393 Compiler, OPT=I NASA LANGLEY RESEARCH CENTER

SUBROUTINE

Time Unit (Sec)

CBAL CBABK2

COMHES COMBAK

CORTH CORTB

COMQR2 COMLR2

COMQR COF~R

CINVIT

ORDER OF MATRIX

N=I0 N=20 N=40 N=60

°009 .063 .54 1.8

.24 . i0 .04 .03

• 12 . 04 .01 .01

I 1 1 1 °47 .60 .62 .64

1.8 1.6 1.6 1.6 .88 .90 .84 .79

16 15 13 13 9.9 8.0 6.9 7.0

7.4 5.9 4.5 4.3 5.5 3.9 2.8 2.8

3.8 2.8 2.2 2.1

PATHS




18 17 14 14

9.5 7.6 6.2 5.9

9.4+.48M 7.6+.19M 6.2+.08M 5.9+.05M

148

4.1-22

TABLE 23




SUBROUTINE

Time Unit (Sec)

BALANC BALBAK


ORTHE S ORTRAN ORTBAK

HQR2

HQR

INVIT

ORDER OF MATRIX

N--10 N=20 N=40 N=60

.006 .032 .24 .77

.27 .17 .07 .05 - .05 • 03 .02

1 1 1 1 • 18 ° 06 . 04 . 02 .55 .58 .61 .61

1.8 2.0 2.2 2.2 .91 .73 .85 .82

i.I 1.3 1.3 1.3

13 14 14 12

6.9 6.7 6.2 4.8

3.6 3.3 3.1 2.9

PATHS

RG (BALANC,ELMHES,ELTRAN, HQR2,BALBAK)


BALANC, E LMHE S, HQR, INVIT, ELMBAK, BALBAK

14 15 15 13

8.5 7.7 7.2 5.9

8.2+.41M 7.9+.20M 7.2+.09M 5.8+.06M

149

4.1-23

TABLE 24

SVMMARY OF EXECUTION TIMES FOR THE EiSPACK SUBROUTINES INCLUDED IN THE PATHS THAT

REDUCE FULL MATRICES TO HEAL SYMMETRIC TRIDIAGONAL FORM


SUBROUTINE

ORDER OF MATRIX N=I0 N=20 N=40 N=60

Time Unit (Sec)


.006 ,030 .19 .58

1 1 i 1 1.6 1.8 2.0 2.0 1.2 1.5 1.7 1.8 1.2 1.4 1.6 1.7 1.2 1.5 1.8 1.7


FIGI FIGI2 BAKVEC

1.7 2.1 2.4 2.5 1.8 2.3 2.6 2.6 1.9 2.7 3.2 3.5 1.9 2.7 3.2 3.2

.03 .01 .00

.07 .02 ,01

.05 .04 .02

TQL2 IMTQL2

TQLRAT TQLI IMTQLI

BISECT TRIDIB iMTQLV RATQR

TINVIT TSTURM

3.6 3.8 4.! 4.1 3.8 4.0 4.4 4.7

1.0 .58 .32 .25 1.5 .95 .55 .42 1.6 i.I .68 .51

15 9.2 5.5 3.9 14 9.1 5.5 3.9 1.5 1.2 .74 .53 3.6 2.8 2.0 1.5

.91 .67 .44 .32 15 9.7 5.8 4.3

PATHS

RS (TREDZ,TQL2) RS (TREDI,TQLRAT) TREDI,BISECT~TINVIT,TRBAKI

TREDI,BISECT

CH (HTRIDi,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,TINVIT,HTRIBK HTRIDI~BISECT

5.5 5.8 6.1 6.1 2.0 1.6 1.4 1.2 I+I.7M I+.56M I+.IgM I+.IOM I+I.5M ~.46M I+.I4M I+.06M

7.2 8.8 9.9 i0 2.6 2.7 2.7 2.6

1.7+1.7M 2.1+.63M 2,4+.23M 2.5+.13M I. 7+1.5M 2. I+. 46M 2.4+. 14M 2.5+. 06M

150

4.1-24

TABLE 25



MACHINE: CDC 7600, Local Compiler NATIONAL CENTER FOR ATMOSPHERIC RESEARCH

SUBROUTINE

Time Unit (Sec)

CBAL CBABK2

COMHES COMBAK

CORTH CORTB

COMQR2 COMLR2

COMQR COMLR

CINVlT

ORDER OF MATRIX

N=I0 N--20 N=40 N=60 N=80

.002 .015 .ii .38 .89

- . i0 .05 .03 .02 - .05 .01 .01 .01

1 I i 1 1 i .57 .60 .61 .62

2 2.3 2.3 2.3 2.3 1 i.i i.i I.i i.i

15 15 13 13 13 i0 8.1 6.9 6.7 6.4

7 5.8 4.7 4.4 4.3 6 3.9 2.8 2.5 2.3

4 3.0 2.3 2.2 2.1

PATHS




18

9

9+. 5M

17 16 15 15

8.0 7.1 6.7 6.6

8.2+. 21M 7. i+. 09M 6.8+. 05M 6.6+. 04M

151

4.1-25

TABLE 26


REAl, GENERAL MATRICES


SUBROUTINE

Time Unit (Sec)

BALANC BALBAK



HQR2

HQR

INVIT

ORDER OF MATRIX

N=I0 N=20 N=40 N=60 N=80

• 001 .007 .050 .16 .38

- - .07 .05 .04 - - .02 .01 .01

1 i 1 1 i - - . 0 4 . 0 2 . 0 2

I .55 .60 .60 ,60

2 2.4 2.5 2.5 2.5 1 .81 .78 .78 .77 1 1.3 1.2 1.2 1,2

18 16 15 14 14

i0 7.4 5.8 5.2 4.8

4 3.4 3.0 2.8 2.7

PATHS


RG (BALANC, ELMHES ,HQR)

BALANC~ELMHES,HQR, INVIT, ELMBAK~BALBAK

20

ii

II+.5M

17 16 15 15

8.6 6.9 6.3 5.8

8.4+.20M 6.9+.09M 6.3+.06M 5.8+.04M

152

4.1-26

TABLE 27




SUBROUTINE

Time Unit (Sec)

TREDI TRED 2 TRED3 TRBAKI TRBAK3

ORDER OF MATRIX N = I0 N=20 N=40 N=60 N=80

.001 .007 .040 .12 .28

i 1 i I 1 2 1.7 1.9 2.0 2.0 2 1.8 2.8 3.2 3.4 I 1.3 1.5 1.5 1.6 2 1.6 2.7 3.0 3.2


2 2.1 2.4 2.6 2.6 2 2.2 2.5 2.6 2.7 2 2.5 3.1 3.3 3.4 2 2.6 3.2 3.4 3.5

FIGI FIGI2 BAKVEC

TQL2 IMTQL2

TQLRAT TQLI IMTQLI


TINVIT TSTURM

- .01 .00 .02 .01 .01 .03 .02 .01

3 3.4 3.6 3.6 3.5 4 3.5 3.8 3.8 3.8

1 .69 .40 .28 .21 2 1.0 .65 .46 .36 2 1.2 .77 .55 .43

18 II 7.0 5.0 3.9 17 Ii 6.6 4.7 3.6 2 1.3 .82 .58 .45 3 2.7 1.9 1.5 1.2

1 .62 .42 .32 .33 18 ii 7.2 5.2 4.1

PATHS

RS (TRED2,TQL2) RS (TREDI,TQLRAT) TREDI~BISECT,TINVIT,TRBAKI TREDI,BISECT

CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI, TQLRAT) HTRIDI~BISECT,TINVIT,HTRIBK

HTRIDI~BISECT

5 5.1 5.5 5.6 5.5 2 1.6 1.4 1.3- 1.2

1+2.0M i+. 65M i+. 22M i+. 11M i+. 07M i+i. 8M i+. 56M i+. 17M I+. 08M i+. 05N

8 4

2+2. IM 2+i .8M

7.9 9.1 9.4 9.6 2.8 2.8 2.8 2.8

2.1+.71M 2.4+.26M 2.6+.14M 2.6+,09M 2.1+.56M 2.4+.17M 2.6+.08M 2.6+.05M

153

4.1-27

TABLE 28



MACHINE: CDC 6400, FTN 3.0 Compiler, OPT=2 NORTHWESTERN UNIVERSITY

SUBROUTINE

Time Unit (Sec)

CBAL CBABK2

COMHES COMBAK

CORTH CORTB

COMQR2 COMLR2

COMQR COMLR

CINVIT

ORDER OF MATRIX

N=I0 N=20 N=40 N=60

.036 .29 2.2 7.5

o 19 .07 ~03 .02 .08 .03 .01 .01

i 1 1 1 .51 .54 .57 .58

2.5 2.4 2.4 2.4 1.2 1.2 1.2 1.2

18 16 15 14 9.7 7.9 6.5 6.5

8~.3 6.2 5.2 4.9 5.3 3.5 2.5 2.3

4.1 2.8 2.2 2.0

PATHS




21 19 17 17

ii 8.7 7.6 7.3

II+.54M 8.7+.20M 7.6+.09M 7.3+.05M

154

4.1-28

TABLE 29

SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCL~ED IN THE PATHS FOR



SUBROUTINE

Time Unit (Sec)

BALANC BALBAK



HQR2

HQR

INVIT

ORDER OF MATRIX

N=IO N=20 N=40 N=60 N=80

.016 .ii .83 2.7 6.3

.31 .14 .06 .04 .03 • 15 .05 .02 .01 .01

1 1 1 1 1 • 15 .06 .03 .02 .01

• 53 .54 .57 .57 .58

2.7 2.8 2.9 3.0 3.0 .83 .77 .77 .77 .77

1.3 1.2 1.2 1.2 1.2

17 15 14 13 13

i0 7.2 5.6 5.1 4.7

4.2 3.2 2.8 2.6 2.5

PATHS

RG (BALANC, EI~MHES, ELTRAN, HQR2, BALBAK)

RG (BALANC,ELMHES ,HQR)


19

Ii

114-. 48M

16 15 14 14

8.3 6.7 6.1 5.7

8 . 3+. I£M 6.7+. 08M 6. I+. 05M 5.7+. 04M

155

4.1-29

TABLE 30




SUBROUTINE

Time Unit (Sec)

TRED 1 TRED2 TILED3 TRBAKI TRBAK3

ORDER OF MATRIX N=I0 N=20 N=40 N=60 N=80

• 019 .ii .69 2.1 4.9

I 1 i i 1 1.7 1.8 1.9 2.0 2.0 1.2 1.3 1.5 1.6 1.6 I.i 1.3 1.5 1.5 1.5 I.i 1.3 1.5 1.6 1.7


2.4 2.7 3.0 3.1 3.2 2.4 2.7 2.9 3.0 3.1 2.6 3.4 4.0 4.3 4.5 2.6 3.4 4.0 4.2 4.4

FiGI FIGI2 BAKVEC

.07 .03 .01 .00 .00

.12 .05 .02 .01 °01

.ii °06 °03 .02 .02

TQL2 !MTQL2

TQLRAT TQLI !MTQLI


TINVIT TSTURM

4.2 4.5 4.7 4.7 4.7 4.4 4.7 4.9 4.9 4.9

I.i °66 .36 .24 .19 1.7 1o2 ~68 .48 .37 2.0 1.3 .77 .54 .41

9.8 6.2 3.5 2.5 1.9 i0 6°2 3.6 2.5 1.9 2.0 1.3 °79 .56 .43 3.1 2.4 1.6 1.2 .97

.94 .61 .37 .28 .31 II 6.7 3.9 2.8 2.2

PATHS


CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI~BISECT,TiNVIT~HTRIBK HTRIDI~BISECT

5.9 6.3 6.6 6.7 6.7 2.1 1.7 1.4 1.2 1.2 i+i .2M i+. 40M I+. 13M I+.07M I+.05M I+. 98M i+. 31M i+. 09M i+. 04M i+. 02M

9.2 i0 ii 12 12 3.5 3.4 3.4 3.4 3.4

2o4+1.3M 2.7+.51M 3.0+.20M 3.1+.12M 3.2+.08M 2.4+.98M 2.7+.31M 3.0+.09M 3.1+.04M 3.2+°02M

156

4.1-30

TABLE 31



MACHINE: CDC 6400/6500, FUN Compiler PURDUE UNIVERSITY

SUBROUTINE

Time Unit (Sec)

CBAL CBABK2

COMHES COMBAK

CORTH CORTB

COMQR2 COMLR2

COMQR COMLR

CINVIT

ORDER OF MATRIX

N=IO N=20 N=40 N=60 N=80

.045 .35 2.7 9.2 22

• 13 .05 .02 .01 °01

• 07 .03 .01 .01 .01

1 1 i 1 1 • 58 .62 .64 • 65 .66

2.7 2.7 2.7 2.7 2.7 1.4 1.3 1.3 1.3 1.3

20 18 16 16 16 ii 8.7 7.4 7.1 6.7

9.5 7.4 6.4 6.2 5.8 5.7 3.8 2.7 2.4 2.2

3.9 2.9 2.4 2.2 2.2

PATHS

CG (CBAL, CORTH,COMQR2,CBABK2)


CBAL,CORTH,COMQR,CINVlT, CORTB,CBABK2

23

12

12+.54M

20

i0

IO+.21M

19 19 18

9.1 8.9 8.5

9. I+.09M 8.9+.06M 8.5+.04M

157

4.1-31

TABLE 32


REAL GENERAL MATR!CES

MACHINE: CDC 6400/6500, FUN Compiler PUF~UE UNIVERSITY

SUBROUTINE

Time Unit (Sec)

BALANC BALBAK

EL~ES ELTRAN EL~b~K


HQR2

HQR

INVIT

ORDER OF MATRIX

N=I0 N=20 N=40 N=60 N=80

.018 .12 .90 3.0 6.9

• 25 • I0 .05 .03 .02 • 14 .06 .03 .02 .01

i I 1 i 1 17 .07 ,03 ,02 .02

.55 .60 .61 .62 ,63

2.6 2.7 2.7 2,8 2.8 .91 .83 .81 .81 ,81

1.4 1.3 1.3 1.3 1.2

33 31 30 30 29

18 14 12 II !0

5.1 4.9 4.6 4.6 4.6

PATHS

RG (BALANC,ELMIIES,ELTRAN, HQR2,BALBAK)


BALANC,ELMHES,HQR, INViT, ELMBAK, BALBAK

35 32 31 31 30

19 15 13 12 ii

19+.58M 15+.28M 13+.13M 12+.09M II+.06M

158

4.1-32

TABLE 33

SLrMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT

REDUCE FULL MATRICES TO REAL SY~METRIC TRIDIAGONAL FORM

MACHINE: CDC 6400/6500, FUN Compiler PURDUE UNIVERSITY

SUBROUTINE

Time Unit (Sec)

TRED I TRED2 TRED3 TRBAKI TRBAK3

ORDER OF MATRIX N= i0 N=20 N=40 N=60 N=80

.024 .13 .81 2.5 5.6

1 1 I I I 1.7 1.8 1.9 2.0 2.0 .92 I.i 1.2 1.2 1.2

I.I 1.3 1.5 1.6 1.6 i.i 1.4 1.6 1.7 1.7


2.4 2.8 3.2 3.4 3.5 2.6 3.1 3.5 3.7 3.9 2.8 3.7 4,5 4.9 5.1 3.0 4.0 4.9 5.3 5.5

FIGI FIGI2 BAKVEC

TQL2 IMTQL2

TQLRAT TQLI IMTQLI


TINViT TSTIYRM

• 06 .02 . Ol . 00 . O0

. Ii .05 .02 .01 .01

.09 .05 .03 .02 .02

3.8 4.2 4.4 4.6 4,6 4.0 4.2 4.5 4.5 4.6

• 83 .51 .28 .19 .15 1.4 .92 .56 .39 .30 1.5 1.0 .62 .44 .34

9.4 6.1 3.6 2.5 2.0 9ol 5.9 3.5 2.5 1.9 1.7 i.I .70 .50 .39 2.9 2,3 1,6 1.2 .98

.97 .68 .43 .33 .37 i0 6.7 4.0 2.9 2.3

PATHS


CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,IQLRAT) HTRIDI,BISECT,TINVIT,HTRIBK HTRIDI~BISECT

5.4 6,0 6.4 6.6 6.6 1.9 1.5 1,3 1.2 I.i

i+i. 2M i+. 40M I+. 14M i+. 07M i+. 05M i+. 94M i+. 30M i+. 09M I+. 04M i+. 02M

9.0 i0 12 13 13 3.3 3.3 3.5 3.6 3.6

2.4+1.3M 2.8+.52M 3.2+.21M 3.4+.13M 3.5+.09M 2.4+.94M 2,8+.30M 3.2+.09M 3,4+.04M 3.5+.02M

159

4.1-33

TABLE 34



MACHINE: CDC 6600/6400, RUN Compiler THE UNIVERSITY OF TEXAS

SUBROUTINE

Time Unit (See)

CBAL CBABK2

COlliES COMBAK

CORTH CORTB

COMQR2 COMLR2

COMQR COMLR

CINVIT

ORDER OF MATRIX

N=I0 N=20 N=40

.015 .084 .69

- ~17 .05 - - .02

1 I i - .64 .64

2.1 3.0 2.9 I.i 1.4 1.3

17 19 17 9.5 9.8 7.8

8.9 8.9 7.4 5.5 4.6 3.1

4.2 3.9 2.9

PATHS

CG (CBAL,CORTR,COMQR2,CBABK2)

CG (CBAL,CORTH,CO~R)

CBAL,CORTH,COMQR, CINVIT, CORTB~CBABK2

19 22 20

12 12 i0

19+.53M 12+.26M 10+.IIM

160

4.1-34

TABLE 35

SITMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR



SUBROUTINE

Time Unit (Sec)

BALANC BALBAK



HQR2

HQR

INVIT

ORDER OF MATRIX

N=20 N=40 N=60

.045 .24 .78

- .06 .06 - - .02

i 1 1 - - .04 .36 .73 .70

2.5 3.5 3.5 .73 .79 .77 .71 1.3 1.2

28 45 36

12 18 13

4.7 6.0 6.2

PATHS



B~C, EI~IHE S, HQR, INVIT, ELMBAK, BALBAK

N = 8 0

1.8

.05

.02

1 .03 .73

3.6 .77

1.2

36

13

6.4

29 46 37 37

13 19 14 14

13+.25M 19+.17M 14+.12M 14+.09M

161

4.1-35

TABLE 36

SUMMARY OF EXECUTION TIMES FOR THE EiSPACK SUBROUTINES ~CLUDED IN THE PATHS THAT




N=20 N=40 N=60 N=80

Time Unit (Sec)

TRED i TRED2 TRED3 TRBAKI TRBA-K3


°033 .21 .63 1.4

1 1 i 1 1.9 2.1 2.1 2.1 1.8 1.6 1.7 1.7 1.7 1.8 1.8 1.9 2.0 2.1 2.2 2.3

2.9 3.1 3.3 3.4 3.5 3.5 3.7 3.9 3.7 4.5 4.8 5.1 4.2 4.9 5.3 5.6

FIGi FiGI2 BAKVEC

TQL2 IMTQL2

TQLRAT TQLI IMTQL 1


TINVIT TSTURM

- - .02 °02

- - - ~02

4.4 4.3 4.2 4.2 4.6 4.8 4.8 4.5

.90 .39 .29 .21 1.2 .84 .60 °44 1.7 .92 .70 .53

12 6.8 4.9 3.8 12 6.8 4.8 3.8 2.3 I.I °79 .59 3.6 2.5 1.9 1.5

i.i .64 .51 .47 13 7.6 5.5 4.3

PATHS

RS (TRED2,TQL2) RS (TREDI, TQLRAT) TREDIgBISECT~TINV!T,T~AKI TREDI,BISECT

CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,T!NVlT,HTRIBK HTRIDI,BISECT

6.5 6.3 6.3 6.3 2.0 1.5 1.3 1.2

i+. 73M i+. 23M I+. 12M l+. 08M i+. 59M i+. 17M i+. 08M i+. 05M

Ii 12 12 13 3.8 3.6 3.5 3.6

2.9+.83M 3.1+.30M 3.3+.17M 3.4+.12M 2.9+.59M 3.1+.17M 3.3+.08M 3.4+.05M

162

4.1-36

TABLE 37



MACHINE: Honeywell 6070 Fortran-Y(SR-F) Optimized BELL LABORATORIES

SUBROUTINE

Time Unit (Sec)

CBAL CBABK2

COMHES COMBAK

CORTH CORTB

COMQR2 COMLR2

COMQR COMLR

CINVIT

ORDER OF MATRIX

N=I0 N=20 N=40 N=60 N=80

.041 .31 2.5 8.6 20

.16 .07 .03 .'02 .02

.07 .03 .01 .01 .01

i i i 1 1 .46 .54 .56 .55 .55

2.4 2.5 2.6 2.5 2.5 I.i i.i 1.2 I.i i.I

14 13 ii U ii 8.2 6.7 5.7 5.7 5.4

6.2 4.7 3.7 3.5 3.4 4.5 2.9 2.1 2.0 1.8

4.3 3.1 2.4 2,3 2.2

PATHS



CBAL,CORTH,COMQR, CINVIT, CORTB,CBABK2

17 15 14 14 13

8.8 7.3 6.3 6.0 6.0

8.7+.54M 7.3+.22M 6.3+.09M 6.1+.06M 5.9+.04M

163

4.1-37

TABLE 38




SUBROUTINE

Time Unit (Sac)

BALANC BALBAK


0RTHES ORTRAN ORTBAK

HQR2

HQR

INVlT

ORDER OF MATRIX

N=I0 N=20 N=40 N=60 N=80

.009 .070 .54 1.8 4.3

.32 .12 .06 .04 .03

. 15 .06 °03 .02 .01

i 1 1 i i . 16 .07 .03 .02 .01

~52 .54 .56 .56 .56

2.9 3.0 3.1 3.1 3.1 .86 .81 .80 .79 .79

1.2 1.2 1.2 1.2 I~2

15 12 I i i0 i0

8.6 6.1 4.3 3.9 3.5

4.6 3.6 3.0 2.7 2.6

PATHS

RG (BALANC, ELMI~ S, ELTRAN, HQR2, BALBAK)

RG (BALANC,ELMHES ,HQR)

BALANC, ELMHES, HQR, INVIT, ELMBAK ~ BALBAK

16 14 12 ii II

i0 7.2 5.4 5.0 4.5

I0+.53M 7.2+.21M 5.4+.09M 5.0+.05M 4.5+.04M

4.1-38

TABLE 39





N=IO N=20 N=40 N=60 N=80

Time Unit (Sec) .013 .078 .53 1.6 3.6


1 1 1 1 1 1.4 1.8 1.9 2.0 2.0 I.i 1.2 1.2 1.2 1.3 .87 i.i 1.3 1.4 1.4

1.0 1.3 1.5 1.6 1.6


2.6 3.0 3.3 3.4 3.5 2.7 3.1 3.5 3.6 3.7 2.9 3.8 4.5 4.7 4.9 2.9 3.8 4.5 4.8 4.9

FIGI FIGI2 BAKVEC

.i0 .03 .01 .00 .00

.14 .05 .02 .01 .01

.12 .06 .03 .02 .02

TQL2 IMTQL2

4.1 4.4 4.2 4.3 4.2 4.2 4.6 4.6 4.6 4.6

TQLRAT TQLI IMTQLI

I.i .60 .29 .21 .15 1.7 i.I .59 .42 .32 1.8 1.2 .65 .46 .34


5.2 3.1 1.6 i.i .84 5.3 3.2 1.6 I.i .81 1.9 i.i .65 .45 .35 3.0 2.1 1.4 1.0 .82

TINVIT TSTURM

1.0 .67 .39 .31 .33 6.2 3.9 2.0 1.4 1.2

PATHS


5.5 6.4 6.0 6.4 6.2 2.0 1.6 1.3 1.2 i.i

i+. 7 IM i+. 24M i+. 08M I+. 05M i+. 03M I+. 52M i+. 15M i+. 04M i+. 02M i+. OIM

CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,TINVIT,HTRIBK HTRIDI,BISECT

9.9 ii 12 12 13 3.7 3.6 3.6 3.6 3.6

2.6+.91M 3.0+.38M 3.3+.16M 3.4+.IOM 3.5+.08M 2.6+.52M 3.Ot.15M 3.3+.04M 3.4+.02M 3.5+.01M

165

4.1-39

TABLE 40



MACHINE: Univac iii0, Fortran V(9) Compiler THE UNIVERSITY OF WISCONSIN

SUBROUTINE

Time Unit (Sec)

CBAL CBABK2

COMHES COMBAK

CORTH CORTB

COMQR2 COMLR2

COMQR COMLR

CINVIT

ORDER OF MATRIX

N=I0 N=20 N=40 N=60 N=80

°025 .18 1.3 4.4 I0

. 16 .08 .04 .02 .02

.08 .03 .01 .01 ~01

1 1 1 1 1 .48 .53 .57 .58 °58

2.3 2.6 2.8 2.8 2.9 1.0 I.i i.i 1.2 1.2

13 12 ii ii II 9.4 7.5 6.3 6.3 6.1

6.2 4.8 3.9 3.9 3.6 5.5 3.6 2.5 2.4 2.2

4.7 3.4 2.7 2.4 2,3

PATHS

CG (CBAL,CORTH, COMQR2,CBABK2)



16 15 14 14 14

8.7 7.4 6.7 6.7 6.5

8.7+.58M 7.4+.23M 6.7+.IOM 6.7+.06M 6.6+.04M

166

4.1-40

TABLE 41



MACHINE: Univac IIi0, Fortran V(9) Compiler THE UNIVERSITY OF WISCONSIN

SUBROUTINE

Time Unit (Sec)

BALANC BALBAK

ELMI{ES ELTRAN ELM~AK


HQR2

HQR

INVIT

ORDER OF MATRIX

N=I0 N=20 N=40 N=60 N=80

.009 .062 .45 1.5 3.4

.39 .17 .08 .05 .04

.Ii .05 .02 .02 .01

1 i 1 1 1 .16 .08 .03 .02 .02 .54 .57 .58 .59 .59

3.2 3.6 3.8 4.0 4.0 .72 .74 .76 .77 .78

1.1 1.1 1.2 1.2 1.2

15 13 Ii ii ii

8.5 6.3 4.7 4.3 3.9

5.6 4.6 4.0 3.8 3.7

PATHS




L6 14 13 12 12

9.9 7.5 5.8 5.4 4.9

9.9+.63M 7.5+.26M 5.8+.12M 5.4+.07M 4.9+.05M

167

4.1-41

TABLE 42

S~RY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT


MACHINE: Un±vac Iii0, Fortran V(9) Compiler THE UNIVERSITY OF WISCONSIN

SUBROUTINE

ORDER OF MATRIX N=I0 N=20 N=40 N=60 N=80

Time Unit (Sec) .012 .065 .40 1.2 2.7


! 1 i 1 1 1.5 1.7 1.9 1.9 2.0 1.3 1.7 2.0 2.2 2.3 .81 I.I 1.3 1.4 1.5

1.4 2.0 2.5 2.7 2.9


2.3 2.5 2.7 2.9 2.9 2.1 2.4 2.7 2.8 2.9 2.2 3.0 3.8 4.1 4.3 2.2 3.1 3.8 4.1 4.3

FIGI FIGI2 BAKVEC

,08 .02 .01 ,00 .00 ,09 ,04 ,02 .01 .01 .08 °05 ,03 .02 .01

TQL2 IMTQL2

TQLRAT TQLI IMTQLI


TINVIT TSTURM

3.4 3.8 4.0 4.1 4.2 3.6 4.0 4.4 4.4 4.3

.99 .63 .36 .26 .19 1.4 .96 .58 .41 .31 1.5 1.0 .64 .45 ,34

6.3 3.9 2.2 1.6 1.2 6.2 3.8 2.2 1.5 I.I 1.6 i. i .67 .47 .35 3.3 2.7 1.8 1.4 1.2

1.2 .82 .51 .39 .38 7.4 4.6 2.7 1.9 !.6

PATHS

RS (TRED2,TQL2) RS (TREDI,TQLRAT) TREDI,BISECT,TINVIT,TRBAKI

TREDI,BISECT


4.9 5.5 5.8 6.0 6.2 2.0 1.6 1.4 1.2 1.2

I+. 83M i+. 29M i+. IOM i+. 06M i+. 04M I+. 63M i+. 19M i+. 06M I+. 03M i+. OIM

8.1 9.3 Ii Ii Ii 3.3 3.1 3.1 3.1 3.1

2.3+.97M 2.5+.39M 2.7+.16M 2.9+.IOM 2.9+,07M 2.3+.63M 2.5+,19M 2.7+.06M 2.9+.03M 2.9+.01M

168

4.1-42

TABLE 43



MACHINE: DEC PDP-10, F40 Compiler YALE UNIVERSITY

SUBROUTINE

Time Unit (Sec)

CBAL CBABK2

COMHES COMBAK

CORTH CORTB

COMQR2 COMLR2

COMQR COMLR

CINVlT

ORDER OF MATRIX

N=I0 N=20 N=30 N=40

.29 2.4 8.3 20

.16 .07 .05 .04

.05 .03 .01 .01

i 1 i 1 • 57 .57 .58 .59

2.0 1.9 2.0 2.0 I.I I.i I.I i.i

13 ii ii ii 8.8 7.6 7.2 6.7

5.1 3.7 3.4 3.2 4.3 3.1 2.6 2.3

3.4 2.7 2.6 2.5

PATHS




15 13 13 13

7.2 5.7 5.4 5.2

7.2+.46M 5.7+.19M 5.4+.12M 5.2+.09M

169

4.1-43

TABLE 44




SUBROUTINE

Time Unit (Sec)

BALA_NC BALBAK

ELegIES ELTRAN EI/iBAK


HQR2

HQR

INVIT

ORDER OF MATRIX

N=I0 N=20 N=30 N=40

.i0 .80 2.7 6°2

~27 . 12 ,08 .06 .12 °04 .03 .02

I I 1 i ,21 .08 ,06 .04 °54 ,58 ,59 .59

1.8 1.9 1.9 1.9 .75 .73 .73 .72

i.i i.i i.i I.i

12 ii 9.9 9.7

6.7 5.0 4.1 3.8

3.5 2.9 2.7 2.6

PATHS

RG (BALANC~ELMHES~ELTRAN, HQR2,BALBAK)


BALANC, ELMIIE S, HQR, INVIT, EI2LBAK, BALBAK

14 12 ii II

7.9 6.2 5.2 4.9

8.0+.42M 6.2+.17M 5.2+.IIM 4.9+.08M

170

4.1-44

TABLE 45




SUBROUTINE

Time Unit (Sec)


N=I0 ORDER OF MATRIX

N=20 N=30 N=40

.i0 .64 2.0 4.7

1 1 i 1 1.8 2.0 2.0 2.1 .85 .87 .88 .88

1.2 1.5 1.6 1.7 i.i 1.4 1.5 1.5


3.2 3.6 3.7 3.8 2.6 3.1 3.2 3.3 4.4 5.5 5.9 6.2 4.4 5.5 5.9 6.2

FIGi FIGI2 BAKVEC

TQL2 IMTQL2

TQLRAT TQLI IMTQLI


TINVIT TSTURM

PATHS

.09 .01 .01 .01

.09 .05 .03 .02

.12 .07 .04 .03

3.7 4.2 4.1 4.0 3.9 4.5 4.2 4.3

.73 .42 .26 .20 1.0 .65 .42 .33 i.i .75 .48 .39

3.9 2.1 1.4 1.0 3.9 2.1 1.3 .99 1.2 .79 .51 .41 2.1 1.4 i.i .87

1.2 .70 .50 .39 5.0 2.8 1.8 1.4

RS (TRED2,TQL2) RS (TREDI,TQLRAT) TREDI,BISECT~TINVIT,TRBAKI TREDI~BISECT

CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI~BISECT~TINVIT~HTRIBK HTRIDI,BISECT

5.5 6.2 6.2 6.1 1.8 1.4 1.3 1.2

i+. 62M I+. 22M i+. 12M i+. 08M i+. 39M 1+. IOM I+. 05M i+. 03M

12 13 14 14 3.9 4.0 4.0 4.0

3.2+.94M 3.6+.41M 3.7+.26M 3.8+.19M 3.2+.39M 3.6+.IOM 3.7+.05M 3.8+.03M

171

4.1-45

TABLE 46



MACHINE: Amdahl 470V/6, Fortran H, OPT=2 UNIVERSITY OF MICHIGAN

SUBROUTINE

Time Unit (Sec)

CBAL CBABK2

COMHES COMBAK

CORTH CORTB

COMQR2 COMLR2

COMQR COMLR

CINVIT

ORDER OF MATRIX

N=I0 N=20 N=40 N=60 N=80

.005 .040 .33 i. 1 2.8

.12 .05 .02 .01 .01

.07 .03 .02 .01 .01

1 1 i I i .46 .50 .54 .58 .60

2.4 2.3 2.2 2.2 2.1 1.3 1.3 1.2 1.2 i.i

18 15 13 13 12 9.4 8.1 6.7 6.5 6.2

8.0 5.7 4.5 4.2 3.9 5.1 3.4 2.4 2.2 2.0

4.8 3.3 2.5 2.2 2.3

PATHS




20

ii

II+.62M

18 16 15 14

8.1 6.7 6.4 6.0

8.1+.23M 6.7+.09M 6.4+.06M 6.0+.04M

172

4.1-46

TABLE 47



MACHINE: Amdahl 470~/6, Fortran H, OPT=2 UNIVERSITY OF MICHIGAN

SUBROUTINE

Time Unit (Sec)

BALANC BALBAK



HQR2

HQR

INVlT

ORDER OF MATRIX

N=I0 N=20 N=40 N=60 N=80

.002 .014 .12 .41 .98

.24 .09 .04 .02 .02

.12 .05 .02 .02 .01

1 1 1 i I .16 .07 .03 .02 .02 .54 .57 .57 .58 .59

2.4 2.2 2.1 2.0 1.9 .81 .71 .65 .62 .60

1.2 I.i .98 .93 .90

20 16 12 12 II

12 7.7 5.2 4.5 3.9

4.5 3.4 2.7 2.4 2.3

PATHS



BALANC, ELMHES, HQR, INVIT, ELMBAK~ BALBAK

21

13

13+.51M

17 14 13 12

8.8 6.2 5.5 4.9

8.8+.20M 6.3+.08M 5.5+.05M 5.0+.04M

173

4.1-47

TABLE 48



MACHINE: Amdahl 470V/6, Fortran H, OPT=2 UNIVERSITY OF MICHIGAN

SUBROUTINE

Time Unit (Sec)


N=IO ORDER OF MATRIX

N=20 N=40 N=60 N=80

.002 .013 .090 ,29 °70

i 1 i 1 i 1.6 1.8 2.0 2.0 2.0 .99 .98 1.0 .98 .96

1.2 1.4 1.6 1.6 1.6 1.0 1.2 1.4 1.4 1.4


2.7 3.1 3.4 3.6 3.7 2.6 3.1 3.4 3.6 3.6 3.3 4.4 5.1 5.4 5.5 3.5 4.6 5.3 5.5 5.5

FIGI FiGI2 BAKVEC

TQL2 IMTQL2

TQLRAT TQLI IMTQLI


TINVIT TSTURM

• 09 .03 .01 .00 .00 .15 ,06 .03 .02 .01 .I0 .06 .03 .02 .02

4.9 5.3 5.1 5.0 4.6 5.0 5.2 5.3 5.0 4.8

1.4 .81 .42 .27 . 19 2.3 1.5 .86 .57 .42 2.3 1.5 .88 .58 .43

ii 6.8 3.7 2.5 1.8 Ii 7.0 3.8 2.6 1.9 2.4 1.6 .89 .59 .43 3.4 2.6 1.7 1.2 .93

1.0 .67 .40 .29 .30 12 7.5 4.2 2.9 2.2

PATHS



6.5 7.1 7.1 7.0 6.7 2.4 1.8 1.4 1.3 1.2 I+i. 3M I+. 44M I+. 14M i+. 07M I+. 05M I+ i. IM I+ . 34M I+. 09M i+. 04M I+ . 02M

ii 12 13 14 14 4.2 3.9 3.8 3.9 3.9

2.7+1.5M 3.1+.59M 3.4+.23M 3.6+.14M 3.7+.IOM 2.7+I.IM 3.1+.34M 3.4+.09M 3.6+.04M 3.7+.02M

174

4.1-48

TABLE 49

EXECUTION TIMES FOR SELECTED EISPACK DRIVER SUBROUTINES OVER VARIOUS COMPUTER SYSTEMS MEASVRED ON MATRICES OF ORDER 40

BOTH WITH EIGENVECTOR~ COMPUTED (I) AND WITHOUT (0)

MACHINE

Time Unit (Sec)

IBM 370/195 (ARGONNE NATIONAL LABORATORY)

IBM 360/75 (UNIVERSITY OF ILLINOIS)

IBM 370/168 (UNIVERSITY OF MICHIGAN)

IBM 370/165 (THE UNIVERSITY OF TORONTO)

CG(1) CG(O) RG(1) RG(O) RS(1) RS(O) CH(1)CH(~)

1.7 .77 .66 .31 .22 .055 .44 .14

i i 1 i 1 1 i 1

16 15 ii Ii 15 12 13 12

5.8 5.2 3.9 3.7 5.6 3.9 5.0 4.5

3.5 3.2 2.9 2.6 3.3 2.9 3.2 2.9

BURROUGHS 6700 118 108 95 92 125 82 122 i00 (UNIVERSITY OF CALIFORNIA,

SAN DIEGO) CDC 6600 5.0 5.3 4.9 4.9 5.5 5.0 3.7 3.0 (KIRTLAND AIR FORCE BASE)

CDC 6600 (NASA LANGLEY RESEARCH CENTER)

4.5 4.3 5.5 5.6 5.3 5.0 4.2 3.8

CDC 7600 i.i 1.0 1.2 I.i 1.0 I.i .81 .83 (NATIONAL CENTER FOR ATMOSPHERIC

RESEARCH) CDC 6400 22 22 19 18 21 18 17 17 (NORTHWESTERN UNIVERSITY)

CDC 6400/6500 (PURDUE UNIVERSITY)

CDC 6600/6400 (THE UNIVERSITY OF TEXAS)

HONEYWELL 6070 (BELL LABORATORIES)

UNIVAC III0 (THE UNIVERSITY OF WISCONSIN)

DEC PDP-IO (YALE UNIVERSITY)

AMDAHL 470V/6 (UNIVERSITY OF MICHIGAN)

31 32 42 38 24 20 22 21

8.2 8.9 17 15 6.1 5.9 5.6 5.6

21 20 9.9 9.4 15 13 14 14

Ii II 8.9 8.4 ii ii 9.8 9.2

155 135 104 98 132 106 146 139

3.1 2.9 2.4 2.3 2.9 2.4 2.7 2.6

175

PROBLEM CLASS

CG

CG

CG

CG

RG

RG

RG

RG

4.1-49

TABLE 50

SUMMARY OF EXECUTION TIMES FOR SELECTED PROBLEMS USING THE EISPAC CONTROL PROGRAM


Time Unit: 1 second

EIGEN- EIGEN- TRANSFOR- VALUES VECTORS MATIONS

All All Unitary

All Some(M=N) Unitary

All All Elementary

All Some(M=N) Elementary

All All Elementary

All Some(M=N) Elementary

All All Orthogonal

All Some(M=N) Orthogonal

ORDER OF MATRIX

N=I0 N=20 N=40 N=60 N=80

RS All All

RS All None

RS Some(M=N) Some(M=N)

RS Some(M=N) None

.044 .25 1.7 5.7 13

.047 .22 1.3 4.2 9.6

.032 .16 1.0 3.3 7.6

.041 .17 ,92 2.7 6.7

CH All All

CH All None

CH Some(M=N) Some(M=N)

CH Some(M=N) None

.023 .i0 .63 2.0 4.5

.024 .095 .51 1.5 3.4

.026 .12 .72 2.3 5.2

,026 .i0 .59 1.8 4.0

,011 ,040 .22 .65 1.5

,007 .016 .059 .15 .33

,025 .080 .33 ,81 1.6

.022 .066 .24 .56 1.0

.016 .07 .44 1.4 3.4

.009 .026 .14 .42 1.0

.029 .ii .52 1.5 3.3

.023 .08 .33 .83 1.8

176

4.2-1

Section 4.2

REPEATABILITY AND RELIABILITY OF THE MEASURED EXECUTION TIMES

In the multi-program environment of modern computers, it is often

very difficult to reliably measure the execution time of a program. Sig-

nificant variations can occur depending on the load on the machine and

the amount of I/O interference. For the EISPACK subroutines in particular,

allowance has to be made also for the dependence of execution times upon

the matrix (see Section 4.3).

Towards improving the usefulness of the timing information for the

various machines, each subroutine was run a number of times on different

matrices and the average time reported. Also, the timing programs were

structured to perform no output until all the timings had been collected.

For the most part, the timing routines used to measure execution time

factor out external interrupts which may occur. The reported times, there-

fore, although not to be interpreted as absolute bounds, should be useful

in giving a feeling for the execution time required by the individual

subroutines or paths.

177

4.3-1

Section 4.3

DEPENDENCE OF THE EXECUTION TIMES UPON THE MATRIX

To characterize the dependence of the execution times of the EISPACK

subroutines upon the matrix, it is helpful to divide the subroutines into

three categories: first, the non-iterative reduction and back transforma-

tion subroutines; second, the iterative reduced-form eigenvalue-eigenvector

subroutines; and third, the semi-iterative subroutines which balance a

mmtrix and back transform the eigenvectors of the balanced matrix.

For the first category of subroutines, the execution times for all

non-sparse matrices of a given order are approximately constant, close to

those given in the tables of Section 4.1. For sparse matrices, some of

the reduction transformations may be skipped and the arithmetic unit may

consume less time to manipulate the many zero operands; however, except

for special sparse matrices, the decrease in execution time of these sub-

routines is marginal.

For the second category of subroutines, their execution times depend

greatly upon the structure of the input matrix (e.g., diagonally dominant,

blocked, sparse), the closeness of the eigenvalues, and the defectiveness

of the matrix. Based upon our experiments on the IBM 370/195, random

matrices tend to produce slower execution of category two subroutines, and

therefore the execution times given in the tables of Section 4.1 appear

to be near the maximum for these subroutines.

For the third category of subroutines, their execution times are

somewhat variable but, in general, are negligible compared with the execu-

tion times of paths in which they are included. For example, the algorithms

BALANC and BALBAK together require about 0.3% of the execution time in the

path BALANC-ELMHES-ELTRAN-HQR2-BALBAK used to find the complete eigensystem

178

4.3-2

of the order 80 real general matrix of Table 5, and CBAL and CBABK2 together

require an even smaller percentage of the time for the corresponding complex

matrix of Table 4. In contrast, we have contrived a matrix for which the

combination of BALANC and BALBAK requires 7% of the normal path time, but

this matrix represents an extreme case. More commonly, the execution

times for these subroutines are only a few percent of the total path times.

179

4.4-I

Section 4.4

EXTRAPOLATION OF TIMING RESULTS TO OTHER MACHINES AND COMPILERS

The extrapolation of timing results to other machines and compilers

may appear straightforward but can be grossly inaccurate if characteris-

tics of the particular machines and compilers are not carefully considered.

To illustrate this point, we make two comparisons: first, the execution

times of EISPACK on an IBM 360/75 and 370/195, and second, the execution

times of EISPACK compiled with the CDC 6600 Fortran RUN and FTN, OPT=I

compilers.

The eigensystems of several random matrices of order 80 were determined

using identical object modules on the IBM 360/75 and 370/195. The ratios

of the IBM 360/75 times to the 370/195 times show large variations from

subroutine to subroutine (compare Tables 4-6 with Tables 7-9). Many of

the ratios are between ii and 14, but at opposite extremes the ratio for

BISECT is 6.7 whereas for TQL2, 19.4.

These large variations in the ratios of execution times among the sub-

routines are attributable to the special architecture of the IBM 370/195;

namely, the buffered or two-level memory, the pipe line or parallel arith-

metic units, and the instruction stack. Some of the EISPACK subroutines

are able to take advantage of these special features of the 370/195 better

than others.

The compiler can also affect the relative efficiencies of EISPACK

subroutines. On two comparable CDC 6600 computers, one employing the

RUN compiler and the other the FTN, OPT=I compiler, the ratios of the

execution times for the EISPACK subroutines were determined (compare

Tables 22-24 with Tables 34-36). Many of the ratios are close to i, but

extremes as large as 2.2 for INVIT, 2.7 for HQR, and 3.0 for HQR2 obtain

180

4.4-2

for real general matrices of order 60.

It is clear from these examples that the relative efficiency of an

algorithm can be very machine and compiler dependent, and hence that the

extrapolation of our timing results to other systems must necessarily

include these nonsiderations.

181

4.5-1

Section 4.5

THE SAMPLE MATRICES FOR THE TIMING RESULTS

In this section, Fortran listings of the program segments which generate

the sample matrices for the timing results are provided. The matrix elements

are pseudo-random integers sampled from a uniform distribution on the inter-

val (-215,+215). A listing of the auxiliary subroutine RANDOM which generates

the random integers is also provided.

482

4.5-2

I0 20

COMPLEX GENERAL MATRIX

DO 20 I = I,N DO i0 d = I,N

CALL RANDOM (INIT, AR(I,J)) CALL RANDOM (INIT, AI(I,J))

CONTINUE CONTINUE

10 20 30

COMPLEX HERMITIAN MATRIX

IF (N .EQ. 1) GO TO 30 DO 20 I = 2,N

CALL RANDOM (INIT, AR(I-Ij I-l)) AI(I-I,I-1) = 0.0 DO 10 J = I,N

CALL RANDOM (INIT, AR(I-I,J)) AR(J, I-1) = AR(I-1,J) CALL RANDOM (INIT, AI(I-1,J)) AI(J,I-1) = -AI(I-1,J)

CONT I NUE CONT I NUE CALL RANDOM (INIT, AR(N,N)) AI(N,N) = 0.0

i0 20

COMPLEX HERMITIAN PACKED MATRIX

DO 20 i = I,N DO i0 d = I,N

CALL RANDOM (INIT, A(I,J)) CONTINUE

CONTINUE

C C

10 20

REAL GENERAL MATRIX

DO20 I = I,N DO I0 J = I,N

CALL RANDOM (INIT, A(I,J)) CONTINUE

CONT I NUE

REAL SYMMETRIC MATRIX

I0 20

DO20 I= I,N DO i0 a = I,N

CALL RANDOM (INIT, A(I,J)) A ( J , I ) = A ( I , J )

CONT I NUE CONT I NUE

183

4.5-3

REAL SYMMETRIC PACKED MATRIX

10

NNN = N*(N+I)/2 DO I0 I = I,NNN

CALL RANDOM (INIT, A(1)) CONTINUE

10 20 30

REAL SYMMETRIC TRIDIAGONAL MATRIX

CALL RANDOM (INIT, A(I,2)) IF (N .EQ. 1) GO TO 30 DO 20 I = 2,N

DO 10 J = 1,2 CALL RANDOM (INIT, A(I,J))

CONTINUE CONTINUE CONTINUE

SPECIAL REAL NON-SYMMETRIC TRIDIAGONAL MATRIX

DO 20 I = I,N DO I0 J = 1,3

CALL RANDOM (INIT, A(I,J)) 10 CONTINUE 20 CONTINUE

IF (N .EQ. i) GO TO 40 DO 30 I = 2,N

A( I , 1 ) = SIGN(A(I,1), A ( I - 1 , 3 ) ) 30 CONTINUE 40 CONTINUE

Subroutine R~NDOM:

SUBROUTINE RANDOM (INIT, X) REAL X INIT = MOD(3125*INIT, 65536) X = INIT - 32768 RETURN END

Subroutine RANDOM produces pseudo-random integer elements X

between -215 and 215 from a starting integer INIT. It was designed

so that it could be implemented in Fortran and would produce the same

set of pseudo-random numbers on different machines. As a result it

has some shortcomings as a random number generator, including a rather

short period of 214 numbers.

184

5.0-I

Section 5

CERTIFICATION ;aND AVAII~ILITY OF EISPACK

Under the auspices of the NATS Project, the subroutines constituting

Release 2 of EISPACK have been tested on and are certified for the follow-

ing computer systems and working precisions (test site names are indicated

in parentheses):

WORKING MACHINE OPERATING SYSTEM COMPILER PRECISION

IBM 370/195

IBM 360/75

IBM 370/168

IBM 360/75

IBM 370/165

BURROUGHS 6700

CDC 6600

CDC 6600

CDC 7600

CDC 6400

CDC 6400/6500

CDC 6600/6400

HONEYWELL 6070

UNIVAC Iii0

DEC PDP-IO

0S/360 (21.7) FTN IV G,H(21.7),WATFIV LONG (ARGONNE NATIONAL LABORATORY)

0S/360 (21.7) FTN IV H(21.7) LONG (UNIVERSITY OF ILLINOIS AT URBANA-CHAMPAIGN)

MTS FTN IV G,H LONG (UNIVERSITY OF MICHIGAN)

OS/360 (21.7) FTN IV H EXTENDED(2.1) LONG (STOCKHOLM DATA CENTER)

0S/360 (21.7) FTN IV H EXTENDED(2.1) LONG (THE UNIVERSITY OF TORONTO)

MCP 2.6 FORTRAN IV(2.6) SINGLE (UNIVERSITY OF CALIFORNIA, SAN DIEGO)

SCOPE 3.4.2 FTN(4.2) SINGLE (KIRTLAND AIR FORCE BASE/AF~rL)

KRONOS 2.1 RUN(2.3) SINGLE (ICASE/NASA LANGLEY RESEARCH CENTER)

(LOCAL) (LOCAL) SINGLE (NATIONAL CENTER FOR ATMOSPHERIC RESEARCH)

SCOPE 3.3 RUN(2.3) ,FTN(3.0) SINGLE (NORTHWESTERN UNIVERSITY)

(LOCAL) FUN SINGLE (PURDUE UNIVERSITY)

UT2D-85 RUN (60.2), MNF, RUh~/ SINGLE (THE UNIVERSITY OF TEXAS AT AUSTIN)

GECOS SR-F FORTRAN-Y (SR-F) SINGLE (BELL LABORATORIES AT MURRAY HILL)

EXEC-8 (31. 244) FORTRAN V(9) SINGLE (THE UNIVERSITY OF WISCONSIN)

TOPS-10 (506B) FORTRAN F40 SINGLE (YALE UNIVERSITY)

185

5.0-2

The control program EISPAC has been tested on and is certified for

the IBM systems at Argonne~ Illinois, Stockholm, and Toronto listed above.

Additional testing of EISPACK was carried out at Stanford University,

Harvard University, and on the Amdahl 470V/6 machine at University of

Michigan.

Certification implies the full support of the NATS project in the

sense that reports of poor or incorrect performance on at least the computer

system~ listed above will be examined and any necessary corrections made.

This support holds only when the software is obtained through the channels

indicated below and has not been modified; it will continue to hold through-

out the useful life of EISPACK or until, in the estimation of the developers,

the package is superseded or incorporated into other supported, widely-

available program libraries. The following individual serves as a contact

for information about EISPACK~ accepting reports from users concerning

performance:

Burton S. Garbow Applied Mathematics Division Argonne National Laboratory Argonne, Illinois 60439 U.S.A. Phone: 312-739-7711 x4342

EISPACK is distributed from the Argonne Code Center. Versions exist

for IBM 360-370, CDC 6000-7000, Univac iii0, Honeywell 6070, DEC PDP-IO,

and Burroughs 6700 machines~ Fortran source decks, documentation, and

testing aids will be transmitted as card images on a tape supplied by the

requester. The tape should have a rating of at least 800 bpi and be a

full 2400 feet long. The requester should specify the desired machine

version. The tape should be mailed to:

Argonne Code Center Bldg. 221 Argonne National Laboratory Argonne, Illinois 60439 U.S.A.

186

5.0-3

The tape will be returned parcel post unless the Code Center is requested

otherwise. It will be returned by air mail collect if the Code Center is

so authorized in writing and the postal service procedures permit such

shipment.

Certain international agreements pertain to the distribution of EISPACK

outside the United States by the Argonne Code Center. Information concern-

ing such distribution may be obtained from the Code Center.

187

6.0-!

Section 6

DIFFERENCES BETWEEN THE EISPACK SUBROUTINES AND THE HANDBOOK ALGOL PROCEDURES

This section describes, subroutine by subroutine, the major differ-

ences between the EiSPACK subroutines and their Algol antecedents in the

Handbook [I]. These differences fall into four categories: I) correction

of several errors, 2) minor algorithmic improvements, 3) changes based on

consideration of Fortran language efficiency, and finally, 4) changes to

better unify the individual programs into a package.

Some of the changes apply to EISPACK as a whole.

i) The base B of the floating point representation on the machine and

the machine precision MACHEP have become internally set variables in the

Fortran programs rather than parameters.

2) The orthogonaiity threshold parameter TOL has been removed from

the Householder reduction subroutines by substituting the alternate scaling

technique discussed in the "Organisational and Notational Details" section

of the Handbook, Contribution 11/2, p. 221.

3) The procedure CDIV called to perform complex division in the

Handbook procedures has been replaced by ordinary division operations with

complex-mode Fortran operands. The procedures CABS and CSQRT called to

perform complex modulus and complex square-root operations have been

replaced by references to corresponding members of the Fortran library

which use complex-mode operands.

4) The Handbook procedure-calls for row interchange in the balancing

process, for determination of Sturm counts in the bisection process, and

for selection of new trial vectors in the inverse iteration process have

been replaced by in-line Fortran coding.

] 88

6.0-2

Specific changes to individual members of EISPACK are as follows.

BALANC - IGH=I rather than IGH=0 is returned when the matrix can be per-

muted to triangular form; IGH is used as an array declarator

subscript in other subroutines and must not be "0".

TRED 1 - Unnecessary operations in the last reduction step that can

introduce roundoff error into the first diagonal element have

been skipped, enabling the resultant tridiagonal form to more

literally duplicate that from TRED2. Also see TRED2 below.

TRED 2 - The arithmetic operation G*(Z/H) is computed instead as (G/H)*Z,

enabling the resultant tridiagonal form to more literally dupli-

cate that from TREDI. The tridiagonal forms from TREDI and TRED2

are now identical (on most machines) except possibly for the sign

of the first subdiagonal element. This property in turn ensures

that TQLI and TQL2, or IMTQLI and IMTQL2, produce identical

eigenvalues in most cases.

TRED3 - As for TREDI.

TRBAKI - Instead of back transforming eigenvectors M1 through M2 as is

done in the Handbook, TRBAKI transforms eigenvectors i through

M. (The MI, M2 form of specification would be more natural if

subroutine BISECT were patterned after the Handbook BISECT

rather than the Handbook TSTURM.)

TRBAK3 - As for TRBAKI.

HQR - Provision for recognition of balancing parameters LOW and IGH

has been made. Also see HQR2 below.

189

6.0-3

HQR2 - Roots of a quadratic equation with discriminant zero are now

classified as real rather than complex as in the Handbook. This

change corrects an error which may otherwise be made in deter-

mining the corresponding eigenvectors. For consistency the

change has been made to HQR also.

- The last component of complex vectors of the reduced form is

initialized to (0,i) rather than (I,0), rendering the vector

matrix of the reduced form strictly triangular and thereby

simplifying the final transformation to the eigenvectors of the

original matrix.

INVIT - The complex eigenvector corresponding to either member of a pair

of conjugate complex eigenvalues may be obtained, not just the

one corresponding to the value with positive imaginary part.

However, if both are requested, only the eigenvector corresponding

to the eigenvalue with positive imaginary part is computed.

- The eigenvector growth requirement has been relaxed by a factor

of !0, reducing the number of convergence failures.

TSTURM - Small subdiagonal entries of the tridiagonal form are treated as

zeros in the computation but are not replaced by zeros in storage.

The subdiagonal array is required in TRBAKI and modification of

any of its elements by TSTURM introduces errors in the back

transformation.

- The input interval (RLB,RUB) is refined making use of Gerschgorin

bounds, thereby reducing the computation time of the bisection

process.

190

6.0-4

- The logical array INT has been eliminated by making use instead

of information present in the reduced triangular form and input

subdiagonal array.

BISECT - The bisection process of TSTURM is used instead of that in the

Handbook BISECT procedure. They differ primarily in the specifi-

cation of the subset of the eigenvalues to be computed.

- The eigenvalues are strictly ordered, rather than locally

ordered within submatrices as in TSTURM; they are tagged with

their submatrix associations by use of the array IND.

TRIDIB - As for BISECT except that the bisection process of the Handbook

BISECT procedure is used.

COMLR - Provision for recognition of balancing parameters LOW and IGH

has been made.

CINVIT - The vector growth requirement has been relaxed by a factor of I0,

reducing the number of convergence failures.

RATQR - The largest as well as the smallest eigenvalues can be requested.

The specification of "NEGATIVE DEFINITE" (when proper) improves

the determination of the largest values in the same way as

uPOSITIVE DEFINITE" does the smallest.

- An error return has been provided for an incorrectly specified

definiteness parameter.

- The incidence of underflow has been markedly reduced by replace-

ment of tiny squared subdiagonal elements by zeros at each

iteration.

191

6.0-5

- The eigenvalues are tagged with their submatrix associations by

use of the array IND. A further modification that saves the

input matrix makes it possible to link RATQRwith TINVIT to

compute the corresponding eigenvectors.

A number of the EISPACK subroutines which have no Handbook antecedents

are patterned closely after existing Handbook procedures.

CBAL is a complex analogue of BALANC,

CBABK2 is a complex analogue of BALBAK,

CORTH is a complex analogue of ORTHES,

CORTB is a complex analogue of ORTBAK,

COMQR is a unitary analogue of COMLR,

COMQR2 is a unitary analogue of COMLR2,

HTRIDI is a complex analogue of TREDi,

HTRIBK is a complex analogue of TRBAKI,

HTRID3 is a complex analogue of TRED3,

HTRIB3 is a complex analogue of TRBAK3,

IMTQLV is an extension of IMTQLI that tags the eigenvalues with their

submatrix associations as in BISECT,

TQLRAT is a rational variant of TQLI, and

TINVIT is that part of TSTURMwhich determines the eigenvectors after

the eigenvalues have been found.

Subroutines FIGI, FIGI2, and BAKVEC provide the EISPACK capability for

special nonsymmetric tridiagonal matrices not present in the Handbook pro-

cedures. They may be considered analogous to TREDI, TRED2, and TRBAKI

respectively.

192

6.0-6

Finally, various minor textual changes have been nmde to render the

first of each of the following pairs of subroutines a virtual subset of

the second: (COMLR,COMLR2), (HQR,HQR2), (TQLI,TQL2), (IM~QLI,IMTQL2), and

(BISECT,TSTURM).

193

7 . 0 - i

Section 7

DOCUMENTATION AN~ SOURCE LISTINGS

This section contains the documentation and source listings for the

EISPACK subroutines and the documentation for the control program EISPAC.

The subroutines appear in alphabetical order in Section 7.1 with the

source listing for each subroutine following its document. Section 7.2

contains the document for EISPAC, but because of its size and machine

dependencies the listing is not included.

Both the subroutine documents and source listings have been system-

atically edited for this publication to eliminate duplicate text; they

therefore differ from the nmterial distributed to requesters of EISPACK.

The statement of certification of item 6 has been removed from the

individual documents and appears here in Section 5. The reference to

this publication which appears in item 4 and the brief discussian of test-

ing that appears in items 5.A and 5.C of the distributed documents have

been removed; the latter has been replaced by a pointer to the more exten-

sive discussion of testing here in Section 3.

Two modifications have been made to the subroutine listings published

here. First, ~hey have been shortened by eliminating com~ents related to

usage, calling sequence, and error exits which basically duplicate text in

the documents, Second, statements initializing variables to machine-

dependent constants, which in each distributed version of EISPACK are

completed to contain the appropriate numerical values of these constants,

appear here as

MACHEP = ?

RADIX = #

194

7.0-2

(The correct value for MACHEP is the smallest positive working precision

floating point number which, when added to 1.0 using the working precision

addition operation on your machine, gives a number larger than 1.0; that

for RADIX is the floating point constant representing the base of the

floating point arithmetic on your machine.) Appropriate values of MACHEP

and RADIX for several machines are summarized in the following table.

MACHINE MACHEP RADIX

Burroughs 6700 2.**(-37) 8.

CDC 6000 and 7000 Series 2.**(-47) 2.

DEC PDP-10 2.**(-26) 2.

Honeywell 6070 2°**(-26) 2.

Univac iii0 2.**(-26) 2.

Except for the statements initializing MACHEP and RADIX, the published

listings are ANSI Fortran. The double precision version certified for

IBM equipment employs non-standard Fortran to the extent of using REAL*8

declarations and a small amount of complex double precision arithmetic.

For this version, the appropriate values of MACHEP and RADIX are 16.D0"*(-13)

and 16.D0.

195

7.1-!

NATS PROJECT

E!GENSYSTEM SUBROUTINE PACKAGE (EISPACK)

F281-2 BAKVEC

A Fortran IV Subroutine to Back Transform the Eigenvectors of that Symmetric Tridiagonal Matrix Determined by FIGIo

May, 1972 July, 1975

I. PURPOSE

The Fortran IV subroutine BAKVEC forms the eigenvectors of a certain real non-symmetric tridiagonal matrix from the eigenvectors of that symmetric tridiagonal matrix determined by FIGI (F280).

2. USAGE.

A. Calling Sequence~

The SUBROUTINE statement is

SUBROUTINE BAKVEC(NM~N,T,E,M,Z,IERR)

The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.

NM is an integer input variable set equal to the row dimension of the two-dimensional arrays T and Z as specified in the DIMENSION statements for T and Z in the calling program°

N is an integer input variable set equal to the order of the matrix T. N must be not greater than NM.

is a working precision real input two- dimensional variable with row dimension NM and column dimension at least 3. T contains the non-symmetric tridiagonal matrix of order N in its first three columns. The subdiagonal elements are stored in the last N-I positions of the

196

7.1-2

M

IERR

first column. The diagonal elements are stored in the second column. The superdiagonal elements are stored in the first N-I positions of the third column. Elements T(I,I) and T(N,3) are arbitrary.

is a working precision real one-dimensional variable of dimension at least N. On input, the last N-I positions in this array contain the subdiagonal elements of the symmetric tridiagonal matrix. E(1) is arbitrary. Note that BAKVEC destroys E.

is an integer input variable set equal to the number of columns of Z to be back transformed.

is a working precision real two-dimensional variable with row dimension NM and column dimension at least M. On input, the first M columns of Z contain the eigenvectors to be back transformed. On output, these columns of Z contain the transformed eigenvectors. The transformed eigenvectors are not normalized.

is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.

B. Error Conditions and Returns.

If E(1) is zero but either T(I,I) or T(I-I,3) is not zero, BAKVEC terminates with IERR set to 2*N+I and with no eigenvectors back transformed. In this case, the transformation by FIGI was not a similarity transformation.

If the above error condition does not occur, IERR is set to zero.

C. Applicability and Restrictions.

This subroutine should be used in conjunction with the subroutine FIGI (F280).

197

7.1-3

3. DISCUSSION OF METHOD AND ALGORITHM.

Suppose that the non-symmetric tridiagonal matrix T has been transformed to the tridiagonal symmetric matrix P by the similarity transformation

-i F = V TV

where V is the diagonal matrix defined in FIGI (F280). Then, given an array Z of column vectors, BAKVEC computes the matrix product VZ. If the eigenvectors of F are columns of the array Z, then BAKVEC forms the eigenvectors of T in their place.

This subroutine is an implementation of the algorithm discussed in detail by Wilkinson (i).

4. REFERENCES°

i) Wilkinson, J.H., The Algebraic Eigenvalue Problem, Oxford, Clarendon Press, 335-337 (1965).

5. CHECKOUT.

A. Test Cases.

See the section discussing testing of the codes for certain real non-symmetric tridiagonal matrices.

B. Accuracy.

The accuracy of BAKVEC can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of certain real non- symmetric tridiagonal matrices. In these paths, this subroutine is numerically stable (I). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.

198

7.1-4

SUBROUTINE BAKVEC(NM,N,T,E,M,Z,IERR)

INTEGER I,J,M,N,NM,IERR REAL T(NM,3),E(N),Z(NM,M)

IERR = 0 IF (M .EQ. 0) GO TO i001 E(1) = 1 . 0

IF (N .EQ. i) GO TO i001

DO i00 1 = 2, N IF (E(1) .NEo 0.0) GO TO 80 IF (T(I,I) .NE. 0.0 .OR. T(I-I,3) .NE. 0.0) GO TO i000 E(I) = 1.0 GO TO I00

80 E(I) = E(I-I) * E(I) / r(I-l,3) 100 CONTINUE

DO 120 J = i, M

DO 120 I = 2, N Z(I,J) = Z(I,J) * E(I)

120 CONTINUE

GO TO i001 C ********** SET ERROR -- EIGENVECTORS CANNOT BE C FOUND BY THIS PROGRAM ********** i000 IERR = 2 * N + I I001 RETURN

END

199

7~i-5

NATS PROJECT

EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)

F269-2 BALANC

A Fortran IV Subroutine to Balance a Real General Matrix.

May, 1972 July, 1975

i. PURPOSE.

The Fortran IV subroutine BALANC balances a real general matrix and isolates eigenvalues whenever possible. Sums of the magnitudes of elements in corresponding rows and columns are made nearly equal by exact similarity transformations, and eigenvalues are isolated by permutation similarity transformations. Balancing reduces the 1-norm of the original matrix whenever sums of the magnitudes of elements in some row and corresponding column are markedly different, while at the same time leaving the eigenvalues unchanged. Reducing the norm in this way can improve the accuracy of the computed eigenvalues and/or eigenvectors.

2. USAGE.

Ao Calling Sequence.


SUBROUTINE BALANC(NM,N,A,LOW, IGH,SCALE)

The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification°

NM is an integer input variable set equal to the row dimension of the two-dimensional array A as specified in the DIMENSION statement for A in the calling program.

is an integer input variable set equal to the order of the matrix A. N must be not greater than NM.

200

7 .I-6

A is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. On input, A contains the matrix of order N to be balanced. On output, A contains the transformed matrix.

LOW, IGH are integer output variables indicating the boundary indices for the balanced matrix. See section 3 for the details.

SCALE is a working precision real output one- dimensional variable of dimension at least N containing information about the similarity transformations. See section 3 for the details.


None.


It is particularly advantageous to use BALANC whenever the sums of the magnitudes of elements in some row and corresponding column are quite different. Additionally, the execution time for BALANC is small compared with the execution time for the routines which determine the eigenvalues and/or eigenvectors. Hence it is recommended that BALANC be used generally.

The subroutine BALBAK (F270) should be used to retrieve the eigenvectors of the original matrix after the eigenvectors of the transformed matrix have been determined.


First BALANC determines a product P of permutation matrices such that

PAP ( T X Y )

= (0 B Z) (0 0 R)

where T and R are upper triangular matrices and B is a square matrix situated in rows and columns LOW through IGH with no zero off-diagonal rows or columns. X, Y, and Z are rectangular matrices of appropriate dimensions. The

201

7.1-7

diagonal elements of T and R are the isolated eigenvalues of A. In the exceptional case where B is empty, LOW = 1 and IGH = 0 -- however, i is returned as the output value of IGH.

Next, the subroutine BALANC determines iteratively a non- singular diagonal matrix D of order IGH-LOW+I such that

-I D BD

is a balanced matrix in the sense that the absolute sums of the magnitudes of elements in corresponding rows and columns of

-i D BD

are nearly equal° The diagonal elements of D are powers of the radix of the floating point arithmetic of the machine.

Upon completion of BALANC, the vector array SCALE contains the information about P and D necessary for BALBAK to retrieve the eigenvectors of the original matrix from the eigenvectors of the transformed matrix. The information is encoded as follows. I. The J-th and SCALE(J)-th rows and columns of the

original matrix have been permuted for J = 1,2,...,LOW-I,IGH+I,IGH+2,...,N.

2. SCALE(J) is the (J-LOW+l)-th diagonal element of D for J = LOW,LOW+I,...,IGH.

Upon completion of BALANC, the output matrix is

( T XD Y ) -I -i

( 0 D BD D Z )

( 0 0 R ).

This subroutine is a translation of the Algol procedure BALANCE written and discussed in detail by Parlett and Reinsch (I).

4. REFERENCES.

i) Parlett, B.N. and Reinsch, C., Balancing a Matrix for Calculation of Eigenvalues and Eigenvectors, Num. Math. 13,293-304 (1969). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinseh, Contribution Ii/ii, 315-326, Springer-Verlag, 1971.)

202

7.1-8

5. CHECKOUT.

A. Test Cases.

See the section discussing testing of the codes for real general matrices.

B. Accuracy.

BALANC introduces no rounding errors (on a machine with at least one guard digit) since its only arithmetic is scaling the input matrix by powers of the radix.

203

7.1-9

SUBROUTINE BALANC(NM,N,A,LOW, IGH,SCALE)

INTEGER I,J,K,L,M,N,JJ,NM,!GH,LOW, IEXC

REAL A(NM,N),SCALE(N) REAL C,F,G,R,S,B2,RADIX

REAL ABS

LOGICAL NOCONV

********** RADIX IS A MACHINE DEPENDENT PARAMETER SPECIFYING THE BASE OF THE MACHINE FLOATING POINT REPRESENTATION.

RADIX = #

B2 = RADIX * RADIX

K = 1

L = N GO TO i00 • ********* IN-LINE PROCEDURE FOR ROW AND

COLUMN EXCHANGE ********~*

20 SCALE(M) = J IF (J .EQ. M) GO TO 50

DO 30 I = I, L F = A(I,J) A(I,J) = A(I,M)

A(I,M) = F

30 CONTINUE

DO 40 1 = K, N

F = A(J, I) A(J,I) = A(M,I)

A(M, I) = F 40 CONTINUE

C 50 GO TO (80, 130), !EXC

C ********** SEARCH FOR ROWS ISOLATING AN EIGENVALUE

C AND PUSH THEM DOWN **********

80 IF (L .EQ. i) GO TO 280

L = L - i C ********** FOR J=L STEP -I UNTIL 1 DO -- **********

i00 DO 120 JJ = i, L J = L + i - JJ

ii0

DO Ii0 I = i, L IF (! .EQ. J) GO TO ii0 IF (A(J,I) .NE. 0.0) GO TO 120

CONTINUE

M = L !EXC = 1 GO TO 20

120 CONTINUE

204

7 . 1 - 1 0

GO TO 140

********** SEARCH FOR COLUMNS ISOLATING AN EIGENVALUE AND PUSH THEM LEFT **********

130 K = K + 1

140 DO 170 J = K, L

150

DO 150 I = K, L IF (I .EQ. J) GO TO 150 IF (A(I,J) .NE. 0.0) GO TO 170

CONTINUE

M = K IEXC = 2 GO TO 20

170 CONTINUE

********** NOW BALANCE THE SUBMATRIX IN ROWS K TO L ********** DO 180 I = K, L

180 SCALE(I) = 1.0

********** ITERATIVE LOOP FOR NORM REDUCTION ********** 190 NOCONV = .FALSE.

DO 270 1 = K, L C = 0.0 R= 0.0

DO 200 J = K, L IF (J .EQ. I) GO TO 200 C = C + ABS(A(J,I)) R = R + ABS(A(I,J))

200 CONTINUE

C ********** GUARD AGAINST ZERO C OR R DUE TO UNDERFLOW ********** IF (C .EQ. 0.0 .OR. R .EQ. 0.0) GO TO 270 G = R / RADIX F=I.0 S = C + R

210 IF (C .GE. G) GO TO 220 F = F * RADIX C = C * B 2 GO TO 210

220 G = R * RADIX 230 IF (C .LT. G) GO TO 240

F = F / RADIX C = C / B2

GO TO 230 C ********** NOW BALANCE **********

240 IF ((C + R) / F .GE. 0.95 * S) GO TO 270 G=I.O/F SCALE(l) = SCALE(l) * F NOCONV = .TRUE.

250 DO 250 J = K, N

A(I,J) = A(I,J) * G

205

7.1-11

260 DO 260 J = I, L

A(J,I) = A(J,I) * F

270 CONTINUE

IF (NOCONV) GO TO 190

280 LOW = K

IGH = L

RETURN END

206

7.1-12

NATS PROJECT


F270-2 BALBAK

A Fortran IV Subroutine to Back Transform the Eigenvectors of that Real Matrix Transformed by BALANC.

May, 1972 July, 1975

i. PURPOSE.

The Fortran IV subroutine BALBAK forms the eigenvectors of a real general matrix from the eigenvectors of that matrix transformed by BALANC (F269).

2. USAGE.

A. Call~ng Sequence.


SUBROUTINE BALBAK(NM,N,LOW, IGH, SCALE,M,Z)


NM is an integer input variable set equal to the row dimension of the two-dimensional array Z as specified in the DIMENSION statement for Z in the calling program.

N is an integer input variable set equal to the number of components of the vectors in the array Z. N must be not greater than NM.

LOW, IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F269 for the details.

SCALE is a working precision real input one- dimensional variable of dimension at least N containing information about the transformations. See section 3 of F269 for the details.

207

7.1-13


is a working precision real two-dimensional variable with row dimension NM and column dimension at least M. On input, the first M columns of Z contain the real and imaginary parts of the eigenvectors to be back transformed. On output, these M columns of Z contain the real and imaginary parts of the transformed eigenvectors.


None°


This subroutine should be used in conjunction with the subroutine BALANC (F269).


Using the notation of F269, the original matrix transformed into the matrix C by the similarity transformation

A is

-I C = G PAPG

where G is the diagonal matrix whose diagonal elements are 1.0 in positions 1 to LOW-I, 1.0 in positions IGH+I to N, and are the diagonal elements of D in positions LOW to IGH. Given an array Z of vectors, the subroutine BALBAK computes the matrix product PGZ. If the real and imaginary parts of the eigenvectors of C are columns of the array Z, then BALBAK forms the eigenvectors of A in their place. The information about P and D is encoded in the array SCALE. See section 3 of F269 for the details.

This subroutine is a translation of the Algol procedure BALBAK written and discussed in detail by Pariett and Reinsch (I).

208

7.1-14

4. REFERENCES.

1) Parlett, B.N. and Reinsch, C., Balancing a Matrix for Calculation of Eigenvalues and Eigenvectors, Num. Math. 13,293-304 (1969). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution II/Ii, 315-326, Springer-Verlag, 1971.)

5. CHECKOUT.

A. Test Cases.


B. Accuracy.

BALBAK introduces no rounding errors (on a machine with at least one guard digit) since its only arithmetic is scaling the eigenvector matrix by powers of the radix.

209

7.1-15

SUBROUTINE BALBAK(NM,N,LOW, IGH, SCALE,M,Z)

INTEGER I~J,K,M,N,II,NM, IGH,LOW REAL SCALE(N),Z(NM,M) REAL S

IF (M ,EQ. 0) GO TO 200 IF (IGH .EQ. LOW) GO TO 120

I00

DO Ii0 i = LOW, IGH S = SCALE(l)

********** LEFT HAND EIGENVECTORS ARE BACK TRANSFORMED IF THE FOREGOING STATEMENT IS REPLACED BY S=I.O/SCALE(1). ***~******

DO i00 J = i, M Z(I,J) = Z(I,J) * S

ii0 CONTINUE ********- FOR I=LOW-I STEP -I UNTIL i~

IGH+I STEP 1 UNTIL N DO -- ********** 120 DO 140 ii = i, N

! = II IF (I .GE. LOW .AND. I .LE. IGH) GO TO 140 IF (I .LT. LOW) I = LOW - II K = SCALE(l) IF (K .EQ. I) GO TO 140

130

DO 130 J = i~ M S = Z(I,J) Z(I,J) = Z(K,J)

Z(K,J) = S CONTINUE

140 CONTINUE

200 RETURN END

210

7.1-16

NATS PROJECT


F294 BISECT

A Fortran IV Subroutine to Determine Some Eigenvalues of a Symmetric Tridiagonal Matrix.

May, 1972

I. PURPOSE.

The Fortran IV subroutine BISECT determines those eigenvalues of a symmetric tridiagonal matrix in a specified interval using Sturm sequencing.

2. USAGE.

A. Calling Sequence.


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


N is an integer input variable set equal to the order of the matrix.

EPSI is a working precision real variable. On input, it specifies an absolute error tolerance for the computed eigenvalues. If the input EPSI is non-positive, it is reset to a default value described in section 2C.

D is a working precision real input one- dimensional variable of dimension at least N containing the diagonal elements of the symmetric tridiagonal matrix.

E is a working precision real input one- dimensional variable of dimension at least N containing, in its last N-I positions, the subdiagonal elements of the symmetric tridiagonal matrix. E(1) is arbitrary.

211

7.1-17

E2 is a working precision real one-dimensional variable of dimension at least N. On input s the last N-I positions in this array contain the squares of the subdiagonal elements of the symmetric tridiagonal matrix. E2(1) is arbitrary. On output, E2(1) is set to zero. If any of the elements in E are regarded as negligible, the corresponding elements of E2 are set to zero, and so the matrix splits into a direct sum of submatrices.

LB,UB are working precision real input variables specifying the lower and upper endpoints, respectively, of the interval to be searched for the eigenvalues. If LB is not less than UB, BISECT computes no eigenvalues. See section 2C for further details.

MM is an integer input variable set equal to an upper bound for the number of eigenvalues in the interval (LB,UB).

M is an integer output variable set equal to the number of eigenvalues determined to lie in the interval (LB,UB).

is a working precision real output one- dimensional variable of dimension at least MM containing the M eigenvalues of the symmetric tridiagonal matrix in the interval (LB,UB). The eigenvalues are in ascending order in W.

IND is an integer output one-dimensional variable of dimension at least MM containing the submatrix indices associated with the corresponding M eigenvalues in W. Eigenvalues belonging to the first submatrix have index I, those belonging to the second submatrix have index 2, etc.

IERR is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.

RV4,RV5 are working precision real temporary one- dimensional variables of dimension at least N used to hold the lower and upper bounds for the eigenvalues in the bisection process.

212

7. 1-18


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 number of eigenvalues determined to lie in (LB,UB).

If M does not exceed MM, IERR is set to zero.


To determine some of the eigenvalues of a full symmetric matrix, BISECT should be preceded by TREDI (F277) to provide a suitable symmetric tridiagonal matrix for BISECT.

To determine some of the eigenvalues of a complex Hermitian matrix, BISECT should be preceded by HTRIDI (F284) to provide a suitable real symmetric tridiagonal matrix for BISECT.

Some of the eigenvalues of certain non-symmetric tridiagonal matrices can be computed using the combination of FIGI (F280) and BISECT. See F280 for the description of this special class of matrices. For these matrices, BISECT should be preceded by FIGI to provide a suitable symmetric matrix for BISECT.

To determine eigenvectors associated with the computed eigenvalues, BISECT should be followed by TINVIT (F223) and the appropriate back transformation subroutine -- TRBAKI (F279) after TREDI, HTRIBK (F285) after HTRIDI, or BAKVEC (F281) after FIGI.

The subroutines TQLI (F289) and IMTQLI (F291) determine all the eigenvalues of a symmetric tridiagonal matrix faster than BISECT determines 25 percent of them. Hence, if more than 25 percent of them are desired, it is recommended 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 eigenvalues very close to the endpoints of the interval may be erroneously counted or missed.

The input interval (LB,UB) may be refined internally to a smaller interval known to contain all the eigenvalues in (LB,UB). This insures that BISECT will not perform unnecessary bisection steps to determine the eigenvalues in (LB,UB).

213

7,1-19

The precision of the computed eigenvalues is controlled through the parameter EPSI. To obtain eigenvalues accurate to within a certain absolute error, EPSI should be set to that error. In particular, if MACHEP denotes the relative machine precision, then to obtain the eigenvalues to an accuracy commensurate with small relative perturbations of the order of MACHEP in the matrix elements, it is enough for most tridiagonal matrices that EPSI be approximately MACHEP times a norm of the matrix. But some matrices require a smaller EPSI for this accuracy 9 perhaps as small as MACHEP times the eigenvalue of smallest magnitude in (LB,UB). Note, however, that if EPSI is smaller than required, BISECT will perform unnecessary bisection steps to determine the eigenvalues. For further discussion of EPSI, see reference (I).

If the input EPSI is non-positive, BISECT resets it, for each submatrix, to -MACHEP times the 1-norm of the submatrix and uses its magnitude. This value is tentatively considered adequate for computing the eigenvalues to an accuracy commensurate with small relative perturbations of the order of MACHEP in the matrix elements.


The eigenvalues are determined by the method of bisection applied to the Sturm sequence.

The calculations proceed as follows. First, the subdiagonal elements are tested for negligibility. If an element is considered negligible, its square is set to zero, and so the matrix splits into a direct sum of submatrices. Then, the Sturm sequence for the entire matrix is evaluated at UB and LB giving the number of eigenvalues of the matrix less than UB and LB respectively. The difference is the number of eigenvalues in (LB,UB).

Next, a submatrix is examined for its eigenvalues in the interval (LB,UB). The Gerschgorin interval, known to contain all the eigenvalues, is determined and used to refine the input interval (LB,UB). If the input EPSI is non- positive, it is reset to the default value described in section 2C~ Then, subintervals, each enclosing an eigenvalue in (LB,UB), are shrunk using a bisection process until the endpoints of each subinterval are close enough to be accepted as an eigenvalue of the submatrix. Here the endpoints of each subinterval are close enough when they differ by less than MACHEP times twice the sum of the magnitudes of the endpoints plus the absolute error tolerance EPSI.

214

7.1-20

The submatrix eigenvalues are then merged with previously found eigenvalues into an ordered set.

The above steps are repeated on each submatrix until all the eigenvalues in the interval (LB,UB) are computed.

This subroutine is a subset (except for the section merging eigenvalues of submatrices) of the Fortran subroutine TSTURM (F293), which is a translation of the Algol procedure TRISTURM written and discussed in detail by Peters and Wilkinson (2). A similar Algol procedure BISECT is discussed in detail by Barth, Martin, and Wilkinson (i).

4. REFERENCES.

i) Barth, W., Martin, R.S., and Wilkinson, J.H., Calculation of the Eigenvalues of a Symmetric Tridiagonal Matrix by the Method of Bisection, Num. Math. 9,386-393 (1967).

2) Peters, G. and Wilkinson, J.H., The Calculation of Specified Eigenvectors by Inverse Iteration, Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/18, 418-439, Springer-Verlag, 1971.

5. CHECKOUT.

A. Test Cases.

See the section discussing testing of the codes for complex Hermitian, real symmetric, real symmetric tridiagonal, and certain real non-symmetric tridiagonal matrices.

B. Accuracy.

The subroutine BISECT is numerically 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.

215

7.1-21

C C

C

C C

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

INTEGER !,J,K)L,M,N,P,Q,R,S,II)MM,MI,M2,TAG,!ERR,ISTURM REAL D(N))E(N) ,E2(N),W(MM) ,RV4(N),RV5(N)

REAL U,V)LB,TI,T2,UB,XU,X0,XI,EPSI,MACHEP REAL ABS,AMAXI,AMiNI,FLOAT

INTEGER IND(MM)

********** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING

THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.

MACHEP = ?

IERR = 0

TAG = 0 TI = LB

T2 = UB C ********** LOOK FOR SMALL SUB-DIAGONAL ENTRIES **********

DO 40 I = i) N

IF (I .EQ. i) GO TO 20 IF (ABS(E(1)) .GT. MACHEP * (ABS(D(1)) + ABS(D(I-I))))

X GO TO 40 20 E2(1) = 0.0

40 CONTINUE C ********** DETERMINE THE NUMBER OF EIGENVALUES

C IN THE INTERVAL **********

P = !

q = N

XI = UB ISTURM = I GO TO 320

60 M = S XI = LB ISTURM = 2 GO TO 320

80 M = M - S IF (M .GT. MM) GO TO 980

Q = 0

R = 0 C ********** ESTABLISH AND PROCESS NEXT SUBMATRIX, REFINING

C INTERVAL BY THE GERSCHGORIN BOUNDS **********

i00 IF (R .EQ. M) GO TO I001

TAG = TAG + I P = Q + I

XU = D(P) xo = D(P) U = 0.0

216

7.1-22

DO 120 Q = P, N

X1 = U

U = 0.0 V = 0.0

IF (Q .EQ. N) GO TO ii0 U = ABS(E(Q+I)) V = E2(Q+I)

Ii0 XU = AMINI(D(Q)-(XI+U),XU)

X0 = AMAXI(D(Q)+(XI+U),X0)

IF (V °EQ. 0.0) GO TO 140 120 CONTINUE

140 X1 = AMAXI(ABS(XU),ABS(X0)) * MACHEP IF (EPSI .LE. 0.0) EPSI =-XI IF (P .NE. Q) GO TO 180

C ********** CHECK FOR ISOLATED ROOT WITHIN INTERVAL ********** IF (rl .GT. D(P) .OR. D(P) .GE. T2) GO TO 940 M1 = P

M2 = P

RVS(P) = D(P)

GO TO 9O0

180 XI = XI * FLOAT(Q-P+1)

LB = AMAXI (TI,XU-XI) UB = AMINI(T2,X0+XI) X1 = LB ISTURM = 3

GO TO 320 200 MI = S + 1

XI = UB ISTURM = 4

GO TO 320 220 M2 = S

IF (MI .GT. M2) GO TO 940

C ********** FIND ROOTS BY BISECTION ********** XO = UB

ISTURM = 5

C C

C

DO 240 I = MI, M2 RVS(I) = UB RV4 (I) = LB

240 CONTINUE

********** LOOP FOR K-TH EIGENVALUE

FOR K=M2 STEP -i UNTIL MI DO --

(-DO- NOT USED TO LEGALIZE COMPUTEE-GO-TO) ********** K = M2

250 XU = LB

********** FOR I=K STEP -I UNTIL M1 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 260

217

7,1-23

C

280 IF (X0 oGT. RV5(K)) X0 = RVS(K) ********** NEXT BISECTION STEP **********

3 0 0 xl : (xu + x0) * 0.5 IF ((X0 - XU) .LE, (2.0 * MACHEP *

X (ABS(XU) + ABS(X0)) + ABS(EPSI))) GO TO 420

********** IN-LINE PROCEDURE FOR STURM SEQUENCE **********

320 S = P - I

U=I.0

325

330

3 4 0

DO 340 1 = P, Q

IF (U .NE. 0.0) GO TO 325 V = ABS(E(1)) / MACHEP

GO TO 330 V = E2(1) / U U = D(1) - Xl - V IF (U .LT. 0.0) S = S + !

CONTINUE

3 6 0

380

400

GO TO (60,80,200,220,360), ISTURM

********** REFINE INTERVALS ********** IF (S .GE. K) GO TO 400

XU = XI IF (S .GE. MI) GO TO 380

RV4(MI) = XI GO TO 300 RV4 (S+I) = XI IF (RV5(S) .GT. El) RV5(S) = XI

GO TO 300

X0 = X1

GO TO 300 ********** K-TH EIGENVALUE FOUND **********

420 RV5(K) = El

K = K - i IF (K ,GE. MI) GO TO 250 ********** ORDER EIGENVALUES TAGGED WITH THEIR

SUBMATRIX ASSOCIATIONS **********

900 S = R R = R + M2 - MI + i

J = i K = MI

DO 920 L = i, R IF (J .GT. S) GO TO 910

IF (K .GT. M2) GO TO 940 IF (RV5(K) .GE. W(L)) GO TO 915

905

DO 905 Ii = J, S

I = L + S - !! W(I+1) = W(I) IND(I+I) = IND(1)

CONTINUE

2 1 8

7 . 1 - 2 4

910 W(L) = RVS(K) IND (L) = TAG

K = K + I GO TO 920

915 J = J + I

920 CONTINUE

940 IF (Q .LT. N) GO TO I00

GO TO i001 *****~***~ SET ERROR -- UNDERESTIMATE OF NUMBER OF

EIGENVALUES IN INTERVAL **********

980 IERR = 3 * N + 1 I001LB = TI

UB = T2 RETURN END

219

7. 1-25

NATS PROJECT


F272-2 CBABK2

A Fortran IV Subroutine to Back Transform the Eigenvectors of that Complex Matrix Transformed by CBAL.

May, 1972 July, 1975

I~ PURPOSEs

The Fortran IV subroutine CBABK2 forms the eigenvectors of a complex general matrix from the eigenvectors of that matrix transformed by CBAL (F271).

2. USAGE.

A. Calling Sequencer


SUBROUTINE CBABK2(NM,N,LOW, IGH, SCALE,M,ZR,ZI)


NM is an integer input variable set equal to the row dimension of the two-dimensional arrays ZR and ZI as specified in the DIMENSION statements for ZR and ZI in the calling program.

N is an integer input variable set equal to the number of components of the vectors in the array Z = (ZR,ZI). N must be not greater than NM.

LOW,!GH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F271 for the details.

SCALE is a working precision real input one- dimensional variable of dimension at least N containing information about the transformations. See section 3 of F271 for the details.

220

7.1-26

M

ZR,ZI

is an integer input variable set equal to the number of columns of Z = (ZR,ZI) to be back transformed.

are working precision real two-dimensional variables with row dimension NM and column dimension at least M. On input, the first M columns of ZR and ZI contain the real and imaginary parts, respectively, of the eigenvectors to be back transformed. On output, these M columns of ZR and ZI contain the real and imaginary parts of the transformed eigenvectors.


None.


This subroutine should be used in conjunction with the subroutine CBAL (F271).


Using the notation of F271, the original matrix A transformed into the matrix C by the similarity transformation

is

-i C = G PAPG

where G is the diagonal matrix whose diagonal elements are 1.0 in positions I to LOW-l, 1.0 in positions IGH+I to N, and are the diagonal elements of D in positions LOW to IGH. Given an array Z of vectors, the subroutine CBABK2 computes the matrix product PGZ. If the eigenvectors of C are columns of the array Z, then CBABK2 forms the eigenvectors of A in their place. The information about P and D is encoded in the array SCALE. See section 3 of F271 for the details.

This subroutine is a translation of the Algol procedure CBABK2 which is the analogue for complex matrices of the procedure BALBAK written and discussed in detail by Parlett and Reinsch (I).

221

7.1-27

4. REFERENCES~

i) Parlett~ B.N. and Reinsch~ C., Balancing a Matrix for Calculation of Eigenvalues and Eigenvectors, Num. Math. 13,293-304 (1969). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution II/ll, 315-326, Springer-Verlag, 1971.)

5, CHECKOUT~

A. Test Cases°

See the section discussing testing of the codes for complex general matrices.

B. Accuracy°

CBABK2 introduces no rounding errors (on a machine with at least one guard digit) since its only arithmetic is scaling the eigenvector matrix by powers of the radix.

222

7.1-28

SUBROUTINE CBABK2(NM,N,LOW, IGH, SCALE,M,ZR,ZI)

INTEGER I,J,K,M,N,II,NM,IGH,LOW

REAL SCALE(N),ZR(NM,M),ZI(NM,M) REAL S

IF (M .EQ. 0) GO TO 200 IF (IGH .EQ. LOW) GO TO 120

i00

DO II0 1 = LOW, IGH S = SCALE(l)

********** LEFT HAND EIGENVECTORS ARE BACK TRANSFORMED IF THE FOREGOING STATEMENT IS REPLACED BY S=I.0/SCALE(1). **********

DO i00 J = I, M ZR(I,J) = ZR(I,J) * S ZI(I,J) = ZI(I,J) * S

CONTINUE

ii0 CONTINUE

********** FOR I=LOW-I STEP -i UNTIL i, IGH+I STEP 1 UNTIL N DO -- **********

120 DO 140 II = i, N I = II

IF (I .GE. LOW .AND. I .LE. IGH) GO TO 140 IF (I .LT. LOW) I = LOW - II K = SCALE(l) IF (K .EQ. I) GO TO 140

130

DO 130 J = i, M S = ZR(I,J) ZR(I,J) = ZR(K,J) ZR(K,J) = S S = ZI(I,J) ZI(I,J) = ZI(K,J) ZI(K,J) = S

CONTINUE

140 CONTINUE

200 RETURN END

223

7. 1-29

NATS PROJECT

EiGENSYSTEM SUBROUTINE PACKAGE (EISPACK)

F271-2 CBAL

A Fortran IV Subroutine to Balance a Complex General Matrix.

May, 1972 July, i975

i. PURPOSE.

The Fortran IV subroutine CBAL balances a complex general matrix and isolates eigenvalues whenever possible. Sums of the magnitudes of elements in corresponding rows and columns are made nearly equal by exact similarity transformations, and eigenvalues are isolated by permutation similarity transformations. Balancing reduces the 1-norm of the original matrix whenever sums of the magnitudes of elements in some row and corresponding column are markedly different, while at the same time leaving the eigenvalues unchanged. Reducing the norm in this way can improve the accuracy of the computed eigenvalues and/or eigenvectors.

2. USAGE.



SUBROUTINE CBAL(NM,N,AR,AI,LOW,IGH,SCALE)


NM is an integer input variable set equal to the row dimension of the two-dimensional arrays AR and AI as specified in the DIMENSION statements for AR and AI in the calling program.

N is an integer input variable set equal to the order of the matrix A = (AR,AI). N must be not greater than NM.

224

7.1-30

AR,AI are working precision real two-dimensional variables with row dimension NM and column dimension at least N. On input, AR and AI contain the real and imaginary parts, respectively, of the complex matrix of order N to be balanced. On output, AR and AI contain the real and imaginary parts of the transformed matrix.

LOW, IGH are integer output variables indicating the boundary indices for the balanced matrix. See section 3 for the details.

SCALE is a working precision real output one- dimensional variable of dimension at least N containing information about the similarity transformations. See section 3 for the details.


None.


It is particularly advantageous to use CBAL whenever the sums of the magnitudes of elements in some row and corresponding column are quite different. Additionally, the execution time for CBAL is small compared with the execution time for the routines which determine the eigenvalues and/or eigenvectors. Hence it is recommended that CBAL be used generally.

The subroutine CBABK2 (F272) should be used to retrieve the eigenvectors of the original matrix after the eigenvectors of the transformed matrix have been determined.

In this implementation, the arithmetic is real throughout.


First CBAL determines a product P such that

PAP (T X Y)

= (0 B Z) (0 0 R)

of permutation matrices

225

7.1-31

where T and R are upper triangular matrices and B is a square matrix situated in rows and columns LOW through IGH with no zero off-diagonal rows or columns. X, Y, and Z are rectangular matrices of appropriate dimensions. The diagonal elements of T and R are the isolated eigenvalues of A. In the exceptional case where B is empty, LOW = 1 and IGH = 0 -- however, I is returned as the output value of IGH.

Next, the subroutine CBAL determines iteratively a real non-singular diagonal matrix D of order IGH-LOW+I such that

-i D BD

is a balanced matrix in the sense that the sums of the magnitudes of elements in corresponding rows and columns of

-i D BD

are nearly equal° The diagonal elements of D are powers of the radix of the floating point arithmetic of the machine.

Upon completion of CBAL, the vector array SCALE contains the information about P and D necessary for CBABK2 to retrieve the eigenvectors of the original matrix from the eigenvectors of the transformed matrix. The information is

encoded as follows. I. The J-th and SCALE(J)-th rows and columns of the

original matrix have been permuted for J = 1,2,...,LOW-I,IGH+I,IGH+2,...,N.

2. SCALE(J) is the (J-LOW+l)-th diagonal element of D

for J = LOW,LOW+I,...,IGH. Upon completion of CBAL, the output matrix is

( T xo Y ) - 1 - 1

( 0 D BD D Z )

( 0 0 R ) .

This subroutine is a translation of the Algol procedure CBALANCE which is the analogue for complex matrices of the procedure BALANCE written and discussed in detail by Parlett and Reinsch (i).

226

7.1-32

4. REFERENCES.

~) Parlett, B.N. and Reinsch, C., Balancing a Matrix for Calculation of Eigenvalues and Eigenvectors, Num. Math. 13,293-304 (1969). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution II/ll, 315-326, Springer-Verlag, 1971.)

5. CHECKOUT.

A. Test Cases.


B. Accuracy.

CBAL introduces no rounding errors (on a machine with at least one guard digit) since its only arithmetic is scaling the input matrix by powers of the radix.

227

7~ 1-33

SUBROUTINE CBAL(NM,N,AR,AI,LOW,iGH,SCALE)

INTEGER !,J,K,L,M,N,JJ,NM,IGH,LOW,IEXC REAL AR(NM,N),AI(NM,N),SCALE(N)

REAL C,F,G,R,S,B2,RADIX REAL ABS

LOGICAL NOCONV

********** RADIX IS A MACHINE DEPENDENT PARAMETER SPECIFYING THE BASE OF THE MACHINE FLOATING POINT REPRESENTATION.

RADIX = #

B2 = RADIX * RADIX

K = 1

L = N GO TO i00 • ********* IN-LINE PROCEDURE FOR ROW AND

COLUMN EXCHANGE ********** 20 SCALE(M) = J

IF (J .EQ~ M) GO TO 50

DO 30 I = i, L

F = AR(I,J) AR(I,J) = AR(I,M)

AR(I,M) = F F = AI(I,J)

AI(I,J) = AI(I,M)

AI(I,M) = F

30 CONTINUE

DO 40 1 = K, N F = AR(J,I)

AR(J,I) = AR(M,I) AR(M,I) = F

F = AI(J,I) AI(J,I) = AI(M,I) AI (M, I) = F

40 CONTINUE

C 50 GO TO (80,130), IEXC

C ********** SEARCH FOR ROWS ISOLATING AN EIGENVALUE

C AND PUSH THEM DOWN **********

80 IF (L .EQ. i) GO TO 280 L = L - I

C ********** FOR J=L STEP -I UNTIL i DO -- **********

i00 DO 120 JJ = i, L J = L + i - JJ

ii0

DO ii0 i = I, L IF (I .EQ. J) GO TO ii0 IF (AR(J,I) .NE. 0.0.0R~ AI(J,I) .NE. 0.0) GO TO 120

CONTINUE

228

7.1-34

C

C C

C

C

M = L

IEXC = 1 GO TO 20

120 CONTINUE

GO TO 140

********** SEARCH FOR COLUMNS ISOLATING AN EIGENVALUE AND PUSH THEM LEFT **********

130 K = K + 1

140 DO 170 J = K, L

150

DO 150 1 = K, L IF (I .EQ. J) GO TO 150

IF (AR(I,J) .NE. 0.0 .OR. AI(I,J) .NE. 0.0) GO TO 170 CONTINUE

M = K IEXC = 2 GO TO 20

170 CONTINUE

********** NOW BALANCE THE SUBMATRIX IN ROWS K TO L ********** DO 180 I = K, L

180 SCALE(l) = 1.0

********** ITERATIVE LOOP FOR NORM REDUCTION ********** 190 NOCONV = .FALSE.

DO 270 1 = K, L C=0.0

R=0.0

DO 200 J = K, L

IF (J .EQ. I) GO TO 200 C = C + ABS(AR(J,I)) + ABS(AI(J,I))

R = R + ABS(AR(I,J)) + ABS(AI(I,J)) 200 CONTINUE

********** GUARD AGAINST ZERO C OR R DUE TO UNDERFLOW ********** IF (C .EQ. 0.0 .OR. R .EQ. 0.0) GO TO 270 G = R / RADIX F = 1.0

S = C +R 210 IF (C .GE. G) GO TO 220

F = F * RADIX C = C * B2 GO TO 210

220 G = R * RADIX

230 IF (C .LT. G) GO TO 240 F = F / RADIX C = C / B 2 GO TO 230

229

7. 1-35

240 ********** NOW BALANCE **********

IF ((C + R) / F .GE. 0.95 * S) GO TO 270 G = 1.0 / F SCALE(I) = SCALE(I) * F

NOCONV = ~TRUE.

250

DO 250 J = K~ N

AR(I,J) = AR(I,J) * G iI(I,J) = AI(I,J) * G

CONTINUE

260

DO 260 J = i, L

AR(J,I) = AR(J,I) * F AI(J,I) = AI(J,I) * F

CONTINUE

270 CONTINUE

IF (NOCONV) GO TO 190

280 LOW = K

IGH = L RETURN

END

230

7.1-36

NATS PROJECT


F301 CG

A Fortran IV Driver Subroutine to Determine the Eigenvalues and Eigenvectors of a Complex General Matrix.

July, 1975

i. PURPOSE.

The Fortran IV subroutine CG calls the recommended sequence of subroutines from the eigensystem subroutine package EISPACK to determine the eigenvalues and eigenvectors (if desired) of a complex general matrix.

2. USAGE.



SUBROUTINE CG(NM,N,AR,AI,WR,WI,MATZ, ZR,ZI,FVI,FV2,FV3,1ERR)


NM is an integer input variable set equal to the row dimension of the two-dimensional arrays AR, AI, ZR, and ZI as specified in the DIMENSION statements for AR, AI, ZR, and ZI in the calling program.

is an integer input variable set equal to the order of the matrix A = (AR,AI). N must not be greater than NM.

AR,AI are working precision real two-dimensional variables with row dimension NM and column dimension at least N. On input, AR and AI contain the real and imaginary parts, respectively, of the complex general matrix of order N whose eigenvalues and eigenvectors are to be found. On output, AR and AI have been destroyed.

231

7.1-37

WR,WI are working precision real output one- dimensional variables of dimension at least N containing the real and imaginary parts, respectively, of the eigenvalues of the complex general matrix.

MATZ is an integer input variable set equal to zero if only eigenvalues are desired; otherwise it is set to any non-zero integer for both eigenvalues and eigenvectors.

ZR,ZI are, if MATZ is non-zero, working precision real output two-dimensional variables with row dimension NM and column dimension at least N containing the real and imaginary parts, respectively, of the eigenvectors. The eigenvectors are not normalized. If MATZ is zero, ZR and ZI are not referenced and can be dummy variables.

FVI,FV2,FV3 are working precision temporary one- dimensional variables of dimension at least N.



If N is greater than NM, the subroutine terminates with IERR set equal to 10*N.

If more than 30 iterations are required to determine an eigenwalue, the subroutine terminates with IERR set equal to the index of the eigenvalue for which the failure occurs. The eigenvalues in the WR and WI arrays should be correct for indices IERR+I,IERR+2,...,N, but no eigenvectors are computed.

If all the eigenvalues are determined within 30 iterations, IERR is set to zero.


This subroutine can be used to find all the eigenvalues and all the eigenvectors (if desired) of a complex general matrix.

232

7. 1-38


This subroutine calls the recommended sequence of subroutines from EISPACK to find the eigenvalues and eigenvectors of a complex general matrix.

To find eigenvalues only, the sequence is the following. C B A L - to balance a complex general matrix, CORTH - to reduce the balanced matrix to an upper

Hessenberg matrix using unitary transformations.

COMQR - to determine the eigenvalues of the original matrix from the Hessenberg matrix.

To find eigenvalues and eigenvectors, the sequence is the following.

C B A L - to balance a complex general matrix. CORTH - to reduce the balanced matrix to an upper

Hessenberg matrix using unitary transformations.

COMQR2 - to determine the eigenvalues and eigenvectors of the balanced matrix from the Hessenberg matrix.

C B A B K 2 - to backtransform the eigenvectors to those of the original matrix.

4. REFERENCES.

i) Garbow, B.S. and Dongarra, J.J., April, 1974.

EISPACK Path Chart,

5. CHECKOUT.

A. Test Cases.


B. Accuracy.

The accuracy of CG can be best described in terms of its role in those paths of EISPACK (I) which find eigenvalues and eigenvectors of complex general matrices. In these paths, this subroutine is numerically stable. This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original matrix.

233

7. 1-39

SUBROUTINE CG(NM,N,AR,AI,WR~WI,MATZ,ZR,ZI,FVI,FV2,FV3,1ERR)

INTEGER N,NM,ISI,IS2,1ERR,MATZ REAL AR(NM,N),AI(NM,N),WR(N),WI(N),ZR(NM,N),ZI(NM,N),

$ FVI(N),FV2(N),FV3(N)

IF (NoLE. NM) !ERR = i0 * N

GO TO 50

GO TO I0

I0 CALL CBAL(NM, N,AR,AI,ISI,IS2,FVI) CALL CORTH(NM,N,ISI,IS2,AR,AI,FV2,FV3) IF (MATZ .RE. 0) GO TO 20 ********** FIND EIGENVALUES ONLY ********** CALL COMQR(NM,N, ISI,IS2,AR,AI,WR,WI, IERR) GO TO 50 ********** FIND BOTH EIGENVALUES AND EIGENVECTORS **********

20 CALL COMQR2(NM~N, ISI,IS2,FV2,FV3~AR~AI~WR,WI,ZR,ZI,IERR) IF (IERR .RE. 0) GO TO 50 CALL CBABK2(NM~N,ISI,IS2~FVI,N,ZR,ZI)

50 RETURN END

234

7.1-40

NATS PROJECT


F302 CH

A Fortran IV Driver Subroutine to Determine the Eigenvalues and Eigenvectors of a Complex Hermitian Matrix.

July, 1975

i. PURPOSE.

The Fortran IV subroutine CH calls the recommended sequence of subroutines from the eigensystem subroutine package EISPACK to determine the eigenvalues and eigenveetors (if desired) of a complex Hermitian matrix.

2. USAGE.



SUBROUTINE CH(NM,N,AR,AI,W,MATZ, ZR,ZI,FVI,FV2,FMI,IERR)



is an integer input variable set equal to the order of the matrix A = (AR,AI). N must not be greater than NM.

AR,AI are working precision real two-dimensional variables with row dimension NM and column dimension at least N. On input, AR and AI contain the real and imaginary parts, respectively, of the complex Hermitian matrix of order N whose eigenvalues and

235

7. 1-41

eigenvectors are to be found. Only the full lower triangle of AR and the strict lower triangle of AI need be supplied. On output, the full upper triangle of AR and the strict upper triangle of Ai are unaltered.

W is a working precision real output one- dimensional variable of dimension at least N containing the eigenvalues of the complex Hermitian matrix in ascending order.


ZR,ZI are, if MATZ is non-zero, working precision real output two-dimensional variables with row dimension NM and column dimension at least N containing the real and imaginary parts, respectively, of the eigenvectors. The eigenvectors are orthonormal. If MATZ is zero, ZR and ZI are not referenced and can be dummy variables.

FVI,FV2 are working precision temporary one- dimensional variables of dimension at least N.

FMI is a working precision temporary two- dimensional variable with row dimension and column dimension at least N.

!ERR is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.



If more than 30 iterations are required to determine an eigenvalue, the subroutine terminates with IERR set equal to the index of the eigenvalue for which the failure occurs. The eigenvalues in the W array should be correct for indices 1,2,...,IERR-I, but no eigenvectors are computed.

236

7.1-42



This subroutine can be used to find all the eigenvalues and all the eigenvectors (if desired) of a complex Hermitian matrix.


This subroutine calls the recommended sequence of subroutines from EISPACK to find the eigenvalues and eigenvectors of a complex Hermitian matrix.

To find eigenvalues only, the sequence is the following. HTRIDI - to reduce a complex Hermitian matrix to a real

symmetric tridiagonal matrix using unitary transformations.

TQLRAT - to determine the eigenvalues of the original matrix from the real symmetric tridiagonal matrix.


HTRIDI - to reduce a complex Hermitian matrix to a real symmetric tridiagonal matrix using unitary transformations.

TQL2 - to determine the eigenvalues and eigenveetors of the real symmetric tridiagonal matrix.

HTRIBK - to backtransform the eigenvectors to those of the original matrix.

4. REFERENCES.


EISPACK Path Chart,

5. CHECKOUT.

A. Test Cases.

See the section discussing testing of the codes for complex Hermitian matrices.

B. Accuracy.

237

7. 1-43

The accuracy of CH can best b e described in terms of its role in those paths of EISPACK (I) which find eigenvalues and eigenvectors of complex Hermitian matrices. In these paths, this subroutine is numerically stable. This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix,

238

7.1-44

C

SUBROUTINE CN(NM~N,AR,AI,W~MATZ,ZR,ZI,FVI,FV2,FMI,IERR)

INTEGER I,J,N,NM,IERR,MATZ REAL AR(NM,N),AI(NM,N),W(N),ZR(NM,N),ZI(NM,N),

$ FVI(N),FV2(N),FMI(2,N)

IF (N .LE. NM) GO TO i0 IERR = i0 * N GO TO 50

i0 CALL HTRIDI(NM,N,AR,AI,W,FVI,FV2,FMI) IF (MATZ .NE. 0) GO TO 20 ********** FIND EIGENVALUES ONLY ********** CALL TQLRAT(N,W,FV2,1ERR) GO TO 50 ********** FIND BOTH EIGENVALUES AND EIGENVECTORS **********

20 DO 40 I = i, N

30

DO 30 J = i, N ZR(J,I) = 0.0

CONTINUE

ZR(I,I) = 1.0 40 CONTINUE

CALL TQL2(NM,N,W,FVI,ZR,IERR) IF (IERR .NE. 0) GO TO 50 CALL HTR!BK(NM,N,AR,AI,FMI,N,ZR,ZI)

50 RETURN END

239

7.1-45

NATS PROJECT


F297-2 CINVIT

A Fortran IV Subroutine to Determine Those Eigenvectors of a Complex Upper Hessenberg Matrix Corresponding to Specified Eigenvalues.

May, 1972 July, 1975

i. PURPOSE.

The Fortran IV subroutine CINVIT computes the eigenvectors of a complex upper Hessenberg matrix corresponding to specified eigenvalues using inverse iteration.

2. USAGE.



SUBROUTINE CINVlT(NM, N,AR,A!,WR,WI,SELECT, MM,M,ZR,ZI,IERR,RMI,RM2,RVI,RV2)



N is an integer input variable set equal to the order of the matrix A = (AR,AI). N must be not greater than NM.

AReAl are working precision real input two- dimensional variables with row dimension NM and column dimension at least N containing the real and imaginary parts 3 respectively~ of the complex upper Hessenberg matrix.

240

7.1-46

WR,WI are working precision real one-dimensional variables of dimension at least N. On input, they contain the real and imaginary parts, respectively, of the eigenvalues of the Hessenberg matrix. The eigenvalues need not be ordered, except that eigenvalues of any submatrix of the input Hessenberg matrix must have indices in WR,WI which lie between the boundary indices for that submatrix. These ordering constraints are satisfied by the output eigenvalues from COMLR (F295). On output, the eigenvalues are unaltered, except that the real parts of close eigenvalues may be perturbed slightly in an attempt to obtain independent eigenvectors.

SELECT is a logical input one-dimensional variable of dimension at least N whose true elements flag those eigenvalues whose eigenvectors are desired.

MM is an integer input variable set equal to an upper bound for the number of columns required to hold the desired eigenvectors.

M is an integer output variable set equal to the number of columns actually used to store the eigenvectors.

ZR,ZI are working precision real output two- dimensional variables with row dimension NM and column dimension at least MM containing the real and imaginary parts, respectively, of the eigenvectors corresponding to the flagged eigenvalues. The eigenvectors are packed into the columns of ZR and ZI starting at the first columns.


RMI,RM2 are working precision real temporary array variables of dimension at least N*N. These arrays holds the triangularized form of the upper Hessenberg matrix used in the inverse iteration process.

241

7.1-47

RVI,RV2 are working precision real temporary one- dimensional variables of dimension at least N. They hold the approximate eigenvectors during the inverse iteration process.

B. Error Conditions and Returns~

If more than MM eigenvectors are requested, CINVIT terminates with IERR set to -(2*N+I) and with the first MM eigenvectors in the arrays ZR and ZI. this case, M = MM.

In

If none of the initial vectors for the inverse iteration process produces an acceptable approximation to an eigenvector, CINVIT terminates the computation for that eigenvector and sets IERR to -K where K is the index of the associated eigenvalue. If this failure occurs for more than one eigenvalue, the last occurrence is recorded in IERR. The columns of ZR and ZI corresponding to failures of the above sort are set to zero vectors.

If both of the above error conditions occur, CINVIT terminates with IERR set to -(N+K) where K is the index of the last eigenvalue whose inverse iteration process failed. The columns of ZR and ZI corresponding to failures in the inverse iteration process are set to zero vectors, and in this case, M = MM.

If neither of the above error conditions occurs, CINVIT sets IERR to zero.


To determine eigenvectors corresponding to some of the eigenvalues of a complex general matrix, CINVlT should be preceded by COMHES (F282) and COMLR (F295). COMHES provides a suitable complex upper Hessenberg matrix for CINVIT and COMLR determines the eigenvalues of this Hessenberg matrix. CINVIT should then be followed by COMBAK (F283) to back transform the eigenvectors from CINVIT into those of the original matrix. Note: the upper Hessenberg matrix must be saved before COMLR, since COMLR destroys this part of A = (AR,AI).

It is recommended in general that CBAL (F271) be used before COMHES in which case CBABK2 (F272) must be used after COMBAK.

242

7.1-48

In this implementation, the arithmetic is real throughout except for complex division and complex absolute value.


The eigenvectors are determined by inverse iteration. In CINVIT, this is a process whereby a vector XI satisfying the matrix linear equation U'X1 = X0 is computed, where X0 is an initial vector and U is the upper triangular factor in the LU decomposition of the matrix B-W*I with partial pivoting. W is an approximate eigenvalue of a leading submatrix B of the Hessenberg matrix in A. The vector X1 is accepted as an eigenvector of B if the norm of XI is sufficiently larger than the norm of X0. This eigenvector of B is transformed to an eigenvector of A by simply appending zero components to it.

The real and imaginary parts of U are stored in the two real arrays RMI and RM2 respectively. Internally, RMI and RM2 are treated as two-dimensional NxN arrays.

The acceptance criterion for X1 is a growth test of its norm. If MACHEP denotes the relative machine precision, then currently, XI is rejected as an eigenvector if

SQRT(UK)*!!B!!*MACHEP*!!XI!! .LT. !!X0!!/10.0

where UK is the order of the submatrix B whose eigenvector is being computed and the norm !! !! is the infinity norm. At most UK orthogonal initial vectors XO are tried to obtain the required growth. If no vector is accepted, the parameter IERR is set to indicate this failure and CINVIT proceeds to compute the next eigenvector.

The real parts of close or identical eigenvalues whose eigenvectors are desired may be perturbed slightly in an attempt to obtain independent eigenvectors (if they exist). If required, such perturbations are positive and small multiples of MACHEP*I!B!!.

This subroutine is a translation of the Algol procedure CX INVIT written and discussed in detail by Peters and Wilkinson (i).

243

7. 1-49

4. REFERENCE$~


5. CHECKOUT.

Ao Test Cases°

See the section discussing testing of the codes for complex general matrices~

Bo Accuracy°

The accuracy of CINVIT can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of complex upper Hessenberg matrices. In these paths, this subroutine is numerically stable (i). This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original upper Hessenberg matrix~

244

7 • 1-50

SUBROUTINE CINVIT(NM,N,AR,AI,WR,WI,SELECT,MM,M,ZR,ZI, X IERR,RMI,RM2,RVI,RV2)

INTEGER I,J,K,M,N,S,II,MM,MP,NM,UK, IPI,ITS,KMI,IERR REAL AR(NM,N),AI(NM,N),WR(N),WI(N),ZR(NM,MM),ZI(NM,MM),

X RMI(N,N),RM2(N,N),RVI(N),RV2(N) REAL X,Y,EPS3,NORM,NORMV,GROWTO,ILAMBD,MACHEP,RLAMBD,UKROOT REAL SQRT,CABS,ABS,FLOAT LOGICAL SELECT(N) COMPLEX Z3 COMPLEX CMPLX REAL REAL,AIMAG

********** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.

MACHEP = ?

IERR = 0 UK = 0 S = I

DO 980 K = i, N IF (.NOT. SELECT(K)) GO TO 980 IF (S .GT. MM) GO TO i000 IF (UK .GE. K) GO TO 200

C ********** CHECK FOR POSSIBLE SPLITTING ********** DO 120 UK = K, N

IF (UK .EQ. N) GO TO 140 IF (AR(UK+I,UK) .EQ. 0.0 .AND. AI(UK+I,UK) .EQ. 0.0)

X GO TO 140 120 CONTINUE

C ********** COMPUTE INFINITY NORM OF LEADING UK BY UK C (HESSENBERG) MATRIX **********

140 NORM = 0.0 MP = I

C

DO 180 I = i, UK X = 0.0

160 DO 160 J = MP, UK X = X + CABS(CMPLX(AR(I,J),AI(I,J)))

180

IF (X °GT. NORM) NORM = X MP = I

CONTINUE

********** EPS3 REPLACES ZERO PIVOT IN DECOMPOSITION AND CLOSE ROOTS ARE MODIFIED BY EPS3 **********

IF (NORM .EQ. 0.0) NORM = 1.0 EPS3 = MACHEP * NORM

245

7.1-51

C ********** GROWTO IS THE CRITERION FOR GROWTH ********** UKROOT = SQRT(FLOAT(UK)) GROWTO = I,OE-I / UKROOT

200 RLAMBD = WR(K)

ILAMBD = WI(K) IF (K .EQ. i) GO TO 280 KMI = K - 1

GO TO 240

C ********** PERTURB EIGENVALUE IF IT IS CLOSE C TO ANY PREVIOUS EIGENVALUE **********

220 RLAMBD = RLAMBD + EPS3

C ********** FOR I=K-I STEP -I UNTIL 1 DO -- ********** 240 DO 260 II = i~ KMI

I = K - II IF (SELECT(I) .AND. ABS(WR(I)-RLAMBD) .LT. EPS3 .AND.

ABS(WI(I)-ILAMBD) .LT. EPS3) GO TO 220

CONTINUE X

260

280

300

320

C

C

C

C

C

WR(K) = RLAMBD ********** FORM UPPER HESSENBERG (AR,AI)-(RLAMBD,ILAMBD)*I

AND INITIAL COMPLEX VECTOR **********

MP = I

DO 320 I = i, UK

DO 300 J = MP, UK RMI(i,J) = AR(I,J) RM2(I,J) = AI(I,J)

CONTINUE

RMI(I,I) = RMI(I,I) - RLAMBD RM2(I,I) = RM2(I,I) - ILAMBD

MP = I RVI(1) = EPS3

CONTINUE ********** TRIANGULAR DECOMPOSITION WITH INTERCHANGES,

REPLACING ZERO PIVOTS BY EPS3 **********

IF (UK oEQ. I) GO TO 420

X

DO 400 ! = 2, UK

MP = I - 1 IF (CABS(CMPLX(RMI(I,MP),RM2(!,MP))) .LE.

CABS(CMPLX(RMI(MP,MP),RM2(MP,MP)))) GO TO 360

340

DO 340 J = MP, UK Y = RMI(I,J) RMI (I, J) = RMI (MP, J)

RMI(MP,J) = Y Y = RM2(I,J) RM2 (I, J) = RM2 (MP, J) RM2 (MP, J) = Y

CONTINUE

246

7.1-52

360

X

X

380

400

420

X

660

680

700

720

760 780

IF (RMI(MP,MP) .EQ. 0.0 .AND. RM2(MP,MP) .EQ. 0.0)

RMI(MP,MP) = EPS3 Z3 = CMPLX(RMI(I,MP),RM2(I,MP)) /

CMPLX(RMI(MP,MP),RM2(MP,MP)) X = REAL(Z3) Y = AIMAG(Z3) IF (X .EQ. 0.0 .AND. Y .EQ. 0.0) GO TO 400

DO 380 J = I, UK RMI(I,J) = RMI(I,J) - X * RMI(MP,J) + Y * RM2(MP,J) RM2(I,J) = RM2(I,J) - X * RM2(MP,J) - Y * RMI(MP,J)

CONTINUE

CONTINUE

IF (RMI(UK,UK) .EQ. 0.0 .AND. RM2(UK,UK) .EQ. 0.0) RMI(UK,UK) = EPS3

ITS = 0 ********** BACK SUBSTITUTION

FOR I--UK STEP -i UNTIL 1 DO -- ********** DO 720 II = i, UK

I = UK + 1 - II X = RVI (I) Y = 0.0 IF (I .EQ. UK) GO TO 700 IPI = I + i

DO 680 J = IPI, UK X = X - RMI(I,J) * RVI(J) + RM2(I,J) * RV2(J) Y = Y - RMI(I,J) * RV2(J) - RM2(I,J) * RVI(J)

CONTINUE

Z3 = CMPLX(X,Y) / CMPLX(RMI(I,I),RM2(I,I)) RVI(1) = REAL(Z3) RV2(1) = AIMAG(Z3)

CONTINUE ********** ACCEPTANCE TEST FOR EIGENVECTOR

AND NORMALIZATION ********** ITS = ITS + 1 NORM = 0.0 NORMV = 0.0

DO 780 1 = i, UK X = CABS (CMPLX(RVI (I), RV2 (I))) IF (NORMV .GE. X) GO TO 760 NORMV = X J = I NORM = NORM + X

CONTINUE

IF (NORM .LT. GROWTO) GO TO 840

247

7.1-53

********** ACCEPT VECTOR ********** X = RVI (J)

Y = RV2 (J)

820

DO 820 i = i, UK

Z3 = CMPLX(RVI(1),RV2(1)) / CMPLX(X,Y)

ZR(I,S) = REAL(Z3) ZI(I,S) = AIMAG(Z3)

CONTINUE

840

IF (UK .EQ. N) GO TO 940

J = UK + 1

GO TO 900

********** IN-LINE PROCEDURE FOR CHOOSING

A NEW STARTING VECTOR ********** IF (ITS .GE. UK) GO TO 880 X = UKROOT Y = EPS3 / (X + 1.0) RVI(1) = EPS3

DO 860 1 = 2, UK 860 RVI(I) = Y

J = UK - ITS + 1

RVI(J) = RVI(J) - EPS3 * X GO TO 660

• ********* SET ERROR -- UNACCEPTED EIGENVECTOR **********

880 J = I

IERR = -K • ********* SET REMAINING VECTOR COMPONENTS TO ZERO **********

900 DO 920 I = J, N ZR(I,S) = 0.0

Zi(I,S) = 0.0 920 CONTINUE

940 S = S + 1 980 CONTINUE

GO TO i001 C ********** SET ERROR -- UNDERESTIMATE OF EIGENVECTOR C SPACE REQUIRED **********

I000 IF (IERR .NE. 0) IERR = IERR - N IF (IERR oEQ. 0) IERR =-(2 * N + i)

I001M = S - i RETURN END

2 4 8

7.1-54

NATS PROJECT


F283-2 COMBAK

A Fortran IV Subroutine to Back Transform the Eigenvectors of that Upper Hessenberg Matrix Determined by COMHES.

May, 1972 July, 1975

I. PURPOSE.

The Fortran IV subroutine COMBAK forms the eigenvectors of a complex general matrix from the eigenvectors of that upper ~essenberg matrix determined by COMHES (F282).

2. USAGE.



SUBROUTINE COMBAK(NM,LOW, IGH,AR,AI,INT,M,ZR,ZI)



LOW, IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F271 for the details. If the matrix is not balanced, set LOW to i and IGH to the order of the matrix.

AR,AI are working precision real input two- dimensional variables with row dimension NM and column dimension at least IGH. Their lower triangles below the subdiagonal contain the multipliers which were used in

249

7.1-55

INT

M

ZR,ZI

the reduction to the Hessenberg form. The remaining upper parts of AR and AI are arbitrary. See section 3 of F282 for the details.

is an integer input one-dimensional variable of dimension at least IGH. INT identifies the rows and columns interchanged during the reduction by COMHES. See section 3 of F282 for the details.


are working precision real two-dimensional variables with row dimension NM and column dimension at least M. On input, the first M columns of ZR and ZI contain the real and imaginary parts, respectively, of the eigenvectors to be back transformed. On output, these M columns of ZR and ZI contain the real and imaginary parts of the transformed eigenvectors.


None.


This subroutine should be used in conjunction with the subroutine COMHES (F282).


Suppose that the matrix upper Hessenberg form F transformation

C (say) has been reduced to the stored in A by the similarity

-i F = G CG

where G is a product of the permutation and elementary matrices encoded in INT and in a lower triangle of A under F respectively. Then, given an array Z of column vectors, COMBAK computes the matrix product GZ. If the eigenvectors of F are columns of the array Z, then COMBAK forms the eigenvectors of C in their place.

250

7.1-56

This subroutine is a translation of the Algol procedure COMBAK written and discussed in detail by Martin and Wilkinson (I).

4. REFERENCES.

1) Martin, R.S. and Wilkinson, J.H., Similarity Reduction of a General Matrix to Hessenberg Form, Num. Math. 12,349-368 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/13, 339-358, Springer-Verlag, 1971.)

5. CHECKOUT.

A. Test Cases.


B. Accuracy.

The accuracy of COMBAK can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of complex general matrices. In these paths, this subroutine is, in practice, numerically stable (i). This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix usually close to the original matrix.

251

7.1-57

C

C

SUBROUTINE COMBAK(NM,LOW, IGH,AR,A!,INT,M,ZR,ZI)

INTEGER I,J,M,LA,MM,MP,NM,IGH,KPI,LOW,MPI REAL AR(NM,IGH),AI(NM, IGH),ZR(NM,M),ZI(NM,M) REAL XR,XI INTEGER !NT(IGN)

IF (M oEQ. 0) GO TO 200 LA = IGH - 1 KPI = LOW + 1 IF (LA .LT. KPI) GO TO 200 ********** FOR MP=IGH-I STEP -i UNTIL LOW+I DO -- ********** DO 140 MM = KPI, LA

MP = LOW + IGH - MM MPI = MP + i

DO ii0 I = MPI, IGH XR = AR(I,MP-I) Xi = AI(I,MP-I) IF (XR .EQ. 0.0 .AND. XI .EQ. 0.0) GO TO ii0

i00

DO i00 J = i, M ZR(I,J) = ZR(I,J) + XR * ZR(MP,J) - XI * ZI(MP,J) Zl(l,J) = ZI(I,J) + XR * ZI(MP,J) + Xl * ZR(MP,J)

CONTINUE

Ii0 CONTINUE

I = !NT(MP) IF (! .EQ. MP) GO TO 140

130

DO 130 J = i, M XR = ZR(I,J) ZR(I,J) = ZR(MP,J) ZR(MP,J) = XR XI = Zl(l,J) ZI(I,J) = ZI(MP,J) ZI(MP,J) = XI

CONTINUE

140 CONTINUE

200 RETURN END

252

7.1-58

NATS PROJECT


F282-2 COMHES

A Fortran IV Subroutine to Reduce a Complex General Matrix to Complex Upper Hessenberg Form Using

Elementary Transformations.

May, 1972 July, 1975

i. PURPOSE.

The Fortran IV subroutine COMHES reduces a complex general matrix to complex upper Hessenberg form using stabilized elementary similarity transformations. This reduced form is used'by other subroutines to find the eigenvalues and/or eigenvectors of the original matrix. See section 2C for the specific routines.

2. USAGE.



SUBROUTINE COMHES(NM,N,LOW~IGH,AR,AI,INT)


NM is an integer input variable set equal to the row dimension of the two-dimenslonal arrays AR and AI as specified in the DIMENSION statements for AR and AI in the calling program.

is an integer input variable set equal to the order of the matrix A = (AR,AI). N must be not greater than NM.

LOW,IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F271 for the details. If the matrix is not balanced, set LOW to 1 and IGH to N.

253

7.1-59

AR,A!

INT

are working precision real two-dimensional variables with row dimension NM and column dimension at least N. On input, AR and AI contain the real and imaginary parts, respectively, of the complex matrix of order N to be reduced to Hessenberg form. On output, AR and AI contain the real and imaginary parts of the upper Hessenberg matrix as well as the multipliers used in the reduction. See section 3 for the details.

is an integer output one-dimensional variable of dimension at least IGH identifying the rows and columns interchanged during the reduction. See section 3 for the details. Only components LOW+I through IGH-I are actually used by COMHES.

B° Error Conditions and Returns.

None°


If all the eigenvalues of the original matrix are desired, this subroutine should be followed by COMLR (F295).

If all the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by COMLR2 (F296)o

If some of the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by COMLR (F295), CINVIT (F297), and COMBAK (F283).

In this implementation, the arithmetic is real throughout except for complex division.


Suppose that the matrix A has the form

( T X Y ) = (0 B Z)

(0 0 R)

254

7.1-60

where T and R are upper triangular matrices, B is a square matrix situated in rows and columns LOW through IGH, and X, Y, and Z are rectangular matrices of the appropriate dimensions. Then the subroutine COMHES performs permutation and elementary similarity transformations to reduce B to Hessenberg form.

The Hessenberg reduction is performed in the following way. Starting with J=LOW, a permutation similarity transformation is performed to stabilize the succeeding elementary transformations in the J-th column of A. Next, each non- zero element below the subdiagonal in the J-th column of A is eliminated using elementary similarity transformations.

The permutation similarity transformation is determined by searching for the element of maximum modulus in the J-th column below the subdiagonal. This element is placed into the subdiagonal position by a row interchange and the corresponding column interchange is made to complete the permutation transformation. The index of the row interchanged with the (J+l)-th row is stored in INT(J+I).

The elementary transformation consists of elementary row operations on the J-th column of A to eliminate the non- zero elements below the diagonal and the corresponding elementary column operations to complete the similarity. The multipliersused in this elimination process are stored in place of the eliminated elements. These multipliers as well as the row interchanges stored in INT are used later in COMBAK for the back transformation of the eigenvectors.

The above steps are repeated on further columns of the transformed A until B is reduced to Hessenberg form; that is, repeated for J = LOW+I,LOW+2,...,IGH-2.

This subroutine is a translation of the Algol procedure COMHES written and discussed in detail by Martin and Wilkinson (i).

4. REFERENCES.

i) Martin, R.S. and Wilkinson, J.H., Similarity Reduction of a General Matrix to Hessenberg Form, Num. Math. 12,349-368 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinseh, Contribution II/13, 339-358, Springer-Verlag, 1971.)

255

7.1-61

5. CHECKOUT°

A. Test Cases,


B. Accuracy°

The accuracy of COMHES can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of complex general matrices. In these paths, this subroutine is, in practice, numerically stable (i). This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix usually close to the original matrix.

256

7.1-62

SUBROUTINE COMHES(NM,N,LOW, IGH,AR,AI,INT)

INTEGER I,J,M,N,LA,NM, IGH,KPI,LOW,MMI,MPI REAL AR(NM,N),AI(NM,N) REAL XR,XI,YR,YI REAL ABS INTEGER INT(IGH) COMPLEX Z3 COMPLEX CMPLX REAL REAL,AIMAG

LA = IGH - 1 KPI = LOW + 1 IF (LA .LT. KPI) GO TO 200

DO 180 M = KPI, LA MMI = M - 1

XR = 0.0 XI = 0.0 I = M

i00

DO i00 J = M, IGH IF (ABS(AR(J,MMI)) + ABS(AI(J,MMI))

.LE. ABS(XR) + ABS(XI)) GO TO i00 XR = AR(J,MMI) El = AI(J,MMI) I = J

CONTINUE

ii0

INT(M) = I IF (I .EQ. M) GO TO 130

********** INTERCHANGE ROWS AND COLUMNS OF AR AND AI ********** DO II0 J = MMI, N

YR = AR(I,J) AR(I,J) = AR(M,J) AR(M,J) = YR YI = AI(I,J) AI(I,J) = AI(M,J) AI(M,J) = YI

CONTINUE

120

130

DO 120 J = i, IGH YR = AR(J,I) AR(J,I) = AR(J,M) AR(J,M) = YR YI = AI(J,I) AI(J,I) = AI(J,M) AI(J,M) = YI

CONTINUE ********** END INTERCHANGE **********

IF (XR .EQ. 0.0 .AND. XI .EQ. 0.0) GO TO 180 MPI = M + i

257

7.1-63

DO 160 I = MPI, IGH

YR = AR(I,MMI) YI = AI(I,MMI)

IF (YR .EQ. 0.0 .AND. YI .EQ. 0.0) GO TO 160

Z3 = CMPLX(YR,YI) / CMPLX(XR,XI) YR = REAL(Z3) YI = AIMAG(Z3)

AR(I,MMI) = YR

AI(I,MMI) = YI

140

DO 140 J = M, N

AR(I,J) = AR(I,J) - YR * AR(M,J) + YI * AI(M,J)

AI(I,J) = AI(I,J) - YR * AI(M,J) - YI * AR(M,J)

CONTINUE

150

DO 150 J = I~ IGH AR(J,M) = AR(J,M) + YR * AR(J,I) - YI * AI(J,I) AI(J,M) = AI(J,M) + YR * AI(J,I) + YI * AR(J,I)

CONTINUE

160 CONTINUE

180 CONTINUE

200 RETURN

END

258

7.1-64

NATS PROJECT


F295-2 COMLR

A Fortran IV Subroutine to Determine the Eigenvalues of a Complex Upper Hessenberg Matrix.

May, 1972 July, 1975

I. PURPOSE.

The Fortran IV subroutine COMLR computes the eigenvalues of a complex upper Hessenberg matrix using the modified LR method.

2. USAGE.



SUBROUTINE COMLR(NM,N,LOW, IGH,HR,HI,WR,WI,IERR)


NM is an integer input variable set equal to the row dimension of the two-dimensional arrays HR and HI as specified in the DIMENSION statements for HR and HI in the calling program.

N is an integer input variable set equal to the order of the matrix H = (HR,HI). N must be not greater than NM.

LOW,IGR are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F271 for the details. If the matrix is not balanced, set LOW to 1 and IGH to N.

259

7.1-65

HR,HI

WR,WI

!ERR

are working precision real two-dimensional variables with row dimension NM and column dimension at least N. On input, HR and HI contain the real and imaginary parts, respectively, of the complex upper Hessenberg matrix. Note: COMLR destroys this upper Hessenberg matrix.

are working precision real output one- dimensional variables of dimension at least N containing the real and imaginary parts, respectively, of the eigenvalues of the upper Hessenberg matrix.



If more than 30 iterations are required to determine an eigenvalue~ this subroutine terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues in the WR and WI arrays should be correct for indices IERR+I,IERR+2,...,N.



To determine some of the eigenvectors of a complex Hessenberg matrix, COMLR should be followed by CiNVIT (F297) to compute those eigenvectors. Note, however, that the upper Hessenberg matrix must be saved before COMLR for later use of CINVIT, since COMLR destroys this upper Hessenberg matrix.

To determine the eigenvalues of a complex general matrix, COMLR should be preceded by COMHES (F282) to provide a suitable complex upper Hessenberg matrix for COMLR.

To determine some of the eigenvectors of a complex general matrix, COMLR should be preceded by COMHES (F282) and followed by CINVlT (F297) and COMBAK (F283). COMBAK back transforms the eigenvectors from CiNVIT into those of the complex general matrix. Note, as above, that the Hessenberg matrix must be saved before COMLR.

260

7.1-66

It is recommended in general that CBAL (F271) be used before COMHES in which case CBABK2 (F272) must be used after COMBAK if eigenvectors are computed.

The subroutine COMLR executes faster than its counterpart COMQR (F245) which uses unitary similarity transformations. COMQR is, however, more accurate in some cases. It is recommended that COMQR be used in general.

In this implementation, the arithmetic is real throughout except for complex square root and complex division.


The eigenvalues are determined by the modified LR method. The essence of this method is a process whereby a sequence of complex upper Hessenberg matrices, similar to the original Hessenberg matrix, is formed which converges to a triangular matrix. The factorization of H into upper (R) and lower (L) triangular matrices is stabilized by permutation similarity transformations at each stage. The rate of convergence of this sequence is improved by shifting the origin at each iteration. Before each iteration, the last Hessenberg form is checked for a possible splitting into submatrices. If a splitting occurs, only the lower submatrix participates in the next iteration.

The origin shift at each iteration is the eigenvalue of the lowest 2x2 principal minor closer to the second diagonal element of this minor. Whenever a lowest ixl principal submatrix finally splits from the rest of the matrix, its element is taken to be an eigenvalue of the original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of order I. The tolerances in the splitting tests are proportional to the relative machine precision.

Some of the eigenvalues may have been isolated on the diagonal by the subroutine CBAL (F271). This information is transmitted to COMLR through the parameters LOW and IGH. As a result, COMLR immediately extracts the eigenvalues in rows I to LOW-I and IGH+I to N, and so applies the LR procedure to the submatrix situated in rows and columns LOW through IGH.

This subroutine is a translation of the Algol procedure COMLR written and discussed in detail by Martin and Wilkinson (I).

261

7.1-67

4. REFERENCES.

1) Martin~ R.S. and Wilkinson, J.H., The Modified LR Algorithm for Complex Hessenberg Matrices, Num. Math. 12,369-376 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/16, 396-4039 Springer-Verlag, 1971.)

5. CHECKOUT.

A. Test Cases.


B. Accuracy°

The subroutine COMLR is usually numerically stable (I); that is, each computed eigenvalue is exact for a matrix usually close to the original upper Hessenberg matrix.

262

7.1-68

C C C C C

C

C

C C

SUBROUTINE COMLR(NM,N,LOW,IGH,HR,HI,WR,WI,IERR)

INTEGER I,J,L,M,N,EN,LL,MM,NM, IGH,IMI,ITS,LOW,MPI,ENMI,IERR REAL HR(NM,N),HI(NM,N),WR(N),WI(N) REAL SI,SR,TI,TR,XI,XR,YI,YR,ZZI,ZZR,MACHEP REAL ABS COMPLEX Z3 COMPLEX CSQRT,CMPLX REAL REAL,AIMAG


MACHEP = ?

IERR = 0 ********** STORE ROOTS ISOLATED BY CBAL ********** DO 200 I = i, N

IF (I .GE. LOW .AND. I .LE. IGH) GO TO 200 WR(1) = HR(l,l) WI(1) = HI(I,I)

200 CONTINUE

EN = IGH TR = 0.0 TI = 0.0 ********** SEARCH FOR NEXT EIGENVALUE **********

220 IF (EN .LT. LOW) GO TO I001 ITS = 0 ENMI = EN - i ********** LOOK FOR SINGLE SMALL SUB-DIAGONAL ELEMENT

FOR L=EN STEP -i UNTIL LOW -- ********** 240 DO 260 LL = LOW, EN

L = EN + LOW - LL IF (L .EQ. LOW) GO TO 300 IF (ABS(HR(L,L-I)) + ABS(HI(L,L-I)) .LE.

X MACHEP * (ABS(HR(L-I,L-I)) + ABS(HI(L-I,L-I)) X + ABS(HR(L,L)) + ABS(HI(L,L)))) GO TO 300

260 CONTINUE ********** FORM SHIFT **********

300 IF (L .EQ. EN) GO TO 660 IF (ITS .EQ. 30) GO TO I000 IF (ITS .EQ. I0 .OR. ITS .EQ. 20) GO TO 320 SR = HR(EN,EN) SI = HI(EN,EN) XR = HR(ENMI,EN) * HR(EN,ENMI) - HI(ENMI,EN) * HI(EN,ENMI) XI = HR(ENMI,EN) * HI(EN,ENMI) + HI(ENMI,EN) * HR(EN,ENMI) IF (XR .EQ. 0.0 .AND. XI .EQ. 0.0) GO TO 340 YR = (HR(ENMI,ENMI) - SR) / 2.0 YI = (HI(ENMI,ENMI) - SI) / 2.0 Z3 = CSQRT(CMPLX(YR**2-YI**2+XR,2.0*YR*YI+XI)) ZZR = REAL(Z3) ZZI = AIMAG(Z3)

263

7 . 1 - 6 9

C

C

IF (YR * ZZR + YI * ZZI ,GE. 0.0) GO TO 310

ZZR = -ZZR ZZI = -ZZI

310 Z3 = CMPLX(XR,XI) / CMPLX(YR+ZZR,YI+ZZI)

SR = SR - REAL(Z3) SI = SI - AIMAG(Z3)

GO TO 340 • ********* FORM EXCEPTIONAL SHIFT **********

320 SR = ABS(HR(EN,ENMI)) + ABS(HR(ENMI,EN-2))

SI = ABS(HI(EN,ENMI)) + ABS(HI(ENMI,EN-2))

340 DO 360 1 = LOW, EN

HR(I,I) = HR(I,I) - SR HI(I,I) = HI(I,I) - SI

360 CONTINUE

TR = TR + SR

TI = TI + SI

ITS = ITS + 1 *~******** LOOK FOR TWO CONSECUTIVE SMALL

SUB-DIAGONAL ELEMENTS **********

XR = ABS(HR(ENMI,ENMI)) + ABS(HI(ENMI,ENMI))

YR = ABS(HR(EN,ENMI)) + ABS(HI(EN,ENMI))

ZZR = ABS(HR(EN,EN)) + ABS(HI(EN,EN)) ********** FOR M=EN-! STEP -I UNTIL L DO -- **********

DO 380 MM = L~ ENMI M = ENMI + L - MM

IF (M .EQ, L) GO TO 420

YI = YR YR = ABS(HR(M,M-I)) + ABS(HI(M,M-I))

XI = ZZR ZZR = XR XR = ABS(HR(M-I,M-I)) + ABS(HI(M-I,M-I)) IF (YR .LE. MACHEP * ZZR / YI * (ZZR + XR + XI)) GO TO 420

380 CONTINUE ********** TRIANGULAR DECOMPOSITION H=L*R **********

420 MPI = M + i

440

DO 520 ! = MPI, EN IMI = I - 1

XR = HR(IMI,IMI) XI = HI(IMI,IMI) YR = HR(I,IMI)

YI = RI(~I IMl) IF (ABS(XR) + ABS(XI) .GE. ABS(YR) + ABS(YI)) GO TO 460

********** INTERCHANGE ROWS OF HR AND HI **********

DO 440 J = IMI, EN ZZR = HR(IMI,J) HR(iMI ,J) = HR(I, J) HR(I, J) = ZZR ZZI = HI(IMI,J) HI (IMI,J) = HI (I, J) HI(I,J) = ZZI

CONTINUE

264

7. 1-70

460

480

Z3 = CMPLX(XR, XI) / CMPLX(YR,YI) WR(1) = 1.0 GO TO 480 Z3 = CMPLX(YR,YI) / CMPLX(XR,XI) WR(I) = -I.0 ZZR = REAL(Z3) ZZI = AIMAG(Z3) HR(I,IMI) = ZZR HI(I,IMI) = ZZI

500

DO 500 J = I, EN HR(I,J) = HR(I,J) - ZZR * HR(IMI,J) + ZZI * HI(IMI,J) HI(I,J) = HI(I,J) - ZZR * HI(IMI,J) - ZZI * HR(IMI,J)

CONTINUE

520 CONTINUE ********** COMPOSITION R*L=H ********** DO 640 J = MPI, EN

XR = HR(J,J-I) XI = Hl(J,J-l) HR(J,J-I) = 0.0 HI(J,J-I) = 0.0

********** INTERCHANGE COLUMNS OF HR AND HI, IF NECESSARY **********

IF (WR(J) .LE. 0.0) GO TO 580

540

DO 540 I = L, J ZER = HR(I,J-I) HR(I,J-I) = HR(I,J) HR(I,J) = ZZR ZZI = HI(I,J-I) HI(I,J-I) = HI(I,~) HI(I,J) = ZZI

CONTINUE

580

600

DO 600 I = L, J HR(I,J-I) = HR(I,J-I) + XR * HR(I,J) - XI * Hl(l,J) HI(I,J-I) = HI(I,J-I) + XR * HI(I,J) + XI * HR(I,J)

CONTINUE

640 CONTINUE

GO TO 240 ********** A ROOT FOUND **********

660 WR(EN) = HR(EN,EN) + TR WI(EN) = HI(EN,EN) + TI EN = ENMI GO TO 220

C ********** SET ERROR -- NO CONVERGENCE TO AN C EIGENVALUE AFTER 30 ITERATIONS ********** I000 IERR = EN i001 RETURN

END

265

7.1-71

NATS PROJECT

EIGENSYSTEM SUBROUTINE PACKAGE (E!SPACK)

F296-2 COMLR2

A Fortran IV Subroutine to Determine the Eigenvalues and Eigenvectors of a Complex Upper Hessenberg Matrix.

May, 1972 July, 1975

i. PURPOSE.

The Fortran IV subroutine COMLR2 computes the eigenvalues and eigenvectors of a complex upper Hessenberg matrix. COMLR2 uses the modified LR method to compute the eigenvalues and accumulates the LR transformations to compute the eigenvectors. The eigenvectors of a complex general matrix can also be computed directly by COMLR2, if COMHES (F282) has been used to reduce this matrix to Hessenberg form.

2. USAGE.

A. Calling Sequence°


SUBROUTINE COMLR2(NM,N,LOW,IGH, INT,HR,HI, WR,WI,ZR,ZI,IERR)


NM is an integer input variable set equal to the row dimension of the two-dimensional arrays HR, HI, ZR, and ZI as specified in the DIMENSION statements for HR, HI, ZR, and ZI in the calling program.

is an integer input variable set equal to the order of the matrix H = (HR,HI). N must be not greater than NM.

266

7.1-72

LOW,IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F271 for the details. If the matrix is not balanced, set LOW to i and IGH to N.

INT is an integer input one-dimensional variable of dimension at least IGH. Only components LOW through IGH are used by COMLR2. If the eigenvectors of the Hessenberg matrix are desired, set INT(J)=J for J = LOW,LOW+I,...,IGH. If the eigenvectors of a complex general matrix are desired, INT contains information saved by COMHES identifying the rows and columns interchanged during the reduction to Hessenberg form.

HR,HI are working precision real two-dimensional variables with row dimension NM and column dimension at least N. On input, HR and HI contain the real and imaginary parts, respectively, of the complex upper Hessenberg matrix. If the eigenvectors of the Hessenberg matrix are desired, set the lower triangles of HR,HI below the subdiagonal to zero. If the eigenvectors of a complex general matrix are desired, the lower triangles of HR,HI contain the multipliers which are generated by COMHES in the reduction to the Hessenberg form. Note: COMLR2 destroys the upper Hessenberg portions of HR,HI, but returns in location HR(I,I) the norm of the triangularized matrix. See section 2C for the definition and significance of this quantity.

WR,WI are working precision real output one- dimensional variables of dimension at least N containing the real and imaginary parts, respectively, of the eigenvalues of the upper Hessenberg matrix.

ZR,ZI are working precision real output two- dimensional variables with row dimension NM and column dimension at least N containing the real and imaginary parts, respectively, of the eigenvectors. The eigenvectors are not normalized.

267

7. 1-73



If more than 30 iterations are required to determine an eigenvalue, this subroutine terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues in the WR and WI arrays should be correct for indices IERR+I,IERR+2,...,N, hut no eigenvectors are computed.



To determine the eigenvalues and eigenvectors of a complex general matrix, COMLR2 must be preceded by COMHES (F282) to provide a suitable complex Hessenberg matrix for COMLR2.

It is recommended in general that CBAL (F271) before COMHES in which case CBABK2 (F272) used after COMLR2.

be used must be

The subroutine COMLR2 may occasionally return poor results, especially in the eigenvectors, due to pronounced growth in the matrix elements that may occur during the LR iterations. A measure of this growth can be obtained from a comparison of the norm quantity returned in HR(I,I), defined as the sum of the absolute values of the real and imaginary components of all the elements of the triangularized matrix, with the corresponding norm of the vector of eigenvalues. This growth cannot occur in the QR algorithm embodied in subroutine COMQR2 (F246), the unitary counterpart of COMLR2. It is recommended that COMQR2, although slower, be used in general.


268

7.1-74


The eigenvalues are determined by the modified LR method. The essence of this method is a process whereby a sequence of complex upper Hessenberg matrices, similar to the original Hessenberg matrix, is formed which converges to a triangular matrix. The factorization of H into upper (R) and lower (L) triangular matrices is stabilized by permutation similarity transformations at each stage. The rate of convergence of this sequence is improved by shifting the origin at each iteration. Before each iteration, the last Hessenberg form is checked for a possible splitting into submatrices. If a splitting occurs, only the lower submatrix participates in the next iteration. The similarity transformations used in each iteration are accumulated in the ZR and ZI arrays along with the reduction transformations for the original matrix.

The origin shift at each iteration is the eigenvalue of the lowest 2x2 principal minor closer to the second diagonal element of this minor. Whenever a lowest ixl principal submatrix finally splits from the rest of the matrix, its element is taken to be an eigenvalue of the original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of order I. The tolerances in the splitting tests are proportional to the relative machine precision. The eigenvectors of this triangular matrix are determined by back substitution, and then back transformed into those of the original matrix.

Some of the eigenvalues may have been isolated on the diagonal by the subroutine CBAL (F271). This information is transmitted to COMLR2 through the parameters LOW and IGH. As a result, COMLR2 immediately extracts the eigenvalues in rows 1 to LOW-I and IGH+I to N, and so applies the LR procedure to the submatrix situated in rows and columns LOW through IGH.

This subroutine is a translation of the Algol procedure COMLR2 written and discussed in detail by Peters and Wilkinson (i).

4. REFERENCES.

i) Peters, G. and Wilkinson, J.H., Eigenveotors of Real and Complex Matrices by LR and QR Triangularizations, Num. Math. 16,181-204 (1970). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/15, 372-395, Springer-Verlag, 1971.)

269

7.1-75

5. CHECKOUT.

A. Test Cases°


B. Accuracy.

The subroutine COMLR2 is usually numerically stable (I); that is, each computed eigenvalue and its corresponding eigenvector are exact for a matrix usually close to the original upper Hessenberg matrix.

270

7.1-76

SUBROUTINE COMLR2(NM,N~LOW~IGH, INT,HR, HI,WR,WI,ZR,ZI,IERR)

INTEGER I,J,K,L,M,N,EN,II,JJ,LL,MM,NM,NN, IGH, IMI,IPI, X ITS,LOW,MPI,ENMI,IEND,IERR REAL HR(NM,N),HI(NM,N),WR(N),WI(N),ZR(NM, N),ZI(NM,N) REAL SI,SR,TI,TR,XI,XR,YI,YR,ZZI,ZZR,NORM,MACHEP REAL ABS INTEGER INT(IGH) INTEGER MIN0 COMPLEX Z3 COMPLEX CSQRT,CMPLX REAL REAL,AIMAG


MACHEP = ?

IERR = 0

**~******* INITIALIZE EIGENVECTOR MATRIX ********** DO i00 I = 19 N

DO I00 J = i, N ZR(I,J) = 0.0 zi(I,J) = o.o

IF (l .EQ. J) ZR(I,J) = 1.0 i00 CONTINUE

********** FORM THE MATRIX OF ACCUMULATED TRANSFORMATIONS FROM THE INFORMATION LEFT BY COMHES **~*******

1END = IGH - LOW - i IF (1END .LE. O) GO TO 180 ********** FOR I=IGH-I STEP -I UNTIL LOW+I DO -- ********** DO 160 II = i, 1END

I = IGH - II IPI = I + i

120

DO 120 K = IPI, IGH ZR(K,I) = HR(K,I-I) ZI(K,I) = HI(K,I-I)

CONTINUE

J = INT(1)

IF (I .EQ. J) GO TO 160

140

DO 140 K = I, IGH ZR(I,K) = ZR(J,K) ZI(I,K) = ZI(J,K) ZR(J,K) = 0.0 ZI(J,K) = 0.0

CONTINUE

ZR(~,I) = 1.0 160 CONTINUE

271

7.1-77

********** STORE ROOTS ISOLATED BY CBAL **********

180 DO 200 1 = i, N IF (! .GE. LOW .AND, I .eE. IGH) GO TO 200

WR(I) = HR(I,I) WI(I) = HI(I,I)

200 CONTINUE

EN = IGH TR = 0.0 TI = 0.0

C ********** SEARCH FOR NEXT EIGENVALUE **********

"220 IF (EN .LT. LOW) GO TO 680

ITS = 0 ENMI = EN - I

C ********** LOOK FOR SINGLE SMALL SUB-DIAGONAL ELEMENT C FOR L=EN STEP -i UNTIL LOW DO -- **********

240 DO 260 LL = LOW, EN L = EN + LOW - LL IF (L .EQ. LOW) GO TO 300 IF (ABS(HR(L,L-I)) + ABS(HI(L,L-I)) .LE.

X MACHEP * (ABS(HR(L-I,L-I)) + ABS(HI(L-I,L-I)) X + ABS(HR(L,L)) + ABS(HI(L,L)))) GO TO 300

260 CONTINUE C ********** FORM SHIFT **********

300 IF (L .EQ. EN) GO TO 660 IF (rTS .EQo 30) GO TO i000 IF (ITS .EQ. i0 .OR. ITS .EQ. 20) GO TO 320

SR = HR(EN,EN) SI = HI(EN,EN) XR = HR(ENMI,EN) * HR(EN,ENMI) - HI(ENMI,EN) * HI(EN,ENMI) XI = HR(ENMI,EN) * HI(EN,ENMI) + HI(ENMI,EN) * HR(EN,ENMI) IF (XR .EQ. 0.0 .AND. XI .EQ. 0.0) GO TO 340

YR = (HR(ENMI,ENMI) - SR) / 2.0 YI = (HI(ENMI,ENMI) - SI) / 2.0 Z3 = CSQRT(CMPLX(YR**2-YI**2+XR,2.0*YR*YI+XI))

ZZR = REAL(Z3) ZZI = AIMAG(Z3) IF (YR * ZZR + YI * ZZI .GE. 0.0) GO TO 310


310 Z3 = CMPLX(XR,XI) / CMPLX(YR+ZZR,YI+ZZI)

SR = SR - REAL(Z3) SI = SI - AIMAG(Z3) GO TO 340

C ********** FORM EXCEPTIONAL SHIFT ********** 320 SR = ABS(HR(EN,ENMI)) + ABS(HR(ENMI,EN-2))

SI = ABS(HI(EN,ENMI)) + ABS(HI(ENMI,EN-2))

340 DO 360 I = LOW, EN HR(I,I) = HR(I,I) - SR H!(i,l) = HI(I,I) - SI

360 CONTINUE

272

7 . 1 - 7 8

TR = TR + SR

TI = TI + SI

ITS = ITS + 1 ********** LOOK FOR TWO CONSECUTIVE SMALL

SUB-DIAGONAL ELEMENTS ********** XR = ABS(HR(ENMI,ENMI)) + ABS(HI(ENMI,ENMI)) YR = ABS(HR(EN,ENMI)) + ABS(HI(EN,ENMI))

ZZR = ABS(HR(EN,EN)) + ABS(HI(EN,EN))

********** FOR M=EN-I STEP -I UNTIL L DO -- ********** DO 380 MM = L, ENMI

M = ENMI + L - MM

IF (M .EQ. L) GO TO 420 YI = YR

YR = ABS(HR(M,M-I)) + ABS(HI(M,M-I)) XI = ZZR

ZZR = XR

XR = ABS(HR(M-I,M-I)) + ABS(HI(M-I,M-I))

IF (YR .LE. MACHEP * ZZR / YI * (ZZR + XR + XI)) GO TO 420 380 CONTINUE

********** TRIANGULAR DECOMPOSITION H=L*R ********** 420 MPI = M + i

440

DO 520 I = MPI, EN IMI = I - 1 XR = HR(IMI,IMI)

Xl = HI(IMI,IMI)

YR = HR(I,IMI) YI = HI(I,IMI)

IF (ABS(XR) + ABS(XI) .GE. ABS(YR) + ABS(YI)) GO TO 460 ********** INTERCHANGE ROWS OF HR AND HI **********

DO 440 J = IMI, N ZZR = HR(IMI,J) HR(IMI,J) = HR(I,J)

HR(I,J) = ZZR ZZI = HI(IMI,J) H!(IMI,J) = HI(I,J)

HI(I,J) = ZZI CONTINUE

460

480

Z3 = CMPLX(XR,XI) / CMPLX(YR,YI) WR(1) -- i. 0 GO TO 480

Z3 = CMPLX(YR,YI) / CMPLX(XR, XI) WR(I) = -i.0 ZZR = REAL(Z3)

ZZI = AIMAG(Z3) HR(I,IMI) = ZZR HI(I,IMI) = ZZI

500

DO 500 J = I, N

HR(I,J) = HR(I,J) - ZZR * HR(IMI,J) + ZZI * HI(IMI,J)

HI(I,J) = HI(I,J) - ZZR * HI(IMI,J) - ZZI * HR(IMI,J) CONTINUE

273

7.1-79

C

C

C

C

C

520 CONTINUE

********** COMPOSITION R*L=H ********** DO 640 J = MPI, EN

XR = HR(J,J-I)

XI = HI(J,J-I) HR(J,J-I) = 0.0

HI(J,J-I) = 0.0

********** INTERCHANGE COLUMNS OF HR, HI, ZR, AND ZI,

IF NECESSARY **********

IF (WR(J) .LE. 0.0) GO TO 580

540

DO 540 1 = i, J ZZR = HR(I,J-I)

HR(I,J-I) = HR(I,J)

HR(I,J) = ZZR ZZI = HI(I,J-I) HI(I,J-I) = HI(I,J)

HI(I,J) = ZZI CONTINUE

560

DO 560 I = LOW, IGH ZZR = ZR(I,J-I)

ZR(I,J-I) = ZR(I,J)

ZR(I,J) = ZZR ZZ! = ZI(I,J-I)

zI(i,J-1) = zI(i,J) ZI(I,J) = ZZ!

CONTINUE

580 DO 600 I = i, J HR(I,J-I) = HR(I,J-I) + XR * HR(I,J) - XI * HI(I,J) H!(I,J-!) = HI(I,J-I) + XR * HI(I,J) + XI * HR(I,J)

600 CONTINUE

• ********* ACCUMULATE TRANSFORMATIONS ********** DO 620 I = LOW, IGH

ZR(I,J-I) = ZR(I,J-I) + XR * ZR(I,J) - XI * ZI(I,J) Zi(I,J-I) = ZI(I,J-I) + XR * ZI(I,J) + XI * ZR(I,J)

620 CONTINUE

640 CONTINUE

GO TO 240 ********** A ROOT FOUND **********

660 HR(EN,EN) = HR(EN,EN) + TR WR(EN) = HR(EN,EN)

HI(EN,EN) = HI(EN,EN) + TI WI(EN) = Hi(EN,EN) EN = ENMI GO TO 220 ********** ALL ROOTS FOUND.

680 NORM = 0.0

BACKSUBSTITUTE TO FIND

VECTORS OF UPPER TRIANGULAR FORM **********

274

7. 1-80

DO 720 1 = I, N

DO 720 J = I, N NORM = NORM + ABS(HR(I,J)) + ABS(RI(I,J))

720 CONTINUE

HR(I,I) = NORM

IF (N .EQ. i .OR. NORM .EQ. 0.0) GO TO i001

********** FOR EN=N STEP -i UNTIL 2 DO -- ********** DO 800 NN = 2, N

EN = N + 2 - NN

XR = WR(EN)

XI = WI(EN)

ENMI = EN - i

********** FOR I=EN-I STEP -I UNTIL I DO -- **********

DO 780 II = I, ENMI I = EN - II

ZZR = HR(I,EN) ZZI = HI(I,EN)

IF (I .EQ. ENMI) GO TO 760 IPI = I + i

740

DO 740 J = IPI, ENMI

ZZR = ZZR + HR(I,J) * HR(J,EN) - HI(I,J) * HI(J,EN) ZZI = ZZI + HR(I,J) * HI(J,EN) + HI(I,J) * HR(J,EN)

CONTINUE

760

780

YR = XR - WR(1)

YI = XI - WI(1)

IF (YR .EQ. 0.0 .AND. YI .EQ. 0.0) YR = MACHEP * NORM Z3 = CMPLX(ZZR, ZZI) / CMPLX(YR,YI) HR(I,EN) = REAL(Z3) HI(I,EN) = AIMAG(Z3)

CONTINUE

C 800 CONTINUE

C ********** END BACKSUBSTITUTION ********** ENMI = N - i

C ********** VECTORS OF ISOLATED ROOTS ********** DO 840 I = I, ENMI

IF (I .GE. LOW .AND. I .LE. IGH) GO TO 840 IPI = I + 1

820

DO 820 J = IPI, N

ZR(I,J) = HR(I,J) zi(i,J) = HI(I,J)

CONTINUE

840 CONTINUE

275

7, 1-81

********** MULTIPLY BY TRANSFORMATION MATRIX TO GIVE

VECTORS OF ORIGINAL FULL MATRIX.

FOR J=N STEP -i UNTIL LOW+I DO -- **********

DO 880 JJ = LOW, ENMI

J = N + LOW - JJ

M = MIN0(J-I,IGH)

DO 880 i = LOW, IGH

ZZR = ZR(I,J)

ZZI = ZI(I,J)

860

DO 860 K = LOW, M

ZZR = ZZR + ZR(I,K) * HR(K,J) - ZI(I,K) * HI(K,J)

ZZI = ZZI + ZR(I,K) * HI(K,J) + ZI(I,K) * HR(K,J)

CONTINUE

ZR(I,J) = ZZR

ZI(i,J) = ZZI

880 CONTINUE

GO TO I001

C ********** SET ERROR -- NO CONVERGENCE TO AN

C EIGENVALUE AFTER 30 ITERATIONS **********

i000 IERR = EN

i001 RETURN

END

276

7,1-82

NATS PROJECT


F245 COMQR

A Fortran IV Subroutine to Determine the Eigenvalues of a Complex Upper Hessenberg Matrix.

July, 1975

!. PURPOSE.

The Fortran IV subroutine COMQR computes the eigenvalues of a complex upper Hessenberg matrix using the QR method.

2. USAGE.



SUBROUTINE COMQR(NM~N,LOW,IGH,HR,HI~WR,WI,IERR)


NM is an integer input variable set equal to the row dimension of the two-dimensional arrays HR and HI as specified in the DIMENSION statements for HR and HI in the calling program.


LOW, IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F271 for the details. If the matrix is not balanced, set LOW to 1 and IGH to N.

277

7 . 1 - 8 3

HR,H!

WR,WI

IERR

are working precision real two-dimensional variables with row dimension NM and column dimension at least N. On input, HR and HI contain the real and imaginary parts, respectively, of the complex upper Hessenberg matrix. Note: COMQR destroys this upper Hessenberg matrix.

are working precision real output one- dimensional variables of dimension at least N containing the real and imaginary parts, respectively, of the eigenvalues of the upper Hessenberg matrix.

is an integer output variable set equal to an error completion code described in section 2B° The normal completion code is zero.


If more than 30 iterations are required to determine an eigenva!ue, this subroutine terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues in the WR and WI arrays should be correct for indices IERR+I,IERR+2,...,N.



To determine some of the eigenvectors of a complex Hessenberg matrix, COMQR should be followed by CINVIT (F297) to compute those eigenvectors. Note, however, that the upper Hessenberg matrix must be saved before COMQR for later use of CINVIT, since COMQR destroys this upper Hessenberg matrix.

To determine the eigenvalues of a complex general matrix, COMQR should be preceded by CORTH (F244) to provide a suitable complex upper Hessenberg matrix for COMQR.

To determine some of the eigenvectors of a complex general matrix, COMQR should be preceded by CORTH (F244) and followed by CINVIT (F297) and CORTB (F247). CORTB back transforms the eigenvectors from CINVIT into those of the complex general matrix. Note, as above, that the Hessenberg matrix must be saved before COMQR.

278

7.1-84

It is recommended in general that CBAL (F271) be used before CORTH in which case CBABK2 (F272) must be used after CORTB if eigenvectors are computed.



The eigenvalues are determined by the QR method. The essence of this method is a process whereby a sequence of complex upper Hessenberg matrices, similar to the original Hessenberg matrix, is formed which converges to a triangular matrix. The rate of convergence of this sequence is improved by shifting the origin at each iteration. Before each iteration, the last Hessenberg form is checked for a possible splitting into submatrices. If a splitting occurs, only the lower submatrix participates in the next iteration.

The origin shift at each iteration is the eigenvalue of the lowest 2x2 principal minor closer to the second diagonal element of this minor. Whenever a lowest ixl principal submatrix finally splits from the rest of the matrix, its element is taken to be an eigenvalue of the original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of order i. The tolerances in the splitting tests are proportional to the relative machine precision.

The subdiagonal elements are rendered real initially by a diagonal unitary similarity transformation and maintained real throughout COMQR.

Some of the eigenvalues may have been isolated on the diagonal by the subroutine CBAL (F271). This information is transmitted to COMQR through the parameters LOW and IGH. As a result, COMQR immediately extracts the eigenvalues in rows i to LOW-1 and IGH+I to N, and so applies the QR procedure to the submatrix situated in rows and columns LOW through IGH.

This subroutine is a translation of a unitary analogue of the Algol procedure COMLR written and discussed in detail by Martin and Wilkinson (i). The unitary analogue substitutes for the LR algorithm the QR algorithm, written and discussed in detail by Francis (2).

279

7.1-85

4. REFERENCES.

i) Martin, RoS. and Wilkinson, J.H., The Modified LR Algorithm for Complex Hessenberg Matrices, Num. Math. 12,369-376 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/16, 396-403, Springer-Verlag, 1971.)

2) Francis, J.G.F., The QR Transformation - Parts 1 and 2, Comp. J. 4,265-271 and 332-345 (1961/62).

5. CHECKOUT.

A. Test Cases°


B. Accuracy~

The subroutine COMQR is numerically stable (1,2); that is, each computed eigenvalue is exact for a matrix close to the original upper Hessenberg matrix.

280

7. 1-86

SUBROUTINE COMQR(NM,N,LOW,IGH,HR,HI,WR,WI,IERR)

INTEGER I,J,L,N,EN,LL,NM,IGH, ITS,LOW~LPI,ENMI,IERR REAL HR(NM,N),HI(NM,N),WR(N),WI(N) REAL SI,SR,TI,TR,XI,XR,YI,YR,ZZI,ZZR,NORM,MACHEP REAL SQRT~CABS,ABS INTEGER MIN0 COMPLEX Z3 COMPLEX CSQRT,CMPLX REAL REAL,AIMAG


**********

MACHEP = ?

IERR = 0 IF (LOW .EQ. IGH) GO TO 180 ********** CREATE REAL SUBDIAGONAL ELEMENTS ********** L = LOW + I

DO 170 1 = L, IGH LL = MIN0(I+I,IGH) IF (HI(I,I-I) .EQ. 0.0) GO TO 170 NORM = CABS(CMPLX(HR(I,I-I),HI(I,I-I))) YR = HR(I,I-I) / NORM YI = HI(I,I-I) / NORM HR(I,I-I) = NORM HI(I,I-I) : 0.0

155

DO 155 J = I, IGH SI = YR * HI(I,J) - YI * HR(I,J) HR(I,J) : YR * HR(I,J) + YI * HI(I,J) HI(I,J) : SI

CONTINUE

160

DO 160 J = LOW, LL

SI = YR * HI(J,I) + YI * HR(J,I) HR(J,I) = YR * HR(J,I) - YI * HI(J,I) HI(J,I) = SI

CONTINUE

170 CONTINUE

********** STORE ROOTS ISOLATED BY CBAL ********** 180 DO 200 I = i, N

IF (I .GE. LOW .AND. I .LE. IGH) GO TO 200 WR(1) = HR(I,I) WI(I) = HI(I,I)

200 CONTINUE

EN = IGH TR = 0.0 TI = 0.0

281

7.1-87

C ********** SEARCH FOR NEXT EIGENVALUE ********** 220 IF (EN .LT. LOW) GO TO i001

ITS = 0 ENMI = EN - 1

C ********** LOOK FOR SINGLE SMALL SUB-DIAGONAL ELEMENT C FOR L=EN STEP -i UNTIL LOW -- **********

240 DO 260 LL = LOW, EN L = EN + LOW - LL IF (L .EQ. LOW) GO TO 300 IF (ABS(HR(L,L-I)) .LE.

X MACHEP * (ABS(HR(L-I,L-I)) + ABS(HI(L-I,L-I)) X + ABS(HR(L,L)) +ABS(HI(L,L)))) GO TO 300

260 CONTINUE

C ********** FORM SHIFT ********** 300 IF (L .EQ. EN) GO TO 660

IF (ITS .EQ. 30) GO TO I000 IF (ITS .EQ. I0 .OR. ITS .EQ. 20) GO TO 320 SR = HR(EN,EN) SI = HI(EN,EN) XR = HR(ENMI,EN) * HR(EN,ENMI) XI = HI(ENMI,EN) * HR(EN,ENMI) IF (XR .EQ. 0.0 .AND. XI .EQ. 0.0) GO TO 340 YR = (HR(ENMI,ENMI) - SR) / 2.0 YI = (HI(ENMI,ENMI) - SI) / 2.0 Z3 = CSQRT(CMPLX(YR**2-YI**2+XR,2.0*YR*YI+XI)) ZZR = REAL(Z3) ZZI = AIMAG(Z3) IF (YR * ZZR + YI * ZZI .GE. 0.0) GO TO 310


310 Z3 = CMPLX(XR,XI) / CMPLX(YR+ZZR,YI+ZZI) SR = SR - REAL(Z3)

SI = SI - AIMAG(Z3) GO TO 340


Sl = 0.0

340 DO 360 1 = LOW, EN HR(l,l) = N R ( I , I ) - SR HI(I,I) = HI(I,I) - SI

360 CONTINUE

TR = TR + SR T! = TI + SI ITS = ITS + 1 ********** REDUCE TO TRIANGLE (ROWS) **********

LPI = L + 1

282

7.1-88

DO 500 I = LPI, EN

SR = HR(I,I-I)

HR(I,I-I) = 0.0

NORM = SQRT(HR(I-I,I-I)*HR(I-I,I-I)+HI(I-I,I-I)*HI(I-I,I-I)

+SR*SR)

XR = HR(I-I,I-I) / NORM

WR(I-I) = XR

XI = HI(I-I,I-I) / NORM

wi(i-1) = El HR(I-I,I-I) = NORM

HI(I-I,I-I) = 0.0

HI(I,I-I) = SR / NORM

490

DO 490 J = I, EN

YR = HR(I-I,J)

YI = HI(I-I,J)

ZZR = HR(I,J)

ZZI = HI(I,J)

HR(I-I,J) = XR * YR + XI * YI + HI(I,I-I) * ZZR

HI(I-I,J) = XR * YI - XI * YR + HI(I,I-I) * ZZI

HR(I,J) = XR * ZZR - Xl * ZZI - HI(I,I-I) * YR

~l(l,J) = XR * ZZI + Xl ~ ZZR - HI(I,I-I) * YI

CONTINUE

500 CONTINUE

SI = HI(EN,EN)

IF (Sl .EQ. 0.0) GO TO 540

NORM = CABS(CMPLX(HR(EN,EN),SI))

SR = HR(EN,EN) / NORM

SI = SI / NORM

HR(EN,EN) = NORM

HI(EN,EN) = 0.0

********** INVERSE OPERATION (COLUMNS) ****~*****

540 DO 600 J = LPI, EN

XR = WR(J-I)

XI = WI(J-I)

560

580

DO 580 I = L, J

YR = HR(I,J-I)

YI = 0.0

ZZR = HR(I,J)

ZZI = HI(I,J)


YI = HI(I,J-I)

HI(I,J-I) = XR * YI + XI ~ YR + HI(J,J-I) * ZZI

HR(I,J-I) = XR * YR - XI * YI + HI(J,J-I) * ZZR

HR(I,J) = XR * ZZR + Xl * ZZI - HI(J,J-I) * YR

HI(I,J) = XR * ZZI - XI * ZZR - HI(J,J-I) * YI CONTINUE

600 CONTINUE

283

7. 1-89

IF (SI .EQ~ 0.0) GO TO 240

DO 630 I = L, EN YR = HR(I,EN)

Yi = HI(I,EN)

HR(I,EN) = SR * YR - SI * YI HI(I,EN) = SR * YI + SI * YR

630 CONTINUE

GO TO 240 ********** A ROOT FOUND **********

660 WR(EN) = HR(EN,EN) + TR

WI(EN) = HI(EN,EN) + TI

EN = ENMI

GO TO 220 C ********** SET ERROR -- NO CONVERGENCE TO AN


I000 IERR = EN

I001 RETURN

END

284

7.1-90

NATS PROJECT


F246 COMQR2

A Fortran IV Subroutine to Determine the Eigenvalues and Eigenvectors of a Complex Upper Hessenberg Matrix.

July , 1975

I. PURPOSE.

The Fortran IV subroutine COMQR2 computes the eigenvalues and eigenvectors of a complex upper Hessenberg matrix. COMQR2 uses the QR method to compute the eigenvalues and accumulates the QR transformations to compute the eigenvectors. The eigenvectors of a complex general matrix can also be computed directly by COMQR2, if CORTH (F244) has been used to reduce this matrix to Hessenberg form.

2. USAGE.



SUBROUTINE COMQR2(NM,N,LOW,IGH,ORTR,ORTI,HR,HI, WR,WI,ZR,ZI,IERR)


NM is an integer input variable set equal to the row dimension of the two-dimensional arrays HR, HI, ZR, and ZI as specified in the DIMENSION statements for HR, HI, ZR, and ZI in the calling program.



285

7 . 1 - 9 1

ORTR,ORT! are working precision real one-dimensional variables of dimension at least IGH. Only components LOW through IGH are used by COMQR2. If the eigenvectors of the Hessenberg matrix are desired, set ORTR(J)=ORTI(J)=0.0 for J = LOW,LOW+I,..°,IGH. If the eigenvectors of a complex general matrix are desired, ORTR and ORTI contain some information about the unitary transformations generated by CORTH during the reduction to the Hessenberg form.

HR,HI are working precision real two-dimensional variables with row dimension NM and column dimension at least N. On input, HR and HI contain the real and imaginary parts, respectively, of the complex upper Hessenberg matrix. If the eigenvectors of the Hessenberg matrix are desired, the lower triangles of HR,HI below the subdiagonal may be arbitrary. If the eigenvectors of a complex general matrix are desired, the lower triangles of HR,HI contain further information about the unitary transformations generated by CORTH in the reduction to the Hessenberg form. Note: COMQR2 destroys the upper Hessenberg portions of HR,HI.

WR,WI are working precision real output one- dimensional variables of dimension at least N containing the real and imaginary parts, respectively, of the eigenvalues of the upper Hessenberg matrix.

ZR, ZI are working precision real output two- dimensional variables with row dimension NM and column dimension at least N containing the real and imaginary parts, respectively, of the eigenvectors. The eigenvectors are not normalized.


286

7.1-92


If more than 30 iterations are required to determine an eigenvalue, this subroutine terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues in the WR and WI arrays should be correct for indices IERR+I,IERR+2,...,N, but no eigenvectors are computed.



To determine the eigenvalues and eigenvectors of a complex general matrix, COMQR2 must be preceded by CORTH (F244) to provide a suitable complex Hessenberg matrix for COMQR2.

It is recommended in general that CBAL (F271) be used before CORTH in which case CBABK2 (F272) must be used after COMQR2.



The eigenvalues are determined by the QR method. The essence of this method is a process whereby a sequence of complex upper Hessenberg matrices, similar to the original Hessenberg matrix, is formed which converges to a triangular matrix. The rate of convergence of this sequence is improved by shifting the origin at each iteration. Before each iteration, the last Hessenberg form is checked for a possible splitting into submatrices. If a splitting occurs, only the lower submatrix participates in the next iteration. The similarity transformations used in each iteration are accumulated in the ZR and ZI arrays along with the reduction transformations for the original matrix.

The origin shift at each iteration is the eigenvalue of the lowest 2x2 principal minor closer to the second diagonal element of this minor. Whenever a lowest ixl principal submatrix finally splits from the rest of the matrix, its element is taken to be an eigenvalue of the original matrix and the algorithm proceeds with the remaining submatrix.

287

7.1-93

This process is continued until the matrix has split completely into submatrices of order i. The tolerances in the splitting tests are proportional to the relative machine precision. The eigenvectors of this triangular matrix are determined by back substitution, and then back transformed into those of the original matrix.

The subdiagonal elements are rendered real initially by a diagonal unitary similarity transformation and maintained real throughout COMQR2.

Some of the eigenvalues may have been isolated on the diagonal by the subroutine CBAL (F271). This information is transmitted to COMQR2 through the parameters LOW and IGH. As a result, COMQR2 immediately extracts the eigenvalues in rows i to LOW-I and IGH+I to N, and so applies the QR procedure to the submatrix situated in rows and columns LOW through IGHo

This subroutine is a translation of a unitary analogue of the Algol procedure COMLR2 written and discussed in detail by Peters and Wilkinson (I). The unitary analogue substitutes for the LR algorithm the QR algorithm, written and discussed in detail by Francis (2).

4. REFERENCES.

i) Peters, G~ and Wilkinson, J.H., Eigenvectors of Real and Complex Matrices by LR and QR Triangularizations, Num. Math. 16,181-204 (1970). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/15, 372-395, Springer-Verlag, 1971.)

2) Francis, J.G.F., The QR Transformation - Parts 1 and 2, Comp. J. 4,265-271 and 332-345 (1961/62).

5. CHECKOUT.

A. Test Cases°


B. Accuracy.

The subroutine COMQR2 is numerically stable (1,2); that is, each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original upper Hessenberg matrix.

288

7.1-94

SUBROUTINE COMQR2(NM,N,LOW,IGH,ORTR,ORTI,HR,HI,WR,WI,ZR,ZI,IERR)

INTEGER I,J,K,L,M,N,EN,II,JJ,LL,NM,NN,IGH,IPI, X ITS,LOW,LPI,ENMI,IEND,IERR REAL HR(NM,N),HI(NM,N),WR(N),WI(N),ZR(NM,N),ZI(NM,N),

X ORTR(IGH),ORTI(IGH) REAL SI,SR, TI,TR,XI,XR,YI,YR,ZZI,ZZR,NORM,MACHEP REAL SQRT,CABS,ABS INTEGER MIN0 COMPLEX Z3 COMPLEX CSQRT,CMPLX REAL REAL,AIMAG

******~*** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.

**********

MACHEP = ?

IERR = 0

********** INITIALIZE EIGENVECTOR MATRIX ********** DO i00 I = I, N

DO I00 J = i, N ZR(I,J) = 0.0 ZI(I,J) = 0.0 IF (I .EQ. J) ZR(I,J) = 1.0

100 CONTINUE

C ********** FORM THE MATRIX OF ACCUMULATED TRANSFORMATIONS C FROM THE INFORMATION LEFT BY CORTH **********

1END = IGH - LOW - I IF (1END) 180, 150, 105

C ********** FOR I=IGH-I STEP -i UNTIL LOW+I DO -- ********** 105 DO 140 II = i, 1END

I = IGH - II

IF (ORTR(1) .EQ. 0.0 .AND. ORTI(1) .EQ. 0.0) GO TO 140 IF (HR(I,I-I) .EQ. 0.0 .AND. HI(I,I-I) .EQ. 0.0) GO TO 140

C ********** NORM BELOW IS NEGATIVE OF H FORMED IN CORTH ********** NORM = HR(I,I-I) * ORTR(1) + HI(I,I-I) * ORTI(1) IPI = I + I

Ii0

DO ii0 K = IPI, IGH ORTR(K) = HR(K,I-I) ORTI(K) = Hl(K,l-l)

CONTINUE

DO 130 J = I, IGH SR = 0.0 SI = 0.0

115

DO 115 K = I, IGH

SR = SR + 0RTR(K) * ZR(K,J) + ORTI(K) * ZI(K,J) SI = SI + ORTR(K) * ZI(K,J) - ORTI(K) * ZR(K,J)

CONTINUE

289

7.1-95

C

SR = SR / NORM

SI = SI / NORM

120

DO 120 K = I, IGH

ZR(K,J) = ZR(K,J) + SR * ORTR(K) - SI * ORTI(K) ZI(K,J) = ZI(K,J) + SR * ORTI(K) + SI * ORTR(K)

CONTINUE

130 CONTINUE

140 CONTINUE

********** CREATE REAL SUBDIAGONAL ELEMENTS ********** 150 L = LOW + 1

DO 170 I = L, IGH

LL = MINO(I+I,IGH)

IF (Hi(I,I-I) .EQ. 0.0) GO TO 170 NORM = CABS(CMPLX(HR(I,I-I),HI(I,I-I))) YR = HR(i,I-I) / NORM

YI = HI(I,I-I) / NORM ~R(I,I-I) = NORM

HI(I,I-I) = 0.0

155

DO 155 J = I, N

SI = YR * HI(I,J) - YI * HR(I,J) HR(I,J) = YR * HR(I,J) + YI * HI(I,J)

HI(I,J) = SI

CONTINUE

160

DO 160 J = I, LL

Sl = YR * HI(J,I) + YI * HR(J,I)

HR(J,I) = YR * HR(J,I) - YI * HI(J,I) HI(J,I) = SI

CONTINUE

165

DO 165 J = LOW, IGH SI = YR * ZI(J,I) + YI * ZR(J,I) zR(J,I) = YR * ZR(J,I) - ~I * ZI(J,I)

ZI(J,I) = SI CONTINUE

170 CONTINUE ********** STORE ROOTS ISOLATED BY CBAL **********

180 DO 200 I = i, N IF (I .GE. LOW .AND. I .LE. IGH) GO TO 20O WR(I) = H~(I,I)

WI(I) = HI(I,I) 200 CONTINUE

EN = IGH

TR = 0.0 TI = 0.0

290

7.1-96

C ********** SEARCH FOR NEXT EIGENVALUE **********

220 IF (EN .LT. LOW) GO TO 680 ITS = 0 ENMI = EN - i

C ********** LOOK FOR SINGLE SMALL SUB-DIAGONAL ELEMENT C FOR L=EN STEP -i UNTIL LOW DO -- **********

240 DO 260 LL = LOW, EN L = EN + LOW - LL IF (L .EQ. LOW) GO TO 300 IF (ABS(HR(L,L-I)) .LE.

X MACHEP * (ABS(HR(L-I,L-I)) + ABS(HI(L-I,L-I)) X + ABS(HR(L,L)) +ABS(HI(L,L)))) GO TO 300


300 IF (L .EQ. EN) GO TO 660 IF (ITS .EQ. 30) GO TO I000 IF (ITS .EQ. i0 .OR. ITS .EQ. 20) GO TO 320 SR = HR(EN,EN) SI = HI(EN,EN)

XR = HR(ENMI,EN) * HR(EN,ENMI) XI = HI(ENMI,EN) * HR(EN,ENMI)

IF (XR .EQ. 0.0 .AND. XI .EQ. 0.0) GO TO 340 YR = (HR(ENMI,ENMI) - SR) / 2.0

YI = (HI(ENMI,ENMI) - SI) / 2.0 Z3 = CSQRT(CMPLX(YR**2-YI**2+XR,2.0*YR*YI+XI)) ZZR = REAL(Z3) ZZI = AIMAG(Z3)

IF (YR * ZZR + YI * ZZI .GE. 0.0) GO TO 310 ZZR = -ZZR ZZI = -ZZI

310 Z3 = CMPLX(XR, XI) / CMPLX(YR+ZZR,YI+ZZI) SR = SR - REAL(Z3) SI = SI - AIMAG(Z3) GO TO 340


SI = 0.0

340 DO 360 1 = LOW, EN HR(I,I) = HR(I,I) - SR HI(I,I) = HI(I,I) - SI

360 CONTINUE

TR = TR + SR TI = TI + SI ITS = ITS + 1

********** REDUCE TO TRIANGLE (ROWS) ********** LPI = L + i

291

7.1-97

X

DO 500 ! = LPI, EN

SR = HR(I,I-I)

HR(I,I-I) = 0.0

NORM = SQRT(HR(I-I,I-I)*HR(!-I,I-I)+HI(I-I,I-I)*HI(I-I,!-I)

+SR*SR)

XR = HR(I-I,I-I) / NORM

wR(I-l) = XR

XI = HI(I-I,I-I) / NORM

wi(i-l) = xI

HR(I-I,I-I) = NORM

HI(I-I,I-I) = 0.0

HI(!,!-1) = SR / NORM

490

DO 490 J = I, N

YR = HR(I-I,J)

YI = HI(!-I,J)

ZZR = HR(I,J)

ZZI = HI(I,J)

HR(I-I,J) = XR * YR + XI * YI + HI(I,I-I) * ZZR

HI(I-I,J) = XR * YI - XI * YR + HI(I,I-I) * ZZI

HR(I,J) = XR * ZZR - XI * ZZI - HI(I,I-I) * YR

HI(I,J) = XR * ZZI + XI * ZZR - HI(I,I-I) * YI

CONTINUE

500 CONTINUE

SI = HI(EN,EN)

IF (SI .EQ. 0.0) GO TO 540

NORM = CABS(CMPLX(HR(EN,EN),SI))

SR = HR(EN,EN) / NORM

SI = SI / NORM

HR(EN,EN) = NORM

HI(EN,EN) = 0.0

IF (EN .EQ. N) GO TO 540

IPI = EN + 1

DO 520 J = IPI, N

YR = HR(EN,J)

YI = HI(EN,J)

HR(EN,J) = SR * YR + SI * YI

HI(EN,J) = SR * YI - SI * YR

520 CONTINUE

• ********* INVERSE OPERATION (COLUMNS) **********

540 DO 600 J = LPI, EN

XR = WR(J-I)

xi = wi(J-1)

DO 580 I = I, J

YR = HR(I,J-l)

YI = 0.0

ZZR = HR(I,J)

ZZI = HI(I,J)


292

7.1-98

560

580

YI = HI(I,J-I) HI(I,J-I) = XR * YI + Xl * YR + HI(J,J-I) * ZZl

HR(I,J-I) = XR * YR - XI * YI + HI(J,J-I) * ZZR

HR(I,J) = XR * ZZR + XI * ZZI - HI(J,J-I) * YR

HI(I,J) = XR * ZZI - XI * ZZR - HI(J,J-I) * YI

CONTINUE

590

DO 590 I = LOW, IGH

YR = ZR(I,J-I)

YI = ZI(I,J-I)

ZZR = ZR(I,J)

ZZI = ZI(I,J) ZR(I,J-I) = XR * YR - XI * YI + HI(J,J-I) * ZZR

ZI(I,J-I) = XR * YI + XI * YR + HI(J,J-I) * ZZI

ZR(I,J) = XR * ZZR + XI * ZZI - HI(J,J-I) * YR

ZI(I,J) = XR * ZZI - Xl * ZZR - HI(J,J-I) * YI

CONTINUE

600 CONTINUE

IF (SI .EQ. 0.0) GO TO 240

DO 630 I = i~ EN

YR = HR(I,EN)

YI = HI(I,EN)

HR(I,EN) = SR * YR - SI * YI

HI(I,EN) = SR * YI + SI * YR

630 CONTINUE

DO 640 I = LOW, IGH

YR = ZR(I,EN)

YI = ZI(I,EN)

ZR(I,EN) = SR * YR - SI * YI

ZI(I,EN) = SR * YI + SI * YR

640 CONTINUE

GO TO 240

********** A ROOT FOUND **********

660 HR(EN,EN) = HR(EN,EN) + TR

WR(EN) = HR(EN,EN)

HI(EN,EN) = HI(EN,EN) + TI

WI(EN) = HI(EN,EN)

EN = ENMI

GO TO 220

********** ALL ROOTS FOUND.

680 NORM = 0.0

BACKSUBSTITUTE TO FIND

VECTORS OF UPPER TRIANGULAR FORM **********

DO 720 1 = i, N

DO 720 J = I, N

NORM = NORM + ABS(HR(I,J)) + ABS(HI(I,J))

720 CONTINUE

293

7.1-99

IF (N oEQ. i .OR. NORM .EQ. 0.0) GO TO I001 ********** FOR EN=N STEP -i UNTIL 2 DO -- **********

DO 800 NN = 2, N

EN = N + 2 - NN

XR = WR(EN) XI = WI(EN)

ENMI = EN - 1

********** FOR I=EN-I STEP -i UNTIL 1 DO -- ********** DO 780 II = I, ENMI

I = EN - II ZZR = HR(I,EN)

ZZI = HI(I,EN) IF (I .EQ. ENMI) GO TO 760

IPI = I + i

740

DO 740 J = IPI~ ENMI ZZR = ZZR + HR(I,J) * HR(J,EN) - HI(I,J) * HI(J,EN)

ZZ! = ZZI + HR(I,J) * HI(J,EN) + HI(I,J) * HR(J,EN)

CONTINUE

760

780

YR = XR - WR(1)

YI = Xi - WI(I)

IF (YR .EQ. 0.0 .AND. YI .EQ. 0.0) YR = MACHEP * NORM Z3 = CMPLX(ZZR,ZZI) / CMPLX(YR, YI)

HR(I,EN) = REAL(Z3) HI(I,EN) = AIMAG(Z3)

CONTINUE

C 800 CONTINUE

C ********** END BACKSUBSTITUTiON **********

ENMI = N - I C ********** VECTORS OF ISOLATED ROOTS **********

DO 840 ! = i, ENMI

IF (I .GE. LOW .AND. I .LE. IGH) GO TO 840

IPI = I + i

820

DO 820 J = IPI, N

ZR(!,J) = HR(I,J) ZI(I,J) = Hl(l,J)

CONTINUE

840 CONTINUE ********** MULTIPLY BY TRANSFORMATION MATRIX TO GIVE


FOR J=N STEP -I UNTIL LOW+I DO -- **********

DO 880 JJ = LOW, ENMI J = N + LOW - JJ M = MIN0(J-I,IGH)

DO 880 I = LOW, IGH ZZR = ZR(I,J) ZZI = ZI(I,J)

294

7 . 1 - 1 0 0

860

DO 860 K = LOW, M

ZZR = ZZR + ZR(I,K) * HR(K,J) - ZI(I,K) * HI(K,J)

ZZI = ZZI + ZR(I,K) * HI(K,J) + ZI(I,K) * HR(K,J) CONTINUE

ZR(I,J) = ZZR

ZI(I,J) = ZZI 880 CONTINUE

GO TO i001

C ********** SET ERROR -- NO CONVERGENCE TO AN C EIGENVALUE AFTER 30 ITERATIONS ********** i000 IERR = EN

i001 RETURN

END

295

7.1-101

NATS PROJECT


F247 CORTB

A Fortran IV Subroutine to Back Transform the Eigenvectors of that Upper Hessenberg Matrix Determined by CORTH.

July, 1975

I. PURPOSE.

The Fortran IV subroutine CORTB forms the eigenvectors of a complex general matrix from the eigenvectors of that upper Hessenberg matrix determined by CORTH (F244).

2. USAGE.



SUBROUTINE CORTB(NM,LOW, IGH,AR,AI,ORTR,ORTI, M,ZR,ZI)



LOW, IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F271 for the details. If the matrix is not balanced, set LOW to i and IGH to the order of the matrix.

AR,AI are working precision real input two- dimensional variables with row dimension NM and column dimension at least IGH. Their lower triangles contain some information about the unitary transformations used in

296

7.1-i02

the reduction to the Hessenberg form. The remaining upper parts of AR and AI are arbitrary. See section 3 of F244 for the details.

ORTR,ORTI are working precision real one-dimensional variables of dimension at least IGH. On input, ORTR and ORTI contain further information about the unitary transformations used in the reduction by CORTH. See section 3 of F244 for the details. ORTR and ORTI are used for temporary storage within CORTB and are not restored.

M is an integer input variable set equal to the number of columns of Z = (ZR,ZI) to be back transformed.

ZR,ZI are working precision real two-dimensional variables with row dimension NM and column dimension at least M. On input, the first M columns of ZR and ZI contain the real and imaginary parts, respectively, of the eigenvectors to be back transformed. On output, these M columns of ZR and ZI contain the real and imaginary Parts of the transformed eigenvectors.


None.


This subroutine should be used in conjunction with the subroutine CORTH (F244).



c (say) has been reduced to the stored in A by the similarity

F = Q CQ

297

7.1-103

where Q is a product of the unitary matrices encoded in ORTR,ORTI and in a lower triangle of A under F. Then, given an array Z of column vectors, CORTB computes the matrix product QZ. If the eigenvectors of F are columns of the array Z, then CORTB forms the eigenvectors of C in their place.

This subroutine is a translation of a complex analogue of the Algol procedure ORTBAK written and discussed in detail by Martin and Wilkinson (i).

4. REFERENCES.

I) Martin~ R.S. and Wilkinson, J.H., Similarity Reduction of a General Matrix to Hessenberg Form, Num. Math. 12,349-368 (1968)o (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution II/13~ 339-358, Springer-Verlag, 1971.)

5. CHECKOUT.

A. Test Cases~


B. Accuracy.

The accuracy of CORTB can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of complex general matrices. In these paths, this subroutine is numerically stable (i). This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original matrix.

298

7.1-104

C

C

SUBROUTINE CORTB(NM,LOW,IGH,AR,AI,ORTR,ORTI,M,ZR,ZI)

INTEGER I,J,M,LA,MM,MP,NM,IGH,KPI,LOW,MPI

REAL AR(NM, IGH),AI(NM,IGH),ORTR(IGH),ORTI(IGH),ZR(NM,M),ZI(NM,M) REAL H,GI,GR

IF (M .EQ. 0) GO TO 200 LA = IGH - 1 KPI = LOW + I IF (LA .LT. KPI) GO TO 200

********** FOR MP=IGH-I STEP -i UNTIL LOW+I DO -- ********** DO 140 MM = KPI, LA

MP = LOW + IGH - MM IF (AR(MP,MP-I) .EQ. 0.0 .AND. AI(MP,MF-I) .EQ. 0.0)

X GO TO 140

********** H BELOW IS NEGATIVE OF H FORMED IN CORTH ********** H = AR(MP,MP-I) * ORTR(MP) + AI(MP,MP-1) * ORTI(MP) MPI = MP + 1

100

DO i00 I = MPI, IGH ORTR(1) = AR(I,MP-I)

ORTI(1) = AI(I,MP-I) CONTINUE

DO 130 J = i, M

GR = 0.0 GI = 0.0

Ii0

DO Ii0 1 = MP, IGH

GR = GR + ORTR(1) * ZR(I,J) + ORTI(1) * ZI(I,J) GI = GI + ORTR(1) * ZI(I,J) - ORTI(1) * ZR(I,J)

CONTINUE

GR = GR / H

GI = GI / H

120

DO 120 I = MP, IGH

ZR(I,J) = ZR(I,J) + GR * ORTR(I) - GI * ORTI(1) ZI(I,J) = ZI(I,J) + GR * ORTI(1) + GI * ORTR(1)

CONTINUE

130 CONTINUE

140 CONTINUE

200 RETURN END

299

7.1-105

NATS PROJECT

EiGENSYSTEM SUBROUTINE PACKAGE (EISPACK)

F244 CORTH

A Fortran IV Subroutine to Reduce a Complex General Matrix to Upper Hessenberg Form Using Unitary Transformations.

July, 1975

i. PURPOSE.

The Fortran IV subroutine CORTH reduces a complex general matrix to complex upper Hessenberg form using unitary similarity transformations. This reduced form is used by other subroutines to find the eigenvalues and/or eigenvectors of the original matrix. See section 2C for the specific routines.

2. USAGE.

A, Calling Sequence,


SUBROUTINE CORTH(NM,N,LOW, IGH,AR,AI,ORTR,ORTI)

The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification°


N is an integer input variable set equal to

the order of the matrix A = (AR,AI). N must be not greater than NM.

LOW,IGH are integer input variables indicating the boundary indices for the balanced matrix, See section 3 of F271 for the details. If the matrix is not balanced, set LOW to I and IGH to N.

300

7.1-106

AR,AI are working precision real two-dimensional variables with row dimension NM and column dimension at least N. On input, AR and AI contain the real and imaginary parts, respectively, of the complex matrix of order N to be reduced to Hessenberg form. On output, AR and AI contain the real and imaginary parts of the upper Hessenberg matrix as well as some information about the unitary transformations used in the reduction. See section 3 for the details.

ORTR,ORTI are working precision real output one- dimensional variables of dimension at least IGH containing the remaining information about the unitary transformations. See section 3 for the details. Only components LOW+I through IGH are actually used by CORTH.


None.


If all the eigenvalues of the original matrix are desired, this subroutine should be followed by COMQR (F245).

If all the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by COMQR2 (F246).

If some of the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by COMQR (F245), CINVIT (F297), and CORTB (F247).

If the matrix has elements of widely varying magnitudes, the larger ones should be in the top left-hand corner.


Suppose that the matrix A = (AR,AI)

(T X Y) A = ( 0 B Z )

(0 0 R)

has the form

301

7.1-!07

where T and R are upper triangular matrices, B is a square matrix situated in rows and columns LOW through IGH, and X, Y, and Z are rectangular matrices of the appropriate dimensions. Then the subroutine CORTH performs unitary similarity transformations to reduce B to Hessenberg form.

The Hessenberg reduction is performed in the following way. Starting with J=LOW, the elements in the J-th column below the diagonal are first scaled, to avoid possible underflow in the transformation that might result in severe departure from orthogonality. The sum of squared magnitudes SIGMA of these scaled elements is next formed. Then, a vector U and a scalar

H = U U/2

define an operator

P = I - UU /H

which is unitary and Hermitian and for which the similarity transformation PAP eliminates the elements in the J-th column of A below the subdiagonal.

The non-zero components of U are the elements of the J-th column below the diagonal with the first of them augmented by the square root of SIGMA times the subdiagonal element divided by its magnitude. By saving this component in the array 0RTR,ORTI and not overwriting the column elements eliminated in the transformation~ full information on P is saved for later use in COMQR2 and CORTB.

The transformation replaces the subdiagonal element with the square root of SIGMA times the negative of the replaced element divided by its magnitude.


This subroutine is a translation of a complex analogue of the Algol procedure ORTHES written and discussed in detail by Martin and Wilkinson (I).

302

7.1-108

4. REFERENCES.

1) Martin, R.S. and Wilkinson, J.H., Similarity Reduction of a General Matrix to Hessenberg Form, Num. Math. 12,349-368 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/13, 339-358, Springer-Verlag, 1971.)

5. CHECKOUT.

A. Test Cases.


B. Accuracy.

The accuracy of CORTH can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of complex general matrices. In these paths, this subroutine is numerically stable (i). This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original matrix.

303

7.1-109

90

i00

SUBROUTINE CORTH(NM,N,LOW, IGH,AR,AI,ORTR,ORTI)

INTEGER I,J,M,N,!I,JJ,LA,MP,NM, IGH,KPI,LOW

REAL AR(NM,N),AI(NM,N),ORTR(IGH),ORTI(IGH)

REAL F,G,H,FI,FR,SCALE

REAL SQRT,CABS,ABS

COMPLEX CMPLX

LA = IGH - 1

KPI = LOW + 1

IF (LA .LT. KPI) GO TO 200

DO 180 M = KPI, LA

H = 0.0 ORTR(M) = 0.0

ORTI(M) = 0.0 SCALE = 0 ~ 0

********** SCALE COLUMN (ALGOL TOL THEN NOT NEEDED) **********

DO 90 1 = M, IGH SCALE = SCALE + ABS(AR(I,M-I)) + ABS(AI(I,M-I))

IF (SCALE .EQ. 0.0) GO TO 180

MP = M + IGH ********** FOR I=IGH STEP -i UNTIL M DO -- **********

DO i00 II = M, IGH I = MP - II

ORTR(1) = AR(I,M-I) / SCALE ORTI(1) = AI(I,M-I) / SCALE H = H + ORTR(i) * ORTR(1) + ORrl(1) * ORTI(1)

CONTINUE

G = SQRT (H) F = CABS(CMPLX(ORTR(M),ORTI(M)))

IF (F .EQ. 0.0) GO TO 103

H = H + F * G

g = g / F ORTR(M) = (i.0 + G) * ORTR(M)

ORTI(M) = (i.0 + G) * ORTI(M)

GO TO 105

103 ORTR(M) = G AR(M,M-I) = SCALE

********** FORM (I-(U*UT)/H) * A **********

105 DO 130 J = M, N FR = 0.0 FI = 0 . 0

********** FOR I=IGH STEP -i UNTIL M DO -- **********

DO II0 II = M, IGH

I = MP - II FR = FR + ORTR(I) * AR(I,J) + ORTI(I) * AI(I,J)

FI = FI + ORTR(I) * AI(I,J) - ORTI(I) * AR(I,J)

II0 CONTINUE

304

7.1-110

FR = FR / H

FI = FI / H

120

DO 120 1 = M, IGH

AR(I,J) = AR(I,J) - FR * ORTR(1) + FI * ORTI(1)

AI(I,J) = AI(I,J) - FR ~ ORTI(1) - FI * ORTR(1)

CONTINUE

130 CONTINUE

~**~**** FORM (I-(U*UT)/H)*A*(I-(U*UT)/H) ***~*~***

DO 160 I = I s IGH

FR = 0.0

FI = 0.0

*******~** FOR J=IGH STEP -I UNTIL M DO -- *~**~****

DO 140 JJ = M, IGH

J = MP - JJ

FR = FR + ORTR(J) * AR(I,J) - ORTI(J) * AI(I,J)

FI = FI + ORTR(J) * AI(I,J) + ORTI(J) * AR(I,J) 140 CONTINUE

FR = FR / H

FI = FI / H

150

DO 150 J = M, IGH

AR(I,J) = AR(I,J) - FR * ORTR(J) - FI * ORTI(J)

AI(I,J) = AI(I,J) + FR * ORTI(J) - FI * ORTR(J)

CONTINUE

160 CONTINUE

ORTR(M) = SCALE * ORTR(M)

ORTI(M) = SCALE * ORTI(M)

AR(M,M-I) = -G * AR(M,M-I)

AI(M,M-I) = -G * AI(M,M-I)

180 CONTINUE

200 RETURN

END

305

7.1-111

NATS PROJECT


F274-2 ELMBAK

A Fortran IV Subroutine to Back Transform the Eigenvectors of that Upper Hessenberg Matrix Determined by ELMHES.

May, 1972 July, 1975

1. PURPOSE,

The Fortran IV subroutine ELMBAK forms the eigenvectors of a real general matrix from the eigenvectors of that upper Hessenberg matrix determined by ELMHES (F273).

2. USAGE.

A° Calling Sequence.


SUBROUTINE ELMBAK(NM, LOW,IGH,A, INT,M,Z)


NM is an integer input variable set equal to the row dimension of the two-dlmensional arrays A and Z as specified in the DIMENSION statements for A and Z in the calling program,

LOW, IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F269 for the details. If the matrix is not balanced, set LOW to I and IGH to the order of the matrix.

is a working precision real input two- dimensional variable with row dimension NM and column dimension at least IGH. Its lower triangle below the subdiagonal contains the multipliers which were used in the reduction to the Hessenberg form. The remaining upper part of A is arbitrary. See section 3 of F273 for the details.

306

7.1-112

INT is an integer input one-dimensional variable of dimension at least IGH. INT identifies the rows and columns interchanged during the reduction by ELMHES. See section 3 of F273 for the details.




None.


This subroutine should be used in conjunction with the subroutine ELMHES (F273).

The real and imaginary parts of an eigenvector need not be stored in consecutive columns of Z.




-i F = G CG

where G is a product of the permutation and elementary matrices encoded in INT and in a lower triangle of A under F respectively. Then, given an array Z of column vectors, ELMBAK computes the matrix product GZ. If the real and imaginary parts of the eigenvectors of F are columns of the array Z, then ELMBAK forms the eigenvectors of C in their place.

307

7.1-113

This subroutine is a translation of the Algol procedure ELMBAK written and discussed in detail by Martin and Wilkinson (i).

4o REFERENCES.

I) Martin, RoS. and Wilkinson~ J.H., Similarity Reduction of a General Matrix to Hessenberg Form, Num. Math. 12,349-368 (1968). (Reprinted in Handbook for $utomatie Computation, Volume II, Linear Algebra, J, H. Wilkinson - C. Reinsch, Contribution 11/13, 339-358, Springer-Verlag, 1971.)

5. CHECKOUT.

Ao Test Cases~


B. Accuracy~

The accuracy of ELMBAK can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real general matrices. In these paths, this subroutine is, in practice, numerically stable (i). This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original matrix.

308

7.1-114

SUBROUTINE ELMBAK(NM~LOW, IGH,A, INT,M,Z)

INTEGER I,J,M, LA,MM,MP,NM, IGH,KPI,LOW,MPI

REAL A(NM,IGH),Z(NM,M) REAL X INTEGER INT(IGH)

IF (M .EQ. 0) GO TO 200 LA = IGH - i KPI = LOW + i IF (LA .LT. KPI) GO TO 200 ********** FOR MP=IGH-I STEP -i UNTIL LOW+I DO -- ********** DO 140 MM = KPI, LA

MP = LOW + IGH - MM MPI = MP + i

DO ii0 I = MPI, IGH X = A(I,MP-I) IF (X .EQ. 0.0) GO TO ii0

i00 DO i00 J = i, M Z(I,J) = Z(I,J) + X * Z(MP,J)

ii0 CONTINUE

I = INT(MP) IF (I .EQ. MP) GO TO 140

130

DO 130 J = I, M X = Z(I,J) Z(I,J) = Z(MP,J) Z(MP,J) = X

CONTINUE

140 CONTINUE

200 RETURN END

309

7.1-115

NATS PROJECT


F273 ELMHES

A Fortran IV Subroutine to Reduce a Real General Matrix to Upper Hessenberg Form Using Elementary Transformations.

May, 1972

i. PURPOSE.

The Fortran IV subroutine ELMHES reduces a real general matrix to upper Hessenberg form using stabilized elementary similarity transformations. This reduced form is used by other subroutines to find the eigenvalues and/or eigenvectors of the original matrix. See section 2C for the specific routines.

2. USAGE.



SUBROUTINE ELMHES(NM,N,LOW, IGH,A, INT)



N is an integer input variable set equal to the order of the matrix A. N must be not

greater than NM.

LOW, IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F269 for the details. the matrix is not balanced, set LOW to and IGH to N.

If 1

310

7.1-I16

INT

is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. On input, A contains the matrix of order N to be reduced to Hessenberg form. On output, A contains the upper Hessenberg matrix as well as the multipliers used in the reduction. See section 3 for the details.

is an integer output one-dimensional variable of dimension at least IGH identifying the rows and columns interchanged during the reduction. See section 3 for the details. Only components LOW+I through IGH-I are actually used by ELMHES.


None.


If all the eigenvalues of the original matrix are desired, this subroutine should be followed by HQR (F286).

If all the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by ELTRAN (F220) and HQR2 (F287).

If some of the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by HQR (F286), INVIT (F288), and ELMBAK (F274).

The subroutine ELMHES executes faster than its counterpart ORTHES (F275), which uses orthogonal similarity transformations. ORTHES is, however, more accurate in some cases. It is recommended that ELMHES be used in general.



( T X Y ) = (0 B Z)

(0 0 R)

311

7.1-117

where T and R are upper triangular matrices, B is a square matrix situated in rows and columns LOW through IGH, and X, Y, and Z are rectangular matrices of the appropriate dimensions. Then the subroutine ELMHES performs permutation and elementary similarity transformations to reduce B to Hessenberg form.

The Hessenberg reduction is performed in the following way. Starting with J=LOW, a permutation similarity transformation is performed to stabilize the succeeding elementary transformations in the J-th column of A. Next, each non- zero element below the subdiagonal in the J-th column of A is eliminated using elementary similarity transformations.

The permutation similarity transformation is determined by searching for the element of maximum modulus in the J-th column below the subdiagonal. This element is placed into the suhdiagonal position by a row interchange and the corresponding column interchange is made to complete the permutation transformation. The index of the row interchanged with the (J+l)-th row is stored in INT(J+I).

The elementary transformation consists of elementary row operations on the J-th column of A to eliminate the non- zero elements below the subdiagonal and the corresponding elementary column operations to complete the similarity. The multipliers used in this elimination process are stored in place of the eliminated elements. These multipliers as well as the row interchange information in INT are used later in ELTRAN for the accumulation of the transformations and in ELMBAK for the back transformation of the eigenvectors,

The above steps are repeated on further columns of the transformed A untii B is reduced to Hessenberg form; that is, repeated for J = LOW+I,LOW+2,...,IGH-2.

This subroutine is a translation of the Algol procedure ELMHES written and discussed in detail by Martin and Wilkinson (I).

4. REFERENCES.

I) Martin, R.S. and Wilkinson, J.H., Similarity Reduction of a General Matrix to Hessenberg Form, Num. Math. 12,349-368 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/13, 339-358, Springer-Verlag, 1971.)

312

7.1-118

5. CHECKOUT.

A. Test Cases.


B. Accuracy.

The accuracy of ELMHES can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real general matrices. In these paths, this subroutine is, in practice, numerically stable (I). This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original matrix.

313

7.1-119

C

i00

Ii0

120

130

140

150

160

SUBROUTINE ELMHES(NM,N,LOW,IGH,A,INT)

INTEGER I,J,M,N,LA,NM,IGH,KPI,LOW,MM1,MPI REAL A(NM,N) REAL X,Y

REAL ABS

INTEGER INT(IGH)

LA = IGH - 1

KPI = LOW + 1


DO 180 M = KPI, LA

MMI = M - i X = 0.0

I = M

DO i00 J = M, IGH IF (ABS(A(J,MMI)) .LE. ABS(X)) GO TO i00

X = A(J,MMI)

! = J

CONTINUE

INT (M) = I IF (I .EQ. M) GO TO 130

****22***2 INTERCHANGE ROWS AND COLUMNS OF A **,2,2,~,2

DO II0 J = MMI, N

Y = A(I,J)

A(I,J) = A(M,J) A(M,J) = Y

CONTINUE

DO 120 J = i, !GH

Y = A(J,I) A(J,I) = A(J,M)

A(J,M) = Y CONTINUE

********** END INTERCHANGE ********** IF (X .EQ. 0.0) GO TO 180

MPI = M + 1

DO 160 1 = MPI, IGH Y = A(I,MMI) IF (Y .EQ. 0.0) GO TO 160

Y = Y / X A(I,MMI) = Y

DO 140 J = M, N A(I,J) = A(I,J) - Y * A(M,J)

DO 150 J = i, IGH A(J,M) = A(J,M) + Y * A(J,I)

CONTINUE

3t4

7.1-120

C 180 CONTINUE

C 200 RETURN

END

315

7. 1-121

NATS PROJECT


F220 ELTRAN

A Fortran IV Subroutine to Accumulate the Transformations in the Reduction of a Real General Matrix by ELMHES.

May, 1972

I. PURPOSE.

The Fortran IV subroutine ELTRAN accumulates the stabilized elementary similarity transformations used in the reduction of a real general matrix to upper Hessenberg form by ELMHES (F273).

2. USAGE.



SUBROUTINE ELTRAN(NM,N,LOW,IGH,A,INT,Z)


NM is an integer input variable set equal to the row dimension of the two-dimensional arrays A and Z as specified in the DIMENSION statements for A and Z in the calling program.

N is an integer input variable set equal to the order of the matrix A. N must be not greater than NM.


316

7.1-122

A

INT

is a working precision real input two- dimensional variable with row dimension NM and column dimension at least IGH. Its lower triangle below the subdiagonal contains the multipliers which were used in the reduction to the Hessenberg form. The remaining upper part of A is arbitrary. See section 3 of F273 for the details.

is an integer input one-dimensional variable of dimension at least IGH. INT identifies the rows and columns interchanged during the reduction by ELMHES. See section 3 of F273 for the details.

is a working precision real output two- dimensional variable with row dimension NM and column dimension at least N. It contains the transformation matrix produced in the reduction by ELMHES to the upper Hessenberg form.


None.


If all the eigenvalues and eigenvectors of the original matrix are desired, this subroutine follows ELMHES (F273) and should be followed by HQR2 (F287). Otherwise, this subroutine will not ordinarily be used.




-I F = G CG

where G is a product of the permutation and elementary matrices encoded in INT and in a lower triangle of A under F respectively. Then, ELTRAN accumulates G the array Z.

This subroutine is a translation of the Algol procedure ELMTRANS written and discussed in detail by Peters and Wilkinson (i).

into

317

7.1-123

4. REFERENCES.

i) Peters, G. and Wilkinson, J.H., Eigenvectors of Real and Complex Matrices by LR and QR Triangularizations, Num. Math. 16,181-204 (1970). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/15, 372-395, Springer-Verlag, 1971.)

5. CHECKOUT.

A. Test Cases.


B. Accuracy.

ELTRAN introduces no rounding errors since it only transfers the multipliers used in the reduction process into the eigenvector matrix.

318

7.1-124

C C

C

SUBROUTINE ELTRAN(NM,N,LOW~IGH,A, INT,Z)

INTEGER I~J,N,KL,MMDMP,NM,IGHjLOW~MPI REAL A(NM,IGH),Z(NM,N) INTEGER INT(IGH)

**mmmmm,,, INITIALIZE Z TO IDENTITY MATRIX ,mmm,m,mm, DO 80 I = lj N

DO 60 J = i, N 60 Z(l,J) = 0.0

Z(I,I) = 1.0 80 CONTINUE

KL = IGH - LOW - 1 IF (EL .LT. i) GO TO 200

*********m FOR MP=IGH-I STEP -I UNTIL LOW+I DO -- ********** DO 140 MM = i, KL

MP = IGH - MM MPI = MP + I

i 0 0 DO i00 I = MPI~ IGH Z(I,MP) = A(I,MP-I)

I = INT(MP) IF (I .EQ~ MP) GO TO 140

130

DO 130 J = MP, IGH Z(MP,J) = Z(I,J) Z(I,J) = 0.0

CONTINUE

Z(I,MP) = 1.0 140 CONTINUE

200 RETURN END

319

7.1-125

NATS PROJECT


F280-2 FIGI

A Fortran IV Subroutine to Transform a Certain Real Non-Symmetric Tridiagonal Matrix to a

Symmetric Tridiagonal Matrix.

May, 1972 July, 1975

I. PURPOSE.

The Fortran IV subroutine FIGI transforms a certain real non-symmetric tridiagonal matrix to a symmetric tridiagonal matrix. The property of the non-symmetric matrix required for use of this subroutine is that the products of pairs of corresponding off-diagonal elements be all non-negative. The transformed matrix is used by other subroutines to find the eigenvalues and/or eigenvectors of the original matrix. See section 2C for the specific routines.

2. USAGE.



SUBROUTINE FIGI(NM,N,T,D,E,E2,1ERR)


NM is an integer input variable set equal to the row dimension of the two-dimensional array T as specified in the DIMENSION statement for T in the calling program.

is an integer input variable set equal to the order of the matrix T. N must be not greater than NM.

320

7.1-126

E2

IERR

is a working precision real input two- dimensional variable with row dimension NM and column dimension at least 3. T contains the non-symmetric tridiagonal matrix of order N in its first three columns. The subdiagonal elements are stored in the last N-I positions of the first column. The diagonal elements are stored in the second column. The superdiagonal elements are stored in the first N-I positions of the third column. Elements T(I,I) and T(N,3) are arbitrary.

is a working precision real output one- dimensional variable of dimension at least N containing the diagonal elements of the tridiagonal symmetric matrix.

is a working precision real output one- dimensional variable of dimension at least N containing, in its last N-I positions, the subdiagonal elements of the tridiagonal symmetric matrix. The element E(1) is not referenced.

is a working precision real output one- dimensional variable of dimension at least N containing, in its last N-I positions, the squares of the subdiagonal elements of the tridiagonal symmetric matrix. The element E2(1) is not referenced. E2 need not be distinct from E (non-standard usage acceptable with at least those compilers included in the certification statement) s in which case no squares are returned.



If the product of T(I,I) and T(I-I,3) is negative, FIGI terminates with IERR set to N+I. In this case, a symmetric matrix cannot be produced with this program.

If the product of T(I,I) and T(I-I,3) is zero but either T(I,I) or T(I-I,3) is not zero, FIGI sets IERR to -(3*N+I) and continues. If this occurs more than once, the last occurrence is recorded in IERR. See section 3.

321

7.1-127

If the products of all pairs of corresponding off- diagonal elements are non-negative, and zero only when both factors are zero, IERR is set to zero.


If all the eigenva!ues of the original matrix are desired, this subroutine should he followed by IMTQLI (F291).

If some of the eigenvalues of the original matrix are desired, this subroutine should be followed by BISECT (F294) or TRIDIB (F237).

If some of the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by TSTURM (F293), or by BISECT (F294) and TINVIT (F223), or by TRIDIB (F237) and TINVIT, or by !MTQLV (F234) and TINVlT, and then by BAKVEC (F281).

If all the eigenvalues and eigenvectors of the original matrix are desired, subroutine FIGI2 (F222) should be used rather than FIGI to perform the symmetrization, and should be followed by IMTQL2 (F292).


The transformation is performed in the following way° If the products of pairs of corresponding off-diagonal elements of T are all positive or if both elements are zero, a non- singular diagonal matrix V can be defined such that the similarity transformation

-i V TV

produces a symmetric tridiagona! matrix with diagonal D and subdiagonal E as follows:

D(J) = T(J,2), J:I,2,3, .... N, E(J) = SQRT(T(J,I) * T(J-I,3)), J:2,3, .... N.

The diagonal elements of the transformation matrix V are as follows:

v ( 1 , 1 ) : i . o ,

and for J=2,3,...,N V(J,J) = V(J-I,J-I) * SQRT(T(J,I) / T(J-I,3))

if T(J,I) * T(J-I,3) is positive, or

V(J,J) = 1.0 if both T(J,I) and T(J-I,3) are zero.

322

7.1-128

If the product of a pair of corresponding off-diagonal elements is zero but only one of the elements is zero, then the symmetric tridiagonal matrix defined above has the same eigenvalues as T but its eigenvectors are not simply related to those of T. In this case, the back transformation subroutine BAKVEC (F281), if called, will set an error flag indicating that the computed eigenvectors are not valid.

This subroutine is an implementation of the algorithm discussed in detail by Wilkinson (I).

4. REFERENCES.


5. CHECKOUT.

A. Test Cases.


B. Accuracy.

The accuracy of FIGI can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of certain real non- symmetric tridiagonal matrices. In these paths, this subroutine is numerically stable (I). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.

323

7.1-129

SUBROUTINE FIGI(NM,N,T,D,E,E2,1ERR)

INTEGER I,N,NM,IERR REAL T(NM, 3) ,D (N), E (N), E2 (N) REAL SQRT

IERR = 0

DO I00 1 = !~ N IF (I .EQ. i) GO TO 90 E2(1) = T(I,I) * T(I-I,3) IF (E2(1)) I000, 60, 80 IF (r(l,l) .EQ. 0.0 .AND. r(l-l,3) .EQ. 0.0) GO TO 80 6O

********** SET ERROR -- PRODUCT OF SOME PAIR OF OFF-DIAGONAL ELEMENTS IS ZERO WITH ONE MEMBER NON-ZERO **********

IERR = -(3 * N + I) 80 E(1) = SQRT(E2(1)) 90 D(1) = T(I,2)

i00 CONTINUE

GO TO I001 ********** SET ERROR -- PRODUCT OF SOME PAIR OF OFF-DIAGONAL

ELEMENTS IS NEGATIVE ********** i000 IERR = N + I I001 RETURN

END

324

7.1-130

NATS PROJECT


F222 FIGI2

A Fortran IV Subroutine to Transform a Certain Real Non-Symmetric Tridiagonal Matrix to a Symmetric Tridiagonal Matrix

Accumulating the Diagonal Transformations.

May, 1972

i. PURPOSE.

The Fortran IV subroutine FIGI2 transforms a certain real non-symmetric tridiagonal matrix to a symmetric tridiagonal matrix using and accumulating diagonal similarity transformations. The property of the non-symmetric matrix required for use of this subroutine is that the products of pairs of corresponding off-diagonal elements be all non- negative, and zero only when both factors are zero. The symmetrized matrix and the transformation matrix are used by subroutine IMTQL2 (F292) to find the eigenvalues and eigenvectors of the original matrix.

2. USAGE.



SUBROUTINE FIGI2(NM,N,T,D,E,Z,IERR)


NM is an integer input variable set equal to the row dimension of the two-dimensional arrays T and Z as specified in the DIMENSION statements for T and Z in the calling program.

is an integer input variable set equal to the order of the matrix T. N must be not greater than NM.

325

7.1-131

IERR

is a working precision real input two- dimensional variable with row dimension NM and column dimension at least 3. T contains the non-symmetric tridiagonal matrix of order N in its first three columns. The subdiagonal elements are stored in the last N-I positions of the first column. The diagonal elements are stored in the second column. The superdiagonal elements are stored in the first N-I positions of the third column. Elements T(I,!) and T(N,3) are arbitrary.

is a working precision real output one- dimensional variable of dimension at least N containing the diagonal elements of the tridiagonal symmetric matrix.

is a working precision real output one- dimensional variable of dimension at least N containing, in its last N-I positions, the subdiagonal elements of the tridiagonal symmetric matrix. The element E(1) is not referenced.

is a working precision real output two- dimensional variable with row dimension NM and column dimension at least N. It contains the diagonal transformation matrix produced in the symmetrization.



If the product of T(i,I) and T(!-I,3) is negative, FIGI2 terminates with IERR set to N+I. If the product of T(I,I) and T(I-I,3) is zero but either T(I,I) or T(!-I,3) is not zero, FIGI2 terminates with IERR set to 2*N+I. In these cases, there does not exist a symmetrizing similarity transformation, essential for the validity of the later eigenvector computation.

If the products of all pairs of corresponding off- diagonal elements are non-negative, and zero only when both factors are zero, IERR is set to zero.

326

7.1-132


If all the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by IMTQL2 (F292).

If some other combination of eigenvalues and eigenvectors is desired, subroutine FIGI (F280) be used rather than FIGI2 to perform the symmetrization.

should


The transformation is performed in the following way. If the products of pairs of corresponding off-diagonal elements of T are all positive or if both elements are zero, a non- singular diagonal matrix Z can be defined such that the similarity transformation

-i Z TZ

produces a symmetric tridiagonal matrix with diagonal D and subdiagonal E as follows:

D(J) = T(J,2), J=1,2,3, .... N, E(J) = SQRT(T(J,I) * T(J-I,3)), J=2,3,...,N.

The diagonal elements of the transformation matrix follows:

Z are as

z(1,1) = 1.0,

and for J=2,3,...,N Z(J,J) = Z(J-I,J-I) * SQRT(T(J,I) / T(J-I,3))

if T(J,I) * T(J-I,3) is positive, or Z(J,J) = 1.0 if both T(J,I) and T(J-I,3) are zero.

This subroutine is an implementation of the algorithm discussed in detail by Wilkinson (i).

4. REFERENCES.


327

7.1-133

5. CHECKOUT.

A. Test Cases°


B, Accuracy,

The accuracy of FIGI2 can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of certain real non- symmetric tridiagonal matrices. In these paths, this subroutine is numerically stable (i). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.

328

7.1-134

C

C

C

C

C

C C

SUBROUTINE FIGI2(NM,N,T,D,E,Z,IERR)

INTEGER I,J,N,NM, IERR REAL T(NM,3),D(N),E(N),Z(NM, N) REAL H REAL SQRT

IERR = 0

DO i00 I = I, N

DO 50 J = i, N 50 Z(I,J) = 0.0

IF (I .EQ. 1) GO TO 70 H = T(I,I) * T(I-I,3) IF (H) 900, 60, 80

60 IF (T(I,I) .NE. 0.0 .OR. T(I-I,3) .NE. 0.0) GO TO I000 E(I) = 0.0

70 Z(I,I) = 1.0 GO TO 90

80 E(1) = SQRT(H) Z ( I , I ) = Z ( I - I , I - 1 ) * E ( I ) / T(I-I,3)

90 D(I) = T(I,2) i00 CONTINUE

GO TO i001

~***~***** SET ERROR -- PRODUCT OF SOME PAIR OF OFF-DIAGONAL ELEMENTS IS NEGATIVE **e*****e*

900 IERR = N + I GO TO 1001

********** SET ERROR -- PRODUCT OF SOME PAIR OF OFF-DIAGONAL ELEMENTS IS ZERO WITH ONE MEMBER NON-ZERO ~***e***~*

1000 IERR = 2 * N + I I001 RETURN

END

329

7. 1-135

NATS PROJECT


F286-2 HQR

A Fortran IV Subroutine to Determine the Eigenvalues of a Real Upper Hessenberg Matrix.

May, 1972 July, 1975

i. PURPOSE~

The Fortran IV subroutine HQR computes the eigenvalues of a real upper Hessenberg matrix using the QR method.

2. USAGE.



SUBROUTINE HQR(NM,N,LOW, IGH,H,WR,WI,IERR)


NM is an integer input variable set equal to the row dimension of the two-dimensional array H as specified in the DIMENSION statement for H in the calling program.

is an integer input variable set equal to the order of the matrix H. N must be not greater than NM.

LOW,!GH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F269 for the details. If the matrix is not balanced, set LOW to 1 and IGH to N.

330

7.1-136

H

WR,WI

IERR

is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. On input, it contains the upper Hessenberg matrix. Note: HQR destroys this upper Hessenberg matrix as well as the two adjacent diagonals below it.

are working precision real output one- dimensional variables of dimension at least N containing the real and imaginary parts, respectively, of the eigenvalues of the Hessenberg matrix. The eigenvalues are unordered except that complex conjugate pairs of eigenvalues appear consecutively with the eigenvalue having the positive imaginary part first.



If more than 30 iterations are required to determine an eigenvalue, this subroutine terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues in the WR and WI arrays should be correct for indices IERR+I,IERR+2,...,N.



To determine some of the eigenvectors of a real Hessenberg matrix, HQR should be followed by INVIT (F288) to compute those eigenvectors. Note, however, that the upper Hessenberg matrix must be saved before HQR for later use by INVIT.

To determine the eigenvalues of a real general matrix, HQR must be preceded by ELMHES (F273) or ORTHES (F275) to produce a suitable upper Hessenberg matrix for HQR.

331

7.1-137

To determine some of the eigenvectors of a real general matrix, HQR should be preceded by ELMHES (F273) or ORTHES (F275) and followed by INVIT (F288) and ELMBAK (F274) or ORTBAK (F276). ELMBAK or ORTBAK back transforms the eigenvectors from INVIT into those of the real general matrix. Note, however, that the upper Hessenberg matrix and the two adjacent diagonals below it must be saved before HQR for the later use by INVIT and ELMBAK or ORTBAK, since HQR destroys this portion of H.

It is recommended in general that BALANC (F269) be used before ELMHES or ORTHES in which case BALBAK (F270) must be used after ELMBAK or ORTBAK if eigenvectors are computed.


The eigenvalues are determined by the QR method. The essence of this method is a process whereby a sequence of upper Hessenberg matrices, unitarily similar to the original Hessenberg matrix, is formed which converges to a quasi- triangular matrix, that is, an upper Hessenberg matrix whose eigenva!ues are the eigenvalues of ixl or 2x2 principal submatrices. The rate of convergence of this sequence is improved by shifting the origin at each iteration. The arithmetic throughout the process is kept real by combining two iterations into one, using two real origin shifts or a pair of complex conjugate origin shifts. Before each iteration, the last Hessenberg form is checked for a possible splitting into submatrices. If a splitting occurs, only the lower submatrix participates in the next iteration.

The origin shifts at each iteration are the eigenvalues of the lowest 2x2 principal minor. Whenever a lowest ixl or 2x2 principal submatrix finally splits from the rest of the matrix, the eigenvalues of this submatrix are taken to be eigenvalues of the original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of order i or 2. The tolerances in the splitting tests are proportional to the relative machine precision.

Some of the eigenvalues may have been isolated on the diagonal by the subroutine BALANC (F269). This information is transmitted to HQR through the parameters LOW and IGH. As a result, HQR immediately extracts the eigenvalues in rows I to LOW-I and IGH+I to N, and so applies the QR procedure to the submatrix situated in rows and columns LOW through IGH.

332

7.1-138

This subroutine is a translation of the Algol procedure written and discussed in detail by Martin, Peters, and Wilkinson (i).

HQR

4. REFERENCES.

i) Martin, R.S., Peters, G., and Wilkinson, J.H., The QR Algorithm for Real Hessenberg Matrices, Num. Math. 14,219-231 (1970). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C° Reinsch, Contribution 11/14, 359-371, Springer-Verlag, 1971.)

5. CHECKOUT.

A. Test Cases.


B. Accuracy.

The subroutine HQR is numerically stable (i); that is, each computed eigenvalue is exact for a matrix close to the original upper Hessenberg matrix.

333

7.1-139

SUBROUTINE HQR(NM,N,LOW, IGH,H,WR,WI,IERR)

INTEGER I,J,K,L,M,N,EN,LL,MM,NA,NM, IGH, ITS,LOW,MP2,ENM2,IERR

REAL H(NM,N),WR(N),WI(N) REAL P,Q,R,S,T,W,X,Y,ZZ,NORM,MACHEP

REAL SQRT,ABS,SIGN

INTEGER MIN0 LOGICAL NOTLAS



MACHEP = ?

IERR = 0 NORM = 0.0

K = 1 ********** STORE ROOTS ISOLATED BY BALANC

AND COMPUTE MATRIX NORM ********** DO 50 I = i, N

40

DO 40 J = K, N

NORM = NORM + ABS(H(I,J))

K = I IF (I .GE. LOW .AND. I .LE. IGH) GO TO 50

WR(1) = H(I,I)

WI(I) = 0.0

50 CONTINUE

EN = !GH

T=0.0 C ********** SEARCH FOR NEXT EIGENVALUES **********

60 IF (EN .LT. LOW) GO TO i001

ITS = 0 NA = EN - 1

ENM2 = NA - 1 C ********** LOOK FOR SINGLE SMALL SUB-DIAGONAL ELEMENT C FOR L=EN STEP -I UNTIL LOW DO -- **********

70 DO 80 LL = LOW, EN L = EN + LOW - LL IF (L .EQ. LOW) GO TO i00

S = ABS(H(L-I,L-I)) + ABS(H(L,L)) IF (S ,EQ. 0.0) S = NORM IF (ABS(H(L,L-I)) .LE. MACHEP * S) GO TO I00


!00 X = H(EN,EN) IF (L .EQ. EN) GO TO 270

Y = H(NA,NA) W = H(EN,NA) * H(NA,EN) IF (L .EQ. NA) GO TO 280 IF (ITS .EQ. 30) GO TO i000

334

7. 1-140

IF (ITS .NE. i0 .AND. ITS .NE. 20) GO TO 130

********** FORM EXCEPTIONAL SHIFT **********

T = T + X

DO 120 1 = LOW, EN

120 H(I,I) = H(!,I) - X

S = ABS(H(EN,NA)) + ABS(H(NA,ENM2)) X = 0.75 * S Y = X W = -0.4375 * S * S

130 ITS = ITS + 1

• ********* LOOK FOR TWO CONSECUTIVE SMALL SUB-DIAGONAL ELEMENTS.

FOR M--EN-2 STEP -I UNTIL L DO -- ********** DO 140 MM = L, ENM2

M = ENM2 + L - MM ZZ = H(M,M)

R -- X - ZZ S = Y - ZZ

P = (R * S - W) / H(M+I,M) + H(M,M+I) Q = H(M+I,M+I) - ZZ - R - S R = H(M+2,M+I)

S = ABS(P) + ABS(Q) + ABS(R) P = P / S

Q = Q / S R = R / S IF (M .EQ. L) GO TO 150

IF (ABS(H(M,M-I)) * (ABS(Q) + ABS(R)) .LE. MACHEP * ABS(P) X * (ABS(H(M-I,M-I)) + ABS(ZZ) + ABS(H(M+I,M+I)))) GO TO 150

140 CONTINUE

150 MP2 = M + 2

DO 160 I = MP2, EN

H(I,I-2) = 0.0

IF (I .EQ. MP2) GO TO 160 H(I,I-3) = 0.0

160 CONTINUE

********** DOUBLE QR STEP INVOLVING ROWS L TO EN AND COLUMNS M TO EN **********

DO 260 K = M, NA

NOTLAS = K .NE. NA

IF (K .EQ. M) GO TO 170 P = H(K,K-I) Q = H(K+I,K-I) R=O.0

IF (NOTLAS) R = H(K+2,K-I)

X = ABS(P) + ABS(Q) + ABS(R) IF (X .EQ. 0.0) GO TO 260 P = e / X

Q = Q / X R = ~ / X

335

7.1-141

170 S = SIGN(SQRT(P*P+Q*Q+R*R),P)

IF (K .EQ. M) GO TO 180

H(K,K-I) = -S * X

GO TO 190 180 IF (L .NE. M) H(K,K-I) = -H(K,K-I)

190 P = P + S x=e/s Y = Q / S zz =R / S Q = Q / e

R = R / P • ********* ROW MODIFICATION **********

DO 210 J = K, EN P = H(K,J) + Q * H(K+l,J) IF (.NOT. NOTLAS) GO TO 200

P = P + R * H(K+2,J) H(K+2,J) = H(K+2,J) - P * ZZ

200 H(K+I,J) = H(K+I,J) - P * Y

H(K,J) = H(K,J) - P * X

210 CONTINUE

220

230

J = MIN0(EN,K+3) ********** COLUMN MODIFICATION **********

DO 230 I = Ls J P = X * H(I,K) + Y * H(I,K+I)

IF (.NOT. NOTLAS) GO TO 220

P = P + EZ * H(I,K+2)

H(I,K+2) = H(I,K+2) - P * R

H(I,K+I) = H(I,K+I) - P * Q

H(l,K) = H(I,K) - P

CONTINUE

260 CONTINUE

GO TO 70 ********** ONE ROOT FOUND **********

270 WR(EN) = X + T WI(EN) = 0.0 EN = NA GO TO 60 ********** TWO ROOTS FOUND **********

280 P = (Y - X) / 2.0 Q = P * P + W ZZ = SQRT(ABS(Q))

X = X + T IF (Q .LT. 0.0) GO TO 320 ********** REAL PAIR **********

ZZ = P + SIGN(ZZ,P)

WR(NA) = X + ZZ WR (EN) = WR (NA) IF (ZZ .NE. 0.0) WR(EN) = X - W / ZZ

Wi(NA) = 0.0 WI(EN) = 0.0 GO TO 330

336

7.1-142

C ********** COMPLEX PAIR **********

320 WR(NA) = X + P

WR(EN) = X + P

WI(NA) = ZZ

WI(EN) = -zz

330 EN = ENM2

GO TO 60



I000 IERR = EN

i001 RETURN

END

337

7. 1-143

NATS PROJECT


F287-2 HQR2

A Fortran IV Subroutine to Determine the Eigenvalues and Eigenvectors of a Real Upper Hessenberg Matrix.

May, 1972 July, 1975

i. PURPOSE.

The Fortran IV subroutine HQR2 computes the eigenvalues and eigenvectors of a real upper Hessenberg matrix using the QR methods The eigenvectors of a real general matrix can also be computed if ELMHES (F273) and ELTRAN (F220) or ORTHES (F275) and ORTRAN (F221) have been used to reduce this general matrix to Hessenberg form and to accumulate the transformations,

2. USAGE.

A, Calling Sequence.


SUBROUTINE HQR2(NM,N,LOW, IGH,H,WR,WI,Z,IERR)


NM is an integer input variable set equal to the row dimension of the two-dimensional arrays H and Z as specified in the DIMENSION statements for H and Z in the calling program.

is an integer input variable set equal to the order of the matrix H. N must be not greater than NM.


338

7.1-144

H

WR,WI

IERR

is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. On input, it contains the upper Hessenberg matrix. Note: HQR2 destroys this upper Hessenberg matrix.

are working precision real output one- dimensional variables of dimension at least N containing the real and imaginary parts, respectively, of the eigenvalues of the Hessenberg matrix. The eigenvalues are unordered except that complex conjugate pairs of eigenvalues appear consecutively with the eigenvalue having the positive imaginary part first.

is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. If the eigenvectors of the upper Hessenberg matrix are desired, then on input, Z contains the identity matrix of order N, and on output, contains the real and imaginary parts of the eigenvectors of this Hessenberg matrix. If the eigenvectors of a real general matrix are desired, then on input, Z contains the transformation matrix produced in ELTRAN or ORTRAN which reduced the general matrix to Hessenberg form, and on output, contains the real and imaginary parts of the eigenvectors of this real general matrix. If the J-th eigenvalue is real, the J-th column of Z contains its eigenvector. If the J-th ~eigenvalue is complex with positive imaginary part, the J-th and (J+l)-th columns of Z contain the real and imaginary parts of its eigenvector. The conjugate of this vector is the eigenvector for the conjugate eigenvalue. The eigenvectors are not normalized.

is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is ZerO.

339

7.1-145


If more than 30 iterations are required to determine an eigenvalue, this subroutine terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues in the WR and WI arrays should be correct for indices IERR+I,IERR+2,...,N, but no eigenvectors are computed.



To determine the eigenvalues and eigenvectors of a real general matrix, HQR2 should be preceded by ELMHES (F273) or ORTHES (F275) to provide a suitable upper Hessenberg matrix for HQR2 and by ELTRAN or ORTRAN to accumulate the transformations.

It is recommended in general that BALANC (F269) be used before ELMHES or ORTHES in which case BALBAK (F270) must be used after HQR2.


The eigenvalues are determined by the QR method. The essence of this method is a process whereby a sequence of upper Hessenberg matrices, unitarily similar to the original Hessenberg matrix, is formed which converges to a quasi- triangular matrix, that is, an upper Hessenberg matrix whose eigenvalues are the eigenvalues of Ixl or 2x2 principal submatrices. The rate of convergence of this sequence is improved by shifting the origin at each iteration. The arithmetic throughout the process is kept real by combining two iterations into one, using two real origin shifts or a pair of complex conjugate origin shifts. Before each iteration, the last Hessenberg form is checked for a possible splitting into submatrices. If a splitting occurs, only the lower submatrix participates in the next iteration. The similarity transformations used in each iteration are accumulated in the Z array.

The origin shifts at each iteration are the eigenvalues of the lowest 2x2 principal minor. Whenever a lowest ixl or 2x2 principal submatrix finally splits from the rest of the matrix, the eigenvalues of this submatrix are taken to be eigenvalues of the original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of

340

7.1-146

order i or 2. The tolerances in the splitting tests are proportional to the relative machine precision. The eigenvectors of this quasi-triangular matrix are determined by a back substitution process and then transformed to the eigenvectors of the original matrix, using the information in Z.

Some of the eigenvalues may have been isolated on the diagonal by the subroutine BALANC (F269). This information is transmitted to HQR2 through the parameters LOW and IGH. As a result, HQR2 immediately extracts the eigenvalues in rows i to LOW-I and IGH+I to N, and so applies the QR procedure to the submatrix situated in rows and columns LOW through IGH.

This subroutine is a translation of the Algol procedure HQR2 written and discussed in detail by Peters and Wilkinson (i).

4. REFERENCES.

1) Peters, G. and Wilkinson, J.H., Eigenvectors of Real and Complex Matrices by LR and QR Triangularizations, Num. Math. 16,181-204 (1970). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution II/15, 372-395, Springer-Verlag, 1971.)

5. CHECKOUT.

A. Test Cases.


B. Accuracy.

The subroutine HQR2 is numerically stable (I); that is, each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original upper Hessenberg matrix.

341

7.1-147

SUBROUTINE HQR2(NM~N,LOW,IGH,H,WR,WI,Z,IERR)

INTEGER I,J,K,L,M,N,EN,II,JJ,LL,MM,NA,NM,NN,

X IGH,ITS,LOW,MP2,ENM2,IERR

REAL H(NM,N),WR(N),WI(N),Z(NM,N) REAL P,Q,R,S,T,W,X~Y,RA, SA,VI,VR,ZZ,NORM,MACHEP

REAL SQRT,ABS,SIGN INTEGER MIN0 LOGICAL NOTLAS

COMPLEX Z3

COMPLEX CMPLX REAL REAL,AIMAG


MACHEP = ?

IERR = 0

NORM = 0.0 K = 1 ********** STORE ROOTS ISOLATED BY BALANC

AND COMPUTE MATRIX NORM **********

DO 50 I = !, N

40

DO 40 J = K, N NORM = NORM + ABS(H(I,J))

K = I IF (I .GE. LOW .AND. I .LE. IGH) GO TO 50

WR(1) = H(I,I) WI(1) = 0.0

50 CONTINUE

EN = IGH T=0.0 ********** SEARCH FOR NEXT E!GENVALUES **********

60 IF (EN .LT. LOW) GO TO 340

ITS = 0 NA = EN - 1

ENM2 = NA - 1 ********** LOOK FOR SINGLE SMALL SUB-DIAGONAL ELEMENT

FOR L=EN STEP -i UNTIL LOW DO -- **********

70 DO 80 LL = LOW, EN L = EN + LOW - LL IF (L .EQ. LOW) GO TO I00 S = ABS(H(L-I,L-I)) + ABS(H(L,L)) IF (S .EQ. 0.0) S = NORM IF (ABS(H(L,L-I)) .LE. MACHEP * S) GO TO I00

80 CONTINUE

342

7.1-148

********** FORM SHIFT ********** i00 X = H(EN,EN)

IF (L .EQ. EN) GO TO 270

Y = H(NA,NA)

W = H(EN,NA) * H(NA,EN)

IF (L .EQ. NA) GO TO 280 IF (ITS .EQ. 30) GO TO I000

IF (ITS .NE. i0 .AND. ITS .NE. 20) GO TO 130 ********** FORM EXCEPTIONAL SHIFT ********** T = T + X

DO 120 I = LOW, EN 120 H(l,l) = H(I,I) - X

S = ABS(H(EN,NA)) + ABS(H(NA,ENM2)) X= 0.75 * S Y = X

W = -0.4375 * S * S 130 ITS = ITS + i

• ********* LOOK FOR TWO CONSECUTIVE SMALL SUB-DIAGONAL ELEMENTS.

FOR M=EN-2 STEP -i UNTIL L DO -- ********** DO 140 MM = L, ENM2

M = ENM2 + L - MM ZZ = H(M,M) R = X - ZZ

S = Y - ZZ

P = (R * S - W) / H(M+I,M) + H(M,M+I) Q = H(M+I,M+I) - ZZ - R - S R = H(M+2,M+I)

S = ABS(P) + ABS(Q) + ABS(R) F = P / S

Q = Q / S R = R / S

IF (M .EQ. L) GO TO 150

IF (ABS(H(M,M-I)) * (ABS(Q) + ABS(R)) .LE. MACHEP * ABS(P)

X * (ABS(H(M-I,M-I)) + ABS(ZZ) + ABS(H(M+I,M+I)))) GO TO 150 140 CONTINUE

130 MP2 = M + 2

DO 160 I = MP2, EN H(I,I-2) = 0.0

IF (I .EQ. MP2) GO TO 160 H(I,I-3) = 0.0

160 CONTINUE

********** DOUBLE QR STEP INVOLVING ROWS L TO EN AND COLUMNS M TO EN **********

DO 260 K = M, NA NOTLAS = K .NE. NA

IF (K .EQ. M) GO TO 170 P = H(K,K-I)

Q = H(K+I,K-I) R = 0.0

343

7. 1-149

IF (NOTLAS) R = H(K+2,K-I) X = ABS(P) + ABS(Q) + ABS(R)

IF (X .EQ. 0.0) GO TO 260

P = P / X Q = Q / x

R = R / X 170 S = SIGN(SQRT(P*P+Q*Q+R*R),P)

IF (K .EQ. M) GO TO 180 H(K,K-I) = -S * X GO TO 190

180 IF (L .NE. M) H(K,K-I) = -H(K,K-I) 190 P = P + S

x=p/s Y = Q / S

ZZ=R/S e = Q / P R = R / e

• ********* ROW MODIFICATION **********

DO 210 J = K, N P = H(K,J) + Q * H(K+I,J)

IF (°NOT. NOTLAS) GO TO 200 P = P + R * H(K+2,J)

H(K+2,J) = H(K+2,J) - P * ZZ 200 H(K+I,J) = H(K+I,J) - P * Y

H(K,J) = H(K,J) - P * X 210 CONTINUE

J = MiN0(EN,K+3) ********** COLUMN MODIFICATION **********

DO 230 I = i, J

P = X * H(I,K) + Y * H(I,K+I) IF (.NOT. NOTLAS) GO TO 220

P = P + ZZ * H(I,K+2) H(l,K+2) = H(I,K+2) - P * R

220 H(I,K+I) = H(I,K+I) - P * Q H(!~K) = N(l,K) - P

230 CONTINUE ********** ACCUMULATE TRANSFORMATIONS **********

DO 250 I = LOW, IGN e = X * Z(I,K) + Y * Z(I,K+I)

IF (.NOT. NOTLAS) GO TO 240 P = P + ZZ * Z(I,K+2) Z(I,K+2) = Z(I,K+2) - P * R

240 Z(I,K+I) = Z(l,K+l) - P * Q

Z(I,K) = Z(I,K) - e 250 CONTINUE

260 CONTINUE

GO TO 70

344

7. i- 150

C ********** ONE ROOT FOUND **********

270 H(EN,EN) = X + T WR(EN) = H(EN,EN)

WI(EN) = 0.0 EN = NA GO TO 60

C ********** TWO ROOTS FOUND ********** 280 P = (Y - X) / 2.0

Q = P * P + W ZZ = SQRT (ABS (Q))

H(EN,EN) = X + T X = H(EN,EN)

H(NA,NA) = Y + T

IF (Q .LT. 0.0) GO TO 320 C ********** REAL PAIR **********

ZZ = P + SIGN(ZZ,P)

WR(NA) = X + ZZ WR(EN) = WR(NA)

IF (ZZ .NE. 0.0) WR(EN) = X - W / ZZ WI(NA) = 0.0 WI(EN) = 0.0

X = H(EN,NA)

S = ABS(X) + ABS(ZZ) F = X / S Q=ZZ/S R = SQRT (P*P+Q*Q) P = P / R

Q = Q / R

C ********** ROW MODIFICATION ********** DO 290 J = NA, N

ZZ = H(NA,J)

H(NA,J) = Q * ZZ + e * H(EN,J)

H(EN,J) = Q * H(EN,J) - P * ZZ 290 CONTINUE

C ********** COLUMN MODIFICATION ********** DO 300 I = i, EN

ZZ = H(I,NA)

H(I,NA) = Q * zz + P * H(I,EN) H(I,EN) = Q * H(I,EN) - P * ZZ

300 CONTINUE

C ********** ACCUMULATE TRANSFORMATIONS ********** DO 310 I = LOW, IGH

ZZ = Z(I,NA)

Z(I,NA) = Q * ZZ + P * Z(I,EN) Z(I,EN) = Q * Z(I,EN) - P * ZZ

310 CONTINUE

GO TO 330

345

7. 1-151

C ********** COMPLEX PAIR ***~****** 320 WR(NA) = X + P

WR(EN) = X + P WI(~A) = zz

WI(EN) = -ZZ

330 EN = ENM2 GO TO 60

C ********** ALL ROOTS FOUND. BACKSUBSTITUTE TO FIND

C VECTORS OF UPPER TRIANGULAR FORM **********

340 IF (NORM oEQ. 0.0) GO TO i001

C ********** FOR EN=N STEP -i UNTIL 1 DO -- ********** DO 800 NN = i, N

EN = N + I - NN

P = WR(EN) Q = WI(EN)

NA = EN - 1 IF (q) 710, 600, 800

C ********** REAL VECTOR ********** 600 M = EN

H(EN,EN) = 1.0 IF (NA .EQ. 0) GO TO 800

C ********** FOR I=EN-I STEP -I UNTIL i DO -- **********

DO 700 II = i, NA

I = EN - II W = H(I,I) - e

R = H(l,EN)

IF (M .GT. NA) GO TO 620

610 DO 610 J = M, NA R = R + H(I,J) * II(J,EN)

620 IF (WI(I) .GE. 0.0) GO TO 630

ZZ = W S = R

GO TO 700 630 M = I

IF (WI(1) .RE. 0.0) GO TO 640 T = W IF (W .EQ. 0.0) r = MACHEP * NORM

H(I,EN) = -R / T

GO TO 700 C ********** SOLVE REAL EQUATIONS **********

640 X = H(I,I+I) Y = H(I+I,I) Q = (WR(1) -P) * (WR(1) -P)+ WI(1) * WI(1)

T = (X * S - ZZ * R) / Q H(I,EN) = T IF (ABS(X) .LE. ABS(ZZ)) GO TO 650 H(I+I,EN) = (-R - W * T) / X

GO TO 700 650 H(I+I,EN) = (-S - Y * T) / ZZ

700 CONTINUE C ********** END REAL VECTOR **********

GO TO 800

346

7.1-152

C ********** COMPLEX VECTOR ********** 710 M = NA

C *********~ LAST VECTOR COMPONENT CHOSEN IMAGINARY SO THAT C EIGENVECTOR MATRIX IS TRIANGULAR **********

IF (ABS(H(EN,NA)) .LE. ABS(H(NA, EN))) GO TO 720 H(NA,NA) = Q / H(EN,NA) H(NA,EN) = -(H(EN,EN) - P) / H(EN,NA) GO TO 730

720 Z3 = CMPLX(0.0,-H(NA, EN)) / CMPLX(H(NA,NA)-P,Q) H(NA,NA) = REAL(Z3) H(NA,EN) = AIMAG(Z3)

730 H(EN,NA) = 0.0 H(EN,EN) = 1.0 ENM2 = NA - i

IF (ENM2 .EQ. 0) GO TO 800 C ********** FOR I=EN-2 STEP -i UNTIL 1 DO -- **********

DO 790 II = I, ENM2 I = NA - II W = H(I,I) - e RA = 0.0 SA = H(I,EN)

760

770

X

780

DO 760 J = M, NA

RA = RA + H(I,J) * H(J,NA) SA = SA + H(I,J) * H(J,EN)

CONTINUE

IF (WI(I) .GE. 0.0) GO TO 770 ZZ = W R = RA S = SA GO TO 790 M = I

IF (WI(I) .NE. 0.0) GO TO 780 Z3 = CMPLX(-RA,-SA) / CMPLX(W,Q) H(I,NA) = REAL(Z3) H(I,EN) = AIMAG(Z3) GO TO 790

********** SOLVE COMPLEX EQUATIONS ********** X = H(I,I+I) Y = H(I+I,I)

VR = (WR(I) - P) * (WR(I) - P) + WI(I) * WI(I) - Q * q vI = (WR(I) - P) * 2.0 * Q

IF (VR .EQ. 0.0 .AND. VI .EQ. 0.0) VR = MACHEP * NORM * (ABS(W) + ABS(Q) + ABS(X) + ABS(Y) + ABS(ZZ))

Z3 = CMPLX(X*R-ZZ*RA+Q*SA,X*S-ZZ*SA-Q*RA) / CMPLX(VR,Vl) H(I,NA) = REAL(Z3) H(I,EN) = AIMAG(Z3)

IF (ABS(X) .LE. ABS(ZZ) + ABS(Q)) GO TO 785 H(I+I,NA) = (-RA - W * H(I,NA) + Q * H(I,EN)) / X H(I+I,EN) = (-SA - W * H(I,EN) - Q * H(I,NA)) / X GO TO 790

347

7.1-153

785 Z3 = CMPLX(-R-Y*H(I,NA),-S-Y*H(I,EN)) / CMPLX(ZZ,Q)

H(I+!,NA) = REAL(Z3)

H(I+I,EN) = AIMAG(Z3)

790 CONTINUE ********** END COMPLEX VECTOR **********

800 CONTINUE ********** END BACK SUBSTITUTION.

VECTORS OF ISOLATED ROOTS **********

DO 840 1 = i, N IF (I oGE. LOW .AND. I .LE. IGH) GO TO 840

820 DO 820 J = I t N Z(I,J) = H(I,J)

840 CONTINUE ********** MULTIPLY BY TRANSFORMATION MATRIX TO GIVE


FOR J=N STEP -I UNTIL LOW DO -- **********

DO 880 JJ = LOW~ N

J = N + LOW - JJ

M = MIN0(J,IGH)

DO 880 1 = LOW, IGH ZZ = 0.0

860 DO 860 K = LOW, M ZZ = ZZ + Z(I,K) * H(K,J)

Z(l,J) = ZZ

880 CONTINUE

GO TO I001 ********** SET ERROR -- NO CONVERGENCE TO AN

EIGENVALUE AFTER 30 ITERATIONS **********

i000 IERR = EN

i001 RETURN

END

348

7. 1-154

NATS PROJECT


F285-2 HTRIBK

A Fortran IV Subroutine to Back Transform the Eigenvectors of that Symmetric Tridiagonal Matrix Determined by HTRIDI.

May, 1972 July, 1975

I. PURPOSE.

The Fortran IV subroutine HTRIBK forms the eigenvectors of a complex Hermitian matrix from the eigenvectors of that real symmetric tridiagonal matrix determined by HTRIDI (F284).

2. USAGE.



SUBROUTINE HTRIBK(NM,N,AR,AI,TAU,M,ZR,ZI)



is an integer input variable set equal to the order of the matrix. N must be not greater than NM.

AR,AI are working precision real input two- dimensional variables with row dimension NM and column dimension at least N. The strict lower triangle of AR and the full lower triangle of AI contain some information about the unitary transformations used in the reduction to the tridiagonal form. The remaining upper parts of the matrices are arbitrary. See section 3 of F284 for the details.

349

7.1-155

TAU

M

ZR, ZI

is a working precision real input two- dimensional variable with row dimension 2 and column dimension at least N. TAU contains the remaining information about the unitary transformations. See section 3 of F284 for the details.


are working precision real two-dimensional variables with row dimension NM and column dimension at least M. On input, the first M columns of ZR contain the real eigenvectors to be back transformed and the contents of ZI are immaterial. On output, these M columns of ZR and ZI contain the real and imaginary parts, respectively, of the transformed eigenvectors. The transformed eigenvectors are orthonormal if the input eigenvectors are orthonormal.

B. Error Conditions and Returns°

None°

Co Applicability and Restrictions.

This subroutine should be used in conjunction with the subroutine HTRIDI (F284).


Suppose that the Hermitian matrix C to the tridiagonal symmetric matrix transformation

(say) has been reduced F by the similarity

F = V Q cqv

where Q is a product of the unitary Hermitian matrices encoded in the lower triangles of AR and A!, and V is a unitary diagonal matrix encoded in TAU. Then, given an array Z of column vectors, HTRIBK computes the matrix product QVZ. If the eigenvectors of F are columns of the array Z, then HTRIBK forms the eigenvectors of C in their place. Since QV is unitary, vector Euclidean norms are preserved. Note that the last component of each transformed eigenvector is real.

350

7.1-156

This subroutine is a complex analogue of the subroutine TRBAKI (F279) which is a translation of the Algol procedure TRBAKI written and discussed in detail by Martin, Reinsch, and Wilkinson (i). A similar Algol procedure REVERSE is discussed in detail by Mueller (2).

4. REFERENCES.

1) Martin, R.S., Reinsch, C., and Wilkinson, J.H., Householder's Tridiagonalization of a Symmetric Matrix, Num. Math. 11,181-195 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 1I/2, 212-226, Springer-Verlag, 1971.)

2) Mueller, D.J., Householder's Method for Complex Matrices and Eigensystems of Hermitian Matrices, Num. Math. 8,72-92 (1966).

5. CHECKOUT.

A. Test Cases.


B. Accuracy.

The accuracy of HTRIBK can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of complex Hermitian matrices. In these paths, this subroutine is numerically stable (1,2). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.

351

7.1-157

C

C

C

SUBROUTINE HTRIBK(NM,N,AR,A!,TAU,M,ZR,Z!)

INTEGER !,J,K,L,M~N,NM REAL AR(NM,N),A!(NM,N),TAU(2,N)~ZR(NM,M),ZI(NM,M) REAL H,S,SI

I F (M .EQ. 0) GO TO 200 ********** TRANSFORM THE EIGENVECTORS OF THE REAL SYMMETRIC

TR!DIAGONAL MATRIX TO THOSE OF THE HERMITIAN TRIDIAGONAL MATRIX. **********

DO 50 K = I, N

DO 50 J = i~ M Z!(K,J) = -ZR(K,J) * TAU(e,K) ZR(K,J) = ZR(K,J) * TAU(I,K)

50 CONTINUE

IF (N .EQ. i) GO TO 200 ********** RECOVER AND APPLY THE HOUSEHOLDER MATRICES ********** DO 140 ! = 2, N

L = I - I H = AI(I,I) IF (H .EQ. 0.0) GO TO 140

DO 130 J = i, M

S = 0.0 Sl = 0.0

I i 0

DO Ii0 K = I, L S = S + AR(I,K) * ZR(K,J) - AI(I,K) * ZI(K,J) SI = SI + AR(I,K) * ZI(K,J) + AI(I,K) * ZR(K,J)

CONTINUE • ********* DOUBLE DIVISIONS AVOID POSSIBLE UNDERFLOW **********

S = (S / H) / H SI = (SI / H) / H

120

DO 120 K = i, L ZR(K,J) = ZR(K,J) - S * AR(I,K) - SI * AI(I,K) ZI(K,J) = ZI(K,J) - SI * AR(I,K) + S * AI(I,K)

CONTINUE

130 CONTINUE

140 CONTINUE

200 RETURN END

352

7.1-158

NATS PROJECT


F243 HTRIB3

A Fortran IV Subroutine to Back Transform the Eigenvectors of that Symmetric Tridiagonal Matrix Determined by HTRID3.

July, 1975

1. PURPOSE.

The Fortran IV subroutine HTRIB3 forms the eigenvectors of a complex Hermitian matrix from the eigenvectors of that real symmetric tridiagonal matrix determined by HTRID3 (F242).

2. USAGE.



SUBROUTINE HTRIB3(NM,N,A,TAU,M,ZR,ZI)


NM is an integer input variable set equal to the row dimension of the two-dimensional arrays A, ZR, and ZI as specified in the DIMENSION statements for A, ZR, and ZI in the calling program.

N is an integer input variable set equal to the order of the matrix. N must be not greater than NM.

A is a working precision real input two- dimensional variable with row dimension NM and column dimension at least N containing some information about the unitary transformations used in the reduction to the tridiagonal form. See section 3 of F242 for the details.

353

7.1-159

TAU

M

ZR, ZI

is a working precision real input two- dimensional variable with row dimension 2 and column dimension at least N. TAU contains the remaining information about the unitary transformations. See section 3 of F242 for the details.


are working precision real two-dimensional variables with row dimension NM and column dimension at least M. On input, the first M columns of ZR contain the real eigenvectors to be back transformed and the contents of ZI are immaterial. On output, these M columns of ZR and ZI contain the real and imaginary parts, respectively, of the transformed eigenvectors. The transformed eigenvectors are orthonormal if the input eigenvectors are orthonormal.

B. Error Conditions and Returns,

None,


This subroutine should be used in conjunction with the subroutine HTRID3 (F242).


Suppose that the Hermitian matrix C to the tridiagonal symmetric matrix transformation


F = V Q CQV

where Q is a product of the unitary Hermitian matrices encoded in A, and V is a unitary diagonal matrix encoded in TAU. Then, given an array Z of column vectors, HTRIB3 computes the matrix product QVZ. If the eigenvectors of F are columns of the array Z, then HTRIB3 forms the eigenvectors of C in their place. Since QV is unitary, vector Euclidean norms are preserved. Note that the last component of each transformed eigenvector is real.

354

7.1-160

This subroutine is a complex analogue of the subroutine TRBAK3 (F229) which is a translation of the Algol procedure TRBAK3 written and discussed in detail by Martin, Reinsch, and Wilkinson (i). A similar Algol procedure REVERSE is discussed in detail by Mueller (2).

4. REFERENCES.

I) Martin, R.S., Reinsch, C., and Wilkinson, J.H., Householder's Tridiagonalization of a Symmetric Matrix, Num. Math. 11,181-195 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/2, 212-226, Springer-Verlag, 1971.)


5. CHECKOUT.

A. Test Cases.


B. Accuracy.

The accuracy of HTRIB3 can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of complex Hermitian matrices. In these paths, this subroutine is numerically stable (1,2). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.

355

7.1-161

C C C

C

C

C

SUBROUTINE HTRIB3(NM,N,A, TAU,M,ZR,ZI)

INTEGER !,J,K,L,M,N,NM REAL A(NM,N),TAU(2,N),ZR(NM,M),ZI(NM,M) REAL H,S,SI

IF (M .EQ. 0) GO TO 200 ********** TRANSFORM THE EIGENVECTORS OF THE REAL SYMMETRIC

TRiDIAGONAL MATRIX TO THOSE OF THE HERMITIAN TRIDIAGONAL MATRIX. **********

DO 50 K = I, N

DO 50 J = I, M

ZI(K,J) = -ZR(K,J) * TAU(2,K) ZR(K,J) = ZR(K,J) * TAU(I,K)

50 CONTINUE

IF (N .EQ. 1) GO TO 200 ********** RECOVER AND APPLY THE HOUSEHOLDER MATRICES ********** DO 140 I = 2, N

L = I - i H = A(I, I) IF (H .EQ. 0.0) GO TO 140

DO 130 J = i, M

S=0.0 Sl = 0.0

Ii0

DO Ii0 K = I, L S = S + A(I,K) * ZR(K,J) - A(K,I) * ZI(K,J) SI = Si + A(I,K) * ZI(K,J) + A(K,I) * ZR(K,J)

CONTINUE • ********* DOUBLE DIVISIONS AVOID POSSIBLE UNDEKFLOW **********

S = (S / H) / H SI = (SI / H) / H

120

DO !20 K = i, L ZR(K,J) = ZR(K,J) - S * A(I,K) - SI * A(K,I) ZI(K,J) = ZI(K,J) - SI * A(I,K) + S * A(K,I)

CONTINUE

130 CONTINUE

140 CONTINUE

200 RETURN END

356

7.1-162

NATS PROJECT


F284-2 HTRIDI

A Fortran IV Subroutine to Reduce a Complex Hermitian Matrix to a Real Symmetric Tridiagonal Matrix Using

Unitary Transformations.

May, 1972 July, 1975

i. PURPOSE.

The Fortran IV subroutine NTRIDI reduces a complex Hermitian matrix to a real symmetric tridiagonal matrix using unitary similarity transformations. This reduced form is used by other subroutines to find the eigenvalues and/or eigenvectors of the original matrix. See section 2C for the specific routines.

2. USAGE.



SUBROUTINE HTRIDI(NM,N,AR,AI,D,E,E2,TAU)



is an integer input variable set equal to the order of the matrix A = (AR,AI). N must be not greater than NM.

357

7. 1-163

AR,AI

E2

TAU

are working precision real two-dimensional variables with row dimension NM and column dimension at least N. On input, AR and AI contain the real and imaginary parts, respectively, of the Hermitian matrix of order N to be reduced to tridiagonal form. Only the full lower triangles of the matrices need be supplied. On output, the strict lower triangle of AR and the full lower triangle of AI contain some information about the unitary transformations used in the reduction. The full upper triangle of AR and the strict upper triangle of AI are unaltered. See section 3 for the details.

is a working precision real output one- dimensional variable of dimension at least N containing the diagonal elements of the real symmetric tridiagonal matrix.

is a working precision real output one- dimensional variable of dimension at least N containing, in its last N-I positions, the subdiagonal elements of the tridiagonal matrix. The element E(1) is set to zero.

is a working precision real output one- dimensional variable of dimension at least N containing, in its last N-I positions, the squares of the subdiagonal elements of the tridiagonal matrix. The element E2(1) is set to zero. E2 need not be distinct from E (non-standard usage acceptable with at least those compilers included in the certification statement), in which case no squares are returned.

is a working precision real output two- dimensional variable with row dimension 2 and column dimension at least N. TAU contains the remaining information about the unitary transformations. See section 3 for

the details.


None.

358

7.1-164


If all the eigenvalues of the original matrix are desired, this subroutine should be followed by TQLI (F289), IMTQLI (F291), or TQLRAT (F235).

If all the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by TQL2 (F290) or IMTQL2 (F292), and then by HTRIBK (F285).


If some of the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by TSTURM (F293), or by BISECT (F294) and TINVIT (F223), or by TRIDIB (F237) and TINVIT, or by IMTQLV (F234) and TINVIT, and then by HTRIBK (F285).


The tridiagonal reduction is performed in the following way. Starting with J=N, the elements in the J-th row to the left of the diagonal of (AR,AI) are first scaled, to avoid possible underflow in the transformation that might result in severe departure from orthogonality. The sum of squared magnitudes SIGMA of these scaled elements is next formed. Then, a vector U and a scalar

= u u/2

define an operator

P = I - UU /H

which is unitary and Hermitian and for which the similarity transformation PAP eliminates the elements in the J-th row of A to the left of the subdiagonal and the symmetrical elements in the J-th column.

The non-zero components of U are the elements of the J-th row to the left of the diagonal with the last of them augmented by the square root of SIGMA times the subdiagonal element divided by its magnitude. By storing the transformed subdiagonal element elsewhere and not overwriting the column elements eliminated in the transformation, full information about P is saved for later use in HTRIBK. The transformed subdiagonal element is then rendered real by a diagonal unitary transformation.

359

7.1-165

The above steps are repeated on further rows of the transformed A in reverse order until A is reduced to symmetric tridiagonal form; that is, repeated for J = N-I,N-2,...,3.

The product of the diagonal unitary transformations is accumulated into a unitary diagonal matrix whose diagonal elements are saved in TAU for later use in HTRIBK.

This subroutine is a complex analogue of the subroutine TREDI (F277) which is a translation of the Algol procedure TREDI written and discussed in detail by Martin, Reinsch, and Wilkinson (i). A similar Algol procedure HOUSEHOLDER HERMITIAN is discussed in detail by Mueller (2).

4. REFERENCES.

!)

2)

Martin, R.S., Reinsch, C., and Wilkinson, J.H., Householder's Tridiagonalization of a Symmetric Matrix, Num. Math, 11,181-195 (1968). (Reprinted in Handbook for Automatic Computation, Volume !I, Linear Algebra~ J. H. Wilkinson - C. Reinsch, Contribution 11/2, 212-226, Springer-Verlag, 1971.)

Mueller~ D.J., Householder's Method for Complex Matrices and Eigensystems of Hermitian Matrices, Num. Math. 8,72-92 (1966).

5. CHECKOUT.

A. Test Cases.


B. Accuracy~

The accuracy of HTRIDI can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of complex Hermitian matrices. In these paths, this subroutine is numerically stable (1,2). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenveetors of that matrix~

360

7.1-166

SUBROUTINE HTRIDI(NM,N,AR,Ai,D,E,E2,TAU)

INTEGER I,J,K,L,N,II,NM,JPI

REAL AR(NM,N),AI(NM,N),D(N),E(N),E2(N),TAU(2,N) REAL F,G,H,FI,GI,HH,SI,SCALE REAL SQRT,CABS,ABS COMPLEX CMPLX

TAU(I,N) = 1.0 TAU(2,N) = 0.0

DO I00 I = i, N I00 D(1) = AR(I,!)

C ********** FOR I=N STEP -I UNTIL I DO -- ********** DO 300 II = i, N

I = N + 1 - II L = I - i H= 0.0 SCALE = 0.0

IF (L .LT. i) GO TO 130 C ********** SCALE ROW (ALGOL TOL THEN NOT NEEDED) *~********

DO 120 K = i, L 120 SCALE = SCALE + ABS(AR(!,K)) + ABS(AI(I,K))

130

IF (SCALE .NE. 0.0) GO TO 140 TAU(I,L) = 1.0 TAU(2,L) = 0.0 E(1) = 0.0 E2 (I) = 0.0 GO TO 290

140

150

DO 150 K = i, L AR(I,K) = AR(I,K) / SCALE AI(I,K) = AI(I,K) / SCALE H = N + AR(I,K) * AR(I,K) + AI(I,K) * AI(I,K)

CONTINUE

160

E2(1) = SCALE * SCALE * H G = SQRT (H) E(1) = SCALE * G F = CABS(CMPLX(AR(I,L),AI(I,L)))

• ********* FORM NEXT DIAGONAL ELEMENT OF MATRIX T ********** IF (F .EQ. 0°0) GO TO 160

TAU(I,L) = (AI(I,L) * TAU(2,1) - AR(I,L) * TAU(I,I)) / F SI = (AR(I,L) * TAU(2,1) + AI(I,L) * TAU(I,I)) / F H = H + F * G G = 1.0 + G / F AR(I,L) = G * AR(I,L) AI(I,L) = G * AI(I,L) IF (L .EQ. i) GO TO 270 GO TO 170 TAU(I,L) = -TAU(I,I) SI = TAU(2,!) AR(I,L) = G

361

7.1-167

170

180

F = 0°0

DO 240 J = I, L

g = 0.0

GI = 0.0

********** FORM ELEMENT OF A*U **********

DO 180 K = i, J

G = G + AR(J,K) * AR(I,K) + A!(J,K) * AI(I,K)

GI = GI - AR(J,K) * AI(I,K) + AI(J,K) * AR(I,K)

CONTINUE

JPI = 7 + I

IF (L oLT. JPI) GO TO 220

DO 200 K = JPI, L

G = G + AR(K,J) * AR(I,K) - AI(K,J) * AI(I,K)

GI = GI - AR(K,J) * AI(I,K) - AI(K,J) * AR(I,K)

200 CONTINUE

• ********* FORM ELEMENT OF P **********

220 E(J) = G / H

TAU(2,J) = GI / H

F = F + E(J) * AR(I,J) - TAU(2,J) * AI(I,J)

240 CONTINUE

HH = F / (H + H)

********** FORM REDUCED A **********

DO 260 J = i, L

F = AR(i,J)

G = E(J) - HH * F

E (J) = g

FI = -AI(I,J)

GI = TAU(2,J) - HH * FI

TAU(2,J) = -GI

X

X

260

DO 260 K = I, J

AR(J,K) = AR(J,K) - F * E(K) - G * AR(I,K) + FI * TAU(2,K) + GI * AI(I,K)

AI(J,K) = AI(J,K) - F * TAU(2,K) - G * AI(I,K)

- FI * E(K) - GI * AR(I,K)

CONTINUE

2 7 0

280

DO 280 K = i, L

AR(I,K) = SCALE * AR(I,K)

AI(I,K) = SCALE * AI(I,K)

CONTINUE

TAU(2,L) = -SI

290 HH = D(I)

D(1) = AR(I,I)

AR(I,I) = HH

AI(I,I) = SCALE * SQRT(H)

300 CONTINUE

362

7.1-168

C RETURN END

363

7. i-!69

NATS PROJECT


F242 HTRID3

A Fortran IV Subroutine to Reduce a Complex Hermitian Matrix, Stored as a Single Square Array, to a Real

Symmetric Tridiagonal Matrix Using Unitary Transformations.

July, 1975

Io PURPOSE°

The Fortran IV subroutine HTRID3 reduces a complex Hermitian matrix, stored as a single square array, to a real symmetric tridiagonal matrix using unitary similarity transformations. This reduced form is used by other subroutines to find the eigenvalues and/or eigenvectors of the original matrix. See section 2C for the specific routines.

2. USAGE.



SUBROUTINE HTRID3(NM,N,A,D,E,E2,TAU)




is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. On input, A contains the lower triangle of the Hermitian matrix of order N to be reduced to tridiagonal form. If the real part of A

364

7. 1-170

E2

TAU

is denoted by AR and the imaginary part by AI, then the full lower triangle of AR should be stored in the full lower triangle of A and the strict lower triangle of AI should be stored in the transposed positions of the strict upper triangle of A. No storage is required for the zero diagonal elements of AI. For example when N=4, A should contain

(AR(I,I) AI(2,1) AI(3,1) AI(4,1) ) (AR(2,1) AR(2,2) AI(3,2) AI(4,2) ) (AR(3,1) AN(3,2) AR(3,3) AI(4,3) ) (AR(4,1) AR(4,2) AN(4,3) AN(4,4) ).

(If the upper triangle of AI is stored instead, the eigenvalues are not changed but the eigenvectors are conjugated.) On output, A contains some information about the unitary transformations used in the reduction. See section 3 for the details.

is a working precision real output one- dimensional variable of dimension at least N containing the diagonal elements of the real symmetric tridiagonal matrix.



is a working precision real output two- dimensional variable with row dimension 2 and column dimension at least N. TAU contains the remaining information about the unitary transformations. See section 3 for the details.

365

7.1-171


None.



If all the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by TQL2 (F290) or IMTQL2 (F292), and then by HTRIB3 (F243) .


If some of the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by TSTURM (F293), or by BISECT (F294) and TINVIT (F223), or by TRIDIB (F237) and TINVIT, or by IMTQLV (F234) and TINVIT, and then by HTRIB3 (F243).


The tridiagonal reduction is performed in the following way~ Starting with J=N, the elements in the J-th row to the left of the diagonal of A are first scaled, to avoid possible underflow in the transformation that might result in severe departure from orthogonality. The sum of squared magnitudes SIGMA of these scaled elements is next formed. Then, a vector U and a scalar

H = U U/2

define an operator

P = I - UU /H

which is unitary and Hermitian and for which the similarity transformation PAP eliminates the elements in the J-th row of A to the left of the subdiagonal and the symmetrical elements in the J-th column.

366

7.1-172

The non-zero components of U are the elements of the J-th row to the left of the diagonal with the last of them augmented by the square root of SIGMA times the subdiagonal element divided by its magnitude. By storing the transformed subdiagonal element elsewhere and not overwriting the column elements eliminated in the transformation, full information about P is saved for later use in HTRIB3. The transformed subdiagonal element is then rendered real by a diagonal unitary transformation.

The above steps are repeated on further rows of the transformed A in reverse order until A is reduced to symmetric tridiagonal form; that is, repeated for J = N-I,N-2,...,3.

The product of the diagonal unitary transformations is accumulated into a unitary diagonal matrix whose diagonal elements are saved in TAU for later use in HTRIB3.

This subroutine is a complex analogue of the subroutine TRED3 (F228) which is a translation of the Algol procedure TRED3 written and discussed in detail by Martin~ Reinsch, and Wilkinson (I). A similar Algol procedure HOUSEHOLDER HERMITIAN is discussed in detail by Mueller (2).

4. REFERENCES.

i) Martin, R.S., Reinsch, C., and Wilkinson, J.H., Householder's Tridiagonalization of a Symmetric Matrix, Num. Math. 11,181-195 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/2, 212-226, Springer-Verlag, 1971.)


5. CHECKOUT.

A. Test Cases°


367

7.1-173

B° Accuracy.

The accuracy of HTRID3 can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of complex Hermitian matrices. In these paths, this subroutine is numerically stable (1,2). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.

368

7.1-174

120

130

140

150

160

170

SUBROUTINE HTRID3(NM,N,A,D,E,E2,TAU)

INTEGER I,J,K,L,N,II,NM,JMI,JPI

REAL A(NM,N),D(N),E(N),E2(N),TAU(2,N) REAL F,G,H,FI,GI,HH,SI,SCALE REAL SQRT,CABS,ABS COMPLEX CMPLX

TAU(I,N) = 1.0 TAU(2,N) = 0.0 ********** FOR I=N STEP -i UNTIL i DO -- ********** DO 300 II = i~ N

I = N + I - II L = I - i H = 0.0 SCALE = 0.0 IF (L .LT. i) GO TO 130

********** SCALE ROW (ALGOL TOL THEN NOT NEEDED) ********** DO 120 K = i, L SCALE = SCALE + ABS(A(I,K)) + ABS(A(K,I))

IF (SCALE .NE. 0.0) GO TO 140 TAU(I,L) = 1.0 TAU(2,L) = 0.0 E(I) = 0.0 E2(1) = 0.0 GO TO 290

DO 150 K = I, L A(I,K) = A(I,K) / SCALE A(K,I) = A(K,I) / SCALE N = H + A(I,K) * A(I,K) + A(K,!) * A(K,I)

CONTINUE

E2(1) = SCALE * SCALE * H G -- SQRT (I{) E(1) = SCALE * G F = CABS(CMPLX(A(I,L),A(L,I)))

• ********* FORM NEXT DIAGONAL ELEMENT OF MATRIX T ********** IF (F .EQ. 0.0) GO TO 160

TAU(I,L) = (A(L,I) * TAU(2,1) - A(I,L) * TAU(I,I)) / F SI = (A(I,L) * TAU(2,1) + A(L,I) * TAU(I,I)) / F H = H + F * G G = 1.0 + G / F

A(I,L) = G * A(I,L) A(L,I) = G * A(L,I) IF (L .EQ. i) GO TO 270 GO TO 170 TAU(I,L) = -TAU(I,I) SI = TAU(2,1) A(I,L) = G F = 0.0

369

o

t~

00

,~l

o'~

o o

o

0 ~

c~

0 0

0

II

11

II

L...;

L-~

t~

o 0 0

~ ¢-

,o I|

tl 11

I I

+ l

H I,o

I

+

C~

~e

h.."

C.+

~

r-4

II

II 0

• :'~

+J

II

(++,

+ P,

~ t',+

:, L"

x'J ~

:"

¢--+

+'+

++++

+

r~

. t+

.+

B+,

~>

c~

t-I

II 0~

+'+~

t";

t'J

H

",~

(~,+

-x

C~

~-'+

'~

~ I

.0

¢~-

¢.-<

r..

.+

+-~

~ -

~"

II I-

o-

l v

~

4"

Ix)

C)

~"

¢7'

~x~

+ H t-t

¢'~

cb

ix0

Ix~

P~

o o

o o

~+.

~e

II

(~I

r..-~

'

~

II

>r'J

~

II

+ r_

.,,

O~

II

• ..

.+"

+~;'+

j I::~

L+

~"J

(~

¢",

II "~

t-'1

4 +

L~

;--+

Bx-J

['x'-J

+w

+.+x ~

I,-.-t

C.

+

I ~t

++ ~

-~

Pe

~ I

.++'+'

x +

t--4

~

¢"b

o o

0 "~

J ~

H 0

l'O

~ II

I--:j

. ~

+

tt

xJ

t.~

o :+

~

+--t

o +-

---+

H Oo

I10~

'J

II 0

I+-1

+ II

L'

~ I

~>

+...-

, L -+

+,,~

+ e..

,+

[-rj

+ '.

~ i.-

+ i..

-..]

.++.

+.

~++'+

H

:g-+

c-x+

i,+4

+ .+

~+

+ + +

~

:e,+

¢+++

.. +

+ x-

-

U

O

I1

0 li

II

r_.+

0

~:~

O"

L~O

0 0 0

¢-,j

'7 +....,

,k.n

7.1-176

TAU(2,L) = -SI 290 D(1) = A(I,I)

A(I,I) = SCALE * SQRT(H) 300 CONTINUE

RETURN END

371

7.1-177

NATS PROJECT


F234 !MTQLV

A Fortran IV Subroutine to Determine the Eigenvalues of a Symmetric Tridiagonal Matrix.

July, 1975

I. PURPOSE.

The Fortran IV subroutine IMTQLV is a variant of IMTQLI (F291) that determines the eigenvalues of a symmetric tridiagonal matrix using the implicit QL method, and associates with them their corresponding submatrix indices. This feature and the preservation of the input matrix make it possible to later determine the eigenvectors of the matrix.

2. USAGE.



SUBROUTINE IMTQLV(N,D,E,E2,W, IND,IERR,RVI)


is an integer input variable set equal to the order of the matrix.

is a working precision real input one- dimensional variable of dimension at least N containing the diagonal elements of the symmetric tridiagonal matrix.

is a working precision real input one- dimensional variable of dimension at least N containing, in its last N-I positions, the subdiagonal elements of the symmetric tridiagonal matrix. E(1) is arbitrary.

372

7.1-178

E2

IND

IERR

RVI

is a working precision real one-dimensional variable of dimension at least N. On input, the last N-I positions in this array contain the squares of the subdiagonal elements of the symmetric tridiagonal matrix. E2(1) is arbitrary. On output, E2(1) is set to zero. If any of the elements in E are regarded as negligible, the corresponding elements of E2 are set to zero, indicative of the splitting of the matrix into a direct sum of submatrices.

is a working precision real output one- dimensional variable of dimension at least N containing the eigenvalues of the symmetric tridiagonal matrix. The eigenvalues are in ascending order in W.

is an integer output one-dimensional variable of dimension at least N containing the submatrix indices associated with the corresponding eigenvalues in W. Eigenvalues belonging to the first submatrix have index i, those belonging to the second submatrix have index 2, etc.


is a working precision real temporary one- dimensional variable of dimension at least N used to copy the subdiagonal array E which would otherwise be destroyed.


If more than 30 iterations are required to determine an eigenvalue, IMTQLV terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues in the W array should be correct for indices 1,2,...,IERR-I. These eigenvalues are ordered but are not necessarily the smallest IERR-I eigenvalues.


373

7.1-179


The subroutine TQLI (F289) can also be used to compute the eigenvalues of a symmetric tridiagonal matrix. (No variant of TQLI is available that associates submatrix indices with the eigenvalues.) Note, however, that TQLI does not perform well on matrices whose successive row sums vary widely in magnitude and are not strictly increasing from the first to the last row. IMTQLV is not sensitive to such row sums and is therefore especially recommended for symmetric tridiagona! matrices whose structure is not known.

To determine the eigenvalues of a full symmetric matrix, IMTQLV should be preceded by TREDI (F277) to provide a suitable symmetric tridiagonal matrix for IMTQLV.

To determine the eigenvalues of a complex Hermitian matrix, IMTQLV should be preceded by HTRIDI (F284) to provide a suitable real symmetric tridiagonal matrix for IMTQLV.

Note, however, that although IMTQLV may perform better on symmetric tridiagonal matrices poorly structured in the above sense, TREDI and HTRIDI may also perform poorly on such full symmetric and complex Hermitian matrices. Hence, any advantage in using IMTQLV over TQLI may be overshadowed by a poor performance in TREDI or HTRIDI.

The eigenvalues of certain non-symmetric tridiagonal matrices can be computed using the combination of FIGI (F280) and IMTQLV. See F280 for the description of this special class of matrices. For such matrices~ IMTQLV should be preceded by FIGI to provide a suitable symmetric matrix for IMTQLV.

To determine eigenvectors associated with the computed eigenvalues, !MTQLV should be followed by TINVIT (F223) and the appropriate back transformation subroutine -- TRBAKI (F279) after TREDI, HTRIBK (F285) after HTRIDI, or BAKVEC (F281) after FIGI.


The eigenvalues are determined by the implicit QL method. The essence of this method is a process whereby a sequence of symmetric tridiagonal matrices, unitarily similar to the original symmetric tridiagonal matrix, is formed which converges to a diagonal matrix. The rate of convergence of this sequence is improved by implicitly shifting the origin

374

7.1-180

at each iteration. Before each iteration, the symmetric tridiagonal matrix is checked for a possible splitting into submatrices. If a splitting occurs, only the uppermost submatrix participates in the next iteration. The eigenvalues are ordered in ascending order as they are found.

The origin shift at each iteration is the eigenvalue of the current uppermost 2x2 principal minor closer to the first diagonal element of this minor. Whenever the uppermost ixl principal submatrix finally splits from the rest of the matrix, its element is taken to be an eigenvalue of the original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of order i. The tolerances in the splitting tests are proportional to the relative machine precision.

This subroutine is a modification of the subroutine IMTQLI which is a translation of the Algol procedure IMTQLI written and discussed in detail by Martin and Wilkinson (i) and modified by Dubrulle (2).

4. REFERENCES.

i) Martin, R.S. and Wilkinson, J.H., The Implicit QL Algorithm, Num. Math. 12,377-383 (1968).

2) Dubrulle, A., A Short Note on the Implicit QL Algorithm, Num. Math. 15,450 (1970). (Combined With (i) in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution II/4, 241-248, Springer-Verlag, 1971.)

5. CHECKOUT.

A. Test Cases.


B. Accuracy.

The subroutine IMTQLV is numerically 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.

375

7,1-181

SUBROUTINE IMTQLV(N,D,E,E2,W, IND,IERR,RVI)

INTEGER I,J,K,L,M,N,II,MML,TAG,!ERR REAL D(N),E(N),E2(N),W(N),RVI(N) REAL B,C,P,G,P,R,S,MACHEP REAL SQRT,ABS,SIGN INTEGER IND(N)


MACHEP = ?

IERR = 0

K = 0 TAG = 0

DO i00 1 = i, N w(1) = D(I) IF (I .NE. i) RVI(I-I) = E(i)

100 CONTINUE

E2(1) = 0.0 RVI(N) = 0.0

DO 290 L = i, N J = 0

C ********** LOOK FOR SMALL SUB-DIAGONAL ELEMENT **********

105 DO ii0 M = L, N IF (M .EQ. N) GO TO 120 IF (ABS(RVI(M)) .LE. MACHEP * (ABS(W(M)) + ABS(W(M+I))))

X GO TO 120 C ********** GUARD AGAINST UNDERFLOWED ELEMENT OF E2 **********

IF (E2(M+I) .EQ. 0.0) GO TO 125

ii0 CONTINUE

C

120

125

130

IF (M .LE. K) GO TO 130 IF (M ,NE. N) E2(M+I) = 0.0

K = M TAG = TAG + I P = W(L) IF (M .EQ. L) GO TO 215 IF (J .EQ. 30) GO TO i000 J = J + i

********** FORM SHIFT ********** G = (W(L+I) - P) / (2.0 * RVI(L)) R = SQRT (G'G+1.0) G = W(M) - P + RVI(L) / (g + SIGN(R,G))

S = 1.0 C = 1,0 P = 0.0 MML = M - L

376

7.1-182

150

160

200

********** FOR I--M-I STEP -i UNTIL L DO -- **********

DO 200 II = i, MML

I = M - II

F = S * RVI(I)

B = C * RVI(I)

IF (ABS(F) .LT. ABS(G)) GO TO 150

C = G / F

R = SQRT(C*C+I.0)

RVI(I+I) = F * R

S = 1 . 0 / R C = C * S

GO TO 160

S = F / G

R = SQRT(S*S+I.0)

RVI(I+I) = G * R

C = 1.0 / R

S = S * C

G = W(I+I) - P

R = (W(1) - G) * S + 2.0 * C * B

P = S * R

W(I+I) = G + P

G = C * R - B

CONTINUE

W(L) = W(L) - P

RVI(L) = G

RVI(M) = 0.0

GO TO 105

********** ORDER EIGENVALUES **********

215 IF (L .EQ. I) GO TO 250

********** FOR I=L STEP -i UNTIL 2 DO -- **********

DO 230 II = 2, L

I = L 4. 2 - II

IF (P .GE. W(I-I)) GO TO 270

w(i) = w(i-1)

IND(I) = IND(I-I)

230 CONTINUE

250 I = 1

270 W(I) = P

IND(I) = TAG

290 CONTINUE

GO TO I001



i000 IERR = L

i001 RETURN

END

377

7.1-183

NATS PROJECT


F291 IMTQLI


May, 1972

i. PURPOSE.

The Fortran IV subroutine IMTQLI determines the eigenvalues of a symmetric tridiagonal matrix using the implicit QL method.

2. USAGE.

A~ Calling Sequence.


SUBROUTINE IMTQLI(N,D,E,IERR)



is a working precision real one-dimensional variable of dimension at least N. On input, it contains the diagonal elements of the symmetric tridiagonal matrix. On output, it contains the eigenvalues of this matrix in ascending order.

is a working precision real one-dimensional variable of dimension at least N. On input, the last N-I positions in this array contain the subdiagonal elements of the symmetric tridiagonal matrix. E(1) is arbitrary. Note that IMTQLI destroys E.

378

7.1-184



If more than 30 iterations are required to determine an eigenvalue, IMTQLI terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues in the D array should be correct for indices 1,2,...,IERR-I. These eigenvalues are ordered but are not necessarily the smallest IERR-I eigenvalues.



The subroutine TQLI (F289) can also be used to compute the eigenvalues of a symmetric tridiagonal matrix. Note, however, that TQLI does not perform well on matrices whose successive row sums vary widely in magnitude and are not strictly increasing from the first to the last row. IMTQLI is not sensitive to such row sums and is therefore especially recommended for symmetric tridiagonal matrices whose structure is not known.

To determine the eigenvalues of a full symmetric matrix, IMTQLI should be preceded by TREDI (F277) to provide a suitable symmetric tridiagonal matrix for IMTQLI.

To determine the eigenvalues of a complex Hermitian matrix, IMTQLI should be preceded by HTRIDI (F284) to provide a suitable real symmetric tridiagonal matrix for IMTQLI.

Note, however, that although IMTQLI may perform better on symmetric tridiagonal matrices poorly structured in the above sense, TREDI and HTRIDI may also perform poorly on such full symmetric and complex Hermitian matrices. Hence, any advantage in using IMTQLI over TQLI may be overshadowed by a poor performance in TREDI or HTRIDI.

379

7.1-185

The eigenvalues of certain non-symmetric tridiagonal matrices can be computed using the combination of FIGI (F280) and IMTQLI. See F280 for the description of this special class of matrices. For such matrices, IMTQLI should be preceded by FIGI to provide a suitable symmetric matrix for IMTQLI.


The eigenvalues are determined by the implicit QL method. The essence of this method is a process whereby a sequence of symmetric tridiagonal matrices, unitari!y similar to the original symmetric tridiagonal matrix, is formed which converges to a diagonal matrix. The rate of convergence of this sequence is improved by implicitly shifting the origin at each iteration. Before each iteration, the symmetric tridiagona! matrix is checked for a possible splitting into submatrices. If a splitting occurs, only the uppermost submatrix participates in the next iteration. The eigenvalues are ordered in ascending order as they are found.

The origin shift at each iteration is the eigenvalue of the current uppermost 2x2 principal minor closer to the first diagonal element of this minor. Whenever the uppermost ixl principal submatrix finally splits from the rest of the matrix, its element is taken to be an eigenvalue of the original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of order i. The tolerances in the splitting tests are proportional to the relative machine precision.

This subroutine is a translation of the Algol procedure IMTQLI written and discussed in detail by Martin and Wilkinson (I) and modified by Dubrulle (2).

4. REFERENCES.


2) Dubrulle, A.~ A Short Note on the Implicit QL Algorithm, Num~ Math. 15,450 (1970). (Combined With (I) in Handbook for Automatic Computation, volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution II/4, 241-248, Springer-Verlag, 1971.)

380

7.1-186

5. CHECKOUT.

A. Test Cases.


B. Accuracy.

The subroutine IMTQLI is numerically 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.

381

7. 1-187

C

C C C C

SUBROUTINE IMTQLI(N,D,E,IERR)

INTEGER I,J,L,M,N,!!,MML,IERR REAL D(N),E(N)

REAL B,C,F,G,P,R,S,MACHEP

REAL SQRT,ABS,SIGN



**********

MACHEP = ?

IERR = 0

IF (N .EQ. i) GO TO I001

DO i00 i = 2, N

100 E(I-I) = E(I)

E(N) -- 0.0

DO 290 L = i, N

J = 0 ********** LOOK FOR SMALL SUB-DIAGONAL ELEMENT **********

105 DO Ii0 M = L, N IF (M .EQ. N) GO TO 120 IF (ABS(E(M)) .LE. MACHEP * (ABS(D(M)) + ABS(D(M+I))))

X GO TO 120

i i0 CONTINUE

120 P = D ( L )

IF (M .EQ. L) ~O TO 215 IF (J .EQ. 30) GO TO i000

J = J + i ********** FORM SHIFT **********

G = (D(L+I) - P) / (2.0 * E(L))

R = SQRT(G*G+I.O) G = D(M) - P + E(L) / (G + SIGN(R,G))

S = 1.0

C = 1.0 P = 0.0

MML = M - L ********** FOR I=M-I STEP -I UNTIL L DO -- **********

DO 200 II = I, MML I = M - !I F = s * E ( I )

B = C * E ( I ) IF (ABS(F) .LT. ABS(G)) GO TO 150

C = G / F R = SQRT(C*C+I.O) E(I+I) = F * R s= i.o /R C = C * S GO TO 160

382

7. 1-188

150 S = F / G

R = SQRT(S*S+I.O)

E(I+I) = G * R

c= i.o /R S = S * C

160 G = D(I+I) - e

R = (D(1) - G) * S + 2.0 * C * B

P = S * R

D(I+I) = G + P

G = C * R - B

200 CONTINUE

D(L) = D(L) - P

E(L) = G

E(M) = 0.0

GO TO 105

********** ORDER EIGENVALUES **********

215 IF (L .EQ. i) GO TO 250

********** FOR I=L STEP -i UNTIL 2 DO -- **********

DO 230 II = 2, L

I = L + 2 - II

IF (e .GE. D(I-I)) GO TO 270

D(1) = D(I-I)

230 CONTINUE

250 I = 1

270 D(I) = P

290 CONTINUE

GO TO i001


C EIGENVALUE AFTER 30 ITERATIONS ********** i000 IERR = L

i001 RETURN

END

383

7.1-189

NATS PROJECT


F292 IMTQL2

A Fortran IV Subroutine to Determine the Eigenvalues and Eigenvectors of a Symmetric Tridiagonal Matrix.

May, 1972

I. PURPOSE.

The Fortran IV subroutine IMTQL2 determines the eigenvalues and eigenvectors of a symmetric tridiagonal matrix. IMTQL2 uses the implicit QL method to compute the eigenvalues and accumulates the QL transformations to compute the eigenvectors. The eigenvectors of a full symmetric matrix can also be computed directly by IMTQL2, if TRED2 (F278) has been used to reduce this matrix to tridiagonal form.

2. USAGE.



SUBROUTINE IMTQL2(NM,N,D,E,Z,IERR)





384

7.1-190

IERR

is a working precision real one-dimensional variable of dimension at least N. On input, the last N-I positions in this array contain the subdiagonal elements of the symmetric tridiagonal matrix. E(1) is arbitrary. Note that IMTQL2 destroys E.

is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. If the eigenvectors of the symmetric tridiagonal matrix are desired, then on input, Z contains the identity matrix of order N, and on output, contains the orthonormal eigenvectors of this tridiagonal matrix. If the eigenvectors of a full symmetric matrix are desired, then on input, Z contains the transformation matrix produced in TRED2 which reduced the full matrix to tridiagonal form, and on output, contains the orthonormal eigenvectors of this full symmetric matrix.



If more than 30 iterations are required to determine an eigenvalue, IMTQL2 terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues and eigenvectors in the D and Z arrays should be correct for indices 1,2,...,IERR-I, but the eigenvalues are unordered.



The subroutine TQL2 (F290) can also be used to compute the eigenvalues and eigenvectors of a symmetric tridiagonal matrix. Note, however, that TQL2 does not perform well on matrices whose successive row sums vary widely in magnitude and are not strictly increasing from the first to the last row. IMTQL2 is not sensitive to such row sums and is therefore especially recommended for symmetric tridiagonal matrices whose structure is not known.

385

7.1-191

To determine the eigenvalues and eigenvectors of a full symmetric matrix, IMTQL2 should be preceded by TRED2 (F278) to provide a suitable symmetric tridiagonal matrix for IMTQL2.

To determine the eigenvalues and eigenvectors of a complex Hermitian matrix, IMTQL2 should be preceded by HTR!DI (F284) to provide a suitable real symmetric tridiagonal matrix for IMTQL2, and the input array Z to IMTQL2 should be initialized to the identity matrix. IMTQL2 should then be followed by HTRIBK (F285) to back transform the eigenvectors from IMTQL2 into those of the original matrix.

Note~ however, that although !MTQL2 may perform better on symmetric tridiagonal matrices poorly structured in the above sense, TRED2 and HTRIDI may also perform poorly on such full symmetric and complex Hermitian matrices. Hence, any advantage in using IMTQL2 over TQL2 may be overshadowed by a poor performance in TRED2 or HTRIDI.

The eigenvalues and eigenvectors of certain non- symmetric tridiagonal matrices can be computed using the combination of FIGI2 (F222) and IMTQL2. See F222 for the description of this special class of matrices. For such matrices, IMTQL2 should be preceded by FIGI2 to provide a suitable symmetric matrix for IMTQL2.


The eigenva!ues are determined by the implicit QL method. The essence of this method is a process whereby a sequence of symmetric tridiagonal matrices, unitarily similar to the original symmetric tridiagonal matrix, is formed which converges to a diagonal matrix. The rate of convergence of this sequence is improved by implicitly shifting the origin at each iteration~ Before each iteration, the symmetric tridiagonal matrix is checked for a possible splitting into submatrices. If a splitting occurs, only the uppermost submatrix participates in the next iteration. The similarity transformations used in each iteration are accumulated in the Z array, producing the orthonormal eigenvectors for the original matrix. Finally, the eigenvalues are ordered in ascending order and the eigenveetors are ordered consistently.

The origin shift at each iteration is the eigenvalue of the current uppermost 2x2 principal minor closer to the first diagonal element of this minor. Whenever the uppermost ixl principal submatrix finally splits from the rest of the matrix, its element is taken to be an eigenvalue of the

386

7.1-192

original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of order i. The tolerances in the splitting tests are proportional to the relative machine precision.

This subroutine is a translation of the Algol procedure IMTQL2 written and discussed in detail by Martin and Wilkinson (i) and modified by Dubrulle (2).

4. REFERENCES.


2) Dubrulle, A., A Short Note on the Implicit QL Algorithm, Num. Math. 15,450 (1970). (Combined With (i) in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/4, 241-248, Springer-Verlag, 1971.)

5. CHECKOUT.

A. Test Cases.


B. Accuracy.

The subroutine IMTQL2 is numerically 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 and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.

387

7.1-193

C C

C C

C

SUBROUTINE IMTQL2(NM,N,D,E,Z,IERR)

INTEGER I,J,K,L,M,N, II,NM,MML,IERR

REAL D (N) ,E(N), Z (NM,N) REAL B,C,F,G,P,R,S,MACHEP

REAL SQRT,ABS,SiGN


MACHEP = ?

IERR = 0


DO i00 I = 2, N i00 E(I-I) = E(1)

E(N) = 0.0

DO 240 L = I, N

J = 0 ********** LOOK FOR SMALL SUB-DIAGONAL ELEMENT **********

105 DO ii0 M = L, N IF (M .EQ. N) GO TO 120 IF (ABS(E(M)) oLE. MACHEP * (ABS(D(M)) + ABS(D(M+I))))

X GO TO 120

Ii0 CONTINUE

120 P = D (L) IF (M .EQ. L) GO TO 240 IF (J .EQ. 30) GO TO I000

J = J + 1 ********** FORM SHIFT **********

G = (D(L+I) - P) / (2.0 * E(L))

R = SQRT (G*G+I. 0) G = D(M) - P + E(L) / (G + SIGN(R,G))

S = 1.0 C = 1.0

P = 0.0 MML = M - L

********** FOR I=M-I STEP -I UNTIL L DO -- **********

DO 200 II = I, MML

I = M - I! F = S * E(1) B = C * E(1) IF (ABS(F) .LT. ABS(G)) GO TO 150

C = G / F R = SQRT(C*C+I.O) E(I+I) = F * R S = 1.0 / R C = C * S GO TO 160

388

7.1-194

150 S = F / G

R = SQRT(S*S+I.0)

E(I+I) = G * R

C= 1.0 /R

S = S * C

160 G = D(I+I) - P

R = (D(1) - G) * S + 2.0 * C * B

P = S * R

D(I+I) = G + P

G = C * R - B

• ********* FORM VECTOR **********

DO 180 K = I, N

F = Z(K,I+I)

Z(K,I+I) = S * Z(K,I) + C * F

Z(K,I) = C * Z(K,I) - S * F

180 CONTINUE

200 CONTINUE

D(L) = D(L) - P

E(L) = G

E(M) = 0.0

GO TO 105

240 CONTINUE

********** ORDER EIGENVALUES AND EIGENVECTORS **********

DO 300 II = 2, N

I = II - i

K = I

e = D(1)

260

DO 260 J = II, N

IF (D(J) .GE. P) GO TO 260

K = J

P = D(J)

CONTINUE

IF (K .EQ. I) GO TO 300

D(K) = D(1)

D(1) = P

280

DO 280 J = I, N

P = Z(J,l)

Z(J,I) = Z(J,K)

Z(J,K) = P

CONTINUE

300 CONTINUE

GO TO i001



i000 IERR = L

i001 RETURN

END

389

7.1-195

NATS PROJECT


F288-2 iNVIT

A Fortran IV Subroutine to Determine Those Eigenvectors of a Real Upper Hessenberg Matrix Corresponding to Specified Eigenvalues.

May, 1972 July, 1975

1. PURPOSE.

The Fortran IV subroutine INVIT computes the eigenvectors of a real upper Hessenberg matrix corresponding to specified eigenvalues using inverse iteration.

2. USAGE.



SUBROUTINE INVlT(NM,NgA,WR,WI,SELECT,MM,M,Z~ IERR,RMI,RVI,RV2)




is a working precision real input two- dimensional variable with row dimension NM and column dimension at least N containing the upper Hessenberg matrix.

390

7.1-196

WR,WI

SELECT

MM

are working precision real one-dimensional variables of dimension at least N. On input, they contain the real and imaginary parts, respectively, of the eigenvalues of the Hessenberg matrix. The eigenvalues need not be ordered, except that complex conjugate eigenvalues must appear consecutively and eigenvalues of any submatrix of the input Hessenberg matrix must have indices in WR,WI which lie between the boundary indices for that submatrix. These ordering constraints are satisfied by the output eigenvalues from HQR (F286). On output, the eigenvalues are unaltered, except that the real parts of close eigenvalues may be perturbed slightly in an attempt to obtain independent eigenvectors.

is a logical one-dimensional variable of dimension at least N. On input, the true elements flag those eigenvalues whose eigenvectors are desired. If both of a pair of complex conjugate eigenvalues are flagged, the second flag is set false and only the eigenvector corresponding to the first of these is computed.

is an integer input variable set equal to an upper bound for the number of columns required to store the real and imaginary parts of the requested eigenvectors. The eigenvector corresponding to a real (complex) eigenvalue requires one (two) column(s).

is an integer output variable set equal to the number of columns actually used to store the eigenvectors.

is a working precision real output two- dimensional variable with row dimension NM and column dimension at least MM containing the eigenvectors corresponding to the flagged eigenvalues. The real and imaginary parts of complex eigenvectors are stored in consecutive columns with the real part first. The eigenvectors are packed into the columns of Z starting at the first column.

391

7.1-197


RM 1 is a working precision real temporary array variable of dimension at least N*N. This array holds the triangularized form of the upper Hessenberg matrix used in the inverse iteration process.

RVI,RV2 are working precision real temporary one- dimensional variables of dimension at least N. They hold the approximate eigenvectors during the inverse iteration process.


If more than MM columns of Z are necessary to store the eigenvectors corresponding to the flagged eigenvalues, INVIT terminates with IERR set to -(2*N+I). In this case, M is either MM or MM-I and is the number of columns of Z containing eigenvectors already computed.

If none of the initial vectors for the inverse iteration process produces an acceptable approximation to an eigenvector, INVIT terminates the computation for that eigenvector and sets IERR to -K where K is the index of the associated eigenvalue. If this failure occurs for more than one eigenvalue, the last occurrence is recorded in IERR. The columns of Z corresponding to failures of the above sort are set to zero vectors.

If both of the above error conditions occur, INVIT terminates with IERR set to -(N+K) where K is the index of the last eigenvalue whose inverse iteration process failed. The columns of Z corresponding to failures in the inverse iteration process are set to zero vectors, and in this case, M is the number of columns of Z containing eigenvectors already computed.

If neither of the above error conditions occurs, INVIT sets IERR to zero.

392

7.1-198


To determine eigenvectors corresponding to some of the eigenvalues of a real general matrix, INVIT should be preceded by ELMHES (F273) or ORTHES (F275) and HQR (F286). ELMHES or ORTHES provides a suitable upper Hessenberg matrix for INVIT and HQR determines the eigenvalues of this Hessenberg matrix. INVIT should then be followed by ELMBAK (F274) or ORTBAK (F276) to back transform the eigenvectors from INVIT into those of the original matrix. Note: the upper Hessenberg matrix and the two adjacent subdiagonals must be saved before HQR, since HQR destroys this part of A.

It is recommended in general that BALANC (F269) be used before ELMHES or ORTHES in which case BALBAK (F270) must be used after ELMBAK or ORTBAK.

In this implementation, the arithmetic is real throughout except for complex division and complex absolute value.


The eigenvectors are determined by inverse iteration. In INVIT, this is a process whereby a vector X1 satisfying the matrix linear equation U'X1 = X0 is computed, where X0 is an initial vector and U is the upper triangular factor in the LU decomposition of the matrix B-W*I with partial pivoting. W is an approximate eigenvalue of a leading submatrix B of the Hessenberg matrix in A. The vector X1 is accepted as an eigenvector of B if the norm of X1 is sufficiently larger than the norm of X0. This eigenvector of B is transformed to an eigenvector of A by simply appending zero components to it.

The computations for the real and complex eigenvectors are separate. In the real case, the factor U in the LU decomposition is stored in the full lower triangle of the array RMI, and in the complex case, the real part of U is stored in the full lower triangle of RMI and the imaginary part of U is stored in the upper triangle of RMI above the superdiagonal augmented by the two columns of Z that will later store the complex eigenvector. (Internally, RMI is treated as a two-dimensional NxN array.)

The acceptance criterion for X1 is a growth test of its norm. If MACHEP denotes the relative machine precision, then currently, X1 is rejected as an eigenveetor if

SQRT(UK)*!!B!!*MACHEP*!!XI!! .LT. !!X0!!/10.0

393

7.1-199

where UK is the order of the submatrix B whose eigenvector is being computed and the norm !! !! is the infinity norm. At most UK orthogonal initial vectors X0 are tried to obtain the required growth. If no vector is accepted, the parameter !ERR is set to indicate this failure and !NVIT proceeds to compute the next eigenvector.

The real parts of close or identical eigenvalues whose eigenvectors are desired may be perturbed slightly in an attempt to obtain independent eigenvectors (if they exist). If required, such perturbations are positive and small multiples of MACHEP*Z!B!!.

This subroutine is a translation of the Algol procedure INVIT written and discussed in detail by Peters and Wilkinson (i)°

4o REFERENCES.

i) Peters, G. and Wilkinson, J.H., The Calculation of Specified Eigenvectors by Inverse Iteration, Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C, Reinsch, Contribution II/18, 418-439, Springer-Verlag, 1971.

5. CHECKOUT.

A. Test Cases.


B° Accuracy.

The accuracy of INVIT can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real upper Hessenberg matrices. In these paths, this subroutine is numerically stable (i)o This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original upper Hessenberg matrix.

394

7.1-200

C C C

SUBROUTINE INVlT(NM,N,A,WR,WI,SELECT,MM,M,Z,IERR,RMI,RVI,RV2)

INTEGER I,J,K,L,M,N,S,II,IP,MM,MP,NM,NS,NI,UK, IPI,ITS,KMI,IERR REAL A(NM,N),WR(N),WI(N),Z(NM,MM),RMI(N,N),RVI(N),RV2(N) REAL T,W,X,Y,EPS3,NORM,NORMV,GROWTO,ILAMBD,MACHEP,RLAMBD,UKROOT REAL SQRT,CABS~ABS,FLOAT INTEGER lABS LOGICAL SELECT(N) COMPLEX Z3 COMPLEX CMPLX REAL REAL,AIMAG


MACHEP = ?

IERR = 0 UK = 0 S = i

********** IP = 0, REAL EIGENVALUE

i, FIRST OF CONJUGATE COMPLEX PAIR -i, SECOND OF CONJUGATE COMPLEX PAIR **********

IP = 0 N1 = N - 1

DO 980 K : i, N

IF (WI(K) .EQ. 0.0 .OR. IP .LT. 0) GO TO i00 IP = i

IF (SELECT(K) .AND. SELECT(K+I)) SELECT(K+1) = .FALSE. i00 IF (.NOT. SELECT(K)) GO TO 960

IF (WI(K) .RE. 0.0) S = S + I IF (S .GT. MM) GO TO i000 IF (UK .GE. K) GO TO 200

********** CHECK FOR POSSIBLE SPLITTING ********** DO 120 UK = K, N

IF (UK .EQ. N) GO TO 140 IF (A(UK+I,UK) .EQ. 0.0) GO TO 140

120 CONTINUE

********** COMPUTE INFINITY NORM OF LEADING UK BY UK [HESSENBERG) MATRIX **********

140 NORM = 0.0 MP = 1

160

180

DO 180 1 = i, UK X=0.0

DO 160 J = MP, UK X = X + ABS(A(I,J))

IF (X .GT. NORM) NORM = X MP = I

CONTINUE

395

7.1-201

C C

C

C

C

C

C

C

200

220

240

X 260

280

300

320

********** EPS3 REPLACES ZERO PIVOT IN DECOMPOSITION

AND CLOSE ROOTS ARE MODIFIED BY EPS3 ********** IF (NORM .EQ. 0.0) NORM = i°0

EPS3 = MACHEP * NORM ********** GROWTO IS THE CRITERION FOR THE GROWTH **********

UKROOT = SQRT(FLOAT(UK))

GROWTO = 1.0E-I / UKROOT

RLAMBD = WR(K)

ILAMBD = WI(K) IF (K .EQ. i) GO TO 280 KMI = K - I

GO TO 240 ********** PERTURB EIGENVALUE IF IT IS CLOSE

TO ANY PREVIOUS EIGENVALUE ********** RLAMBD = RLAMBD + EPS3

********** FOR I=K-I STEP -i UNTIL 1 DO -- **********

DO 260 II = i, KMI I = K - II IF (SELECT(l) .AND. ABS(WR(1)-RLAMBD) .LT. EPS3 .AND.

ABS(WI(1)-ILAMBD) .LT. EPS3) GO TO 220

CONTINUE

WR(K) = RLAMBD ********** PERTURB CONJUGATE EIGENVALUE TO MATCH **********

IPI = K + IP

WR(IPI) = RLAMBD ********** FORM UPPER HESSENBERG A-RLAMBD*I (TRANSPOSED)

AND INITIAL REAL VECTOR ********** MP = !

DO 320 I = I, UK

DO 300 J = MP, UK RMI(J,I) = A(I,J)

RMI(I,I) = RMI(I,I) - RLAMBD

MP = I RVI(1) = EPS3

CONTINUE

ITS = 0 IF (ILAMBD .NE. 0.0) GO TO 520

********** REAL EIGENVALUE. TRIANGULAR DECOMPOSITION WITH INTERCHANGES, REPLACING ZERO PIVOTS BY EPS3 **********

IF (UK ~EQ. i) GO TO 420

DO 400 I = 2, UK MP = I m 1 IF (ABS(RMI(MP, I)) .LE. ABS(RMI(MP,MP))) GO TO 360

396

7.1-202

340

360

380

400

420

440

460

480 500

520

540

550

DO 340 J = MP, UK

Y = RMI(J,I) RMI(J,I) = RMI(J,MP) RMI(J,MP) = Y

CONTINUE

IF (RMI(MP,MP) .EQ. 0.0) RMI(MP,MP) = EPS3 X = RMI(MP,I) / RMI(MP,MP) IF (X .EQ. 0.0) GO TO 400

DO 380 J = I, UK

RMI(J,I) = RMI(J,I) - X * RMI(J,MP)

CONTINUE

IF (RMI(UK,UK) .EQ. 0.0) RMI(UK,UK) = EPS3

********** BACK SUBSTITUTION FOR REAL VECTOR FOR I=UK STEP -i UNTIL 1 DO -- **********

DO 500 II = i, UK I = UK + 1 - II Y = RVI (I)

IF (I .EQ. UK) GO TO 480 IPI = I + 1

DO 460 J = IPI, UK Y = Y - RMI(J,I) * RVI(J)

RVI(1) = Y / RMI(I,I) CONTINUE

GO TO 740

********** COMPLEX EIGENVALUE.

TRIANGULAR DECOMPOSITION WITH INTERCHANGES, REPLACING ZERO PIVOTS BY EPS3. STORE IMAGINARY PARTS IN UPPER TRIANGLE STARTING AT (1,3) **********

NS = N - S Z(I,S-I) = -ILAMBD Z(I,S) = 0.0

IF (N .EQ. 2) GO TO 550 RMI(I,3) = -ILAMBD Z(I,S-I) = 0.0

IF (N .EQ. 3) GO TO 550

DO 540 I = 4, N RMI(I,I) = 0.0

DO 640 I = 2, UK MP = I - I W = RMI(MP,I) IF (I .LT. N) T = RMI(MP, I+I) IF (I .EQ. N) T = E(MP,S-I) X = RMI(MP,MP) * RMI(MP,MP) + T * T IF (W * W .LE. X) GO TO 580

397

7. 1-203

555

560

570

580

600

610

615 620

X = RMI(MP,MP) / W Y = T / W RMI(MP,MP) = W

IF (I .LT. N) RMI(MP,I+I) = 0.0 IF (I .EQ. N) Z(MP,S-I) = 0.0

DO 560 J = !, UK W = RMI(J,I)

RMI(J,I) = RMI(J,MP) - X * W

RMI(J,MP) = W IF (J .LT. NI) GO TO 555

L = J - NS Z(!,L) = Z(MP,L) - Y * W

Z(MP,L) = 0.0

GO TO 560 RMI(I,J+2) = RMI(MP,J+2) - Y * W

RMI(MP,J+2) = 0.0

CONTINUE

RMI(I,!) = RMI(I,I) - Y * ILAMBD

IF (I oLT. NI) GO TO 570

L = I - NS

Z(MP,L) = -ILAMBD Z(I,L) = Z(I,L) + X * ILAMBD

GO TO 640 RMI(MP,I+2) = -ILAMBD RMI(I,I+2) = RMI(I,I+2) + X * ILAMBD

GO TO 640 IF (X .NE. 0.0) GO TO 600

RMI(MP,MP) = EPS3 IF (I .LT. N) RMI(MP,I+I) = 0.0

IF (I .EQ. N) Z(MP,S-I) = 0.0

T = 0.0 X = EPS3 * EPS3

w = w / x X = RMI(MP,MP) * W

Y = -T * W

DO 620 J = I, UK IF (J .LT. NI) GO TO 610

L = J - NS T = Z(MP,L) Z(I,L) = -X * T - Y * RMI(J,MP)

GO TO 615 T = RMI(MP,J+2) RMI(I,J+2) = -X * T - Y * RMI(J,MP) RMI(J,I) = RMI(J,I) - X * RMI(J,MP) + Y * T

CONTINUE

398

7.1-204

C

C

630 640

650

655

660

670

675

680

700

IF (I .LT. NI) GO TO 630

L = I - NS

Z(I,L) = Z(I,L) - ILAMBD GO TO 640 RMI(I,I+2) = RMI(I,I+2) - ILAMBD

CONTINUE

IF (UK .LT. NI) GO TO 650 L = UK - NS T = Z (UK, L) GO TO 655

T = RMI(UK,UK+2)

IF (RMI(UK,UK) .EQ. 0.0 .AND. T .EQ. 0.0) RMI(UK,UK) = EPS3

********** BACK SUBSTITUTION FOR COMPLEX VECTOR FOR I=UK STEP -I UNTIL 1 DO -- **********

DO 720 II = i, UK

I = UK + i - II

X = RVI (I) Y = 0.0

IF (I .EQ. UK) GO TO 700 IPI = I + i

DO 680 J = IPI, UK

IF (J .LT. NI) GO TO 670 L = J - NS T = Z(I,L)

GO TO 675

T = RMI(I,J+2)

X = X - RMI(J,I) * RVI(J) + T * RV2(J)

Y = Y - RMI(J,I) * RV2(J) - T * RVI(J) CONTINUE

IF (I .LT. Nt) GO TO 710 L = I - NS T = Z(I,L) GO TO 715

710 T = RMI(I,I+2)

715 z3 = CMPLX(X,Y) / CMPLX(RMI(I,I),T) RVI(I) = REAL(Z3)

RV2(I) = AIMAG(Z3) 720 CONTINUE

********** ACCEPTANCE TEST FOR REAL OR COMPLEX EIGENVECTOR AND NORMALIZATION **********

740 ITS = ITS + 1

NORM = 0.0

NORMV = 0.0

DO 78O I = i, UK

IF (ILAMBD .EQo 0.0)X = ABS(RVI(I))

IF (ILAMBD .NE. 0.0) X = CABS(CMPLX(RVI(I),RV2(I))) IF (NORMV .GE. X) GO TO 760 NORMV -- X J = I

399

7.1-205

C

C

760

780 NORM = NORM + X

CONTINUE

IF (NORM ,LT. GROWTO) GO TO 840

********** ACCEPT VECTOR ********** X = RVI(J) IF (ILAMBD .EQ. 0.0) X = 1.0 / X IF (ILAMBD .NE. 0.0) Y = RV2(J)

800

820

DO 820 ! = I~ UK

IF (ILAMBD .NE. 0.0) GO TO 800 z(i,s) = RVI(I) * X

GO TO 820 Z3 = CMPLX(RVI(1),RV2(1)) / CMPLX(X,Y)

Z(I,S-I) = REAL(Z3) Z(I,S) = AIMAG(Z3)

CONTINUE

840

IF (UK .EQ° N) GO TO 940 J = UK + I

GO TO 900 ********** IN-LINE PROCEDURE FOR CHOOSING

A NEW STARTING VECTOR ********** IF (ITS .GE. UK) GO TO 880

X = UKROOT Y = EPS3 1 (X + 1.0)

RVI(1) = EPS3

DO 860 1 = 2, UK

860 RVI(1) = Y

J = UK - ITS + i RVI(J) = RVI(J) - EPS3 * X IF (!LAMBD .EQ. 0.0) GO TO 440

GO TO 660 • ********* SET ERROR -- UNACCEPTED EIGENVECTOR **********

880 J = ! IERR = -K

• ********* SET REMAINING VECTOR COMPONENTS TO ZERO **********

900 DO 920 1 = J, N z(i,s) = o.o IF (!LAMBD .NE. 0.0) Z(I,S-I) = 0.0

920 CONTINUE

940 S = S + 1 960 IF (ie .EQ. (-i)) Ie = 0

IF (IP ,EQ. i) IP = -i

980 CONTINUE

GO TO i001

400

7.1-206

C ********** SET ERROR -- UNDERESTIMATE OF EIGENVECTOR

C SPACE REQUIRED **********

i000 IF (IERR .NE. 0) IERR = IERR - N

IF (IERR .EQ. 0) IERR = -(2 * N + i)

i001M = S - 1 - IABS(IP)

RETURN

END

401

7.1-207

NATS PROJECT


F276-2 ORTBAK

A Fortran IV Subroutine to Back Transform the Eigenvectors of that Upper Hessenberg Matrix Determined by ORTHES.

May, 1972 July, 1975

I. PURPOSE°

The Fortran IV subroutine ORTBAK forms the eigenvectors of a real general matrix from the eigenvectors of that upper Hessenberg matrix determined by ORTHES (F275).

2. USAGE.



SUBROUTINE ORTBAK(NM, LOW, IGN,A,ORT,M,Z)



LOW,IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F269 for the details. If the matrix is not balanced, set LOW to 1 and IGH to the order of the matrix.

A is a working precision real input two- dimensional variable with row dimension NM and column dimension at least IGH. The strict lower triangle of A contains some information about the orthogona!

402

7.1-208

ORT

M

transformations used in the reduction to the Hessenberg form. The remaining upper part of the matrix is arbitrary. See section 3 of F275 for the details.

is a working precision real one-dimensional variable of dimension at least IGH. On input, ORT contains further information about the orthogonal transformations used in the reduction by ORTHES. See section 3 of F275 for the details. ORT is used for temporary storage within ORTBAK and is not restored.




None.


This subroutine should be used in conjunction with the subroutine ORTHES (F275).

The real and imaginary parts of an eigenvector need not be stored in consecutive columns of Z.




F = Q CQ

403

7.1-209

where Q is a product of the orthogonal matrices encoded in ORT and in a lower triangle of A under F. Then, given an array Z of column vectors, ORTBAK computes the matrix product QZ. If the real and imaginary parts of the eigenvectors of F are columns of the array Z, then ORTBAK forms the eigenvectors of C in their place.

This subroutine is a translation of the Algol procedure ORTBAK written and discussed in detail by Martin and Wilkinson (I).

4. REFERENCES°

i) Martin, R.S. and Wilkinson, J.H., Similarity Reduction of a General Matrix to Hessenberg Form, Num. Math. 12,349-368 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/13, 339-358, Springer-Verlag, 1971.)

5. CHECKOUT.

Ao Test Cases.


Bo Accuracy~

The accuracy of ORTBAK can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real general matrices. In these paths, this subroutine is numerically stable (I). This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original matrix.

404

7. 1-210

SUBROUTINE ORTBAK(NM,LOW, IGH,A, ORT,M,Z)

INTEGER I,J,M,LA,MM,MP,NM,IGH,KPI,LOW,MPI

REAL A(NM,IGH),ORT(IGH),Z(NM,M) REAL G

IF (M .EQ. 0) GO TO 200 LA = IGH - 1 KPI = LOW + 1


********** FOR MP=IGH-I STEP -I UNTIL LOW+I DO -- ********** DO 140 MM = KPI, LA

MP = LOW + IGH - MM IF (A(MP,MP-I) .EQ. 0.0) GO TO 140 MPI = MP + 1

i00 DO i00 1 = MPI, IGH ORT(1) = A(I,MP-I)

DO 130 J = i , M

G=O.0

i i 0 DO ii0 1 = MP, IGH G = G + ORT(1) * Z(I,J)

• ********* DIVISOR BELOW IS NEGATIVE OF H FORMED IN ORTHES. DOUBLE DIVISION AVOIDS POSSIBLE UNDERFLOW **********

G = (G / ORT(MP)) / A(MP,MP-I)

120

130

DO 120 I = MP, IGH

Z(l,J) = Z(l,J) + G * ORT(1)

CONTINUE

140 CONTINUE

200 RETURN END

405

7.1-2!1

NATS PROJECT


F275 ORTHES

A Fortran IV Subroutine to Reduce a Real General Matrix to Upper Hessenberg Form Using Orthogonal Transformations.

May, 1972

!. PURPOSE.

The Fortran IV subroutine ORTHES reduces a real general matrix to upper Hessenberg form using orthogonal similarity transformations. This reduced form is used by other subroutines to find the eigenvalues and/or eigenvectors of the original matrix. See section 2C for the specific routines,

2. USAGE.

A, Calling Sequence,


SUBROUTINE ORTHES(NM,N,LOW, IGH,A,ORT)




LOW~IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F269 for the details. If the matrix is not balanced, set LOW to 1 and !GH to N.

406

7.1-212

A

0RT

is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. On input, A contains the matrix of order N to be reduced to Hessenberg form. On output, A contains the upper Hessenberg matrix as well as some information about the orthogonal transformations used in the reduction. See section 3 for the details.

is a working precision real output one- dimensional variable of dimension at least IGH containing the remaining information about the orthogonal transformations. See section 3 for the details. Only components LOW+I through IGH are actually used by ORTHES.


None.


If all the eigenvalues of the original matrix are desired, this subroutine should be followed by HQR (F286).

If all the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by ORTRAN (F221) and HQR2 (F287).

If some of the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by HQR (F286), INVIT (F288), and ORTBAK (F276) .

The subroutine ORTHES executes slower than its counterpart ELMHES (F273), which uses elementary similarity transformations. ORTHES is, however, more accurate in some cases. It is recommended that ELMHES be used in general.

If the matrix has elements of widely varying magnitudes, the larger ones should be in the top left-hand corner.

407

7.1-213



A ( T X Y )

= (0 B Z) (0 0 R)

where T and R are upper triangular matrices, B is a square matrix situated in rows and columns LOW through IGH, and X, Y, and Z are rectangular matrices of the appropriate dimensions. Then the subroutine ORTHES performs orthogonal similarity transformations to reduce to Hessenberg form.

The Hessenberg reduction is performed in the following way. Starting with J=LOW, the elements in the J-th column below the diagonal are first scaled, to avoid possible underflow in the transformation that might result in severe departure from orthogonality. The sum of squares SIGMA of these scaled elements is next formed. Then, a vector U and a scalar

T H = U U / 2

define an operator

T p = i - u u / H

which is orthogonal and symmetric and for which the similarity transformation PAP eliminates the elements in the J-th column of A below the subdiagonal.

The non-zero components of U are the elements of the J-th column below the diagonal with the first of them augmented by the square root of SIGMA prefixed by the sign of the subdiagonal element. By saving this component in the array ORT and not overwriting the column elements eliminated in the transformation, full information on ~ is saved for later use in ORTRAN and ORTBAK.

The transformation replaces the subdiagonal element with the square root of SIGMA prefixed by sign opposite to that of the replaced element.


This subroutine is a translation of the Algol procedure ORTHES written and discussed in detail by Martin and Wilkinson (i).

408

7. 1-214

4. REFERENCES.

l) Martin, R.S. and Wilkinson, J.H., Similarity Reduction of a General Matrix to Hessenberg Form, Num. Math. 12,349-368 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/13, 339-358, Springer-Verlag, 1971.)

5. CHECKOUT.

A. Test Cases.


B. Accuracy.

The accuracy of ORTHES can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real general matrices. In these paths, this subroutine is numerically stable (I). This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix hlose to the original matrix.

409

7.1-215

C

C

90

I00

ii0

120

130

140

SUBROUTINE ORTHES(NM,N,LOW, IGH,A,ORT)

INTEGER I,J,M,N,I!,JJ,LA,MP,NM,IGH,KPI,LOW

REAL A(NM,N)~ORT(IGH)

REAL F,G,H,SCALE

REAL SQRT,ABS,SIGN

LA = !GH - I

KPI = LOW + i

IF (LA oLT. KPI) GO TO 200

DO 180 M = KPI, LA

H = 0.0

ORT(M) = 0.0

SCALE = 0.0

********** SCALE COLUMN (ALGOL TOL THEN NOT NEEDED) **********

DO 90 I = M, IGH

SCALE = SCALE + ABS(A(I,M-I))

IF (SCALE .EQ. 0.0) GO TO 180

MP = M + IGH

********** FOR I=IGH STEP -i UNTIL M DO -- **********

DO i00 II = M, IGH

! = MP - II

ORT(1) = A(I,M-I) / SCALE

H = H + ORT(1) * ORT(1)

CONTINUE

G = -SIGN(SQRT(H),ORT(M))

H = H - ORT(M) * G

ORr (M) = ORT (M) - G

• ********* FORM (I-(U*UT)/H) * A **********

DO 130 J = M, N

F = 0.0

• ********* FOR I=IGH STEP -I UNTIL M DO -- **********

DO Ii0 II = M~ IGH

I = MP - II

F = F + ORr(1) * A(I,J)

CONTINUE

F = F / H

DO 120 ! = M, IGH

A(I,J) = A(I,J) - F * ORT(1)

CONTINUE ********** FORM (I-(U*UT)/H)*A*(I-(U*UT)/H) **********

DO 160 I = I, IGH

F=0.0

********** FOR J=IGH STEP -I UNTIL M DO -- **********

DO 140 JJ = M, IGH

J = MP - JJ F = F + ORT(J) * A(I,J)

CONTINUE

410

7.1-216

F = F / H

150

DO 150 J = M, IGH

A(I,J) = A(I,J) - F * ORT(J)

160 CONTINUE

O R T ( M ) = SCALE * O R T ( M ) A(M,M-I) = SCALE * G

180 CONTINUE

200 RETURN

END

411

7.1-217

NATS PROJECT


F221-2 ORTRAN

A Fortran IV Subroutine to Accumulate the Transformations in the Reduction of a Real General Matrix by ORTHES.

May, 1972 July, 1975

I. PURPOSE.

The Fortran IV subroutine ORTRAN accumulates the orthogonal similarity transformations used in the reduction of a real general matrix to upper Hessenberg form by ORTHES (F275).

2. USAGE.



SUBROUTINE ORTRAN(NM,N,LOW, IGH,A,ORT,Z)





412

7.1-218

A

ORT

is a working precision real input two- dimensional variable with row dimension NM and column dimension at least IGH. The strict lower triangle of A contains some information about the orthogonal transformations used in the reduction to the Hessenberg form. The remaining upper part of the matrix is arbitrary. See section 3 of F275 for the details.

is a working precision real one-dimensional variable of dimension at least IGH. On input, ORT contains further information about the orthogonal transformations used in the reduction by ORTHES. See section 3 of F275 for the details. ORT is used for temporary storage within ORTRAN and is not restored.

is a working precision real output two- dimensional variable with row dimension NM and column dimension at least N. It contains the transformation matrix produced in the reduction by ORTHES to the upper Hessenberg form.


None.


If all the eigenvalues and eigenvectors of the original matrix are desired, this subroutine follows ORTHES (F275) and should be followed by HQR2 (F287). Otherwise, this subroutine will not ordinarily be used.




T F = Q CQ

where Q is a product of the orthogonal matrices encoded in ORT and in a lower triangle of A under F. Then, ORTRAN accumulates Q into the array Z.

413

7.1-219

This subroutine is a translation of the Algol procedure ORTRANS written and discussed in detail by Peters and Wilkinson (i).

4. REFERENCES.

l) Peters~ G. and Wilkinson, J.H., Eigenvectors of Real and Complex Matrices by LR and QR Triangularizations, Numo Math. 16,181-204 (1970). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/15, 372-395, Springer-Verlag, 1971.)

5. CHECKOUT.

A. Test Cases~


B. Accuracy.

The accuracy of ORTRAN can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real general matrices. In these paths, this subroutine is numerically stable (i). This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original matrix.

414

7 . 1 - 2 2 0

SUBROUTINE ORTRAN(NM~N,LOW,IGH,A~ORT~Z)

INTEGER I,J,N~KL,MM,MP,NM,IGH~LOW~MPI REAL A(NM,IGH),ORT(IGH),Z(NM,N) REAL G

**~******* INITIALIZE Z TO IDENTITY MATRIX ***~****** DO 80 I = i~ N

DO 60 J = i, N 60 Z(l,J) = 0.0

z(I,I) : 1.0 80 CONTINUE

KL = IGH - LOW - 1 IF (EL .LT. I) GO TO 200

***me***** FOR MP=IGH-I STEP -i UNTIL LOW+I DO -- ********** DO 140 MM = i, KL

MP = IGH - MM

IF (A(MP,MP-I) .EQ. 0.0) GO TO 140 MPI = MP + i

I00 DO i00 I = MPI, IGH ORT(1) = A(I,MP-I)

DO 130 J = MP, IGH G=0.0

ii0 DO II0 I = MP, IGH G = G + ORT(1) * Z(I,J)

• ********* DIVISOR BELOW IS NEGATIVE OF H FORMED IN ORTHES. DOUBLE DIVISION AVOIDS POSSIBLE UNDERFLOW *********~

g = (G / ORT(MP)) / A(MP,MP-I)

120 DO 120 I = MP, IGH Z(I,J) = Z(l,J) + G * ORT(1)

130 CONTINUE

140 CONTINUE

200 RETURN END

415

7. 1-221

NATS PROJECT


F298-2 RATQR

A Fortran IV Subroutine to Determine Some Extreme Eigenvaiues of a Symmetric Tridiagonal Matrix.

May, 1972 July, 1975

i. PURPOSE.

The Fortran IV subroutine RATQR determines the algebraically smallest or largest eigenvalues of a symmetric tridiagonal matrix using the rational QR method with Newton corrections.

2. USAGE.

Ao Calling Sequence.


SUBROUTINE RATQR(N~EPSI,D,E,E2, M,W, IND,BD,TYPE, IDEF,IERR)


is an integer input variable set equal to the order of the matrix,

EPSI is a working precision real variable. On input, EPSI specifies a tolerance for the theoretical absolute error of the computed eigenva!ues. If MACHEP denotes the relative machine precision, then if the input EPSI is less than MACHEP times the magnitude of any of the computed eigenvalues, it is reset to a default value described in section 3. The theoretical absolute error in the K-th eigenvalue is usually not greater than K times the output EPSI.

416

7.1-222

E2

M

W

IND

BD



is a working precision real one-dimensional variable of dimension at least N. On input, the last N-I positions in this array contain the squares of the subdiagonal elements of the symmetric tridiagonal matrix. E2(1) is arbitrary. On output, E2(1) is set to 0.0 if the smallest eigenvalues are found and to 2.0 if the largest eigenvalues are found. If any of the elements in E are regarded as negligible, the corresponding elements of E2 are set to zero, and so the matrix splits into a direct sum of submatrices.

is an integer input variable set equal to the number of extreme eigenvalues desired.

is a working precision real output one- dimensional variable of dimension at least N containing the M extreme eigenvalues of the symmetric tridiagonal matrix. If the smallest eigenvalues have been found, they are in ascending order in W. If the largest eigenvalues have been found, they are in descending order in W. W need not be distinct from D.

is an integer output one-dimensional variable of dimension at least N containing the submatrix indices associated with the corresponding M eigenvalues in W. Eigenvalues belonging to the first submatrix have index I, those belonging to the second submatrix have index 2, etc.

is a working precision real output one- dimensional variable of dimension at least N. BD(K) is a tighter bound than K*EPSI for the theoretical error of the K-th eigenvalue W(K), K = 1,2,...,M. BD need not be distinct from E2.

417

7.1-223

TYPE

IDEF

IERR

is a logical input variable set true if the smallest eigenvalues are to be found and set false if the largest eigenvalues are to be found.

is an integer input variable set to 1 if the symmetric tridiagonal matrix is known to be positive definite, set to -i if the matrix is known to be negative definite, and set to 0 otherwise.



If IDEF is set to 1 and TYPE is set true when the input matrix is not positive definite, or if IDEF is set to -i and TYPE is set false when the matrix is not negative definite, RATQR terminates with IERR set to 6*N+I. No eigenvalues are computed. Note: this error return may also be made if M has been inadvertently specified greater than N.

If successive iterates to the K-th eigenvalue are not strictly monotone increasing, RATQR terminates the calculation for that eigenvalue with IERR set to 5*N+K. The sum of all the shifts up to this point is taken as the eigenvalue and the program proceeds to the next eigenvalue calculation. If this failure occurs for more than one eigenvalue, the last occurrence is

recorded in IERR.

If neither of the above error conditions occurs, IERR is set to zero.


To determine extreme eigenvalues of a full symmetric matrix, RATQR should be preceded by TREDI (F277) provide a suitable symmetric tridiagonal matrix for

RATQR.

to

To determine extreme eigenvalues of a complex Hermitian matrix, RATQR should be preceded by HTRIDI (F284) to provide a suitable real symmetric tridiagonal matrix for

RATQR.

418

7.1-224

To determine extreme eigenvalues of certain non- symmetric tridiagonal matrices, RATQR should be preceded by FIGI (F280) to provide a suitable symmetric tridiagonal matrix for RATQR. See F280 a description of this special class of matrices.

for

To determine eigenvectors associated with the computed eigenvalues, RATQR should be followed by TINVlT (F223) and the appropriate back transformation subroutine -- TRBAKI (F279) after TREDI, HTRIBK (F285) after HTRIDI, or BAKVEC (F281) after FIGI.

The subroutine TRIDIB (F237) is generally faster and more accurate than RATQR if the eigenvalues are clustered.


The eigenvalues are determined by the rational QR method with Newton corrections. The essence of this method is a process whereby a sequence of symmetric tridiagonal matrices, unitarily similar to the original symmetric tridiagonal matrix with shifted origin, is formed which converges to a matrix with zero diagonal elements. The origin shifts using the Newton step improve the convergence rate of the sequence.

The algorithm applies to the determination of the algebraically smallest eigenvalues. D is first copied into W and IDEF into variable JDEF. If TYPE is false, RATQR then reverses the signs of the elements of W and negates JDEF.

Next, the subdiagonal elements are tested for negligibility. If an element is considered negligible, its square is set to zero, and so the matrix splits into a direct sum of submatrices. Then if JDEF is not i or if JDEF is 1 and the Gerschgorin lower bound for the smallest eigenvalue is positive, the origin is first shifted so that the Gerschgorin lower bound for the translated matrix is zero.

Starting from the new origin, two QR decompositions are performed providing with additional calculations the Newton step by which the origin is again shifted. This process is repeated until a diagonal element of one of the intermediate matrices becomes negligible. Then the sum of the origin shifts is taken as an eigenvalue, the matrix is deflated by deleting the row and column with the negligible diagonal element (the location of this row serves to identify the submatrix to which the eigenvalue belongs), and the complete process is repeated on the deflated matrix.

419

7.1-225

If at any stage MACHEP times the absolute sum of the origin shifts exceeds EPSI, EPSI is reset to this quantity. A diagonal element is considered negligible if it is no greater than the current EPSI. At each iteration, negligible squared subdiagonal elements (earlier copied into BD) are set to zero to avoid underflows which would otherwise occur.

The algorithm assumes after the initial origin shift that the matrix is positive definite, and so can expect diagonal elements of certain intermediate matrices to be positive. If any of these are negative, then !ERR is flagged indicating that !DEF was set erroneously. Also, because the matrix is positive definite, the sum of the origin shifts must increase. If the sum does not increase, this is considered an irregular end of iteration and IERR is flagged. In this case, the current sum of the origin shifts is taken as an eigenvalue, and the matrix is deflated by deleting the row and column corresponding to the smallest diagonal element.

Finally, if TYPE is false, RATQR again reverses the signs of the elements of W.

This subroutine is a translation of the Algol procedure RATQR written and discussed in detail by Reinsch and Bauer (i).

4. REFERENCES°

i) Reinsch, C. and Bauer, F.L., Rational QR Transformation With Newton Shift for Symmetric Tridiagonal Matrices, Num. Math. 11,264-272 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/6, 257-265, Springer-Verlag, 1971.)

5. CHECKOUT.

A~ Test Cases~


420

7.1-226

B. Accuracy.

The subroutine RATQR is numerically stable when limited to the computation of a few eigenvalues that are not tightly clustered (i); 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.

421

7.1-227

SUBROUTINE RATQR(N,EPSI,D,E,E2,M,W, IND,BD,TYPE,IDEF,IERR)

INTEGER I,J,K,M,N,II,JJ,KI,!DEF,IERR,JDEF REAL D (N), E (N), E2 (N), W(N), BD (N) REAL F,P,Q,R,S,EP,QP,ERR,TOT,EPSI,DELTA,MACHEP REAL ABS,AM!NI INTEGER IND(N) LOGICAL TYPE


MACHEP = ?

IERR = 0

JDEF = IDEF ********** COPY D ARRAY INTO W ********** DO 20 I = I, N

2O W(I) = D(I)

IF (TYPE) GO TO 40 J = ! GO TO 400

40 ERR = 0.0 s = o.o

********** LOOK FOR SMALL SUB-DIAGONAL ENTRIES AND DEFINE INITIAL SHIFT FROM LOWER GERSCHGORIN BOUND. COPY E2 ARRAY INTO BD **********

TOT = W(1) Q = 0.0 J = 0

DO i00 1 = I, N

P = Q IF (I .EQ. i) GO TO 60 IF (P °gr. MACHEP * (ABS(D(1)) + ABS(D(I-I)))) GO TO 80

60 E2(1) = 0.0 80 BD(1) = E2(1)

• ********* COUNT ALSO IF ELEMENT OF E2 HAS UNDERFLOWED **********

IF (E2(1) .EQ. 0.0) J = J + I lED(l) = J Q= 0,0 IF (I .RE. N) Q = ABS(E(I+I)) TOT = AMINI (W(1)-P-Q,TOT)

I00 CONTINUE

IF (JDEF .EQ° I .AND. TOT .LT. 0.0) GO TO 140

DO Ii0 1 = I, N

II0 W(1) = W(1) - TOT

GO TO 160 140 TOT = 0.0

422

7.1-228

160 DO 360 K = i, M

********** NEXT QR TRANSFORMATION **********

180 TOT = TOT + S

DELTA = W(N) - S

I = N

F = ABS(MACHEP*TOT)

IF (EPSI .LT. F) EPSI = F

IF (DELTA .GT. EPSI) GO TO 190

IF (DELTA .LT. (-EPSI)) GO TO i000

GO TO 300

*~******** REPLACE SMALL SUB-DIAGONAL SQUARES BY ZERO

TO REDUCE THE INCIDENCE OF UNDERFLOWS *********e

190 IF (K .EQ. N) GO TO 210

K1 = K + 1

DO 200 J = KI, N

IF (BD(J) .LE. (MACHEP*(W(J)+W(J-I))) ** 2) BD(J) = 0.0

200 CONTINUE

210 F = BD(N) / DELTA

QP = DELTA + F

P = 1.0

IF (K .EQ. N) GO TO 260

K1 = N - K

~********~ FOR I=N-I STEP -I UNTIL K DO -- **********

DO 240 II = i, KI

I = N - II

Q = W(!) - S - F

R = Q / QP

P = P * R + 1.0

EP = F * R

W(I+I) = QP + EP

DELTA = Q - EP

IF (DELTA .GT. EPSI) GO TO 220

IF (DELTA .LT. (-EPSI)) GO TO i000

GO TO 300

220 F = BD(1) / Q

QP = DELTA + F

BD(I+I) = QP * EP

240 CONTINUE

260 W(K) = QP

S = QP / P

IF (TOT + S .GT. TOT) GO TO 180

**~******* SET ERROR -- IRREGULAR END OF ITERATION.

DEFLATE MINIMUM DIAGONAL ELEMENT ********** IERR = 5 * N + K

S=0.0

DELTA = QP

423

7.1-229

DO 280 J = K, N

IF (W(J) ~GT. DELTA) GO TO 280

I = J

DELTA = W(J)

280 CONTINUE

********** CONVERGENCE **********

300 IF (I .LT. N) BD(I+I) = BD(1) * F / QP

II = IND(1)

IF (I oEQ. K) GO TO 340

KI = I - K

**~******* FOR J=I-i STEP -i UNTIL K DO -- **********

DO 320 JJ = I, K1

J = I - JJ

W(J+I) = W(J) - S

BD(J+I) = BD(J)

IND(J+I) = IND(J)

320 CONTINUE

340 W(K) = TOT

ERR = ERR + ABS(DELTA)

BD(K) = ERR

IND(K) = II

360 CONTINUE

IF (TYPE) GO TO I001

F = BD(1)

E2(1) = 2.0

BD(1) = F

J = 2

********** NEGATE ELEMENTS OF W FOR LARGEST VALUES **********

400 DO 500 1 = i, N

5O0 W(1) : -W(1)

JDEF = -JDEF

GO TO (40,1001), J

********** SET ERROR -- IDEF SPECIFIED INCORRECTLY ***~******

i000 IERR = 6 * N + 1

i001 RETURN

END

424

7.1-230

NATS PROJECT


F303 RG

A Fortran IV Driver Subroutine to Determine the Eigenvalues and Eigenvectors of a Real General Matrix.

July, 1975

I. PURPOSE.

The Fortran IV subroutine RG calls the recommended sequence of subroutines from the eigensystem subroutine package EISPACK to determine the eigenvalues and eigenvectors (if desired) of a real general matrix.

2. USAGE.



SUBROUTINE RG(NM,N,A,WR,W!,MATZ,Z,IVI,FVI,IERR)



N is an integer input variable set equal to the order of the matrix A. N must not be greater than NM.

A is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. On input, A contains the real general matrix of order N whose eigenvalues and eigenvectors are to be found. On output, A has been destroyed.

425

7.1-231

WR,WI

MATZ

IVl

FVI

IERR

are working precision real output one- dimensional variables of dimension at least N containing the real and imaginary parts, respectively, of the eigenvalues of the real general matrix. The eigenvalues are unordered except that complex conjugate pairs of eigenvalues appear consecutively with the eigenvalue having the positive imaginary part first.

is an integer input variable set equal to zero if only eigenvalues are desired; otherwise it is set to any non-zero integer for both eigenvalues and eigenvectors.

is, if MATZ is non-zero, a working precision real output two-dimensional variable with row dimension NM and column dimension at least N containing the real and imaginary parts of the eigenveetors. If the J-th eigenvalue is real, the J-th column of Z contains its eigenvector. If the J-th eigenvalue is complex with positive imaginary part, the J-th and (J+l)-th columns of Z contain the real and imaginary parts of its eigenvector. The conjugate of this vector is the eigenvector for the conjugate eigenvalue. The eigenvectors are not normalized. If MATZ is zero, Z is not referenced and can be a dummy variable.

is an integer temporary one-dimensional variable of dimension at least N.

is a working precision temporary one- dimensional variable of dimension at least N.


426

7.1-232


If N is greater than NM, the subroutine terminates with IERR set equal to IO*N.

If more than 30 iterations are required to determine an eigenvalue, the subroutine terminates with IERR set equal to the index of the eigenvalue for which the failure occurs. The eigenvalues in the WR and WI arrays should be correct for indices IERR+I,IERR+2,...,N, but no eigenvectors are computed.



This subroutine can be used to find all the eigenvalues and all the eigenvectors (if desired) of a real general matrix.


This subroutine calls the recommended sequence of subroutines from EISPACK to find the eigenvalues and eigenvectors of a real general matrix.

To find eigenvalues only, the sequence is the following. BALANC - to balance a real general matrix. ELMHES - to reduce the balanced matrix to an upper

Hessenberg matrix using elementary transformations.

HQR - to determine the eigenvalues of the original matrix from the Hessenberg matrix.


BALANC - to balance a real general matrix. ELMHES - to reduce the balanced matrix to an upper

Hessenberg matrix using elementary transformations.

ELTRAN - to accumulate the transformations from the Hessenberg reduction.

HQR2 - to determine the eigenvalues and eigenvectors of the balanced matrix from the Hessenberg matrix.

BALBAK - to backtransform the eigenvectors to those of the original matrix.

427

7. 1-233

4. REFERENCES~

I) Garbow, B.S. and Dongarra, J.J., April, 1974.

EISPACK Path Chart,

5. CHECKOUT~

A. Test Cases~


B. Accuracy.

The accuracy of RG can be best described in terms of its role in those paths of EISPACK (I) which find eigenvalues and eigenvectors of real general matrices. In these paths, this subroutine is, in practice, numerically stable. This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original matrix.

428

7.1-234

SUBROUTINE RG(NM,N,A,WR,WI,MATZ,Z,IVI,FVI,IERR)

INTEGER N,NM,ISI,IS2,1ERR,MATZ REAL A(NM,N),WR(N),WI(N),Z(NM,N),FVI(N) INTEGER IVI(N)

IF (N .LE. NM) IERR = I0 * N GO TO 50

GO TO I0

i0 CALL BALANC(NM,N,A, ISI,IS2,FVI) CALL ELMHES(NM,N,ISI,IS2,A, IVI) IF (MATZ .RE. 0) GO TO 20 ********** FIND EIGENVALUES ONLY ********** CALL HQR(NM,N, ISI,IS2,A,WR,WI,IERR) GO TO 50 ********** FIND BOTH EIGENVALUES AND EIGENVECTORS

20 CALL ELTRAN(NM,N,ISI,IS2,A,IVI,Z) CALL HQR2(NM,N,ISI,IS2,A,WR,WI,Z,IERR) IF (IERR .NE. 0) GO TO 50 CALL BALBAK(NM,N,ISI,IS2,FVI,N,Z)

50 RETURN END

429

7.1-235

NATS PROJECT


F304 RS

A Fortran IV Driver Subroutine to Determine the Eigenvalues and Eigenvectors of a Real Symmetric Matrix.

July, 1975

i. PURPOSE.

The Fortran IV subroutine RS calls the recommended sequence of subroutines from the eigensystem subroutine package EISPACK to determine the eigenvalues and eigenvectors (if desired) of a real symmetric matrix.

2. USAGE.



SUBROUTINE RS(NM,N,A,W,MATZ,Z,FVI,FV2,1ERR)



N is an integer input variable set equal to the order of the matrix A. N must not be greater than NM.

A is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. On input, A contains the real symmetric matrix of order N whose eigenvalues and eigenvectors are to be found. Only the full lower triangle of A need be supplied. On output, the full upper triangle of A is unaltered.

430

7.1-236

W is a working precision real output one- dimensional variable of dimension at least N containing the eigenvalues of the real symmetric matrix in ascending order.


is, if MATZ is non-zero, a working precision real output two-dimensional variable with row dimension NM and column dimension at least N containing the eigenvectors. The eigenvectors are orthonormal. If MATZ is zero, Z is not referenced and can be a dummy variable.





If more than 30 iterations are required to determine an eigenvalue, the subroutine terminates with IERR set equal to the index of the eigenvalue for which the failure occurs. The eigenvalues and eigenvectors in the W and Z arrays should be correct for indices 1,2,...,IERR-I.



This subroutine can be used to find all the eigenvalues and all the eigenvectors (if desired) of a real symmetric matrix.

4,31

7.1-237


This subroutine calls the recommended sequence of subroutines from EISPACK to find the eigenvalues and eigenvectors of a real symmetric matrix.

To find eigenvalues only, the sequence is the following. TREDI - to reduce a real symmetric matrix to a

symmetric tridiagonal matrix using orthogonal transformations.

TQLRAT - to determine the eigenvalues of the original matrix from the symmetric tridiagonal matrix.


TRED2 - to reduce a real symmetric matrix to a symmetric tridiagonal matrix using and accumulating orthogonal transformations.

TQL2 - to determine the eigenvalues and eigenvectors of the original matrix from the symmetric tridiagonal matrix.

4, REFERENCES.

i) Garbow, B.S. and Dongarra~ J.J., April, 1974.

EISPACK Path Chart,

5. CHECKOUT.

A. Test Cases.

See the section discussing testing of the codes for real symmetric matrices.

B. Accuracy°

The accuracy of RS can best be described in terms of its role in those paths of EISPACK (i) which find eigenvalues and eigenvectors of real symmetric matrices. In these paths, this subroutine is numerically stable. This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.

432

7.1-238

SUBROUTINE RS(NM,N,A,W,MATZ,Z,FVI,FV2,1ERR)

INTEGER N,NM,IERR,MATZ REAL A(NM,N),W(N),Z(NM,N),FVI(N),FV2(N)

IF (N .LE. NM) IERR = i0 * N GO TO 50

GO TO I0

I0 IF (MATZ .NE. 0) GO TO 20 ********** FIND EIGENVALUES ONLY ********** CALL TREDI(NM~N,A,W,FVI,FV2) CALL TQLRAT(N~W,FV2,1ERR) GO TO 50 ********** FIND BOTH EIGENVALUES AND EIGENVECTORS

20 CALL TRED2(NM,N,A,W,FVI,Z) CALL TQL2(NM,N,W, FVI,Z,IERR)

50 RETURN END

433

7.1-239

NATS PROJECT


F307 RSP

A Fortran IV Driver Subroutine to Determine the Eigenvalues and Eigenvectors of a Real Symmetric Packed Matrix.

July, 1975

I. PURPOSE.

The Fortran IV subroutine RSP calls the recommended sequence of subroutines from the eigensystem subroutine package EISPACK to determine the eigenvalues and eigenvectors (if desired) of a real symmetric packed matrix.

2. USAGE.



SUBROUTINE RSP(NM,N,NV,A,W,MATZ,Z,FVI,FV2,IERR)


NM

N

NV

is an integer input variable set equal to the row dimension of the two-dimensional array Z as specified in the DIMENSION statement for Z in the calling program.

is an integer input variable set equal to the order of the matrix A. N must not be greater than NM.

is an integer input variable set equal to the dimension of the array A as specified in the DIMENSION statement for A in the calling program. NV must not be less than N*(N+I)/2.

434

7.1-240

A is a working precision real one-dimensional variable of dimension at least NV. On input, A contains the lower triangle, stored row-wise, of the real symmetric packed matrix of order N whose eigenvalues and eigenvectors are to be found. For example if N=3, A should contain

(A(I,I),A(2,1),A(2,2),A(3,1),A(3,2),A(3,3))

where the subscripts for each element refer to the row and column of the element in the standard two-dimensional representation. On output, A has been destroyed.

W is a working precision real output one- dimensional variable of dimension at least N containing the eigenvalues of the real symmetric packed matrix in ascending order.







If NV is less than N*(N+I)/2, the subroutine terminates with IERR set equal to 20*N.

435

7.1-241

If more than 30 iterations are required to determine an eigenvalue, the subroutine terminates with IERR set equal to the index of the eigenvalue for which the failure occurs. The eigenvalues and eigenvectors in the W and Z arrays should be correct for indices 1,2,...,IERR-Io



This subroutine can be used to find all the eigenvalues and all the eigenvectors (if desired) of a real symmetric packed matrix.


This subroutine calls the recommended sequence of subroutines from EISPACK to find the eigenvalues and eigenvectors of a real symmetric packed matrix.

To find eigenva!ues only, the sequence is the following. TRED3 - to reduce a real symmetric packed matrix to a

symmetric tridiagonal matrix using orthogonal transformations.

TQLRAT - to determine the eigenvalues of the original matrix from the symmetric tridiagonal matrix.

To find eigenva!ues and eigenvectors, the sequence is the following.

TRED3 - to reduce a real symmetric packed matrix to a symmetric tridiagonal matrix using orthogonal transformations.

TQL2 - to determine the eigenvalues and eigenvectors of the symmetric tridiagonal matrix.

TRBAK3 - to backtransform the eigenvectors to those of the original matrix.

4. REFERENCES.

I) Garbow~ B.S. and Dongarra, J.J., April, 1974.

EISPACK Path Chart,

5. CHECKOUT.

A. Test Cases.

See the section discussing testing of the codes for real symmetric packed matrices.

436

7.1-242

B. Accuracy.

The accuracy of RSP can best be described in terms of its role in those paths of EISPACK (i) which find eigenvalues and eigenvectors of real symmetric packed matrices. In these paths, this subroutine is numerically stable. This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.

437

7.1-243

SUBROUTINE RSP(NM,N,NV,A,W,MATZ,Z,FVI,FV2~IERR)

INTEGER !,J~N,NM,NV,IERR,MATZ REAL A(NV),W(N),Z(NM,N),FVI(N),FV2(N)

IF (N .LE. NM) GO TO 5 !ERR = i0 * N GO TO 50

5 IF (NV .GE. (N * (N + i)) / 2) GO TO i0 IERR = 20 * N GO TO 50

I0 CALL TRED3(N,NV,A,W, FVI,FV2) IF (MATZ .NE. O) GO TO 20 ********** FIND EIGENVALUES ONLY ********** CALL TQLRAT(N,W,FV2,1ERR) GO TO 50 ********** FIND BOTH EIGENVALUES AND EIGENVECTORS **********

20 DO 40 I = i, N

30

DO 30 J = i, N Z(J,I) = 0.0

CONTINUE

Z(I,I) = 1.0 40 CONTINUE

CALL TQL2(NM,N,W, FVI,Z,IERR) IF (IERR .NE. 0) GO TO 50 CALL TRBAK3(NM,N,NV,A,N,Z)

50 RETURN END

438

7.1-244

NATS PROJECT


F305 RST

A Fortran IV Driver Subroutine to Determine the Eigenvalues and Eigenvectors of a Real Symmetric Tridiagonal Matrix.

July, 1975

I. PURPOSE.

The Fortran IV subroutine RST calls the recommended sequence of subroutines from the eigensystem subroutine package EISPACK to determine the eigenvalues and eigenvectors (if desired) of a real symmetric tridiagonal matrix.

2. USAGE.



SUBROUTINE RST(NM,N,W,E,MATZ,Z,IERR)



N is an integer input variable set equal to the order of the matrix. N must not be greater than NM.

W is a working precision real one-dimensional variable of dimension at least N. On input, it contains the diagonal elements of the real symmetric tridiagonal matrix. On output, it contains the eigenvalues of the matrix in ascending order.

439

7.1-245

MATZ

!ERR

is a working precision real one-dimensional variable of dimension at least N. On input~ it contains the subdiagonal elements of the matrix in its last N-I positions. E(1) is arbitrary. On output, E has been destroyed.





If N is greater than NM, the subroutine terminates with IERR set equal to IO*N.

If more than 30 iterations are required to determine an eigenvalue, the subroutine terminates with !ERR set equal to the index of the eigenvalue for which the failure occurs. The eigenvalues and eigenvectors in the W and Z arrays should be correct for indices 1,2,o~.,IERR-I.

If all the eigenvalues are determined within 30 iterations~ IERR is set to zero.

C, Applicability and Restrictions°

This subroutine can be used to find all the eigenvalues and all the eigenvectors (if desired) of a real symmetric tridiagonal matrix.

440

7.1-246


This subroutine calls the recommended sequence of subroutines from EISPACK to find the eigenvalues and eigenvectors of a real symmetric tridiagona! matrix.

To find eigenvalues only, the sequence is the following. IMTQLI - to determine the eigenvalues of a real

symmetric tridiagonal matrix.


IMTQL2 - to determine the eigenvalues and eigenvectors of a real symmetric tridiagonal matrix.

4. REFERENCES.

i) Garbow, B.S. and Dongarra, J°J., April, 1974.

EISPACK Path Chart,

5. CHECKOUT.

A. Test Cases.

See the section discussing testing of the codes for real symmetric tridiagonal matrices.

B. Accuracy.

The subroutine RST is numerically stable; 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 and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.

441

7.1-247

SUBROUTINE RST(NM,N,W,E,MATZ,Z,IERR)

INTEGER I,J,N,NM, IERR,MATZ REAL W(N),E(N),Z(NM,N)

IF (N .LE. NM) GO TO i0 IERR = i0 * N GO TO 50

i0 IF (MATZ .NE. 0) GO TO 20 ********** FIND EIGENVALUES ONLY ********** CALL IMTQLI(N~W,E,IERR) GO TO 50 ********** FIND BOTH EIGENVALUES AND EIGENVECTORS **********

20 DO 40 I = I, N

30

DO 30 J = i, N z(J,I) = 0o0

CONTINUE

z(~,i) = i.o

40 CONTINUE

CALL IMTQL2(NM,N,W,E,Z,IERR)

50 RETURN END

442

7.1-248

NATS PROJECT


F306 RT

A Fortran IV Driver Subroutine to Determine the Eigenvalues and Eigenvectors of a Certain Real Tridiagonal Matrix.

July, 1975

i. PURPOSE.

The Fortran IV subroutine RT calls the recommended sequence of subroutines from the eigensystem subroutine package EISPACK to determine the eigenvalues and eigenvectors (if desired) of a certain real tridiagonal matrix. The property of the matrix required for use of this subroutine is that the products of pairs of corresponding off-diagonal elements be all non-negative, and further if eigenvectors are desired, no product be zero unless both factors are zero.

2. USAGE.



SUBROUTINE RT(NM~N~A,W,MATZ,Z~FVI,IERR)



is an integer input variable set equal to the order of the matrix A. N must not be greater than NM.

443

7.1-249

MATZ

FVI

!ERR

is a working precision real input two- dimensional variable with row dimension NM and column dimension at least 3 containing the real tridiagonal matrix of order N whose eigenvalues and eigenvectors are to be found. Its subdiagonal elements are stored in the last N-I positions of the first column, its diagonal elements are stored in the second column, and its superdiagonal elements are stored in the first N-I positions of the third column. Elements A(I,I) and A(N,3) are arbitrary.

is a working precision real output one- dimensional variable of dimension at least N containing the eigenvalues of the real tridiagonal matrix in ascending order.


is, if MATZ is non-zero, a working precision real output two-dimensional variable with row dimension NM and column dimension at least N containing the eigenvectors. The eigenvectors are not normalized. If MATZ is zero, Z is not referenced and can be a dummy variable.

is a working precision temporary one- dimensional variable of dimension at least N.




If the product of A(I,I) and the subroutine terminates with and no results computed.

A(I-I,3) is negative, IERR set equal to N+I

If the product is zero with one factor non-zero, and MATZ is non-zero, the subroutine terminates with IERR set equal to 2*N+I and no results computed.

444

7.1-250

If more than 30 iterations are required to determine an eigenvalue, the subroutine terminates with IERR set equal to the index of the eigenvalue for which the failure occurs. The eigenvalues and eigenvectors in the W and Z arrays should be correct for indices 1,2,...,IERR-I.



This subroutine can be used to find all the eigenvalues and all the eigenvectors (if desired) of a certain real tridiagonal matrix.


This subroutine calls the recommended sequence of subroutines from EISPACK to find the eigenvalues and eigenvectors of a certain real tridiagonal matrix.

To find eigenvalues only, the sequence is the following. FIGI - to transform a certain real tridiagonal matrix

into a symmetric tridiagonal matrix. IMTQLI - to determine the eigenvalues of the original

matrix from the symmetric tridiagonal matrix.


FIGI2 - to transform a certain real tridiagonal matrix into a symmetric tridiagonal matrix, accumulating the transformations.

IMTQL2 - to determine the eigenvalues and eigenvectors of the original matrix from the symmetric tridiagonal matrix.

4. REFERENCES.


EISPACK Path Chart,

5. CHECKOUT.

A. Test Cases.


B. Accuracy.

445

7,1-251

The accuracy of RT can best be described in terms of its role in those paths of EISPACK (i) which find eigenvalues and eigenvectors of certain real non- symmetric tridiagonal matrices. In these paths, this subroutine is numerically stable. This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.

446

7.1-252

SUBROUTINE RT(NM,N,A,W,MATZ,Z,FVl,IERR)

INTEGER N,NM,IERR,MATZ REAL A(NM,3),W(N),Z(NM,N),FVI(N)

IF (N .LE. NM) GO TO I0 IERR = i0 * N GO TO 50

I0 IF (MATZ .NE. 0) GO TO 20 ********** FIND EIGENVALUES ONLY ********** CALL FIGI(NM,N,A,W,FVI,FVI,IERR) IF (IERR .GT. 0) GO TO 50 CALL IMTQLI(N,W,FVI,IERR) GO TO 50 ********** FIND BOTH EIGENVALUES AND EIGENVECTORS **********

20 CALL FIGI2(NM,N,A,W, FVI,Z,IERR) IF (IERR .NE. O) GO TO 50 CALL IMTQL2(NM,N,W,FVI,Z,IERR)

50 RETURN END

447

7. 1-253

NATS PROJECT


F223-2 TINVIT

A Fortran IV Subroutine to Determine Some Eigenvectors of a Symmetric Tridiagonal Matrix.

May, 1972 July, 1975

io PURPOSE°

The Fortran IV subroutine TINVIT determines those eigenvectors of a symmetric tridiagonal matrix corresponding to a set of ordered approximate eigenvalues~ using inverse

iteration.

2. USAGE.



SUBROUTINE TINVIT(NM,N,D,E,E2,M,W, IND,Z, IERR,RVI,RV2,RV3,RV4,RV6)


NM

N

D

is an integer input variable set equal to the row dimension of the two-dimensional array Z as specified in the DIMENSION statement for Z in the calling program.



448

7.1-254

E2

M

W

IND


is a working precision real input one- dimensional variable of dimension at least N containing, in its last N-I positions, the squares of the corresponding elements of E with zeros corresponding to negligible elements of E, (The successive submatrices are located from the zeros of E2.) If MACHEP denotes the relative machine precision, then E(I) is considered negligible if it is not larger than the product of MACHEP and the sum of the magnitudes of D(I) and D(I-I). E2(1) should contain 0.0 if the eigenvalues are in ascending order and 2.0 if the eigenvalues are in descending order. If subroutine BISECT (F294) or TRIDIB (F237) has been used to determine the eigenvalues, their output E2 array is suitable for input to TINVIT.

is an integer input variable set equal to the number of specified eigenvalues for which the corresponding eigenvectors are to be determined.

is a working precision real input one- dimensional variable of dimension at least M containing the M specified eigenvalues of the symmetric tridiagonal matrix. The eigenvalues must be in either ascending or descending order in W. The ordering is required to insure the determination of independent orthogonal eigenvectors associated with close eigenvalues.

is an integer input one-dimensional variable of dimension at least M containing the submatrix indices associated with the corresponding M eigenvalues in W. Eigenvalues belonging to the first submatrix have index i, those belonging to the second submatrix have index 2, etc. If BISECT or TRIDIB has been used to determine the eigenvalues, their output IND array is suitable for input to TINVIT.

449

7.1-255

is a working precision real output two- dimensional variable with row dimension NM and column dimension at least M. It contains M orthonormal eigenvectors of the symmetric tridiagonal matrix corresponding to the M eigenvalues in W.

!ERR is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.

RVI,RV2,RV3

are working precision real temporary one- dimensional variables of dimension at least N used to store the main diagonal and the two adjacent diagonals of the triangular matrix produced in the inverse iteration process.

RV4,RV6 are working precision real temporary one- dimensional variables of dimension at least N. RV4 holds the multipliers of the Gaussian elimination step in the inverse iteration process. RV6 holds the approximate eigenvectors in this process.


If more than 5 iterations are required to determine an eigenvector, TINVIT terminates the computation for that eigenvector and sets IERR to -R where R is the index of the eigenvector. If this failure occurs for more than one eigenvector, the last occurrence is recorded in IERR. The columns of Z corresponding to failures of the above sort are set to zero vectors.

If all the eigenvectors are determined within 5 iterations, IERR is set to zero.


To determine some of the eigenva!ues and eigenvectors of a full symmetric matrix, TINVIT should be preceded by TREDI (F277) to provide a suitable symmetric tridiagonal matrix for BISECT (F294), TRIDIB (F237), or !MTQLV (F234) which can then be used to determine the eigenvalues. It should be followed by TRBAKI (F279) to back transform the eigenvectors from TINVIT into those of the original matrix.

450

7.1-256

To determine some of the eigenvalues and eigenvectors of a complex Hermitian matrix, TINVlT should be preceded by HTRIDI (F284) to provide a suitable real symmetric tridiagonal matrix for BISECT (F294), TRIDIB (F237), or IMTQLV (F234). It should then be followed by HTRIBK (F285) to back transform the eigenvectors from TINVIT into those of the original matrix.

Some of the eigenvalues and eigenvectors of certain non- symmetric tridiagonal matrices can be computed using the combination of FIGI (F280), BISECT (F294) or TRIDIB (F237), TINVlT, and BAKVEC (F281). See F280 for the description of this special class of matrices. For these matrices, TINVIT should be preceded by FIGI to provide a suitable symmetric matrix for BISECT or TRIDIB. It should then be followed by BAKVEC to back transform the eigenvectors from TINVIT into those of the original matrix.

The computation of the eigenvectors by inverse iteration requires that the precision of the eigenvalues be commensurate with small relative perturbations of the order of MACHEP in the matrix elements. For most symmetric tridiagonal matrices, it is enough that the absolute error in the eigenvalues for which eigenvectors are desired be approximately MACHEP times a norm of the matrix. But some matrices require a smaller absolute error, perhaps as small as MACHEP times the eigenvalue of smallest magnitude.


The calculations proceed as follows. First, the E2 array is inspected for the presence of a zero element defining a submatrix. The eigenvalues belonging to this submatrix are identified by their common submatrix index in IND.

The eigenvectors of the submatrix are then computed by inverse iteration. First, the LU decomposition of the submatrix with an approximate eigenvalue subtracted from its diagonal elements is achieved by Gaussian elimination using partial pivoting. The multipliers defining the lower triangular matrix L are stored in the temporary array RV4 and the upper triangular matrix U is stored in the three temporary arrays RVI, RV2, and RV3. Saving these quantities in RVl, RV2, RV3, and RV4 avoids repeating the LU decomposition if further iterations are required. An approximate vector, stored in RV6, is computed starting from an initial vector, and the norm of the approximate vector is compared with a norm of the submatrix to determine whether the growth is sufficient to accept it as an eigenvector. If this vector is accepted, its Euclidean norm

451

7.1-257

is made I, If the growth is not sufficient, this vector is used as the initial vector in computing thenext approximate vector, This iteration process is repeated at most 5 times.

Eigenvectors computed in the above way corresponding to well- separated eigenvalues of this submatrix will be orthogonal. However, eigenvectors corresponding to close eigenvalues of this submatrix may not be satisfactorily orthogonal. Hence, to insure orthogonal eigenvectors~ each approximate vector is made orthogonal to those previously computed eigenvectors whose eigenvalues are close to the current eigenvalue. If the orthogonalization process produces a zero vector, a column of the identity matrix is used as an initial vector for the next iteration.

Identical eigenvalues are perturbed slightly in an attempt to obtain independent eigenvectors. These perturbations are not recorded in the eigenvalue array W.

The above steps are repeated on each submatrix until all the eigenvectors are computed.

This subroutine is a subset (except for the resolution of non-convergent eigenvectors) of the Fortran subroutine TSTUKM (F293), which is a translation of the Algol procedure TR!STURM written and discussed in detail by Peters and Wilkinson (I)°

4. REFERENCES.

i) Peters, Go and Wilkinson, J.H., The Calculation of Specified Eigenvectors by Inverse Iteration, Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/18, 418-439, Springer-Verlag, 1971.

5. CHECKOUT.

A. Test Cases°


452

7.1-258

B. Accuracy.

The accuracy of TINVIT can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real symmetric matrices and matrix systems. In these paths, this subroutine is numerically stable (i). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix or system close to the original matrix or system and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix or system.

453

7.1-259

C

C

C C

C C

C

C

C C C C

SUBROUTINE TINVIT(NM,N,D,E,E2,M,W,IND,Z, X IERR,RVI,RV2,RV3,RV4,RV6)

INTEGER I,J,M,N,P,Q,R~S,II,IP,JJ,NM,ITS,TAG, IERR,GROUP

REAL D(N),E(N),E2(N),W(M),Z(NM,M),

X RVI(N),RV2(N),RVB(N),RV4(N),RV6(N) REAL U,V,UK,XU,XO,XI,EPS2,EPS3,EPS4,NORM,ORDER,MACHEP

REAL SQRT,ABS,FLOAT INTEGER IND(M)



MACHEP = ?

IERR = 0 IF (M .EQ. 0) GO TO I001

TAG = 0 ORDER = 1.0 - E2(1)

Q = 0 ********** ESTABLISH AND PROCESS NEXT SUBMATRIX **********

I00 P = Q + I

DO 120 Q = P, N IF (Q .EQ. N) GO TO 140 IF (E2(Q+I) .EQ. 0.0) GO TO 140

120 CONTINUE ********** FIND VECTORS BY INVERSE ITERATION ~*********

140 TAG = TAG + 1

S = 0

490

DO 920 R = i, M IF (!ND(R) .NEo TAG) GO TO 920

ITS = 1

Xl = W(R) IF (S .ME. 0) GO TO 510

********** CHECK FOR ISOLATED ROOT **********

XU = 1.0 IF (P .ME. Q) GO TO 490

RV6(P) = 1.0 GO TO 870 NORM = ABS(D(P)) IP = P + i

500 DO 500 I = IP, Q NORM = NORM + ABS(D(1)) + ABS(E(1))

********** EPS2 IS THE CRITERION FOR GROUPING, EPS3 REPLACES ZERO PIVOTS AND EQUAL

ROOTS ARE MODIFIED BY EPS3, EPS4 IS TAKEN VERY SMALL TO AVOID OVERFLOW **********

EPS2 = 1.0E-3 * NORM EPS3 = MACHEP * NORM UK = FLOAT(Q-P+I)

454

7.1-260

C

C

EPS4 = UK * EPS3

UK = EPS4 / SQRT(UK)

S = P

505 GROUP = 0 GO TO 520

• ********* LOOK FOR CLOSE OR COINCIDENT ROOTS ********** 510 IF (ABS(XI-X0) .GE. EPS2) GO TO 505

GROUP = GROUP + I

IF (ORDER * (XI - X0) .LE. 0.0) XI = X0 + ORDER * EPS3

• ********* ELIMINATION WITH INTERCHANGES AND INITIALIZATION OF VECTOR **********

520 V = 0.0

540

560

580

600

620

DO 580 1 = P, Q

RV6 (I) = UK IF (I .EQ. P) GO TO 560

IF (ABS(E(1)) .LT. ABS(U)) GO TO 540 ********** WARNING -- A DIVIDE CHECK MAY OCCUR HERE IF

E2 ARRAY HAS NOT BEEN SPECIFIED CORRECTLY ********** XU = U / E(1)

RV4(I) = XU RVt(I-l) = E(I)

RV2(I-I) = D(1) - El

RV3(I-I) = 0.0

IF (I .NE. Q) RV3(I-I) = E(I+I) U = V - XU * RV2(I-I) V = -XU * RV3(I-I)

GO TO 580 xu = E(I) / U RV4(1) = XU RVI(I-I) = u

RV2(I-I) = V RV3(I-I) = 0.0 U = D(I) - X1 - XU * V

IF (I .NE. Q) V = E(I+I) CONTINUE

IF (U .EQ. 0.0) U = EPS3 RVI(Q) = u

RV2(Q) = 0.0

RV3(Q) = 0.0

********** BACK SUBSTITUTION FOR I=Q STEP -I UNTIL P DO -- **********

DO 620 II = P, Q

I = P + Q - II

RV6(I) = (RV6(I) - U * RV2(I) - V * RV3(I)) / RVI(I) V = U U = RV6 (I)

CONTINUE

********** ORTHOGONALIZE WITH RESPECT TO PREVIOUS MEMBERS OF GROUP **********

IF (GROUP .EQ. O) GO TO 700 J = R

455

7.1-261

C

C

C

C C

C

630

640

660

680

700

720

740

DO 680 JJ = I, GROUP

J = J - 1

IF (IND(J) oNE. TAG) GO TO 630

XU = 0.0

DO 640 1 = P, Q

xu = xu + RV6(!) * Z(I,J)

DO 660 I = P, Q RV6(1) = RV6(1) - XU * Z(I,J)

CONTINUE

NORM = 0.0

DO 720 I = P, Q

NORM = NORM + ABS(RV6(I))

IF (NORM .GE. !.0) GO TO 840 ******~*** FORWARD SUBSTITUTION **********

IF (ITS .EQ. 5) GO TO 830 IF (NORM .NE. 0.0) GO TO 740

RV6(S) = EPS4 S = S + I IF (S .GT. Q) S = P

GO TO 780 XU = EPS4 / NORM

DO 760 1 = P, Q

760 RV6(I) = RV6(I) * XU • ********* ELIMINATION OPERATIONS ON NEXT VECTOR

ITERATE **********

780 DO 820 I = IP, Q

U = RV6 (I) • ********* IF RVI(I-I) .EQ. E(1), A ROW INTERCHANGE

WAS PERFORMED EARLIER IN THE TRIANGULARIZATION PROCESS **********

IF (RVI(I-I) .NE. E(I)) GO TO 800

u = ~v6(i-1)

RV6(I-I) = RV6(I)

800 RV6(1) = U - RV4(1) * RV6(I-I) 820 CONTINUE

ITS = ITS + ! GO TO 600

C ********** SET ERROR -- NON-CONVERGED EIGENVECTOR **********

830 IERR = -R XU = 0.0 GO TO 870

C ********** NORMALIZE SO THAT SUM OF SQUARES IS C 1 AND EXPAND TO FULL ORDER **********

840 U = 0.0

456

7 .1 -262

DO 860 I = P, Q 860 u = u + RV6(1)**2

C

XU = 1.0 / SQRT(U) C

870 DO 880 I = i, N 880 Z(I,R) = 0.0

C DO 900 I = P, Q

900 Z(I,R) = RV6(I) * XU C

X0 = X1 920 CONTINUE

C

IF (Q .LT. N) GO TO I00 I001 RETURN

END

457

7.!-263

NATS PROJECT


F235 TQLRAT


July, 1975

I. PURPOSE.

The Fortran IV subroutine TQLRAT determines the eigenvalues of a symmetric tridiagonal matrix using a rational variant of the QL method.

2. USAGE.

A. Calling Sequences


SUBROUTINE TQLRAT(N,D,E2,1ERR)


N is an integer input variable set equal to the order of the matrix.


E2 is a working precision real one-dimensional variable of dimension at least N. On input, the last N-I positions in this array contain the squares of the subdiagonal elements of the symmetric tridiagonal matrix. E2(1) is arbitrary. Note that TQLRAT destroys E2.

458

7.1-264



If more than 30 iterations are required to determine an eigenvalue, TQLRAT terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues in the D array should be correct for indices 1,2,...,IERR-I. These eigenvalues are ordered but are not necessarily the smallest IERR-I eigenvalues.

If all the eigenva!ues are determined within 30 iterations, IERR is set to zero.


To determine the eigenvalues of a full symmetric matrix, TQLRAT should be preceded by TREDI (F277) to provide a suitable symmetric tridiagonal matrix for TQLRAT.

To determine the eigenvalues of a complex Hermitian matrix, TQLRAT should be preceded by HTRIDI (F284) to provide a suitable real symmetric tridiagonal matrix for TQLRAT.

TQLRAT does not perform well on matrices whose successive row sums vary widely in magnitude and are not strictly increasing from the first to the last row. The subroutine IMTQLI (F291) is not sensitive to such row sums and is therefore recommended for symmetric tridiagonal matrices whose structure is not known.


The eigenvalues are determined by a rational variant of the QL method. The essence of this method is a process whereby a sequence of symmetric tridiagonal matrices, unitarily similar to the original symmetric tridiagonal matrix, is formed which converges to a diagonal matrix. The rate of convergence of this sequence is improved by shifting the origin at each iteration. Before the iterations for each eigenvalue, the symmetric tridiagonal matrix is checked for a possible splitting into submatrices. If a splitting occurs, only the uppermost submatrix participates in the next iteration. The eigenvalues are ordered in ascending order as they are found.

459

7.1-265

The origin shift at each iteration is the eigenvalue of the current uppermost 2x2 principal minor closer to the first diagonal element of this minor. Whenever the uppermost Ixl principal submatrix finally splits from the rest of the matrix, its element is taken to be an eigenvalue of the original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of order i. The tolerances in the splitting tests are proportional to the relative machine precision.

This subroutine is a translation of the Algol procedure TQLRAT written and discussed in detail by Reinsch (I). It is a rational variant of the subroutine TQLI which is a translation of the Algol procedure TQLI written and discussed in detail by Bowdler, Martin, Reinsch, and Wilkinson (2).

4. REFERENCES.

1) Reinsch, C.H.~ A Stable Rational QR Algorithm for the Computation of the Eigenvalues of an Hermitian, Tridiagonal Matrix, Math. Comp. 25,591-597 (1971). (Algorithm 464, Comm, ACM 16,689 (1973).)

2) Bowdler, Ho, Martin, R.S.~ Reinsch, C., and Wilkinson, J.H., The QR and QL Algorithms for Symmetric Matrices, Num. Math. 11,293-306 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - Co Reinsch, Contribution 11/3, 227-240, Springer-Verlag, 1971.)

5. CHECKOUT.

A, Test Cases.


Bo Accuracy,

The subroutine TQLRAT is numerically 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.

460

7.1-266

SUBROUTINE TQLRAT(N,D,E2,1ERR)

INTEGER I,J,L,M,N,II,LI,MML,IERR

REAL D(N),E2(N) REAL B,C,F,G,H,P,R,S,MACHEP

REAL SQRT,ABS,SIGN



**********

MACHEP = ?

IERR = 0 IF (N .EQ. i) GO TO I001

DO i00 1 = 2, N i00 E2(I-I) = E2(1)

F = 0.0

B = 0.0 E2 (N) = 0.0

105

i i 0

DO 290 L = I, N J = 0 H = MACHEP * (ABS(D(L)) + SQRT(E2(L)))

IF (B .GT. H) GO TO 105 B = H

C = B * B

• ********* LOOK FOR SMALL SQUARED SUB-DIAGONAL ELEMENT ********** DO II0 M = L, N

IF (E2(M) .LE. C) GO TO 120 • ********* E2(N) IS ALWAYS ZERO, SO THERE IS NO EXIT

THROUGH THE BOTTOM OF THE LOOP ********** CONTINUE

120

130 IF (M .EQo L) GO TO 210 IF (J .EQ. 30) GO TO i000 J = J + I

********** FORM SHIFT ********** LI = L + I S = SQRT(E2(L))

G = D(L)

P = (D(LI) - G) / (2.0 * S) R = SQRT(P*P+I.0)

D(L) = S / (e + SIGN(R,P))

H = G - D(L)

140 DO 140 1 = LI, N D(I) = D(I) - H

F = F + H

461

7.1-267

200

********** RATIONAL QL TRANSFORMATION **********

G = D (M)

IF (G ,EQ, 0.0) G = B

H = G

S = 0 , 0

M M L = M - L

********** FOR !=M-I STEP -I UNTIL L DO -- **********

DO 200 II = I, MML

I = M - II

P = G * H

R = P + E2(1)

E2(I+I) = S * R

S = E2(1) / R

o(I+i) = H + s * (~ + D(I))

G = D(1) - E2(1) / g

IF (G .EQ. 0.0) G = B

H = G * P / R

CONTINUE

E2(L) = S * G

D(L) = H

C ********** GUARD AGAINST UNDERFLOW IN CONVERGENCE TEST **********

IF (H .EQ. 0.0) GO TO 210

IF (ABS(E2(L)) .LE. ABS(C/H)) GO TO 210

E2(L) = H * E2(L)

IF (E2(L) .NE. 0.0) GO TO 130

210 P = D(L) + F

C ********** ORDER EIGENVALUES **********

IF (L ,EQ. i) GO TO 250

C ********** FOR I=L STEP -i UNTIL 2 DO -- **********

DO 230 II = 2, L

I = L + 2 - II

IF (P .GE. D(I-I)) GO TO 270

D(!) = D (I-I)

230 CONTINUE

250 I = 1

270 D(1) = P

290 CONTINUE

GO TO I001 ********** SET ERROR -- NO CONVERGENCE TO AN

EIGENVALUE AFTER 30 ITERATIONS **********

I000 IERR = L

i001 RETURN

END

462

7.1-268

NATS PROJECT


F289-2 TQLI


May, 1972 July, 1975

i. PURPOSE.

The Fortran IV subroutine TQLI determines the eigenvalues of a symmetric tridiagonal matrix using the QL method.

2. USAGE.



SUBROUTINE TQLI(N,D,E,IERR)



is a working precision real one-dimensional variable of dimension at least N. On input, it contains the diagonal elements of the symmetric tridiagonal matrix. On output, it contains the eigenva!ues of this matrix in ascending order.

is a working precision real one-dimensional variable of dimension at least N. On input, the last N-I positions in this array contain the subdiagonal elements of the symmetric tridiagona! matrix. E(1) is arbitrary. Note that TQLI destroys E.

463

7.1-269



If more than 30 iterations are required to determine an eigenvalue, TQLI terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues in the D array should be correct for indices 1,2,o..,IERR-I. These eigenvalues are ordered but are not necessarily the smallest IERR-I eigenvalues.



To determine the eigenvalues of a full symmetric matrix, TQLI should be preceded by TREDI (F277) to provide a suitable symmetric tridiagonal matrix for TQLI.

To determine the eigenvalues of a complex Hermitian matrix, TQLI should be preceded by HTRIDI (F284) to provide a suitable real symmetric tridiagonal matrix for TQLI.

TQLI does not perform well on matrices whose successive row sums vary widely in magnitude and are not strictly increasing from the first to the last row. The subroutine IMTQL! (F291) is not sensitive to such row sums and is therefore recommended for symmetric tridiagonal matrices whose structure is not known.


The eigenvalues are determined by the QL method. The essence of this method is a process whereby a sequence of symmetric tridiagonal matrices, unitarily similar to the original symmetric tridiagonal matrix, is formed which converges to a diagonal matrix. The rate of convergence of this sequence is improved by shifting the origin at each iteration° Before the iterations for each eigenvalue, the symmetric tridiagonal matrix is checked for a possible splitting into submatrices. If a splitting occurs, only the uppermost submatrix participates in the next iteration. The eigenvalues are ordered in ascending order as they are found.

464

7.1-270

The origin shift at each iteration is the eigenvaiue of the current uppermost 2x2 principal minor closer to the first diagonal element of this minor. Whenever the uppermost ixl principal submatrix finally splits from the rest of the matrix, its element is taken to be an eigenvalue of the original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of order I. The tolerances in the splitting tests are proportional to the relative machine precision.

This subroutine is a translation of the Algol procedure TQLI written and discussed in detail by Bowdler, Martin, Reinsch, and Wilkinson (I).

4. REFERENCES.

i) Bowdler, H., Martin, R.S., Reinsch, C., and Wilkinson, J.H., The QR and QL Algorithms for Symmetric Matrices, Num. Math. 11,293-306 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/3, 227-240, Springer-Verlag, 1971.)

5. CHECKOUT.

A. Test Cases.


B. Accuracy.

The subroutine TQLI is numerically stable (i); 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.

465

7.1-271

C

SUBROUTINE TQLI(N,D,E,IERR)

INTEGER !,J,L,M,N,II,LI,MML,IERR

REAL D(N),E(N) REAL B,C,F,G,H,P,R,S,MACHEP

REAL SQRT,ABS,SIGN



**********

MACHEP = ?

IERR = 0


DO i00 I = 2, N

100 E(I-I) = E(1)

F = 0.0

B = 0.0 E(N) = 0.0

ii0

DO 290 L = i, N

J=0 H = MACHEP * (ABS(D(L)) + ABS(E(L))) IF (B .er. H) B = H

• ********* LOOK FOR SMALL SUB-DIAGONAL ELEMENT **********

DO Ii0 M = L, N IF (ABS(E(M)) .LE. B) GO TO 120

• ********* E(N) IS ALWAYS ZERO, SO THERE IS NO EXIT

THROUGH THE BOTTOM OF THE LOOP **********

CONTINUE

120 130

IF (M °EQ. L) GO TO 210

IF (J ,EQ. 30) GO TO I000

J = J + 1 ********** FORM SHIFT **********

L1 = L + 1 G = D (L) e = (D(LI) - G) / (2.0 * E(L))

R = SQRT(P*P+I.0) D(L) = E(L) / (e + SIGN(R,P))

H = G - D(L)

140

DO 140 I = LI, N

D(1) = D(i) - H

F = F + H

********** QL TRANSFORMATION **********

P = D (M)

C = i°0 S = 0 . 0

MML = M - L

466

7.1-272

150

160

200

********** FOR I--M-I STEP -I UNTIL L DO -- **********

DO 200 II = i, MML

I = M- II

G = C * E(I)

H = C * P

IF (ABS(P) .LT. ABS(E(1))) GO TO 150

C = E(1) / P

R = SQRT(C*C+I.0)

E(I+I) = S * P * R

S=C/R C = 1.0 / R

GO TO 160

C = P / E(1)

R = SQRT(C*C+I.0)

E(I+I) = S * E(1) * R

S = 1,0 1 R

C = C * S

P = C * D(1) - S * G

D(I+I) = II + S * (C * g + S * D(1))

CONTINUE

E(L) = S * P

D(L) = C * P

IF (ABS(E(L)) .GT. B) GO TO 130

210 P = D(L) + F

• ********* ORDER EIGENVALUES **********

IF (L .EQ. I) GO TO 250

• ********* FOR I=L STEP -i UNTIL 2 DO -- **********

DO 230 II = 2, L

I = L + 2 - II

IF (P oGE. D(I-I)) GO TO 270

D(1) = D(I-I)

230 CONTINUE

250 I = 1

270 D(I) = P

290 CONTINUE

GO TO I001

********** SET ERROR -- NO CONVERGENCE TO AN

EIGENVALUE AFTER 30 ITERATIONS ********** i000 IERR = L

i001 RETURN

END

467

7.1-273

NATS PROJECT


F290-2 TQL2

A Fortran IV Subroutine to Determine the Eigenvalues and Eigenvectors of a Symmetric Tridiagonal Matrix.

May, 1972 July, 1975

1, PURPOSE.

The Fortran IV subroutine TQL2 determines the eigenvalues and eigenvectors of a symmetric tridiagonal matrix. TQL2 uses the QL method to compute the eigenvalues and accumulates the QL transformations to compute the eigenvectors. The eigenvectors of a full symmetric matrix can also be computed directly by TQL2, if TRED2 (F278) has been used to reduce this matrix to tridiagonal form.

2. USAGE.

A. Calling Sequence~


SUBROUTINE TQL2(NM,N,D,E,Z,IERR)





468

7. 1-274

IERR

is a working precision real one-dimensional variable of dimension at least N. On input, the last N-I positions in this array contain the subdiagonal elements of the symmetric tridiagonal matrix. E(1) is arbitrary. Note that TQL2 destroys E.

is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. If the eigenvectors of the symmetric tridiagonal matrix are desired, then on input, Z contains the identity matrix of order N, and on output, contains the orthonormal eigenvectors of this tridiagonal matrix. If the eigenvectors of a full symmetric matrix are desired, then on input, Z contains the transformation matrix produced in TRED2 which reduced the full matrix to tridiagonal form, and on output, contains the orthonormal eigenveetors of this full symmetric matrix.



If more than 30 iterations are required to determine an eigenvalue, TQL2 terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues and eigenvectors in the D and Z arrays should be correct for indices 1,2,...,IERR-I, but the eigenvalues are unordered.



To determine the eigenvalues and eigenvectors of a full symmetric matrix, TQL2 should be preceded by TRED2 (F278) to provide a suitable symmetric tridiagonal matrix for TQL2.

469

7ol-275

To determine the eigenvalues and eigenvectors of a complex Hermitian matrix, TQL2 should be preceded by HTRIDI (F284) to provide a suitable real symmetric tridiagonal matrix for TQL2, and the input array Z to TQL2 should be initialized to the identity matrix. TQL2 should then be followed by HTRIBK (F285) to back transform the eigenvectors from TQL2 into those of the original matrix.

TQL2 does not perform well on matrices whose successive row sums vary widely in magnitude and are not strictly increasing from the first to the last row. The subroutine IMTQL2 (F292) is not sensitive to such row sums and is therefore recommended for symmetric tridiagonal matrices whose structure is not known.


The eigenvalues are determined by the QL method. The essence of this method is a process whereby a sequence of symmetric tridiagonal matrices, unitarily similar to the original symmetric tridiagona! matrix, is formed which converges to a diagonal matrix. The rate of convergence of this sequence is improved by shifting the origin at each iteration. Before the iterations for each eigenvalue, the symmetric tridiagonal matrix is checked for a possible splitting into submatrices. If a splitting occurs, only the uppermost submatrix participates in the next iteration. The similarity transformations used in each iteration are accumulated in the Z array, producing the orthonormal eigenvectors for the original matrix. Finally, the eigenvalues are ordered in ascending order and the eigenvectors are ordered consistently.

The origin shift at each iteration is the eigenvalue of the current uppermost 2x2 principal minor closer to the first diagonal element of this minor. Whenever the uppermost Ixl principal submatrix finally splits from the rest of the matrix, its element is taken to be an eigenvalue of the original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of order I. The tolerances in the splitting tests are proportional to the relative machine precision.

This subroutine is a translation of the Algol procedure TQL2 written and discussed in detail by Bowdler, Martin, Reinsch, and Wilkinson (I).

470

7.1-276

4. REFERENCES.

i) Bowdler, H., Martin, R.S., Reinsch, C., and Wilkinson, J.H., The QR and QL Algorithms for Symmetric Matrices, Num. Math. 11,293-306 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution II/3, 227-240, Springer-Verlag, 1971.)

5. CHECKOUT.

A. Test Cases.


B. Accuracy.

The subroutine TQL2 is numerically stable (i); 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 and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.

471

7.1-277

C

C

C

SUBROUTINE TQL2(NM,N,D,E,Z,IERR)

INTEGER I,J,K,L,M,N, II,LI,NM,MML,IERR

REAL D(N),E(N),Z(NM,N)

REAL B,C,F,G,H,P,R,S,MACHEP REAL SQRT,ABS,SIGN



**********

MACHEP = ?

IERR = 0

IF (N .EQ. I) GO TO i001

DO I00 1 = 2, N 100 E(I-t) = E(I)

F = 0.0 B = 0.0

E(N) = 0.0

ii0

DO 240 L = I, N

J = 0

H = MACHEP * (ABS(D(L)) + ABS(E(L))) IF (B .LT. H) B = H

• ********* LOOK FOR SMALL SUB-DIAGONAL ELEMENT **********

DO Ii0 M = L, N

IF (ABS(E(M)) .LE. B) GO TO 120 • ********* E(N) IS ALWAYS ZERO, SO THERE IS NO EXIT

THROUGH THE BOTTOM OF THE LOOP **********

CONTINUE

120 130

IF (M .EQ. L) GO TO 220

IF (J .EQ. 30) GO TO i000

J = J + i ********** FORM SHIFT **********

L1 = L + i G = D (L) P = (D(LI) -G) / (2.0 * E(L))

R = SQRT(P*P+I.0) D(L) = E(L) / (P + SIGN(R,P))

H = G - D(L)

140 DO 140 I = LI, N O(1) = D(1) - H

F = F + H ********** QL TRANSFORMATION **********

P = D (M)

C : 1.0 S = 0 . 0

MML = M - L

472

O3

I'o

O0

0 ff'~

t~

t~

~ ~.

.~

0 0

.-~

.-

"~

~.'~

~ ~

II o

tl I!

~ II

H

•

II

II -

w

I-4

~--.

~'

0 0 0

OX

0

0

0 0

0 II

II II

0

II 11

0

~ M

H

~;I

tZl

c~

t:~

~..~

~ I

II

2 ""

O

~ f'

~ c3

.~

I..o

o 00

o

o o

o

~,'

0

~ H

,-',

~'

J ,"

,, •

--- -

0

0"~

C~

0 .,-

-.

I~

L'~

"..-

/ h~

i >d

-I

- "-

-"

;'l-J

• H C

~

I--I

C~

0 r,~

0 0 0 LO

O

0 0

x-.

0 0

x..

~.~

x..H

~ ~

~::;q

II

o~i

",..~

~

- 0

~'-~

[;~

n

l:~

. ~

, ii

v~

<:~

i---i

~'~

~ I

L'q

~-

I ~-"

It It

II t-

-I

II II

il I|

H II

II

r.~

c~

,.-.~

0~

~s

'~ "

.-~

~... ~

"~'o

~

o

" i-I

0 0 0

0 o II

I! II

o

c~

~ :~

I

II

H

X-,

0 tl ! I t~

0 I !

? ..j

00

7.1-279

C

300 CONTINUE

C

GO TO i001



i000 IERR = L

i001 RETURN

END

474

7. 1-280

NATS PROJECT


F279-2 TRBAKI

A Fortran IV Subroutine to Back Transform the Eigenvectors of that Symmetric Tridiagonal Matrix Determined by TREDI.

May, 1972 July, 1975

i. PURPOSE.

The Fortran IV subroutine TRBAKI forms the eigenvectors of a real symmetric matrix from the eigenvectors of that symmetric tridiagonal matrix determined by TREDI (F277).

2. USAGE.



SUBROUTINE TRBAKI(NM,N,A,E,M,Z)




is a working precision real input two- dimensional variable with row dimension NM and column dimension at least N. The strict lower triangle of A contains some information about the orthogonal transformations used in the reduction to the tridiagonal form. The remaining upper part of the matrix is arbitrary. See section 3 of F277 for the details.

475

7.1-281

is a working precision real input one- dimensional variable of dimension at least N containing, in its last N-I positions, the subdiagonal elements of the tridiagonal matrix. The element E(1) is arbitrary. These elements serve to provide the remaining information about the orthogonal transformations.


is a working precision real two-dimensional variable with row dimension NM and column dimension at least M. On input, the first M columns of Z contain the eigenvectors to be back transformed. On output, these columns of Z contain the transformed eigenvectors. The transformed eigenvectors are orthonormal if the input eigenvectors are orthonormal.


None~

C. Applicability and Restrictions~

This subroutine should be used in conjunction with the subroutine TREDI (F277).


Suppose that the symmetric matrix C to the tridiagonal symmetric matrix transformation


T F = Q CQ

where Q is a product of the orthogonal symmetric matrices encoded in E and in the strict lower triangle of A. Then, given an array Z of column vectors, TRBAKI computes the matrix product QZ. If the eigenvectors of F are columns of the array Z, then TRBAKI forms the eigenvectors of C in their place. Since Q is orthogonal, vector Euclidean norms are preserved.

476

7.1-282

This subroutine is a translation of the Algol procedure TRBAKI written and discussed in detail by Martin, Reinsch, and Wilkinson (I).

4. REFERENCES.

l) Martin, R.S., Reinsch, C., and Wilkinson, J.H., Householder's Tridiagonalization of a Symmetric Matrix, Num. Math. 11,181-195 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution II/2, 212-226, Springer-Verlag, 1971.)

5. CHECKOUT.

A. Test Cases.


B. Accuracy.

The accuracy of TRBAKI can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real symmetric matrices and matrix systems. In these paths, this subroutine is numerically stable (I). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix or system close to the original matrix or system and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix or system.

477

7.1-283

SUBROUTINE TRBAKI(NM,N,A,E,M,Z)

INTEGER I,J,K,L,M,N,NM REAL A(NM,N), E (N), Z (NM,M) REAL S

IF (M .EQ. 0) GO TO 200 IF (N .EQ. i) GO TO 200

DO 140 I = 2~ N L = I - 1 IF (E(I) .EQ. 0.0) GO TO 140

DO 130 J = I, M S=Oo0

Ii0 DO Ii0 K = i, L

s = s + A(I~K) * Z(K,J) • ********* DIVISOR BELOW IS NEGATIVE OF H FORMED IN TREDI.

DOUBLE DIVISION AVOIDS POSSIBLE UNDERFLOW **********

S = (S / A ( i , L ) ) / E ( I )

120 DO 120 K = i, L Z(K,J) = Z(K,J) + S * A(I,K)

130 CONTINUE

140 CONTINUE

200 RETURN

END

478

7.1-284

NATS PROJECT


F229 TRBAK3

A Fortran IV Subroutine to Back Transform the Eigenvectors of that Symmetric Tridiagonal Matrix Determined by TRED3.

July, 1975

i. PURPOSE.

The Fortran IV subroutine TRBAK3 forms the eigenvectors of a real symmetric matrix from the eigenvectors of that symmetric tridiagonal matrix determined by TRED3 (F228).

2. USAGE.



SUBROUTINE TRBAK3(NM,N,NV,A,M,Z)




NV is an integer input variable set equal to the dimension of the array A as specified in the DIMENSION statement for A in the calling program. NV must be not less than N* (N+I) 12.

A is a working precision real input one- dimensional variable of dimension at least N*(N+I)/2 containing information about the orthogonal transformations used in the reduction to the tridiagonal form. See section 3 of F228 for the details.

479

7.1-285

M is an integer input variable set equal to the number of columns of Z to be back transformed.

is a working precision real two-dimensional variable with row dimension NM and column dimension at least M. On input, the first M columns of Z contain the eigenvectors to be back transformed. On output, these columns of Z contain the transformed eigenvectors. The transformed eigenvectors are orthonormal if the input eigenvectors are orthonormal.


None.


This subroutine should be used in conjunction with the subroutine TRED3 (F228).

3~ DISCUSSION OF METHOD AND ALGORITHM.

Suppose that the symmetric matrix C to the tridiagonal symmetric matrix transformation


T F = Q CQ

where Q is a product of the orthogonal symmetric matrices encoded in A. Then, given an array Z of column vectors, TRBAK3 computes the matrix product Qz. If the eigenvectors of F are columns of the array Z, then TRBAK3 forms the eigenvectors of C in their place. Since Q is orthogonal, vector Euclidean norms are preserved.

This subroutine is a translation of the Algol procedure TRBAK3 written and discussed in detail by Martin, Reinsch, and Wilkinson (I).

480

7.1-286

4. REFERENCES.

1) Martin, R.S., Reinsch, C., and Wilkinson, J.H., Householder's Tridiagonalization of a Symmetric Matrix, Num. Math. 11,181-195 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/2, 212-226, Springer-Verlag, 1971.)

5. CHECKOUT.

A. Test Cases.


B. Accuracy.

The accuracy of TRBAK3 can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real symmetric packed matrices. In these paths, this subroutine is numerically stable (i). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.

481

41

O0

I'O

0 0 0 0

0 0

bo

0 C

) 0

0

.,-~

~:~

~ 0

II ! N..

H

C~

II

~a

C~

0

~'- C')

~'0

~

.~

tJ

0 t~

0~

0 t~

D~

0

C~

0

0 ~

II 0

I---I ~

II

C~

~"~°

~I

II

t,~

C~

H

H

II 11

0

U II

" °

Hk

.~

b~

0 0

0 0

O0

O0

O

0

~t

n

v~

H

ba

Z

C3

c~

t~

0 t"z~

t~

N

'7

7.1-288

NATS' PROJECT


F277-2 TREDI

A Fortran IV Subroutine to Reduce a Real Symmetric Matrix to a Symmetric Tridiagonal Matrix Using

Orthogonal Transformations.

May, 1972 July, 1975

i. PURPOSE.

The Fortran IV subroutine TREDI reduces a real symmetric matrix to a symmetric tridiagonal matrix using orthogonal similarity transformations. This reduced form is used by other subroutines to find the eigenvalues and/or eigenvectors of the original matrix. See section 2C for the specific routines.

2. USAGE.



SUBROUTINE TREDI(NM,N,A,D,E,E2)




A is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. On input, A contains the symmetric matrix of order N to be reduced to tridiagonal form. Only the full lower triangle of the matrix need be

483

7. 1 -289

E2

supplied. On output, the strict lower triangle of A contains information about the orthogona! transformations used in the reduction. The full upper triangle of A is unaltered. See section 3 for the details.

is a working precision real output one- dimensional variable of dimension at least N containing the diagonal elements of the tridiagonal matrix.



Bo Error Conditions and Returns.

None.




If some of the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by TSTURM (F293), or by BISECT (F294) and TINVIT (F223), or by TRIDIB (F237) and TINVIT, or by IMTQLV (F234) and TINVIT, and then by TRBAKI (F279).

484

7.1-290

If all the eigenvalues and eigenvectors of the original matrix are desired, subroutine TRED2 (F278) should be used rather than TREDI to perform the tridiagonal reduction, and should be followed by TQL2 (F290) or IMTQL2 (F292).

If the matrix has elements of widely varying magnitudes, the smaller ones should be in the top left-hand corner.


The tridiagonal reduction is performed in the following way. Starting with J=N, the elements in the J-th row to the left of the diagonal are first scaled, to avoid possible underflow in the transformation that might result in severe departure from orthogonality. The sum of squares SIGMA of these scaled elements is next formed. Then, a vector U and a scalar

T H -- U U/2

define an operator

T P = I - UU /H

which is orthogonal and symmetric and for which the similarity transformation PAP eliminates the elements in the J-th row of A to the left of the subdiagonal and the symmetrical elements in the J-th column.

The non-zero components of U are the elements of the J-th row to the left of the diagonal with the last of them augmented by the square root of SIGMA prefixed by the sign of ~ the subdiagonal element. By storing the transformed subdiagonal element in E(J) and not overwriting the row elements eliminated in the transformation, full information about P is saved for later u~e in YRBAKI.

The transformation sets E2(J) equal to SIGMA and E(J) equal to the square root of SIGMA prefixed by sign opposite to that of the replaced subdiagonal element.

The above steps are repeated on further rows of the transformed A in reverse order until A is reduced to tridiagonal form; that is, repeated for J = N-I,N-2,...,3.

Only the elements in the lower triangle of A are accessed, and although the diagonal elements are modified in the algorithm, they are restored to their original contents by the end of the subroutine, thus preserving the full upper triangle of A.

4 8 5

7.1-291

This subroutine is a translation of the Algol procedure TREDI written and discussed in detail by Martin~ Reinsch, and Wilkinson (I).

4. REFERENCES°

I) Martin, R~S°~ Reinsch, C.~ and Wilkinson~ J.H., Householder's Tridiagonalization of a Symmetric Matrix, Num. Math. 11,181-195 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, Jo H. Wilkinson - C. Reinsch, Contribution II/2, 212-226, Springer-Verlag~ 1971.)

5. CHECKOUT.

A. Test Cases.


B. Accu~acyo

The accuracy of TREDI can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real symmetric matrices and matrix systems. In these paths, this subroutine is numerically stable (I). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix or system close to the original matrix or system and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix or system.

486

7.1-292

SUBROUTINE TREDI(NM,N,A,D,E,E2)

INTEGER I,J,K,L,N,II,NM,JPI

REAL A(NM,N),D(N),E(N),E2(N)

REAL F,G,H,SCALE

REAL SQRT,ABS,SIGN

DO i00 1 = i, N

I00 D(I) = A(I,I)

C ********** FOR I=N STEP -i UNTIL 1 DO -- ********** DO 300 II = i, N

I = N + 1 - II

L = I - i

H=0.0

SCALE = 0.0

IF (L .LT. i) GO TO 130

C ********** SCALE ROW (ALGOL TOL THEN NOT NEEDED) ********** DO 120 K = i, L

120 SCALE = SCALE + ABS(A(I,K))

130 IF (SCALE .NE. 0.0) GO TO 140 E(I) -- 0.0

E2(1) = 0.0

GO TO 290

140

150

DO 150 K = i, L

A(!,K) = A(I,K) / SCALE

H = H + A(I,K) * A(I,K) CONTINUE

E2(I) = SCALE * SCALE * H

F = A(I,L)

G = -SIGN(SQRT(H),F)

E(1) = SCALE * G

H = H - F * G

A(I,L) = F - G

IF (n .EQ. I) GO TO 270

F = 0.0

180

DO 240 J = i, L

G = 0.0

********** FORM ELEMENT OF A*U **********

DO 180 K = I, J

C = C + A(J,K) * A(I,K)

JPI = J + i

IF (L .LT. JPI) GO TO 220

DO 200 K = JPI, L

200 G = G + A(K,J) * A(I,K)

• ********* FORM ELEMENT OF P ********** 220 E(J) = G / H

F = F + E(J) * A(I,J) 240 CONTINUE

487

7.1-293

C

C

H = F / (~ + H)

********** FORM REDUCED A **********

DO 260 J = I, L

F = A(I,J)

G = E(J) - H * F

E(J) = G

260

DO 260 K = i, J

A(J,K) = A(J,K) - F * E(K) - G * A(I,K)

CONTINUE

270

280

DO 280 K = I, L

A(I,K) = SCALE * A(I,K)

290 H = D(i)

D(I) = A(I,I)

A(I,I) =

300 CONTINUE

RETURN

END

488

7.1-294

NATS PROJECT


F278-2 TRED2

A Fortran IV Subroutine to Reduce a Real Symmetric Matrix to a Symmetric Tridiagonal Matrix Accumulating the

Orthogonal Transformations.

May, 1972 July, 1975

i. PURPOSE.

The Fortran IV subroutine TRED2 reduces a real symmetric matrix to a symmetric tridiagonal matrix using and accumulating orthogonal similarity transformations. This reduced form and the transformation matrix are used by subroutine TQL2 (F290) or IMTQL2 (F292) to find the eigenvalues and eigenvectors of the original matrix.

2. USAGE.



SUBROUTINE TRED2(NM,N,A,D,E,Z)




489

7.1-295

is a working precision real input two- dimensional variable with row dimension NM and column dimension at least N. A contains the symmetric matrix of order N to be reduced to tridiagonal form. Only the full lower triangle of the matrix need be supplied.


is a working precision real output one- dimensional variable of dimension at least N containing~ in its last N-I positions, the subdiagonal elements of the tridiagonal matrix. The element E(1) is set to zero.

is a working precision real output two- dimensional variable with row dimension and column dimension at least N. It contains the orthogonal transformation matrix produced in the reduction to the tridiagonal form.

NM

Be Error Conditions and Returns°

None.


If all the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by TQL2 (F290) or IMTQL2 (F292).

If some other combination of eigenvalues and eigenvectors is desired, subroutine TREDI (F277) should be used rather than TRED2 to perform the tridiagonal reduction.

If the matrix has elements of widely varying magnitudes, the smaller ones should be in the top left-hand corner.

Parameters A and Z need not be distinct.

490

7.1-296


The lower triangle of A is initially copied into Z and all subsequent operations are performed on Z.


T H = U U/2

define an operator

T P = I - UU /H

which is orthogonal and symmetric and for which the ° °

slmllarmty transformation PAP eliminates the elements in the J-th row of A to the left of the subdiagonal and the symmetrical elements in the J-th column.

The non-zero components of U are the elements of the J-th row to the left of the diagonal with the last of them augmented by the square root of SIGMA prefixed by the sign of the subdiagonal element. By storing the transformed subdiagonal element in E(J) and not overwriting the row elements eliminated in the transformation, full information about P is saved for later accumulation of transformations.

The transformation sets E(J) equal to the square root of SIGMA prefixed by sign opposite to that of the replaced subdiagonal element.

The above steps are repeated on further rows of the transformed A in reverse order until A is reduced to tridiagonal form; that is, repeated for J = N-I,N-2,...,3.

Finally, the orthogonal transformation matrix is accumulated in Z as the product of the N-2 operators defined in the tridiagonal reduction.

This subroutine is a translation of the Algol procedure TRED2 written and discussed in detail by Martin, Reinsch, and Wilkinson (I).

491

7 . 1 - 2 9 7

4. REFERENCES.

1) Martin, R.S., Reinsch, C., and Wilkinson, J.H., Householder's Tridiagonalization of a Symmetric Matrix, Num. Math. 11,181-195 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/2, 212-226, Springer-Verlag, 1971.)

5~ CHECKOUT.

A. Test Cases~


B. Accuracy.

The accuracy of TRED2 can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real symmetric matrices and matrix systems. In these paths, this subroutine is numerically stable (i). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix or system close to the original matrix or system and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix or system.

492

7.1-298

C

SUBROUTINE TRED2(NM,N,A,D,E,Z)

INTEGER I,J,K,L,N, II,NM,JPI

REAL A(NM,N),D(N),E(N),Z(NM,N) REAL F,G,H,HH,SCALE REAL SQRT,ABS,SIGN

DO I00 1 = i, N

DO I00 J = I, I Z(l,J) = A(I,J)

i00 CONTINUE

120

IF (N .EQ. I) GO TO 320

********** FOR I=N STEP -i UNTIL 2 DO -- ********** DO 300 II = 2, N

I = N + 2 - II

L = I - 1 H = 0.0 SCALE = 0.0

IF (L ,LT. 2) GO TO 130

********** SCALE ROW (ALGOL TOL THEN NOT NEEDED) ********** DO 120 K = I, L

SCALE = SCALE + ABS(Z(I,K))

130 IF (SCALE .NE. 0.0) GO TO 140 E(1) = Z(l,L) GO TO 290

140

150

DO 150 K = i, L

Z(I,K) = Z(I,K) / SCALE H = H + Z(I,K) * Z(l,K)

CONTINUE

F = Z(I,L)

G = -SIGN(SQRT(H),F) E(1) = SCALE * G H = H - F * G Z(I,L) = F - G

F = 0.0

180

DO 240 J = I, L Z(J,Z) = Z(I,J) / i

G = 0.0 ********** FORM ELEMENT OF A*U **********

DO 180 K = i, J

G = G + Z(J,K) * Z(I,K)

JPI = J + 1

IF (L .LT. JPI) GO TO 220

200 DO 200 K = JPI, L

G = g + Z(K,J) * Z(I,K)

493

7.1-299

********** FORM ELEMENT OF P **********

220 E(J) = G / H

F = F + E(J) * Z(l,J)

240 CONTINUE

HH = F / (H + H) ********** FORM REDUCED A **********

DO 260 J = I, L

F = Z(I,J)

G = E(J) - HH * F

E(J) = G

260

DO 260 K = i, J

Z(J,K) = Z(J,K) - F * E(K) - G * Z(I,K)

CONTINUE

290 D(1) = H

300 CONTINUE

320 D(1) = 0.0

~(I) = o.o ********** ACCUMULATION OF TRANSFORMATION MATRICES **********

DO 500 I = I, N

L = I - i

IF (D(I) oEQ. 0.0) GO TO 380

DO 360 J = I, L

G=0~0

340

DO 340 K = i, L

G = G + Z(I,K) * Z(K,J)

360

DO 360 K = i, L

Z(K,J) = Z(K,J) - G * Z(K,I)

CONTINUE

380 D(I) = Z(I,I)

Z(I,i) = 1.0 IF (L .LT. I) GO TO 500

400

DO 400 J = I, L

Z(I,J) = 0.0 Z(J,I) = 0.0

CONTINUE

500 CONTINUE

RETURN

END

494

7.1-300

NATS PROJECT


F228 TRED3

A Fortran IV Subroutine to Reduce a Real Symmetric Matrix, Stored as a One-Dimensional Array, to a Symmetric

Tridiagonal Matrix Using Orthogonal Transformations.

July, 1975

i. PURPOSE.

The Fortran IV subroutine TRED3 reduces a real symmetric matrix, stored as a one-dimensional array, to a symmetric tridiagonal matrix using orthogonal similarity transformations. This reduced form is used by other subroutines to find the eigenvalues and/or eigenvectors of the original matrix. See section 2C for the specific routines.

2. USAGE.



SUBROUTINE TRED3(N,NV,A,D,E,E2)


N is an integer input variable set equal to the order of the matrix A.

NV is an integer input variable set equal to the dimension of the array A as specified in the DIMENSION statement for A in the calling program. NV must be not less than N* (N+I) 12.

A is a working precision real one-dimensional variable of dimension at least N*(N+I)/2. On input, A contains the lower triangle of the symmetric matrix of order N to be reduced to tridiagonal form, packed row- wise. For example if N=3, A should contain

495

7.1-301

E2

(A(i, I),A(2, i) ,A(2,2) ,A(3, I),A(3,2) ,A(3,3))

where the subscripts for each element refer to the row and column of the element in the standard two-dimensional representation. On output, A contains information about the orthogonal transformations used in the reduction. See section 3 for the details.





None°



If some of the eigenvalues of the original matrix are desired, this subroutine should be followed by BISECT (F294) or TR!DIB (F237).

If some of the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by TSTURM (F293), or by BISECT (F294) and TINVIT (F223), or by TRIDIB (F237) and TINVIT, or by IMTQLV (F234) and TINVIT, and then by TRBAK3 (F229).

496

7.1-302

If all the eigenvalues and eigenvectors of the original matrix are desired, subroutine TRED2 (F278) should be used rather than TRED3 to perform the tridiagonal reduction, and should be followed by TQL2 (F290) or IMTQL2 (F292). In this case, the packed form of the matrix cannot be used, but the eigenvectors can share the space required for the matrix.

If the matrix has elements of widely varying magnitudes, the smaller ones should be at the top.


Discussion of the algorithm is facilitated if the matrix is considered square. The implementation, however, achieves significant storage economy by specifying only the lower triangle to be stored and packed one-dimensionally.


T H = u u/2

define an operator

T P = I -UU /H

which is orthogonal and symmetric and for which the similarity transformation PAP eliminates the elements in the J-th row of A to the left of the subdiagonal and the symmetrical elements in the J-th column.

The non-zero components of U are the elements of the J-th row to the left of the diagonal with the last of them augmented by the square root of SIGMA prefixed by the sign of the subdiagonal element. By storing the transformed subdiagonal element in E(J) and not overwriting the row elements eliminated in the transformation, full information about P is saved for later use in TRBAK3.

The transformation sets E2(J) equal to SIGMA and E(J) equal to the square root of SIGMA prefixed by sign opposite to that of the replaced subdiagonal element.

497

7.1-303

The above steps are repeated on further rows of the transformed A in reverse order until A is reduced to tridiagonal form~ that is, repeated for J = N-I,N-2,...,3o

This s~broutine is a translation of the Algol procedure TRED3 written and discussed in detail by Martin, Reinsch, and Wilkinson (i).

4. REFERENCES°

i) Martin~ R~So, Reinsch, C.~ and Wilkinson, J.H., Householder's Tridiagonalization of a Symmetric Matrix, Num. Math. 11,181-195 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, Jo H~ Wilkinson - C. Reinsch, Contribution 11/2, 212-226, Springer-Verlag, 1971.)

5. CHECKOUT~

A. Test Cases~


B. Accuracy°

The accuracy of TRED3 can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real symmetric packed matrices. In these paths, this subroutine is numerically stable (I). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.

498

7.1-304

C

120

130

140

150

180

SUBROUTINE TRED3(N,NV,A,D,E,E2)

INTEGER I,J,K,L,N,II,IZ,JK,NV

REAL A(NV), D (N), E (N), E2 (N) REAL F,G,H,HH,SCALE

REAL SQRT,ABS,SIGN

********** FOR I=N STEP -I UNTIL 1 DO -- ********** DO 300 II = i, N

I = N + i - II L = I - 1 I Z = ( I * L ) / 2 H = 0.0 SCALE = 0.0

IF (L .LT. i) GO TO 130

********** SCALE ROW (ALGOL TOL THEN NOT NEEDED) ********** DO 120 K = I, L

IZ = IZ + 1 D(K) = A(IZ)

SCALE = SCALE + ABS(D(K)) CONTINUE

IF (SCALE .NE. 0.0) GO TO 140 E(I) = 0.0

E2(1) = 0.0 GO TO 290

DO 150 K = I, L

D(K) = D(K) / SCALE H = H + D(K) * D(K)

CONTINUE

E2(1) = SCALE * SCALE * H F = D (L) G = -SIGN (SQRT (H), F)

E(1) = SCALE * G H = H - F * G D(L) = F - g A(IZ) = SCALE * D(L)

IF (L .EQ. i) GO TO 290 F = 0.0

DO 240 J = i, L G = 0.0

JK = (J * (J-l)) / 2

• ********* FORM ELEMENT OF A*U ********** DO 180 K = i, L

JK = JK + 1

IF (K .GT. J) JK = JK + K - 2 G = G + A(JK) * D(K)

CONTINUE

499

7.1-305

240

********** FORM ELEMENT OF P **********

E(J) = G / H F = F + E(J) * D(J)

CONTINUE

HH = F / (H + H) JK = 0

********** FORM REDUCED A **********

DO 260 J = I, L

F = D(J)

G = E(J) - HH * F

E(J) = G

260

DO 260 K = i, J

JK = JK + 1

A(JK) = A(JK) - F * E(K) - G * D(K)

CONTINUE

290 D(1) = A(IZ+I)

A(IZ+!) = SCALE * SQRT(H)

300 CONTINUE

RETURN

END

500

7.1-306

NATS PROJECT


F237 TRIDIB

A Fortran IV Subroutine to Determine Some Eigenvalues of a Symmetric Tridiagonal Matrix.

July, 1975

i. PURPOSE.

The Fortran IV subroutine TRIDIB determines those eigenvalues of a symmetric tridiagonal matrix between specified boundary indices using Sturm sequencing.

2. USAGE.



SUBROUTINE TRIDIB(N,EPSI,D,E,E2,LB,UB, MII,M,W, IND,IERR,RV4,RV5)



EPSI is a working precision real variable. On input, it specifies an absolute error tolerance for the computed eigenvalues. If the input EPSI is non-positive, it is reset to a default value described in section 2C.

D is a working precision real input one- dimensional variable of dimension at least N containing the diagonal elements of the symmetric tridiagonal matrix.


501

7,1-307

E2 is a working precision real one-dimensional variable of dimension at least N. On input, the last N-I positions in this array contain the squares of the subdiagonal elements of the symmetric tridiagonal matrix. E2(1) is arbitrary. On output, E2(1) is set to zero. If any of the elements in E are regarded as negligible, the corresponding elements of E2 are set to zero, and so the matrix splits into a direct sum of submatriceso

LB,UB are working precision real output variables set to the lower and upper endpoints, respectively, of an interval containing exactly the desired eigenvalues. See section 2C for further details.

MII is an integer input variable specifying the lower index of the set of desired (smallest) eigenvalues.

M is an integer input variable specifying the number of eigenvalues desired. The upper index, M22, of the set is then obtained internally as M22=MII+M-I.

W is a working precision real output one- dimensional variable of dimension at least M containing the M eigenvalues of the symmetric tridiagonal matrix between boundary indices MII and M22. The eigenvalues are in ascending order in W.

IND is an integer output one-dimensional variable of dimension at least M containing the submatrix indices associated with the corresponding M eigenvalues in W. Eigenvalues belonging to the first submatrix have index i, those belonging to the second submatrix have index 2, etc.


RV4,RV5 are working precision real temporary one- dimensional variables of dimension at least N used to hold the lower and upper bounds for the eigenvalues in the bisection process.

502

7.1-308


If exactly multiple eigenvalues prevent the determination of an appropriate LB, TRIDIB terminates with no eigenvalues computed, and IERR is set to 3*N+I. In this case, the returned values of LB and UB define the Gerschgorin interval containing all the eigenvalues of the matrix.

If, after determining LB, exactly multiple eigenvalues prevent the determination of an appropriate UB, TRIDIB terminates with no eigenvalues computed, and IERR is set to 3"N+2. In this case, the returned value of UB is the upper bound for the Gerschgorin interval containing all the eigenvalues of the matrix.

If neither of the above error conditions occurs, IERR is set to zero.


To determine some of the eigenvalues of a full symmetric matrix, TRIDIB should be preceded by TREDI (F277) to provide a suitable symmetric tridiagonal matrix for TRIDIB.

To determine some of the eigenvalues of a complex Hermitian matrix, TRIDIB should be preceded by HTRIDI (F284) to provide a suitable real symmetric tridiagonal matrix for TRIDIBo

Some of the eigenvalues of certain non-symmetric tridiagonal matrices can be computed using the combination of FIGI (F280) and TRIDIB. See F280 for the description of this special class of matrices. For these matrices, TRIDIB should be preceded by FIGI to provide a suitable symmetric matrix for TRIDIB.

To determine eigenvectors associated with the computed eigenvalues, TRIDIB should be followed by TINVIT (F223) and the appropriate back transformation subroutine -- TRBAKI (F279) after TREDI, HTRIBK (F285) after HTRIDI, or BAKVEC (F281) after FIGI.

The subroutines TQLI (F289), IMTQLI (F291), and TQLRAT (F235) determine all the eigenvalues of a symmetric tridiagonal matrix faster than TRIDIB determines 25 percent of them. Hence~ if more than 25 percent of them are desired, it is recommended that TQLI, IMTQLI, or TQLRAT be used.

503

7 . 1 - 3 0 9

If it is preferred to specify the interval (LB,UB) be searched for eigenvalues rather than the boundary indices MII and M22, use subroutine BISECT (F294) instead.

to

The precision of the computed eigenvalues is controlled through the parameter EPSI. To obtain eigenvalues accurate to within a certain absolute error, EPSI should be set to that error. In particular, if MACHEP denotes the relative machine precision~ then to obtain the eigenvalues to an accuracy commensurate with small relative perturbations of the order of MACHEP in the matrix elements, it is enough for most tridiagonal matrices that EPSI be approximately MACHEP times a norm of the matrix. But some matrices require a smaller EPSI for this accuracy, perhaps as small as MACHEP times the eigenvalue of smallest magnitude in (LB,UB). Note, however, that if EPSI is smaller than required, TRIDIB will perform unnecessary bisection steps to determine the eigenvalues. For further discussion of EPSI, see reference (i).

If the input EPSI is non-positive, TRIDIB resets it, for each submatrix, to -MACHEP times the l-norm of the submatrix and uses its magnitude. This value is tentatively considered adequate for computing the eigenvalues to an accuracy commensurate with small relative perturbations of the order of MACHEP in the matrix elements.


The eigenva!ues are determined by the method of bisection applied to the Sturm sequence.

The calculations proceed as follows. First, the subdiagonal elements are tested for negligibility. If an element is considered negligible, its square is set to zero, and so the matrix splits into a direct sum of submatrices. At the same time, the Gerschgorin interval known to contain all the eigenvalues of the matrix is determined. Then, an interval (LB,UB) is determined, using a bisection process proceeding from the Gerschgorin bounds, that contains exactly eigenvalues MII through M22.

Next, a submatrix is examined for its eigenvalues in the interval (LB,UB). Its Gerschgorin interval is determined and used to refine the interval (LB,UB). If the input EPSI is non-positive, it is reset to the default value described in section 2C. Then, subintervals, each enclosing an eigenvalue in (LB,UB), are shrunk using a bisection process

504

7.1-310

until the endpoints of each subinterval are close enough to be accepted as an eigenvalue of the submatrix. Here the endpoints of each subinterval are close enough when they differ by less than MACHEP times twice the sum of the magnitudes of the endpoints plus the absolute error tolerance EPSI.

The submatrix eigenvalues are then merged with previously found eigenvalues into an ordered set.

The above steps are repeated on each submatrix until all the eigenvalues between boundary indices MII and M22 are computed.

This subroutine is a translation of the Algol procedure BISECT written and discussed in detail by Barth, Martin, and Wilkinson (I). A similar Algol procedure TRISTURM is discussed in detail by Peters and Wilkinson (2); a subset of it has been translated as subroutine BISECT (F294).

4. REFERENCES.

i) Barth, W., Martin, R.S., and Wilkinson, J.H., Calculation of the Eigenvalues of a Symmetric Tridiagonal Matrix by the Method of Bisection, Num. Math. 9,386-393 (1967). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/5, 249-256, Springer-Verlag, 1971.)


5. CHECKOUT.

A. Test Cases.


505

7.1-311

B. Accuracy~

The subroutine TRIDIB is numerically 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.

506

7.1-312

SUBROUTINE TRIDIB(N,EPSI,D,E,E2,LB,UB,MII,M,W,IND,IERR,RV4,RV5)

INTEGER I,J,K,L,M,N,P,Q,R,S,II,MI,M2,MII,M22,TAG,IERR,ISTURM

REAL D(N),E(N),E2(N),W(M),RV4(N),RV5 (N)

REAL U,V,LB,TI~T2,UB,XU,X0,XI,EPSI,MACHEP

REAL ABS,AMAXI,AMINI,FLOAT

INTEGER lED(M)



MACHEP = ?

IERR = 0

TAG = 0

XU = D(1)

X0 = D(i)

U = 0.0

********** LOOK FOR SMALL SUB-DIAGONAL ENTRIES AND DETERMINE AN

INTERVAL CONTAINING ALL THE EIGENVALUES ********** DO 40 I = I, N

XI = U

U = 0.0

IF (I .NE. N) U = ABS(E(I+I))

XU = AMINI(D(1)-(XI+U),XU)

X0 = AMAXI(D(1)+(XI+U),X0)

IF (I .EQ. I) GO TO 20

IF (ABS(E(1)) .GT. MACHEP * (ABS(D(1)) + ABS(D(I-I))))

X GO TO 40

20 E2(1) = 0.0

40 CONTINUE

XI = AMAXI(ABS(XU),ABS(X0)) * MACHEP * FLOAT(N)

XU = XU - XI

TI = XU

X0 = X0 + X1

T2 = X0

• ********* DETERMINE AN INTERVAL CONTAINING EXACTLY

THE DESIRED EIGENVALUES ********** P = i

Q = N

M1 = MII - i

IF (MI .EQ. 0) GO TO 75

ISTURM = i

50 V = XI

Xl = (XU + X0) * 0.5

IF (XI .EQ. V) GO TO 980

GO TO 320

60 IF (S - MI) 65, 73, 70

65 XU = XI

GO TO 50

70 X0 = X1

GO TO 50

507

7. 1-313

73 XU = X1

T1 = X1 75 M22 = M1 + M

IF (M22 .EQo N) GO TO 90

X0 = T2

ISTURM = 2 GO TO 50

80 IF (S - M22) 65, 85, 70

85 T2 = XI

90 Q = 0 R = 0 ********** ESTABLISH AND PROCESS NEXT SUBMATRIX, REFINING

INTERVAL BY THE GERSCHGORIN BOUNDS **********

i00 IF (R .EQ, M) GO TO i001 TAG = TAG + i

P = Q + i xu = D(P)

XO = D(P)

U = 0o0

DO 120 Q = P, N

X1 = U U = 0.0

V = 0.0 IF (Q .EQ. N) GO TO ii0

U = ABS(E(Q+I)) V = E2(Q+I)

Ii0 XU = AMINI (D (Q) - (Xl+U), xu) x0 = AMAXI(D(Q)+(XI+U),X0) IF (V .EQo 0,0) GO TO 140

120 CONTINUE

140 XI = AMAXI(ABS(XU),ABS(X0)) * MACHEP

IF (EPSI ,LE. 0.0) EPSI = -XI

IF (P .NE. Q) GO TO iS0 • ********* CHECK FOR ISOLATED ROOT WITHIN INTERVAL **********

IF (TI ,GT. D(P) .OR. D(P) .GE. T2) GO TO 940

MI = P M2 = P

RV5 (e) = D(P) GO TO 900

180 XI = XI * FLOAT(Q-P+I)

LB = AMAXI (TI ,XU-XI) UB = AMINI(T2,X0+XI) XI = LB ISTURM = 3 GO TO 320

200 MI = S + 1 X1 = UB I STURM = 4 GO TO 320

220 M2 = S IF (MI .GT. M2) GO TO 940

508

7.1-314

C

C C

C

C

C

********** FIND ROOTS BY BISECTION **********

X0 = UB

ISTURM = 5

DO 240 I = MI, M2 RV5(1) = UB

RV4(1) = LB

240 CONTINUE ********** LOOP FOR K-TH EIGENVALUE

FOR K=M2 STEP -i UNTIL M1 DO -- (-DO- NOT USED TO LEGALIZE COMPUTEE-GO-TO) **********

K = M2 250 XU = LB

********** FOR I=K STEP -i UNTIL MI DO -- **********

DO 260 II = MI, K I = MI + K - II

IF (XU .GE. RV4(1)) GO TO 260

XU = RV4 (I)

GO TO 280

260 CONTINUE

280 IF (XO .GT. RV5(K)) X0 = RV5(K) ********** NEXT BISECTION STEP **********

300 Xl = (XU + X0) * 0.5 IF ((X0 - XU) .LE. (2.0 * MACHEP *


********** IN-LINE PROCEDURE FOR STURM SEQUENCE ********** 320 S = P - 1

U:I.0

325

330

340

DO 340 1 = P, Q

IF (U .NE. 0.0) GO TO 325

V = ABS(E(1)) / MACHEP GO TO 330 V = E2(1) / U

u = D(I) - El - V

IF (U .LT. 0.0) S = S + I CONTINUE

GO TO (60,80,200,220,360), ISTURM ********** REFINE INTERVALS **********

360 IF (S .GE. K) GO TO 400 XU = Xl IF (S .GE. MI) GO TO 380

RV4(MI) = El

GO TO 300 380 RV4(S+I) = XI

IF (RVS(S) .GT. XI) RVS(S) = El

GO TO 300 400 XO = X1

GO TO 300

509

7.1-315

C ********** K-TH EIGENVALUE FOUND **********

420 RV5(K) = X1

K = K - I

IF (K .GE. MI) GO TO 250

C ********** ORDER EIGENVALUES TAGGED WITH THEIR

C SUBMATRIX ASSOCIATIONS **********

900 S = R

R = R + M2 - M1 + 1

J = 1

K = M1

DO 920 L = i, R

IF (J .GT. S) GO TO 910

IF (K .GT. M2) GO TO 940

IF (RV5(K) .GE. W(L)) GO TO 915

905

DO 905 II = J, S

I = L + S - II

W(I+t) = W(I)

!ND(I+I) = IND(1)

CONTINUE

910 W(L) = RV5(K)

IND(L) = TAG

K = K + i

GO TO 920

915 7 = J + I

920 CONTINUE

940 IF (q ~LT. N) GO TO I00

GO TO i001 ********** SET ERROR -- INTERVAL CANNOT BE FOUND CONTAINING

EXACTLY THE DESIRED EIGENVALUES **********

980 IERR = 3 * N + ISTURM

i001LB = TI

UB = T2

RETURN

END

510

7.1-316

NATS PROJECT


F293-2 TSTURM

A Fortran IV Subroutine to Determine Some Eigenvalues and Eigenvectors of a Symmetric Tridiagonal Matrix.

May, 1972 July, 1975

i. PURPOSE.

The Fortran IV subroutine TSTURM determines those eigenvalues of a symmetric tridiagonal matrix in a specified interval and their corresponding eigenvectors, using Sturm sequencing and inverse iteration.

2. USAGE.



SUBROUTINE TSTURM(NM,N,EPSI,D,E,E2,LB,UB, MM,M,W,Z,IERR,RVI,RV2,RV3, RV4,RV5,RV6)




EPS 1 is a working precision real variable. On input, it specifies an absolute error tolerance for the computed eigenvalues. If MACHEP denotes the relative machine precision, then EPSI should be chosen so that the accuracy of these eigenvalues is

511

7.1-317

E2

LB,UB

MM

commensurate with relative perturbations of the order of MACHEP in the matrix elements. If the input EPSI is non- positive, it is reset to a default value described in section 2C.



is a working precision real one-dimensional variable of dimension at least N. On input, the last N-I positions in this array contain the squares of the subdiagonal elements of the symmetric tridiagonal matrix. E2(1) is arbitrary. On output, E2(1) is set to zero. If any of the elements in E are regarded as negligible, the corresponding elements of E2 are set to zero, and so the matrix splits into a direct sum of submatrices.

are working precision real input variables specifying the lower and upper endpoints, respectively, of the interval to be searched for the eigenvalues. If LB is not less than UB, TSTURM computes no eigenvalues or eigenvectors. See section 2C for further details.

is an integer input variable set equal to an upper bound for the number of eigenvalues in the interval (LB,UB).

is an integer output variable set equal to the number of eigenvalues found to lie in the interval (LB,UB).

is a working precision real output one- dimensional variable of dimension at least MM containing the M eigenvalues of the symmetric tridiagonal matrix in the interval (LB,UB). If the matrix does not split into submatrices, the eigenvalues are in ascending order in W. If the matrix does split, the eigenvalues for each submatrix are in ascending order in W.

512

7 .1 -318

is a working precision real output two- dimensional variable with row dimension NM and column dimension at least MM. It contains M orthonormal eigenvectors of the symmetric tridiagonal matrix corresponding to the M eigenvalues in W.


RVI,RV2,RV3

are working precision real temporary one- dimensional variables of dimension at least N used to store the main diagonal and the two adjacent diagonals of the triangular matrix produced in the inverse iteration process.

RV4,RVS,RV6 are working precision real temporary one- dimensional variables of dimension at least N. RV4 and RV5 hold the lower and upper bounds for the eigenvalues in the bisection process. In addition, RV4 holds the multipliers of the Gaussian elimination step in the inverse iteration process. RV6 holds the approximate eigenvectors in this process.


If M exceeds MM, TSTURM terminates with no eigenvalues or eigenvectors computed, and IERR is set to 3*N+I. In this case, the output parameter M is the number of eigenvalues found to lie in (LB,UB).

If more than 5 iterations are required to determine an eigenvector, TSTURM terminates with IERR set to 4*N+R, where R is the index of the eigenvector for which the failure occurs. The eigenvalues and eigenvectors in the W and Z arrays should be correct for indices 1,2,...~R-I.

If M does not exceed MM and all the eigenvectors are determined within 5 iterations, IERR is set to zero.

513

7. 1-319


To determine some of the eigenvalues and eigenvectors of a full symmetric matrix, TSTURM should be preceded by TREDI (F277) to provide a suitable symmetric tridiagonal matrix for TSTURM. It should then be followed by TRBAKI (F279) to back transform the eigenvectors from TSTURM into those of the original matrix.

To determine some of the eigenvalues and eigenvectors of a complex Hermitian matrix, TSTURM should be preceded by HTRIDI (F284) to provide a suitable real symmetric tridiagonal matrix for TSTURM. It should then be followed by HTRIBK (F285) to back transform the eigenvectors from TSTURM into those of the original matrix.

Some of the eigenvalues and eigenvectors of certain non- symmetric tridiagonal matrices can be computed using the combination of FIGI (F280), TSTURM, and BAKVEC (F281). See F280 for the description of this special class of matrices. For these matrices, TSTURM should be preceded by FIGI to provide a suitable symmetric matrix for TSTURM. It should then be followed by BAKVEC to back transform the eigenvectors from TSTURM into those of the original matrix.

The interval (LB,UB) is formally half-open, not including the upper endpoint UB. However, because of rounding errors, the true eigenvalues very close to the endpoints of the interval may be erroneously counted or missed.

The input interval (LB,UB) may be refined internally to a smaller interval known to contain all the eigenvalues in (LB,UB). This insures that TSTURM will not perform unnecessary bisection steps to determine the eigenvalues in (LB,UB).

The computation of the eigenvectors by inverse iteration requires that the precision of the eigenvalues be commensurate with small relative perturbations of the order of MACHEP in the matrix elements. For most symmetric tridiagonal matrices, it is enough that the absolute error EPSI in the eigenvalues for which eigenvectors are desired be approximately MACHEP times a norm of the matrix. But some matrices require a smaller EPSI, perhaps as small as MACHEP times the eigenvalue of smallest magnitude in the interval (LB,UB). Note, however, that if EPSI is smaller than necessary, TSTURM will perform unnecessary bisection steps to determine the eigenvalues. For further discussion of EPSI, see reference (2).

514

7.1-320

If the input EPSI is non-positive, TSTURM resets it, for each submatrix, to -MACHEP times the 1-norm of the submatrix and uses its magnitude. This value is considered adequate for most symmetric tridiagonal matrices and is recommended for use generally. If TSTURM terminates with a vector error exit, a smaller EPSI may be more successful.


The eigenvalues are determined by the method of bisection applied to the Sturm sequence and the eigenvectors are determined by inverse iteration.

The calculations proceed as follows. First, the subdiagonal elements are tested for negligibility. If an element is considered negligible, its square is set to zero, and so the matrix splits into a direct sum of submatrices. Then, the Sturm sequence for the entire matrix is evaluated at UB and LB giving the number of eigenvalues of the matrix less than UB and LB respectively. The difference is the number of eigenvalues in (LB,UB).

Next, a submatrix is examined for its eigenvalues in the interval (LB,UB). The Gerschgorin interval, known to contain all the eigenvalues, is determined and used to refine the input interval (LB,UB). If the input EPSI is non- positive, it is reset to the default value described in section 2C. Then, subintervals, each enclosing an eigenvalue in (LB,UB), are shrunk using a bisection process until the endpoints of each subinterval are close enough to be accepted as an eigenvalue of the submatrix. Here the endpoints of each subinterval are close enough when they differ by less than MACHEP times twice the sum of the magnitudes of the endpoints plus the absolute error tolerance EPSI.

The eigenvectors of the same submatrix are then computed by inverse iteration. First, the LU decomposition of the submatrix with an approximate eigenvalue subtracted from its diagonal elements is achieved by Gaussian elimination using partial pivoting. The multipliers defining the lower triangular matrix L are stored in the temporary array RV4 and the upper triangular matrix U is stored in the three temporary arrays RVl, RV2, and RV3. Saving these quantities in RVI, RV2, RV3, and RV4 avoids repeating the LU decomposition if further iterations are required. An approximate vector, stored in RV6, is computed starting from an initial vector, and the norm of the approximate vector is compared with a norm of the submatrix to determine whether the growth is sufficient to accept it as an eigenveetor. If this vector is accepted, its Euclidean norm

515

7.1-321

is made I~ If the growth is not sufficient, this vector is used as the initial vector in computing the next approximate vector. This iteration process is repeated at most 5 times.

Eigenvectors computed in the above way corresponding to well- separated eigenvalues of this submatrix will be orthogonal. However, eigenvectors corresponding to close eigenvalues of this submatrix may not be satisfactorily orthogonal. Hence, to insure orthogonal eigenvectors, each approximate vector is made orthogona! to those previously computed eigenvectors whose eigenvalues are close to the current eigenvalue. If the orthogonalization process produces a zero vector, a column of the identity matrix is used as an initial vector for the next iteration.

Identical eigenvalues are perturbed slightly in an attempt to obtain independent eigenvectors. These perturbations are not recorded in the output eigenvalue array W.

The above steps are repeated on each submatrix until all the eigenvalues in the interval (LB,UB) and their corresponding eigenvectors are computed.

This subroutine is a translation of the Algol procedure TRISTURM written and discussed in detail by Peters and Wilkinson (I).

4. REFERENCES.

i) Peters, G. and Wilkinson, J.H., The Calculation of Specified Eigenvectors by Inverse Iteration, Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/18, 418-439, Springer-Verlag, 1971.

z) Barth, W., Martin, R.S., and Wilkinson, J.H., Calculation of the Eigenvalues of a Symmetric Tridiagonal Matrix by the Method of Bisection, Num. Math. 9,386-393 (1967).

5 . CHECKOUT°

A. Test Cases~


B. Accuracy.

516

7.1-322

The subroutine TSTURM is numerically 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 and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.

517

7.1-323

SUBROUTINE TSTURM(NM,N,EPSI,D,E,E2,LB,UB,MM,M,W,Z,

X IERR,RVI,RV2,RV3,RV4,RVS,RV6)

INTEGER I,J,K,M,N,P,Q,R,S,II,IP,JJ,MM,MI,M2,NM,ITS, X !ERK,GROUP,ISTURM REAL D(N),E(N),E2(N),W(MM),Z(NM,MM),

X RVI (N),RV2(N),RV3(N),RV4(N),RV5(N),RV6(N) REAL U,V,LB,TI,T2,UB,UK,XU,X0,XI,EPSI,EPS2,EPS3,EPS4,

X NORM,MACHEP REAL SQRT,ABS,AMAXI,AMINI,FLOAT



**********

MACHEP = ?

IERR = 0

TI = LB

T2 = UB C ********** LOOK FOR SMALL SUB-DIAGONAL ENTRIES **********

DO 40 I = i, N IF (I .EQ. I) GO TO 20 IF (ABS(E(1)) .GT. MACHEP * (ABS(D(1)) + ABS(D(I-I))))

X GO TO 40

20 E2(1) = 0.0 40 CONTINUE

C ********** DETERMINE THE NUMBER OF EIGENVALUES

C IN THE INTERVAL **********

P=I Q = N

XI = UB ISTURM = 1

GO TO 320 60 M = S

XI = LB ISTURM = 2 GO TO 320

80 M = M - S IF (M .GT. MM) GO TO 980

Q = 0

R = 0 C ********** ESTABLISH AND PROCESS NEXT SUBMATRIX, REFINING

C INTERVAL BY THE GERSCHGORIN BOUNDS *****~****

i00 IF (R .EQ. M) GO TO I001 P = Q + I

XU = D ( P )

X0 = D(P) U=O.O

518

7.1-324

C

DO 120 Q = P, N

X1 = U

U = 0.0 V = 0.0 IF (Q .EQ. N) GO TO Ii0

U = ABS (E (Q+I))

v = E2(Q+I) ii0 XU = AMINI(D(Q)-(XI+U),XU)

X0 = AMAXI(D(Q)+(XI+U),X0)

IF (V .EQ. 0.0) GO TO 140 120 CONTINUE

140 Xl = AMAXI(ABS(XU),ABS(XO)) * MACHEP IF (EPSI .LE. 0.0) EPSI =-XI

IF (P .NE. Q) GO TO 180

• ********* CHECK FOR ISOLATED ROOT WITHIN INTERVAL ********** IF (TI .GT. D(P) .OR. D(P) .GE. T2) GO TO 940 R = R + 1

DO 160 I = I, N 160 Z(I,R) = 0.0

W(R) = D(P) Z(P,R) = 1.0

GO TO 940

180 X1 = X1 * FLOAT(Q-P+I) LB = AMAXI(TI,XU-XI)

UB = AMINI(T2,X0+XI) X1 = LB ISTURM = 3

GO TO 320 200 MI = S + i

Xl = UB ISTURM = 4

GO TO 320 220 M2 = S

IF (MI .GT. M2) GO TO 940

• ********* FIND ROOTS BY BISECTION ********** X0 = UB ISTURM = 5

DO 240 I = MI, M2

RV5 (I) = UB RV4(I) = LB

240 CONTINUE

********** LOOP FOR K-TH EIGENVALUE FOR K=M2 STEP -i UNTIL M1 DO --

(-DO- NOT USED TO LEGALIZE COMPUTEE-GO-TO) ********** K = M2

250 XU = LB

519

7.1-325

C

C

C

260

********** FOR I=K STEP -i UNTIL M1 DO -- ********** DO 260 II = M!, K

I = M1 + K - II

IF (XU .GE. RV4(I)) GO TO 260

XU = RV4(1) GO TO 280

CONTINUE

280 IF (XO .GT. RV5(K)) X0 = RV5(K)

********** NEXT BISECTION STEP **********

300 X1 = (XU + X0) * 0.5 IF ((X0 - XU) .LE. (2.0 * MACHEP *


********** IN-LINE PROCEDURE FOR STURM SEQUENCE **********

320 S = P - 1 U=I.0

325

330

340

DO 340 1 = P, Q

IF (U .NE. 0.0) GO TO 325 V = ABS(E(1)) / MACHEP

GO TO 330 V = E2(I) / U U = D(1) - El - V IF (U .LT. 0.0) S = S + i

CONTINUE

GO TO (60,80,200,220,360), !STURM ********** REFINE INTERVALS **********

360 IF (S .GE. K) GO TO 400

XU = X1 IF (S aGE. MI) GO TO 380

RV4(MI) = XI

GO TO 300

380 RV4 (S+I) = X1 IF (RV5(S) .GT. XI) RV5(S) = X1

GO TO 300

400 X0 = X1 GO TO 300

********** K-TH EIGENVALUE FOUND **********

420 RV5 (K) = X1

K = K - 1 IF (K .GE. MI) GO TO 250 ***~****** FIND VECTORS BY INVERSE ITERATION **********

NORM = ABS(D(P)) IP = P + i

DO 500 I = IP, Q 500 NORM = NORM + ABS(D(1)) + ABS(E(1))

520

7.1-326

520

540

560

580

********** EPS2 IS THE CRITERION FOR GROUPING,

EPS3 REPLACES ZERO PIVOTS AND EQUAL

ROOTS ARE MODIFIED BY EPS3,

EPS4 IS TAKEN VERY SMALL TO AVOID OVERFLOW ********** EPS2 = 1.0E-3 * NORM EPS3 = MACHEP * NORM UK = FLOAT (Q-P+I)

EPS4 = UK * EPS3 UK = EPS4 / SQRT(UK)

GROUP = 0 S = P

DO 920 K = MI, M2 R = R + I

ITS = 1 W(R) = RV5(K)

Xl = RV5 (K)

********** LOOK FOR CLOSE OR COINCIDENT ROOTS ********** IF (K .EQ. MI) GO TO 520

IF (XI - X0 .GE. EPS2) GROUP = -i GROUP = GROUP + 1

IF (XI .LE. X0) Xl = X0 + EPS3

********** ELIMINATION WITH INTERCHANGES AND

INITIALIZATION OF VECTOR ********** v=o.o

DO 580 I = P, Q

RV6 (I) = UK

IF (I .EQ. P) GO TO 560

IF (ABS(E(1)) .LT. ABS(U)) GO TO 540 XU = U / E(1) RV4(1) = XU RVI(I-I) = E(I)

RV2(I-I) = D(1) - XI

RV3(I-I) = 0.0

IF (I .NE. Q) RV3(I-I) -- E(I+I) U = V - XU * RV2(I-I) V = -XU * RV3(I-I)

GO TO 580 XU = E(1) / U RV4(1) = XU

RVI(I-I) = U

RV2(I-I) = V

RV3(I-I) = 0.0

u = D(I) - Xl - XU * V

IF (I .NE. Q)V = E(I+I) CONTINUE

IF (U .EQ. 0.0) U = EPS3 RVI (Q) = U

RV2(Q) = 0.0 RV3(Q) = 0.0

521

7.1-327

C ********** BACK SUBSTITUTION

C FOR I=Q STEP -I UNTIL P DO -- ********** 600 DO 620 II = P, Q

I = P + Q - II RV6(1) = (RV6(1) - U * RV2(1) - V * RV3(1)) / RVI(1)

V = U

U = RV6 (I) 620 CONTINUE

C ********** ORTHOGONALIZE WITH RESPECT TO PREVIOUS

C MEMBERS OF GROUP **********

IF (GROUP .EQ. 0) GO TO 700

640

660

C 680

C 700

C

720

740

C C

C

DO 680 JJ = I, GROUP J = R - GROUP - 1 + JJ

XU = 0.0

DO 640 ! = P, Q XU = XU + RV6(1) * Z(I,J)

DO 660 1 = P, Q RV6(1) = RV6(1) - XU * Z(I,J)

CONTINUE

NORM = 0.0

DO 720 1 = P, Q NORM = NORM + ABS(RV6(I))

IF (NORM oGE. 1.0) GO TO 840

********** FORWARD SUBSTITUTION ********** IF (ITS .EQ. 5) GO TO 960

IF (NORM .NE. 0.0) GO TO 740

RV6(S) = EPS4

S = S + 1 IF (S .GT. Q) S = P

GO TO 780 XU = EPS4 / NORM

DO 760 I = P, Q 760 l{V6(I) = RV6(I) * XU

• ********* ELIMINATION OPERATIONS ON NEXT VECTOR

ITERATE **********

780 DO 820 I = IP, Q U = RV6 (I)

• ********* IF RVI(I-I) .EQ. E(1), A ROW INTERCHANGE

WAS PERFORMED EARLIER IN THE

TRIANGULARIZATION PROCESS ********** IF (RVI(I-I) .NE. E(1)) GO TO 800

U = RV6 (I-I) RV6(I-I) = RV6(1)

800 RV6(1) = U - RV4(1) * RV6(I-I) 820 CONTINUE

522

7.1-328

840

ITS = ITS + 1

GO TO 600

********** NORMALIZE SO THAT SUM OF SQUARES IS

i AND EXPAND TO FULL ORDER **********

U = 0.0

860

DO 860 1 = P, q U = U + RV6(1)**2

XU = 1.0 / SQRT(U)

880 DO 880 1 = I, N

Z(I,R) = 0.0

900

DO 900 1 = P, Q

Z(I,R) = RV6(1) * XU

X0 = XI

920 CONTINUE

940 IF (Q .LT. N) GO TO i00

GO TO i001

********** SET ERROR -- NON-CONVERGED EIGENVECTOR ********** 960 IERR = 4 * N + R

GO TO i001

********** SET ERROR -- UNDERESTIMATE OF NUMBER OF

EIGENVALUES IN INTERVAL **********

980 IERR = 3 * N + I

i001LB = TI

UB = T2

RETURN

END

523

7.2-I

NATS PROJECT


F299-2 EISPAC

A Control Program for the Eigensystem Package (F269 to F298 and F220 to F247).

May, 1972 July, 1975

i. PURPOSE~

The Fortran IV and 0S/360-370 assembly language subroutine EISPAC (together with its associated "keyword" entry points) is designed to simplify the solution of the standard and generalized matrix eigenproblems using the subroutines in the eigensystem package (F269-F298, F220-F247). It thus may be used to compute some or all of the eigenvalues, with or without eigenvectors, of complex general, complex Hermitian, real general, real symmetric, real symmetric tridiagonal, certain real non-symmetric tridiagonal, and real symmetric band matrices; and it may also be used to compute some or all of the eigenvalues, with or without eigenvectors, for the real symmetric generalized eigenproblem, or all of the eigenvalues, with or without eigenvectors, for the real non- symmetric generalized eigenproblem. EISPAC offers the following advantages if you wish to solve an eigenproblem:

!o You describe the problem to EISPAC in simple, familiar terms°

2~ Using your description, EISPAC automatically selects subroutines to solve your problem and executes them in the proper order and with parameters passed from one to another in the proper way. In general, EISPAC selects the sequence of subroutines in the eigensystem package which will solve your problem as rapidly as possible with reasonable assurance of stability in the calculations.

3~ EISPAC loads each selected subroutine only as it is required, thus making available for data storage as much memory as possible. On the other hand, if sufficient memory is available, the subroutines used are retained in memory and are not reloaded when you repeatedly call EISPAC to solve the same problem. (See section 3 below.)

4. EISPAC allocates and frees any necessary auxiliary storage automatically.

524

7.2-2

5. Use of EISPAC minimizes the number of changes you must make to your program if you wish to solve a slight variation of your original problem or if you wish to take advantage of new methods when they are introduced.

6. EISPAC is called as a subroutine from your own driver program. Thus the matrix whose eigensystem is being computed may itself be the result of other computations in your program, and the computed eigensystem may conveniently be used in further calculations.

Thus EISPAC relieves you of having to develop a detailed knowledge of the applicability, efficiency, and calling sequences of the individual EISPACK subroutines.

2. USAGE.


EISPAC employs variable length parameter lists and "keyword" parameters to simplify specification of your problem and to group related subparameters. An overview of the calls to EISPAC is given by the prototype calls below; specific calls for different classes of matrices are discussed in section 2.B.

The prototype call to EISPAC for the standard eigenproblem is:

CALL EISPAC (NM, N, MATRIX (...), BAND (...), VALUES (.0.), VECTOR (...), METHOD (...), ERROR (...), SU~R ( . . . ) )

where

NM is an integer variable which supplies the row (first) dimension of any two- dimensional arrays appearing in the call to EISPAC (as that dimension is specified in the DIMENSION statements for them in the calling program). For example, if your program contains arrays dimensioned: A(50,50), Z(50,50) which appear in the call to EISPAC, and the order of the eigenproblem being solved is 25, then NM = 50 and N = 25.

525

7 . 2 - 3

is an integer variable which supplies the order of the input matrix. N is checked to verify that it is neither greater than NM nor less than i.

MATRIX, BAND, VALUES, VECTOR, METHOD, ERROR, SUBR are keyword parameters. They accept sets of subparameters which define the eigenproblem being solved. (These subparameters are discussed in detail in section 2.C below.) Keyword parameters not needed to specify a particular problem are omitted from the call to EISPAC; those appearing may appear in any order.

The prototype call to EISPAC for the generalized eigenproblem is:

CALL EISPAC (NM, N, MATA (..o), MATB (...), VALUES (...), VECTOR (...), ERROR (...), SUBR (.o.))

where MATA and MATB replace MATRIX as keyword parameters. Note: MATRIX and MATA are alternate forms of the same keyword and can be used interchangeably.

To use EISPAC, you must include a private library DD card for EISPACLB (the dynamic load library, see section 3 below) in the GO-step of your job. This card associates EISPACLB with the dataset where the load modules for EISPAC and the eigensystem package subroutines reside. If you are using a typical Fortran cataloged procedure, this card is:

//GO.EISPACLB DD DISP=SHR,DSNAME=...

Similarly, if you are using the TSO time sharing system~ you should execute the command:

ALLOC FiLE(EISPACLB) DATASET(...) SHR

before executing your program.

Finally, if you wish to use EISPAC from a PL/I (Checkout or Optimizer) program by means of the interlanguage communication facility, you should write a simple Fortran subroutine which is called from your PL/I program and which in turn calls E!SPAC as described below. This is necessary because EISPAC makes certain (non-standard) assumptions about the Fortran environment of the program calling it which may not be satisfied

526

7.2-4

when the program is written in PL/I. The Fortran program calling EISPAC should have as parameters the variables to be passed to EISPAC; you should take care that the vectors and arrays appear in DIMENSION statements in it. Thus for the example concluding the section on real symmetric matrices in section 2.B below, the Fortran subroutine called by your PL/I program should look like:

SUBROUTINE EISCAL (N, A, W, Z) INTEGER N REAL*8 A(N,N), W(N), Z(N,N) CALL EISPAC (N, N, MATRIX ('REAL, A, 'SYMMETRIC'),

VALUES (W), VECTOR (Z)) RETURN END

This example assumes that the PL/I arrays corresponding to the matrices A and Z are dimensioned exactly NxN, and hence that the parameter NM can be replaced by N. In the PL/I calling program, EISCAL would be declared:

DCL EISCAL ENTRY (FIXED BINARY(31,0), (*,*) FLOAT DECIMAL(16), (*) FLOAT DECIMAL(16), (*,*) FLOAT DECIMAL(16)) OPTIONS (FORTRAN) EXTERNAL;

You must provide a DD card or allocation for FT06F001, the standard Fortran output file, because Fortran automatically tries to open it. This file should be associated with the same dataset as the output from the PL/I program, so that EISPAC error messages, if any, appear with it. Finally, if you are using the PL/I Checkout compiler, you need to specify the option SIZE(-nK) to the execution step to reserve dynamic storage for EISPAC; at a minimum n=14, and it must be large enough to accommodate any temporary arrays that are allocated. (An insufficiently large value of n will result in either of the system completion codes 804 or 80A (see section 2.D).)

The use of EISPAC to solve various kinds of eigenproblems is illustrated in the following section. You may wish to read first the examples for the type of matrix you have and then consult section 2.C for further details about the keyword subparameters. (Note that in these examples the continuation symbol which must appear in column 6 of a Fortran continuation card has been omitted.)

527

7.2-5

B. EISPAC Examples for Different Classes of Matrices.

Complex General Matrix

The basic call, which finds all of the eigenvalues (WR, WI) of the complex general matrix (AR, AI), is:

CALL EISPAC (NM, N, MATRIX ('C0MPLSX', AR, A!), VALUES (WR, WZ))

If you wish to find all of the eigenvectors (ZR, ZI), add: VECTOR (ZR, ZI).

If you wish to find all of the eigenvalues and only selected eigenvectors~ add: VECTOR (ZR, ZI, MM, M, SELECT).

If you prefer not to balance the matrix, add: METHOD ('NO', 'BALANCE').

If you wish to use elementary instead of unitary similarities, add: METHOD ('ELEMENTARY')~

Thus a call to find all of the eigenvalues and some of the eigenvectors of a complex general matrix is:

CALL EISPAC (NM, N, MATRIX ('COMPLEX', AR, AI), VALUES (WR, WI), VECTOR (ZR, ZI, MM, M, SELECT))

Complex Hermitian Matrix

Recall that a complex Hermitian matrix is a matrix which is equal to its complex conjugate transpose. If you wish to solve an eigenproblem for a complex symmetric matrix (a matrix which is equal to its transpose without conjugation), you must follow the complex general matrix examples.

The basic call, which finds all of the eigenvalues W of the complex Hermitian matrix (AR, AI), is:

CALL EISPAC (NM, N, MATRIX ('COMPLEX', AR, AI, 'HERMITIAN'), VALUES (W))

528

7.2-6

If the complex Hermitian matrix is packed into a single two-dimensional array, HP, substitute for MATRIX ('COMPLEX', AR, AI, 'HERMITIAN'): MATRIX ('COMPLEX', HP, HP, 'HERMITIAN', 'PACKED').

If you wish to find only the eigenvalues in the interval (RLB,RUB), substitute for VALUES (W) (see note 3): VALUES (W, MM, M, RLB, RUB).

Alternatively, if you wish to find exactly M eigenvalues, starting from the Mll-th smallest one, substitute for VALUES (W): VALUES (W, MII, M). (See notes i and 3.)

If you wish to find the eigenvectors (ZR, ZI) corresponding to the eigenvalues found, add: VECTOR (ZR, ZI).

Thus a call to find a few eigenvalues and their corresponding eigenvectors of a complex Hermitian matrix is:

CALL EISPAC (NM, N, MATRIX ('COMPLEX', AR, AI, 'HERMITIAN'), VALUES (W, MM, M, RLB, RUB), VECTOR (ZR, ZI))

Real General Matrix

The basic call, which finds all of the eigenvalues (WR, WI) of the real general matrix A, is:

CALL EISPAC (NM, N, MATRIX ('REAL', A), VALUES (WR, WI))

If you wish to find all of the eigenvectors ZP, add: VECTOR (ZP).

If you wish to find all of the eigenvalues and only selected eigenvectors, add: VECTOR (ZP, MM, M, SELECT).

If you prefer not to balance the matrix, add: METHOD ('NO', 'BALANCE').

If you wish to use orthogonal instead of elementary similarities for the reduction to upper Hessenberg form, add (see note 5): METHOD ('ORTHOGONAL').

529

7.2-7

Thus a call to find all of the eigenva!ues of a real general matrix without balancing and using orthogonal similarities is:

CALL EiSPAC (NM, N, MATRIX ('REAL', A), VALUES (WR, WI), METHOD ('NO', 'BALANCE', 'ORTHOGONAL'))

Real Non-Symmetric Tridiagonal Matrix

The following examples apply only if the products of corresponding off-diagonal elements of the tridiagonal matrix all are non-negative. (Read note 4 below for an additional restriction if you wish to compute eigenvectors.) Otherwise the real general matrix examples must be followed.

The basic call, which finds all of the eigenvalues W of the real tridiagonal matrix UST, is:

CALL EISPAC (NM, N, MATRIX ('REAL', UST, 'TRIDIAGONAL'), VALUES (W))

If you wish to find only the eigenva!ues in the interval (RLB,RUB), substitute for VALUES (W) (see note 3): VALUES (W, MM, M, RLB, RUB).

Alternatively, if you wish to find exactly M eigenvalues, starting from the Mll-th smallest one, substitute for VALUES (W): VALUES (W, MII, M). (See notes 1 and 3.)

If you wish to find the eigenvectors Z corresponding to the eigenvalues found, add: VECTOR (Z).

Thus a call to find exactly M eigenvalues, starting from the Mll-th smallest one, of a real non-symmetric tridiagonal matrix is:

CALL EISPAC (NM, N, MATRIX ('REAL', UST, 'TRIDIAGONAL'), VALUES (W, MII, M))

Real Symmetric Matrix

The basic call, which finds all of the eigenvalues W of the real symmetric matrix A, is (see note 2):

530

7 . 2 - 8

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

If the real symmetric matrix is packed into a single one-dimensional array, SP, substitute for MATRIX ('REAL', A, 'SYMMETRIC'): MATRIX ('REAL', SP, 'SYMMETRIC', 'PACKED').


Alternatively, if you wish to find exactly M eigenvalues, starting from the Mll-th smallest one, substitute for VALUES (W): VALUES (W, MII, M). (See notes I and 3.)


Thus a call to find all of the eigenvalues and eigenvectors of a real symmetric matrix is:

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

Real Symmetric Tridiagonal Matrix

The basic call, which finds all of the eigenvalues W of the real symmetric tridiagonal matrix ST, is (see note 2):

CALL EISPAC (NM, N, MATRIX ('REAL', ST, 'SYMMETRIC', 'TRIDIAGONAL'), VALUES (W))




531

7.2-9

Thus a call to find some of the eigenvalues of a real symmetric tridiagonal matrix is:

CALL EISPAC (NM, N, MATRIX ('REAL', ST, 'SYMMETRIC', 'TRIDIAGONAL'), VALUES (W, MM, M, RLB, RUB))

Real Symmetric Band Matrix . . . . . . . . . . . . . . . . . . . . . . .

The basic call, which finds all of the eigenvalues W of the real symmetric band matrix SB, is (see notes 2 and 6):

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


Alternatively, if you wish to find exactly M eigenvalues, starting from the Mll-th smallest one, substitute for VALUES (W): VALUES (W, MII, M). (See notes 1 and 3.)


Thus a call to find some of the eigenvalues of a real symmetric band matrix is:

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

Generalized Real Symmetric Matrix Systems

There are three forms of the real symmetric generalized eigenproblem that can be solved with EISPAC: namely, the forms Ax = (lambda)Bx, ABx = (lambda)x, and BAx = (lambda)x, where A and B are both symmetric and B is positive definite.

532

7.2-10

The basic call, which finds all of the eigenvalues W of the real symmetric generalized system Ax = (lambda)Bx, is (see notes 2 and 7):

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




If the problem is of the form ABx = (lambda)x or BAx = (lambda)x, supply 'ABX=LX' or 'BAX=LX', respectively, to MATB (in a position after the B parameter).

Thus a call to find exactly M eigenvalues, starting from the Mll-th smallest one, and the corresponding eigenveetors of the real symmetric generalized system ABx = (lambda)x, is:

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

Generalized Real Non-Symmetric Matrix System

The basic call, which finds all of the eigenvalues (ALPHAR/BETA, ALPHAI/BETA) for the real non~ symmetric generalized eigenproblem Ax = (lambda)Bx, is (see note 8):

CALL EISPAC (NM, N, MATA ('REAL', A), MATB ('REAL', B), VALUES (ALPHAR, ALPHAI, BETA))

If you wish to find all of the eigenvectors, ZP, of the system, add: VECTOR (ZP).

533

7.2-11

Thus a call to find all of the eigenvalues and eigenvectors of a real non-symmetric generalized system is:

CALL EISPAC (NM, N, MATA ('REAL ~ , A), MATB ('REAL', B), VALUES (ALPHAR, ALPHAI, BETA), VECTOR (ZP))

C~ Meanings of Keyword Subparameters.

Subparameters for MATRIX, MATA, and MATB:

'REAL' specifies that the matrix whose eigensystem is to be computed is real. (See note 9.)

'COMPLEX' specifies that the matrix whose eigensystem is to be computed is complex. (See note 9.)

AR, AI are long precision real two-dimensional variables with row dimension NM and column dimension at least N. They supply, respectively, the real and imaginary parts of the complex matrix whose eigensystem is to be computed. In the non-Hermitian case, the information in the full AR and AI arrays specifies the matrix, and all of it is destroyed. In the Hermitian case, the information in the full lower triangle of AR and the strict lower triangle of AI specifies the matrix, and is destroyed as well as the diagonal of AI; the full upper triangle of AR and the strict upper triangle of AI are left unaltered.

A~ B are long precision real two-dimensional variables with row dimension NM and column dimension at least N. They supply the real matrices whose eigensystem is to be computed. (For the standard eigenproblem, only A is supplied.) In the non-symmetric case, the information in the full A and B arrays specifies the matrices, and all of it is destroyed. In the symmetric standard case~ the information in the full lower triangle of A specifies the matrix; that in the strict lower triangle may be destroyed, and that in the full upper triangle is left

534

7.2-12

UST

ST

HP

unaltered. In the symmetric generalized case, the information in the full upper triangles of A and B specifies the matrices; the full lower triangle of A and the strict lower triangle of B are destroyed, and the strict upper triangle of A and the full upper triangle of B are left unaltered.

is a long precision real two-dimensional variable with row dimension NM and column dimension at least 3. It supplies a real non-symmetric tridiagonal matrix whose subdiagonal elements are stored in the last N-I positions of the first column, whose diagonal elements are stored in the second column, and whose superdiagonal elements are stored in the first N-I positions of the third column. UST(I,I) and UST(N,3) are arbitrary. None of the information in UST is destroyed. The non-symmetric tridiagonal matrix supplied by UST must have the additional special property that the products of corresponding off-diagonal elements all are non-negative. (Read note 4 for an additional restriction on UST if eigenvectors are being computed.) Violation of these restrictions on UST causes an EISPAC execution phase error (see section 2.D below).

is a long precision real two-dimensional variable with row dimension NM and column dimension at least 2. It supplies a real symmetric tridiagonal matrix whose subdiagonal elements are stored in the last N-I positions of the first column and whose diagonal elements are stored in the second column. ST(I,1) is arbitrary. The information in the subdiagonal (first column) only is destroyed.

is a long precision real two-dimensional variable with row dimension NM and column dimension at least N. On input, HP contains the lower triangle of a packed complex Hermitian matrix of order N whose eigensystem is to be computed. If the real part of the matrix is denoted by AR and the imaginary part by AI, then the full

535

7.2-13

SP

SB

lower triangle of AR should be stored in the full lower triangle of HP, and the strict lower triangle of AI should be stored in the strict upper triangle of HP in transposed form. For example when N=4, HP should contain

(AR(I,I) AI(2,1) AI(3,1) A!(4,1) ) (AR(2,1) AR(2,2) AI(3,2) AI(4,2) ) (AR(3,1) AR(3,2) AR(3,3) AI(4,3) ) (AR(4,1) AR(4,2) AR(4,3) AR(4,4) ).

All of the information in HP is destroyed.

is a long precision real one-dimensional variable with dimension at least N*(N+I)/2. It supplies the lower triangle of a real symmetric matrix A of order N, packed row-wise. For example when N=3, SP should contain

(A(I,I),A(2,1),A(2,2),A(3,1),A(3,2),A(3,3))

where the subscripts of each element refer to the row and column of the element in the standard two-dimensional representation. All of the information in SP is destroyed.

is a long precision real two-dimensional variable with row dimension NM and column dimension at least MB. It supplies the lower triangle of a real symmetric matrix A of order N in band form with half bandwidth MB. The lowest subdiagonal of the matrix is stored in the last N+I-MB positions of the first column of SB, the next subdiagonal in the last N+2-MB positions of the second column, further diagonals similarly, and finally the principal diagonal in the N positions of the last column. Contents of storage locations not part of the matrix are arbitrary. For example, when N=5 and MB=3, SB 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) ).

536

7.2-14

All of the information in SB is destroyed.

'HERMITIAN', 'SYMMETRIC', 'TRIDIAGONAL' 'POSITIVE DEFINITE' , 'NEGATIVE DEFINITE', 'PACKED I

specify that the matrix whose eigensystem is to be found has the stated special property. (See also notes I, 2, and 9.)

'ABX=LX', 'BAX=LX' (as subparameters for MATB) specify the corresponding variant of the real symmetric generalized eigenproblem.

Subparameter for BAND:

MB is an integer variable which supplies the half bandwidth of a real symmetric band matrix. It is defined as the number .of adjacent diagonals, including the principal diagonal, required to specify the non-zero portion of the lower triangle of the matrix.

Subparameters for VALUES:

WR, WI are long precision real one-dimensional variables of dimension at least N. They receive, respectively, the real and imaginary parts of the N complex eigenvalues computed.

W is a long precision real one-dimensional variable of dimension at least sufficient (N, MM, or M) to hold the eigenvalues. It receives the N (M) eigenvalues computed.

MM is an integer variable which, when it is a subparameter to VALUES, supplies a maximum for the number of eigenvalues expected in the interval (RLB,RUB); more than MM eigenvalues in (RLB,RUB) is an error. The dimension of W, and the column dimension of ZR and ZI or Z if used, must be at least MM.

M is an integer variable which, when it is a subparameter to VALUES, denotes the number of eigenvalues actually stored in W. It is supplied (in conjunction with MII) by the user if a specified number of eigenvalues is to be computed. It is set by the program, if an interval (RLB,RUB) has been specified, to the number of eigenvalues actually found.

537

7.2-15

RLB, RUB are long precision real variables which define an interval to be searched for eigenvalues. The eigenvalues found lie in the interval (RLB,RUB), which is closed on the left and open on the right; if RLB is not less than RUB, no eigenvalues are found. (RLB,RUB) must not contain more than MM eigenvalueso

MII is an integer variable which, when it is a subparameter to VALUES, supplies the index of the smallest eigenvalue to be computed.

EPS 1 is a long precision real variable which supplies an absolute error tolerance for the computed eigenvalues; if the input value of EPSI is non-positive, a default value will be used. (See note 3.)

ALPHAR, ALPHAI, BETA are long precision real one-dimensional variables with dimension at least N which receive the complex eigenvalues for a real non-symmetric generalized eigenproblem. The real part of each eigenvalue is given by ALPHAR(I)/BETA(I) and the imaginary part by ALPHAI(I)/BETA(1). (See note 8.)

'LARGEST', 'SMALLEST' specify that the M largest or smallest eigenvalues are to be computed if the rational QR method has been selected° In this case substitute for VALUES(W): VALUES (W, M, 'LARGEST') or VALUES (W, M, 'SMALLEST'), respectively° (See notes i and 9.)

Subparameters for VECTOR:

ZR, ZI are long precision real two-dimensional variables with row dimension NM and column dimension at least sufficient (N, MM, or M) to hold the eigenvectors. They receive, respectively, the real and imaginary parts of the N (M) eigenvectors computed.

ZP is a long precision real two-dimensional variable with row and column dimensions as described for ZR and ZI. It receives N (M) columns which represent eigenvectors of a real general matrix or matrix system. To conserve storages these eigenvectors are stored in ZP in packed form:

538

7.2-16

MM

M

SELECT

corresponding to a real eigenvalue, one column representing the real eigenvector is stored; corresponding to a complex conjugate pair of eigenvalues, two consecutive columns representing the real and imaginary parts of the eigenvector corresponding to the first, or first flagged (see SELECT below), of the pair are stored. For example, suppose all of the eigenvectors of a real general matrix are being computed. If the K-th eigenvalue is real (WI(K) = 0) then ZP(K) is the corresponding eigenvector. If the K-th and (K+l)-th eigenvalues are a complex conjugate pair (with WI(K) .GT. 0) then ZP(K) is the real part and ZP(K+I) is the imaginary part of the eigenvector corresponding to the K-th eigenvalue. The conjugate of this vector is the eigenvector for the conjugate eigenvalue. (Example Fortran statements for unpacking the eigenvectors may be found in section 2.3.2 of (6).)

is a long precision real two-dimensional variable with row and column dimensions as described for ZR and ZI. It receives the N (M) eigenvectors computed. When all of the eigenvectors of a real symmetric (full) matrix or generalized matrix system are being computed, the array A which supplies the input matrix may be used for Z; the eigenvectors then overwrite the input matrix.

is an integer variable which, when it is a subparameter to VECTOR, supplies the maximum number of columns of ZR and ZI or ZP which will be used. The column dimension of ZR and ZI or ZP must be at least MM.

is an integer variable which, when it is a subparameter to VECTOR, receives the number of columns used to store eigenvectors in ZR and ZI or ZP.

is a logical one-dimensional variable of dimension at least N whose true elements flag those eigenvalues of a real or complex general matrix whose eigenvectors are to be computed. If eigenvectors of a real general matrix are being computed and both of a pair of complex conjugate eigenvalues

539

7.2-17

are flagged, the second flag is set false and only the eigenveetor corresponding to the first of the pair is computed. An error results if MM is smaller than the number of columns required to hold the selected eigenvectors.

Subparameters for METHOD:

(See note 9 concerning alphanumeric parameters.)

'ORTHOGONAL' specifies that orthogonal similarities (instead of elementary similarities) are to be used to reduce a real general matrix to upper Hessenberg form. Reduction by orthogonal similarities is somewhat slower than that by elementary similarities~ but in some cases it may improve the accuracy of the computed eigensystem. In particular, if you wish to calculate the condition numbers for the computation of the eigensystem of a matrix (see (3), po 199 and (4), pp. 86-89), you should use the condition-number-preserving orthogonal transformations.

'ELEMENTARY' specifies that elementary similarities (instead of unitary similarities) are to be used on a complex general matrix (the LR rather than the QR transformation). Elementary similarities are somewhat faster than unitary similarities, but in some cases diminish the accuracy of the computed (complex general) eigensystem.

~NO', 'BALANCE' specifies that a real or complex general matrix is not to be balanced before its eigensystem is computed. In general, balancing improves the accuracy of the computed eigensystem and requires very little additional computation time.

'RATQR T specifies that the rational QR method is to be used to compute a few of the largest or smallest eigenvalues. (See note i.)

540

7.2-18

Subparameter for ERROR:

IERROR is an integer variable which receives a value indicating whether certain errors occurred during the solution of the eigensystem. See section 2.D below.

Subparameter for SUBR:

USUB is a user-supplied subroutine with the following parameter list:

USUB (SUBRNO, NM, N, AR, AI, WR, Wl, ZR, ZI, MM, M, RLB, RUB, EPSI, SELECT, IDEF, SMLSTV, IERROR, LOW, UPP, BND, D, E, E2, IND, INT, ORTR, SCALE, TAU, ORTI, MII, NV, MB, BR, DL, ALPHAR, ALPHAI, BETA).

The keyword parameter SUBR (USUB) may be added to any EISPAC call. (Note that USUB must be mentioned in an EXTERNAL statement in the calling program.) USUB will be called before execution begins and after execution of each numbered routine in the path determined by the parameters to EISPAC and defined in the "EISPAC Eigensystem Path Chart" (i); the number of the routine (zero before execution begins) is passed by the integer variable SUBRNO. USUB may be used to examine intermediate results, to obtain timing information, etc.; its use is quite analogous to that of the procedure "INFORM" described by Rutishauser ~5). For the meanings of the parameters it receives, and appropriate dimensions for those requiring them, see (i), (2), and section 2.3.7 of (6).

Note I: Computing a Few of the Largest or Smallest Eigenvalues.

The recommended procedure for computing a few of the extreme eigenvalues of a real symmetric or complex Hermitian matrix is by appropriate specification of the subparameters MII and M to VALUES. Alternatively, the rational QR method may be employed, although it has proven less stable numerically. If the rational QR method is selected and you know that the matrix is positive (negative) definite, you may indicate so by adding the subparameter 'POSITIVE DEFINITE' ('NEGATIVE DEFINITE') to MATRIX, e.g.,

541

7.2-19

MATRIX ('REAL', ST, ~SYMMETRIC', 'TR!DIAGONAL' 'POSITIVE DEFINITE'), METHOD ('RATQR'), VALUES (W, M, 'SMALLEST').

Computational economy results only when the largest (smallest) eigenvalues of a negative (positive) definite matrix are sought.

Note that subparameter W to VALUES must be of dimension at least N, if the rational QR method is used, even though only M eigenvalues are requested.

Note 2: ~HERM!TIAN' for Real Matrices.

For a real matrix, are synonymous.

~HERMiTIAN' and 'SYMMETRIC'

Note 3: EPSI as a Subparameter to VALUES.

EPSI is a long precision real variable which supplies an absolute error tolerance for the computed eigenvalues when only a few eigenvalues (or a few eigenvalues and their corresponding eigenvectors) are being calculated for the standard or generalized real symmetric problems; or for the non-symmetric generalized problem where all eigenvalues and possibly eigenvectors are being found. If the input value of EPSI is non- positive, a suitable default value, which is related to the machine precision and the norm of the matrix, is used in place of EPSI; this same default is used if EPSI is not supplied to EiSPAC. The input value, if any, of EPSI is not altered when the default value is employed; however, for the standard problem only, the (last) default value used may be examined by means of a user subroutine supplied as the subparameter to SUBR (see above). To supply EPSI to E!SPAC, substitute for the recommended call to VALUES: VALUES (W, MM, M, RLB, RUB, EPSI) or VALUES (ALPHAR, ALPHAI, BETA, EPSI) as appropriate.

If eigenvalues only (no eigenvectors) are being computed, EPSI may be used to control the trade- off between computation time and absolute accuracy of the computed eigenvalues, if less (or more) accuracy than that given by the default value of EPSI is required.

542

7.2-20

If eigenvalues and their corresponding eigenvectors are being computed, extreme care must be taken in choosing a value for EPSI other than the default, since if EPSI is too large, the eigenvectors may be poor because the eigenvalues are not sufficiently accurate; whereas if EPSI is smaller than necessary for convergence, the additional accuracy of the computed eigenvalues will not increase the accuracy of the eigenvectors. For further discussion, or in case of difficulty, see section 2.3.3 of (6), and also the NATS subroutine documents for F223 TINVIT, F294 BISECT, F237 TRIDIB, and F239 QZIT (2).

Note 4: Class of Non-Symmetric Tridiagonal Matrices for which Eigenvectors may be Found.

The class of real non-symmetric tridiagonal matrices for which eigenvectors can be computed is somewhat more restricted than that for which eigenvalues can be found. For the eigenvector computation to be successful, not only must the products of corresponding off-diagonal elements all be non-negative, but also when such a product is zero~ the corresponding off-diagonal elements must both be zero.

Note 5: 'UNITARY' for Real Matrices.

For a real matrix, 'UNITARY' and 'ORTHOGONAL' are synonymous.

Note 6: Symmetric Band Matrices of Half Bandwidth 2.

If MB is specified as 2 for a real symmetric band matrix, EISPAC selects the same subroutines as if 'TRIDIAGONAL' had been specified as a subparameter to MATRIX.

Note 7: Generalized Problem Matrix Subparameters.

As discussed earlier, for a problem to be classified "Real Symmetric Generalized", the A and B input matrices must each be symmetric with B positive definite. Unless 'SYMMETRIC' is specified as a subparameter to MATA and both 'SYMMETRIC' and 'POSITIVE DEFINITE' are specified as subparameters to MATB, EISPAC will select a path corresponding to the real non-symmetric generalized case instead (and assume storage of the full A and B matrices).

543

7.2-21

Note 8: Eigenvalues for the Non-Symmetric Generalized Problem.

The divisions ALPHAR(1)/BETA(1) and ALPHAI(1)/BETA(1) to obtain the real and imaginary parts of the eigenvalues for the real non-symmetric generalized problem are left to the user. The arrays ALPHAR, ALPHAI, and BETA themselves are returned instead, because they have more information than the quotients when B (or both A and B) is nearly singular. Indeed, if B is singular, at least one element of BETA will be zero and division dare not be attempted.

Note 9: Negation and Abbreviation of Alphanumeric Subparameters.

Any alphanumeric subparameter (e.g., 'BALANCE') is negated if its immediately preceding subparameter is 'NO', 'NON', or 'NOT' Similarly, the subparameters 'YES', 'IS', 'USE', and 'DO' act as identity alphanumeric subparameters. These conventions are useful when you desire to use a single EISPAC call to compute the eigensystem of a matrix which sometimes is to be balanced and sometimes not, say, since the subparameter 'NO' or 'YES' may be an alphanumeric variable.

Any alphanumeric subparameter may be abbreviated by enough of its initial letters to unambiguously distinguish it from all other alphanumeric subparameters. For protection against ambiguities arising from the future introduction of new alphanumeric subparameters, you should use at least three (perhaps four) letter abbreviations when they exist. The alphanumeric subparameters currently in use are listed below (synonyms are separated by commas, antonyms by hyphens):

DO', 'IS', 'USE ~, 'YES' NO', 'NON', 'NOT' REAL ~ - 'COMPLEX' HERMITIAN' - 'GENERAL' (see note 2) SYMMETRIC' - 'GENERAL' TRIDIAGONAL' - 'FULL' POSITIVE DEFINITE' NEGATIVE DEFINITE' BALANCE' ORTHOGONAL' - 'ELEMENTARY'

~UNITARY' - 'ELEMENTARY' (see note 5) ~AX=LBX', 'AZ=WBZ' 'ABX=LX', 'ABZ=WZ' 'BAX=LX' 'BAZ=WZ' 'LARGEST ~ - 'SMALLEST'

544

7.2-22

As a final example illustrating these concepts, suppose you wish to compute the eigenvalues and eigenvectors of an order N real general matrix without balancing and using orthogonal transformations, with retrieval of the error indicator and calls to a user subroutine, in a program with variables dimensioned: A(100,100), WR(100), WI(100), Z(100,100). Then two of several possible calls are:

CALL EISPAC (i00, N, MATRIX ('REAL', A), VALUES (WR, WI), VECTOR (Z), METHOD ('ORTHOGONAL', 'NO', 'BALANCE'), ERROR (IERROR), SUBR (USUB))

CALL EISPAC (i00, N, MATRIX ('NOT', 'COMPLEX', A), METHOD ('USE', 'ORTHOG', 'NO' 'NO' 'NO', 'BALAN'), VALUES (WR, WI), VECTOR (Z), SUBR (USUB), ERROR (IERROR))

(Recall in the last example that keyword parameters can appear in any order in the third parameter position and beyond.)

D. Error Conditions and Returns.

Three types of errors can occur in EISPAC: "decision phase" errors, "execution phase" errors, and "linkage" errors. (See section 3 below.) Decision phase errors arise when EISPAC detects a mistake or inconsistency in the form of the parameters it receives. Execution phase errors are those which it detects during the execution of the eigensystem-package subroutines themselves. Decision phase errors always result in a message describing the error and the further message "EXECUTION CONTINUING" or "EXECUTION TERMINATED" and the appropriate action. Execution phase errors always result in a message describing the error and termination of execution, unless the ERROR keyword was supplied (see below).

Linkage errors may occur either during the decision or execution phases and always cause termination of execution. Linkage error 00 arises when the internal file name EISPACLB has not been associated with a dataset via a DD card or ALLOC command. Linkage error 01 arises when such an association has been made but a requested subroutine or phase of EISPAC cannot be found in the associated dataset. In this case, check that it contains the required eigensystem-package subroutines and the phases of EISPAC. (See sections 3 and 5 below.)

545

7.2-23

You may modify the behavior of EiSPAC when an execution phase error is detected by supplying the ERROR keyword. When it is supplied, its subparameter IERROR is set to a value characterizing the error and return is made to the calling program (i.e., execution is not terminated). Furthermore, you may suppress the printing of the error message by setting IERROR to the value -755 870 989 before calling EISPAC.

A non-zero value of IERROR on return from EISPAC indicates that an execution phase error has occurred. If IERROR is positive, the computation has been abandoned, and few, if any, useful results have been produced. However, if IERROR is negative, the computation has been continued despite the error(s) and some meaningful results have been produced; use of the ERROR keyword thus permits you to recover these results. The values IERROR may assume and their significance are discussed below. (See also (2) and (6) . )

Value of Error iERROR Msg. No. Significance

None No execution phase errors occurred.

I O0 The calculation of the l-th eigenvalue failed to converge. If the eigensystem of a real or complex general matrix or for a non-symmetric generalized problem was being computed, eigenvalues I+I,I+2,...,N should be correct; otherwise, eigenvalues 1,2,...,I-I should be correct.

N+I 0i For a real non-symmetric tridiagonal matrix, A(I,I)*A(I-I,3) .LT. 0, violating the restriction discussed above. No useful results are produced.

2*N+I 02 For the eigenvectors of a real non-

symmetric tridiagonal matrix, A(I,I) and A(I-I,3) violated the restriction of note 4, above. All eigenvalues, but no eigenvectors, are correct.

546

7.2-24

3*N+I

3"N+2

4*N+I

5*N+I

6*N+I

7*N+I

-I

03

04

None

05

06

07

50

Either: (i) Parameter MM specified insufficient storage to hold all of the eigenvalues in the interval (RLB,RUB). The only useful result is M, which contains the number of eigenvalues which lie in the interval.

multiplicity at index MII. useful results are produced.

Or: (2) It is not possible to compute exactly M eigenvalues (starting from the Mll-th) because of exact

No

It is not possible to compute exactly M eigenvalues (starting from the Mll-th) because of exact multiplicity at index MII+M-I. No useful results are produced.

Not used in EISPAC.

The M largest or smallest eigenvalues were being computed by the rational QR method and the I-th eigenvalue failed to converge. All eigenvalues probably have some accuracy, but no stronger statement can be made.

The M largest or smallest eigenvalues were being computed by the rational QR method, the matrix was specified negative or positive definite, but the computation suggests it may not be; try again omitting the definiteness specification. No useful results are produced.

The eigensystem for a real symmetric generalized problem was being computed and the matrix supplied to MATB was not positive definite. No useful results are produced.

The calculation of one or more eigenvectors including the l-th failed to converge. All eigenvalues and the non-zero eigenvectors are correct.

547

7.2-25

-(N+I) None Both error 50 above and error 52 below occurred.

2*N+I) 52 Parameter MM specified insufficient columns to hold the selected eigenvectors. All eigenvalues and the first MM columns of (ZR, ZI) or Z are correct.

3*N+I) None This error predicts that error 02 above will occur. It will not normally be returned from EISPAC but may be observed when the user subroutine is emp!oyed.

In addition to the above errors which are diagnosed by EISPAC, other errors may produce System/360-370 completion codes (SCC). The most commonly produced completion codes and their meanings in conjunction with EISPAC are the following:

804 There was not enough storage to dynamically load a requested subroutine. Provide more storage (region), reduce the size of the eigenproblem being solved, or choose a path which requires less temporary storage (see (I) and (6)). The minimum storage requirement for EISPAC is approximately 22,000 (decimal) bytes on System/360-370.

606 Same as SCC804 above.

80A There was not enough storage to allocate a temporary vector or matrix~ See suggestions under SCC804 above.

E. Applicability and Restrictions°

EiSPAC is applicable to the solution of the standard and generalized eigensystem problems for the classes of matrices for which examples are given above. For further details on applicability, see (6), or consult the "EISPAC Eigensystem Path Chart" (I) to determine which subroutines are used in the path of interest and then the NATS subroutine documents (2) for those subroutines.

548

7.2-26


EISPAC consists of three major parts, the parameter- interpreter phase, the decision phase, and the execution phase, which are co-ordinated by a supervisor. The supervisor employs brief assembly language routines to count the number of subparameters supplied to each of the keywords and the number of parameters supplied to EISPAC itself. It then loads the parameter-interpreter phase dynamically and passes the parameter information to it.

The parameter-interpreter phase analyzes the parameters, checks them for consistency, supplies defaults for omitted optional parameters, and produces a characterization of the problem they specify. It returns this characterization and a standardized list of parameters to the supervisor.

If errors have been detected in the parameter-interpreter phase, the supervisor loads an error message module dynamically which prints error messages and which may terminate execution. Otherwise, the supervisor loads a decision phase appropriate to the problem being solved and passes the characterization to it. The decision phase determines the "path", or sequence, of eigensystem-package subroutines and auxiliary actions (e.g., temporary storage allocations) needed to solve the specified eigenproblem. It then returns a representation of this path to the supervisor.

The supervisor then calls the execution phase, which interprets the representation of the path (and information about order of execution) to load dynamically the required eigensystem subroutines and to allocate and free needed temporary storage. (Loading, allocating, and freeing are performed by operating system requests contained in brief assembly language routines.) When execution is complete, or as soon as a fatal error occurs, the execution phase returns to the supervisor. If execution phase errors have occurred and error messages are to be printed (see section 2.D above), the supervisor loads the error message module dynamically and prints them; execution terminates or continues as described above. When execution continues, the supervisor returns the results of the computation to the calling program.

Certain economies of execution are possible when EISPAC is called repeatedly to solve the same eigenproblem. After the first execution of the path for the problem, usable copies of the eigensystem-package subroutines for it may remain in memory (if sufficient storage is available), and if so they are reused without being reloaded on subsequent executions of the path.

549

7.2-27

The design and implementation of EISPAC are highly modular, so that additional subroutines and paths can be added relatively easily and with only a minimum of disturbance to existing paths. This modular design of EISPAC and the philosophy behind it are discussed in detail in (7).

4. REFERENCES~

i)

2)

Boyle, J~M., Hauser, C.H., and Rothaar, H.R., EISPAC Eigensystem Package Path Chart, Release 2, Argonne National Laboratory, Applied Mathematics Division, February, 1975.

NATS Project, Eigensystem Subroutine Package (EISPACK), Subroutines F269 to F298 and F220 to F247.

3) Wilkinson, J.H. and Reinsch, C., Handbook for Automatic Computation, Volume II, Linear Algebra, Springer-Verlag, (i97i).

4) Wilkinson, J.H., The Algebraic Eigenvalue Problem, Oxford, Clarendon Press (1965).

5) Rutishauser, H., Interference With an Algol-Procedure, Annual Review in Automatic Programming, Vol. 2 (R. Goodman, Ed.), Pergamon Press, (1961).

6) This publication. (Reference retained to resolve User Guide pointers, thus enabling compatibility with distributed documentation.)

7) Boyle, J.M. and Grau, A.Ao, Modular Design of a User- Oriented Control Program for EISPACK, Applied Mathematics Division Technical Memorandum No. 242, Argonne National Laboratory, Argonne, Illinois 60439, November 1973.

5. PROGRAM STATISTICS.

A. Additional Entry Point Names in EISPAC.

The entry point names listed below are entry point names in the part of EISPAC loaded with your program. Your program must not include other subroutines or functions having any of these names:

BAND, COREEP, EERMEP, EIDFEP, EISPAC, ERROR, FIDFEP, LINKEP, MATA, MATB, MATRIX, METHOD, SUBR, SUPVEP, VALUES, VECTOR.

550

7.2-28

In addition, the other phases of EISPAC contain entry points with the names DGNHEP, DGSHEP, DIDFEP, DSNHEP, EGNHEP, EGSHEP, ERMSEP, ERSEP, ESNHEP, FIDFEP, IBCMEP, IBCOM#, ICHREP, INTREP, and LKUPEP. These entry points will not, however, conflict with those in your program, since these phases are loaded dynamically.

B. Common Storage.

None.

C. Space Requirements.

The parts of EISPAC loaded with your program (subroutine EISPAC and the supervisor) require 2738 (HEX) = 10040 (DECIMAL) bytes under FORTRAN H, OPT=2, Release 21.7 of 0S/360. However, EISPAC requires an additional amount of storage for the dynamically loaded subroutines and the temporary arrays some of them require. At a minimum, this requirement is 2EA0 (HEX) = 11936 (DECIMAL) bytes for the parameter- interpreter phase of EISPAC. During execution, up to 3100 (HEX) = 12544 (DECIMAL) bytes are required for the appropriate execution phase of EISPAC and a typical EISPACK subroutine, plus whatever additional storage is needed for dynamically allocated temporary arrays. See (I) and (2) for further information for estimating this dynamically-determined amount of storage.

6. CHECKOUT.

A. Test Cases.

EISPAC has been tested on the same matrices as have the separate EISPACK subroutines. See Section 3 -- "VALIDATION OF EISPACK".

B. Accuracy.

The accuracy of EISPAC depends directly upon the subroutines used from the EISPACK package (2). Consult the path chart (i) to learn which subroutines have been selected, and then reference the separate accuracy statements that apply to these subroutines.

551

ebooksclub.org matrix eigensystem routines eispack guide lecture notes in computer science vol 6

Documents

new subroutines

eispack i

eispack subroutines

eispack eigensystem

applicability of eispack

set of subroutines

set of additional subroutines

new problem classes