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 • J. J. Dongarra B. S. Garbow. Y. Ikebe • V. C. Klema C. B. Moler

Matrix Eigensystem Routines EISPACK Guide Second Edition I I

I

II III

Springer-Verlag Berlin.Heidelberg. New York 1976

Editorial Board P. Brinch Hansen ° D. Gries • C. M o l e r . 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. Z L Series. QA193. M57 1976 512.9'43' 0285425 76-2662

A M S Subject Classifications (1970): 15A18, 65F15 CR Subject Classifications (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 Berlin. 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, reprinting, re-use of illustrations, broadcasting, reproduction by photocopying machine or similar means, and storage in data banks. Under § 54 of the German Copyright Law where copies are made for other than private use, a fee is payable to the publisher, the amount of the fee to be determined by agreement with the publisher. © by Springer-Vertag Berlin • Heidelberg 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 INTRODUCTION

1

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

i.

Organization

2.

Accuracy

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

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

14

1.2

All eigenvalues

16

1.3

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

17

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

19

1.5

All eigenvalues

21

1.6

Some eigenvalues and corresponding eigenvectors of a c o m p l e x Hermitian matrix . . . . . . . . . . . . . . . . . .

22

1.7

Some eigenvalues

24

1.8

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

26

1.9

All eigenvalues

28

i. I0

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

30

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

32

1.12

All eigenvalues

34

1.13

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

35

Some eigenvalues

37

1.4

I.ii

1.14

of a complex general matrix . . . . . . . . .

of a complex Hermitian

matrix . . . . . . . .

of a complex Hermitian

of a real general matrix

matrix

.......

..........

of a real symmetric matrix

.........

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

1.15

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

39

1.16

All eigenvalues of a real symmetric tridiagonal m a t r i x

41

1.17

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

1.19

All eigenvalues and corresponding eigenvectors of a special real tridiagonal m a t r i x . . . . . . . . . . . . . . . . . . .

48

1.20

All eigenvalues

50

1o21

Some eigenvalues and corresponding eigenvectors of a special real tridiagonal matrix . . . . . . . . . . . . . . . . . . .

52

Some eigenvalues

55

Variations

of a special real tridiagonal m a t r i x

. ,

46

Some eigenvalues of a real symmetric tridiagonal matrix.

....

of a special real tridiagonal matrix . . . .

57

of the recommended E I S P A C K paths . . . . . . . . . . . .

59

2.1

N o n - b a l a n c i n g of complex and real general matrices

2.2

Orthogonal reduction transformations to real Hessenberg form . . . . . . . . . . . . . . . . . . . . . . . . . . . .

62

2.3

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

65

2.4

The rational QR algorithm for finding a few extreme eigenvalues . . . . . . . . . . . . . . . . . . . . . . . . .

68

2.5

The use of T S T U R M as an alternate to BISECT-TINVIT

71

2.6

Elementary similarity transformations for complex general matrices . . . . . . . . . . . . . . . . . . . . . .

.....

.....

74

IMTQLV-TINVIT pairing in paths for partial eigensystems.

2.8

Specification of boundary eigenvalue indices to the bisection process . . . . . . . . . . . . . . . . . . . . . .

78

Packed representations of real symmetric and complex Hermitian matrices . . . . . . . . . . . . . . . . . . . . .

80

Additional 3.1

3.2

information and examples . . . . . . . . . . . . . . . .

.

76

2.7

2,9

3.

43

1.18

1.22

2.

. . .

83

Selecting the eigenvectors of real and complex general matrices . . . . . . . . . . . . . . . . . . . . . . . . . .

84

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

88

VI

3.3

The EPSI parameter

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

91

3.4

Relative efficiencies of computing p a r t i a l and complete eigensystems . . . . . . . . . . . . . . . . . . . . . . . .

95

3.5

D e t e r m i n a t i o n 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.

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

182

for the timing results

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

. .

177

SECTION 5 CERTIFICATION AND A V A I L A B I L I T Y OF EISPACK . . . . . . . . . . . . . . .

185

SECTION 6 DIFFERENCES BETWEEN THE EISPACK SUBROUTINES AND THE HANDBOOK ALGOL PROCEDURES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

188

SECTION 7 DOCUMENTATION AFD SOURCE LISTINGS . . . . . . . . . . . . . . . . . . .

194

i.

E I S P A C K subroutines . . . . . . . . . . . . . . . . . . . . . . . .

196

2.

EISPAC control p r o g r a m

524

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

VII

L I S T OF T A B L E S

i.

Sections

2.

ISUBNO EISPAC

3. 4-6.

Summary

describing

the r e c o m m e n d e d

basic

paths

in E I S P A C K

. . .

v a l u e s and p a r a m e t e r n a m e s for s u b r o u t i n e calls from . . . . . . . . . . . . . . . . . . . . . . . . . . . . . of v a l u e s

107

of I E R R . . . . . . . . . . . . . . . . . . . .

112

E x e c u t i o n times on the I B M 3 7 0 / 1 9 5 at A r g o n n e N a t i o n a l Laboratory . . . . . . . . . . . . . . . . . . . . . . . . . . . at U n i v e r s i t y

130

7-9°

Execution

times

on the I B M 360/75

10-12.

Execution

times

on the I B M 3 7 0 / 1 6 8

at U n i v e r s i t y

13-15.

Execution

times

on the I B M 370/165

at The U n i v e r s i t y

16-18.

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

Illinois.

. .

133

of M i c h i g a n

. .

136

of Toronto.

19-21.

Execution

times

on the CDC 6600 at K i r t l a n d

22-24.

Execution

times

on the CDC

25-27.

E x e c u t i o n times on the CDC 7600 at N a t i o n a l C e n t e r for Atmospheric Research . . . . . . . . . . . . . . . . . . . . . .

6600 at N A S A

Langley

Base

Research

142 . . .

Center.

148

151

times

on the CDC

31-33.

Execution

times

on the CDC 6 4 0 0 / 6 5 0 0

at P u r d u e

34-36.

Execution

times

on the CDC

at The U n i v e r s i t y

37-39.

Execution

times

on the H o n e y w e l l

.

163

40-42.

E x e c u t i o n times on the U n i v a c 1110 at The U n i v e r s i t y of Wisconsin . . . . . . . . . . . . . . . . . . . . . . . . . . . .

166

43-45.

Execution

times

on the D E C P D P - 1 0

169

46-48.

Execution

times

on the A m d a h l

6600/6400 6070

University.

University

at U n i v e r s i t y

. . .

154 .

of Texas.

at B e l l L a b o r a t o r i e s

at Y a l e

470V/6

University

145

Execution

50.

at N o r t h w e s t e r n

Force

139

28-30.

49.

6400

Air

of

13

160

......

of M i c h i g a n

157

.

172

E x e c u t i o n times for the E I S P A C K d r i v e r s u b r o u t i n e s over v a r i o u s c o m p u t e r systems . . . . . . . . . . . . . . . . . . . . . . . .

175

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

176

REFERENCES

i°

Wilkinson, J. H. and Reinsch, C., Handbook for Automatic Computation, Volume II, Linear Algebra, Part 2, Springer-Verlag, New York, Heidelberg, Berlin, 1971.

2.

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

3.

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 Certify and Disseminate Mathematical Software, Proceedings 1972 National ACM Conference, Volume II, Association for Computing Machinery, New York, 1972, pp. 630-635.

4.

Smith, B. T., The NATS Project, A National Activity to Test Software, SHARE SSD 228, October, 1972, item C-5732, pp. 35-42.

5.

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.

6.

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,

7.

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,

and special real tridiagonal matrices.

real symmetric tridiagonal,

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 availability of EISPACK, and describe the major differences between the published Algol procedures in [i] and their Fortran counterparts.

The final section

includes detailed documentation with Fortran listings of each EISPACK subroutine and the document for the control program.

i.i-I Section !.i ORGANIZATION OF THE GUIDE

This guide is organized for the convenience, hopefully, of the user. Material most pertinent to the basic uses of the package and the control program appears in the early sections and references the more detailed and specific information in later sections.

Here follows a brief 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 conditions 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) associated 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 indeed 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. for an introduction to the modularization of EISPACK.)

(See [7]

Consequently,

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

These subroutines must

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

Throughout the re-

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

path.

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

a description of the basic paths and their var-

iations, and a description of the individual subroutines in EISPACK. information about the paths constitutes the remainder of this section while the subroutine documentation is collected in Section 7.

The

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 nonzero 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 subroutine 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 systems 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 corresponding 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 discussed in Section 2.2. To determine the recommended path to solve your particular eigenproblem, 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 Section 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 information 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. indicative timing results. fully in Section 4.)

These are followed by

(Timing considerations are discussed more

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

One of these concerns the types of the

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.

fv2

Thus

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 N M m u s t 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 i n ;

otherwise unpredictable errors will occur.

An example may help clarify the use of ~ using the path described in Section 2.1.13.

and ~ .

Suppose you are

Considering only the parameters

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

W(~),

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.

10

Similarly, M will be set

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 ~ N and ~

is equal to M.

is equal to

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. be to print IERR and stop.

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

Real Special Complexl Complex Real Real Symmetric Real GeneraliHemitianGeneral Symmetric Tridiagonali Tridiagonal

Classification~ All Eigenvalues & Corresponding Eigenvectors

2.1.1

2.1.4

2.1.8

2.1.11

2.1.15

2.1.19

All Eigenvalues

2.1.2

2.1.5

2.1.9

2.1.12

2.1.16

2.1.20

All Eigenvalues & Selected Eigenvectors

2.1.3

2.1.10

Some Eigenvalues & Corresponding Eigenvectors

2.1.6

2.1.13

2.1.17

2.1.21

Some Eigenvalues

2.1.7

2.1.14

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 eigenvectors

(WR,WI) and their corresponding

(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)

IF (IERR .NE. 0) GO TO 99999

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: Wl(r~n), ZR(~,ryn),

Zi(r~m,r~m),

AR(nm,~m), A l ( ~ , n m ) ,

fv1(r~), fv2(~n),

and

WR(nm),

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

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

CALL

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

CALL

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

IF (IERR .NE. 0) GO TO 99999

or~ using driver subroutine CG:

CALL

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

IF (IERR .NE. 0) GO TO 99999

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: Wl(nm),

fv1(r~), fv2(nm),

and

AR(z~n,nm), Al(nm,~),

WR(nm),

fv3(nm).

The array storage required to execute this path is 2N 2 + 5N working precision words~ WR and WI for

fv2

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

fv3;

saved by identifying ~ 1

another N working precision words could be

and

fv2.)

Indicative execution times for this path (run on an IBM 370/195) are .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 substitute elementary for unitary transformations;

16

see Sections 2.2.1 and 2.2.6.

2. i-i0

Section 2.1.3 ALL EIGENVALUES AND SELECTED EIGENVECTORS

To determine all the eigenvalues (ZR, ZI) (those corresponding

OF A COMPLEX GENERAL MATRIX

(WR,WI) and certain eigenveetors

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

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

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)

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

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

IF (IERR .NE. 0) GO TO 99999 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 corresponding 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. zero if a vector fails to converge.)

This path destroys AR and AI.

Suitable dimensions for the arrays are:

WR(nm),

(IERR is also set non-

AR(~,~),

Wl(nJn), ZR(nm,mm), Zl(nm,mm), SELECT(nm),

fvl(nm), fv2(nm), fv3(n~m), fv4(nm),

AI(~,~),

fml(nm,nm), fm2(nm,nm),

and ~ 5 ( n m ) .

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. Variants of this path omit the balancing of the input matrix or substitute elementary for unitary transformations; 2.2.6.

18

see Sections 2.2.1 and

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)

IF (IERR .NE. O) GO TO 99999

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: ZR(n~n,nm), ZI (nm,nm),

fvl (nm),

and

AR(r~n,~), Al(~,r~n), W ( ~ ) ,

fml(2,nm).

The array storage required to execute this path is 4N 2 . 4N working precision words. Indicative execution times for this path (run on an IBM 370/195) are .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)

IF (IERR .NE. 0) GO TO 99999

or, using driver subroutine CH:

CALL

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

IF (IERR .NE. O) GO TO 99999

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:

fvl(nm),

AR(n~n,nm), AI(mm,nm), W(nm),

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

The array storage required to execute this path is 2N 2 + 5N working precision words. Indicative execution times for this path (run on an IBM 370/195) are .005, .022, .14, and 1.0 seconds for sample matrices of order I0, 20, 40, and 80 respectively. Variants of this path substitute the explicit or implicit for the rational QL shift or proceed from a packed form representation input matrix; see Sections 2.2.3 and 2.2.9.

2~

of the

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)

IF (IERR ~NE. 0) GO TO 99999 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 ! M M ,

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 triangle of AI. Suitable dimensions for the arrays are: ZR(~w,~),

ZI(~,~),

AR(~,~),

AI(~,r~n), W ( ~ ) ,

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 ~ T R I X

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

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

Setting it to zero or calling EISPAC without supplying it

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

Further infor-

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 ~ M M ,

the eigenvalues are in ascending order in W.

Note

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

This path preserves the full upper

triangle of AR and the strict upper triangle of AI. Suitable dimensions for the arrays are:

AR(nm,nm),

fv1(nm), fv2(nm), fv3(nm), fv4(nm), fv5(nm), fm1(2,nm),

A l ( n m , ~ ) , W(mm), 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

Indicative execution times for this path (run on an IBM 370/195), when 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 bisection 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) IF (IERR .NE. 0) GO TO 99999 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. path destroys A. Suitable dimensions for the arrays are:

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

26

A(~n,~),

WR(~),

WI(~),

This

2.1-20

The array storage required to execute this path is 2N 2 + 3N working pre cision words and N integer words. Indicative execution times for this path (run on an IBM 370/195) are .019, .I0, .66, and 4.6 seconds for sample matrices of order I0, 20, 40, and 80 respectively. Variants of this path omit the balancing of the input matrix or substitute 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) IF (IERR .NE. 0) GO TO 99999

or, using driver subroutine RG:

CALL RG(NM,N,A,WR,WI,O,DUMMY,iVl,fu2,!ERR) IF (IERR .NE. 0) GO TO 99999

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), W R ( ~ ) ,

WI(~),

fvl (~), and iv1(~) ° The array storage required to execute this path is N 2 + 3N working precision words and N integer words.

(N working precision words could be saved

by using WR or WI for fvl.) Indicative execution times for this path (run on an IBM 370/195) are .012,

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

and 80 respectively.

28

2.1-22

Variants of this path omit the balancing of the input matrix or substitute orthogonal for elementary reduction transformations; see Sections 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) 50

= A(I,J)

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)

IF (IERR .NE. 0) GO TO 99999 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. 2.3.1 for a discussion of the SELECT array.

See Section

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 corresponding 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. also set non-zero if a vector fails to converge.) discussion of the eigenvector packing into Z. Suitable dimensions for the arrays are:

Z (~,mm),

SELECT (nm),

(IERR is

See Section 2.3.2 for a

This path destroys A. A(nm,nm), WR(nm), Wl(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) working precision words, N logical words, and N integer words. Indicative execution times for this path (run on an IBM 370/195), when 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. Variants of this path omit the balancing of the input matrix or substitute orthogonal for elementary reduction transformations; see Sections 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 orthonormal eigenvectors; it leaves A unaltered. Suitable dimensions for the arrays are: and

A(nm,nm),

W(r~), Z(~,nm),

fvi (nm)~ The array storage required to execute this path is 2N 2 + 2N working

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. Indicative execution times for this path (run on an IBM 370/195) are ~007, ~036, .22, and 1.5 seconds for sample matrices of order i0, 20, 40, and 80 respectively. 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 T Q L R A T ( N , W , ~ , I E R R ) IF (IERR 0NE. 0) GO TO 99999

or, using driver subroutine RS:

CALL

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

IF (IERR .NE. 0) GO TO 99999

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: and

A(~,n~),

W(~),

fvi(nm),

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

precision words~ Indicative execution times for this path (run on an IBM 370/195) are .003, .011, ~055, and .33 seconds for sample matrices of order i0, 20, 40, and 80 respectively. 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

To determine the eigenvalues W in an interval extending from RLB to 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)

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

,fv2 ,fv3 ,M,W ,iv2, Z, IERR ,fv4 ,fv5 ,fv6 ,fvf ,fvS)

IF (IERR .NE. 0) GO TO 99999 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))

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 ! M M ,

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. full upper triangle of A.

35

This path preserves the

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)

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 .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. 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, the determination of the eigenvalues and eigenvectors form into a single subroutine,

combine

of the tridiagonal

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

To determine the eigenvalues W in an interval extending from RLB to 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)

IF (IERR .NE. 0) GO TO 99999

or, using EISPAC:

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

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

Setting it to zero or calling EISPAC without supplying it

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

Further

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 ! M M , in W.

the eigenvalues are in ascending order

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:

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

and

A(nm,rm0, W(mm),

fvl (rim),

ivl(mm).

The array storage required to execute this path is N 2 + 5N + M working precision words and M integer words.

37

2.1-31

Indicative execution times for this path (run on an IBM 370/195), 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 Variants of this path substitute the rational QR method for the bisection 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 subdiagonal 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 eigenvectors 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) IF (IERR .NE. 0) GO TO 99999

or, using driver subroutine RST:

CALL RST(NM,N,W,fu2, I,Z,IERR) IF (IERR .NE. 0) GO TO 99999

39

2.1-33

or, using EISPAC:

CALL EISPAC (NM,N ,MATRIX ( vREAL v ,A, TSY~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

course which would otherwise be destroyed.

fvl

preserves A of

EISPAC, however, preserves

only the second column (diagonal elements) of A. Suitable dimensions for the arrays are: and

A(nm,2), W(nm), Z(nm,nm),

fvl (rim)° The array storage required to execute this path is N 2 + 4N working

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.) Indicative execution times for this path (run on an IBM 370/195) are .005,

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

and 80 respectively. A variant of this path substitutes the explicit for the implicit QL shift; see Section 2.2.3.

40

2.1-34

Section 2.1.16 ALL EIGENVALUES 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 subdiagonal 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 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) IF (IERR .NE. 0) GO TO 99999

or, using driver subroutine RST:

CALL RST(NM,N,W,fV2,0,DUMMY,IERR) IF (IERR .NE. 0) GO TO 99999

or, using EISPAC:

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

This path returns the eigenvalues in ascending order. W and

fvl

Copying A into

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:

41

A(nm,2), W(nm), and

fv1(nm).

2.1-35

The array storage required to execute this path is 4N working precision 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.) Indicative execution times for this path (run on an IBM 370/195) are .003, .011,

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

and 80 respectively. Variants of this path substitute the explicit or its rational reformulation 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

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 subdiagonal 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 the eigenvalues W in an interval extending from RLB to 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)

IF (IERR .NE. 0) GO TO 99999

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

Setting it to zero or calling EISPAC without supplying it

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 ! ~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.) Indicative execution times for this path (run on an IBM 370/195), when computing all N eigenvalues and eigenvectors, are .017, .059, .22, and .84 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, 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

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 subdiagonal 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 the eigenvalues W in an interval extending from RLB to 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)

IF (IERR .NE. 0) GO TO 99999

or, using EISPAC:

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

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

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

Setting it to zero or calling EISPAC without supplying it

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

46

Further

2.1-40

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 ~ M M , order in W.

the eigenvalues are in ascending

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:

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

and

A(~n,2), W(mm), fv2(nm),

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.) Indicative execution times for this path (run on an IBM 370/195), 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 discussed in Section 4. Variants of this path substitute the rational QR method for the bisection process or allow the specification of boundary eigenvalue indices instead of an interval to the bisection process; see Sections 2.2.4 and 2.2.8.

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 eigenvectors 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) IF (IERR ~NE. 0) GO TO 99999 CALL

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

IF (IERR .NE. 0) GO TO 99999

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 (nonorthonorma!) eigenvectors;

it leaves A unaltered.

48

Note that a non-zero

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: and

A(nm,3), W(nm), Z(nm,nm),

fvl (rim). The array storage required to execute this path is N 2 + 5N working

precision words. Indicative execution times for this path (run on an IBM 370/195) are .006, .027,

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

and 80 respectively. A variant of this path substitutes shift; see Section 2.2.3.

49

the explicit for the implicit QL

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, has the property that products of pairs of corresponding off-diagonal elements are all non-negative, can be presented to EISPACK as a threecolumn 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)

IF (IERR ~NE. 0) GO TO 99999 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) IF (IERR ~NE. 0) GO TO 99999

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 precision words. Indicative execution times for this path (run on an IBM 370/195) are .003, .012,

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

and 80 respectively. Variants of this path substitute the explicit or its rational reformulation 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

A real tridiagonal 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-! 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 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)

IF (IERR .NE. 0) GO TO 99999 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)

IF (IERR .NE. O) GO TO 99999 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

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

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 ! ~ ,

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 i v l ( ~ ) . The array storage required to execute this path is IIN + M(N+I) working precision words and M integer words. Indicative execution times for this path (run on an IBM 370/195), when computing all N eigenvalues and eigenvectors, are .018, .060, .22, and .84 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, or combine the determination of the eigenvalues and eigenvectors

53

2.1-47

of the s~-mmetrized matrix into a single subroutine; 2.2.7, 2.2.8, and 2.2.5.

54

see Sections 2.2.4,

2.1-48

Section 2.1.22 SOME EIGENVALUES OF A SPECIAL REAL TRIDIAGONAL MATRIX

A real tridiagonal matrix of order N which, although not symmetric, has the property that products of pairs of corresponding off-diagonal elements are all non-negative, can be presented to EISPACK as a threecolumn 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)

IF (IERR .NE. 0) GO TO 99999 EPSI = 0.0 CALl.

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

IF (IERR .NE. 0) GO TO 99999

or, using EISPAC:

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

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

Setting it to zero or calling EISPAC without supplying it

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

Further

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 ~ M M , in W.

the eigenvalues are in ascending order

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

IERRnon-zero and does not compute any eigenvalues. unaltered.

BISECT sets

This path leaves A

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:

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

and

A(nm,3), W(~v~), fv2(nm),

ivl(mm).

The array storage required to execute this path is 8N + M working precision words and M integer words. Indicative execution times for this path (run on an IBM 370/195), when computing all N eigenvalues, are .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. Variants of this path substitute the rational QR method for the bisection process or allow the specification of boundary eigenvalue indices instead of an interval to the bisection process; see Sections 2.2.4 and 2.2.8.

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. to considerations of:

The variant paths are related

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 tridiagonal 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 similarities 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 recommended 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 equilibration 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 eigenvalues 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. time.

Clearly balancing costs some

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

59

It may also happen that

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 ~ B A K

or CBABK2, which transform the eigenvectors

balanced matrix into eigenvectors moved altogether~

of the original matrix, should be re-

To use the control program EISPAC without balancing,

the keyword parameter METHOD with alphanumeric subparameters 'BALANCE'

of the

vNO~,

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

matrix (AR,AI) of order N without balancing,

60

(ZR,ZI) of a complex general the EISPACK path is:

2.2-5

isl = 1 is2 = N

CALL C O R T H ( N M , N , i s l , i s 2 , A R , A I , f v 2 , f v 3 ) CALL C O M Q R 2 ( N M , N , i s l , i s 2 , f v 2 , f v 3 , A R , A I , W R , W I , Z R , Z I , I E R R ) IF (IERR .NE. 0) GO TO 99999

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 isolate 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 eigenvalues

([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 similarities 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 similarities 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. that although the orthogonal subroutines individually

Note, however,

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

fv4

similarities, 'ORTHOGONAL'

for

wherever they appear, substituting the array

ivl.

To use the control program EISPAC with orthogonal

the keyword parameter METHOD with alphanumeric subparameter 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,

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)

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

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

or, using EISPAC:

63

the EISPACK path is:

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.82.1.10 with

fv4(r~)

replacing iv1(r~).

The array storage requirements

are thus decreased by N integer words and increased by N working precision words.

64

2.2-9

Section 2.2.3 THE IMPLICIT AND EXPLICIT QL ALGORITHMS

EISPACK contains two pairs of subroutines plus one unpaired subroutine 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 essentially 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 magnitude, 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), 11 =

ai~i+ 1

=

ai+l, i

i = 1,2,~..,7

10 2i-1,

a.. = 0 lj

i = 1,2,.o.~6 otherwise.

When a tridiagonal matrix is presented so that it is graded increasingly, 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 explicit 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

fvl instead of fv2.

transmitting array parameter

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) IF (IERR .NE. 0) GO TO 99999

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 replacement 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) IF (IERR .NE. 0) GO TO 99999

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 interval determined by the values of the parameters RLB and RUB.

EISPACK

contains an alternate subroutine which can be used, with minor modifications 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 eigenvalues, 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 R A T Q R m i g h t 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 without 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)

IF (IERR .NE. 0) GO TO 99999

or, using EISPAC:

CALL EISPAC(NM,N,MATRIX(~REAL',A,'SYMMETRIC','POSITIVE

DEFINITE'),

VALUES(W,M,'SMALLEST'),METNOD('RATQR'))

fv1(nm),

Suitable dimensions for the arrays are:

A(~m,nm), W(nm),

fv2(~), fv3(r~n), fv4(~),

Note that storage for W and

and

ivl(nm).

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. identified with W and

fv4

The arrays

fvl

and

fv3

may be

respectively, thereby reducing the working

precision storage required to N 2 + 3N words.

70

2.2-15

Section 2.2.5 THE USE OF T S T U R M A S

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 subroutine T S T U R M w h i c h

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. (see Section 2.2.4), I ~ Q L V

Thus paths including RATQR

(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 extending 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)

IF (IERR oNE. 0) GO TO 99999 CALL TINVIT

(NM,N,fvl ,fv2 ,fv3,M,W,ivl ,Z,IERR,fv4 ,fv5,fv6 ,fvf ,fvS)

IF (IERR .NE. 0) GO TO 99999

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 ) IF (IERR ~NE. 0) GO TO 99999 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. tional working precision array that the integer array

Note that one addi-

fvg, dimensioned fvg(~), is required but

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

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

EISPAC with elementary similarities, alphanumeric subparameter

To use the control program

the keyword parameter METHOD with

'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

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

CALL

COMHES(N~.i,N,isT,is2,AR,AI,iv2)

CALL

COMLR2(NM,N,isl,is2,ivl,AR.AI,WR,WI,ZR,ZI,IERR)

IF (IERR .NE. O) GO TO 99999 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 subroutines 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 subroutine 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 CALL

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

LMTQLV(N,fvl,fv2,fv3,W,ivl,IERR,fv4)

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

TINVIT(NM, N,fvl,fv2,fv3,3,W,ivl,Z,IERR,fv4,fv5,fv6,fvF,fv8)

IF (IERR .NE. 0) GO TO 99999 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. enables this option~

Substitution of subroutine TRIDIB for BISECT

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 eigenvalues 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)

IF (IERR .NE. 0) GO TO 99999

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, CALL TRED3 (N, NV,A,fvl

the EISPACK path is:

,fv2 ,fv3)

EPSI = 0.0 CALL BISECT(N,EPSI,fvl

,fv2,fu3,RLB,RUB,MM,M,W,iV2 ,IERR,fu4,fv5)

IF (IERR oNE. 0) GO TO 99999 CALL

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

IF (IERR .NE. O) GO TO 99999 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 Hermitian matrix in packed representation,

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) IF (IERR .NE. 0) GO TO 99999 CALL

HTRIB3(NM,N,A,fml,N,ZR,ZI) 81

of a complex

the EISPACK path is:

2.2-26

or, using EISPAC:

CALL EISPAC(NM,N,MATRIX('COMPLEX',A,A,'HERMITIAN','PACKED~), VALUES(W)~VECTOR(ZR,ZI))

The array storage required to execute this path is 3N 2 + 4N working 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 usersupplied 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 quasitriangular form; the examination of the IERR parameter and intermediate results when using the control program EiSPAC; and a summary of the possible values of IERR and their meanings.

The section concludes with two

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

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. siderations involved in setting SELECT and determining ~

The con-

(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 correspondence 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 eigenvalues 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 ~ N.

Again MM must be set to ~

is the smaller of twice this number and 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)

IF (IERR .NE. 0) GO TO 99999 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 eigenvectors 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 flag corresponding to the second eigenvalue in the pair.

reset the

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 eigenvectors 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 eigenvectors 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 Z R ( ~ , n m )

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 corresponding 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 available.

For most of the subroutines, accuracy is controlled by an internal

variable, MACHEP ("machine epsilon"), whose value reflects the precision of the machine arithmetic and should not be altered.

However, user 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 eigenvalues 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 default value for each submatrix; this default value is MACHEP times the larger (in magnitude) Gerschgorin bound for the eigenvalues of that submatrix.

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 computation 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 particular 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 eigenvector 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 eigensystems with those which compute partial eigensystems. array storage, and accuracy requirements,

Considering timing,

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 for such matrices, and eigenvalue-eigenvector

paths

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.) machine;

Here a factor in the timing is the identity of the

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. storage for a partial set of eigenvectors

is clearly less with TINVIT

than for the complete set of vectors with TQL2. be remembered that working array requirements

However, it must also

for BISECT-TiNVIT exceed

those for TQL2 (of. Sections 2.1.15 and 2.1.17), and further, follows TRED2 for a real symmetric matrix,

Array

that if TQL2

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 could be significantly of the eigenvalues

longer.

timings with RATQR

This owes to the generally poorer accuracy

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

Working array

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. is the variant RATQR-TINVIT the inaccuracies from T I N V I T m a y

The weakest such path

for real symmetric matrices generally due to

of the eigenvalues

(see Section 2.2.4).

Eigenvectors

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 interested 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 computing 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. erties of subroutine BISECT:

It makes use of two prop-

(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

Schur~s Lemma asserts formation which reduces it may be of interest

the existence

any matrix to triangular

to compute

be carried out without

resort

the m a t r i x of the orthogonal to quasi-triangular form because

form.

it retains

of a unitary

similarity

form.

FORM

trans-

For real matrices,

the part of this transformation which can

to complex arithmetic, transformation

Quasi-triangular

that is, to compute

which reduces

a real matrix

form falls short of triangular

2 × 2 blocks on the main diagonal which correspond

to complex conjugate pairs of eigenvalues. The orthogonal

quasi-triangularization

be used in place of the usual decomposition canonical matrix)

and is faster.

AX+XB

PJP

-I

(where J is a Jordan

As an example of its application,

sider the following problem in control is sought which satisfies

of a real matrix can frequently

theory.

con-

Suppose an m × n matrix X

the equation

= C

where A, B and C are real m x m, n × n and m × n matrices If the orthogonal

(upper) quasi-triangularizations

B = VRV T are computed,

and substituted

respectively.

of A T = uLTu T and

into the equation,

then the simpler

equation for Y

LY + YR = E

results where L and R are respectively matrices

and

X = UYV T and E = uTcv.

100

lower and upper quasi-triangular

2.3-19

The columns of Y can now be determined successively by a process of forward 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 immediately 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 orthogonal 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 behavior 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. supplied, EiSPAC behaves instead as follows:

When ERROR(IEPdlOR) is

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 M M m a y

103

be used for the last

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 subparameter 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 action 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 intermediate 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. example corresponds to that in Section 2.3.1.) contain the statements

104

(This

Your driver program must

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

2.3-25

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

Subroutine Call*

532

BAKVEC (NM,N,AR,E,M, ZR,IERR)

509

BALANC (NM,N,AR,LOW,IGH, SCALE)

515

BALBAK (NM,N,LOW, IGH,SCALE,M,ZR)

539

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)

526

BISECT (N,EPSI,D,E,E2,RLB,RUB,MM,M,WR, IND,IERR,-,BND) in other paths

504

CBABK2 (IfM,N,LOW,IGH,SCALE,M,ZR,ZI)

501

CBAL (NM,N~AR,AI,LOW,IGH,SCALE)

507

CINVIT (NM,N,AR,AI,WR,WI,SELECT,MM,M,ZR,ZI,IERR,-,-,-,-)

508

COMBAK (NM,LOW, IGH,AR,AI,INT,M,ZR,ZI)

502

COMHES (NM,N,LOW,IGH,AR,AI,INT)

505

COMLR (NM,N,LOW,IGH,AR,AI,WR,WI,IERR) in path for all values, no vectors (2.1.2), modified

506

COMLR (N,N,LOW,IGH,-,-,WR,WI,IERR) in path for all values, selected vectors (2.1.3), modified

503

COMLR2(NM,N,LOW,IGH,INT,AR,AI,WR,WI,ZR,ZI,IERR)

565

COMQR (NM,N,LOW,IGII,AR,AI,WR,WI,IERR) in path for all values, no vectors (2.1.2)

566

COMQR (N,N,LOW,IGH,-,-,WR,WI,IERR) in path for all values, selected vectors (2.1.3)

564

COMQR2 (NM,N,LOW,IGH,ORTR,ORTI,AR,AI,WR,WI~ZR,ZI,IERR)

567

CORTB (NM,LOW, IGH~AR,AI,ORTR,ORTI,M,ZR,ZI)

563

CORTH'(NM,N,LOW~IGH,AR,AI,ORTR,ORTI)

107

2.3-26

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

Subroutine Call*

519

ELMBAK (NM,LOW, IGH,AR, INT,M,ZR)

510

ELMHES (NM,N,LOW,!GH,AR, INT)

512

ELTRAN (NM,N,LOW,IGH,AR,INT,ZR)

530

FIGI (NM,N,AR,WR,E,E,IERR) in path for all values, no vectors (2.1.20)

531

F!GI (NM,N,AR,D,E,E2~IERR) in paths for some values (2.1.21, 2.1.22)

529

FIGI2 (NM,N,AR,WR,E,ZR, IERR)

516

HQR (NM,N,LOW,IGH,AR,WR,WI,IERR) in path for all values, no vectors (2.1.9)

517

HQR (N,N~LOW,IGH,-,WR,WI,IERR) in path for all values, selected vectors (2.1.10)

514

HQR2 (NM,N,LOW,IGH,AR,WR,WI,ZR,IERR)

523

HTRIBK (NM~N,AR,AI,TAU,M,ZR,ZI)

553

HTRIB3 (NM,N,AR,TAU,M, ZR,ZI)

521

HTRIDI (NM,N,AR,AI,WR,E,E,TAU) in path for all values and vectors (2.1.4)

525

HTRIDI (h~M,N,AR,AI,D,E,E2,TAU) in paths for some values (2.1.6, 2.1.7)

560

HTRIDI (NM~N,AR,AI,WR,E,E2,TAU) in path for all values, no vectors (2.1.5)

552

HTRID3 (NM, N,AR,WR,E,E,TAU) in path for all values and vectors (2.1.4), modified

554

HTRID3 (NM,N,AR,D,E,E2,TAU) in paths for some values (2.1.6, 2.1.7), modified

108

2.3-27

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

ISUBNO Value 561

HTRID3 (NM, N,AR jWR,E ~E2,TAU) in path for all values, no vectors (2.1.5), modified

(not used) 524

IMTQLV IMTQL 1 (N,WR,E, IERR) in certain real tridiagonal path (2.1.20)

538

IMTQLI (N,WR,AR(I, I) ,IERR) in real symmetric tridiagonal path (2. I. 16)

522

IMTQL2 (NM, N, WR, E, ZR, IERR) in certain real tridiagonal path (2.1.19)

537

l~ffQL2 (NM,N,WR,AR(I, I),ZR,IERR) in real symmetric tridiagonal path (2. I. 15)

518

INVIT (NM~N,AR~WR~WI, S E L E C T ~ M M , M 9 ZR~ IERR~ -,-,-)

520

ORTBAK (NM,LOW, IGH, AR, ORTR, M, ZR)

511

ORTHES (NM,N,LOW, IGH~AR,ORTR)

513

ORTRAN (NM, N, LOW, IGH,AR, ORTR, ZR)

540

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

527

RATQR (N, EPS I,D, E, E2,M,WR, IND, BND, TYPE, IDEF, IERR) in other paths

541

TINVlT (NM,N,AR(I,2),AR(I,I),E2,M, WR,IND,ZR, IERR, , , , ,BND) in real symmetric tridiagonal path (2.1.17)

528

TINVIT (NM,N~D~E~E2,MjWR~IND~ZR~IERR, in other paths

543 (not used)

TQLRAT (N,WR, E2, IERR) TQLI

109

, , , ~BND)

2.3-28

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

Subroutine Call*

542

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

536

TRBAKI

557

TRBAK3 (NM,N,NV,AR,M, ZR)

534

TREDI (NM, N,AR,WR,E,E2)

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

in path for all values, no vectors 535

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

533

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

555

TRED3 (N,NV,AR,WR,E,E)

(2.1.13, 2.1.14)

in path for all values and vectors 556

(2.1.13, 2.1.14), modified

TRED3 (N,NV,AR,WR,E,E2) in path for all values, no vectors

559

(2.1.12), modified

TRIDIB (N,EPSI,AR(I,2),AR(I,I),E2,RLB,RUB,MII,M,WR, in real symmetric tridiagonal paths

558

(2.1.11), modified

TRED3 (N,NV,AR,D,E,E2) in paths for some values

562

(2.1.12)

TRIDIB

IND,IERR,BND,-)

(2.1.17, 2.1.18), modified

(N,EPSI,D,E,E2,RLB,RUB,MII,M,WR, IND,IERR, BND,-)

in other paths (not used)

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

SUBROUTINES

EISPAC MESSAGE

i, INi~N

CG,CH,COMLR~ COMLR2,COMQR, COMQR2,HQR, HQR2,1MTQLV, IMTQLI,IMTQL2, RG,RS,RSP,RST, RT,TQLRAT, TQLI,TQL2

00

N+i, 2AiSN

FIGI,FIGI2

Ol

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.

2N+i, 2~iAN

BAKVEC, FIGI2

For a real non-symmetric tridiagonal matrix (aij) , one but

02

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. 3N+I

BISECT, TRIDIB, TSTURM

If BISECT or T S T U R M w a s 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.

03

I12

2.3-31

TABLE 3 (Contd.) SUMMARY OF VALUES OF IERR

IERR

SUBROUTINES

EISPAC MESSAGE

SIGNIFICANCE OF THE ERROR

3N+2

TRIDIB

4N+i, l~i~N

TSTURM

5N+i, l~i_<M

RATQR

05

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.

6N+I

RATQR

06

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.

-i, l~i~N

CINVIT, INVIT, TINVIT

50

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.

-N-i, l~i-
C INV IT, INVIT

04

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.

50,52

113

Both the error above (nonconvergence) and the error below (insufficient storage) occurred with their respective results.

2.3-32

TABLE 3 (Contd.) SUMMARY OF VALUES OF IERR

IERR

SUBROUTINES

-2N-I

CINVIT, INVIT

-3N-i, 2~i~N

FIGI

EISPAC MESSAGE

SIGNIFICANCE OF THE ERROR 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.

52

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 complicated 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 output 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 ~

cussed in Section 2.1 have the values 20 and 3 respectively.

115

and ~

dis-

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. grams depend upon ~

Dimensions for the array variables in the sample proand

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

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 Z. INTERVAL (0,3) AND THE ASSOCIATED ORTHONORMAL EIGENVECTORS SEE SECTION 2.1.13. 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 REAL

A(20,20),W(3),Z(20,3) 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 C C C

READ IN THE REAL SYMMETRIC MATRIX OF ORDER

N

ROW-WISE.

10 READ(5,20) N 20 FORMAT(I4) IF (N .LE. 0) STOP C 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) C 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.)

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 90 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(/11HEIGENVALUE/1X,1PE16.8//14H CORRESPONDING, + 12H EIGENVECTOR/(1X,3E16.8)) 110 CONTINUE GO TO 10 C THERE ARE NO EIGENVALUES IN (0,3). C C 88888 WRITE(6,88100) 88100 FORMAT(43HONO EIGENVALUES OF A IN THE INTERVAL (0,3).) GO TO i0 C HANDLING OF IERR PARAMETER C C 99999 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 Z. SEE SECTION 2.1.13. 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 +

EISPAC(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 C C C

PRINT THE M EIGENVALUES AND CORRESPONDING ARE THERE ANY EIGENVALUES

EIGENVECTORS.

IN (0,3)?

IF (M oNE. 0) GO TO 90 C C C

NO. WRITE(6,80) FORMAT(43HONO GO TO 10

80 C C C

EIGENVALUES OF A IN THE INTERVAL (0,3).)

YES. 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 4 1.875 -0.5 0.375 -0.25 0

1.0 1.0 -i.0

-i.0 -i.0 1.0

-0.5 2.25 -0.25 -0.375

0.375 -0.25 2.125 -0.125

121

-0.25 -0. 375 -0.125 2. 125

3

4

6.57192290E-01

1

NOT ENOUGH SPACE ALLOCATED FOR THE

4 EIGENVALUES IN THE INTERVAL (0,3).

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

ORDER OF THE MATRIX IS

CORRESPONDING EIGENVECTOR -3.69047642E-01 -6.57192111E-01

EIGENVALUE 2.56154823E 00

NUMBER OF EIGENVALUES IN THE INTERVAL (0,3) IS

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

ORDER OF THE MATRIX IS

OUTPUT FROM THE EISPACK SAMPLE PROGRAM PRINTED ON UNIT 6

O

GQ !

CO

3

4

6.57192300D-01

EXECUTION TERMINATED.

EISPAC EXECUTION PHASE ERROR(S)... 03 PARAMETER MM SPECIFIED INSUFFICIENT STORAGE TO HOLD ALL EIGENVALUES IN THE INTERVAL LB TO UB.

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

ORDER OF THE MATRIX IS

CORRESPONDING EIGENVECTOR -3.69048184D-01 -6.57192300D-01

EIGENVALUE 2.56155281D 00

NUMBER OF EIGENVALUES IN THE INTERVAL (0,3) IS

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

ORDER OF THE MATRIX IS

OUTPUT FROM THE EISPAC SAMPLE PROGRAM PRINTED ON UNIT 6

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.

124

It is computed as:

3.0-2

11Azi = max iNi!N

-

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 precision 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). deemed poor.

If ~ is greater than i00, the performance is

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

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 eigenvectors 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 individual 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. for a matrix of different order.

Each column of a table reports times

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.

128

The entries

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

ORDER OF MATRIX SUBROUTINE

N=I0

N=20

N=40

N=60

N=80

Time Unit (See)

.002

.014

.099

.33

°86

17 II

.07 .05

.03 .03

.02 .02

~01 .01

i .46

i .53

i .61

1 .66

I .91

CBAL CBABK2 COMHES COMBAK

o

.

CORTH CORTB

2.3 i,I

2.6 1.3

3,0 1.4

3.0 1.5

2.8 1.3

COMQR2 COMLR2

15 ii

14 i0

!4 9.3

14 9,1

13 8.0

COMQR COMLR

7.7 6.9

5.8 4.9

4.8 3.5

4.4 3.1

3.8 2.6

CINVIT

7.4

5.5

4.3

3.7

3.4

CG (CBAL,CORTH,COMQR2,CBABK2)

18

17

17

17

15

CG (CBAL,CORTH,COMQR)

i0

8.5

7.8

7.5

6.7

PATHS

CBAL,CORTH,COMQR,CINVIT, CORTB~CBABK2

I0+.86M

130

8.5+o34M 7.8+.14M 7.5+.09M 6.6+.06M

4. I-4

TABLE 5 SUMMARY OF EXECUTION TIM~S FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR REAL GENERAL MATRICES MACHINE: IBM 370/195, Fortran H, OPT=2 ARGONNE NATIONAL LABORATORY

ORDER OF MATRIX SUBROUTINE

N= i0

N=20

N=40

N=60

N=80

Time Unit (Sec)

.001

.006

.047

.15

.36

BALANC BALBAK

.40 .17

.13 .07

.05 .03

.03 .02

.02 .02

ELMHES ELTRAN ELMBAK

1 .28 .63

1 .13 .59

i .06 .60

1 .04 .60

i .03 .64

ORTHES ORTRAN ORTBAK

2.6 .72 1.0

2.7 .60 .91

2.7 .54 .83

2.6 .52 .79

2.6 .51 .78

HQR2

19

15

13

12

12

HQR

12

7.9

5.4

4.7

4.2

INVIT

6.3

5.2

4.3

3.9

3.7

RG (BALANC, ELMHES, ELTRAN, HQR2, BALBAK) RG (BALANC,ELMHES,HQR)

20

17

14

14

13

13

9.0

6.6

5.8

5.2

BALANC, ELMHES, HQR, INVIT, ELMBAK ~BALBAK

13+.71M

PATHS

131

9 .0+. 29M 6 .5+. 12M 5.8+. 08M 5.3+. 05M

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 MACHINE: IBM 370/195, Fortran H, OPT=2 ARGONNE NATIONAL LABORATORY

SUBROUTINE

N=IO

ORDER OF MATRIX N=20 N=40 N=60

Time Unit (Sec)

.001

,007

.041

.12

N=80

.27

TREDI TRED2 TRED3 TRBAKI TRBAK3

1

1

1

1

1

1.6 ,98 1.2 .85

1.8 i.i 1.4 I.i

2.0 i.I 1.6 1.3

2.1 1.2 1.7 1.5

2.2 1.2 1.8 1.5

HTRIDI HTRID3 HTRIBK HTRIB3

2.1 2.2 2.3 2.6

2.6 2.8 3.4 4.0

3.0 3.3 4.3 5.1

3.2 3.6 4.9 5.7

3.4 3.8 5.1 6,0

FIGI FIGI2 BAKVEC

13 18 I0

~05 .i0 .05

°02 ~05 ~03

TQL2 IMTQL2

3.4 3,8

3.5 3.8

3.3 3.7

TQLRAT TQLI IMTQLI

1.2 2.1 2.2

.67 1.5 1.6

°36 ,94 1.0

BISECT TRIDiB IMTQLV RATQR

12 12 2.4 2.6

8.1 7.7 1.7 2.2

TINVIT TSTURM

.95 13

5.0 2.2

.01 .03 .02 3.2 3.5

°00 ,02 .01 3.2 3.5

.24 .66 ,73

,18 ,52 ,57

4.9 4.6 I. 1 1.5

3.5 3.3 .77 1.2

2.7 2.5 .60 .93

,64 8.6

~40 5.3

.30 3.8

.30 3.0

5.3 1.7

5.3 1.3

5.3 1.2 I+. 0 9 M I+. 06M

5.3 1.2 i+. 06M i+. 03M

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

I+i .4 M

i+. 5 IM

I+. 17M

i+i. 2M

i+. 40M

I+. 12M

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 8.1

132

4.1-6

TABLE 7 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR COMPLEX GENERAL MATRICES MACHINE:

IBM 360/75, Fortran H, OPT=2 UNIVERSITY OF ILLINOIS

ORDER OF MATRIX SUBROUTINE

N=20

Time Unit (See)

.20

N=40

N=60

N=80

1.6

5.2

12

CBAL CBABK2

.04 .05

.02 .01

.01 .01

.01 .01

COMIIES COMBAK

1 .48

i .52

i .55

1 .55

CORTH CORTB

2.2 1.2

2.3 1.2

2.3 1.2

2.4 1.3

COMQR2 COMLR2

15 7.7

14 6.6

14 6.5

14 6.3

COMQR COMLR

5.7 3.5

4.7 2.4

4.5 2.3

4.4 2.1

CINVlT

3.2

2.4

2.2

2.1

CG (CBAL, CORTH, COMQR2, CBABK2 )

17

17

16

16

CG (CBAL, CORTH, COMQR)

7.9

7.1

6.8

6.7

PATHS

CBAL, CORTH, COMQR, CINVlT, CORTB, CBABK2

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 MACHINE:

IBM 360/75, Fortran H, OPT=2 UNIVERSITY OF ILLINOIS

ORDER OF MATRIX SUBROUTINE

N=20

N=40

Time Unit (Sec)

.063

.49

II ~03

.04 .02

.02 .02

.02 °01

ELMHES ELTRAN ELMBAK

I .05 .65

1 .03 .60

1 .02 .61

i .01 .60

ORTHES ORTRAN ORTBAK

2.5 .78 I.i

2.4 .69 i.i

2.3 .68 I.i

2.3 .67 1.0

HQR2

17

14

14

13

HQR

8.0

5.8

5.2

4.6

INVIT

3.7

3.1

2.9

2.7

18

15

15

14

9.1

6.8

6.2

5.7

BALANC BALBAK

.

N=60

N=80

1.6

3.9

PATHS RG (BALANC,ELMIIES ,ELTRAN, NQR2, BALBAK) RG (BALANC, ELMHES, HQR)

9.1+.22M 6.8+.09M 6.2+.06M 5.7+.04M

BALANC, ELMHES, HQR, INVIT, ELMBAK, BALBAK

134

4. i-8

TABLE 9 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT REDUCE FULL MATRICES TO REAL SYMMETRIC TRIDIAGONAL FORM MACHINE:

IBM 360/75, Fortran H, OPT=2 UNIVERSITY OF ILLINOIS

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.8 .96 1.3 1.2

1 1.9 .93 1.5 1.3

1 1.9 1.0 1.5 1.4

1 2.0 1.0 1.5 1.4

HTRIDI HTRID3 HTRIBK HTRIB3

2.9 3.0 4.1 4.4

3.2 3.3 4.6 5.0

3.4 3.6 5.0 5.5

3.5 3.7 5.1 5.6

FIGI FIGI2 BAKVEC

.01 .01 .02

TQL2 IMTQL2

4.9 5.0

TQLRAT TQLI IMTQLI

.58 1.3 1.2

BISECT TRIDIB IMTQLV RATQR

4.9 5.2 1.3 2.2

TINVIT TSTURM

5.5

• 49

5.0 5.0

4.8 4.9

.00 .01 .01 4.8 4.9

.32 .70 .71

.21 .47 .50

.15 .36 .38

2.7 2.8 .75 1.4

1.8 1.9 .49 .99

1.4 1.5 .38 .79

.34

3.1

.25

2.2

.28

1.7

PATHS RS (TRED2,TQL2) RS (TREDI, TQLRAT) TREDI,BISECT,TINVIT,TRBAKI TREDI,BISECT

6.7 1.4 i+. 33M i+. 24M

CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,TINVlT,HTRIBK HTRIDI,BISECT

6.9 1.3 I+. 1 IM I+. 07M

6.8 1.2 i+. 06M I+. 03M

6.8 i.I I+. 04M I+. 02M

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 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR COMPLEX GENERAL MATRICES MACHINE:

IBM 370/168, Fortran H, OPT=2 UNIVERSITY OF MICHIGAN

ORDER OF MATRIX SUBROUTINE

N=I0

N=20

N=40

Time Unit (Sec)

.008

°070

.57

CBAL CBABK2 COMHES COMBAK

N=60

N=80

2.0

4.7

.08

.03

.01

.01

.01

•07

.03

~01

.01

.01

!

1

1

1

1

• 47

.52

,54

.55

,58

CORTH CORTB

2.3

2.3

2.2

2.2

2.2

1.3

1.3

1.2

1.2

1.2

COMQR2 COMLR2

19 9.1

16 7.7

15 6.5

14 6.3

14 6.1

COMQR COMLR

8.1 4.9

5.9 3.3

4.8 2.3

4.6 2.1

4.3 1.9

CINVIT

4.5

3.0

2.2

2.0

1.9

CG (CBAL, CORTH~COMQR2,CBABK2)

21

19

17

17

16

CG (CBAL,CORTH,COMQR)

Ii

8.1

7.0

6.7

6.4

PATHS

CBAL,CORTH,COMQR,CINVIT, CORTB~CBABK2

1 i+. 58M

136

8.2+.21M 7~O+.09M 6.7+.05M 6o4+.04M

4.1-10

TABLE Ii SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR REAL GENERAL MATRICES MACHINE:

IBM 370/168, Fortran H, OPT=2 UNIVERSITY OF MICHIGAN

ORDER OF MATRIX SUBROUTINE

N=I0

N=20

N=40

N=60

Time Unit (Sec)

.003

.020

.16

.56

BALANC BALBAK

.20 .14

.07 .06

.03 .03

.02 .02

.01 .01

ELMHES ELTRAN ELMBAK

i 12 .56

1 .05 .58

i .02 .59

I .01 .59

1 .01 .60

ORTHE S ORTRAN ORTBAK

2.7 .87 1.4

2.5 .81 1.3

2.4 .78 1.2

2.3 .77 1.2

2.3 .76 1.2

HQR2

23

18

15

15

14

HQR

13

8.8

6.1

5.5

4.9

INVIT

4.7

3.6

2.8

2.6

2.4

25

19

16

16

15

14

9.8

7.2

6.5

5.9

•

N=80 1.4

PATHS RG (BALANC~ELMIIES~ELTRAN~ HQR2,BALBAK) RG (BALANC,ELMHES,HQR) BAL~NC,ELMHES,HQR~INVlT~ ELMBAK, BALBAK

14+.54M

137

9.8+.21M 7.2+.09M 6.5+.05M 5.9+.04M

4.1-11

TABLE 12 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT REDUCE FULL MATRICES TO REAL SYMMETRIC TRIDIAGONAL FORM MACHINE:

IBM 370/168, Fortran H, OPT=2 UNIVERSITY OF MICHIGAN

SUBROUTINE

N=I0

ORDER OF MATRIX N=20 N=40 N=60

N=80

Time Unit (See)

~004

.023

1,2

TRED 1 TRED2 TRED3 TRBAKI TRBAK3

1 1,6 .98 i.i .99

I 1.8 °99 1.3 1.2

i 1.9 1.0 1.5 1.4

1 2.0 1.0 1.5 1.5

i 2.0 1.0 1,5 1.5

HTRIDI HTRID3 HTRIBK HTRIB3

2.8 2.7 3.3 3.4

3.1 3.1 4.3 4.5

3.4 3.5 5.0 5.2

3.6 3.6 5.2 5.4

3.7 3.7 5.3 5.5

FiGI FIGI2 BAKVEC

.09 ,12 .i0

.03 .04 .05

TQL2 IMTQL2

5.4 5.4

5.8 5.5

TQLRAT TQLI IMTQLI

1.2 2,3 2,3

.66 1.4 1.5

BISECT TRIDIB IMTQLV RATQR

8.0 8.4 2.4 2.8

TINVIT TSTUPd<

.16

.01 .02 .03 5.7 5.6

.50

.00 ,01 .02 5.6 5.3

,00 .01 .02 5.4 5.3

.34 .81 .83

.22 .55 .56

.16 ,42 .42

4.9 5.0 1.5 2,1

2.7 2.7 .85 1.4

1.8 1.8 .57 1.0

1.4 1.4 .44 ,80

.86 8,8

.54 5.3

.31 2.9

.23 2.0

°26 1.6

7.0 2.2 I+I.0M I+. 80M

7.6 1,7 i+. 34M I+. 24M

7.6 1.3 i+. IIM i+. 07M

7.6 1.2 I+.06M I+. 03M

7.4 1.2 1+. 04M I+. 02M

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

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 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR COMPLEX GENERAL MATRICES MACHINE:

IBM 370/165, Fortran H Extended, OPTIMIZE(2) THE UNIVERSITY OF TORONTO

ORDER OF MATRIX SUBROUTINE

N=I0

N=20

N=40

N=60

N=80

Time Unit (Sec)

.006

.043

.39

1.5

4.0

.06

.03 .02

.02 .02

.01

1 .62

1 .71

1 .98

CBAL CBABK2

-

COMHES COMBAK

1 1

CORTH CORTB

2 1

2.2 1.2

2.0 I. 1

1.9 .95

1.7 .85

COMQR2 COMLR2

17 ii

16 9.3

13 7.5

12 6.5

i0 5.9

COMQR COMLR

8 6

5.9 4.1

4.3 2.7

3.7 2.2

3.2 1.9

CINVIT

7

4.8

3.3

2.6

2.5

-

-

1 .53

.01

PATHS CG (CBAL,CORTH,COMQR2,CBABK2)

20

18

15

13

12

CG (CBAL,CORTH,COMQR)

ii

8.2

6.4

5.6

4.9

CBAL,CORTH,COMQR,CINViT, CORTB,CBABK2

10+.8M

139

8.2+.30M 6.4+.IIM 5.6+.06M 4.9+.04M

4.1-13

TABLE 14 SUMY~RY OF EXECUTION TIMES FOR THE E!SPACK SUBROUTINES INCLUDED IN THE PATHS FOR REAL GENERAL MATRICES MACHINE:

IBM 370/165, Fortran H Extended, OPTIMIZE(2) THE UNIVERSITY OF TORONTO

ORDER OF MATRIX SUBROUTINE

N=20

N=40

N=60

Time Unit (Sec)

.016

.12

.43

-

.05

.03

.02

-

.03

.02

.02

BALANC BALBAK

N=80 i.i

1

1

1

1

-

.07

.04

.03

.62

.63

.66

.80

ORTHES ORTRAN ORTBAK

2.3 •83 1.2

2.4 .75 I.i

2.2 .71 i.i

2.1 .64 .95

HQR2

16

15

13

ii

HQR

8.5

5.9

4.9

4.1

INVIT

4,2

3.7

3.1

2,8

18

16

14

12

9.1

6.8

5.9

5.1

ELMHES ELTRAN ELMBAK

PATHS RG (BALANC, ELMHES, ELTRAN, HQR2, BALBAK) RG (BALANC, ELMHES, HQR)

9.5+.24M 7.0+.IIM 5.9+.06M 5.1+.05M

BALANC, ELMHES, HQR, INVIT, ELMBAK, BALBAK

140

4.1-14

TABLE 15 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT REDUCE FULL MATRICES TO REAL SYMMETRIC TRIDIAGONAL FORM MACHINE:

IBM 370/165, Fortran H Extended, OPTIMIZE(2) THE UNIVERSITY OF TORONTO

SUBROUTINE

N=I0

ORDER OF MATRIX N=20 N=40 N=60

Time Unit (Sec)

.003

.017

TREDI TRED2 TRED3 TRBAKI TRBAK3

i 2 I i i

i 1.7 .92 1.5 i.i

i 1.9 1.0 1.6 1.3

i 2.0 1.0 1.7 1.3

1 2.0 1.0 1.6 1.3

HTRIDI HTRID3 HTRIBK HTRIB3

2 3 3 4

2.7 2.7 3.7 4.0

3.1 3.2 4.7 5.1

3.6 3.4 5.0 5.1

4.1 3.5 5.5 5.1

FIGI FIGI2 BAKVEC

.ii

-

.04 .03

TQL2 IMTQL2

4 4

4.8 4.9

TQLRAT TQLI IMTQLI

2 2 2

.80 1.5 1.7

BISECT TRIDIB IMTQLV RATQR

i0 9 3 2

TiNVIT TSTURM

i i0

4.7 4.8

.35

.01 .03 .02 4.8 4.7

N=80 .84

.00 .02 .02 4.4 4.6

.42 .92 .96

.27 .61 .63

.19 .46 .47

6.7 6.5 1.7 2.3

3.9 3.8 .98 1.6

2.6 2.6 .64 i.i

1.9 1.9 .48 .86

.76 7.3

.42 4.2

.30 2.9

.30 2.2

6.8 1.8 i+. 45M i+. 34M

6.6 1.4 I+. 15M i+. 10M

6.7 1.3 i+. 08M i+. 04M

6.3 1.2 i+. 05M i+. 02M

PATHS RS (TRED2,TQL2) RS (TRED i, TQLRAT) TREDI,BISECT,TINVIT,TRBAKI TREDI,BISECT

6 3 i+ 1 .2M I+i. 0M

CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,TINVIT~HTRIBK HTRIDI,BISECT

ii 4 4+i. 4M 4+1.0M

141

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

4.1-15

TABLE 16 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR COMPLEX GENERAL MATRICES MACHINE: Burroughs 6700, Fortran IV (2.6) UNIVERSITY OF CALIFORNIA~ SAN DIEGO

ORDER OF MATRIX SUBROUTINE

N=I0 .27

Time Unit (Sec)

N=20

N=40

N=60

2.1

17

59

CBAL CBABK2

. i0

.04 .02

°02 .01

.01

.05

COMHES COMBAK

i .58

1 .56

1 .59

I .59

CORTH CORTB

1.7 .92

1.6 1.0

1.6 .99

1.6 .94

COMQR2 COMLR2

13 8.6

Ii 7.9

i0 6.8

9.6 6.8

COMQR COMLR

5.0 4.3

3.9 3.1

3.3 2.4

3.1 2.3

CINVlT

3.3

2.6

2.3

2.2

CG (CBAL~CORTH,COMQR2,CBABK2)

14

13

12

Ii

CG (CBAL,CORTH, COMQR)

6.7

5.6

4.9

4.6

.01

PATHS

CBAL~CORTH,COMQR~CINVIT, CORTB~CBABK2

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 REAL GENERAL MATRICES MACHINE: Burroughs 6700, Fortran IV (2.6) UNIVERSITY OF CALIFORNIA, SAN DIEGO

ORDER OF MATRIX SUBROUTINE

N=I0

N=20

Time Unit (Sec)

.095

.79

BALANC BALBAK

.18 .08

.06 .04

.03 .02

.02 .01

ELMHES ELTR2uN ELMBAK

1 .17 •57

1 .07 .58

i .04 .59

1 .03 .60

ORTHES ORTRAN ORTBAK

1.7 .83 i.i

1.7 .70 .99

1.6 .66 .94

1.7 .66 1.0

HQR2

12

9.9

8.9

8.8

HQR

6.3

4.3

3.6

3.1

INVIT

3.1

2.4

2.1

2.1

14

11

I0

9.9

7.8

5.4

4.5

4.3

N=40

N=60

6.3

20

PATHS RG (BALANC,ELMHES,ELTRAN, HQR2,BALBAK) RG (BALANC, ELMHES, HQR) BALANC, ELMHES, HQR, INVIT ELMBAK, BALBAK

7.5+. 38M 5.4+. 15M 4.6+. 07M 4. i+. 04M

143

4.1-17

TABLE 18 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT REDUCE FULL MATRICES TO REAL SYMMETRIC TRIDIAGONAL FORM MACHINE: Burroughs 6700, Fortran IV (2.6) UNIVERSITY OF CALIFORNIA, SAN DIEGO ORDER OF MATRIX N=20 N=40 N=60

SUBROUTINE

N=IO

Time Unit (Sec)

.093

~56

TRED i TRED2 TRED3 TRBAKI TRBAK3

i 1.6 .77 I.I I.i

HTRIDI HTRID3 HTRIBK HTRIB3

2.5 2.4 3.5 3.7 .05 .12 .09

FIGI FIGI2 BAKVEC TQL2 IMTQL2

4.2 4.4

TQLRAT TQLI IMTQLI

.77 i.I 1.2

BISECT TRIDIB IMTQLV

HATQR

3.7 4.1 i. 1 1.4

TINVlT TSTURM

5.0

.68

4.1

13

1 1.9 .82 1.5 1.4

1 2.0 .76 1.6 1,5

I 2.2 .80 1.8 1.6

2.9 2.8 4.6 4.9

3.1 3.0 5.1 5.1

3.1 3.1 5.3 5.3

.01 ,05 .06 4,7 5.1

.00 .03 .03 4.6 4.8

.00 .02 .02 4.7 5.2

.38 .68 .69

.19 .36 .37

.13 .25 .25

2.1 2.5 .61 I.I

I.I 1.2 .31 .62

,73 .83 .22 ,46

o43

3.0

.24

1.5

.19

i.I

PATHS RS (TRED2,TQL2) RS (TREDI,TQLRAT) TREDI,BISECT,TINVlT,TRBAKI TREDI~BISECT CH (HTRIDI,TQL2,HTRiBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,TINVIT,HTRIBK HTRIDI,BISECT

5.8 1.5 I+. 55M I+. 37M

6.9 1.3 i+. 20M i+. IIM

6.6 i.I I+. 07M i+. 03M

6.9 i.i I+. 04M I+.01M

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 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR COMPLEX GENERAL MATRICES MACHINE:

CDC 6600, FTN (4.2) Compiler KIRTLAND AIR FORCE BASE

ORDER OF MATRIX SUBROUTINE Time Unit (Sec)

N=40 .52

N=50

N=60

N=70

N=80

1.0

1.8

2.8

4.2

CBAL CBABK2 COMHES COMBAK

1 .72

1 .57

1 .55

1 .56

1 .56

CORTH CORTB

2.8 1.0

2.6 .96

2.7 .93

2.7 .95

2.7 .97

COMQR2 COMLR2

14 7.5

12 6.9

12 6.6

12 6.5

12 6.6

COMQR COMLR

4.9 3.1

4.5 2.7

4.3 2.5

4.2 2.4

4.2 2.4

CINVIT

2.6

2.3

2.2

2.2

2.2

CC (CBAL,CORTH,COMQR2,CBABK2)

16

15

15

14

15

CC (CBAL,CORTH,COMQR)

7.8

7.1

6,9

6.8

7.0

PATHS

CBAL,CORTH,COMQR,CINVIT, CORTB,CBABK2

7.7+.09M 7.1+.07M 6.9+.05M 6.8+.04M 6.9+.04M

145

4.1-19

TABLE 20 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR REAL GENERAL MATRICES MACHINE:

CDC 6600, FTN (4.2) Compiler KIRTLAND AIR FORCE BASE

ORDER OF MATRIX N=40

N=50

N=60

N=70

N=80

.25

.49

.80

1.4

2.0

ELMHES ELTRAN ELMBAK

1

1

1

1

1

.46

.59

°59

.61

°58

0RTHES ORTRAN ORTBAK

2.6

2.6 •81 1.2

2.5

1.2

2.6 .81 1.2

1.2

1.2

HQR2

12

12

12

ii

i0

HQR

5.1

4.9

4.6

4.0

3.8

INVIT

2.8

2.7

2.7

2.5

2.4

13

13

13

12

12

6.1

5.7

5.7

5.0

4.7

SUBROUTINE Time Unit (Sec) BALANC BALBAK

•9 2

.76

2.5 .75

PATHS RG (BALANC, ELMHES, ELTRAN, HQR2, BALBAK) RG (BALANC, ELMHES, HQR) BALANC, ELMHES ,HQR, INVIT, ELMBAK, BALBAK

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 K I R T L A N D A I R FORCE BASE

SUBROUTINE Time Unit (Sec)

N=40 .19

ORDER OF MATRIX N=50 N=60 N=70 .37

.60

.92

N=80 1.3

TRED 1 TRED2 TRED3 TRBAKI TRBAK3

1 2.2 1.8 1.7 1.9

1 2ol 1.8 1.7 1.9

1 2.1 1.7 1.7 2.0

1 2.2 1.8 1.8 2.1

1 2.2 1.7 1.8 2.0

HTRIDI HTRID3 HTRIBK HTRIB3

2.2 1.9 3.4 3.0

1.9 2.1 3.0 3.1

2.2 2.2 3.5 3.4

2.3 2.3 3.7 3.6

2.1 2.0 3.3 3.4

4.2 4.5

4.0 4.3

4.0 4.4

4.2 4.4

4.0 4.4

FIGI FIGI2 BAKVEC TQL2 IMTQL2 TQLRAT TQLI IMTQLI

.39 •63 .68

.28 .49 .56

.25 .42 .50

.21 .37 .44

.19 .32 .38

BISECT TRIDiB IMTQLV RATQR

6.2 6.0 .76 2.0

4.9 4.8 .62 1.6

4.2 4.2 .54 1.4

3.7 3.6 .47 1.3

3.2 3.2 .42 i.i

TINViT TSTURM

.52 6.6

.40 5.3

.39 4.6

.36 4.1

.40 3.7

6.3 1.4 I+.21M i+. 16M

6.0 1.3 I+. 14M i+. IOM

6.1 1.2 I+. IIM I+. 07M

6.2 1.2 I+.08M i+. 05M

6.2 1.2 I+.07M i+. 04M

PATHS RS (TRED2,TQL2) RS (TREDI,TQLRAT) TREDI,BISECT,TINVIT,TRBAKI TREDI,BISECT 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 . ~ . 1 5 M 2.1+.11M 2.3+.09M 2.I+.07M 2.2+.16M 2 . ~ . I O M 2.1+.07M 2 . ~ . 0 5 M 2.1+.04M

147

4.1-21

TABLE 22 SUMMARY OF EXECUTION TIMES FOR ~IE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR COMPLEX GENERAL MATRICES MACHINE:

CDC 6600, FTN 4.3+P393 Compiler, OPT=I NASA LANGLEY RESEARCH CENTER

ORDER OF MATRIX SUBROUTINE

N=I0

N=20

N=40

Time Unit (Sec)

°009

.063

.54

N=60 1.8

CBAL CBABK2

.24

. i0

.04

.03

• 12

. 04

.01

.01

COMHES COMBAK

I °47

1 .60

1 .62

1 .64

CORTH CORTB

1.8 .88

1.6 .90

1.6 .84

1.6 .79

COMQR2 COMLR2

16 9.9

15 8.0

13 6.9

13 7.0

COMQR COF~R

7.4 5.5

5.9 3.9

4.5 2.8

4.3 2.8

CINVIT

3.8

2.8

2.2

2.1

CG (CBAL,CORTH,COMQR2,CBABK2)

18

17

14

14

CG (CBAL,CORTH,COMQR)

9.5

7.6

6.2

5.9

PATHS

CBAL,CORTH,COMQR,CINVIT, CORTB,CBABK2

9.4+.48M 7.6+.19M 6.2+.08M 5.9+.05M

148

4.1-22

TABLE 23 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR REAL GENERAL MATRICES MACHINE:

CDC 6600, FTN 4.3+P393 Compiler, OPT=I NASA LANGLEY RESEARCH CENTER

ORDER OF MATRIX SUBROUTINE

N--10

N=20

N=40

N=60

Time Unit (Sec)

.006

.032

.24

.77

.27

.17

.07

.05

-

.05

• 03

.02

ELMHES ELTRAN ELMBAK

1

1

1

• 18

°06

.04

.55

.58

.61

1 . 02 .61

ORTHE S ORTRAN ORTBAK

1.8 .91 i.I

2.0 .73 1.3

2.2 .85 1.3

2.2 .82 1.3

HQR2

13

14

14

12

HQR

6.9

6.7

6.2

4.8

INVIT

3.6

3.3

3.1

2.9

14

15

15

13

8.5

7.7

7.2

5.9

BALANC BALBAK

PATHS RG (BALANC,ELMHES,ELTRAN, HQR2,BALBAK) RG (BALANC,ELMHES,HQR) BALANC, E LMHE S, HQR, INVIT, ELMBAK, BALBAK

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 MACHINE:

CDC 6600, FTN 4.3+P393 Compiler, OPT=I NASA LANGLEY RESEARCH CENTER

SUBROUTINE

N=I0

ORDER OF MATRIX N=20 N=40 N=60

Time Unit (Sec)

.006

,030

TREDI TRED2 TRED3 TRBAKI TRBAK3

1 1.6 1.2 1.2 1.2

1 1.8 1.5 1.4 1.5

i 2.0 1.7 1.6 1.8

1 2.0 1.8 1.7 1.7

HTRIDI HTRID3 HTRIBK HTRIB3

1.7 1.8 1.9 1.9

2.1 2.3 2.7 2.7

2.4 2.6 3.2 3.2

2.5 2.6 3.5 3.2

.03 .07 .05

FIGI FIGI2 BAKVEC TQL2 IMTQL2

3.6 3.8

3.8 4.0

TQLRAT TQLI IMTQLI

1.0 1.5 1.6

.58 .95 i.I

BISECT TRIDIB iMTQLV RATQR

15 14 1.5 3.6

TINVIT TSTURM

.19

.01 .02 .04 4.! 4.4

.58

.00 ,01 .02 4.1 4.7

.32 .55 .68

.25 .42 .51

9.2 9.1 1.2 2.8

5.5 5.5 .74 2.0

3.9 3.9 .53 1.5

.91 15

.67 9.7

.44 5.8

.32 4.3

5.5 2.0 I+I.7M I+I.5M

5.8 1.6 I+.56M ~.46M

6.1 1.4 I+.IgM I+.I4M

6.1 1.2 I+.IOM I+.06M

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

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 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR COMPLEX GENERAL MATRICES MACHINE: CDC 7600, Local Compiler NATIONAL CENTER FOR ATMOSPHERIC RESEARCH

ORDER OF MATRIX SUBROUTINE

N=I0

N--20

N=40

N=60

N=80

Time Unit (Sec)

.002

.015

.ii

.38

.89

CBAL CBABK2

-

. i0

.05

.03

.02

-

.05

.01

.01

.01

COMHES COMBAK

1 i

I .57

i .60

1 .61

1 .62

CORTH CORTB

2 1

2.3 i.i

2.3 i.i

2.3 I.i

2.3 i.i

COMQR2 COMLR2

15 i0

15 8.1

13 6.9

13 6.7

13 6.4

COMQR COMLR

7 6

5.8 3.9

4.7 2.8

4.4 2.5

4.3 2.3

CINVlT

4

3.0

2.3

2.2

2.1

18

17

16

15

15

9

8.0

7.1

6.7

6.6

PATHS CG (CBAL,CORTH,COMQR2,CBABK2) CG (CBAL,CORTH,COMQR) CBAL,CORTH,COMQR,CINVIT, CORTB,CBABK2

9+. 5M

151

8.2+. 21M 7. i+. 09M 6.8+. 05M 6.6+. 04M

4.1-25

TABLE 26 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR REAl, GENERAL MATRICES MACHINE: CDC 7600, Local Compiler NATIONAL CENTER FOR ATMOSPHERIC RESEARCH

ORDER OF MATRIX SUBROUTINE

N=I0

N=20

N=40

N=60

N=80

Time Unit (Sec)

• 001

.007

.050

.16

.38

.07 .02

.05 .01

.04 .01

i

BALANC BALBAK

-

-

-

-

ELMHES ELTRAN ELMBAK

1

i

1

1

-

-

.04

.02

.02

I

.55

.60

.60

,60

ORTHES ORTRAN ORTBAK

2 1 1

2.4 .81 1.3

2.5 .78 1.2

2.5 .78 1.2

2.5 .77 1,2

HQR2

18

16

15

14

14

HQR

i0

7.4

5.8

5.2

4.8

4

3.4

3.0

2.8

2.7

20

17

16

15

15

ii

8.6

6.9

6.3

5.8

INVIT

PATHS RG (BALANC, ELMHES, ELTRAN, HQR2, BALBAK) RG (BALANC, ELMHES ,HQR) BALANC~ELMHES,HQR, INVIT, ELMBAK~BALBAK

II+.5M

152

8.4+.20M 6.9+.09M 6.3+.06M 5.8+.04M

4.1-26 TABLE 27 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT REDUCE FULL MATRICES TO REAL SYMMETRIC TRIDIAGONAL FORM MACHINE: CDC 7600, Local Compiler NATIONAL CENTER FOR ATMOSPHERIC RESEARCH

SUBROUTINE

N = I0

ORDER OF MATRIX N=20 N=40 N=60

Time Unit (Sec)

.001

.007

.040

.12

N=80 .28

TREDI TRED 2 TRED3 TRBAKI TRBAK3

i 2 2 I 2

1 1.7 1.8 1.3 1.6

i 1.9 2.8 1.5 2.7

I 2.0 3.2 1.5 3.0

1 2.0 3.4 1.6 3.2

HTRIDI HTRID3 HTRIBK HTRIB3

2 2 2 2

2.1 2.2 2.5 2.6

2.4 2.5 3.1 3.2

2.6 2.6 3.3 3.4

2.6 2.7 3.4 3.5

FIGI FIGI2 BAKVEC

-

.02 .03

TQL2 IMTQL2

3 4

3.4 3.5

TQLRAT TQLI IMTQLI

1

2 2

.69 1.0 1.2

BISECT TRIDIB IMTQLV RATQR

18 17 2 3

TINVIT TSTURM

1 18

3.6 3.8

.01 .01 .02 3.6 3.8

.00 .01 .01 3.5 3.8

.40 .65 .77

.28 .46 .55

.21 .36 .43

II Ii 1.3 2.7

7.0 6.6 .82 1.9

5.0 4.7 .58 1.5

3.9 3.6 .45 1.2

.62 ii

.42 7.2

.32 5.2

.33 4.1

5.1 1.6 i+. 65M i+. 56M

5.5 1.4 i+. 22M i+. 17M

5.6 1.3i+. 11M I+. 08M

5.5 1.2 i+. 07M i+. 05N

PATHS RS (TRED2,TQL2) RS (TREDI,TQLRAT) TREDI~BISECT,TINVIT,TRBAKI TREDI,BISECT

5 2 1+2.0M i+i. 8M

CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI, TQLRAT) HTRIDI~BISECT,TINVIT,HTRIBK HTRIDI~BISECT

8 4 2+2. IM 2+i .8M

153

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

4.1-27

TABLE 28 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR COMPLEX GENERAL MATRICES MACHINE:

CDC 6400, FTN 3.0 Compiler, OPT=2 NORTHWESTERN UNIVERSITY

ORDER OF MATRIX SUBROUTINE

N=I0

N=20

Time Unit (Sec)

.036

.29

19 .08

.07 .03

~03 .01

.02 .01

i .51

1 .54

1 .57

1 .58

CBAL CBABK2 COMHES COMBAK

o

N=40

N=60

2.2

7.5

CORTH CORTB

2.5 1.2

2.4 1.2

2.4 1.2

2.4 1.2

COMQR2 COMLR2

18 9.7

16 7.9

15 6.5

14 6.5

COMQR COMLR

8~.3 5.3

6.2 3.5

5.2 2.5

4.9 2.3

CINVIT

4.1

2.8

2.2

2.0

CG (CBAL,CORTH,COMQR2,CBABK2)

21

19

17

17

CG (CBAL,CORTH,COMQR)

ii

8.7

7.6

7.3

PATHS

CBAL,CORTH,COMQR,CINVIT, CORTB,CBABK2

II+.54M

154

8.7+.20M 7.6+.09M 7.3+.05M

4.1-28

TABLE 29 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES I N C L ~ E D IN THE PATHS FOR REAL GENERAL MATRICES MACHINE:

CDC 6400, FTN 3.0 Compiler, OPT=2 NORTHWESTERN UNIVERSITY

ORDER OF MATRIX SUBROUTINE

N=IO

N=20

N=40

Time Unit (Sec)

.016

.ii

.83

BALANC BALBAK

.31

.14 .05

.06 .02

.04 .01

.03 .01

ELMHES ELTRAN ELMBAK

1

1 .06 .54

1 .03 .57

1 .02 .57

1

15 •53

ORTHES ORTRAN ORTBAK

2.7 .83 1.3

2.8 .77 1.2

2.9 .77 1.2

3.0 .77 1.2

3.0 .77 1.2

HQR2

17

15

14

13

13

HQR

i0

7.2

5.6

5.1

4.7

INVIT

4.2

3.2

2.8

2.6

2.5

RG (BALANC, EI~MHES, ELTRAN, HQR2, BALBAK) RG (BALANC,ELMHES ,HQR)

19

16

15

14

14

Ii

8.3

6.7

6.1

5.7

BALANC, ELMHES, HQR, INVIT, ELMBAK, BALBAK

114-.48M

• 15

•

N=60

N=80

2.7

6.3

.01

.58

PATHS

155

8 .3+. I£M 6.7+. 08M 6. I+. 05M 5.7+. 04M

4.1-29 TABLE 30 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT REDUCE FULL MATRICES TO REAL SYMMETRIC TRIDIAGONAL FORM MACHINE:

CDC 6400, FTN 3.0 Compiler, OPT=2 NORTHWESTERN UNIVERSITY

SUBROUTINE

N=I0

Time Unit (Sec)

•019

ORDER OF MATRIX N=20 N=40 N=60 .ii

.69

2.1

N=80 4.9

TRED 1 TRED2 TILED3 TRBAKI TRBAK3

I

1

i

i

1

1.7 1.2 I.i I.i

1.8 1.3 1.3 1.3

1.9 1.5 1.5 1.5

2.0 1.6 1.5 1.6

2.0 1.6 1.5 1.7

HTRIDI HTRID3 HTRIBK HTRIB3

2.4 2.4 2.6 2.6

2.7 2.7 3.4 3.4

3.0 2.9 4.0 4.0

3.1 3.0 4.3 4.2

3.2 3.1 4.5 4.4

FiGI FIGI2 BAKVEC

.07 .12 .ii

.03 .05 °06

TQL2 !MTQL2

4.2 4.4

4.5 4.7

TQLRAT TQLI !MTQLI

I.i 1.7 2.0

°66 1o2 1.3

BISECT TRIDIB IMTQLV RATQR

9.8 i0 2.0 3.1

TINVIT TSTURM

.01 .02 °03 4.7 4.9

.00 .01 .02 4.7 4.9

.00 °01 .02 4.7 4.9

.36 ~68 .77

.24 .48 .54

.19 .37 .41

6.2 6°2 1.3 2.4

3.5 3.6 °79 1.6

2.5 2.5 .56 1.2

1.9 1.9 .43 .97

.94 II

.61 6.7

.37 3.9

.28 2.8

.31 2.2

5.9 2.1 i+i .2M I+. 98M

6.3 1.7 i+. 40M i+. 31M

6.6 1.4 I+. 13M i+. 09M

6.7 1.2 I+.07M i+. 04M

6.7 1.2 I+.05M i+. 02M

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

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 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR COMPLEX GENERAL MATRICES MACHINE:

CDC 6400/6500, FUN Compiler PURDUE UNIVERSITY

ORDER OF MATRIX SUBROUTINE

N=IO

N=20

N=40

N=60

N=80

Time Unit (Sec)

.045

.35

2.7

9.2

22

CBAL CBABK2

• 13

.05 .03

.02 .01

.01

°01

•07

.01

.01

COMHES COMBAK

1

1

i

1

1

•5 8

.62

.64

•6 5

.66

CORTH CORTB

2.7 1.4

2.7 1.3

2.7 1.3

2.7 1.3

2.7 1.3

COMQR2 COMLR2

20 ii

18 8.7

16 7.4

16 7.1

16 6.7

COMQR COMLR

9.5 5.7

7.4 3.8

6.4 2.7

6.2 2.4

5.8 2.2

CINVIT

3.9

2.9

2.4

2.2

2.2

CG (CBAL, CORTH,COMQR2,CBABK2)

23

20

19

19

18

CG (CBAL,CORTH,COMQR)

12

i0

9.1

8.9

8.5

12+.54M

IO+.21M

PATHS

CBAL,CORTH,COMQR,CINVlT, CORTB,CBABK2

157

9. I+.09M 8.9+.06M 8.5+.04M

4.1-31

TABLE 32 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR REAL GENERAL MATR!CES MACHINE:

CDC 6400/6500, FUN Compiler PUF~UE UNIVERSITY

ORDER OF MATRIX SUBROUTINE

N=I0

N=20

N=40

Time Unit (Sec)

.018

.12

.90

•25 14

• I0 .06

.05 .03

.03 .02

.02 .01

EL~ES ELTRAN EL~b~K

i 17 .55

I .07 .60

1 ,03 .61

i ,02 .62

1 .02 ,63

ORTHES ORTRAN ORTBAK

2.6 .91 1.4

2.7 .83 1.3

2.7 .81 1.3

2,8 .81 1.3

2.8 ,81 1.2

HQR2

33

31

30

30

29

HQR

18

14

12

II

!0

INVIT

5.1

4.9

4.6

4.6

4.6

35

32

31

31

30

19

15

13

12

ii

BALANC BALBAK

•

N=60

N=80

3.0

6.9

PATHS RG (BALANC,ELMIIES,ELTRAN, HQR2,BALBAK) RG (BALANC,ELMHES,HQR) BALANC,ELMHES,HQR, INViT, ELMBAK, BALBAK

19+.58M

158

15+.28M

13+.13M

12+.09M

II+.06M

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

N= i0

Time Unit (Sec)

.024

ORDER OF MATRIX N=20 N=40 N=60 .13

.81

N=80

2.5

5.6

TRED I TRED2 TRED3 TRBAKI TRBAK3

1 1.7 .92 I.I i.i

1 1.8 I.i 1.3 1.4

I 1.9 1.2 1.5 1.6

I 2.0 1.2 1.6 1.7

I 2.0 1.2 1.6 1.7

HTRIDI HTRID3 HTRIBK HTRIB3

2.4 2.6 2.8 3.0

2.8 3.1 3.7 4.0

3.2 3.5 4,5 4.9

3.4 3.7 4.9 5.3

3.5 3.9 5.1 5.5

FIGI FIGI2 BAKVEC

•06

.02

.O l

.0 0

.O 0

. Ii

.05 .05

.02 .03

.01 .02

.01 .02

.09

TQL2 IMTQL2

3.8

4.2

4.4

4.6

4,6

4.0

4.2

4.5

4.5

4.6

TQLRAT TQLI IMTQLI

•83 1.4 1.5

.51 .92 1.0

BISECT TRIDIB IMTQLV RATQR

9.4 9ol 1.7 2.9

TINViT TSTIYRM

.28 .56 .62

.19 .39 .44

.15 .30 .34

6.1 5.9 i.I 2,3

3.6 3.5 .70 1,6

2.5 2.5 .50 1.2

2.0 1.9 .39 .98

.97 i0

.68 6.7

.43 4.0

.33 2.9

.37 2.3

5.4 1.9 i+i. 2M i+. 94M

6,0 1.5 i+. 40M i+. 30M

6.4 1,3 I+. 14M i+. 09M

6.6 1.2 i+. 07M I+. 04M

6.6 I.i i+. 05M i+. 02M

PATHS RS (TRED2,TQL2) RS (TREDI,TQLRAT) TREDI,BISECT,TINVIT,TRBAKI TREDI,BISECT CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,IQLRAT) HTRIDI,BISECT,TINVIT,HTRIBK HTRIDI~BISECT

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 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR COMPLEX GENERAL MATRICES MACHINE: CDC 6600/6400, RUN Compiler THE UNIVERSITY OF TEXAS

ORDER OF MATRIX SUBROUTINE

N=I0

N=20

N=40

Time Unit (See)

.015

.084

.69

~17

.05 .02

I .64

i .64

CBAL CBABK2 COlliES COMBAK

-

-

1 -

-

CORTH CORTB

2.1 I.i

3.0 1.4

2.9 1.3

COMQR2 COMLR2

17 9.5

19 9.8

17 7.8

COMQR COMLR

8.9 5.5

8.9 4.6

7.4 3.1

CINVIT

4.2

3.9

2.9

CG (CBAL,CORTR,COMQR2,CBABK2)

19

22

20

CG (CBAL,CORTH,CO~R)

12

12

i0

19+.53M

12+.26M

10+.IIM

PATHS

CBAL,CORTH,COMQR, CINVIT, CORTB~CBABK2

160

4.1-34

TABLE 35 SITMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR REAL GENERAL MATRICES MACHINE: CDC 6600/6400, RUN Compiler THE UNIVERSITY OF TEXAS

ORDER OF MATRIX SUBROUTINE

N=20

N=40

N=60

Time Unit (Sec)

.045

.24

.78

BALANC BALBAK

-

ELMHES ELTRAN ELMBAK

.06 -

i

1

-

-

.06

N = 8 0

1.8

.02

.05 .02 1 .03 .73

.36

.73

1 .04 .70

ORTHES ORTRAN ORTBAK

2.5 .73 .71

3.5 .79 1.3

3.5 .77 1.2

3.6 .77 1.2

HQR2

28

45

36

36

HQR

12

18

13

13

INVIT

4.7

6.0

6.2

6.4

29

46

37

37

13

19

14

14

13+.25M

19+.17M

14+.12M

14+.09M

PATHS RG (BALANC, ELMHES, ELTRAN, HQR2, BALBAK) RG (BALANC, ELMHES, HQR) B~C,

EI~IHES, HQR, INVIT, ELMBAK, BALBAK

161

4.1-35 TABLE 36 SUMMARY OF EXECUTION TIMES FOR THE EiSPACK SUBROUTINES ~ C L U D E D IN THE PATHS THAT REDUCE FULL MATRICES TO HEAL SYMMETRIC TRIDIAGONAL FORM MACHINE: CDC 6600/6400, RUN Compiler THE UNIVERSITY OF TEXAS

SUBROUTINE

ORDER OF MATRIX N=20 N=40 N=60

N=80

Time Unit (Sec)

°033

1.4

.21

.63

TRED i TRED2 TRED3 TRBAKI TRBA-K3

1 1.9 1.8 1.7 2.0

1 2.1 1.6 1.8 2.1

i 2.1 1.7 1.8 2.2

1 2.1 1.7 1.9 2.3

HTRIDI HTRID3 HTRIBK HTRIB3

2.9 3.5 3.7 4.2

3.1 3.5 4.5 4.9

3.3 3.7 4.8 5.3

3.4 3.9 5.1 5.6

FIGi FiGI2 BAKVEC

-

-

.02

°02

-

-

-

TQL2 IMTQL2

4.4 4.6

4.3 4.8

4.2 4.8

TQLRAT TQLI IMTQL 1

.90 1.2 1.7

BISECT TRIDIB IMTQLV RATQR

12 12 2.3 3.6

TINVIT TSTURM

i.i 13

.39 .84 .92

~02

4.2 4.5

.29 .60 .70

.21 °44 .53

6.8 6.8 I.I 2.5

4.9 4.8 °79 1.9

3.8 3.8 .59 1.5

.64 7.6

.51 5.5

.47 4.3

6.3 1.5 i+. 23M i+. 17M

6.3 1.3 I+. 12M i+. 08M

6.3 1.2 l+. 08M i+. 05M

PATHS 6.5 2.0 i+. 73M i+. 59M

RS (TRED2,TQL2) RS (TREDI, TQLRAT) TREDIgBISECT~TINV!T,T~AKI TREDI,BISECT

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

CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,T!NVlT,HTRIBK HTRIDI,BISECT

162

4.1-36

TABLE 37 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR COMPLEX GENERAL MATRICES MACHINE:

Honeywell 6070 Fortran-Y(SR-F) Optimized BELL LABORATORIES

ORDER OF MATRIX SUBROUTINE

N=I0

N=20

Time Unit (Sec)

.041

.31

CBAL CBABK2

.16 .07

.07 .03

.03 .01

.'02 .01

.02 .01

COMHES COMBAK

i .46

i .54

i .56

1 .55

1 .55

N=40

N=60

N=80

2.5

8.6

20

CORTH CORTB

2.4 I.i

2.5 i.i

2.6 1.2

2.5 I.i

2.5 i.I

COMQR2 COMLR2

14 8.2

13 6.7

ii 5.7

U 5.7

ii 5.4

COMQR COMLR

6.2 4.5

4.7 2.9

3.7 2.1

3.5 2.0

3.4 1.8

CINVIT

4.3

3.1

2.4

2,3

2.2

CG (CBAL,CORTH,COMQR2,CBABK2)

17

15

14

14

13

CG (CBAL,CORTH,COMQR)

8.8

7.3

6.3

6.0

6.0

PATHS

CBAL,CORTH,COMQR, CINVIT, CORTB,CBABK2

8.7+.54M 7.3+.22M 6.3+.09M 6.1+.06M 5.9+.04M

163

4.1-37

TABLE 38 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR REAL GENERAL MATRICES MACHINE:

Honeywell 6070 Fortran-Y(SR-F) Optimized BELL LABORATORIES

ORDER OF MATRIX SUBROUTINE

N=I0

N=20

N=40

Time Unit (Sac)

.009

.070

.54

BALANC BALBAK

.32 . 15

.12 .06

.06 °03

.04 .02

.03

ELMHES ELTRAN ELMBAK

i

1 .07 .54

1 .03 .56

i .02 .56

i

16 ~52

0RTHES ORTRAN ORTBAK

2.9 .86 1.2

3.0 .81 1.2

3.1 .80 1.2

3.1 .79 1.2

3.1 .79 I~2

HQR2

15

12

Ii

i0

i0

HQR

8.6

6.1

4.3

3.9

3.5

INVlT

4.6

3.6

3.0

2.7

2.6

16

14

12

ii

II

i0

7.2

5.4

5.0

4.5

.

N=60

N=80

1.8

4.3

.01

.01

.56

PATHS RG (BALANC, ELMI~ S, ELTRAN, HQR2, BALBAK) RG (BALANC,ELMHES ,HQR) BALANC, ELMHES, HQR, INVIT, ELMBAK ~BALBAK

I0+.53M

7.2+.21M 5.4+.09M 5.0+.05M 4.5+.04M

4.1-38 TABLE 39 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT REDUCE FULL MATRICES TO HEAL SYMMETRIC TRIDIAGONAL FORM MACHINE:

Honeywell 6070 Fortran-Y(SR-F) Optimized BELL LABORATORIES

SUBROUTINE

N=IO

ORDER OF MATRIX N=20 N=40 N=60

N=80

Time Unit (Sec)

.013

.078

1.6

3.6

TREDI TRED2 TRED3 TRBAKI TRBAK3

1 1.4 I.i .87 1.0

1 1.8 1.2 i.i 1.3

1 1.9 1.2 1.3 1.5

1 2.0 1.2 1.4 1.6

1 2.0 1.3 1.4 1.6

HTRIDI HTRID3 HTRIBK HTRIB3

2.6 2.7 2.9 2.9

3.0 3.1 3.8 3.8

3.3 3.5 4.5 4.5

3.4 3.6 4.7 4.8

3.5 3.7 4.9 4.9

FIGI FIGI2 BAKVEC

.i0 .14 .12

.03 .05 .06

TQL2 IMTQL2

4.1 4.2

4.4 4.6

TQLRAT TQLI IMTQLI

I.i 1.7 1.8

.60 i.I 1.2

BISECT TRIDIB

IMTQLV RATQR

5.2 5.3 1.9 3.0

TINVIT TSTURM

1.0 6.2

.53

.01 .02 .03 4.2 4.6

.00 .01 .02 4.3 4.6

.00 .01 .02 4.2 4.6

.29 .59 .65

.21 .42 .46

.15 .32 .34

3.1 3.2 i.i 2.1

1.6 1.6 .65 1.4

i.i I.i .45 1.0

.84 .81 .35 .82

.67 3.9

.39 2.0

.31 1.4

.33 1.2

6.4 1.6 i+. 24M i+. 15M

6.0 1.3 i+. 08M i+. 04M

6.4 1.2 I+. 05M i+. 02M

6.2 i.i i+. 03M i+. OIM

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 2.0 i+. 7 IM I+. 52M

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 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR COMPLEX GENERAL MATRICES MACHINE:

Univac iii0, Fortran V(9) Compiler THE UNIVERSITY OF WISCONSIN

ORDER OF MATRIX SUBROUTINE

N=I0

N=20

Time Unit (Sec)

°025

.18

CBAL CBABK2

16 .08

.08 .03

.04 .01

.02 .01

.02 ~01

COMHES COMBAK

1 .48

1 .53

1 .57

1 .58

1 °58

.

N=40

N=60

N=80

1.3

4.4

I0

CORTH CORTB

2.3 1.0

2.6 I.i

2.8 i.i

2.8 1.2

2.9 1.2

COMQR2 COMLR2

13 9.4

12 7.5

ii 6.3

ii 6.3

II 6.1

COMQR COMLR

6.2 5.5

4.8 3.6

3.9 2.5

3.9 2.4

3.6 2.2

CINVIT

4.7

3.4

2.7

2.4

2,3

CG (CBAL,CORTH, COMQR2,CBABK2)

16

15

14

14

14

CG (CBAL,CORTH,COMQR)

8.7

7.4

6.7

6.7

6.5

PATHS

CBAL,CORTH,COMQR,CINVIT, CORTB~CBABK2

8.7+.58M 7.4+.23M 6.7+.IOM 6.7+.06M 6.6+.04M

166

4.1-40

TABLE 41 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR REAL GENERAL MATRICES MACHINE:

Univac IIi0, Fortran V(9) Compiler THE UNIVERSITY OF WISCONSIN

ORDER OF MATRIX SUBROUTINE

N=I0

N=20

N=40

Time Unit (Sec)

.009

.062

.45

BALANC BALBAK

.39 .Ii

.17 .05

.08 .02

.05 .02

.04 .01

ELMI{ES ELTRAN ELM~AK

1 .16 .54

i .08 .57

1 .03 .58

1 .02 .59

1 .02 .59

ORTHES ORTRAN ORTBAK

3.2 .72 1.1

3.6 .74 1.1

3.8 .76 1.2

4.0 .77 1.2

4.0 .78 1.2

HQR2

15

13

Ii

ii

ii

HQR

8.5

6.3

4.7

4.3

3.9

INVIT

5.6

4.6

4.0

3.8

3.7

L6

14

13

12

12

9.9

7.5

5.8

5.4

4.9

N=60

N=80

1.5

3.4

PATHS RG (BALANC, ELMHES, ELTRAN, HQR2, BALBAK) RG (BALANC, ELMHES, HQR) BALANC, ELMHES, HQR, INVIT, ELMBAK, BALBAK

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 REDUCE FULL MATRICES TO REAL SYMMETRIC TRIDIAGONAL FORM MACHINE:

Un±vac Iii0, Fortran V(9) Compiler THE UNIVERSITY OF WISCONSIN

SUBROUTINE

N=I0

ORDER OF MATRIX N=20 N=40 N=60

N=80

Time Unit (Sec)

.012

.065

1.2

2.7

TRED 1 TRED2 TRED3 TRBAKI TRBAK3

! 1.5 1.3 .81 1.4

1 1.7 1.7 I.I 2.0

i 1.9 2.0 1.3 2.5

1 1.9 2.2 1.4 2.7

1 2.0 2.3 1.5 2.9

HTRIDI HTRID3 HTRIBK HTRIB3

2.3 2.1 2.2 2.2

2.5 2.4 3.0 3.1

2.7 2.7 3.8 3.8

2.9 2.8 4.1 4.1

2.9 2.9 4.3 4.3

FIGI FIGI2 BAKVEC

,08 ,09 .08

.02 ,04 °05

TQL2 IMTQL2

3.4 3.6

3.8 4.0

TQLRAT TQLI IMTQLI

.99 1.4 1.5

.63 .96 1.0

BISECT TRIDIB IMTQLV RATQR

6.3 6.2 1.6 3.3

TINVIT TSTURM

1.2 7.4

.40

.01 ,02 ,03 4.0 4.4

,00 .01 .02 4.1 4.4

.00 .01 .01 4.2 4.3

.36 .58 .64

.26 .41 .45

.19 .31 ,34

3.9 3.8 i. i 2.7

2.2 2.2 .67 1.8

1.6 1.5 .47 1.4

1.2 I.I .35 1.2

.82 4.6

.51 2.7

.39 1.9

.38 !.6

5.5 1.6 i+. 29M i+. 19M

5.8 1.4 i+. IOM i+. 06M

6.0 1.2 i+. 06M I+. 03M

6.2 1.2 i+. 04M i+. OIM

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

4.9 2.0 I+. 83M I+. 63M

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 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR COMPLEX GENERAL MATRICES MACHINE:

DEC PDP-10, F40 Compiler YALE UNIVERSITY

ORDER OF MATRIX SUBROUTINE

N=I0 .29

Time Unit (Sec)

N=20

N=30

N=40

2.4

8.3

20

CBAL CBABK2

.16 .05

.07 .03

.05 .01

.04 .01

COMHES COMBAK

i •57

1 .57

i .58

1 .59

CORTH CORTB

2.0 I.I

1.9 I.i

2.0 I.I

2.0 i.i

COMQR2 COMLR2

13 8.8

ii 7.6

ii 7.2

ii 6.7

COMQR COMLR

5.1 4.3

3.7 3.1

3.4 2.6

3.2 2.3

CINVlT

3.4

2.7

2.6

2.5

CG (CBAL,CORTH,COMQR2,CBABK2)

15

13

13

13

CG (CBAL,CORTH,COMQR)

7.2

5.7

5.4

5.2

PATHS

CBAL,CORTH,COMQR,CINVIT, CORTB,CBABK2

7.2+.46M 5.7+.19M 5.4+.12M 5.2+.09M

169

4.1-43

TABLE 44 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR REAL GENERAL MATRICES MACHINE:

DEC PDP-10, F40 Compiler YALE UNIVERSITY

ORDER OF MATRIX SUBROUTINE

N=I0

N=20

.i0

.80

BALA_NC BALBAK

~27 .12

. 12 °04

,08 .03

.06 .02

ELegIES ELTRAN EI/iBAK

I ,21 °54

I .08 ,58

1 ,06 ,59

i .04 .59

ORTHES ORTRAN ORTBAK

1.8 .75 i.i

1.9 .73 i.i

1.9 .73 i.i

1.9 .72 I.i

HQR2

12

ii

9.9

9.7

HQR

6.7

5.0

4.1

3.8

INVIT

3.5

2.9

2.7

2.6

14

12

ii

II

7.9

6.2

5.2

4.9

Time Unit (Sec)

N=30

N=40

2.7

6°2

PATHS RG (BALANC~ELMHES~ELTRAN, HQR2,BALBAK) RG (BALANC,ELMHES,HQR) BALANC, ELMIIES, HQR, INVIT, EI2LBAK, BALBAK

8.0+.42M 6.2+.17M 5.2+.IIM 4.9+.08M

170

4.1-44 TABLE 45 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT REDUCE FULL MATRICES TO REAL SYMMETRIC TRIDIAGONAL FORM MACHINE:

DEC PDP-10, F40 Compiler YALE UNIVERSITY

SUBROUTINE

N=I0

Time Unit (Sec)

ORDER OF MATRIX N=20 N=30 N=40

.i0

.64

TREDI TRED2 TRED3 TRBAKI TRBAK3

1 1.8 .85 1.2 i.i

HTRIDI HTRID3 HTRIBK HTRIB3

3.2 2.6 4.4 4.4

FIGi FIGI2 BAKVEC

.09 .09 .12

TQL2 IMTQL2

3.7 3.9

TQLRAT TQLI IMTQLI

.73 1.0 i.i

BISECT TRIDIB IMTQLV RATQR TINVIT TSTURM

2.0

4.7

1 2.0 .87 1.5 1.4

i 2.0 .88 1.6 1.5

1 2.1 .88 1.7 1.5

3.6 3.1 5.5 5.5

3.7 3.2 5.9 5.9

3.8 3.3 6.2 6.2

.01 .05 .07 4.2 4.5

.01 .03 .04 4.1 4.2

.01 .02 .03 4.0 4.3

.42 .65 .75

.26 .42 .48

.20 .33 .39

3.9 3.9 1.2 2.1

2.1 2.1 .79 1.4

1.4 1.3 .51 i.i

1.0 .99 .41 .87

1.2 5.0

.70 2.8

.50 1.8

.39 1.4

6.2 1.4 I+. 22M 1+. IOM

6.2 1.3 i+. 12M I+. 05M

6.1 1.2 i+. 08M i+. 03M

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.8 i+. 62M i+. 39M

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 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR COMPLEX GENERAL MATRICES MACHINE:

Amdahl 470V/6, Fortran H, OPT=2 UNIVERSITY OF MICHIGAN

ORDER OF MATRIX SUBROUTINE

N=I0

N=20

N=40

Time Unit (Sec)

.005

.040

.33

CBAL CBABK2

.12 .07

.05 .03

.02 .02

.01 .01

.01 .01

COMHES COMBAK

1 .46

1 .50

i .54

I .58

i .60

N=60

N=80

i. 1

2.8

CORTH CORTB

2.4 1.3

2.3 1.3

2.2 1.2

2.2 1.2

2.1 i.i

COMQR2 COMLR2

18 9.4

15 8.1

13 6.7

13 6.5

12 6.2

COMQR COMLR

8.0 5.1

5.7 3.4

4.5 2.4

4.2 2.2

3.9 2.0

CINVIT

4.8

3.3

2.5

2.2

2.3

CG (CBAL,CORTH,COMQR2,CBABK2)

20

18

16

15

14

CG (CBAL,CORTH,COMQR)

ii

8.1

6.7

6.4

6.0

PATHS

CBAL,CORTH,COMQR,CINVIT, CORTB,CBABK2

II+.62M

172

8.1+.23M 6.7+.09M 6.4+.06M 6.0+.04M

4.1-46

TABLE 47 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR REAL GENERAL MATRICES MACHINE:

Amdahl 470~/6, Fortran H, OPT=2 UNIVERSITY OF MICHIGAN

ORDER OF MATRIX SUBROUTINE

N=I0

N=20

N=40

N=60

N=80

Time Unit (Sec)

.002

.014

.12

.41

.98

BALANC BALBAK

.24 .12

.09 .05

.04 .02

.02 .02

.02 .01

ELMHES ELTRAN ELMBAK

1 .16 .54

1 .07 .57

1 .03 .57

i .02 .58

I .02 .59

ORTHES ORTRAN ORTBAK

2.4 .81 1.2

2.2 .71 I.i

2.1 .65 .98

2.0 .62 .93

1.9 .60 .90

HQR2

20

16

12

12

II

HQR

12

7.7

5.2

4.5

3.9

INVlT

4.5

3.4

2.7

2.4

2.3

RG (BALANC, ELMHES, ELTRAN, HQR2, BALBAK) RG (BALANC, ELMHES, HQR)

21

17

14

13

12

13

8.8

6.2

5.5

4.9

BALANC, ELMHES, HQR, INVIT, ELMBAK~ BALBAK

13+.51M

PATHS

173

8.8+.20M 6.3+.08M 5.5+.05M 5.0+.04M

4.1-47 TABLE 48 SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT REDUCE FULL MATRICES TO REAL SYMMETRIC TRIDIAGONAL FORM MACHINE:

Amdahl 470V/6, Fortran H, OPT=2 UNIVERSITY OF MICHIGAN

SUBROUTINE

N=IO

ORDER OF MATRIX N=20 N=40 N=60

Time Unit (Sec)

.002

.013

.090

TREDI TRED2 TRED3 TRBAKI TRBAK3

i 1.6 .99 1.2 1.0

1 1.8 .98 1.4 1.2

HTRIDI HTRID3 HTRIBK HTRIB3

2.7 2.6 3.3 3.5

3.1 3.1 4.4 4.6

FIGI FiGI2 BAKVEC

•09 .15 .I0

.03 ,06 .06

TQL2 IMTQL2

4.9 5.0

5.3 5.2

TQLRAT TQLI IMTQLI

1.4 2.3 2.3

.81 1.5 1.5

BISECT TRIDIB IMTQLV RATQR

ii Ii 2.4 3.4

TINVIT TSTURM

1.0 12

N=80

,29

°70

i 2.0 1.0 1.6 1.4

1 2.0 .98 1.6 1.4

i 2.0 .96 1.6 1.4

3.4 3.4 5.1 5.3

3.6 3.6 5.4 5.5

3.7 3.6 5.5 5.5

.01 .03 .03 5.1 5.3

.00 .02 .02 5.0 5.0

.00 .01 .02 4.6 4.8

.42 .86 .88

.27 .57 .58

.19 .42 .43

6.8 7.0 1.6 2.6

3.7 3.8 .89 1.7

2.5 2.6 .59 1.2

1.8 1.9 .43 .93

.67 7.5

.40 4.2

.29 2.9

.30 2.2

7.1 1.8 I+. 44M I+ .34M

7.1 1.4 I+. 14M I+. 09M

7.0 1.3 i+. 07M i+. 04M

6.7 1.2 I+. 05M I+ .02M

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

6.5 2.4 I+i. 3M I+ i. IM

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)

CG(1) CG(O) RG(1) RG(O) RS(1) RS(O) CH(1)CH(~) .77

.66

.31

.22

i

i

1

i

1

IBM 360/75 (UNIVERSITY OF ILLINOIS)

16

15

ii

Ii

IBM 370/168 (UNIVERSITY OF MICHIGAN)

5.8

5.2

3.9

IBM 370/165 (THE UNIVERSITY OF TORONTO)

3.5

3.2

IBM 370/195 (ARGONNE NATIONAL LABORATORY)

BURROUGHS 6700 (UNIVERSITY OF CALIFORNIA, SAN DIEGO) CDC 6600 (KIRTLAND AIR FORCE BASE)

1.7

118

108

.44

.14

1

i

1

15

12

13

12

3.7

5.6

3.9

5.0

4.5

2.9

2.6

3.3

2.9

3.2

2.9

95

92

125

.055

82

122

i00

5.0

5.3

4.9

4.9

5.5

5.0

3.7

3.0

CDC 6600 (NASA LANGLEY RESEARCH CENTER)

4.5

4.3

5.5

5.6

5.3

5.0

4.2

3.8

CDC 7600 (NATIONAL CENTER FOR ATMOSPHERIC RESEARCH) CDC 6400 (NORTHWESTERN UNIVERSITY)

i.i

1.0

1.2

I.i

1.0

I.i

22

22

19

18

21

18

17

17

CDC 6400/6500 (PURDUE UNIVERSITY)

31

32

42

38

24

20

22

21

CDC 6600/6400 (THE UNIVERSITY OF TEXAS)

8.2

8.9

17

15

6.1

5.9

5.6

5.6

HONEYWELL 6070 (BELL LABORATORIES)

21

20

9.9

9.4

15

13

14

14

UNIVAC III0 (THE UNIVERSITY OF WISCONSIN)

Ii

II

8.9

8.4

ii

ii

9.8

9.2

155

135

132

106

DEC PDP-IO (YALE UNIVERSITY) AMDAHL 470V/6 (UNIVERSITY OF MICHIGAN)

3.1

2.9

175

104

2.4

98

2.3

2.9

2.4

.81

146

2.7

.83

139

2.6

4.1-49 TABLE 50 SUMMARY OF EXECUTION TIMES FOR SELECTED PROBLEMS USING THE EISPAC CONTROL PROGRAM MACHINE: IBM 370/195, Fortran H, OPT=2 ARGONNE NATIONAL LABORATORY

Time Unit:

1 second ORDER OF MATRIX

EIGENVALUES

EIGENVECTORS

TRANSFORMATIONS

N=I0

N=20

N=40

N=60

N=80

CG

All

All

Unitary

.044

.25

1.7

5.7

13

CG

All

Some(M=N)

Unitary

.047

.22

1.3

4.2

9.6

CG

All

All

Elementary

.032

.16

1.0

3.3

7.6

CG

All

Some(M=N)

Elementary

.041

.17

,92

2.7

6.7

RG

All

All

Elementary

.023

.i0

.63

2.0

4.5

RG

All

Some(M=N)

Elementary

.024

.095

.51

1.5

3.4

RG

All

All

Orthogonal

.026

.12

.72

2.3

5.2

RG

All

Some(M=N)

Orthogonal

,026

.i0

.59

1.8

4.0

RS

All

All

,011

,040

.22

.65

RS

All

None

,007

.016

.059

.15

RS

Some(M=N)

Some(M=N)

,025

.080

.33

,81

1.6

RS

Some(M=N)

None

.022

.066

.24

.56

1.0

CH

All

All

.016

.07

.44

CH

All

None

.009

.026

.14

CH

Some(M=N)

Some(M=N)

.029

.ii

.52

CH

Some(M=N)

.023

.08

.33

PROBLEM CLASS

None

176

1.4 .42 1.5 .83

1.5 .33

3.4 1.0 3.3 1.8

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 subroutines 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 execution 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 characteristics 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 subroutines are attributable to the special architecture of the IBM 370/195; namely, the buffered or two-level memory, the pipe line or parallel arithmetic 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 interval (-215,+215).

A listing of the auxiliary subroutine RANDOM which generates

the random integers is also provided.

482

4.5-2 COMPLEX GENERAL MATRIX

I0 20

DO 20 I = I,N DO i0 d = I,N CALL RANDOM (INIT, AR(I,J)) CALL RANDOM (INIT, AI(I,J)) CONTINUE CONTINUE

COMPLEX HERMITIAN MATRIX

10 20 30

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 INUE CONT INUE CALL RANDOM (INIT, AR(N,N)) AI(N,N) = 0.0

COMPLEX HERMITIAN PACKED MATRIX

i0 20

C C

DO 20 i = I,N DO i0 d = I,N CALL RANDOM (INIT, A(I,J)) CONTINUE CONTINUE

REAL GENERAL MATRIX

10 20

D O 2 0 I = I,N DO I0 J = I,N CALL RANDOM (INIT, A(I,J)) CONTINUE CONT INUE

REAL SYMMETRIC MATRIX DO20

I=

I,N

DO i0 a = I,N

I0 20

CALL RANDOM (INIT, A(I,J)) A(J,I) = A(I,J) CONTI NUE CONTI 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

REAL SYMMETRIC TRIDIAGONAL MATRIX

10 20 30

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

10 20

30 40

DO 20 I = I,N DO I0 J = 1,3 CALL RANDOM (INIT, A(I,J)) CONTINUE CONTINUE IF (N .EQ. i) GO TO 40 DO 30 I = 2,N

A ( I , 1 ) = SIGN(A(I,1), A ( I - 1 , 3 ) ) CONTINUE 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 following computer systems and working precisions (test site names are indicated in parentheses): MACHINE

OPERATING SYSTEM

COMPILER

WORKING PRECISION

IBM 370/195

0S/360 (21.7) FTN IV G,H(21.7),WATFIV (ARGONNE NATIONAL LABORATORY)

LONG

IBM 360/75

0S/360 (21.7) FTN IV H(21.7) (UNIVERSITY OF ILLINOIS AT URBANA-CHAMPAIGN)

LONG

IBM 370/168

MTS FTN IV G,H (UNIVERSITY OF MICHIGAN)

LONG

IBM 360/75

OS/360 (21.7) FTN IV H EXTENDED(2.1) (STOCKHOLM DATA CENTER)

LONG

IBM 370/165

0S/360 (21.7) FTN IV H EXTENDED(2.1) (THE UNIVERSITY OF TORONTO)

LONG

BURROUGHS 6700

MCP 2.6 FORTRAN IV(2.6) (UNIVERSITY OF CALIFORNIA, SAN DIEGO)

SINGLE

CDC 6600

SCOPE 3.4.2 FTN(4.2) (KIRTLAND AIR FORCE BASE/AF~rL)

SINGLE

CDC 6600

KRONOS 2.1 RUN(2.3) (ICASE/NASA LANGLEY RESEARCH CENTER)

SINGLE

CDC 7600

(LOCAL) (LOCAL) (NATIONAL CENTER FOR ATMOSPHERIC RESEARCH)

SINGLE

CDC 6400

SCOPE 3.3 RUN(2.3) ,FTN(3.0) (NORTHWESTERN UNIVERSITY)

SINGLE

CDC 6400/6500

(LOCAL) FUN (PURDUE UNIVERSITY)

SINGLE

CDC 6600/6400

UT2D-85 RUN (60.2), MNF, RUh~/ (THE UNIVERSITY OF TEXAS AT AUSTIN)

SINGLE

HONEYWELL 6070

GECOS SR-F FORTRAN-Y (SR-F) (BELL LABORATORIES AT MURRAY HILL)

SINGLE

UNIVAC Iii0

EXEC-8 (31. 244) FORTRAN V(9) (THE UNIVERSITY OF WISCONSIN)

SINGLE

DEC PDP-IO

TOPS-10 (506B) FORTRAN F40 (YALE UNIVERSITY)

SINGLE

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 throughout the useful life of EISPACK or until, in the estimation of the developers, the package is superseded or incorporated into other supported, widelyavailable 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. version.

The requester should specify the desired machine

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

of several errors,

fall into four categories:

2) minor algorithmic improvements,

consideration of Fortran language efficiency,

I) correction

3) changes based on

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 technique discussed in the "Organisational

the alternate scaling

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 4) process,

operands.

The Handbook procedure-calls

for row interchange in the balancing

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

TRED 2

Also see TRED2 below.

- The arithmetic operation G*(Z/H) is computed instead as (G/H)*Z, enabling the resultant tridiagonal form to more literally duplicate 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 determining 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 replacement 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 R A T Q R w i t h

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 T S T U R M w h i c h

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

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

(BISECT,TSTURM).

193

(IM~QLI,IMTQL2), and

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 systematically 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 testing 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 extensive 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

E!GENSYSTEM

PROJECT

SUBROUTINE F281-2

PACKAGE

(EISPACK)

BAKVEC

A F o r t r a n IV S u b r o u t i n e to B a c k T r a n s f o r m the E i g e n v e c t o r s of that S y m m e t r i c T r i d i a g o n a l M a t r i x D e t e r m i n e d by FIGIo

May, July,

1972 1975

I. P U R P O S E The F o r t r a n IV s u b r o u t i n e BAKVEC f o r m s the e i g e n v e c t o r s of a certain real non-symmetric t r i d i a g o n a l m a t r i x f r o m the e i g e n v e c t o r s of that s y m m e t r i c t r i d i a g o n a l m a t r i x d e t e r m i n e d by F I G I (F280).

2.

USAGE. A.

Calling The

Sequence~

SUBROUTINE SUBROUTINE

statement

is

BAKVEC(NM~N,T,E,M,Z,IERR)

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

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

N

is an i n t e g e r i n p u t v a r i a b l e the o r d e r of the m a t r i x T. greater than NM.

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

is a w o r k i n g p r e c i s i o n r e a l i n p u t twod i m e n s i o n a l v a r i a b l e w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at l e a s t 3. T c o n t a i n s the n o n - s y m m e t r i c tridiagonal m a t r i x of o r d e r N in its f i r s t t h r e e columns. The s u b d i a g o n a l e l e m e n t s are s t o r e d in the last N-I p o s i t i o n s of the

196

7.1-2

f i r s t column. The d i a g o n a l e l e m e n t s are s t o r e d in the s e c o n d c o l u m n . The s u p e r d i a g o n a l e l e m e n t s are s t o r e d in the first N-I p o s i t i o n s of the t h i r d column. Elements T(I,I) and T(N,3) are arbitrary. is a w o r k i n g p r e c i s i o n r e a l o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N. On input, the last N-I p o s i t i o n s in this a r r a y c o n t a i n the s u b d i a g o n a l e l e m e n t s of the s y m m e t r i c t r i d i a g o n a l m a t r i x . E(1) is arbitrary. N o t e that BAKVEC destroys E. M

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

input variable c o l u m n s of Z

set e q u a l to to be b a c k

is a w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t M. On input, the f i r s t M c o l u m n s of Z c o n t a i n the e i g e n v e c t o r s to be b a c k t r a n s f o r m e d . On o u t p u t , these c o l u m n s of Z c o n t a i n the t r a n s f o r m e d eigenvectors. The t r a n s f o r m e d e i g e n v e c t o r s are not n o r m a l i z e d . IERR

B.

Error

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

Conditions

and

to is

Returns.

If E(1) is zero but e i t h e r T(I,I) or T(I-I,3) is not zero, BAKVEC terminates with IERR set to 2*N+I and w i t h no e i g e n v e c t o r s b a c k t r a n s f o r m e d . In this case, the t r a n s f o r m a t i o n by FIGI was not a s i m i l a r i t y transformation. If the a b o v e set to zero.

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

error

and

condition

does

not

occur,

IERR

is

with

the

Restrictions.

This s u b r o u t i n e s h o u l d be subroutine FIGI (F280).

197

used

in c o n j u n c t i o n

7.1-3

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

OF M E T H O D

AND

ALGORITHM.

S u p p o s e that the n o n - s y m m e t r i c tridiagonal matrix T b e e n t r a n s f o r m e d to the t r i d i a g o n a l s y m m e t r i c m a t r i x the s i m i l a r i t y t r a n s f o r m a t i o n

has P by

-i F = V

TV

where V is the d i a g o n a l m a t r i x d e f i n e d in Then, g i v e n an a r r a y Z of c o l u m n v e c t o r s , the m a t r i x p r o d u c t VZ. If the e i g e n v e c t o r s c o l u m n s of the a r r a y Z, then BAKVEC forms of T in their place. This s u b r o u t i n e is an i m p l e m e n t a t i o n of d i s c u s s e d in d e t a i l by W i l k i n s o n (i).

4.

algorithm

REFERENCES° i)

5.

the

F I G I (F280). BAKVEC computes of F are the e i g e n v e c t o r s

W i l k i n s o n , J.H., Oxford, Clarendon

The A l g e b r a i c E i g e n v a l u e P r e s s , 3 3 5 - 3 3 7 (1965).

Problem,

CHECKOUT. A.

Test

Cases.

See the certain

section discussing real n o n - s y m m e t r i c

t e s t i n g of the codes for tridiagonal matrices.

B. A c c u r a c y . The a c c u r a c y of BAKVEC can b e s t be d e s c r i b e d in terms of its role in those p a t h s of EISPACK w h i c h find e i g e n v a l u e s and e i g e n v e c t o r s of c e r t a i n r e a l n o n symmetric tridiagonal matrices. In these paths, this s u b r o u t i n e is n u m e r i c a l l y s t a b l e (I). This s t a b i l i t y c o n t r i b u t e s to the p r o p e r t y of these p a t h s that the c o m p u t e d e i g e n v a l u e s are the exact e i g e n v a l u e s of a m a t r i x c l o s e to the o r i g i n a l m a t r i x and the c o m p u t e d e i g e n v e c t o r s are c l o s e (but not n e c e s s a r i l y equal) to the e i g e n v e c t o r s of that m a t r i x .

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. E(1) = 1.0 IF (N .EQ. DO

TO

i001

i) GO

TO

i001

=

120

J =

DO 120 Z(I,J) CONTINUE

* E(I)

i000 I001

.NE.

0.0)

/ r(I-l,3)

i, M I = 2, N = Z ( I , J ) * E(I)

GO TO i 0 0 1 **********

C C

80 T(I-I,3)

1.0

GO TO I00 E(I) = E ( I - I ) CONTINUE DO

120

GO

i00 1 = 2, N IF (E(1) .NEo 0.0) GO TO IF ( T ( I , I ) .NE. 0.0 .OR. E(I)

80 100

0)

SET E R R O R -- E I G E N V E C T O R S CANNOT F O U N D BY T H I S P R O G R A M * * * * * * * * * * IERR = 2 * N + I RETURN END

199

BE

GO TO

i000

7~i-5

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F269-2

A Fortran

IV

Subroutine

PACKAGE

BALANC

to B a l a n c e

May, July,

(EISPACK)

a Real

General

Matrix.

1972 1975

i. P U R P O S E . T h e F o r t r a n IV s u b r o u t i n e BALANC balances a real general m a t r i x and i s o l a t e s e i g e n v a l u e s w h e n e v e r p o s s i b l e . Sums of the m a g n i t u d e s of e l e m e n t s in c o r r e s p o n d i n g rows and c o l u m n s are m a d e n e a r l y e q u a l by exact s i m i l a r i t y t r a n s f o r m a t i o n s , and e i g e n v a l u e s are i s o l a t e d by p e r m u t a t i o n s i m i l a r i t y transformations. B a l a n c i n g r e d u c e s the 1 - n o r m of the o r i g i n a l m a t r i x w h e n e v e r sums of the m a g n i t u d e s of e l e m e n t s in some row and c o r r e s p o n d i n g c o l u m n are m a r k e d l y d i f f e r e n t , w h i l e at the same time l e a v i n g the e i g e n v a l u e s u n c h a n g e d . R e d u c i n g the n o r m in this way can i m p r o v e the a c c u r a c y of the computed eigenvalues and/or eigenvectors.

2.

USAGE. Ao

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

BALANC(NM,N,A,LOW, IGH,SCALE)

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

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

200

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

7 .I-6

is a w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t N. On input, A c o n t a i n s the m a t r i x of o r d e r N to be balanced. On o u t p u t , A c o n t a i n s the transformed matrix.

A

LOW, IGH are i n t e g e r o u t p u t v a r i a b l e s i n d i c a t i n g the b o u n d a r y i n d i c e s for the b a l a n c e d m a t r i x . See s e c t i o n 3 for the d e t a i l s . SCALE

B.

Error

is a w o r k i n g p r e c i s i o n real o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g i n f o r m a t i o n a b o u t the similarity transformations. See s e c t i o n 3 for the d e t a i l s .

Conditions

and

Returns.

None.

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

and

Restrictions.

It is p a r t i c u l a r l y a d v a n t a g e o u s to use BALANC whenever the sums of the m a g n i t u d e s of e l e m e n t s in some row and corresponding column are quite different. Additionally, the e x e c u t i o n time for BALANC is s m a l l c o m p a r e d w i t h the e x e c u t i o n time for the r o u t i n e s w h i c h d e t e r m i n e the eigenvalues and/or eigenvectors. H e n c e it is r e c o m m e n d e d that BALANC be u s e d g e n e r a l l y . The s u b r o u t i n e B A L B A K (F270) s h o u l d be used to r e t r i e v e the e i g e n v e c t o r s of the o r i g i n a l m a t r i x a f t e r the e i g e n v e c t o r s of the t r a n s f o r m e d m a t r i x h a v e b e e n determined.

3.

DISCUSSION

OF M E T H O D

First BALANC m a t r i c e s such

AND

ALGORITHM.

determines that

PAP

=

a product

( T

X

(0

B

Z)

(0

0

R)

P

of p e r m u t a t i o n

Y )

where T and R are u p p e r t r i a n g u l a r m a t r i c e s and B is a s q u a r e m a t r i x s i t u a t e d in rows and c o l u m n s LOW through IGH w i t h no zero o f f - d i a g o n a l rows or columns. X, Y, and Z are r e c t a n g u l a r m a t r i c e s of a p p r o p r i a t e d i m e n s i o n s . The

201

7.1-7

d i a g o n a l e l e m e n t s of T and R are the i s o l a t e d e i g e n v a l u e s of A. In the e x c e p t i o n a l c a s e w h e r e B is empty, LOW = 1 and IGH = 0 -- h o w e v e r , i is r e t u r n e d as the o u t p u t v a l u e of IGH. Next, the s u b r o u t i n e BALANC singular diagonal matrix D

determines iteratively a nonof o r d e r IGH-LOW+I s u c h that

-I D

BD

is a b a l a n c e d m a t r i x in the s e n s e that the a b s o l u t e sums of the m a g n i t u d e s of e l e m e n t s in c o r r e s p o n d i n g r o w s and c o l u m n s of -i D

BD

are n e a r l y equal° The d i a g o n a l the r a d i x of the f l o a t i n g p o i n t

e l e m e n t s of D are p o w e r s a r i t h m e t i c of the m a c h i n e .

of

U p o n c o m p l e t i o n of B A L A N C , the v e c t o r a r r a y SCALE contains the i n f o r m a t i o n a b o u t P and D n e c e s s a r y for BALBAK to r e t r i e v e the e i g e n v e c t o r s of the o r i g i n a l m a t r i x f r o m the e i g e n v e c t o r s of the t r a n s f o r m e d m a t r i x . The i n f o r m a t i o n is e n c o d e d as f o l l o w s . I. The J-th and SCALE(J)-th rows and c o l u m n s of the o r i g i n a l m a t r i x h a v e b e e n p e r m u t e d for J = 1,2,...,LOW-I,IGH+I,IGH+2,...,N. 2. SCALE(J) is the (J-LOW+l)-th d i a g o n a l e l e m e n t of D for J = LOW,LOW+I,...,IGH. U p o n c o m p l e t i o n of B A L A N C , the o u t p u t m a t r i x is ( T ( 0

XD -I D BD

( 0

0

Y -i D

) Z )

R

).

This s u b r o u t i n e is a t r a n s l a t i o n of the A l g o l p r o c e d u r e BALANCE w r i t t e n and d i s c u s s e d in d e t a i l by P a r l e t t and R e i n s c h (I).

4.

REFERENCES.

i)

P a r l e t t , B.N. and R e i n s c h , C., B a l a n c i n g a M a t r i x for C a l c u l a t i o n of E i g e n v a l u e s and E i g e n v e c t o r s , Num. Math. 1 3 , 2 9 3 - 3 0 4 (1969). ( R e p r i n t e d in H a n d b o o k for A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , J. H. W i l k i n s o n - C. R e i n s e h , C o n t r i b u t i o n Ii/ii, 315-326, Springer-Verlag, 1971.)

202

7.1-8

5.

CHECKOUT. A.

Test

Cases.

See the s e c t i o n d i s c u s s i n g real general matrices.

B.

testing

of

the c o d e s

for

Accuracy. BALANC i n t r o d u c e s no r o u n d i n g e r r o r s (on a m a c h i n e at l e a s t one g u a r d digit) s i n c e its only a r i t h m e t i c s c a l i n g the input m a t r i x by p o w e r s of the radix.

203

with is

7.1-9

SUBROUTINE

BALANC(NM,N,A,LOW,

IGH,SCALE)

INTEGER I,J,K,L,M,N,JJ,NM,!GH,LOW, REAL A(NM,N),SCALE(N) REAL C,F,G,R,S,B2,RADIX REAL ABS LOGICAL NOCONV **********

RADIX

=

A MACHINE DEPENDENT PARAMETER OF THE MACHINE FLOATING POINT

#

B2 = RADIX K = 1 L = N GO TO i00 • ********* 20

RADIX IS THE BASE

IEXC

* RADIX

IN-LINE PROCEDURE FOR ROW COLUMN EXCHANGE ********~* SCALE(M) = J IF (J .EQ. M) G O T O 5 0

AND

DO

30

3 0 I = I, L F = A(I,J) A(I,J) = A(I,M) A(I,M) = F CONTINUE

DO

40

4 0 1 = K, N F = A ( J , I) A(J,I) = A(M,I) A ( M , I) = F CONTINUE

C 50 C C 80 C i00

G O T O (80, 1 3 0 ) , ! E X C ********** SEARCH FOR ROWS ISOLATING AN EIGENVALUE AND PUSH THEM DOWN ********** IF (L .EQ. i) G O T O 2 8 0 L = L - i ********** F O R J = L S T E P -I U N T I L 1 D O -- * * * * * * * * * * D O 1 2 0 J J = i, L J = L + i - JJ DO

ii0

120

I i 0 I = i, IF (! .EQ. IF ( A ( J , I ) CONTINUE

L J) G O T O i i 0 .NE. 0 . 0 ) G O

TO

M = L !EXC = 1 GO TO 20 CONTINUE

204

120

SPECIFYING REPRESENTATION.

7.1-10

GO TO 140 ********** 130

K

140

DO

=

K + 170

SEARCH FOR COLUMNS AND PUSH THEM LEFT

170

180 190

AN

EIGENVALUE

1 J

= K,

L

DO

150 I = K, IF (I .EQ. IF ( A ( I , J ) CONTINUE

150

ISOLATING **********

L J) G O T O 1 5 0 .NE. 0.0) GO

TO

170

M = K IEXC = 2 GO TO 20 CONTINUE ********** NOW BALANCE THE SUBMATRIX IN R O W S DO 1 8 0 I = K, L SCALE(I) = 1.0 ********** ITERATIVE LOOP FOR NORM REDUCTION NOCONV = .FALSE. DO

270 C = R=

1 = K, 0.0 0.0

K

TO

L

**********

**********

L

DO

200 C

210

220 230

2 0 0 J = K, L IF (J .EQ. I) G O T O 2 0 0 C = C + ABS(A(J,I)) R = R + ABS(A(I,J)) CONTINUE ********** GUARD AGAINST ZERO IF (C .EQ. 0 . 0 .OR. R .EQ. G = R / RADIX F=I.0 S = C + R IF (C .GE. G) G O T O 2 2 0 F = F * RADIX C = C * B 2 GO T O 2 1 0 G = R * RADIX IF (C .LT. G) G O T O 2 4 0 F = F / RADIX C

C 240

250

=

C

/

C OR 0.0)

TO UNDERFLOW 270

B2

GO TO 230 ********** NOW BALANCE ********** IF ((C + R) / F .GE. 0 . 9 5 * S) G=I.O/F SCALE(l) = SCALE(l) * F NOCONV = .TRUE. DO 250 A(I,J)

R DUE GO TO

J

=

K,

= A(I,J)

N

* G

205

GO

TO

270

**********

7.1-11

DO 260 A(J,I)

260 270

= I, L A(J,I)

* F

CONTINUE IF

280

J =

(NOCONV)

GO

TO

190

LOW = K IGH = L RETURN END

206

7.1-12

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F270-2

PACKAGE

(EISPACK)

BALBAK

A F o r t r a n IV S u b r o u t i n e to B a c k T r a n s f o r m the E i g e n v e c t o r s of that R e a l M a t r i x T r a n s f o r m e d by BALANC.

May, July,

1972 1975

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e BALBAK forms the e i g e n v e c t o r s of a r e a l g e n e r a l m a t r i x f r o m the e i g e n v e c t o r s of that m a t r i x t r a n s f o r m e d by B A L A N C (F269).

2. U S A G E . A.

Call~ng The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

B A L B A K ( N M , N , L O W , IGH, S C A L E , M , Z )

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

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

N

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to the n u m b e r of c o m p o n e n t s of the v e c t o r s in the a r r a y Z. N m u s t be not g r e a t e r than NM.

LOW, IGH are i n t e g e r i n p u t v a r i a b l e s i n d i c a t i n g the b o u n d a r y i n d i c e s for the b a l a n c e d m a t r i x . See s e c t i o n 3 of F269 for the d e t a i l s . SCALE

is a w o r k i n g p r e c i s i o n real i n p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N c o n t a i n i n g i n f o r m a t i o n a b o u t the transformations. See s e c t i o n 3 of F269 for the d e t a i l s .

207

7.1-13

is an i n t e g e r i n p u t v a r i a b l e the n u m b e r of c o l u m n s of Z transformed.

set e q u a l to to b e b a c k

is a w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t M. On input, the f i r s t M c o l u m n s of Z c o n t a i n the r e a l and i m a g i n a r y p a r t s of the e i g e n v e c t o r s to be back transformed. On o u t p u t , t h e s e M c o l u m n s of Z c o n t a i n the r e a l and i m a g i n a r y p a r t s of the t r a n s f o r m e d eigenvectors.

B.

Error

Conditions

and

Returns.

None°

C.

Applicability

and

Restrictions.

This s u b r o u t i n e s h o u l d be u s e d subroutine B A L A N C (F269).

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

OF M E T H O D

AND

in c o n j u n c t i o n

with

the

ALGORITHM.

U s i n g the n o t a t i o n of F269, t r a n s f o r m e d i n t o the m a t r i x transformation

the o r i g i n a l m a t r i x C by the s i m i l a r i t y

A

is

-I C = G

PAPG

where G is the d i a g o n a l m a t r i x w h o s e d i a g o n a l e l e m e n t s a r e 1.0 in p o s i t i o n s 1 to LOW-I, 1.0 in p o s i t i o n s IGH+I to N, and are the d i a g o n a l e l e m e n t s of D in p o s i t i o n s LOW to IGH. G i v e n an a r r a y Z of v e c t o r s , the s u b r o u t i n e BALBAK c o m p u t e s the m a t r i x p r o d u c t PGZ. If the r e a l and i m a g i n a r y p a r t s of the e i g e n v e c t o r s of C are c o l u m n s of the array Z, t h e n BALBAK f o r m s the e i g e n v e c t o r s of A in their p l a c e . The i n f o r m a t i o n a b o u t P and D is e n c o d e d in the a r r a y SCALE. See s e c t i o n 3 of F269 for the d e t a i l s . This subroutine BALBAK written R e i n s c h (I).

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

208

7.1-14

4. REFERENCES.

1)

Parlett, B.N. and Reinsch, C., Balancing a Matrix for C a l c u l a t i o n of Eigenvalues and Eigenvectors, Num. Math. 13,293-304 (1969). (Reprinted in H a n d b o o k for A u t o m a t i c Computation, Volume II, Linear Algebra, J. H. W i l k i n s o n - C. Reinsch, C o n t r i b u t i o n II/Ii, 315-326, S p r i n g e r - V e r l a g , 1971.)

5. CHECKOUT. A.

Test

Cases.

See the section discussing real general matrices.

testing

of

the codes

for

B. Accuracy. BALBAK introduces no rounding errors (on a m a c h i n e with at least one guard digit) since its only arithmetic is scaling the e i g e n v e c t o r m a t r i x by powers of the radix.

209

7.1-15

SUBROUTINE

BALBAK(NM,N,LOW,

INTEGER I~J,K,M,N,II,NM, REAL SCALE(N),Z(NM,M) REAL S IF IF

(M ,EQ. 0) G O TO 2 0 0 ( I G H .EQ. L O W ) G O T O

IGH, S C A L E , M , Z )

IGH,LOW

120

DO

I00 ii0

120

Ii0 i = L O W , I G H S = SCALE(l) ********** LEFT HAND EIGENVECTORS ARE IF T H E F O R E G O I N G STATEMENT S=I.O/SCALE(1). ***~****** DO i 0 0 J = i, M Z(I,J) = Z(I,J) * S CONTINUE ********-

DO

FOR I=LOW-I IGH+I STEP = i, N

S T E P -I U N T I L i~ 1 UNTIL N D O -- * * * * * * * * * *

1 4 0 ii ! = II IF (I .GE. L O W . A N D . I .LE. I G H ) IF (I .LT. L O W ) I = L O W - II K = SCALE(l) IF (K .EQ. I) G O T O 1 4 0 DO

130

1 3 0 J = i~ M S = Z(I,J) Z(I,J) = Z(K,J) Z(K,J) = S CONTINUE

140

CONTINUE

200

RETURN END

BACK TRANSFORMED IS R E P L A C E D BY

210

GO

TO

140

7.1-16

NATS

EIGENSYSTEM

SUBROUTINE F294

A Fortran

PROJECT

PACKAGE

(EISPACK)

BISECT

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

May,

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

1972

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

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

2. USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

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

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

is an i n t e g e r input v a r i a b l e the order of the matrix.

EPSI

is a w o r k i n g p r e c i s i o n r e a l v a r i a b l e . On input, it s p e c i f i e s an a b s o l u t e error t o l e r a n c e for the c o m p u t e d e i g e n v a l u e s . If the input EPSI is n o n - p o s i t i v e , it is r e s e t to a d e f a u l t v a l u e d e s c r i b e d in s e c t i o n 2C.

D

is a w o r k i n g p r e c i s i o n r e a l input oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N c o n t a i n i n g the d i a g o n a l e l e m e n t s of the s y m m e t r i c t r i d i a g o n a l matrix.

E

is a w o r k i n g p r e c i s i o n real input oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N c o n t a i n i n g , in its last N-I positions, the s u b d i a g o n a l e l e m e n t s of the s y m m e t r i c t r i d i a g o n a l matrix. E(1) is a r b i t r a r y .

211

set

equal

to

7.1-17

E2

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

LB,UB

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

MM

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to an u p p e r b o u n d for the n u m b e r of e i g e n v a l u e s in the i n t e r v a l (LB,UB).

M

is an i n t e g e r o u t p u t v a r i a b l e set e q u a l the n u m b e r of e i g e n v a l u e s d e t e r m i n e d to in the i n t e r v a l (LB,UB).

to lie

is a w o r k i n g p r e c i s i o n real o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t MM c o n t a i n i n g the M e i g e n v a l u e s of the s y m m e t r i c t r i d i a g o n a l m a t r i x in the i n t e r v a l (LB,UB). The e i g e n v a l u e s are in a s c e n d i n g o r d e r in W. IND

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

IERR

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

RV4,RV5

to is

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

212

7. 1-18

B. Error

Conditions

and

Returns.

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

M

does

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

not

exceed

MM,

and

Restrictions.

IERR

is set

to zero.

To d e t e r m i n e s o m e of the e i g e n v a l u e s of a full s y m m e t r i c matrix, BISECT s h o u l d be p r e c e d e d by TREDI (F277) to p r o v i d e a s u i t a b l e s y m m e t r i c t r i d i a g o n a l m a t r i x for BISECT. To d e t e r m i n e some of the e i g e n v a l u e s of a c o m p l e x Hermitian matrix, BISECT should be p r e c e d e d by HTRIDI (F284) to p r o v i d e a s u i t a b l e real s y m m e t r i c t r i d i a g o n a l m a t r i x for BISECT. Some of the e i g e n v a l u e s of c e r t a i n n o n - s y m m e t r i c t r i d i a g o n a l m a t r i c e s can be c o m p u t e d u s i n g the c o m b i n a t i o n of FIGI (F280) and BISECT. See F280 for the d e s c r i p t i o n of this s p e c i a l class of m a t r i c e s . For these m a t r i c e s , BISECT s h o u l d be p r e c e d e d by FIGI to p r o v i d e a s u i t a b l e s y m m e t r i c m a t r i x for BISECT. To d e t e r m i n e e i g e n v e c t o r s a s s o c i a t e d w i t h the c o m p u t e d eigenvalues, BISECT s h o u l d be f o l l o w e d by TINVIT (F223) and the a p p r o p r i a t e b a c k t r a n s f o r m a t i o n s u b r o u t i n e -T R B A K I (F279) after TREDI, HTRIBK (F285) after HTRIDI, or B A K V E C (F281) after FIGI. The s u b r o u t i n e s TQLI (F289) and IMTQLI (F291) d e t e r m i n e all the e i g e n v a l u e s of a s y m m e t r i c t r i d i a g o n a l m a t r i x f a s t e r than BISECT determines 25 p e r c e n t of them. Hence, if m o r e than 25 p e r c e n t of them are d e s i r e d , it is r e c o m m e n d e d that TQLI or IMTQLI be used. The i n t e r v a l (LB,UB) is f o r m a l l y h a l f - o p e n , not i n c l u d i n g the upper e n d p o i n t UB. H o w e v e r , b e c a u s e of r o u n d i n g e r r o r s , the true e i g e n v a l u e s v e r y close to the e n d p o i n t s of the i n t e r v a l may be e r r o n e o u s l y c o u n t e d or missed. The input i n t e r v a l (LB,UB) m a y be r e f i n e d i n t e r n a l l y to a s m a l l e r i n t e r v a l k n o w n to c o n t a i n all the e i g e n v a l u e s in (LB,UB). This i n s u r e s that BISECT w i l l not p e r f o r m u n n e c e s s a r y b i s e c t i o n steps to d e t e r m i n e the e i g e n v a l u e s in (LB,UB).

213

7,1-19

The p r e c i s i o n of the c o m p u t e d e i g e n v a l u e s is c o n t r o l l e d t h r o u g h the p a r a m e t e r EPSI. To o b t a i n e i g e n v a l u e s a c c u r a t e to w i t h i n a c e r t a i n a b s o l u t e error, EPSI s h o u l d be set to that error. In p a r t i c u l a r , if MACHEP d e n o t e s the r e l a t i v e m a c h i n e p r e c i s i o n , then to o b t a i n the e i g e n v a l u e s to an a c c u r a c y c o m m e n s u r a t e w i t h s m a l l r e l a t i v e p e r t u r b a t i o n s of the o r d e r of MACHEP in the m a t r i x e l e m e n t s , it is e n o u g h for m o s t t r i d i a g o n a l m a t r i c e s that EPSI be a p p r o x i m a t e l y MACHEP times a n o r m of the m a t r i x . But some m a t r i c e s r e q u i r e a s m a l l e r EPSI for this a c c u r a c y 9 p e r h a p s as s m a l l as MACHEP times the e i g e n v a l u e of s m a l l e s t m a g n i t u d e in (LB,UB). N o t e , h o w e v e r , that if EPSI is s m a l l e r than r e q u i r e d , BISECT w i l l p e r f o r m u n n e c e s s a r y b i s e c t i o n steps to d e t e r m i n e the e i g e n v a l u e s . For f u r t h e r d i s c u s s i o n of EPSI, see r e f e r e n c e (I). If the i n p u t EPSI is n o n - p o s i t i v e , BISECT r e s e t s it, for each s u b m a t r i x , to -MACHEP t i m e s the 1 - n o r m of the s u b m a t r i x and uses its m a g n i t u d e . This v a l u e is t e n t a t i v e l y c o n s i d e r e d a d e q u a t e for c o m p u t i n g the e i g e n v a l u e s to an a c c u r a c y c o m m e n s u r a t e w i t h s m a l l r e l a t i v e p e r t u r b a t i o n s of the o r d e r of MACHEP in the matrix elements.

3.

DISCUSSION

OF M E T H O D

AND

ALGORITHM.

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

by

the m e t h o d

of b i s e c t i o n

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

214

7.1-20

The s u b m a t r i x eigenvalues are then merged with previously found eigenvalues into an ordered set. The above steps are repeated eigenvalues in the interval

on each submatrix until all the (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 w r i t t e n and discussed in detail by Peters and W i l k i n s o n (2). A similar Algol procedure BISECT is discussed in detail by Barth, Martin, and W i l k i n s o n (i).

4. REFERENCES.

i)

Barth, W., Martin, R.S., and Wilkinson, J.H., 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, H a n d b o o k Automatic Computation, Volume II, Linear Algebra, J. H. W i l k i n s o n - C. Reinsch, Contribution 11/18, 418-439, Springer-Verlag, 1971.

for

5. CHECKOUT. A. Test Cases. See the section discussing testing of the codes for complex Hermitian, real symmetric, real symmetric tridiagonal, and certain real n o n - s y m m e t r i c tridiagonal matrices.

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

215

7.1-21

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) C C C C C

**********

MACHEP

C

C C

=

MACHEP IS A THE RELATIVE

MACHINE DEPENDENT PARAMETER SPECIFYING PRECISION OF FLOATING POINT ARITHMETIC.

?

IERR = 0 TAG = 0 TI = LB T2 = UB ********** LOOK FOR SMALL SUB-DIAGONAL ENTRIES ********** D O 4 0 I = i) N I F (I .EQ. i) G O T O 20 IF ( A B S ( E ( 1 ) ) .GT. M A C H E P * (ABS(D(1)) + ABS(D(I-I)))) X GO TO 40 20 E2(1) = 0.0 40 C O N T I N U E ********** DETERMINE THE NUMBER OF EIGENVALUES IN THE INTERVAL ********** P = ! q

60

80

=

N

XI = UB ISTURM = I GO TO 320 M = S XI = LB ISTURM = 2 GO TO 320 M = M - S I F (M . G T . M M ) Q

=

R = 0 **********

C C

i00

GO

TO

ESTABLISH INTERVAL IF (R .EQ. M) G O T O TAG = TAG + I P = Q + I XU = D(P)

xo U

=

=

980

0

AND PROCESS NEXT BY THE GERSCHGORIN I001

D(P) 0.0

216

SUBMATRIX, REFINING BOUNDS **********

7.1-22

DO

Ii0

120

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

140

X1 = AMAXI(ABS(XU),ABS(X0)) * MACHEP I F ( E P S I .LE. 0 . 0 ) E P S I = - X I IF (P .NE. Q) G O T O 1 8 0 C ********** CHECK FOR ISOLATED ROOT WITHIN INTERVAL IF (rl .GT. D ( P ) .OR. D ( P ) .GE. T2) G O T O 9 4 0 M1 = P M2 = P RVS(P) = D(P) GO TO 9O0 1 8 0 XI = X I * F L O A T ( 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 . G T . M 2 ) G O T O 9 4 0 C ********** FIND ROOTS BY BISECTION ********** XO = UB ISTURM = 5

250

240 I = MI, M2 RVS(I) = UB R V 4 (I) = L B CONTINUE ********** LOOP FOR K-TH EIGENVALUE FOR K=M2 STEP -i UNTIL MI (-DO- NOT USED TO LEGALIZE K = M2 XU = LB

260

********** F O R I = K S T E P -I U N T I L M 1 D O 2 6 0 II = M I , K I = M 1 + K - II IF ( X U .GE. R V 4 ( 1 ) ) GO TO 260 XU = RV4(1) GO TO 280 CONTINUE

**********

DO

240 C C C

217

DO -COMPUTEE-GO-TO)

DO

--

**********

**********

7,1-23

280

IF (X0 **********

xl

300

:

oGT. R V 5 ( K ) ) X0 NEXT BISECTION

(xu + x0)

RVS(K) STEP **********

=

* 0.5

IF

( ( X 0 - X U ) .LE, ( 2 . 0 * M A C H E P * X (ABS(XU) + ABS(X0)) + ABS(EPSI))) ********** IN-LINE PROCEDURE FOR STURM 320 S = P - I U=I.0

GO TO 420 SEQUENCE **********

DO

3 4 0 1 = P, Q IF (U .NE. 0 . 0 ) G O T O 3 2 5 V = ABS(E(1)) / MACHEP GO TO 330 V = E2(1) / U U = D(1) - Xl - V I F (U .LT. 0 . 0 ) S = S + ! CONTINUE

325 330 340

360

380

400

420

900

GO TO (60,80,200,220,360), ISTURM ********** REFINE INTERVALS ********** I F (S .GE. K) G O T O 4 0 0 XU = XI IF (S .GE. M I ) G O T O 3 8 0 RV4(MI) = XI GO TO 300 RV4 (S+I) = XI IF (RV5(S) .GT. E l ) R V 5 ( S ) = XI GO TO 300 X0 = X1 GO TO 300 ********** K-TH EIGENVALUE FOUND ********** RV5(K) = El K = K - i IF (K ,GE. M I ) G O T O 2 5 0 ********** ORDER EIGENVALUES TAGGED WITH THEIR SUBMATRIX ASSOCIATIONS ********** S = R R = R + M2 - MI + i J = i K = MI

C DO

9 2 0 L = i, IF (J .GT. IF (K . G T . IF ( R V 5 ( K )

R S) G O T O 9 1 0 M2) GO TO 940 .GE. W ( L ) ) GO

DO

905

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

218

TO

915

7.1-24

910

915 920 940

W(L) = RVS(K) I N D (L) = T A G K = K + I GO TO 920 J = J + I CONTINUE IF (Q .LT. GO TO i001 *****~***~

980 IERR = 3 I001LB = TI UB = T2 RETURN END

N)

GO

TO

I00

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

219

OF

7. 1-25

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F272-2

PACKAGE

(EISPACK)

CBABK2

A F o r t r a n IV S u b r o u t i n e to B a c k T r a n s f o r m the E i g e n v e c t o r s of that C o m p l e x M a t r i x T r a n s f o r m e d by CBAL.

May, July,

1972 1975

I~ P U R P O S E s The F o r t r a n IV s u b r o u t i n e CBABK2 a c o m p l e x g e n e r a l m a t r i x f r o m the t r a n s f o r m e d by CBAL (F271).

f o r m s the e i g e n v e c t o r s of e i g e n v e c t o r s of that m a t r i x

2. U S A G E . A.

Calling The

Sequencer

SUBROUTINE SUBROUTINE

statement

is

C B A B K 2 ( N M , N , L O W , IGH, S C A L E , M , Z R , Z I )

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

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

N

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to the n u m b e r of c o m p o n e n t s of the v e c t o r s in the a r r a y Z = (ZR,ZI). N m u s t be not greater than NM.

LOW,!GH

are i n t e g e r i n p u t v a r i a b l e s i n d i c a t i n g the b o u n d a r y i n d i c e s for the b a l a n c e d m a t r i x . See s e c t i o n 3 of F271 for the d e t a i l s .

SCALE

is a w o r k i n g p r e c i s i o n r e a l i n p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g i n f o r m a t i o n a b o u t the transformations. See s e c t i o n 3 of F271 for the d e t a i l s .

220

7.1-26

B.

Error

M

is an i n t e g e r i n p u t v a r i a b l e set e q u a l the n u m b e r of c o l u m n s of Z = (ZR,ZI) back transformed.

ZR,ZI

are w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l variables with row dimension NM and c o l u m n d i m e n s i o n at l e a s t M. On input, the f i r s t M c o l u m n s of ZR and ZI c o n t a i n the r e a l and i m a g i n a r y parts, r e s p e c t i v e l y , of the e i g e n v e c t o r s to be b a c k t r a n s f o r m e d . On output, these M c o l u m n s of ZR and ZI c o n t a i n the real and i m a g i n a r y p a r t s of the transformed eigenvectors.

Conditions

and

to to be

Returns.

None.

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

and

Restrictions.

This s u b r o u t i n e s h o u l d be subroutine CBAL (F271).

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

OF M E T H O D

AND

used

in c o n j u n c t i o n

with

the

ALGORITHM.

U s i n g the n o t a t i o n of F271, t r a n s f o r m e d into the m a t r i x transformation

the o r i g i n a l m a t r i x C by the s i m i l a r i t y

A

is

-i C = G

PAPG

where G is the d i a g o n a l m a t r i x w h o s e d i a g o n a l e l e m e n t s are 1.0 in p o s i t i o n s I to LOW-l, 1.0 in p o s i t i o n s IGH+I to N, and are the d i a g o n a l e l e m e n t s of D in p o s i t i o n s LOW to IGH. G i v e n an a r r a y Z of v e c t o r s , the s u b r o u t i n e CBABK2 c o m p u t e s the m a t r i x p r o d u c t PGZ. If the e i g e n v e c t o r s of C are c o l u m n s of the a r r a y Z, then CBABK2 f o r m s the e i g e n v e c t o r s of A in their place. The information about P and D is e n c o d e d in the a r r a y SCALE. See s e c t i o n 3 of F271 for the d e t a i l s . This s u b r o u t i n e is a t r a n s l a t i o n of the A l g o l p r o c e d u r e CBABK2 w h i c h is the a n a l o g u e for c o m p l e x m a t r i c e s of the procedure BALBAK w r i t t e n and d i s c u s s e d in d e t a i l by P a r l e t t and R e i n s c h (I).

221

7.1-27

4. REFERENCES~

i)

5,

Parlett~ B.N. and Reinsch~ C., Balancing a M a t r i x for C a l c u l a t i o n of E i g e n v a l u e s and Eigenvectors, Num. Math. 13,293-304 (1969). (Reprinted in H a n d b o o k for A u t o m a t i c Computation, V o l u m e II, Linear Algebra, J. H. W i l k i n s o n - C. Reinsch, C o n t r i b u t i o n II/ll, 315-326, S p r i n g e r - V e r l a g , 1971.)

CHECKOUT~ A.

Test

Cases°

See the section c o m p l e x general

discussing matrices.

testing

of the

codes

for

B. Accuracy° CBABK2 introduces no rounding errors (on a m a c h i n e with at least one guard digit) since its only arithmetic is scaling the e i g e n v e c t o r m a t r i x by powers of the radix.

222

7.1-28

SUBROUTINE

CBABK2(NM,N,LOW,

IGH, S C A L E , M , Z R , Z I )

INTEGER I,J,K,M,N,II,NM,IGH,LOW REAL SCALE(N),ZR(NM,M),ZI(NM,M) REAL S IF IF

(M .EQ. 0) G O T O 2 0 0 (IGH

.EQ.

LOW)

GO

TO

120

DO

i00 ii0

120

II0 1 = LOW, IGH S = SCALE(l) ********** LEFT HAND EIGENVECTORS ARE IF T H E F O R E G O I N G STATEMENT S=I.0/SCALE(1). ********** DO i 0 0 J = I, M ZR(I,J) = ZR(I,J) * S ZI(I,J) = ZI(I,J) * S CONTINUE

CONTINUE ********** DO

FOR I=LOW-I S T E P -i U N T I L i, I G H + I S T E P 1 U N T I L N D O -- * * * * * * * * * * = i, N

1 4 0 II I = II IF (I .GE. L O W . A N D . I .LE. I G H ) IF (I .LT. L O W ) I = L O W - II K = SCALE(l) IF (K .EQ. I) G O T O 1 4 0 DO

130

1 3 0 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

BACK TRANSFORMED IS R E P L A C E D BY

223

GO

TO

140

7. 1-29

NATS

EiGENSYSTEM

PROJECT

SUBROUTINE F271-2

A Fortran

IV

Subroutine

PACKAGE

CBAL

to B a l a n c e

May, July,

(EISPACK)

a Complex

General

Matrix.

1972 i975

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e CBAL balances a complex general m a t r i x and i s o l a t e s e i g e n v a l u e s w h e n e v e r p o s s i b l e . Sums of the m a g n i t u d e s of e l e m e n t s in c o r r e s p o n d i n g rows and c o l u m n s are m a d e n e a r l y e q u a l by exact s i m i l a r i t y t r a n s f o r m a t i o n s , and e i g e n v a l u e s are i s o l a t e d by p e r m u t a t i o n s i m i l a r i t y transformations. B a l a n c i n g r e d u c e s the 1 - n o r m of the o r i g i n a l m a t r i x w h e n e v e r sums of the m a g n i t u d e s of e l e m e n t s in s o m e r o w and c o r r e s p o n d i n g c o l u m n are m a r k e d l y d i f f e r e n t , w h i l e at the s a m e time l e a v i n g the e i g e n v a l u e s u n c h a n g e d . R e d u c i n g the n o r m in this w a y can i m p r o v e the a c c u r a c y of the computed eigenvalues and/or eigenvectors.

2. U S A G E . A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

CBAL(NM,N,AR,AI,LOW,IGH,SCALE)

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

is an i n t e g e r i n p u t v a r i a b l e set equal to the row d i m e n s i o n of the t w o - d i m e n s i o n a l arrays AR and AI as s p e c i f i e d in the D I M E N S I O N s t a t e m e n t s for AR and AI in the c a l l i n g p r o g r a m .

N

is an i n t e g e r i n p u t v a r i a b l e set e q u a l the o r d e r of the m a t r i x A = (AR,AI). m u s t be n o t g r e a t e r than NM.

224

to N

7.1-30

AR,AI

are w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l variables with row dimension NM and c o l u m n d i m e n s i o n at l e a s t N. On input, AR and AI c o n t a i n the real and i m a g i n a r y parts, r e s p e c t i v e l y , of the c o m p l e x m a t r i x of o r d e r N to be b a l a n c e d . On o u t p u t , AR and AI c o n t a i n the real and i m a g i n a r y p a r t s of the transformed matrix.

LOW, IGH are i n t e g e r o u t p u t v a r i a b l e s i n d i c a t i n g the b o u n d a r y i n d i c e s for the b a l a n c e d m a t r i x . See s e c t i o n 3 for the d e t a i l s . SCALE

B.

Error

is a w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g i n f o r m a t i o n a b o u t the similarity transformations. See s e c t i o n 3 for the d e t a i l s .

Conditions

and

Returns.

None.

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

and

Restrictions.

It is p a r t i c u l a r l y a d v a n t a g e o u s to use CBAL whenever the sums of the m a g n i t u d e s of e l e m e n t s in some row and c o r r e s p o n d i n g c o l u m n are q u i t e d i f f e r e n t . Additionally, the e x e c u t i o n time for CBAL is s m a l l c o m p a r e d w i t h the e x e c u t i o n time for the r o u t i n e s w h i c h d e t e r m i n e the eigenvalues and/or eigenvectors. H e n c e it is r e c o m m e n d e d that CBAL be used g e n e r a l l y . The s u b r o u t i n e C B A B K 2 (F272) s h o u l d be u s e d to r e t r i e v e the e i g e n v e c t o r s of the o r i g i n a l m a t r i x a f t e r the e i g e n v e c t o r s of the t r a n s f o r m e d m a t r i x h a v e b e e n determined. In this i m p l e m e n t a t i o n , throughout.

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

OF M E T H O D

First CBAL s u c h that

AND

is

real

ALGORITHM.

determines

PAP

the a r i t h m e t i c

a product

=

P

(T

X

(0

B

Z)

(0

0

R)

225

Y)

of p e r m u t a t i o n

matrices

7.1-31

where T and R are u p p e r t r i a n g u l a r m a t r i c e s and B is a s q u a r e m a t r i x s i t u a t e d in r o w s and c o l u m n s LOW through IGH w i t h no zero o f f - d i a g o n a l r o w s or c o l u m n s . X, Y, and Z are r e c t a n g u l a r m a t r i c e s of a p p r o p r i a t e d i m e n s i o n s . The d i a g o n a l e l e m e n t s of T and R are the i s o l a t e d e i g e n v a l u e s of A. In the e x c e p t i o n a l c a s e w h e r e B is empty, LOW = 1 and IGH = 0 -- h o w e v e r , I is r e t u r n e d as the o u t p u t v a l u e of IGH. N e x t , the s u b r o u t i n e non-singular diagonal that

CBAL determines iteratively a real matrix D of o r d e r IGH-LOW+I such

-i D

BD

is a b a l a n c e d m a t r i x in the s e n s e that the sums of the m a g n i t u d e s of e l e m e n t s in c o r r e s p o n d i n g rows and c o l u m n s

of

-i D

BD

are n e a r l y equal° The d i a g o n a l the r a d i x of the f l o a t i n g p o i n t

e l e m e n t s of D are p o w e r s a r i t h m e t i c of the m a c h i n e .

U p o n c o m p l e t i o n of CBAL, the v e c t o r a r r a y SCALE contains the i n f o r m a t i o n a b o u t P and D n e c e s s a r y for CBABK2 to r e t r i e v e the e i g e n v e c t o r s of the o r i g i n a l m a t r i x f r o m the e i g e n v e c t o r s of the t r a n s f o r m e d m a t r i x . T h e i n f o r m a t i o n is e n c o d e d as f o l l o w s . I. The J-th and SCALE(J)-th rows and c o l u m n s of the o r i g i n a l m a t r i x h a v e b e e n p e r m u t e d for J = 1,2,...,LOW-I,IGH+I,IGH+2,...,N. 2. SCALE(J) is the (J-LOW+l)-th d i a g o n a l e l e m e n t of D for J = LOW,LOW+I,...,IGH. U p o n c o m p l e t i o n of CBAL, the o u t p u t m a t r i x is

( T ( 0

xo -1 D BD

( 0

0

Y

)

-1 D

Z ) R

).

This s u b r o u t i n e is a t r a n s l a t i o n of the A l g o l p r o c e d u r e CBALANCE w h i c h is the a n a l o g u e for c o m p l e x m a t r i c e s of procedure BALANCE w r i t t e n and d i s c u s s e d in d e t a i l by P a r l e t t and R e i n s c h (i).

226

the

of

7.1-32

4. REFERENCES.

~)

Parlett, B.N. and Reinsch, C., Balancing a M a t r i x for C a l c u l a t i o n of Eigenvalues and Eigenvectors, Num. Math. 13,293-304 (1969). (Reprinted in H a n d b o o k for Automatic Computation, Volume II, Linear Algebra, J. H. W i l k i n s o n - C. Reinsch, C o n t r i b u t i o n II/ll, 315-326, S p r i n g e r - V e r l a g , 1971.)

5. CHECKOUT. A.

Test

Cases.

See the section complex general

discussing matrices.

testing

of the codes

for

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

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

=

A MACHINE DEPENDENT PARAMETER OF THE MACHINE FLOATING POINT

SPECIFYING REPRESENTATION.

#

B2 = RADIX K = 1 L = N GO TO i00 • ********* 20

RADIX IS THE BASE

* RADIX

IN-LINE PROCEDURE FOR ROW COLUMN EXCHANGE ********** SCALE(M) = J I F (J . E Q ~ M ) G O T O 5 0

AND

DO

30

3 0 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 CONTINUE

DO

40

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) A I (M, I) = F CONTINUE

C 50 C C 80 C i00

GO TO (80,130), IEXC ********** SEARCH FOR ROWS ISOLATING AN EIGENVALUE AND PUSH THEM DOWN ********** IF (L .EQ. i) G O T O 2 8 0 L = L - I ********** FOR J=L STEP -I UNTIL i DO -- ********** D O 1 2 0 J J = i, L J = L + i - JJ DO

ii0

i i 0 i = I, L IF (I .EQ. J) G O IF ( A R ( J , I ) .NE. CONTINUE

TO ii0 0.0.0R~

228

AI(J,I)

.NE.

0.0)

GO

TO

120

7.1-34

120

M = L IEXC = 1 GO TO 20 CONTINUE

C GO TO 140 **********

C C 130

K

= K +

140

DO

170

SEARCH FOR COLUMNS AND PUSH THEM LEFT

ISOLATING **********

AN

EIGENVALUE

1

C J = K,

L

C DO

1 5 0 1 = K, L IF (I .EQ. J) G O IF ( A R ( I , J ) .NE. CONTINUE

150

170

180 190

TO 150 0 . 0 .OR.

AI(I,J)

.NE.

M = K IEXC = 2 GO TO 20 CONTINUE ********** NOW BALANCE THE SUBMATRIX IN ROWS D O 1 8 0 I = K, L SCALE(l) = 1.0 ********** ITERATIVE LOOP FOR NORM REDUCTION NOCONV = .FALSE. DO

2 7 0 1 = K, C=0.0 R=0.0

0.0)

GO

K

L

TO

TO

170

**********

**********

L

DO

200

210

220 230

2 0 0 J = K, L IF (J .EQ. I) G O T O 2 0 0 C = C + ABS(AR(J,I)) + ABS(AI(J,I)) R = R + ABS(AR(I,J)) + ABS(AI(I,J)) CONTINUE ********** GUARD AGAINST ZERO C OR R DUE IF (C .EQ. 0 . 0 .OR. R .EQ. 0 . 0 ) G O T O G = R / RADIX F = 1.0 S = C +R I F (C .GE. G) G O T O 2 2 0 F = F * RADIX C = C * B2 GO TO 210 G = R * RADIX IF (C .LT. G) G O T O 2 4 0 F = F / RADIX

C=C/B2 GO TO 230

229

TO UNDERFLOW 270

**********

7. 1 - 3 5

240

********** NOW BALANCE ********** IF ((C + R) / F .GE. 0 . 9 5 * S) G = 1.0 / F SCALE(I) = SCALE(I) * F NOCONV = ~TRUE. DO

2 5 0 J = K~ N AR(I,J) = AR(I,J) iI(I,J) = AI(I,J) CONTINUE

250

2 6 0 J = i, L AR(J,I) = AR(J,I) AI(J,I) = AI(J,I) CONTINUE

* G * G

DO

260 270

CONTINUE IF

280

* F * F

(NOCONV)

GO

TO

190

LOW = K IGH = L RETURN END

230

GO

TO

270

7.1-36

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F301

A Fortran

PACKAGE

(EISPACK)

CG

IV D r i v e r S u b r o u t i n e to D e t e r m i n e the E i g e n v a l u e s E i g e n v e c t o r s of a C o m p l e x G e n e r a l M a t r i x .

July,

and

1975

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e CG c a l l s the r e c o m m e n d e d s e q u e n c e of s u b r o u t i n e s f r o m the e i g e n s y s t e m s u b r o u t i n e p a c k a g e EISPACK to d e t e r m i n e the e i g e n v a l u e s and e i g e n v e c t o r s (if d e s i r e d ) of a c o m p l e x g e n e r a l m a t r i x .

2.

USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

CG(NM,N,AR,AI,WR,WI,MATZ, ZR,ZI,FVI,FV2,FV3,1ERR)

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

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to the row d i m e n s i o n of the t w o - d i m e n s i o n a l arrays AR, AI, ZR, and ZI as s p e c i f i e d in the D I M E N S I O N s t a t e m e n t s for AR, AI, ZR, and ZI in the c a l l i n g p r o g r a m . is an i n t e g e r i n p u t v a r i a b l e set e q u a l the o r d e r of the m a t r i x A = (AR,AI). m u s t not be g r e a t e r than NM.

AR,AI

to N

are w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l v a r i a b l e s w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at l e a s t N. On input, AR and AI c o n t a i n the r e a l and i m a g i n a r y parts, r e s p e c t i v e l y , of the c o m p l e x g e n e r a l m a t r i x of o r d e r N w h o s e e i g e n v a l u e s and e i g e n v e c t o r s are to be found. On o u t p u t , AR and AI have been destroyed.

231

7.1-37

WR,WI

are w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e s of d i m e n s i o n at l e a s t N c o n t a i n i n g the r e a l and i m a g i n a r y p a r t s , r e s p e c t i v e l y , of the e i g e n v a l u e s of the complex general matrix.

MATZ

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to zero if o n l y e i g e n v a l u e s are d e s i r e d ; o t h e r w i s e it is set to any n o n - z e r o i n t e g e r for b o t h e i g e n v a l u e s and e i g e n v e c t o r s .

ZR,ZI

are, if MATZ is n o n - z e r o , w o r k i n g precision real output two-dimensional variables with row dimension NM and c o l u m n d i m e n s i o n at l e a s t N c o n t a i n i n g the r e a l and i m a g i n a r y p a r t s , r e s p e c t i v e l y , of the eigenvectors. T h e e i g e n v e c t o r s a r e not normalized. If MATZ is zero, ZR and ZI are not r e f e r e n c e d and can be d u m m y variables.

FVI,FV2,FV3 are w o r k i n g dimensional N. IERR

B. E r r o r

precision variables

t e m p o r a r y oneof d i m e n s i o n at

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

Conditions

subroutine

If m o r e t h a n 30 i t e r a t i o n s are r e q u i r e d an e i g e n w a l u e , the s u b r o u t i n e t e r m i n a t e s e q u a l to the i n d e x of the e i g e n v a l u e for failure occurs. The e i g e n v a l u e s in the a r r a y s s h o u l d be c o r r e c t for i n d i c e s I E R R + I , I E R R + 2 , . . . , N , b u t no e i g e n v e c t o r s If all the e i g e n v a l u e s are d e t e r m i n e d iterations, IERR is set to zero.

Applicability

and

to is

and R e t u r n s .

If N is g r e a t e r t h a n NM, the with IERR set e q u a l to 10*N.

C.

least

terminates

to d e t e r m i n e with IERR set w h i c h the WR and WI are

within

computed. 30

Restrictions.

T h i s s u b r o u t i n e can be u s e d to f i n d all the e i g e n v a l u e s and all the e i g e n v e c t o r s (if d e s i r e d ) of a c o m p l e x general matrix.

232

7. 1 - 3 8

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

OF M E T H O D

AND

ALGORITHM.

This s u b r o u t i n e calls the r e c o m m e n d e d s e q u e n c e of s u b r o u t i n e s from EISPACK to find the e i g e n v a l u e s and e i g e n v e c t o r s of a c o m p l e x g e n e r a l matrix. To

find

e i g e n v a l u e s only, the s e q u e n c e is the f o l l o w i n g . to b a l a n c e a c o m p l e x g e n e r a l m a t r i x , CORTH to r e d u c e the b a l a n c e d m a t r i x to an upper Hessenberg matrix using unitary transformations. COMQR - to d e t e r m i n e the e i g e n v a l u e s of the o r i g i n a l m a t r i x f r o m the H e s s e n b e r g matrix. C B A L

To find e i g e n v a l u e s and e i g e n v e c t o r s , the s e q u e n c e is the following. C B A L to b a l a n c e a c o m p l e x g e n e r a l matrix. CORTH - to r e d u c e the b a l a n c e d m a t r i x to an u p p e r Hessenberg matrix using unitary transformations. COMQR2 - to d e t e r m i n e the e i g e n v a l u e s and e i g e n v e c t o r s of the b a l a n c e d m a t r i x f r o m the H e s s e n b e r g matrix. C B A B K 2 to b a c k t r a n s f o r m the e i g e n v e c t o r s to those of the o r i g i n a l m a t r i x .

4.

REFERENCES. i)

5.

G a r b o w , B.S. April, 1974.

and

Dongarra,

J.J.,

EISPACK

Path

Chart,

CHECKOUT. A.

Test

Cases.

See the complex

section general

discussing matrices.

testing

of

the

codes

for

B. A c c u r a c y . The a c c u r a c y of CG can be b e s t d e s c r i b e d in terms of its r o l e in those paths of E I S P A C K (I) w h i c h find e i g e n v a l u e s and e i g e n v e c t o r s of c o m p l e x g e n e r a l matrices. In these paths, this s u b r o u t i n e is n u m e r i c a l l y stable. This s t a b i l i t y c o n t r i b u t e s to the p r o p e r t y of these paths that each c o m p u t e d e i g e n v a l u e and its c o r r e s p o n d i n g e i g e n v e c t o r are exact for a m a t r i x c l o s e to the o r i g i n a l m a t r i x .

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 A R ( N M , N ) , A I ( N M , N ) , W R ( N ) , W I ( N ) , Z R ( N M , N ) , Z I ( N M , N ) , $ FVI(N),FV2(N),FV3(N) IF ( N o L E . !ERR = i 0 GO TO 50

NM) *

GO TO

I0

N

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 * * * * * * * * * * F I N D E I G E N V A L U E S ONLY * * * * * * * * * * CALL C O M Q R ( N M , N , I S I , I S 2 , A R , A I , W R , W I , IERR) GO TO 50 * * * * * * * * * * F I N D B O T H E I G E N V A L U E S AND E I G E N V E C T O R S ********** 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 R E T U R N END

234

7.1-40

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F302

A Fortran

PACKAGE

(EISPACK)

CH

IV D r i v e r S u b r o u t i n e to D e t e r m i n e the E i g e n v a l u e s E i g e n v e c t o r s of a C o m p l e x H e r m i t i a n M a t r i x .

July,

and

1975

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e CH calls the r e c o m m e n d e d s e q u e n c e of s u b r o u t i n e s f r o m the e i g e n s y s t e m s u b r o u t i n e p a c k a g e EISPACK to d e t e r m i n e the e i g e n v a l u e s and e i g e n v e e t o r s (if d e s i r e d ) of a c o m p l e x H e r m i t i a n m a t r i x .

2. USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

CH(NM,N,AR,AI,W,MATZ, ZR,ZI,FVI,FV2,FMI,IERR)

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

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to the row d i m e n s i o n of the t w o - d i m e n s i o n a l arrays AR, AI, ZR, and ZI as s p e c i f i e d in the D I M E N S I O N s t a t e m e n t s for AR, AI, ZR, and ZI in the c a l l i n g p r o g r a m . is an i n t e g e r i n p u t v a r i a b l e set e q u a l the order of the m a t r i x A = (AR,AI). m u s t not be g r e a t e r than NM.

AR,AI

to N

are w o r k i n g p r e c i s i o n real t w o - d i m e n s i o n a l variables with row dimension NM and c o l u m n d i m e n s i o n at l e a s t N. On input, AR and AI c o n t a i n the r e a l and i m a g i n a r y p a r t s , r e s p e c t i v e l y , of the c o m p l e x H e r m i t i a n m a t r i x of o r d e r N w h o s e e i g e n v a l u e s and

235

7. 1-41

e i g e n v e c t o r s are to be f o u n d . O n l y the f u l l l o w e r t r i a n g l e of AR and the s t r i c t lower t r i a n g l e of AI n e e d be s u p p l i e d . On o u t p u t , the f u l l u p p e r t r i a n g l e of AR and the s t r i c t u p p e r t r i a n g l e of Ai are unaltered.

B.

Error

W

is a w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g the e i g e n v a l u e s of the c o m p l e x H e r m i t i a n m a t r i x in a s c e n d i n g order.

MATZ

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to zero if o n l y e i g e n v a l u e s are d e s i r e d ; o t h e r w i s e it is set to any n o n - z e r o i n t e g e r for b o t h e i g e n v a l u e s and e i g e n v e c t o r s .

ZR,ZI

are, if MATZ is n o n - z e r o , w o r k i n g precision real output two-dimensional variables with row dimension NM and c o l u m n d i m e n s i o n at l e a s t N c o n t a i n i n g the r e a l and i m a g i n a r y p a r t s , r e s p e c t i v e l y , of the eigenvectors. The e i g e n v e c t o r s are orthonormal. If MATZ is zero, ZR and ZI are n o t r e f e r e n c e d and can be d u m m y variables.

FVI,FV2

are w o r k i n g dimensional N.

precision variables

temporary oneof d i m e n s i o n at

least

FMI

is a w o r k i n g p r e c i s i o n t e m p o r a r y twod i m e n s i o n a l v a r i a b l e w i t h row d i m e n s i o n and c o l u m n d i m e n s i o n at l e a s t N.

!ERR

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

Conditions

to is

and R e t u r n s .

If N is g r e a t e r t h a n NM, the with IERR set e q u a l to 10*N.

subroutine

terminates

If m o r e t h a n 30 i t e r a t i o n s are r e q u i r e d to d e t e r m i n e an e i g e n v a l u e , the s u b r o u t i n e t e r m i n a t e s w i t h IERR set e q u a l to the i n d e x of the e i g e n v a l u e for w h i c h the failure occurs. The e i g e n v a l u e s in the W array should be c o r r e c t for i n d i c e s 1 , 2 , . . . , I E R R - I , but no e i g e n v e c t o r s are c o m p u t e d .

236

7.1-42

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

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

within

30

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

This s u b r o u t i n e can be u s e d to find all the e i g e n v a l u e s and all the e i g e n v e c t o r s (if d e s i r e d ) of a c o m p l e x Hermitian matrix.

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

OF M E T H O D

AND

ALGORITHM.

T h i s s u b r o u t i n e calls the r e c o m m e n d e d s e q u e n c e of s u b r o u t i n e s from EISPACK to find the e i g e n v a l u e s and e i g e n v e c t o r s of a complex Hermitian matrix. To

find e i g e n v a l u e s only, the s e q u e n c e is the f o l l o w i n g . HTRIDI to r e d u c e a c o m p l e x H e r m i t i a n m a t r i x to a r e a l symmetric tridiagonal matrix using unitary transformations. T Q L R A T - to d e t e r m i n e the e i g e n v a l u e s of the o r i g i n a l m a t r i x f r o m the real s y m m e t r i c t r i d i a g o n a l matrix. -

To find e i g e n v a l u e s and e i g e n v e c t o r s , the s e q u e n c e is the following. HTRIDI to r e d u c e a c o m p l e x H e r m i t i a n m a t r i x to a r e a l symmetric tridiagonal matrix using unitary transformations. TQL2 - to d e t e r m i n e the e i g e n v a l u e s and e i g e n v e e t o r s of the real s y m m e t r i c t r i d i a g o n a l m a t r i x . HTRIBK to b a c k t r a n s f o r m the e i g e n v e c t o r s to those of the o r i g i n a l m a t r i x . -

-

4.

REFERENCES. i)

5.

G a r b o w , B.S. A p r i l , 1974.

and

Dongarra,

J.J.,

EISPACK

Path

Chart,

CHECKOUT. A.

Test

Cases.

See the s e c t i o n d i s c u s s i n g t e s t i n g complex Hermitian matrices. B. A c c u r a c y .

237

of

the

codes

for

7. 1-43

The a c c u r a c y of CH can b e s t b e d e s c r i b e d in terms of its r o l e in t h o s e p a t h s of E I S P A C K (I) w h i c h find e i g e n v a l u e s and e i g e n v e c t o r s of c o m p l e x H e r m i t i a n matrices. In t h e s e p a t h s , this s u b r o u t i n e is numerically stable. This s t a b i l i t y c o n t r i b u t e s to the p r o p e r t y of t h e s e p a t h s that the c o m p u t e d e i g e n v a l u e s are the e x a c t e i g e n v a l u e s of a m a t r i x c l o s e to the o r i g i n a l m a t r i x and the c o m p u t e d e i g e n v e c t o r s are c l o s e (but not n e c e s s a r i l y equal) to the e i g e n v e c t o r s of that matrix,

238

7.1-44

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) I E R R = i0 * N GO TO 50

GO TO

i0

C i0 C A L L HTRIDI(NM,N,AR,AI,W,FVI,FV2,FMI) IF ( M A T Z .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 DO 30

30 J = i, N Z R ( J , I ) = 0.0 CONTINUE

ZR(I,I) 40

= 1.0

CONTINUE

CALL TQL2(NM,N,W,FVI,ZR,IERR) IF ( I E R R .NE. 0) GO TO 50 CALL HTR!BK(NM,N,AR,AI,FMI,N,ZR,ZI) 50 R E T U R N END

239

**********

7.1-45

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F297-2

PACKAGE CINVIT

A F o r t r a n IV S u b r o u t i n e to D e t e r m i n e T h o s e Upper Hessenberg Matrix Corresponding

May, July,

(EISPACK)

Eigenvectors to S p e c i f i e d

of a C o m p l e x Eigenvalues.

1972 1975

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e CINVIT c o m p u t e s the e i g e n v e c t o r s of a c o m p l e x upper H e s s e n b e r g m a t r i x c o r r e s p o n d i n g to s p e c i f i e d e i g e n v a l u e s using i n v e r s e i t e r a t i o n .

2. USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

CINVlT(NM, N,AR,A!,WR,WI,SELECT, MM,M,ZR,ZI,IERR,RMI,RM2,RVI,RV2)

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

is an i n t e g e r input v a r i a b l e set equal to the row d i m e n s i o n of the t w o - d i m e n s i o n a l arrays AR, AI, ZR, and ZI as s p e c i f i e d in the D I M E N S I O N s t a t e m e n t s for AR, AI, ZR, and ZI in the c a l l i n g p r o g r a m .

N

is an i n t e g e r input v a r i a b l e set equal the order of the m a t r i x A = (AR,AI). m u s t be not g r e a t e r t h a n NM.

AReAl

are w o r k i n g p r e c i s i o n real input twod i m e n s i o n a l v a r i a b l e s w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at least N containing the r e a l and i m a g i n a r y parts 3 r e s p e c t i v e l y ~ of the c o m p l e x u p p e r H e s s e n b e r g matrix.

240

to N

7.1-46

WR,WI

are working precision real o n e - d i m e n s i o n a l v a r i a b l e s of d i m e n s i o n at least N. On input, they contain the real and imaginary parts, respectively, of the eigenvalues of the H e s s e n b e r g matrix. The eigenvalues need not be ordered, except that eigenvalues of any submatrix of the input H e s s e n b e r g m a t r i x must have indices in WR,WI w h i c h lie between the b o u n d a r y 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 i n d e p e n d e n t eigenvectors.

SELECT

is a logical input o n e - d i m e n s i o n a l v a r i a b l e 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 v a r i a b l e set equal to the number of columns actually used to store the eigenvectors.

ZR,ZI

are working p r e c i s i o n real output twod i m e n s i o n a l variables with row d i m e n s i o n NM and column d i m e n s i o n at least MM containing the real and imaginary parts, respectively, of the eigenvectors c o r r e s p o n d i n g to the flagged eigenvalues. The eigenvectors are packed into the columns of ZR and ZI starting at the first columns.

IERR

is an integer output variable set equal an error completion code described in section 2B. The normal completion code zero.

RMI,RM2

to is

are w o r k i n g p r e c i s i o n real temporary array variables of dimension at least N*N. These arrays holds the triangularized form of the upper H e s s e n b e r g m a t r i x used in the inverse iteration process.

241

7.1-47

RVI,RV2

B.

Error

are w o r k i n g p r e c i s i o n r e a l t e m p o r a r y o n e d i m e n s i o n a l v a r i a b l e s of d i m e n s i o n at l e a s t N. T h e y h o l d the a p p r o x i m a t e e i g e n v e c t o r s d u r i n g the i n v e r s e i t e r a t i o n p r o c e s s .

Conditions

and

Returns~

If m o r e than MM e i g e n v e c t o r s are r e q u e s t e d , CINVIT terminates with IERR set to -(2*N+I) and w i t h the In first MM e i g e n v e c t o r s in the a r r a y s ZR and ZI. this c a s e , M = MM. If n o n e of the i n i t i a l v e c t o r s for the i n v e r s e i t e r a t i o n p r o c e s s p r o d u c e s an a c c e p t a b l e a p p r o x i m a t i o n to an eigenvector, CINVIT t e r m i n a t e s the c o m p u t a t i o n for t h a t e i g e n v e c t o r and sets IERR to -K where K is the i n d e x of the a s s o c i a t e d e i g e n v a l u e . If this f a i l u r e o c c u r s for m o r e t h a n one e i g e n v a l u e , the last o c c u r r e n c e is r e c o r d e d in IERR. T h e c o l u m n s of ZR and ZI c o r r e s p o n d i n g to f a i l u r e s of the a b o v e sort are set to zero v e c t o r s . If b o t h of the a b o v e e r r o r c o n d i t i o n s o c c u r , CINVIT terminates with IERR set to -(N+K) where K is the i n d e x of the last e i g e n v a l u e w h o s e i n v e r s e i t e r a t i o n process failed. The c o l u m n s of ZR and ZI c o r r e s p o n d i n g to f a i l u r e s in the i n v e r s e i t e r a t i o n p r o c e s s are set to z e r o v e c t o r s , and in this case, M = MM. If n e i t h e r sets IERR

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

of the a b o v e to zero.

and

error

conditions

occurs,

CINVIT

Restrictions.

To d e t e r m i n e e i g e n v e c t o r s c o r r e s p o n d i n g to some of the e i g e n v a l u e s of a c o m p l e x g e n e r a l m a t r i x , CINVlT should be p r e c e d e d by C O M H E S (F282) and C O M L R (F295). COMHES provides a suitable complex upper Hessenberg m a t r i x for CINVIT and COMLR d e t e r m i n e s the e i g e n v a l u e s of this H e s s e n b e r g m a t r i x . CINVIT should t h e n be f o l l o w e d by C O M B A K (F283) to b a c k t r a n s f o r m the e i g e n v e c t o r s f r o m CINVIT into t h o s e of the original matrix. Note: the u p p e r H e s s e n b e r g m a t r i x m u s t be s a v e d b e f o r e COMLR, since COMLR d e s t r o y s this p a r t of A = (AR,AI). It is r e c o m m e n d e d in g e n e r a l t h a t C B A L (F271) be u s e d before COMHES in w h i c h c a s e C B A B K 2 (F272) m u s t be used after COMBAK.

242

7.1-48

In this i m p l e m e n t a t i o n , the a r i t h m e t i c t h r o u g h o u t e x c e p t for c o m p l e x d i v i s i o n a b s o l u t e value.

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

OF M E T H O D

AND

is r e a l and c o m p l e x

ALGORITHM.

The e i g e n v e c t o r s are d e t e r m i n e d by i n v e r s e i t e r a t i o n . In CINVIT, this is a p r o c e s s w h e r e b y a v e c t o r XI satisfying the m a t r i x l i n e a r e q u a t i o n U ' X 1 = X0 is c o m p u t e d , w h e r e X0 is an i n i t i a l v e c t o r and U is the u p p e r t r i a n g u l a r f a c t o r in the LU d e c o m p o s i t i o n of the m a t r i x B-W*I with partial pivoting. W is an a p p r o x i m a t e e i g e n v a l u e of a leading submatrix B of the H e s s e n b e r g m a t r i x in A. The vector X1 is a c c e p t e d as an e i g e n v e c t o r of B if the n o r m of XI is s u f f i c i e n t l y l a r g e r than the n o r m of X0. This e i g e n v e c t o r of B is t r a n s f o r m e d to an e i g e n v e c t o r of A by s i m p l y a p p e n d i n g zero c o m p o n e n t s to it. The r e a l and i m a g i n a r y p a r t s of U are s t o r e d in the two real a r r a y s RMI and RM2 respectively. Internally, RMI and RM2 are t r e a t e d as t w o - d i m e n s i o n a l NxN arrays. T h e a c c e p t a n c e c r i t e r i o n for X1 is a g r o w t h test of its norm. If MACHEP d e n o t e s the r e l a t i v e m a c h i n e p r e c i s i o n , then c u r r e n t l y , XI is r e j e c t e d as an e i g e n v e c t o r if SQRT(UK)*!!B!!*MACHEP*!!XI!!

.LT.

!!X0!!/10.0

where UK is the order of the s u b m a t r i x B whose e i g e n v e c t o r is b e i n g c o m p u t e d and the n o r m !! !! is the i n f i n i t y norm. At m o s t UK orthogonal initial vectors XO are t r i e d to o b t a i n the r e q u i r e d growth. If no v e c t o r is a c c e p t e d , the p a r a m e t e r IERR is set to i n d i c a t e this f a i l u r e and CINVIT p r o c e e d s to c o m p u t e the n e x t eigenvector. The r e a l p a r t s of close or i d e n t i c a l e i g e n v a l u e s w h o s e e i g e n v e c t o r s are d e s i r e d m a y be p e r t u r b e d s l i g h t l y in an a t t e m p t to o b t a i n i n d e p e n d e n t e i g e n v e c t o r s (if they exist). If r e q u i r e d , s u c h p e r t u r b a t i o n s are p o s i t i v e and s m a l l m u l t i p l e s of MACHEP*I!B!!. This s u b r o u t i n e is a t r a n s l a t i o n of the A l g o l p r o c e d u r e CX I N V I T w r i t t e n and d i s c u s s e d in d e t a i l by P e t e r s and W i l k i n s o n (i).

243

7. 1-49

4. REFERENCE$~

1)

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

for

5. CHECKOUT. Ao Test

Cases°

See the section c o m p l e x general

discussing matrices~

testing

of the

codes

for

Bo Accuracy° The accuracy of CINVIT can best be described in terms of its role in those paths of EISPACK which find e i g e n v a l u e s and e i g e n v e c t o r s of complex upper H e s s e n b e r g matrices. In these paths, this s u b r o u t i n e is n u m e r i c a l l y stable (i). This stability c o n t r i b u t e s to the p r o p e r t y of these paths that each computed e i g e n v a l u e and its c o r r e s p o n d i n g e i g e n v e c t o r are exact for a m a t r i x close to the original upper H e s s e n b e r g matrix~

244

7 • 1-50

SUBROUTINE

CINVIT(NM,N,AR,AI,WR,WI,SELECT,MM,M,ZR,ZI, IERR,RMI,RM2,RVI,RV2)

X

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) C O M P L E X Z3 COMPLEX CMPLX REAL REAL,AIMAG **********

MACHEP

=

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

?

IERR = 0 UK = 0 S = I DO

C

C C

9 8 0 K = i, N IF ( . N O T . S E L E C T ( K ) ) GO TO 980 IF (S .GT. MM) GO TO i 0 0 0 IF (UK .GE. K) G O TO 2 0 0 ********** CHECK FOR POSSIBLE SPLITTING ********** DO 120 U K = K, N IF (UK .EQ. N) G O TO 140 IF ( A R ( U K + I , U K ) .EQ. 0 . 0 .AND. A I ( U K + I , U K ) .EQ. X GO T O 140 120 CONTINUE ********** C O M P U T E I N F I N I T Y N O R M OF L E A D I N G U K BY U K (HESSENBERG) MATRIX ********** 140 N O R M = 0.0 MP = I DO

160

180 X =

I = 0.0

i,

0.0)

UK

DO 160 J = MP, U K X = X + CABS(CMPLX(AR(I,J),AI(I,J)))

C

180

IF (X °GT. N O R M ) N O R M = X MP = I CONTINUE ********** EPS3 REPLACES Z E R O P I V O T IN D E C O M P O S I T I O N AND CLOSE ROOTS ARE MODIFIED BY E P S 3 * * * * * * * * * * IF ( N O R M .EQ. 0.0) N O R M = 1.0 EPS3 = MACHEP * NORM

245

7.1-51

C

200

C C 220 C 240

260

********** GROWTO IS T H E C R I T E R I O N FOR GROWTH ********** UKROOT = SQRT(FLOAT(UK)) GROWTO = I,OE-I / UKROOT RLAMBD = WR(K) ILAMBD = WI(K) IF (K .EQ. i) G O T O 2 8 0 KMI = K - 1 GO TO 240 ********** PERTURB EIGENVALUE IF IT IS C L O S E TO ANY PREVIOUS EIGENVALUE ********** RLAMBD = RLAMBD + EPS3 ********** FOR I=K-I STEP -I UNTIL 1 DO -- ********** D O 2 6 0 II = i~ K M I I = K - II I F (SELECT(I) . A N D . A B S ( W R ( I ) - R L A M B D ) .LT. E P S 3 .AND. ABS(WI(I)-ILAMBD) .LT. E P S 3 ) G O T O 2 2 0 X CONTINUE

C WR(K) = RLAMBD ********** FORM UPPER HESSENBERG (AR,AI)-(RLAMBD,ILAMBD)*I AND INITIAL COMPLEX VECTOR ********** MP = I

C C 280 C

DO

320

I =

i,

UK

C DO

300 J = MP, UK RMI(i,J) = AR(I,J) RM2(I,J) = AI(I,J) CONTINUE

300

RMI(I,I) = RMI(I,I) - RLAMBD RM2(I,I) = RM2(I,I) - ILAMBD MP = I RVI(1) = EPS3 CONTINUE ********** TRIANGULAR DECOMPOSITION REPLACING ZERO PIVOTS BY I F ( U K oEQ. I) G O T O 4 2 0

320

DO

X

4 0 0 ! = 2, U K MP = I - 1 IF ( C A B S ( C M P L X ( R M I ( I , M P ) , R M 2 ( ! , M P ) ) ) CABS(CMPLX(RMI(MP,MP),RM2(MP,MP)))) DO

340

WITH EPS3

340 J = MP, UK Y = RMI(I,J) R M I (I, J) = R M I (MP, J) RMI(MP,J) = Y Y = RM2(I,J) R M 2 (I, J) = R M 2 (MP, J) R M 2 (MP, J) = Y CONTINUE

246

INTERCHANGES, **********

.LE. GO

TO

360

7.1-52

IF

(RMI(MP,MP) .EQ. 0 . 0 . A N D . R M 2 ( M P , M P ) .EQ. RMI(MP,MP) = EPS3 Z3 = C M P L X ( R M I ( I , M P ) , R M 2 ( I , M P ) ) / CMPLX(RMI(MP,MP),RM2(MP,MP)) X = REAL(Z3) Y = AIMAG(Z3) IF (X .EQ. 0 . 0 . A N D . Y .EQ. 0 . 0 ) G O T O 4 0 0

360 X X

DO

380 J = RMI(I,J) RM2(I,J) CONTINUE

380 400

680 J X = X Y = Y CONTINUE

680

* RM2(MP,J) * RMI(MP,J)

IPI, UK - RMI(I,J) - RMI(I,J)

=

* RVI(J) * RV2(J)

+ RM2(I,J) - RM2(I,J)

Z3 = C M P L X ( 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 = I T S + 1 NORM = 0.0 NORMV = 0.0 DO

760 780

+ Y - Y

(RMI(UK,UK) .EQ. 0 . 0 . A N D . R M 2 ( U K , U K ) .EQ. 0 . 0 ) RMI(UK,UK) = EPS3 ITS = 0 ********** BACK SUBSTITUTION F O R I--UK S T E P -i U N T I L 1 DO -- * * * * * * * * * * D O 720 II = i, U K I = U K + 1 - II X = R V I (I) Y = 0.0 IF (I .EQ. U K ) G O T O 7 0 0 IPI = I + i DO

720

* RMI(MP,J) * RM2(MP,J)

IF

X

700

- X - X

CONTINUE

420

660

I, U K = RMI(I,J) = RM2(I,J)

0.0)

7 8 0 1 = i, U K X = CABS (CMPLX(RVI IF ( N O R M V .GE. X) NORMV = X J = I NORM = NORM + X CONTINUE IF

(NORM

.LT.

GROWTO)

(I), R V 2 ( I ) ) ) G O TO 7 6 0

GO

247

TO

840

* RV2(J) * RVI(J)

7.1-53

********** ACCEPT X = R V I (J) Y = R V 2 (J)

VECTOR

**********

DO

8 2 0 i = i, U K Z3 = CMPLX(RVI(1),RV2(1)) ZR(I,S) = REAL(Z3) ZI(I,S) = AIMAG(Z3) CONTINUE

820

840

I F ( U K .EQ. N) G O T O 9 4 0 J = UK + 1 GO TO 900 ********** IN-LINE PROCEDURE FOR A NEW STARTING VECTOR I F ( I T S .GE. U K ) G O T O 8 8 0 X = UKROOT Y = E P S 3 / (X + 1 . 0 ) RVI(1) = EPS3 DO

860

860

1 =

RVI(I)

=

2,

/ CMPLX(X,Y)

CHOOSING **********

UK

Y

920

J = UK - ITS + 1 RVI(J) = RVI(J) - EPS3 * X GO TO 660 • ********* SET ERROR -- UNACCEPTED EIGENVECTOR J = I IERR = -K • ********* SET REMAINING VECTOR COMPONENTS TO D O 9 2 0 I = J, N ZR(I,S) = 0.0 Zi(I,S) = 0.0 CONTINUE

940 980

S = S + CONTINUE

880

900

I000

IF IF

(IERR (IERR I001M = S - i RETURN END

ZERO

1

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

C C

**********

SET ERROR -- UNDERESTIMATE SPACE REQUIRED ********** .NE. 0) I E R R = I E R R - N oEQ. 0) I E R R = - ( 2 * N + i)

248

OF

EIGENVECTOR

**********

7.1-54

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F283-2

A Fortran of that

PACKAGE

(EISPACK)

COMBAK

IV S u b r o u t i n e to B a c k T r a n s f o r m the E i g e n v e c t o r s U p p e r H e s s e n b e r g M a t r i x D e t e r m i n e d by COMHES.

May, July,

1972 1975

I. P U R P O S E . The F o r t r a n IV s u b r o u t i n e COMBAK forms the e i g e n v e c t o r s of a c o m p l e x g e n e r a l m a t r i x f r o m the e i g e n v e c t o r s of that u p p e r ~ e s s e n b e r g m a t r i x d e t e r m i n e d by COMHES (F282).

2. USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

COMBAK(NM,LOW, IGH,AR,AI,INT,M,ZR,ZI)

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

is an i n t e g e r input v a r i a b l e set equal to the row d i m e n s i o n of the t w o - d i m e n s i o n a l arrays AR, AI, ZR, and ZI as s p e c i f i e d in the D I M E N S I O N s t a t e m e n t s for AR, AI, ZR, and ZI in the c a l l i n g program.

LOW, IGH

are i n t e g e r input v a r i a b l e s i n d i c a t i n g the b o u n d a r y i n d i c e s for the b a l a n c e d matrix. See s e c t i o n 3 of F271 for the details. If the m a t r i x is not b a l a n c e d , set LOW to i and IGH to the order of the matrix.

AR,AI

are w o r k i n g p r e c i s i o n real input twod i m e n s i o n a l v a r i a b l e s w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at least IGH. Their lower t r i a n g l e s b e l o w the s u b d i a g o n a l c o n t a i n the m u l t i p l i e r s w h i c h w e r e u s e d in

249

7.1-55

the r e d u c t i o n to the H e s s e n b e r g form. The r e m a i n i n g u p p e r p a r t s of AR and AI are arbitrary. See s e c t i o n 3 of F282 for the details.

B.

Error

INT

is an i n t e g e r i n p u t o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t IGH. INT identifies the rows a n d c o l u m n s i n t e r c h a n g e d d u r i n g the r e d u c t i o n by COMHES. See s e c t i o n 3 of F282 for the d e t a i l s .

M

is an i n t e g e r input v a r i a b l e set e q u a l the n u m b e r of c o l u m n s of Z = (ZR,ZI) back transformed.

ZR,ZI

are w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l v a r i a b l e s w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at l e a s t M. On i n p u t , the f i r s t M c o l u m n s of ZR and ZI c o n t a i n the r e a l and i m a g i n a r y p a r t s , r e s p e c t i v e l y , of the e i g e n v e c t o r s to be b a c k t r a n s f o r m e d . On output, these M c o l u m n s of ZR and ZI c o n t a i n the r e a l and i m a g i n a r y p a r t s of the transformed eigenvectors.

Conditions

and

to to be

Returns.

None.

C.

Applicability

and

Restrictions.

This s u b r o u t i n e s h o u l d be u s e d subroutine C O M H E S (F282).

3.

DISCUSSION

OF M E T H O D

AND

in c o n j u n c t i o n

with

the

ALGORITHM.

C (say) has b e e n r e d u c e d to the S u p p o s e that the m a t r i x s t o r e d in A by the s i m i l a r i t y upper Hessenberg form F transformation -i F = G

CG

where G is a p r o d u c t of the p e r m u t a t i o n and e l e m e n t a r y m a t r i c e s e n c o d e d in INT a n d in a l o w e r t r i a n g l e of A under F respectively. Then, g i v e n an a r r a y Z of c o l u m n vectors, COMBAK c o m p u t e s the m a t r i x p r o d u c t GZ. If the e i g e n v e c t o r s of F are c o l u m n s of the a r r a y Z, then COMBAK f o r m s the e i g e n v e c t o r s of C in their place.

250

7.1-56

This subroutine COMBAK written W i l k i n s o n (I).

is a translation of the Algol p r o c e d u r e and discussed in detail by M a r t i n and

4. REFERENCES.

1)

Martin, R.S. and Wilkinson, J.H., Similarity Reduction of a General M a t r i x to H e s s e n b e r g Form, Num. Math. 12,349-368 (1968). (Reprinted in H a n d b o o k for Automatic Computation, Volume II, Linear Algebra, J. H. W i l k i n s o n - C. Reinsch, C o n t r i b u t i o n 11/13, 339-358, S p r i n g e r - V e r l a g , 1971.)

5. CHECKOUT. A. Test

Cases.

See the section complex general

discussing matrices.

testing

of the codes

for

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 s u b r o u t i n e is, in practice, n u m e r i c a l l y stable (i). This stability contributes to the property of these paths that each computed eigenvalue and its c o r r e s p o n d i n g eigenvector are exact for a matrix usually close to the original matrix.

251

7.1-57

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) G O T O 2 0 0 LA = IGH - 1 KPI = LOW + 1 IF ( L A .LT. K P I ) G O T O 2 0 0 ********** FOR MP=IGH-I STEP DO 140 M M = K P I , L A MP = LOW + IGH - MM MPI = MP + i DO

ii0 I = M P I , IGH XR = AR(I,MP-I) Xi = A I ( I , M P - I ) IF (XR .EQ. 0 . 0 . A N D . DO

i00 J = ZR(I,J) Zl(l,J) CONTINUE

i00

i, M = ZR(I,J) = ZI(I,J)

XI

+ +

C Ii0

CONTINUE

C I = !NT(MP) IF (! .EQ. M P )

GO

TO

140

DO

130

1 3 0 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

-i

252

XR XR

UNTIL

.EQ.

LOW+I

0.0)

* ZR(MP,J) * ZI(MP,J)

GO

DO

--

TO

ii0

- XI + Xl

**********

* ZI(MP,J) * ZR(MP,J)

7.1-58

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F282-2

A Fortran

PACKAGE

(EISPACK)

COMHES

IV S u b r o u t i n e to R e d u c e a C o m p l e x G e n e r a l to C o m p l e x U p p e r H e s s e n b e r g F o r m U s i n g Elementary Transformations.

May, July,

Matrix

1972 1975

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e COMHES reduces a complex general m a t r i x to c o m p l e x upper H e s s e n b e r g f o r m u s i n g s t a b i l i z e d elementary similarity transformations. This r e d u c e d f o r m is u s e d ' b y o t h e r s u b r o u t i n e s to f i n d the e i g e n v a l u e s a n d / o r e i g e n v e c t o r s of the o r i g i n a l matrix. See s e c t i o n 2C for the specific routines.

2. USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

COMHES(NM,N,LOW~IGH,AR,AI,INT)

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

is an i n t e g e r input v a r i a b l e set e q u a l to the row d i m e n s i o n of the t w o - d i m e n s l o n a l arrays AR and AI as s p e c i f i e d in the D I M E N S I O N s t a t e m e n t s for AR and AI in the c a l l i n g program. is an i n t e g e r input v a r i a b l e set e q u a l the order of the m a t r i x A = (AR,AI). m u s t be not g r e a t e r than NM.

LOW,IGH

to N

are integer input v a r i a b l e s i n d i c a t i n g the b o u n d a r y i n d i c e s for the b a l a n c e d matrix. See s e c t i o n 3 of F271 for the details. If the m a t r i x is not b a l a n c e d , set LOW to 1 and IGH to N.

253

7.1-59

B°

Error

AR,A!

are w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l v a r i a b l e s w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at least N. On input, AR and AI c o n t a i n the real and i m a g i n a r y parts, respectively, of the c o m p l e x m a t r i x of o r d e r N to be r e d u c e d to H e s s e n b e r g form. On output, AR and AI c o n t a i n the real and i m a g i n a r y p a r t s of the upper H e s s e n b e r g m a t r i x as w e l l as the m u l t i p l i e r s u s e d in the r e d u c t i o n . See s e c t i o n 3 for the details.

INT

is an i n t e g e r o u t p u t o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least IGH i d e n t i f y i n g the rows and c o l u m n s i n t e r c h a n g e d d u r i n g the r e d u c t i o n . See s e c t i o n 3 for the d e t a i l s . Only components LOW+I through IGH-I are a c t u a l l y u s e d by COMHES.

Conditions

and

Returns.

None°

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

and

Restrictions.

If all the e i g e n v a l u e s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e s h o u l d be f o l l o w e d by COMLR (F295). If all the m a t r i x are by COMLR2

e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l d e s i r e d , this s u b r o u t i n e should be f o l l o w e d (F296)o

If some of the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e s h o u l d be f o l l o w e d by C O M L R (F295), C I N V I T (F297), and COMBAK (F283). In this i m p l e m e n t a t i o n , the a r i t h m e t i c is r e a l t h r o u g h o u t e x c e p t for c o m p l e x d i v i s i o n .

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

OF M E T H O D that

AND

ALGORITHM.

the m a t r i x

A

=

has ( T (0 (0

254

the X B 0

form

Y ) Z) R)

7.1-60

where T and R are upper t r i a n g u l a r m a t r i c e s , B is a s q u a r e m a t r i x s i t u a t e d in rows and c o l u m n s LOW through IGH, and X, Y, and Z are r e c t a n g u l a r m a t r i c e s of the appropriate dimensions. T h e n the s u b r o u t i n e COMHES p e r f o r m s p e r m u t a t i o n and e l e m e n t a r y s i m i l a r i t y transformations to r e d u c e B to H e s s e n b e r g form. The H e s s e n b e r g r e d u c t i o n is p e r f o r m e d in the f o l l o w i n g way. Starting with J=LOW, a p e r m u t a t i o n s i m i l a r i t y t r a n s f o r m a t i o n is p e r f o r m e d to s t a b i l i z e the s u c c e e d i n g e l e m e n t a r y transformations in the J-th c o l u m n of A. Next, each n o n zero e l e m e n t b e l o w the s u b d i a g o n a l in the J-th c o l u m n of A is e l i m i n a t e d u s i n g e l e m e n t a r y s i m i l a r i t y t r a n s f o r m a t i o n s . The p e r m u t a t i o n s i m i l a r i t y t r a n s f o r m a t i o n is d e t e r m i n e d by s e a r c h i n g for the e l e m e n t of m a x i m u m m o d u l u s in the J-th c o l u m n b e l o w the s u b d i a g o n a l . This e l e m e n t is p l a c e d into the s u b d i a g o n a l p o s i t i o n by a row i n t e r c h a n g e and the corresponding c o l u m n i n t e r c h a n g e is m a d e to c o m p l e t e the permutation transformation. The index of the row i n t e r c h a n g e d w i t h the (J+l)-th r o w is stored in INT(J+I). The e l e m e n t a r y t r a n s f o r m a t i o n c o n s i s t s of e l e m e n t a r y row o p e r a t i o n s on the J-th c o l u m n of A to e l i m i n a t e the n o n zero e l e m e n t s b e l o w the d i a g o n a l and the c o r r e s p o n d i n g e l e m e n t a r y column o p e r a t i o n s to c o m p l e t e the s i m i l a r i t y . The multipliersused in this e l i m i n a t i o n p r o c e s s are stored in p l a c e of the e l i m i n a t e d e l e m e n t s . T h e s e m u l t i p l i e r s as w e l l as the row i n t e r c h a n g e s stored in INT are used later in COMBAK for the b a c k t r a n s f o r m a t i o n of the e i g e n v e c t o r s . The a b o v e steps are r e p e a t e d on f u r t h e r c o l u m n s of the transformed A until B is r e d u c e d to H e s s e n b e r g form; is, r e p e a t e d for J = LOW+I,LOW+2,...,IGH-2. This subroutine COMHES written W i l k i n s o n (i).

that

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

4. R E F E R E N C E S .

i)

M a r t i n , R.S. and W i l k i n s o n , J.H., Similarity Reduction of a G e n e r a l M a t r i x to H e s s e n b e r g Form, Num. Math. 1 2 , 3 4 9 - 3 6 8 (1968). ( R e p r i n t e d in H a n d b o o k for A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , J. H. W i l k i n s o n - C. R e i n s e h , C o n t r i b u t i o n II/13, 339-358, S p r i n g e r - V e r l a g , 1971.)

255

7.1-61

5. CHECKOUT° A.

Test

Cases,

See the section complex general

discussing matrices.

testing

of the

codes

for

B. Accuracy° The accuracy of COMHES can best be described in terms of its role in those paths of EISPACK w h i c h find e i g e n v a l u e s and e i g e n v e c t o r s of complex general matrices. In these paths, this s u b r o u t i n e is, in practice, n u m e r i c a l l y stable (i). This stability c o n t r i b u t e s to the property of these paths that each computed e i g e n v a l u e and its c o r r e s p o n d i n g e i g e n v e c t o r are exact for a m a t r i x usually close to the original matrix.

256

7.1-62

SUBROUTINE

COMHES(NM,N,LOW,

INTEGER I,J,M,N,LA,NM, 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 ( L A .LT. K P I ) DO

180 M = K P I , MMI = M - 1 XR = 0.0 XI = 0 . 0 I = M

GO

IGH,AR,AI,INT)

IGH,KPI,LOW,MMI,MPI

TO

200

LA

DO

i00

ii0

i 0 0 J = M, I G H IF ( A B S ( A R ( J , M M I ) ) + ABS(AI(J,MMI)) .LE. A B S ( X R ) + ABS(XI)) GO T O i00 XR = AR(J,MMI) El = A I ( J , M M I ) I = J CONTINUE

INT(M) = I IF (I .EQ. M) G O T O 130 ********** INTERCHANGE ROWS D O II0 J = M M I , 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

AND

COLUMNS

AR

AND

DO

120 130

120 J = i, I G H 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 . A N D . X I .EQ. 0 . 0 ) MPI = M + i

OF

257

GO

TO

180

AI

**********

7.1-63

DO

160 I = MPI, IGH YR = AR(I,MMI) YI = AI(I,MMI) I F ( Y R .EQ. 0 . 0 . A N D . Y I .EQ. 0 . 0 ) Z3 = C M P L X ( Y R , Y I ) / CMPLX(XR,XI) YR = REAL(Z3) YI = AIMAG(Z3) AR(I,MMI) = YR AI(I,MMI) = YI 1 4 0 J = M, N AR(I,J) = AR(I,J) AI(I,J) = AI(I,J) CONTINUE

GO

TO

160

DO

140

DO

150 J = AR(J,M) AI(J,M) CONTINUE

150 160

I~ I G H = AR(J,M) = AI(J,M)

CONTINUE

180

CONTINUE

200

RETURN END

258

- YR - YR

* AR(M,J) * AI(M,J)

+ YI - YI

* AI(M,J) * AR(M,J)

+ +

* AR(J,I) * AI(J,I)

- YI + YI

* AI(J,I) * AR(J,I)

YR YR

7.1-64

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F295-2

PACKAGE

(EISPACK)

COMLR

A F o r t r a n IV S u b r o u t i n e to D e t e r m i n e of a C o m p l e x U p p e r H e s s e n b e r g

May, July,

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

1972 1975

I. P U R P O S E . The F o r t r a n IV s u b r o u t i n e a complex upper Hessenberg method.

COMLR matrix

c o m p u t e s the e i g e n v a l u e s u s i n g the m o d i f i e d LR

of

2. U S A G E . A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

COMLR(NM,N,LOW, IGH,HR,HI,WR,WI,IERR)

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

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

N

is an i n t e g e r input v a r i a b l e set e q u a l the o r d e r of the m a t r i x H = (HR,HI). m u s t be not g r e a t e r t h a n NM.

LOW,IGR

are i n t e g e r i n p u t v a r i a b l e s i n d i c a t i n g the b o u n d a r y i n d i c e s for the b a l a n c e d m a t r i x . See s e c t i o n 3 of F271 for the d e t a i l s . If the m a t r i x is not b a l a n c e d , set LOW to 1 and IGH to N.

259

to N

7.1-65

B.

Error

HR,HI

are w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l variables with row dimension NM and c o l u m n d i m e n s i o n at l e a s t N. On input, HR and HI c o n t a i n the r e a l and i m a g i n a r y p a r t s , r e s p e c t i v e l y , of the c o m p l e x u p p e r Hessenberg matrix. Note: COMLR destroys this u p p e r H e s s e n b e r g m a t r i x .

WR,WI

are w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e s of d i m e n s i o n at l e a s t N c o n t a i n i n g the r e a l and i m a g i n a r y p a r t s , r e s p e c t i v e l y , of the e i g e n v a l u e s of the upper Hessenberg matrix.

!ERR

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

Conditions

and

to is

Returns.

If m o r e than 30 i t e r a t i o n s are r e q u i r e d to d e t e r m i n e an e i g e n v a l u e ~ this s u b r o u t i n e t e r m i n a t e s w i t h IERR set to the i n d e x of the e i g e n v a l u e for w h i c h the f a i l u r e occurs. The e i g e n v a l u e s in the WR and WI arrays s h o u l d be c o r r e c t for i n d i c e s IERR+I,IERR+2,...,N. If all the e i g e n v a l u e s are d e t e r m i n e d iterations, IERR is set to zero.

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

and

within

30

Restrictions.

To d e t e r m i n e some of the e i g e n v e c t o r s of a c o m p l e x Hessenberg matrix, COMLR s h o u l d be f o l l o w e d by CiNVIT (F297) to c o m p u t e t h o s e e i g e n v e c t o r s . Note, h o w e v e r , that the u p p e r H e s s e n b e r g m a t r i x m u s t be s a v e d b e f o r e COMLR for l a t e r use of CINVIT, since COMLR destroys this u p p e r H e s s e n b e r g m a t r i x . To d e t e r m i n e the e i g e n v a l u e s of a c o m p l e x g e n e r a l matrix, COMLR s h o u l d be p r e c e d e d by C O M H E S (F282) to p r o v i d e a s u i t a b l e c o m p l e x u p p e r H e s s e n b e r g m a t r i x for COMLR. To d e t e r m i n e s o m e of the e i g e n v e c t o r s of a c o m p l e x general matrix, COMLR s h o u l d b e p r e c e d e d by COMHES (F282) and f o l l o w e d by C I N V l T (F297) and COMBAK (F283). COMBAK b a c k t r a n s f o r m s the e i g e n v e c t o r s f r o m CiNVIT into t h o s e of the c o m p l e x g e n e r a l m a t r i x . Note, as above, that the H e s s e n b e r g m a t r i x m u s t be s a v e d before COMLR.

260

7.1-66

It is r e c o m m e n d e d in g e n e r a l that CBAL (F271) be u s e d before COMHES in w h i c h case C B A B K 2 (F272) m u s t be u s e d after COMBAK if e i g e n v e c t o r s are c o m p u t e d . The s u b r o u t i n e COMLR e x e c u t e s f a s t e r than its counterpart COMQR (F245) w h i c h uses u n i t a r y s i m i l a r i t y transformations. COMQR is, h o w e v e r , m o r e a c c u r a t e in some cases. It is r e c o m m e n d e d that COMQR be used in general. In this i m p l e m e n t a t i o n , the a r i t h m e t i c is real t h r o u g h o u t e x c e p t for c o m p l e x s q u a r e root and c o m p l e x division.

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

OF M E T H O D

AND

ALGORITHM.

The e i g e n v a l u e s are d e t e r m i n e d by the m o d i f i e d LR method. The e s s e n c e of this m e t h o d is a p r o c e s s w h e r e b y a s e q u e n c e of c o m p l e x u p p e r H e s s e n b e r g m a t r i c e s , s i m i l a r to the o r i g i n a l H e s s e n b e r g m a t r i x , is f o r m e d w h i c h c o n v e r g e s to a t r i a n g u l a r matrix. The f a c t o r i z a t i o n of H into u p p e r (R) and lower (L) t r i a n g u l a r m a t r i c e s is s t a b i l i z e d by p e r m u t a t i o n similarity transformations at each stage. The rate of c o n v e r g e n c e of this s e q u e n c e is i m p r o v e d by s h i f t i n g the o r i g i n at each i t e r a t i o n . B e f o r e e a c h i t e r a t i o n , the last H e s s e n b e r g f o r m is c h e c k e d for a p o s s i b l e s p l i t t i n g into submatrices. If a s p l i t t i n g occurs, only the lower s u b m a t r i x p a r t i c i p a t e s in the n e x t i t e r a t i o n . The o r i g i n shift at each i t e r a t i o n is the e i g e n v a l u e of the lowest 2x2 p r i n c i p a l m i n o r closer to the s e c o n d d i a g o n a l e l e m e n t of this minor. Whenever a lowest ixl principal s u b m a t r i x f i n a l l y splits f r o m the rest of the m a t r i x , its e l e m e n t is taken to be an e i g e n v a l u e of the o r i g i n a l m a t r i x and the a l g o r i t h m p r o c e e d s w i t h the r e m a i n i n g s u b m a t r i x . This p r o c e s s is c o n t i n u e d u n t i l the m a t r i x has split c o m p l e t e l y into s u b m a t r i c e s of order I. The t o l e r a n c e s in the s p l i t t i n g tests are p r o p o r t i o n a l to the r e l a t i v e m a c h i n e precision. Some of the e i g e n v a l u e s may h a v e b e e n i s o l a t e d on the d i a g o n a l by the s u b r o u t i n e CBAL (F271). This i n f o r m a t i o n is t r a n s m i t t e d to COMLR t h r o u g h the p a r a m e t e r s LOW and IGH. As a result, COMLR i m m e d i a t e l y e x t r a c t s the e i g e n v a l u e s in rows I to LOW-I and IGH+I to N, and so a p p l i e s the LR p r o c e d u r e to the s u b m a t r i x s i t u a t e d in rows and c o l u m n s LOW through IGH. This s u b r o u t i n e is a t r a n s l a t i o n of the A l g o l p r o c e d u r e COMLR w r i t t e n and d i s c u s s e d in d e t a i l by M a r t i n and Wilkinson (I).

261

7.1-67

4. REFERENCES.

1)

Martin~ R.S. and Wilkinson, J.H., The M o d i f i e d LR A l g o r i t h m for Complex H e s s e n b e r g Matrices, Num. Math. 12,369-376 (1968). (Reprinted in H a n d b o o k A u t o m a t i c Computation, Volume II, Linear Algebra, J. H. W i l k i n s o n - C. Reinsch, C o n t r i b u t i o n 11/16, 396-4039 Springer-Verlag, 1971.)

for

5. CHECKOUT. A. Test

Cases.

See the section d i s c u s s i n g complex general matrices.

testing

of the codes

for

B. Accuracy° The subroutine COMLR is usually n u m e r i c a l l y stable (I); that is, each computed eigenvalue is exact for a m a t r i x usually close to the original upper H e s s e n b e r g matrix.

262

7.1-68

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 R E A L HR(NM,N),HI(NM,N),WR(N),WI(N) REAL SI,SR,TI,TR,XI,XR,YI,YR,ZZI,ZZR,MACHEP REAL ABS C O M P L E X Z3 COMPLEX CSQRT,CMPLX REAL REAL,AIMAG C C C C C

**********

MACHEP

=

M A C H E P IS A M A C H I N E D E P E N D E N T P A R A M E T E R S P E C I F Y I N G T H E R E L A T I V E P R E C I S I O N OF F L O A T I N G P O I N T A R I T H M E T I C .

?

C

200

C 220

C C 240

260 300

IERR = 0 ********** S T O R E R O O T S I S O L A T E D BY C B A L * * * * * * * * * * DO 200 I = i, N IF (I .GE. L O W .AND. I .LE. IGH) GO TO 200 WR(1) = HR(l,l) WI(1) = HI(I,I) CONTINUE EN = I G H TR = 0.0 TI = 0.0 ********** SEARCH FOR NEXT EIGENVALUE ********** IF (EN .LT. L O W ) GO TO I 0 0 1 ITS = 0 E N M I = EN i ********** LOOK FOR SINGLE SMALL SUB-DIAGONAL ELEMENT F O R L = E N S T E P -i U N T I L L O W -- * * * * * * * * * * DO 260 LL = L O W , E N L = EN + L O W - LL IF (L .EQ. L O W ) G O TO 3 0 0 IF ( A B S ( H R ( 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 3 0 0 CONTINUE ********** FORM SHIFT ********** IF (L .EQ. EN) GO TO 660 IF (ITS .EQ. 30) GO TO I000 IF (ITS .EQ. I0 .OR. ITS .EQ. 20) GO TO 3 2 0 SR = H R ( E N , E N ) SI = H I ( E N , E N ) XR = H R ( E N M I , E N ) * HR(EN,ENMI) - HI(ENMI,EN) * HI(EN,ENMI) XI = H R ( E N M I , E N ) * HI(EN,ENMI) + HI(ENMI,EN) * HR(EN,ENMI) IF (XR .EQ. 0 . 0 .AND. XI .EQ. 0.0) GO TO 340 YR = ( H R ( E N M I , E N M I ) - SR) / 2 . 0 YI = ( H I ( E N M I , E N M I ) - SI) / 2.0 Z3 = C S Q R T ( C M P L X ( Y R * * 2 - Y I * * 2 + X R , 2 . 0 * Y R * Y I + X I ) ) ZZR = REAL(Z3) ZZI = A I M A G ( Z 3 )

263

7.1-69

310

320

IF (YR * ZZR + YI * ZZI ,GE. 0.0) GO TO 310 ZZR = -ZZR ZZI = -ZZI Z3 = C M P L X ( X R , X I ) / CMPLX(YR+ZZR,YI+ZZI) SR = SR - REAL(Z3) SI = SI - A I M A G ( Z 3 ) GO TO 340 • ********* FORM EXCEPTIONAL SHIFT ********** SR = ABS(HR(EN,ENMI)) + ABS(HR(ENMI,EN-2)) SI = A B S ( H I ( E N , E N M I ) ) + ABS(HI(ENMI,EN-2))

C 340

DO

360

1 = LOW,

HR(I,I) 360

HI(I,I) CONTINUE

EN

= HR(I,I) =

HI(I,I)

-

-

SR SI

C

380 420

TR = TR + SR T I = T I + 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 -- ********** D O 3 8 0 M M = L~ E N M I M = ENMI + L - MM IF (M .EQ, L) G O T O 4 2 0 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)) I F ( Y R .LE. M A C H E P * ZZR / YI * (ZZR + XR + XI)) GO CONTINUE ********** TRIANGULAR DECOMPOSITION H=L*R ********** MPI = M + i DO

440

520 ! = MPI, EN IMI = I - 1 XR = HR(IMI,IMI) XI = HI(IMI,IMI) YR = HR(I,IMI) YI = RI(~I IMl) IF ( A B S ( X R ) + ABS(XI) .GE. A B S ( Y R ) ********** INTERCHANGE R O W S OF H R A N D DO 440 J = IMI, EN ZZR = HR(IMI,J) H R ( i M I ,J) = H R ( I , J) H R ( I , J) = Z Z R ZZI = HI(IMI,J) HI (IMI,J) = H I (I, J) HI(I,J) = ZZI CONTINUE

TO

264

+ ABS(YI)) GO HI **********

TO

460

420

7. 1 - 7 0

460 480

Z3 = C M P L X ( X R , XI) WR(1) = 1.0 GO TO 480 Z3 = C M P L X ( Y R , Y I ) WR(I) = -I.0 ZZR = REAL(Z3) ZZI = AIMAG(Z3) HR(I,IMI) = ZZR HI(I,IMI) = ZZI DO

500 520

500 J = HR(I,J) HI(I,J) CONTINUE

I, E N = HR(I,J) = HI(I,J)

HI(I,J-I) 540

580

DO

660

C C I000 i001

- ZZR - ZZR

R*L=H

* HR(IMI,J) * HI(IMI,J)

+ ZZI - ZZI

* HI(IMI,J) * HR(IMI,J)

**********

COLUMNS OF ********** GO TO 580

HR

AND

HI,

5 4 0 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) CONTINUE

640

/ CMPLX(XR,XI)

CONTINUE ********** COMPOSITION DO 640 J = MPI, EN XR = HR(J,J-I) XI = H l ( J , J - l ) HR(J,J-I) = 0.0 HI(J,J-I) = 0.0 ********** INTERCHANGE IF N E C E S S A R Y IF ( W R ( J ) .LE. 0 . 0 ) DO

600

/ CMPLX(YR,YI)

= HI(I,~) =

ZZI

6 0 0 I = L, J HR(I,J-I) = HR(I,J-I) HI(I,J-I) = HI(I,J-I) CONTINUE

+ +

XR XR

* HR(I,J) * HI(I,J)

- XI + XI

* Hl(l,J) * HR(I,J)

CONTINUE GO T O 2 4 0 ********** A ROOT FOUND ********** WR(EN) = HR(EN,EN) + TR WI(EN) = HI(EN,EN) + TI EN = ENMI GO TO 220 ********** S E T E R R O R -- N O C O N V E R G E N C E TO EIGENVALUE AFTER 30 I T E R A T I O N S IERR = EN RETURN END

265

AN **********

7.1-71

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F296-2

PACKAGE

(E!SPACK)

COMLR2

A F o r t r a n IV S u b r o u t i n e to D e t e r m i n e the E i g e n v a l u e s and E i g e n v e c t o r s of a C o m p l e x U p p e r H e s s e n b e r g M a t r i x .

May, July,

1972 1975

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e COMLR2 c o m p u t e s the e i g e n v a l u e s and e i g e n v e c t o r s of a c o m p l e x u p p e r H e s s e n b e r g m a t r i x . COMLR2 uses the m o d i f i e d LR m e t h o d to c o m p u t e the e i g e n v a l u e s and a c c u m u l a t e s the LR t r a n s f o r m a t i o n s to c o m p u t e the e i g e n v e c t o r s . The e i g e n v e c t o r s of a c o m p l e x g e n e r a l m a t r i x can also be c o m p u t e d d i r e c t l y by COMLR2, if C O M H E S (F282) has b e e n u s e d to r e d u c e this m a t r i x to H e s s e n b e r g form.

2. U S A G E . A.

Calling The

Sequence°

SUBROUTINE SUBROUTINE

statement

is

COMLR2(NM,N,LOW,IGH, INT,HR,HI, WR,WI,ZR,ZI,IERR)

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

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to the r o w d i m e n s i o n of the t w o - d i m e n s i o n a l arrays HR, HI, ZR, and ZI as s p e c i f i e d in the D I M E N S I O N s t a t e m e n t s for HR, HI, ZR, a n d ZI in the c a l l i n g p r o g r a m . is an i n t e g e r i n p u t v a r i a b l e set e q u a l the o r d e r of the m a t r i x H = (HR,HI). m u s t be n o t g r e a t e r t h a n NM.

266

to N

7.1-72

LOW,IGH

are i n t e g e r input v a r i a b l e s i n d i c a t i n g the b o u n d a r y i n d i c e s for the b a l a n c e d matrix. See s e c t i o n 3 of F271 for the d e t a i l s . If the m a t r i x is not b a l a n c e d , set LOW to i and IGH to N.

INT

is an i n t e g e r input o n e - d i m e n s i o n a l variable of d i m e n s i o n at least IGH. Only c o m p o n e n t s LOW through IGH are u s e d by COMLR2. If the e i g e n v e c t o r s of the H e s s e n b e r g m a t r i x are d e s i r e d , set INT(J)=J for J = LOW,LOW+I,...,IGH. If the e i g e n v e c t o r s of a c o m p l e x g e n e r a l m a t r i x are d e s i r e d , INT c o n t a i n s i n f o r m a t i o n saved by COMHES i d e n t i f y i n g the rows and c o l u m n s i n t e r c h a n g e d during the r e d u c t i o n to H e s s e n b e r g form.

HR,HI

are w o r k i n g p r e c i s i o n real t w o - d i m e n s i o n a l v a r i a b l e s w i t h row d i m e n s i o n NM and column d i m e n s i o n at least N. On input, HR and HI c o n t a i n the real and i m a g i n a r y parts, respectively, of the c o m p l e x u p p e r H e s s e n b e r g matrix. If the e i g e n v e c t o r s of the H e s s e n b e r g m a t r i x are desired, set the lower t r i a n g l e s of HR,HI b e l o w the s u b d i a g o n a l to zero. If the e i g e n v e c t o r s of a c o m p l e x g e n e r a l m a t r i x are d e s i r e d , the lower t r i a n g l e s of HR,HI c o n t a i n the m u l t i p l i e r s w h i c h are g e n e r a t e d by COMHES in the r e d u c t i o n to the H e s s e n b e r g form. Note: COMLR2 d e s t r o y s the u p p e r H e s s e n b e r g p o r t i o n s of HR,HI, but r e t u r n s in l o c a t i o n HR(I,I) the n o r m of the t r i a n g u l a r i z e d matrix. See s e c t i o n 2C for the d e f i n i t i o n and s i g n i f i c a n c e of this q u a n t i t y .

WR,WI

are w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e s of d i m e n s i o n at least N c o n t a i n i n g the r e a l and i m a g i n a r y parts, respectively, of the e i g e n v a l u e s of the u p p e r H e s s e n b e r g matrix.

ZR,ZI

are w o r k i n g p r e c i s i o n real o u t p u t twod i m e n s i o n a l v a r i a b l e s w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at least N containing the real and i m a g i n a r y parts, r e s p e c t i v e l y , of the e i g e n v e c t o r s . The e i g e n v e c t o r s are not n o r m a l i z e d .

267

7. 1-73

IERR

B.

Error

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

Conditions

and

to is

Returns.

If m o r e than 30 i t e r a t i o n s are r e q u i r e d to d e t e r m i n e an e i g e n v a l u e , this s u b r o u t i n e t e r m i n a t e s w i t h IERR set to the i n d e x of the e i g e n v a l u e for w h i c h the f a i l u r e occurs. T h e e i g e n v a l u e s in the WR and WI arrays s h o u l d be c o r r e c t for i n d i c e s IERR+I,IERR+2,...,N, hut no e i g e n v e c t o r s are c o m p u t e d . If all the e i g e n v a l u e s are d e t e r m i n e d iterations, IERR is set to zero.

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

and

within

30

Restrictions.

To d e t e r m i n e the e i g e n v a l u e s and e i g e n v e c t o r s of a complex general matrix, COMLR2 m u s t be p r e c e d e d by C O M H E S (F282) to p r o v i d e a s u i t a b l e c o m p l e x H e s s e n b e r g m a t r i x for COMLR2. be u s e d It is r e c o m m e n d e d in g e n e r a l t h a t C B A L (F271) m u s t be before COMHES in w h i c h c a s e C B A B K 2 (F272) used after COMLR2. The s u b r o u t i n e COMLR2 may occasionally return poor r e s u l t s , e s p e c i a l l y in the e i g e n v e c t o r s , due to p r o n o u n c e d g r o w t h in the m a t r i x e l e m e n t s that m a y o c c u r d u r i n g the LR iterations. A m e a s u r e of this g r o w t h can b e o b t a i n e d f r o m a c o m p a r i s o n of the n o r m q u a n t i t y r e t u r n e d in H R ( I , I ) , d e f i n e d as the s u m of the a b s o l u t e v a l u e s of the r e a l and i m a g i n a r y c o m p o n e n t s of all the e l e m e n t s of the t r i a n g u l a r i z e d m a t r i x , w i t h the c o r r e s p o n d i n g n o r m of the v e c t o r of e i g e n v a l u e s . This g r o w t h c a n n o t o c c u r in the QR a l g o r i t h m e m b o d i e d in subroutine C O M Q R 2 (F246), the u n i t a r y c o u n t e r p a r t of COMLR2. It is r e c o m m e n d e d that COMQR2, although s l o w e r , be u s e d in g e n e r a l . In this i m p l e m e n t a t i o n , the a r i t h m e t i c is real t h r o u g h o u t e x c e p t for c o m p l e x s q u a r e r o o t and c o m p l e x division.

268

7.1-74

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

OF M E T H O D

AND A L G O R I T H M .

The e i g e n v a l u e s are d e t e r m i n e d by the m o d i f i e d LR method. The e s s e n c e of this m e t h o d is a p r o c e s s w h e r e b y a s e q u e n c e of c o m p l e x u p p e r H e s s e n b e r g m a t r i c e s , s i m i l a r to the o r i g i n a l H e s s e n b e r g m a t r i x , is f o r m e d w h i c h c o n v e r g e s to a t r i a n g u l a r matrix. The f a c t o r i z a t i o n of H into u p p e r (R) and lower (L) t r i a n g u l a r m a t r i c e s is s t a b i l i z e d by p e r m u t a t i o n similarity transformations at each stage. The rate of c o n v e r g e n c e of this s e q u e n c e is i m p r o v e d by s h i f t i n g the o r i g i n at each i t e r a t i o n . B e f o r e e a c h i t e r a t i o n , the last H e s s e n b e r g f o r m is c h e c k e d for a p o s s i b l e s p l i t t i n g into submatrices. If a s p l i t t i n g occurs, only the lower s u b m a t r i x p a r t i c i p a t e s in the n e x t i t e r a t i o n . The s i m i l a r i t y transformations used in each i t e r a t i o n are a c c u m u l a t e d in the ZR and ZI arrays along w i t h the r e d u c t i o n t r a n s f o r m a t i o n s for the o r i g i n a l matrix. The o r i g i n shift at each i t e r a t i o n is the e i g e n v a l u e of the lowest 2x2 p r i n c i p a l m i n o r closer to the s e c o n d d i a g o n a l e l e m e n t of this minor. Whenever a lowest ixl principal s u b m a t r i x f i n a l l y s p l i t s f r o m the rest of the m a t r i x , its e l e m e n t is taken to be an e i g e n v a l u e of the o r i g i n a l m a t r i x and the a l g o r i t h m p r o c e e d s w i t h the r e m a i n i n g s u b m a t r i x . This p r o c e s s is c o n t i n u e d until the m a t r i x has split c o m p l e t e l y into s u b m a t r i c e s of order I. The t o l e r a n c e s in the s p l i t t i n g tests are p r o p o r t i o n a l to the r e l a t i v e m a c h i n e precision. The e i g e n v e c t o r s of this t r i a n g u l a r m a t r i x are d e t e r m i n e d by b a c k s u b s t i t u t i o n , and then b a c k t r a n s f o r m e d into those of the o r i g i n a l matrix. Some of the e i g e n v a l u e s may h a v e b e e n i s o l a t e d on the d i a g o n a l by the s u b r o u t i n e CBAL (F271). This i n f o r m a t i o n is t r a n s m i t t e d to COMLR2 t h r o u g h the p a r a m e t e r s LOW and IGH. As a result, COMLR2 i m m e d i a t e l y e x t r a c t s the e i g e n v a l u e s in rows 1 to LOW-I and IGH+I to N, and so a p p l i e s the LR p r o c e d u r e to the s u b m a t r i x s i t u a t e d in rows and c o l u m n s LOW through IGH. This s u b r o u t i n e COMLR2 written W i l k i n s o n (i).

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

4. R E F E R E N C E S .

i)

P e t e r s , G. and W i l k i n s o n , J.H., E i g e n v e o t o r s of R e a l C o m p l e x M a t r i c e s by LR and QR T r i a n g u l a r i z a t i o n s , Num. Math. 1 6 , 1 8 1 - 2 0 4 (1970). ( R e p r i n t e d in H a n d b o o k A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , J. H. W i l k i n s o n - C. R e i n s c h , C o n t r i b u t i o n 11/15, 372-395, S p r i n g e r - V e r l a g , 1971.)

269

and for

7.1-75

5. CHECKOUT. A.

Test

Cases°

See the section complex general

discussing matrices.

testing

of the

codes

for

B. Accuracy. The s u b r o u t i n e COMLR2 is usually n u m e r i c a l l y stable (I); that is, each computed eigenvalue and its c o r r e s p o n d i n g e i g e n v e c t o r are exact for a m a t r i x usually close to the original upper H e s s e n b e r g matrix.

270

7.1-76

SUBROUTINE

COMLR2(NM,N~LOW~IGH,

INT,HR, HI,WR,WI,ZR,ZI,IERR)

INTEGER

X

I,J,K,L,M,N,EN,II,JJ,LL,MM,NM,NN, IGH, I M I , I P I , 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

=

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

?

IERR = 0 **~******* DO i 0 0 I = DO

i00

INITIALIZE 19 N

I00 J = ZR(I,J)

i, N = 0.0

zi(I,J)

=

EIGENVECTOR

o.o

120 K = I P I , I G H ZR(K,I) = HR(K,I-I) ZI(K,I) = HI(K,I-I) CONTINUE

J = INT(1) IF (I .EQ. DO

140

140 K = ZR(I,K) ZI(I,K) ZR(J,K) ZI(J,K) CONTINUE ZR(~,I)

160

**********

IF (l .EQ. J) Z R ( I , J ) = 1.0 CONTINUE ********** FORM THE MATRIX OF A C C U M U L A T E D TRANSFORMATIONS FROM THE INFORMATION LEFT BY COMHES **~******* 1END = IGH - LOW - i IF ( 1 E N D .LE. O) G O T O 180 ********** FOR I=IGH-I S T E P -I U N T I L L O W + I DO -- * * * * * * * * * * DO 160 II = i, 1 E N D I = I G H - II IPI = I + i DO

120

MATRIX

=

J) I, = = = =

GO

TO

160

IGH ZR(J,K) ZI(J,K) 0.0 0.0

1.0

CONTINUE

271

7.1-77

180

********** STORE ROOTS ISOLATED BY C B A L * * * * * * * * * * D O 2 0 0 1 = i, N IF (! .GE. L O W .AND, I .eE. IGH) GO TO 2 0 0

WR(I) WI(I) 200

HR(I,I) = HI(I,I)

=

CONTINUE

EN = IGH T R = 0.0 TI = 0 . 0 C ********** SEARCH FOR NEXT EIGENVALUE ********** "220 IF (EN .LT. L O W ) G O TO 680 ITS = 0 ENMI = EN - I C ********** LOOK FOR SINGLE SMALL SUB-DIAGONAL ELEMENT C F O R L = E N S T E P -i U N T I L L O W D O -- * * * * * * * * * * 240 DO 260 LL = LOW, EN L = EN + L O W - LL IF (L .EQ. L O W ) GO TO 3 0 0 IF ( A B S ( H R ( 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 ********** 3 0 0 IF (L .EQ. EN) G O T O 660 IF (rTS .EQo 30) G O T O i 0 0 0 IF (ITS .EQ. i0 .OR. ITS .EQ. 20) GO TO 3 2 0 SR = HR(EN,EN) SI = H I ( E N , E N ) XR = HR(ENMI,EN) * HR(EN,ENMI) - HI(ENMI,EN) * HI(EN,ENMI) XI = H R ( E N M I , E N ) * HI(EN,ENMI) + HI(ENMI,EN) * HR(EN,ENMI) IF (XR .EQ. 0 . 0 . A N D . XI .EQ. 0.0) G O TO 3 4 0 YR = (HR(ENMI,ENMI) - SR) / 2 . 0 YI = (HI(ENMI,ENMI) - SI) / 2 . 0 Z3 = C S Q R T ( C M P L X ( Y R * * 2 - Y I * * 2 + X R , 2 . 0 * Y R * Y I + X I ) ) ZZR = REAL(Z3) ZZI = AIMAG(Z3) IF (YR * Z Z R + Y I * Z Z I .GE. 0 . 0 ) G O T O 3 1 0 ZZR = -ZZR ZZI = -ZZI 3 1 0 Z3 = C M P L X ( X R , X I ) / CMPLX(YR+ZZR,YI+ZZI) SR = S R - R E A L ( Z 3 ) SI = SI - A I M A G ( Z 3 ) GO TO 3 4 0 C ********** FORM EXCEPTIONAL SHIFT ********** 320 S R = A B S ( H R ( E N , E N M I ) ) + ABS(HR(ENMI,EN-2)) SI = A B S ( H I ( E N , E N M I ) ) + ABS(HI(ENMI,EN-2)) 340

DO

360

I = LOW,

HR(I,I)

360

H!(i,l) CONTINUE

EN

=

HR(I,I)

-

=

HI(I,I)

-

SR SI

272

7.1-78

380 420

TR = TR + SR T I = T I + 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 -- ********** D O 3 8 0 M M = L, E N M I M = ENMI + L - MM IF (M .EQ. L) G O T O 4 2 0 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)) I F ( Y R .LE. M A C H E P * ZZR / YI * (ZZR + XR + XI)) GO CONTINUE ********** TRIANGULAR DECOMPOSITION H=L*R ********** MPI = M + i DO

440

460 480

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. A B S ( Y R ) ********** INTERCHANGE R O W S OF H R A N D 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

TO

Z3 = CMPLX(XR,XI) W R ( 1 ) -- i. 0 GO TO 480 Z3 = CMPLX(YR,YI) WR(I) = -i.0 ZZR = REAL(Z3) ZZI = AIMAG(Z3) HR(I,IMI) = ZZR HI(I,IMI) = ZZI DO

500

+ ABS(YI)) GO HI **********

TO

460

/ CMPLX(YR,YI)

/ CMPLX(XR,

5 0 0 J = I, N HR(I,J) = HR(I,J) HI(I,J) = HI(I,J)

- ZZR - ZZR

CONTINUE

273

XI)

* HR(IMI,J) * HI(IMI,J)

+ -

ZZI ZZI

* HI(IMI,J) * HR(IMI,J)

420

7.1-79

C 520 C

CONTINUE ********** COMPOSITION 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 IF NECESSARY IF ( W R ( J ) .LE. 0 . 0 )

R*L=H

**********

COLUMNS OF ********** GO TO 580

HR,

HI,

ZR,

AND

ZI,

DO

540

5 4 0 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 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) 560

ZI(I,J) CONTINUE

580

DO

= zI(i,J) =

ZZ!

620

6 0 0 I = i, J HR(I,J-I) = HR(I,J-I) + XR * H!(I,J-!) = HI(I,J-I) + XR * CONTINUE • ********* ACCUMULATE TRANSFORMATIONS DO 620 I = LOW, IGH ZR(I,J-I) = ZR(I,J-I) + XR * Zi(I,J-I) = ZI(I,J-I) + XR * CONTINUE

640

CONTINUE

600

HR(I,J) HI(I,J)

- XI + XI

* HI(I,J) * HR(I,J)

********** ZR(I,J) ZI(I,J)

- XI + XI

* ZI(I,J) * ZR(I,J)

C C C 660

680

GO TO 240 ********** A ROOT FOUND ********** 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 BACKSUBSTITUTE ********** ALL ROOTS FOUND. VECTORS OF UPPER TRIANGULAR FORM NORM = 0.0

274

TO FIND **********

7. 1 - 8 0

DO

720

1 =

I,

N

DO

720

7 2 0 J = I, N NORM = NORM + CONTINUE

ABS(HR(I,J))

+

ABS(RI(I,J))

HR(I,I) = NORM IF (N .EQ. i .OR. N O R M .EQ. 0 . 0 ) G O T O i 0 0 1 ********** FOR EN=N STEP -i UNTIL 2 DO -- ********** D O 8 0 0 N N = 2, N EN = N + 2 - NN XR = WR(EN) XI = WI(EN) ENMI = EN - i ********** FOR I=EN-I S T E P -I U N T I L I DO -- ********** D O 7 8 0 I I = I, E N M I I = EN II ZZR = HR(I,EN) ZZI = HI(I,EN) IF (I .EQ. E N M I ) G O T O 7 6 0 IPI = I + i DO

740 J ZZR = ZZI = CONTINUE

740 760

780

= IPI, ENMI ZZR + HR(I,J) ZZI + HR(I,J)

* HR(J,EN) * HI(J,EN)

- HI(I,J) + HI(I,J)

YR = XR - WR(1) YI = XI - WI(1) IF ( Y R .EQ. 0 . 0 . A N D . Y I .EQ. 0 . 0 ) Z3 = CMPLX(ZZR, ZZI) / CMPLX(YR,YI) HR(I,EN) = REAL(Z3) HI(I,EN) = AIMAG(Z3) CONTINUE

YR

= MACHEP

C 800 C C

CONTINUE ********** END BACKSUBSTITUTION ENMI = N - i ********** VECTORS OF ISOLATED D O 8 4 0 I = I, E N M I IF (I .GE. L O W . A N D . I .LE. IPI = I + 1 DO

820 840

820 J = ZR(I,J)

IPI, N = HR(I,J)

zi(i,J)

= HI(I,J)

CONTINUE CONTINUE

275

********** ROOTS IGH)

********** GO

TO

* HI(J,EN) * HR(J,EN)

840

* NORM

7, 1 - 8 1

**********

DO

MULTIPLY BY TRANSFORMATION MATRIX VECTORS OF ORIGINAL FULL MATRIX. FOR J=N STEP -i UNTIL LOW+I DO -880 JJ = LOW, ENMI J = N + LOW - JJ M = MIN0(J-I,IGH) DO

880 ZZR ZZI

i = =

= LOW, ZR(I,J) ZI(I,J)

DO

860 K ZZR = ZZI = CONTINUE

860

880

ZR(I,J) ZI(i,J) CONTINUE GO TO I001 **********

C C i000 i001

IERR = RETURN END

GIVE

**********

IGH

= LOW, M ZZR + ZR(I,K) ZZI + ZR(I,K)

= =

TO

* *

HR(K,J) HI(K,J)

+

ZI(I,K) ZI(I,K)

* HI(K,J) * HR(K,J)

ZZR ZZI

SET ERROR EIGENVALUE

-- NO CONVERGENCE TO AFTER 30 ITERATIONS

EN

276

AN **********

7,1-82

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F245

PACKAGE

(EISPACK)

COMQR

A F o r t r a n IV S u b r o u t i n e to D e t e r m i n e of a C o m p l e x U p p e r H e s s e n b e r g

July,

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

1975

!. P U R P O S E . T h e F o r t r a n IV s u b r o u t i n e a complex upper Hessenberg

COMQR matrix

c o m p u t e s the e i g e n v a l u e s u s i n g the QR method.

of

2. U S A G E . A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

COMQR(NM~N,LOW,IGH,HR,HI~WR,WI,IERR)

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

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to the row d i m e n s i o n of the t w o - d i m e n s i o n a l arrays HR and HI as s p e c i f i e d in the D I M E N S I O N s t a t e m e n t s for HR and HI in the c a l l i n g p r o g r a m . is an i n t e g e r i n p u t v a r i a b l e set e q u a l the o r d e r of the m a t r i x H = (HR,HI). m u s t be not g r e a t e r t h a n NM.

to N

LOW, IGH are i n t e g e r i n p u t v a r i a b l e s i n d i c a t i n g the b o u n d a r y i n d i c e s for the b a l a n c e d m a t r i x . See s e c t i o n 3 of F271 for the d e t a i l s . If the m a t r i x is not b a l a n c e d , set LOW to 1 and IGH to N.

277

7.1-83

B. E r r o r

HR,H!

are w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l variables with row dimension NM and c o l u m n d i m e n s i o n at l e a s t N. On input, HR and HI c o n t a i n the r e a l and i m a g i n a r y p a r t s , r e s p e c t i v e l y , of the c o m p l e x u p p e r Hessenberg matrix. Note: COMQR destroys this u p p e r H e s s e n b e r g m a t r i x .

WR,WI

are w o r k i n g p r e c i s i o n real o u t p u t oned i m e n s i o n a l v a r i a b l e s of d i m e n s i o n at least N c o n t a i n i n g the r e a l and i m a g i n a r y parts, r e s p e c t i v e l y , of the e i g e n v a l u e s of the upper Hessenberg matrix.

IERR

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

Conditions

and

to is

Returns.

If m o r e than 30 i t e r a t i o n s are r e q u i r e d to d e t e r m i n e an e i g e n v a ! u e , this s u b r o u t i n e t e r m i n a t e s w i t h IERR set to the i n d e x of the e i g e n v a l u e for w h i c h the f a i l u r e occurs. The e i g e n v a l u e s in the WR and WI arrays s h o u l d be c o r r e c t for i n d i c e s IERR+I,IERR+2,...,N. If all the e i g e n v a l u e s are d e t e r m i n e d iterations, IERR is set to zero.

C.

Applicability

and

within

30

Restrictions.

To d e t e r m i n e some of the e i g e n v e c t o r s of a c o m p l e x Hessenberg matrix, COMQR s h o u l d be f o l l o w e d by CINVIT (F297) to c o m p u t e t h o s e e i g e n v e c t o r s . Note, h o w e v e r , that the u p p e r H e s s e n b e r g m a t r i x m u s t be s a v e d b e f o r e COMQR for l a t e r use of CINVIT, since COMQR destroys this u p p e r H e s s e n b e r g m a t r i x . To d e t e r m i n e the e i g e n v a l u e s of a c o m p l e x g e n e r a l matrix, COMQR s h o u l d be p r e c e d e d by C O R T H (F244) to p r o v i d e a s u i t a b l e c o m p l e x u p p e r H e s s e n b e r g m a t r i x for COMQR. To d e t e r m i n e some of the e i g e n v e c t o r s of a c o m p l e x general matrix, COMQR s h o u l d be p r e c e d e d by CORTH (F244) and f o l l o w e d by C I N V I T (F297) and CORTB (F247). CORTB b a c k t r a n s f o r m s the e i g e n v e c t o r s f r o m CINVIT i n t o t h o s e of the c o m p l e x g e n e r a l m a t r i x . Note, as above, that the H e s s e n b e r g m a t r i x m u s t be s a v e d before COMQR.

278

7.1-84

It is r e c o m m e n d e d in g e n e r a l that CBAL (F271) be used before CORTH in w h i c h case C B A B K 2 (F272) m u s t be used a f t e r CORTB if e i g e n v e c t o r s are c o m p u t e d . In this i m p l e m e n t a t i o n , the a r i t h m e t i c is real t h r o u g h o u t e x c e p t for c o m p l e x s q u a r e root and c o m p l e x division.

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

OF M E T H O D

AND

ALGORITHM.

The e i g e n v a l u e s are d e t e r m i n e d by the QR method. The e s s e n c e of this m e t h o d is a p r o c e s s w h e r e b y a s e q u e n c e of c o m p l e x u p p e r H e s s e n b e r g m a t r i c e s , s i m i l a r to the o r i g i n a l H e s s e n b e r g m a t r i x , is f o r m e d w h i c h c o n v e r g e s to a t r i a n g u l a r matrix. The r a t e of c o n v e r g e n c e of this s e q u e n c e is i m p r o v e d by s h i f t i n g the o r i g i n at e a c h iteration. B e f o r e each iteration, the last H e s s e n b e r g f o r m is c h e c k e d for a p o s s i b l e s p l i t t i n g into s u b m a t r i c e s . If a s p l i t t i n g occurs, only the lower s u b m a t r i x p a r t i c i p a t e s in the n e x t i t e r a t i o n . The o r i g i n shift at each i t e r a t i o n is the e i g e n v a l u e of the lowest 2x2 p r i n c i p a l m i n o r c l o s e r to the second d i a g o n a l e l e m e n t of this minor. Whenever a lowest ixl principal s u b m a t r i x f i n a l l y splits from the rest of the matrix, its e l e m e n t is taken to be an e i g e n v a l u e of the o r i g i n a l m a t r i x and the a l g o r i t h m p r o c e e d s w i t h the r e m a i n i n g submatrix. This p r o c e s s is c o n t i n u e d until the m a t r i x has split c o m p l e t e l y into s u b m a t r i c e s of order i. The t o l e r a n c e s in the s p l i t t i n g tests are p r o p o r t i o n a l to the r e l a t i v e m a c h i n e precision. The s u b d i a g o n a l e l e m e n t s are r e n d e r e d real diagonal unitary similarity transformation real t h r o u g h o u t COMQR.

i n i t i a l l y by a and m a i n t a i n e d

Some of the e i g e n v a l u e s may h a v e b e e n i s o l a t e d on the d i a g o n a l by the s u b r o u t i n e CBAL (F271). This i n f o r m a t i o n is t r a n s m i t t e d to COMQR t h r o u g h the p a r a m e t e r s LOW and IGH. As a result, COMQR i m m e d i a t e l y e x t r a c t s the e i g e n v a l u e s in rows i to LOW-1 and IGH+I to N, and so a p p l i e s the QR p r o c e d u r e to the s u b m a t r i x s i t u a t e d in rows and c o l u m n s LOW through IGH. This s u b r o u t i n e is a t r a n s l a t i o n of a u n i t a r y a n a l o g u e of the Algol procedure COMLR w r i t t e n and d i s c u s s e d in d e t a i l by M a r t i n and W i l k i n s o n (i). The u n i t a r y a n a l o g u e s u b s t i t u t e s for the LR a l g o r i t h m the QR a l g o r i t h m , w r i t t e n and d i s c u s s e d in d e t a i l by F r a n c i s (2).

279

7.1-85

4. REFERENCES.

i)

2)

Martin, RoS. and Wilkinson, J.H., The M o d i f i e d LR A l g o r i t h m for Complex H e s s e n b e r g Matrices, Num. Math. 12,369-376 (1968). (Reprinted in H a n d b o o k Automatic Computation, Volume II, Linear Algebra, J. H. W i l k i n s o n - C. Reinsch, C o n t r i b u t i o n 11/16, 396-403, S p r i n g e r - V e r l a g , 1971.) Francis, J.G.F., The QR T r a n s f o r m a t i o n - Parts Comp. J. 4,265-271 and 332-345 (1961/62).

for

1 and 2,

5. CHECKOUT. A. Test

Cases°

See the section discussing complex general matrices.

testing

of the codes

for

B. Accuracy~ The s u b r o u t i n e COMQR is n u m e r i c a l l y stable (1,2); that is, each computed eigenvalue is exact for a m a t r i x close to the original upper H e s s e n b e r g matrix.

280

7. 1 - 8 6

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 IS A M A C H I N E DEPENDENT PARAMETER SPECIFYING THE RELATIVE PRECISION OF F L O A T I N G POINT ARITHMETIC. **********

MACHEP

=

?

IERR = 0 IF ( L O W .EQ. I G H ) ********** CREATE L = LOW + I DO

G O T O 180 REAL SUBDIAGONAL

ELEMENTS

**********

170 1 = L, I G H LL = M I N 0 ( I + I , I G H ) IF ( H I ( I , I - I ) .EQ. 0 . 0 ) GO T O 1 7 0 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 DO

155 J = I, I G H SI = Y R * H I ( I , J ) - YI HR(I,J) : YR * HR(I,J) HI(I,J) : SI CONTINUE

155

160 J = L O W , LL SI = Y R * H I ( J , I ) + YI HR(J,I) = YR * HR(J,I) HI(J,I) = SI CONTINUE

* HR(I,J) + YI * HI(I,J)

DO

160 170 180

200

* HR(J,I) - YI * HI(J,I)

CONTINUE ********** STORE ROOTS ISOLATED D O 2 0 0 I = i, N IF (I .GE. L O W . A N D . I .LE. WR(1) = HR(I,I) WI(I) = HI(I,I) CONTINUE EN

=

TR TI

= =

IGH 0.0 0.0

281

BY

CBAL

IGH)

GO

********** TO

200

7.1-87

C 220

C C 240

260 C 300

310

C 320

340

360

********** SEARCH FOR NEXT EIGENVALUE ********** IF ( E N .LT. L O W ) G O T O i 0 0 1 ITS = 0 E N M I = EN 1 ********** LOOK FOR SINGLE SMALL SUB-DIAGONAL ELEMENT F O R L = E N S T E P -i U N T I L LOW -- ********** DO 260 LL = LOW, EN L = EN + L O W - L L IF (L .EQ. L O W ) G O T O 3 0 0 IF ( A B S ( H R ( 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)))) G O TO 3 0 0 CONTINUE ********** FORM SHIFT ********** IF (L .EQ. EN) G O T O 6 6 0 IF ( I T S .EQ. 30) G O T O I 0 0 0 IF ( I T S .EQ. I0 .OR. I T S .EQ. 20) GO T O 3 2 0 SR = H R ( E N , E N ) SI = H I ( E N , E N ) XR = HR(ENMI,EN) * HR(EN,ENMI) XI = HI(ENMI,EN) * HR(EN,ENMI) IF ( X R .EQ. 0 . 0 . A N D . XI .EQ. 0 . 0 ) G O T O 3 4 0 YR = (HR(ENMI,ENMI) - SR) / 2 . 0 YI = (HI(ENMI,ENMI) - SI) / 2 . 0 Z3 = C S Q R T ( C M P L X ( Y R * * 2 - Y I * * 2 + X R , 2 . 0 * Y R * Y I + X I ) ) ZZR = REAL(Z3) ZZI = AIMAG(Z3) IF (YR * Z Z R + Y I * Z Z I .GE. 0 . 0 ) G O TO 3 1 0 ZZR = -ZZR ZZI = -ZZI Z3 = C M P L X ( X R , X I ) / CMPLX(YR+ZZR,YI+ZZI) S R = SR - R E A L ( Z 3 ) SI = SI - A I M A G ( Z 3 ) G O TO 3 4 0 ********** FORM EXCEPTIONAL SHIFT ********** SR = A B S ( H R ( E N , E N M I ) ) + ABS(HR(ENMI,EN-2)) Sl = 0 . 0 DO

360 1 = LOW, EN HR(l,l) = N R ( I , I ) HI(I,I) = HI(I,I) CONTINUE

T R = T R + SR T! = T I + SI ITS = ITS + 1 ********** REDUCE LPI = L + 1

TO

-

-

SR SI

TRIANGLE

282

(ROWS)

**********

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 DO

490 500

540

4 9 0 J = I, E N YR = HR(I-I,J) YI = HI(I-I,J) ZZR = HR(I,J) ZZI = HI(I,J) HR(I-I,J) = XR HI(I-I,J) = XR HR(I,J) = XR * ~l(l,J) = XR * CONTINUE

* YR + XI * YI * YI - XI * YR ZZR - Xl * ZZI ZZI + Xl ~ ZZR

+ + -

HI(I,I-I) HI(I,I-I) HI(I,I-I) HI(I,I-I)

* ZZR * ZZI * YR * YI

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 DO 600 J = LPI, EN XR = WR(J-I) XI = WI(J-I)

(COLUMNS)

DO

560

580 600

5 8 0 I = L, J YR = HR(I,J-I) YI = 0.0 ZZR = HR(I,J) ZZI = HI(I,J) I F (I . E Q . J) G O T O 5 6 0 YI = HI(I,J-I) HI(I,J-I) = XR * YI + XI ~ YR HR(I,J-I) = XR * YR - XI * YI HR(I,J) = XR * ZZR + Xl * ZZI HI(I,J) = XR * ZZI - XI * ZZR CONTINUE

****~*****

CONTINUE

283

+ + -

HI(J,J-I) HI(J,J-I) HI(J,J-I) HI(J,J-I)

* * * *

ZZI ZZR YR YI

7. 1 - 8 9

IF

(SI

.EQ~

0.0)

TO

240

DO

630

660

C C I000 I001

6 3 0 I = L, E N YR = HR(I,EN) Yi = HI(I,EN) HR(I,EN) = SR HI(I,EN) = SR CONTINUE

GO

* YR * YI

+

SI SI

* YI * YR

GO TO 240 ********** A ROOT FOUND ********** WR(EN) = HR(EN,EN) + TR WI(EN) = HI(EN,EN) + TI EN = ENMI GO TO 220 ********** SET ERROR -- NO CONVERGENCE TO EIGENVALUE AFTER 30 ITERATIONS IERR = EN RETURN END

284

AN **********

7.1-90

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F246

PACKAGE

(EISPACK)

COMQR2

A F o r t r a n IV S u b r o u t i n e to D e t e r m i n e the E i g e n v a l u e s and E i g e n v e c t o r s of a C o m p l e x Upper H e s s e n b e r g Matrix.

July , 1975

I. P U R P O S E . The F o r t r a n IV s u b r o u t i n e COMQR2 c o m p u t e s the e i g e n v a l u e s and e i g e n v e c t o r s of a c o m p l e x upper H e s s e n b e r g matrix. COMQR2 uses the QR m e t h o d to c o m p u t e the e i g e n v a l u e s and a c c u m u l a t e s the QR transformations to c o m p u t e the eigenvectors. The e i g e n v e c t o r s of a c o m p l e x g e n e r a l m a t r i x can also be c o m p u t e d d i r e c t l y by COMQR2, if CORTH (F244) has b e e n u s e d to r e d u c e this m a t r i x to H e s s e n b e r g form.

2. USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

COMQR2(NM,N,LOW,IGH,ORTR,ORTI,HR,HI, WR,WI,ZR,ZI,IERR)

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

is an i n t e g e r input v a r i a b l e set equal to the row d i m e n s i o n of the t w o - d i m e n s i o n a l arrays HR, HI, ZR, and ZI as s p e c i f i e d in the D I M E N S I O N s t a t e m e n t s for HR, HI, ZR, and ZI in the c a l l i n g program. is an i n t e g e r input v a r i a b l e set e q u a l the order of the m a t r i x H = (HR,HI). m u s t be not g r e a t e r than NM.

LOW,IGH

to N

are i n t e g e r input v a r i a b l e s i n d i c a t i n g the b o u n d a r y indices for the b a l a n c e d matrix. See s e c t i o n 3 of F271 for the details. If the m a t r i x is not b a l a n c e d , set LOW to 1 and IGH to N.

285

7.1-91

ORTR,ORT! are w o r k i n g p r e c i s i o n r e a l o n e - d i m e n s i o n a l v a r i a b l e s of d i m e n s i o n at least IGH. Only components LOW through IGH are used by COMQR2. If the e i g e n v e c t o r s of the H e s s e n b e r g m a t r i x are desired, set ORTR(J)=ORTI(J)=0.0 for J = LOW,LOW+I,..°,IGH. If the e i g e n v e c t o r s of a c o m p l e x g e n e r a l m a t r i x are d e s i r e d , ORTR and ORTI c o n t a i n some i n f o r m a t i o n a b o u t the u n i t a r y t r a n s f o r m a t i o n s generated by CORTH d u r i n g the r e d u c t i o n to the H e s s e n b e r g form. HR,HI

are w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l v a r i a b l e s w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at least N. On input, HR and HI c o n t a i n the r e a l and i m a g i n a r y parts, respectively, of the c o m p l e x u p p e r H e s s e n b e r g matrix. If the e i g e n v e c t o r s of the H e s s e n b e r g m a t r i x are desired, the lower t r i a n g l e s of HR,HI b e l o w the s u b d i a g o n a l may be a r b i t r a r y . If the e i g e n v e c t o r s of a c o m p l e x g e n e r a l m a t r i x are d e s i r e d , the lower t r i a n g l e s of HR,HI contain further i n f o r m a t i o n a b o u t the u n i t a r y transformations g e n e r a t e d by CORTH in the r e d u c t i o n to the H e s s e n b e r g form. Note: COMQR2 d e s t r o y s the u p p e r H e s s e n b e r g p o r t i o n s of HR,HI.

WR,WI

are w o r k i n g p r e c i s i o n real o u t p u t oned i m e n s i o n a l v a r i a b l e s of d i m e n s i o n at least N c o n t a i n i n g the real and i m a g i n a r y parts, respectively, of the e i g e n v a l u e s of the u p p e r H e s s e n b e r g matrix.

ZR, ZI

are w o r k i n g p r e c i s i o n r e a l o u t p u t twod i m e n s i o n a l v a r i a b l e s w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at least N containing the r e a l and i m a g i n a r y parts, r e s p e c t i v e l y , of the e i g e n v e c t o r s . The e i g e n v e c t o r s are not normalized.

IERR

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

286

to is

7.1-92

B.

Error

Conditions

and R e t u r n s .

If m o r e t h a n 30 i t e r a t i o n s are r e q u i r e d to d e t e r m i n e an e i g e n v a l u e , this s u b r o u t i n e t e r m i n a t e s w i t h IERR set to the i n d e x of the e i g e n v a l u e for w h i c h the f a i l u r e occurs. The e i g e n v a l u e s in the WR and WI arrays s h o u l d b e c o r r e c t for i n d i c e s IERR+I,IERR+2,...,N, but no e i g e n v e c t o r s are c o m p u t e d . If all the e i g e n v a l u e s are d e t e r m i n e d iterations, IERR is set to zero.

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

and

within

30

Restrictions.

To d e t e r m i n e the e i g e n v a l u e s and e i g e n v e c t o r s of a complex general matrix, COMQR2 m u s t be p r e c e d e d by C O R T H (F244) to p r o v i d e a s u i t a b l e c o m p l e x H e s s e n b e r g m a t r i x for COMQR2. It is r e c o m m e n d e d in g e n e r a l before CORTH in w h i c h case used after COMQR2.

that CBAL (F271) be used C B A B K 2 (F272) m u s t be

In this i m p l e m e n t a t i o n , the a r i t h m e t i c is r e a l t h r o u g h o u t e x c e p t for c o m p l e x s q u a r e root and c o m p l e x division.

3.

DISCUSSION

OF M E T H O D

AND

ALGORITHM.

The e i g e n v a l u e s are d e t e r m i n e d by the QR method. The e s s e n c e of this m e t h o d is a p r o c e s s w h e r e b y a s e q u e n c e of c o m p l e x u p p e r H e s s e n b e r g m a t r i c e s , s i m i l a r to the o r i g i n a l H e s s e n b e r g m a t r i x , is f o r m e d w h i c h c o n v e r g e s to a t r i a n g u l a r matrix. The rate of c o n v e r g e n c e of this s e q u e n c e is i m p r o v e d by s h i f t i n g the o r i g i n at each i t e r a t i o n . B e f o r e each i t e r a t i o n , the last H e s s e n b e r g f o r m is c h e c k e d for a p o s s i b l e s p l i t t i n g into s u b m a t r i c e s . If a s p l i t t i n g o c c u r s , o n l y the l o w e r s u b m a t r i x p a r t i c i p a t e s in the n e x t i t e r a t i o n . The s i m i l a r i t y t r a n s f o r m a t i o n s u s e d in e a c h i t e r a t i o n are a c c u m u l a t e d in the ZR and ZI a r r a y s a l o n g w i t h the r e d u c t i o n t r a n s f o r m a t i o n s for the o r i g i n a l m a t r i x . The o r i g i n s h i f t at each i t e r a t i o n is the e i g e n v a l u e of the lowest 2x2 p r i n c i p a l m i n o r c l o s e r to the s e c o n d d i a g o n a l e l e m e n t of this m i n o r . Whenever a lowest ixl principal s u b m a t r i x f i n a l l y s p l i t s f r o m the rest of the m a t r i x , its e l e m e n t is t a k e n to be an e i g e n v a l u e of the o r i g i n a l m a t r i x and the a l g o r i t h m p r o c e e d s w i t h the r e m a i n i n g s u b m a t r i x .

287

7.1-93

This p r o c e s s is c o n t i n u e d u n t i l the m a t r i x has s p l i t c o m p l e t e l y into s u b m a t r i c e s of o r d e r i. The t o l e r a n c e s in the s p l i t t i n g tests are p r o p o r t i o n a l to the r e l a t i v e m a c h i n e precision. The e i g e n v e c t o r s of this t r i a n g u l a r m a t r i x are d e t e r m i n e d by b a c k s u b s t i t u t i o n , and then b a c k t r a n s f o r m e d into those of the o r i g i n a l m a t r i x . The s u b d i a g o n a l e l e m e n t s are r e n d e r e d real diagonal unitary similarity transformation real t h r o u g h o u t COMQR2.

i n i t i a l l y by a and m a i n t a i n e d

Some of the e i g e n v a l u e s m a y h a v e b e e n i s o l a t e d on the d i a g o n a l by the s u b r o u t i n e CBAL (F271). This i n f o r m a t i o n is t r a n s m i t t e d to COMQR2 t h r o u g h the p a r a m e t e r s LOW and IGH. As a r e s u l t , COMQR2 i m m e d i a t e l y e x t r a c t s the e i g e n v a l u e s in rows i to LOW-I and IGH+I to N, and so a p p l i e s the QR p r o c e d u r e to the s u b m a t r i x s i t u a t e d in rows and c o l u m n s LOW through IGHo This s u b r o u t i n e is a t r a n s l a t i o n of a u n i t a r y a n a l o g u e of the Algol procedure COMLR2 w r i t t e n and d i s c u s s e d in d e t a i l by P e t e r s and W i l k i n s o n (I). The u n i t a r y a n a l o g u e s u b s t i t u t e s for the LR a l g o r i t h m the QR a l g o r i t h m , w r i t t e n and d i s c u s s e d in d e t a i l by F r a n c i s (2).

4. R E F E R E N C E S .

i)

2)

5.

Peters, G~ and W i l k i n s o n , J.H., E i g e n v e c t o r s of R e a l C o m p l e x M a t r i c e s by LR and QR T r i a n g u l a r i z a t i o n s , Num. Math. 1 6 , 1 8 1 - 2 0 4 (1970). ( R e p r i n t e d in H a n d b o o k A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , J. H. W i l k i n s o n - C. R e i n s c h , C o n t r i b u t i o n 11/15, 372-395, S p r i n g e r - V e r l a g , 1971.)

and

Francis, Comp. J.

2,

J.G.F., T h e QR T r a n s f o r m a t i o n - Parts 4 , 2 6 5 - 2 7 1 and 3 3 2 - 3 4 5 (1961/62).

1 and

for

CHECKOUT. A.

Test

Cases°

See the complex

section general

discussing matrices.

testing

of

the

codes

for

B. A c c u r a c y . The s u b r o u t i n e COMQR2 is n u m e r i c a l l y s t a b l e (1,2); that is, each c o m p u t e d e i g e n v a l u e and its c o r r e s p o n d i n g e i g e n v e c t o r are exact for a m a t r i x close to the o r i g i n a l upper H e s s e n b e r g m a t r i x .

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, 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 C O M P L E X Z3 COMPLEX CSQRT,CMPLX REAL REAL,AIMAG

X

******~***

M A C H E P IS A M A C H I N E D E P E N D E N T P A R A M E T E R S P E C I F Y I N G T H E R E L A T I V E P R E C I S I O N OF F L O A T I N G P O I N T A R I T H M E T I C . **********

MACHEP

=

?

IERR = 0 ********** INITIALIZE DO i00 I = I, N

EIGENVECTOR

MATRIX

**********

DO

I00 J = i, N Z R ( I , J ) = 0.0 Z I ( I , J ) = 0.0 IF (I .EQ. J) Z R ( I , J ) = 1.0 100 C O N T I N U E C * * * * * * * * * * F O R M T H E M A T R I X OF A C C U M U L A T E D TRANSFORMATIONS C F R O M T H E I N F O R M A T I O N L E F T BY C O R T H * * * * * * * * * * 1END = IGH - LOW - I IF (1END) 180, 150, 105 C * * * * * * * * * * F O R I = I G H - I S T E P -i U N T I L L O W + I DO -- * * * * * * * * * * 105 DO 140 II = i, 1 E N D I = IGH II IF ( O R T R ( 1 ) .EQ. 0 . 0 .AND. O R T I ( 1 ) .EQ. 0.0) GO TO 140 IF ( H R ( I , I - I ) .EQ. 0 . 0 .AND. H I ( I , I - I ) .EQ. 0.0) GO TO 140 C * * * * * * * * * * N O R M B E L O W IS N E G A T I V E OF H F O R M E D IN C O R T H * * * * * * * * * * NORM = HR(I,I-I) * ORTR(1) + HI(I,I-I) * ORTI(1) IPI = I + I DO

Ii0

ii0 K = IPI, IGH ORTR(K) = HR(K,I-I) ORTI(K) = Hl(K,l-l) CONTINUE

DO

130 J = I, SR = 0.0 SI = 0.0

IGH

DO

115

115 K = I, IGH SR = SR + 0 R T R ( K ) SI = SI + O R T R ( K ) CONTINUE

* ZR(K,J) * ZI(K,J)

289

+ ORTI(K) - ORTI(K)

* ZI(K,J) * ZR(K,J)

7.1-95

C SR SI

= =

SR SI

/ NORM / NORM

DO

1 2 0 K = I, I G H ZR(K,J) = ZR(K,J) ZI(K,J) = ZI(K,J) CONTINUE

120 130 140 150

+ +

SR SR

* ORTR(K) * ORTI(K)

+

SI SI

* ORTI(K) * ORTR(K)

CONTINUE CONTINUE ********** L = LOW + DO

CREATE

SUBDIAGONAL

ELEMENTS

**********

1 7 0 I = L, I G H LL = MINO(I+I,IGH) IF (Hi(I,I-I) .EQ. 0 . 0 ) G O T O 1 7 0 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 DO

155 J = SI = Y R HR(I,J) HI(I,J) CONTINUE

155

REAL

1

I, N * HI(I,J) - YI = YR * HR(I,J) = SI

1 6 0 J = I, L L Sl = Y R * H I ( J , I ) + YI HR(J,I) = YR * HR(J,I) HI(J,I) = SI CONTINUE

* HR(I,J) + YI * HI(I,J)

DO

160

DO

165 J = LOW, IGH SI = Y R * Z I ( J , I ) zR(J,I)

ZI(J,I) CONTINUE

165 170 180

200

CONTINUE ********** DO 200 I IF (I WR(I) WI(I) CONTINUE EN TR TI

=

= =

=

YR

=

SI

*

+

YI

ZR(J,I)

* HR(J,I) - YI * HI(J,I)

* ZR(J,I) -

STORE ROOTS ISOLATED = i, N .GE. L O W . A N D . I .LE. = H~(I,I) = HI(I,I)

IGH 0.0 0.0

290

~I

*

ZI(J,I)

BY

CBAL

IGH)

GO

********** TO

20O

7.1-96

C 220

C C 240

260 C 300

310

C 320

340

360

********** SEARCH FOR NEXT EIGENVALUE ********** IF (EN .LT. L O W ) G O TO 6 8 0 ITS = 0 E N M I = EN i ********** LOOK FOR SINGLE SMALL SUB-DIAGONAL ELEMENT F O R L = E N S T E P -i U N T I L L O W D O -- * * * * * * * * * * D O 2 6 0 LL = L O W , E N L = EN + LOW - LL IF (L .EQ. L O W ) G O TO 3 0 0 IF ( A B S ( H R ( 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 CONTINUE ********** FORM SHIFT ********** IF (L .EQ. EN) G O T O 6 6 0 IF ( I T S .EQ. 30) G O T O I 0 0 0 IF (ITS .EQ. i0 .OR. ITS .EQ. 20) G O T O 3 2 0 SR = H R ( E N , E N ) SI = H I ( E N , E N ) XR = HR(ENMI,EN) * HR(EN,ENMI) XI = H I ( E N M I , E N ) * HR(EN,ENMI) IF ( X R .EQ. 0 . 0 . A N D . XI .EQ. 0 . 0 ) G O TO 3 4 0 YR = (HR(ENMI,ENMI) - SR) / 2 . 0 YI = (HI(ENMI,ENMI) - SI) / 2 . 0 Z3 = C S Q R T ( C M P L X ( Y R * * 2 - Y I * * 2 + X R , 2 . 0 * Y R * Y I + X I ) ) ZZR = REAL(Z3) ZZI = AIMAG(Z3) IF (YR * Z Z R + Y I * Z Z I .GE. 0 . 0 ) GO TO 3 1 0 ZZR = -ZZR ZZI = -ZZI Z3 = C M P L X ( X R , XI) / C M P L X ( Y R + Z Z R , Y I + Z Z I ) S R = SR - R E A L ( Z 3 ) SI = SI - A I M A G ( Z 3 ) GO TO 340 ********** FORM EXCEPTIONAL SHIFT ********** SR = A B S ( H R ( E N , E N M I ) ) + ABS(HR(ENMI,EN-2)) SI = 0 . 0 DO

3 6 0 1 = L O W , EN HR(I,I) = HR(I,I) HI(I,I) = HI(I,I) CONTINUE

T R = T R + SR T I = TI + SI ITS = I T S + 1 ********** REDUCE LPI = L + i

TO

-

SR SI

TRIANGLE

291

(ROWS)

**********

7.1-97

DO

X

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 DO

4 9 0 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 HI(I-I,J) = XR HR(I,J) = XR * HI(I,J) = XR * CONTINUE

490 500

* YR + XI * YI * YI - XI * YR ZZR - XI * ZZI ZZI + XI * ZZR

+ + -

HI(I,I-I) HI(I,I-I) HI(I,I-I) HI(I,I-I)

CONTINUE SI = HI(EN,EN) I F (SI .EQ. 0 . 0 ) G O T O 5 4 0 NORM = CABS(CMPLX(HR(EN,EN),SI)) SR = HR(EN,EN) / NORM SI = S I / N O R M HR(EN,EN) = NORM HI(EN,EN) = 0.0 I F ( E N .EQ. N) G O T O 5 4 0 IPI = EN + 1 DO

520 540

520 J = IPI, N YR = HR(EN,J) YI = HI(EN,J) HR(EN,J) = SR * HI(EN,J) = SR * CONTINUE • ********* INVERSE DO 600 J = LPI, EN XR = WR(J-I) xi = wi(J-1) DO

5 8 0 I = I, J YR = HR(I,J-l) YI = 0.0 ZZR = HR(I,J) ZZI = HI(I,J) IF (I . E Q . J)

YR YI

+ -

SI SI

* *

OPERATION

GO

TO

560

292

YI YR (COLUMNS)

**********

* ZZR * ZZI * YR * YI

7.1-98

YI = HI(I,J-I) HI(I,J-I) = XR HR(I,J-I) = XR HR(I,J) = XR * HI(I,J) = XR * CONTINUE

560

580

* YI + Xl * YR * YR - XI * YI ZZR + XI * ZZI ZZI - XI * ZZR

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 ZI(I,J-I) = XR * YI + XI * YR ZR(I,J) = XR * ZZR + XI * ZZI ZI(I,J) = XR * ZZI - Xl * ZZR CONTINUE

+ + -

HI(J,J-I) HI(J,J-I) HI(J,J-I) HI(J,J-I)

* * * *

ZZl ZZR YR YI

+ + -

HI(J,J-I) HI(J,J-I) HI(J,J-I) HI(J,J-I)

* * * *

ZZR ZZI YR YI

DO

590 600

CONTINUE IF

(SI

.EQ.

0.0)

TO

240

DO

630

6 3 0 I = i~ E N YR = HR(I,EN) YI = HI(I,EN) HR(I,EN) = SR HI(I,EN) = SR CONTINUE

GO

* *

YR YI

SI SI

* YI * YR

+

SI SI

* *

DO

640

660

680

640 I = LOW, IGH YR = ZR(I,EN) YI = ZI(I,EN) ZR(I,EN) = SR * YR ZI(I,EN) = SR * YI CONTINUE

+

YI YR

GO TO 240 ********** A ROOT FOUND ********** 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 BACKSUBSTITUTE ********** ALL ROOTS FOUND. VECTORS OF UPPER TRIANGULAR FORM NORM = 0.0 DO

720

1

=

i,

TO FIND **********

N

DO

720

7 2 0 J = I, N NORM = NORM + CONTINUE

ABS(HR(I,J))

293

+

ABS(HI(I,J))

7.1-99

IF (N oEQ. i .OR. N O R M .EQ. 0 . 0 ) G O T O I 0 0 1 ********** FOR EN=N STEP -i UNTIL 2 DO -- ********** D O 8 0 0 N N = 2, N EN = N + 2 - NN XR = WR(EN) XI = WI(EN) E N M I = EN 1 ********** FOR I=EN-I STEP -i UNTIL 1 DO -- ********** D O 7 8 0 II = I, E N M I I = EN II ZZR = HR(I,EN) ZZI = HI(I,EN) IF (I .EQ. E N M I ) GO TO 760 IPI = I + i DO

740 J ZZR = ZZ! = CONTINUE

740 760

YR YI

= IPI~ ENMI ZZR + HR(I,J) ZZI + HR(I,J)

=

XR

-

=

Xi

-

* HR(J,EN) * HI(J,EN)

- HI(I,J) + HI(I,J)

WR(1) WI(I)

IF ( Y R .EQ. 0 . 0 . A N D . Y I .EQ. 0 . 0 ) Z3 = CMPLX(ZZR,ZZI) / CMPLX(YR, YI) HR(I,EN) = REAL(Z3) HI(I,EN) = AIMAG(Z3) CONTINUE

780

* HI(J,EN) * HR(J,EN)

YR

= MACHEP

* NORM

C 800 C C

CONTINUE ********** END BACKSUBSTITUTiON ENMI = N - I ********** VECTORS OF ISOLATED DO 8 4 0 ! = i, E N M I I F (I .GE. L O W . A N D . I .LE. IPI = I + i DO

820 J = ZR(!,J) ZI(I,J) CONTINUE

820 840

IPI,

= =

ROOTS IGH)

********** GO

TO

840

N

HR(I,J) Hl(l,J)

CONTINUE **********

DO

**********

MULTIPLY BY TRANSFORMATION MATRIX VECTORS OF ORIGINAL FULL MATRIX. F O R J = N S T E P -I U N T I L L O W + I DO -880 JJ = LOW, ENMI J = N + LOW - JJ M = MIN0(J-I,IGH) DO

880 ZZR ZZI

I = LOW, IGH = ZR(I,J) = ZI(I,J)

294

TO

GIVE

**********

7.1-100

DO

860 K = LOW, M ZZR = ZZR + ZR(I,K) ZZI = ZZI + ZR(I,K) CONTINUE

860

880

ZR(I,J) ZI(I,J) CONTINUE GO TO i001 **********

C C i000 i001

IERR = RETURN END

= =

* HR(K,J) * HI(K,J)

+

ZI(I,K) ZI(I,K)

* HI(K,J) * HR(K,J)

ZZR ZZI

SET ERROR EIGENVALUE

-- NO CONVERGENCE TO AFTER 30 ITERATIONS

EN

295

AN **********

7.1-101

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F247

PACKAGE

(EISPACK)

CORTB

A F o r t r a n IV S u b r o u t i n e to B a c k T r a n s f o r m the E i g e n v e c t o r s of that U p p e r H e s s e n b e r g M a t r i x D e t e r m i n e d by CORTH.

July,

1975

I. P U R P O S E . T h e F o r t r a n IV s u b r o u t i n e CORTB f o r m s the e i g e n v e c t o r s of a c o m p l e x g e n e r a l m a t r i x f r o m the e i g e n v e c t o r s of that u p p e r H e s s e n b e r g m a t r i x d e t e r m i n e d by C O R T H (F244).

2.

USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

CORTB(NM,LOW, IGH,AR,AI,ORTR,ORTI, M,ZR,ZI)

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

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to the r o w d i m e n s i o n of the t w o - d i m e n s i o n a l arrays AR, AI, ZR, and ZI as s p e c i f i e d in the D I M E N S I O N s t a t e m e n t s for AR, AI, ZR, and ZI in the c a l l i n g p r o g r a m .

LOW, IGH

are i n t e g e r i n p u t v a r i a b l e s i n d i c a t i n g the b o u n d a r y i n d i c e s for the b a l a n c e d m a t r i x . See s e c t i o n 3 of F271 for the d e t a i l s . If the m a t r i x is not b a l a n c e d , set LOW to i and IGH to the o r d e r of the m a t r i x .

AR,AI

are w o r k i n g p r e c i s i o n real i n p u t twodimensional variables with row dimension NM and c o l u m n d i m e n s i o n at l e a s t IGH. Their l o w e r t r i a n g l e s c o n t a i n some i n f o r m a t i o n a b o u t the u n i t a r y t r a n s f o r m a t i o n s used in

296

7.1-i02

the r e d u c t i o n to the H e s s e n b e r g form. The r e m a i n i n g u p p e r p a r t s of AR and AI are arbitrary. See s e c t i o n 3 of F244 for the details. ORTR,ORTI are w o r k i n g p r e c i s i o n r e a l o n e - d i m e n s i o n a l v a r i a b l e s of d i m e n s i o n at least IGH. On input, ORTR and ORTI contain further i n f o r m a t i o n a b o u t the u n i t a r y t r a n s f o r m a t i o n s u s e d in the r e d u c t i o n by CORTH. See s e c t i o n 3 of F244 for the details. ORTR and ORTI are u s e d for temporary storage within CORTB and are n o t restored.

B.

Error

M

is an i n t e g e r input v a r i a b l e set e q u a l the n u m b e r of c o l u m n s of Z = (ZR,ZI) back transformed.

ZR,ZI

are w o r k i n g p r e c i s i o n real t w o - d i m e n s i o n a l variables with row dimension NM and c o l u m n d i m e n s i o n at l e a s t M. On input, the f i r s t M c o l u m n s of ZR and ZI c o n t a i n the r e a l and i m a g i n a r y p a r t s , r e s p e c t i v e l y , of the e i g e n v e c t o r s to be b a c k t r a n s f o r m e d . On output, these M c o l u m n s of ZR and ZI c o n t a i n the real and i m a g i n a r y P a r t s of the transformed eigenvectors.

Conditions

and

to to be

Returns.

None.

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

and

Restrictions.

This s u b r o u t i n e s h o u l d be used subroutine C O R T H (F244).

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

OF M E T H O D

AND

in

conjunction

with

the

ALGORITHM.

S u p p o s e that the m a t r i x c (say) has b e e n upper Hessenberg form F s t o r e d in A by transformation

F = Q CQ

297

r e d u c e d to the the s i m i l a r i t y

7.1-103

where Q is a p r o d u c t of the u n i t a r y m a t r i c e s e n c o d e d in ORTR,ORTI and in a lower t r i a n g l e of A under F. Then, g i v e n an a r r a y Z of c o l u m n v e c t o r s , CORTB c o m p u t e s the matrix product QZ. If the e i g e n v e c t o r s of F are c o l u m n s of the a r r a y Z, then CORTB forms the e i g e n v e c t o r s of C in their place. This s u b r o u t i n e is a t r a n s l a t i o n Algol procedure ORTBAK written M a r t i n and W i l k i n s o n (i).

of a c o m p l e x a n a l o g u e of the and d i s c u s s e d in d e t a i l by

4. R E F E R E N C E S .

I)

5.

M a r t i n ~ R.S. and W i l k i n s o n , J.H., Similarity Reduction of a G e n e r a l M a t r i x to H e s s e n b e r g Form, Num. Math. 1 2 , 3 4 9 - 3 6 8 (1968)o ( R e p r i n t e d in H a n d b o o k for A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , J. H. W i l k i n s o n - C. R e i n s c h , C o n t r i b u t i o n II/13~ 339-358, S p r i n g e r - V e r l a g , 1971.)

CHECKOUT. A.

Test

Cases~

See the complex

section general

discussing matrices.

testing

of

the

codes

for

B. A c c u r a c y . The a c c u r a c y of CORTB can b e s t be d e s c r i b e d in terms of its role in t h o s e paths of EISPACK w h i c h find e i g e n v a l u e s and e i g e n v e c t o r s of c o m p l e x g e n e r a l matrices. In t h e s e paths, this s u b r o u t i n e is numerically s t a b l e (i). This s t a b i l i t y c o n t r i b u t e s to the p r o p e r t y of these paths that each c o m p u t e d e i g e n v a l u e and its c o r r e s p o n d i n g e i g e n v e c t o r are exact for a m a t r i x close to the o r i g i n a l matrix.

298

7.1-104

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 C IF (M .EQ. 0) GO TO 2 0 0 LA = IGH - 1 KPI = LOW + I IF (LA .LT. K P I ) GO TO 2 0 0 ********** FOR MP=IGH-I S T E P -i U N T I L L O W + I DO -- * * * * * * * * * * D O 140 M M = K P I , L A MP = LOW + IGH - MM IF ( A R ( M P , M P - I ) .EQ. 0 . 0 . A N D . A I ( M P , M F - I ) .EQ. 0 . 0 ) X G O T O 140 ********** H BELOW IS N E G A T I V E OF H F O R M E D IN C O R T H * * * * * * * * * * H = AR(MP,MP-I) * ORTR(MP) + AI(MP,MP-1) * ORTI(MP) MPI = MP + 1

C

DO

100

i00 I = MPI, IGH ORTR(1) = AR(I,MP-I) ORTI(1) = AI(I,MP-I) CONTINUE

DO

130 J = i, GR = 0.0 GI = 0 . 0

M

DO

I i 0 1 = MP, I G H GR = GR + ORTR(1) GI = GI + O R T R ( 1 ) CONTINUE

Ii0

GR GI

=

GR

/

=

GI

/ H

* ZR(I,J) * ZI(I,J)

+ ORTI(1) - ORTI(1)

* ZI(I,J) * ZR(I,J)

H

DO

120 I = M P , I G H ZR(I,J) = ZR(I,J) ZI(I,J) = ZI(I,J) CONTINUE

120 130

+ +

GR GR

CONTINUE

140

CONTINUE

200

RETURN END

299

* ORTR(I) * ORTI(1)

- GI + GI

*

ORTI(1)

* ORTR(1)

7.1-105

NATS

EiGENSYSTEM

PROJECT

SUBROUTINE F244

A Fortran to U p p e r

PACKAGE

(EISPACK)

CORTH

IV S u b r o u t i n e to R e d u c e a C o m p l e x G e n e r a l M a t r i x Hessenberg Form Using Unitary Transformations.

July,

1975

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e CORTH reduces a complex general m a t r i x to c o m p l e x u p p e r H e s s e n b e r g f o r m u s i n g u n i t a r y similarity transformations. T h i s r e d u c e d f o r m is u s e d by o t h e r s u b r o u t i n e s to f i n d the e i g e n v a l u e s a n d / o r e i g e n v e c t o r s of the o r i g i n a l m a t r i x . See s e c t i o n 2C for the s p e c i f i c routines.

2.

USAGE. A,

Calling The

Sequence,

SUBROUTINE SUBROUTINE

statement

is

CORTH(NM,N,LOW, IGH,AR,AI,ORTR,ORTI)

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

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

N

is an i n t e g e r i n p u t v a r i a b l e set e q u a l the o r d e r of the m a t r i x A = (AR,AI). m u s t be n o t g r e a t e r t h a n NM.

LOW,IGH

are i n t e g e r i n p u t v a r i a b l e s i n d i c a t i n g the b o u n d a r y i n d i c e s for the b a l a n c e d m a t r i x , See s e c t i o n 3 of F271 for the d e t a i l s . If the m a t r i x is n o t b a l a n c e d , set LOW to I and IGH to N.

300

to N

7.1-106

are w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l v a r i a b l e s w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at least N. On input, AR and AI c o n t a i n the r e a l and i m a g i n a r y parts, respectively, of the c o m p l e x m a t r i x of order N to be r e d u c e d to H e s s e n b e r g form. On output, AR and AI c o n t a i n the r e a l and i m a g i n a r y parts of the upper H e s s e n b e r g m a t r i x as w e l l as some i n f o r m a t i o n about the unitary transformations u s e d in the reduction. See s e c t i o n 3 for the details.

AR,AI

ORTR,ORTI are w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e s of d i m e n s i o n at least IGH c o n t a i n i n g the r e m a i n i n g i n f o r m a t i o n about the u n i t a r y t r a n s f o r m a t i o n s . See s e c t i o n 3 for the details. Only c o m p o n e n t s LOW+I through IGH are a c t u a l l y u s e d by CORTH.

B.

Error

Conditions

and

Returns.

None.

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

and

Restrictions.

If all the e i g e n v a l u e s of the o r i g i n a l m a t r i x are desired, this s u b r o u t i n e s h o u l d be f o l l o w e d by COMQR (F245). If all the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e s h o u l d be f o l l o w e d by C O M Q R 2 (F246). If some of the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x are desired, this s u b r o u t i n e s h o u l d be f o l l o w e d by C O M Q R (F245), C I N V I T (F297), and CORTB (F247). If the m a t r i x has e l e m e n t s of w i d e l y v a r y i n g m a g n i t u d e s , the larger ones should be in the top l e f t - h a n d corner.

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

OF M E T H O D that

A

AND

ALGORITHM.

the m a t r i x

=

A =

(T ( 0

X B

Y) Z )

(0

0

R)

301

(AR,AI)

has

the

form

7.1-!07

where T and R are upper triangular matrices, B is a s q u a r e m a t r i x s i t u a t e d in r o w s a n d c o l u m n s LOW through IGH, and X, Y, and Z are r e c t a n g u l a r m a t r i c e s of the appropriate dimensions. T h e n the s u b r o u t i n e CORTH performs unitary similarity transformations to r e d u c e B to H e s s e n b e r g form. The H e s s e n b e r g r e d u c t i o n is p e r f o r m e d in the f o l l o w i n g way. Starting with J=LOW, the e l e m e n t s in the J-th column below the d i a g o n a l are f i r s t s c a l e d , to a v o i d p o s s i b l e u n d e r f l o w in the t r a n s f o r m a t i o n that m i g h t r e s u l t in s e v e r e d e p a r t u r e f r o m orthogonality. The s u m of s q u a r e d m a g n i t u d e s SIGMA of t h e s e s c a l e d e l e m e n t s is n e x t formed. Then, a v e c t o r U and a scalar

H = U U/2 define

an o p e r a t o r

P = I - UU

/H

w h i c h is u n i t a r y and H e r m i t i a n and for w h i c h transformation PAP e l i m i n a t e s the e l e m e n t s c o l u m n of A b e l o w the s u b d i a g o n a l .

the s i m i l a r i t y in the J-th

The n o n - z e r o c o m p o n e n t s of U are the e l e m e n t s of the J-th c o l u m n b e l o w the d i a g o n a l w i t h the f i r s t of t h e m a u g m e n t e d by the s q u a r e root of SIGMA times the s u b d i a g o n a l e l e m e n t d i v i d e d by its m a g n i t u d e . By s a v i n g this c o m p o n e n t in the array 0RTR,ORTI and not o v e r w r i t i n g the c o l u m n e l e m e n t s e l i m i n a t e d in the t r a n s f o r m a t i o n ~ f u l l i n f o r m a t i o n on P is s a v e d for l a t e r use in COMQR2 and CORTB. The t r a n s f o r m a t i o n r e p l a c e s the s u b d i a g o n a l e l e m e n t w i t h the s q u a r e r o o t of SIGMA times the n e g a t i v e of the r e p l a c e d e l e m e n t d i v i d e d by its m a g n i t u d e . The a b o v e steps are r e p e a t e d on f u r t h e r c o l u m n s of transformed A until B is r e d u c e d to H e s s e n b e r g is, r e p e a t e d for J = LOW+I,LOW+2,...,IGH-2. This s u b r o u t i n e is a t r a n s l a t i o n Algol procedure ORTHES written M a r t i n and W i l k i n s o n (I).

302

the form;

that

of a c o m p l e x a n a l o g u e of the and d i s c u s s e d in d e t a i l by

7.1-108

4. REFERENCES.

1)

Martin, R.S. and Wilkinson, J.H., Similarity R e d u c t i o n of a General M a t r i x to H e s s e n b e r g Form, Num. Math. 12,349-368 (1968). (Reprinted in H a n d b o o k for Automatic Computation, Volume II, Linear Algebra, J. H. W i l k i n s o n - C. Reinsch, C o n t r i b u t i o n 11/13, 339-358, S p r i n g e r - V e r l a g , 1971.)

5. CHECKOUT. A. Test

Cases.

See the section complex general

discussing matrices.

testing

of the codes

for

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 n u m e r i c a l l y stable (i). This stability contributes to the property of these paths that each computed e i g e n v a l u e and its c o r r e s p o n d i n g eigenvector are exact for a m a t r i x close to the original matrix.

303

7.1-109

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 I F ( L A .LT. K P I ) DO

90

i00

180 M = H = 0.0 ORTR(M) ORTI(M) SCALE = ********** DO 90 1 SCALE =

KPI,

GO

TO

200

LA

= 0.0 = 0.0 0 ~0 SCALE COLUMN (ALGOL TOL THEN NOT NEEDED) = M, I G H SCALE + ABS(AR(I,M-I)) + ABS(AI(I,M-I))

**********

IF ( S C A L E .EQ. 0 . 0 ) G O T O 1 8 0 MP = M + IGH ********** FOR I=IGH STEP -i UNTIL M DO -- ********** D O i 0 0 II = M, I G H 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 = S Q R T (H) F = CABS(CMPLX(ORTR(M),ORTI(M))) IF (F .EQ. 0 . 0 ) G O T O 1 0 3 H = H + F * G g = g / F ORTR(M) = ( i . 0 + G) * O R T R ( M ) ORTI(M) = ( i . 0 + G) * O R T I ( M ) GO TO 105

103

105

II0

ORTR(M) = G AR(M,M-I) = SCALE ********** FORM (I-(U*UT)/H) D O 1 3 0 J = M, N FR = 0.0 FI = 0.0 ********** FOR I=IGH STEP -i D O I I 0 II = M, I G H I = MP II FR = FR + ORTR(I) * FI = FI + ORTR(I) * CONTINUE

304

* A

**********

UNTIL

AR(I,J) AI(I,J)

M

DO

--

**********

+ ORTI(I) - ORTI(I)

* AI(I,J) * AR(I,J)

7.1-110

FR FI

=

FR

/

=

FI

/ H

H

DO

120 1 = AR(I,J) AI(I,J) CONTINUE

120 130

140

M, I G H = AR(I,J) = AI(I,J)

- FR - FR

* ~

ORTR(1) ORTI(1)

+ -

FI FI

* *

ORTI(1) ORTR(1)

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 -- *~**~**** D O 1 4 0 J J = M, I G H J = MP - JJ FR = FR + ORTR(J) * AR(I,J) - ORTI(J) * AI(I,J) FI = FI + ORTR(J) * AI(I,J) + ORTI(J) * A R ( I , J ) CONTINUE FR FI

= =

FR FI

/ H / H

DO

150 J = M, IGH AR(I,J) = AR(I,J) AI(I,J) = AI(I,J) CONTINUE

150 160

180 200

+

CONTINUE ORTR(M) = ORTI(M) = AR(M,M-I) AI(M,M-I) CONTINUE

SCALE * ORTR(M) SCALE * ORTI(M) = -G * AR(M,M-I) = -G * AI(M,M-I)

RETURN END

305

FR FR

* *

ORTR(J) ORTI(J)

- FI - FI

* *

ORTI(J) ORTR(J)

7.1-111

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F274-2

A Fortran of that

(EISPACK)

ELMBAK

IV S u b r o u t i n e to B a c k T r a n s f o r m the E i g e n v e c t o r s U p p e r H e s s e n b e r g M a t r i x D e t e r m i n e d by ELMHES.

May, July,

1.

PACKAGE

1972 1975

PURPOSE, The F o r t r a n IV s u b r o u t i n e ELMBAK f o r m s the e i g e n v e c t o r s a r e a l g e n e r a l m a t r i x f r o m the e i g e n v e c t o r s of that u p p e r H e s s e n b e r g m a t r i x d e t e r m i n e d by E L M H E S (F273).

of

2. U S A G E . A°

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

ELMBAK(NM, LOW,IGH,A, INT,M,Z)

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

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

LOW, IGH are i n t e g e r i n p u t v a r i a b l e s i n d i c a t i n g the b o u n d a r y i n d i c e s for the b a l a n c e d m a t r i x . See s e c t i o n 3 of F269 for the d e t a i l s . If the m a t r i x is n o t b a l a n c e d , set LOW to I and IGH to the o r d e r of the m a t r i x . is a w o r k i n g p r e c i s i o n r e a l i n p u t twod i m e n s i o n a l v a r i a b l e w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at least IGH. Its l o w e r t r i a n g l e b e l o w the s u b d i a g o n a l c o n t a i n s the m u l t i p l i e r s w h i c h w e r e u s e d in the r e d u c t i o n to the H e s s e n b e r g form. The r e m a i n i n g u p p e r p a r t of A is a r b i t r a r y . See s e c t i o n 3 of F273 for the d e t a i l s .

306

7.1-112

INT

is an i n t e g e r i n p u t o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t IGH. INT identifies the rows and c o l u m n s i n t e r c h a n g e d d u r i n g the r e d u c t i o n by ELMHES. See s e c t i o n 3 of F273 for the d e t a i l s . is an i n t e g e r the n u m b e r of transformed.

input variable c o l u m n s of Z

set e q u a l to to be b a c k

is a w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t M. On input, the f i r s t M c o l u m n s of Z c o n t a i n the real and i m a g i n a r y p a r t s of the e i g e n v e c t o r s to be back transformed. On o u t p u t , t h e s e M c o l u m n s of Z c o n t a i n the real and i m a g i n a r y p a r t s of the t r a n s f o r m e d eigenvectors.

B.

Error

Conditions

and

Returns.

None.

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

and

Restrictions.

This s u b r o u t i n e s h o u l d be u s e d subroutine E L M H E S (F273).

in c o n j u n c t i o n

The r e a l and i m a g i n a r y p a r t s of an e i g e n v e c t o r be s t o r e d in c o n s e c u t i v e c o l u m n s of Z.

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

OF M E T H O D

AND

with

the

need

not

ALGORITHM.

S u p p o s e that the m a t r i x C (say) has b e e n r e d u c e d to the upper Hessenberg form F s t o r e d in A b y the s i m i l a r i t y transformation -i F = G

CG

where G is a p r o d u c t of the p e r m u t a t i o n and e l e m e n t a r y m a t r i c e s e n c o d e d in INT and in a lower t r i a n g l e of A under F respectively. Then, g i v e n an a r r a y Z of c o l u m n vectors, ELMBAK c o m p u t e s the m a t r i x p r o d u c t GZ. If the r e a l and i m a g i n a r y p a r t s of the e i g e n v e c t o r s of F are c o l u m n s of the a r r a y Z, then ELMBAK f o r m s the e i g e n v e c t o r s of C in their place.

307

7.1-113

This s u b r o u t i n e ELMBAK written Wilkinson (i).

4o

REFERENCES.

I)

5.

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

M a r t i n , RoS. and W i l k i n s o n ~ J.H., Similarity Reduction of a G e n e r a l M a t r i x to H e s s e n b e r g Form, Num. Math. 1 2 , 3 4 9 - 3 6 8 (1968). ( R e p r i n t e d in H a n d b o o k for $ u t o m a t i e C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , J, H. W i l k i n s o n - C. R e i n s c h , C o n t r i b u t i o n 11/13, 339-358, Springer-Verlag, 1971.)

CHECKOUT. Ao

Test

Cases~

See the s e c t i o n d i s c u s s i n g real general matrices.

B.

testing

of

the

codes

for

Accuracy~ The a c c u r a c y of ELMBAK can b e s t be d e s c r i b e d in terms of its role in those p a t h s of EISPACK w h i c h find e i g e n v a l u e s and e i g e n v e c t o r s of real g e n e r a l m a t r i c e s . In these paths, this s u b r o u t i n e is, in p r a c t i c e , numerically s t a b l e (i). T h i s s t a b i l i t y c o n t r i b u t e s to the p r o p e r t y of these p a t h s that each c o m p u t e d e i g e n v a l u e and its c o r r e s p o n d i n g e i g e n v e c t o r are exact for a m a t r i x c l o s e to the o r i g i n a l m a t r i x .

308

7.1-114

SUBROUTINE

ELMBAK(NM~LOW,

IGH,A, INT,M,Z)

INTEGER I,J,M, LA,MM,MP,NM, REAL A(NM,IGH),Z(NM,M) REAL X INTEGER INT(IGH)

IGH,KPI,LOW,MPI

IF (M .EQ. 0) GO T O 2 0 0 LA = IGH - i KPI = LOW + i IF ( L A .LT. K P I ) G O T O 2 0 0 ********** FOR MP=IGH-I STEP DO 140 MM = KPI, LA MP = LOW + IGH - MM MPI = MP + i DO

DO i00 Z(I,J)

i00 ii0

ii0 I = MPI, IGH X = A(I,MP-I) IF (X .EQ. 0 . 0 ) G O J =

= i, M Z(I,J) +

TO

X

GO

TO

140

DO

130

1 3 0 J = I, M X = Z(I,J) Z(I,J) = Z(MP,J) Z(MP,J) = X CONTINUE

140

CONTINUE

200

RETURN END

UNTIL

ii0

* Z(MP,J)

CONTINUE I = INT(MP) IF (I .EQ. MP)

-i

309

LOW+I

DO

--

**********

7.1-115

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F273

PACKAGE

(EISPACK)

ELMHES

A F o r t r a n IV S u b r o u t i n e to R e d u c e a Real G e n e r a l M a t r i x to Upper Hessenberg Form Using Elementary Transformations.

May,

1972

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e ELMHES reduces a real general m a t r i x to u p p e r H e s s e n b e r g f o r m u s i n g s t a b i l i z e d e l e m e n t a r y similarity transformations. This r e d u c e d f o r m is u s e d by o t h e r s u b r o u t i n e s to find the e i g e n v a l u e s a n d / o r e i g e n v e c t o r s of the o r i g i n a l m a t r i x . See s e c t i o n 2C for the s p e c i f i c routines.

2. U S A G E . A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

E L M H E S ( N M , N , L O W , IGH,A, INT)

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

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

N

is an i n t e g e r i n p u t v a r i a b l e the o r d e r of the m a t r i x A. g r e a t e r than NM.

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

LOW, IGH are i n t e g e r i n p u t v a r i a b l e s i n d i c a t i n g the b o u n d a r y i n d i c e s for the b a l a n c e d m a t r i x . If See s e c t i o n 3 of F269 for the d e t a i l s . 1 the m a t r i x is n o t b a l a n c e d , set LOW to and IGH to N.

310

7.1-I16

is a w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l variable with row dimension NM and c o l u m n d i m e n s i o n at least N. On input, A c o n t a i n s the m a t r i x of o r d e r N to be r e d u c e d to H e s s e n b e r g form. On o u t p u t , A c o n t a i n s the upper H e s s e n b e r g m a t r i x as well as the m u l t i p l i e r s used in the r e d u c t i o n . See s e c t i o n 3 for the details. is an i n t e g e r o u t p u t o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least IGH i d e n t i f y i n g the rows and c o l u m n s i n t e r c h a n g e d d u r i n g the r e d u c t i o n . See s e c t i o n 3 for the details. Only c o m p o n e n t s LOW+I through IGH-I are a c t u a l l y u s e d by ELMHES.

INT

B.

Error

Conditions

and Returns.

None.

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

and

Restrictions.

If all the e i g e n v a l u e s of the o r i g i n a l m a t r i x are desired, this s u b r o u t i n e s h o u l d be f o l l o w e d by HQR (F286). If a l l the m a t r i x are by ELTRAN

e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l d e s i r e d , this s u b r o u t i n e s h o u l d be f o l l o w e d (F220) and HQR2 (F287).

If some of the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x are desired, this s u b r o u t i n e s h o u l d f o l l o w e d by HQR (F286), INVIT (F288), and ELMBAK (F274).

be

The s u b r o u t i n e ELMHES e x e c u t e s f a s t e r than its counterpart O R T H E S (F275), w h i c h uses o r t h o g o n a l similarity transformations. ORTHES is, h o w e v e r , m o r e a c c u r a t e in some cases. It is r e c o m m e n d e d that ELMHES be used in general.

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

OF M E T H O D that

AND

ALGORITHM.

the m a t r i x

=

( T (0 (0

A X B 0

has Y ) Z) R)

311

the

form

7.1-117

where T and R are u p p e r t r i a n g u l a r m a t r i c e s , B is a s q u a r e m a t r i x s i t u a t e d in rows and c o l u m n s LOW through IGH, and X, Y, and Z are r e c t a n g u l a r m a t r i c e s of the appropriate dimensions. T h e n the s u b r o u t i n e ELMHES p e r f o r m s p e r m u t a t i o n and e l e m e n t a r y s i m i l a r i t y transformations to r e d u c e B to H e s s e n b e r g form. The H e s s e n b e r g r e d u c t i o n is p e r f o r m e d in the f o l l o w i n g way. Starting with J=LOW, a p e r m u t a t i o n s i m i l a r i t y t r a n s f o r m a t i o n is p e r f o r m e d t o s t a b i l i z e the s u c c e e d i n g e l e m e n t a r y transformations in the J-th c o l u m n of A. Next, e a c h n o n zero e l e m e n t b e l o w the s u b d i a g o n a l in the J-th c o l u m n of A is e l i m i n a t e d u s i n g e l e m e n t a r y s i m i l a r i t y t r a n s f o r m a t i o n s . The p e r m u t a t i o n s i m i l a r i t y t r a n s f o r m a t i o n is d e t e r m i n e d by s e a r c h i n g for the e l e m e n t of m a x i m u m m o d u l u s in the J-th c o l u m n b e l o w the s u b d i a g o n a l . This e l e m e n t is p l a c e d into the s u h d i a g o n a l p o s i t i o n by a row i n t e r c h a n g e a n d the corresponding c o l u m n i n t e r c h a n g e is m a d e to c o m p l e t e the permutation transformation. The index of the row i n t e r c h a n g e d w i t h the (J+l)-th row is s t o r e d in INT(J+I). The e l e m e n t a r y t r a n s f o r m a t i o n c o n s i s t s of e l e m e n t a r y row o p e r a t i o n s on the J-th c o l u m n of A to e l i m i n a t e the n o n zero e l e m e n t s b e l o w the s u b d i a g o n a l and the c o r r e s p o n d i n g e l e m e n t a r y c o l u m n o p e r a t i o n s to c o m p l e t e the s i m i l a r i t y . The m u l t i p l i e r s u s e d in this e l i m i n a t i o n p r o c e s s are s t o r e d in p l a c e of the e l i m i n a t e d e l e m e n t s . These multipliers as w e l l as the row i n t e r c h a n g e i n f o r m a t i o n in INT are u s e d later in ELTRAN for the a c c u m u l a t i o n of the t r a n s f o r m a t i o n s and in ELMBAK for the b a c k t r a n s f o r m a t i o n of the e i g e n v e c t o r s , The a b o v e steps are r e p e a t e d on f u r t h e r c o l u m n s of the transformed A untii B is r e d u c e d to H e s s e n b e r g form; is, r e p e a t e d for J = LOW+I,LOW+2,...,IGH-2. This s u b r o u t i n e ELMHES written Wilkinson (I).

that

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

4. R E F E R E N C E S .

I)

M a r t i n , R.S. and W i l k i n s o n , J.H., Similarity Reduction of a G e n e r a l M a t r i x to H e s s e n b e r g Form, Num. Math. 1 2 , 3 4 9 - 3 6 8 (1968). ( R e p r i n t e d in H a n d b o o k for A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , J. H. W i l k i n s o n - C. R e i n s c h , C o n t r i b u t i o n 11/13, 339-358, S p r i n g e r - V e r l a g , 1971.)

312

7.1-118

5.

CHECKOUT. A.

Test

Cases.

See the s e c t i o n d i s c u s s i n g real g e n e r a l m a t r i c e s .

B.

testing

of

the

codes

for

Accuracy. The a c c u r a c y of ELMHES can b e s t be d e s c r i b e d in terms of its role in those paths of EISPACK w h i c h find e i g e n v a l u e s and e i g e n v e c t o r s of real g e n e r a l m a t r i c e s . In these paths, this s u b r o u t i n e is, in p r a c t i c e , n u m e r i c a l l y s t a b l e (I). This s t a b i l i t y c o n t r i b u t e s to the p r o p e r t y of these paths that each c o m p u t e d e i g e n v a l u e and its c o r r e s p o n d i n g e i g e n v e c t o r are e x a c t for a m a t r i x close to the o r i g i n a l m a t r i x .

313

7.1-119

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 I F ( L A .LT. K P I ) DO

180 M = MMI = M X = 0.0 I = M

KPI, - i

GO

TO

200

LA

DO

i00

Ii0

i 0 0 J = M, I G H IF ( A B S ( A ( J , M M I ) ) X = A(J,MMI) ! = J CONTINUE

.LE.

I N T (M) = I IF (I .EQ. M) G O T O ****22***2 INTERCHANGE DO II0 J = MMI, N Y = A(I,J) A(I,J) = A(M,J) A(M,J) = Y CONTINUE

130 ROWS

ABS(X))

AND

COLUMNS

DO

120 130

1 2 0 J = i, ! G H Y = A(J,I) A(J,I) = A(J,M) A(J,M) = Y CONTINUE ********** END INTERCHANGE ********** IF (X .EQ. 0 . 0 ) G O T O 1 8 0 MPI = M + 1 DO

160 1 = MPI, IGH Y = A(I,MMI) I F (Y .EQ. 0 . 0 ) G O Y = Y / X A(I,MMI) = Y

TO

160

C 140

DO 140 A(I,J)

J =

150

DO 150 A(J,M)

J = i, I G H = A(J,M) +

160

= M, N A(I,J)

- Y

Y

* A(M,J)

* A(J,I)

CONTINUE

3t4

GO

TO

i00

OF

A

**,2,2,~,2

7.1-120

C 180

CONTINUE

200

RETURN END

C

315

7. 1-121

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F220

PACKAGE

(EISPACK)

ELTRAN

A F o r t r a n IV S u b r o u t i n e to A c c u m u l a t e the T r a n s f o r m a t i o n s in the R e d u c t i o n of a R e a l G e n e r a l M a t r i x b y ELMHES.

May,

1972

I. P U R P O S E . The F o r t r a n IV s u b r o u t i n e ELTRAN a c c u m u l a t e s the s t a b i l i z e d e l e m e n t a r y s i m i l a r i t y t r a n s f o r m a t i o n s u s e d in the r e d u c t i o n of a r e a l g e n e r a l m a t r i x to u p p e r H e s s e n b e r g f o r m b y ELMHES (F273).

2. U S A G E . A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

ELTRAN(NM,N,LOW,IGH,A,INT,Z)

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

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

N

is an i n t e g e r i n p u t v a r i a b l e the o r d e r of the m a t r i x A. g r e a t e r than NM.

LOW,IGH

are i n t e g e r i n p u t v a r i a b l e s i n d i c a t i n g the b o u n d a r y i n d i c e s for the b a l a n c e d m a t r i x . See s e c t i o n 3 of F269 for the d e t a i l s . If the m a t r i x is n o t b a l a n c e d , set LOW to 1 and IGH to N.

316

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

7.1-122

A

is a w o r k i n g p r e c i s i o n r e a l i n p u t twodimensional variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t IGH. Its lower t r i a n g l e b e l o w the s u b d i a g o n a l c o n t a i n s the m u l t i p l i e r s w h i c h w e r e u s e d in the r e d u c t i o n to the H e s s e n b e r g form. The r e m a i n i n g u p p e r p a r t of A is a r b i t r a r y . See s e c t i o n 3 of F273 for the details.

INT

is an i n t e g e r input o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least IGH. INT identifies the rows and c o l u m n s i n t e r c h a n g e d d u r i n g the r e d u c t i o n by ELMHES. See s e c t i o n 3 of F273 for the details. is a w o r k i n g p r e c i s i o n r e a l o u t p u t twod i m e n s i o n a l v a r i a b l e w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at l e a s t N. It c o n t a i n s the t r a n s f o r m a t i o n m a t r i x p r o d u c e d in the r e d u c t i o n by ELMHES to the u p p e r H e s s e n b e r g form.

B.

Error

Conditions

and

Returns.

None.

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

and

Restrictions.

If all the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e f o l l o w s ELMHES (F273) and s h o u l d be f o l l o w e d b y H Q R 2 (F287). O t h e r w i s e , this s u b r o u t i n e w i l l not o r d i n a r i l y be used.

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

OF M E T H O D

AND

ALGORITHM.

S u p p o s e that the m a t r i x C (say) has b e e n upper Hessenberg form F s t o r e d in A by transformation

r e d u c e d to the the s i m i l a r i t y

-I F = G

CG

where G is a p r o d u c t of the p e r m u t a t i o n and e l e m e n t a r y m a t r i c e s e n c o d e d in INT and in a lower t r i a n g l e of A under F respectively. Then, ELTRAN accumulates G into the a r r a y Z. This s u b r o u t i n e is a t r a n s l a t i o n of the A l g o l p r o c e d u r e ELMTRANS w r i t t e n and d i s c u s s e d in d e t a i l by P e t e r s and W i l k i n s o n (i).

317

7.1-123

4. REFERENCES.

i)

5.

Peters, G. and Wilkinson, J.H., E i g e n v e c t o r s of Real Complex Matrices by LR and QR T r i a n g u l a r i z a t i o n s , Num. Math. 16,181-204 (1970). (Reprinted in H a n d b o o k A u t o m a t i c Computation, V o l u m e II, Linear Algebra, J. H. W i l k i n s o n - C. Reinsch, C o n t r i b u t i o n 11/15, 372-395, S p r i n g e r - V e r l a g , 1971.)

and for

CHECKOUT. A.

Test

Cases.

See the section d i s c u s s i n g real general matrices.

testing

of the

codes

for

B. Accuracy. ELTRAN introduces no rounding transfers the m u l t i p l i e r s used into the e i g e n v e c t o r matrix.

318

errors since it only in the reduction process

7.1-124

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) C C

**mmmmm,,, D O 80 I =

60

INITIALIZE lj N

D O 60 J = i, Z(l,J) = 0.0

Z TO

IDENTITY

MATRIX

,mmm,m,mm,

N

C 80

Z(I,I) CONTINUE

=

1.0

KL = IGH - LOW - 1 IF (EL .LT. i) G O TO 2 0 0 *********m FOR MP=IGH-I STEP DO 1 4 0 M M = i, K L M P = IGH MM MPI = MP + I

i00

DO i00 I = M P I ~ I G H Z(I,MP) = A(I,MP-I) I = INT(MP) IF (I .EQ~ M P )

GO

TO

140

DO

130

140 200

1 3 0 J = MP, I G H Z(MP,J) = Z(I,J) Z(I,J) = 0.0 CONTINUE

Z(I,MP) CONTINUE

=

1.0

RETURN END

319

-I

UNTIL

LOW+I

DO

--

**********

7.1-125

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F280-2

PACKAGE

(EISPACK)

FIGI

A F o r t r a n IV S u b r o u t i n e to T r a n s f o r m a C e r t a i n Non-Symmetric T r i d i a g o n a l M a t r i x to a Symmetric Tridiagonal Matrix.

May, July,

Real

1972 1975

I. P U R P O S E . The F o r t r a n IV s u b r o u t i n e FIGI transforms a certain real non-symmetric t r i d i a g o n a l m a t r i x to a s y m m e t r i c t r i d i a g o n a l matrix. The p r o p e r t y of the n o n - s y m m e t r i c m a t r i x r e q u i r e d for use of this s u b r o u t i n e is that the p r o d u c t s of p a i r s of c o r r e s p o n d i n g o f f - d i a g o n a l e l e m e n t s be all n o n - n e g a t i v e . The t r a n s f o r m e d m a t r i x is u s e d by o t h e r s u b r o u t i n e s to f i n d the e i g e n v a l u e s a n d / o r e i g e n v e c t o r s of the o r i g i n a l m a t r i x . See s e c t i o n 2C for the s p e c i f i c r o u t i n e s .

2. U S A G E . A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

FIGI(NM,N,T,D,E,E2,1ERR)

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

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

320

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

7.1-126

is a w o r k i n g p r e c i s i o n r e a l i n p u t twodimensional variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t 3. T c o n t a i n s the n o n - s y m m e t r i c t r i d i a g o n a l m a t r i x of o r d e r N in its f i r s t t h r e e columns. The s u b d i a g o n a l e l e m e n t s are s t o r e d in the last N-I p o s i t i o n s of the f i r s t column. The d i a g o n a l e l e m e n t s are s t o r e d in the s e c o n d column. The s u p e r d i a g o n a l e l e m e n t s are s t o r e d in the first N-I p o s i t i o n s of the third column. Elements T(I,I) and T(N,3) are arbitrary. is a w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N c o n t a i n i n g the d i a g o n a l e l e m e n t s of the t r i d i a g o n a l symmetric m a t r i x . is a w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g , in its last N-I positions, the s u b d i a g o n a l e l e m e n t s of the t r i d i a g o n a l symmetric matrix. The e l e m e n t E(1) is n o t referenced.

B.

Error

E2

is a w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g , in its last N-I positions, the s q u a r e s of the s u b d i a g o n a l e l e m e n t s of the t r i d i a g o n a l s y m m e t r i c matrix. The element E2(1) is n o t r e f e r e n c e d . E2 need not be d i s t i n c t f r o m E (non-standard usage a c c e p t a b l e w i t h at l e a s t t h o s e c o m p i l e r s i n c l u d e d in the c e r t i f i c a t i o n s t a t e m e n t ) s in w h i c h case no s q u a r e s are r e t u r n e d .

IERR

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

Conditions

and

to is

Returns.

If the p r o d u c t of T(I,I) and T(I-I,3) is n e g a t i v e , FIGI terminates with IERR set to N+I. In this case, a s y m m e t r i c m a t r i x c a n n o t be p r o d u c e d w i t h this p r o g r a m . If the p r o d u c t of T(I,I) and T(I-I,3) is zero but either T(I,I) or T(I-I,3) is n o t zero, FIGI sets IERR to -(3*N+I) and c o n t i n u e s . If this o c c u r s m o r e t h a n once, the last o c c u r r e n c e is r e c o r d e d in IERR. See s e c t i o n 3.

321

7.1-127

If the p r o d u c t s of all pairs of c o r r e s p o n d i n g offd i a g o n a l e l e m e n t s are n o n - n e g a t i v e , and zero only w h e n b o t h f a c t o r s are zero, IERR is set to zero.

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

and

Restrictions.

If all the e i g e n v a ! u e s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e s h o u l d he f o l l o w e d by IMTQLI (F291). If some of the e i g e n v a l u e s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e s h o u l d be f o l l o w e d by BISECT (F294) or T R I D I B (F237). If some of the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e s h o u l d be f o l l o w e d by T S T U R M (F293), or by B I S E C T (F294) and T I N V I T (F223), or by T R I D I B (F237) and TINVIT, or by ! M T Q L V (F234) and TINVlT, and then by B A K V E C (F281). If all the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x are d e s i r e d , s u b r o u t i n e FIGI2 (F222) s h o u l d be used r a t h e r than FIGI to p e r f o r m the s y m m e t r i z a t i o n , and s h o u l d be f o l l o w e d by IMTQL2 (F292).

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

OF M E T H O D

AND

ALGORITHM.

The t r a n s f o r m a t i o n is p e r f o r m e d in the f o l l o w i n g way° If the p r o d u c t s of p a i r s of c o r r e s p o n d i n g o f f - d i a g o n a l e l e m e n t s of T are all p o s i t i v e or if b o t h e l e m e n t s are zero, a nonsingular diagonal matrix V can be d e f i n e d such that the similarity transformation -i V

TV

produces a symmetric tridiagona! subdiagonal E as follows: D(J) E(J)

= T(J,2), J : I , 2 , 3 , .... N, = SQRT(T(J,I) * T(J-I,3)),

The d i a g o n a l follows: v(1,1)

and

:

elements

of

the

matrix

with

diagonal

D

J:2,3, .... N.

transformation

matrix

V

are

i.o,

for J=2,3,...,N V(J,J) = V ( J - I , J - I ) * S Q R T ( T ( J , I ) / T(J-I,3)) if T(J,I) * T ( J - I , 3 ) is p o s i t i v e , or

V(J,J)

= 1.0

if b o t h

T(J,I)

322

and

and

T(J-I,3)

are

zero.

as

7.1-128

If the product of a pair of c o r r e s p o n d i n g o f f - d i a g o n a l elements is zero but only one of the elements is zero, then the symmetric t r i d i a g o n a l m a t r i x defined above has the same eigenvalues as T but its eigenvectors are not simply related to those of T. In this case, the back t r a n s f o r m a t i o n subroutine BAKVEC (F281), if called, will set an error flag indicating that the computed eigenvectors are not valid. This s u b r o u t i n e is an i m p l e m e n t a t i o n of the a l g o r i t h m discussed in detail by W i l k i n s o n (I).

4. REFERENCES. i)

Wilkinson, J.H., Oxford, Clarendon

The Algebraic E i g e n v a l u e Press, 335-337 (1965).

Problem,

5. CHECKOUT. A. Test

Cases.

See the section discussing certain real n o n - s y m m e t r i c

testing of the codes for tridiagonal matrices.

B. Accuracy. The accuracy of FIGI can best be d e s c r i b e d in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of certain real nonsymmetric t r i d i a g o n a l matrices. In these paths, this subroutine is n u m e r i c a l l y stable (I). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not n e c e s s a r i l y 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 R E A L T ( N M , 3) ,D (N), E (N), E2 (N) REAL SQRT IERR

= 0

DO

6O

80 90 i00

I00 1 = !~ N IF (I .EQ. i) GO TO 90 E2(1) = T(I,I) * T(I-I,3) IF ( E 2 ( 1 ) ) I 0 0 0 , 60, 80 IF ( r ( l , l ) .EQ. 0 . 0 .AND. r ( l - l , 3 ) .EQ. 0.0) GO TO 80 ********** SET E R R O R -- P R O D U C T OF S O M E P A I R OF O F F - D I A G O N A L E L E M E N T S IS Z E R O W I T H O N E M E M B E R N O N - Z E R O * * * * * * * * * * I E R R = -(3 * N + I) E(1) = S Q R T ( E 2 ( 1 ) ) D(1) = T(I,2) CONTINUE

GO TO I001 ********** i000 I001

SET E R R O R -- P R O D U C T E L E M E N T S IS N E G A T I V E IERR = N + I RETURN END

324

OF S O M E P A I R **********

OF

OFF-DIAGONAL

7.1-130

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F222

PACKAGE

(EISPACK)

FIGI2

A F o r t r a n IV S u b r o u t i n e to T r a n s f o r m a C e r t a i n R e a l N o n - S y m m e t r i c T r i d i a g o n a l M a t r i x to a S y m m e t r i c T r i d i a g o n a l M a t r i x A c c u m u l a t i n g the D i a g o n a l T r a n s f o r m a t i o n s .

May,

1972

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e FIGI2 transforms a certain real non-symmetric t r i d i a g o n a l m a t r i x to a s y m m e t r i c t r i d i a g o n a l m a t r i x u s i n g and a c c u m u l a t i n g d i a g o n a l s i m i l a r i t y transformations. The p r o p e r t y of the n o n - s y m m e t r i c m a t r i x r e q u i r e d for use of this s u b r o u t i n e is that the p r o d u c t s of p a i r s of c o r r e s p o n d i n g o f f - d i a g o n a l e l e m e n t s be all n o n n e g a t i v e , and zero only w h e n b o t h f a c t o r s are zero. The s y m m e t r i z e d m a t r i x and the t r a n s f o r m a t i o n m a t r i x are u s e d by subroutine I M T Q L 2 (F292) to find the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x .

2. USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

FIGI2(NM,N,T,D,E,Z,IERR)

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

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

325

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

7.1-131

is a w o r k i n g p r e c i s i o n real i n p u t twodimensional variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t 3. T c o n t a i n s the n o n - s y m m e t r i c tridiagonal m a t r i x of o r d e r N in its f i r s t t h r e e columns. The s u b d i a g o n a l e l e m e n t s are s t o r e d in the last N-I p o s i t i o n s of the f i r s t column. The d i a g o n a l e l e m e n t s are s t o r e d in the s e c o n d column. The s u p e r d i a g o n a l e l e m e n t s are s t o r e d in the first N-I p o s i t i o n s of the third column. Elements T(I,!) and T(N,3) are arbitrary. is a w o r k i n g p r e c i s i o n real o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g the d i a g o n a l e l e m e n t s of the tridiagonal symmetric matrix. is a w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g , in its last N-I positions, the s u b d i a g o n a l e l e m e n t s of the t r i d i a g o n a l symmetric matrix. The e l e m e n t E(1) is not referenced. is a w o r k i n g p r e c i s i o n r e a l o u t p u t twod i m e n s i o n a l v a r i a b l e w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at least N. It c o n t a i n s the d i a g o n a l t r a n s f o r m a t i o n m a t r i x p r o d u c e d in the s y m m e t r i z a t i o n . IERR

B.

Error

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

Conditions

and

to is

Returns.

If the p r o d u c t of T(i,I) and T(!-I,3) is n e g a t i v e , FIGI2 terminates with IERR set to N+I. If the p r o d u c t of T(I,I) and T(I-I,3) is zero b u t e i t h e r T(I,I) or T(!-I,3) is n o t zero, FIGI2 terminates with IERR set to 2*N+I. In t h e s e cases, there does not e x i s t a s y m m e t r i z i n g s i m i l a r i t y t r a n s f o r m a t i o n , e s s e n t i a l for the v a l i d i t y of the later e i g e n v e c t o r computation. If the p r o d u c t s of all p a i r s of c o r r e s p o n d i n g offd i a g o n a l e l e m e n t s are n o n - n e g a t i v e , and zero only w h e n b o t h f a c t o r s are zero, IERR is set to zero.

326

7.1-132

C. A p p l i c a b i l i t y If all the m a t r i x are by IMTQL2

and R e s t r i c t i o n s . e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l d e s i r e d , this s u b r o u t i n e s h o u l d be f o l l o w e d (F292).

If some other c o m b i n a t i o n of e i g e n v a l u e s and e i g e n v e c t o r s is desired, s u b r o u t i n e FIGI (F280) be used r a t h e r than FIGI2 to p e r f o r m the symmetrization.

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

OF M E T H O D

AND

should

ALGORITHM.

The t r a n s f o r m a t i o n is p e r f o r m e d in the f o l l o w i n g way. If the p r o d u c t s of pairs of c o r r e s p o n d i n g o f f - d i a g o n a l e l e m e n t s of T are all p o s i t i v e or if b o t h e l e m e n t s are zero, a nonsingular diagonal matrix Z can be d e f i n e d such that the similarity transformation -i Z

TZ

produces a symmetric tridiagonal subdiagonal E as follows: D(J) E(J)

= T(J,2), J = 1 , 2 , 3 , .... N, = SQRT(T(J,I) * T(J-I,3)),

The d i a g o n a l follows: z(1,1)

and

=

elements

of the

matrix

with

diagonal

D

J=2,3,...,N.

transformation

matrix

Z

are

1.0,

for J=2,3,...,N Z(J,J) = Z ( J - I , J - I ) * S Q R T ( T ( J , I ) / T(J-I,3)) if T(J,I) * T ( J - I , 3 ) is p o s i t i v e , or Z(J,J) = 1.0 if b o t h T(J,I) and T(J-I,3) are

This s u b r o u t i n e is an i m p l e m e n t a t i o n of the d i s c u s s e d in d e t a i l by W i l k i n s o n (i).

zero.

algorithm

4. R E F E R E N C E S . i)

W i l k i n s o n , J.H., Oxford, C l a r e n d o n

The A l g e b r a i c E i g e n v a l u e Press, 3 3 5 - 3 3 7 (1965).

327

and

Problem,

as

7.1-133

5.

CHECKOUT. A.

Test

Cases°

See the certain

B,

section discussing real non-symmetric

t e s t i n g of the c o d e s for tridiagonal matrices.

Accuracy, The a c c u r a c y of FIGI2 can b e s t be d e s c r i b e d in terms of its r o l e in t h o s e p a t h s of EISPACK which find e i g e n v a l u e s and e i g e n v e c t o r s of c e r t a i n r e a l n o n symmetric tridiagonal matrices. In t h e s e p a t h s , this s u b r o u t i n e is n u m e r i c a l l y s t a b l e (i). This s t a b i l i t y c o n t r i b u t e s to the p r o p e r t y of t h e s e p a t h s that the c o m p u t e d e i g e n v a l u e s are the e x a c t e i g e n v a l u e s of a m a t r i x c l o s e to the o r i g i n a l m a t r i x and the c o m p u t e d e i g e n v e c t o r s are c l o s e (but not n e c e s s a r i l y equal) to the e i g e n v e c t o r s of that m a t r i x .

328

7.1-134

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, REAL H REAL SQRT

N)

C

IERR

= 0

C

DO

i00

I =

I,

N

C

50

DO 50 J = i, Z ( I , J ) = 0.0

N

60

IF (I .EQ. 1) G O TO 70 H = T(I,I) * T(I-I,3) IF (H) 900, 60, 80 IF ( T ( I , I ) .NE. 0.0 .OR.

C

E(I)

70 80

=

.NE.

0.0)

GO

TO

I000

Z ( I , I ) = 1.0 GO TO 90 E(1) = S Q R T ( H )

Z(I,I) 90 i00

T(I-I,3)

0.0

= Z(I-I,I-1)

D(I) = CONTINUE

* E(I)

/

T(I-I,3)

T(I,2)

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

C C 900

1000 I001

IERR = N + G O TO 1001 ********** IERR = RETURN END

S E T E R R O R -- P R O D U C T ELEMENTS IS N E G A T I V E I

OF S O M E P A I R **e*****e*

OF

OFF-DIAGONAL

SET E R R O R -- P R O D U C T OF S O M E P A I R OF O F F - D I A G O N A L ELEMENTS IS Z E R O W I T H O N E M E M B E R N O N - Z E R O ~***e***~* 2 * N + I

329

7. 1-135

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F286-2

A F o r t r a n IV S u b r o u t i n e of a R e a l U p p e r

PACKAGE

(EISPACK)

HQR

to D e t e r m i n e the E i g e n v a l u e s Hessenberg Matrix.

May, July,

1972 1975

i. P U R P O S E ~ T h e F o r t r a n IV s u b r o u t i n e HQR c o m p u t e s the e i g e n v a l u e s r e a l u p p e r H e s s e n b e r g m a t r i x u s i n g the QR method.

of

a

2. U S A G E . A.

Calling The

Sequence°

SUBROUTINE SUBROUTINE

statement

is

HQR(NM,N,LOW, IGH,H,WR,WI,IERR)

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

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

LOW,!GH

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

are i n t e g e r i n p u t v a r i a b l e s i n d i c a t i n g the b o u n d a r y i n d i c e s for the b a l a n c e d m a t r i x . See s e c t i o n 3 of F269 for the d e t a i l s . If the m a t r i x is not b a l a n c e d , set LOW to 1 and IGH to N.

330

7.1-136

B.

Error

H

is a w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l v a r i a b l e w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at least N. On input, it c o n t a i n s the u p p e r H e s s e n b e r g m a t r i x . Note: HQR d e s t r o y s this u p p e r H e s s e n b e r g m a t r i x as w e l l as the two a d j a c e n t d i a g o n a l s b e l o w it.

WR,WI

are w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e s of d i m e n s i o n at least N c o n t a i n i n g the real and i m a g i n a r y parts, r e s p e c t i v e l y , of the e i g e n v a l u e s of the Hessenberg matrix. The e i g e n v a l u e s are u n o r d e r e d e x c e p t that c o m p l e x c o n j u g a t e p a i r s of e i g e n v a l u e s a p p e a r c o n s e c u t i v e l y w i t h the e i g e n v a l u e h a v i n g the p o s i t i v e i m a g i n a r y p a r t first.

IERR

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

Conditions

and

to is

Returns.

If m o r e than 30 i t e r a t i o n s are r e q u i r e d to d e t e r m i n e an e i g e n v a l u e , this s u b r o u t i n e t e r m i n a t e s w i t h IERR set to the i n d e x of the e i g e n v a l u e for w h i c h the f a i l u r e occurs. The e i g e n v a l u e s in the WR and WI arrays s h o u l d be c o r r e c t for i n d i c e s IERR+I,IERR+2,...,N. If all the e i g e n v a l u e s are d e t e r m i n e d iterations, IERR is set to zero.

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

and

within

30

Restrictions.

To d e t e r m i n e s o m e of the e i g e n v e c t o r s of a r e a l Hessenberg matrix, HQR s h o u l d be f o l l o w e d by INVIT (F288) to c o m p u t e t h o s e e i g e n v e c t o r s . Note, h o w e v e r , that the u p p e r H e s s e n b e r g m a t r i x m u s t be s a v e d b e f o r e HQR for l a t e r u s e by INVIT. To d e t e r m i n e the e i g e n v a l u e s of a r e a l g e n e r a l m a t r i x , HQR m u s t be p r e c e d e d by E L M H E S (F273) or ORTHES (F275) to p r o d u c e a s u i t a b l e u p p e r H e s s e n b e r g m a t r i x for HQR.

331

7.1-137

To d e t e r m i n e s o m e of the e i g e n v e c t o r s of a r e a l g e n e r a l matrix, HQR s h o u l d be p r e c e d e d by E L M H E S (F273) or O R T H E S (F275) and f o l l o w e d by I N V I T (F288) and E L M B A K (F274) or O R T B A K (F276). ELMBAK or ORTBAK b a c k t r a n s f o r m s the e i g e n v e c t o r s f r o m INVIT into those of the r e a l g e n e r a l m a t r i x . N o t e , h o w e v e r , that the u p p e r H e s s e n b e r g m a t r i x and the two a d j a c e n t d i a g o n a l s b e l o w it m u s t be s a v e d b e f o r e HQR for the later use by INVIT and ELMBAK or ORTBAK, since HQR destroys this p o r t i o n of H. It is r e c o m m e n d e d in g e n e r a l that B A L A N C (F269) be used before ELMHES or ORTHES in w h i c h case BALBAK (F270) m u s t be u s e d a f t e r ELMBAK or ORTBAK if e i g e n v e c t o r s are c o m p u t e d .

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

OF M E T H O D

AND

ALGORITHM.

The e i g e n v a l u e s are d e t e r m i n e d by the QR method. The e s s e n c e of this m e t h o d is a p r o c e s s w h e r e b y a s e q u e n c e of u p p e r H e s s e n b e r g m a t r i c e s , u n i t a r i l y s i m i l a r to the o r i g i n a l H e s s e n b e r g m a t r i x , is f o r m e d w h i c h c o n v e r g e s to a q u a s i t r i a n g u l a r m a t r i x , that is, an u p p e r H e s s e n b e r g m a t r i x w h o s e e i g e n v a ! u e s are the e i g e n v a l u e s of ixl or 2x2 principal submatrices. T h e r a t e of c o n v e r g e n c e of this s e q u e n c e is i m p r o v e d by s h i f t i n g the o r i g i n at each i t e r a t i o n . The a r i t h m e t i c t h r o u g h o u t the p r o c e s s is k e p t real by c o m b i n i n g two i t e r a t i o n s into one, u s i n g two r e a l o r i g i n s h i f t s or a p a i r of c o m p l e x c o n j u g a t e o r i g i n shifts. B e f o r e each i t e r a t i o n , the last H e s s e n b e r g f o r m is c h e c k e d for a p o s s i b l e s p l i t t i n g into s u b m a t r i c e s . If a s p l i t t i n g occurs, o n l y the l o w e r s u b m a t r i x p a r t i c i p a t e s in the n e x t i t e r a t i o n . The o r i g i n s h i f t s at e a c h i t e r a t i o n are the e i g e n v a l u e s of the l o w e s t 2x2 principal minor. Whenever a lowest ixl or 2x2 p r i n c i p a l s u b m a t r i x f i n a l l y s p l i t s f r o m the rest of the m a t r i x , the e i g e n v a l u e s of this s u b m a t r i x are taken to be e i g e n v a l u e s of the o r i g i n a l m a t r i x and the a l g o r i t h m p r o c e e d s w i t h the r e m a i n i n g s u b m a t r i x . T h i s p r o c e s s is c o n t i n u e d u n t i l the m a t r i x has s p l i t c o m p l e t e l y into s u b m a t r i c e s of order i or 2. T h e t o l e r a n c e s in the s p l i t t i n g tests are p r o p o r t i o n a l to the r e l a t i v e m a c h i n e p r e c i s i o n . Some of the e i g e n v a l u e s m a y h a v e b e e n i s o l a t e d on the d i a g o n a l by the s u b r o u t i n e B A L A N C (F269). This i n f o r m a t i o n is t r a n s m i t t e d to HQR t h r o u g h the p a r a m e t e r s LOW and IGH. As a r e s u l t , HQR i m m e d i a t e l y e x t r a c t s the e i g e n v a l u e s in r o w s I to LOW-I and IGH+I to N, and so a p p l i e s the QR p r o c e d u r e to the s u b m a t r i x s i t u a t e d in rows and c o l u m n s LOW through IGH.

332

7.1-138

This subroutine is a translation of the Algol procedure w r i t t e n and discussed in detail by Martin, Peters, and W i l k i n s o n (i).

HQR

4. REFERENCES.

i)

Martin, R.S., Peters, G., and Wilkinson, J.H., The QR A l g o r i t h m for Real Hessenberg Matrices, Num. Math. 14,219-231 (1970). (Reprinted in H a n d b o o k for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C° Reinsch, C o n t r i b u t i o n 11/14, 359-371, Springer-Verlag, 1971.)

5. CHECKOUT. A. Test Cases. See the section discussing real general matrices.

testing of the codes for

B. Accuracy. The subroutine HQR is n u m e r i c a l l y 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, 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

=

MACHEP IS A THE RELATIVE

40

50

I =

WR(1) WI(I)

C 60

C C 70

80 C !00

STORE ROOTS AND COMPUTE i, N

ISOLATED BY MATRIX NORM

BALANC **********

D O 4 0 J = K, N NORM = NORM + ABS(H(I,J)) K = I IF (I

50

MACHINE DEPENDENT PARAMETER SPECIFYING PRECISION OF FLOATING POINT ARITHMETIC.

?

IERR = 0 NORM = 0.0 K = 1 ********** DO

IGH, ITS,LOW,MP2,ENM2,IERR

.GE. = =

LOW

.AND.

I

.LE.

IGH)

GO

TO

50

H(I,I) 0.0

CONTINUE EN = !GH T=0.0 ********** SEARCH FOR NEXT EIGENVALUES ********** IF ( E N .LT. L O W ) G O T O i 0 0 1 ITS = 0 NA = EN - 1 E N M 2 = NA - 1 ********** LOOK FOR SINGLE SMALL SUB-DIAGONAL ELEMENT FOR L=EN STEP -I UNTIL LOW DO -- ********** D O 80 L L = L O W , E N L = EN + LOW - LL IF (L .EQ. L O W ) G O T O i 0 0 S = ABS(H(L-I,L-I)) + ABS(H(L,L)) IF ( S , E Q . 0.0) S = NORM IF (ABS(H(L,L-I)) .LE. M A C H E P * S) G O T O I 0 0 CONTINUE ********** FORM SHIFT ********** X = H(EN,EN) IF (L .EQ. E N ) G O T O 2 7 0 Y = H(NA,NA) W = H(EN,NA) * H(NA,EN) IF (L .EQ. N A ) G O T O 2 8 0 IF ( I T S .EQ. 30) G O T O i 0 0 0

334

7. 1 - 1 4 0

120

130

IF ( I T S .NE. i0 ********** FORM T = T + X

. A N D . I T S .NE. 20) G O T O 1 3 0 EXCEPTIONAL SHIFT **********

DO 120 H(I,I)

EN - X

1 = LOW, = H(!,I)

S = ABS(H(EN,NA)) + ABS(H(NA,ENM2)) X = 0.75 * S Y = X W = -0.4375 * S * S ITS = ITS + 1 • ********* LOOK FOR TWO CONSECUTIVE SMALL SUB-DIAGONAL ELEMENTS. F O R M--EN-2 S T E P - I U N T I L L D O - D O 1 4 0 M M = L, E N M 2 M = ENM2 + L - MM ZZ = H ( M , M ) R -- X - Z Z 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 I F (M .EQ. L) G O T O 1 5 0 IF ( A B S ( H ( M , M - I ) ) * (ABS(Q) + X * (ABS(H(M-I,M-I)) + ABS(ZZ) 140 CONTINUE 150

MP2

= M +

ABS(R)) .LE. M A C H E P + ABS(H(M+I,M+I))))

2

DO

160

160 I = MP2, EN H(I,I-2) = 0.0 IF (I .EQ. M P 2 ) G O T O 1 6 0 H(I,I-3) = 0.0 CONTINUE ********** DOUBLE QR STEP INVOLVING ROWS COLUMNS M TO EN ********** D O 2 6 0 K = M, N A NOTLAS = K .NE. N A IF (K .EQ. M) G O T O 1 7 0 P = H(K,K-I) Q = H(K+I,K-I) R=O.0 IF ( N O T L A S ) R = H(K+2,K-I) X = ABS(P) + ABS(Q) + ABS(R) IF (X . E Q . 0 . 0 ) G O T O 2 6 0 P = e / X Q = Q / X

R=~/X

335

L

TO

EN

AND

* ABS(P) GO TO 150

7.1-141

170

180 190

S = SIGN(SQRT(P*P+Q*Q+R*R),P) I F (K .EQ. M ) G O T O 1 8 0 H(K,K-I) = -S * X GO TO 190 IF (L .NE. M) H ( K , K - I ) = -H(K,K-I) P = P + S

x=e/s Y

=

zz

Q

/ S

=R

/ S

210

Q = Q / e R = R / P • ********* ROW MODIFICATION ********** D O 2 1 0 J = K, E N 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 H(K+I,J) = H(K+I,J) - P * Y H(K,J) = H(K,J) - P * X CONTINUE

220

J = MIN0(EN,K+3) ********** COLUMN MODIFICATION ********** D O 2 3 0 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

200

H(l,K)

230 260

CONTINUE

270

G O T O 70 ********** WR(EN) = X

WI(EN)

280

=

H(I,K)

-

P

CONTINUE

ONE + T

ROOT

FOUND

**********

= 0.0

EN = NA G O T O 60 ********** TWO ROOTS FOUND ********** P = (Y - X) / 2 . 0 Q = P * P + W ZZ = S Q R T ( A B S ( Q ) ) X = X + T I F (Q .LT. 0 . 0 ) G O T O 3 2 0 ********** REAL PAIR ********** ZZ = P + SIGN(ZZ,P) WR(NA) = X + ZZ W R (EN) = W R (NA) IF (ZZ . N E . 0 . 0 ) W R ( E N ) = X - W / ZZ Wi(NA) = 0.0 WI(EN) = 0.0 GO TO 330

336

7.1-142

C 320

********** WR(NA) = X WR(EN) = X WI(NA) WI(EN)

330 C C I000 i001

= =

EN = ENM2 G O T O 60 ********** IERR = RETURN END

COMPLEX + P + P

PAIR

**********

ZZ -zz

SET ERROR EIGENVALUE

-- NO CONVERGENCE TO AFTER 30 I T E R A T I O N S

EN

337

AN **********

7. 1-143

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F287-2

PACKAGE

(EISPACK)

HQR2

A F o r t r a n IV S u b r o u t i n e to D e t e r m i n e the E i g e n v a l u e s E i g e n v e c t o r s of a R e a l U p p e r H e s s e n b e r g M a t r i x .

May, July,

and

1972 1975

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e HQR2 c o m p u t e s the e i g e n v a l u e s and e i g e n v e c t o r s of a r e a l u p p e r H e s s e n b e r g m a t r i x u s i n g the QR methods The e i g e n v e c t o r s of a r e a l g e n e r a l m a t r i x can also be c o m p u t e d if E L M H E S (F273) and E L T R A N (F220) or ORTHES (F275) and O R T R A N (F221) h a v e b e e n u s e d to r e d u c e this g e n e r a l m a t r i x to H e s s e n b e r g f o r m and to a c c u m u l a t e the transformations,

2. USAGE. A,

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

HQR2(NM,N,LOW, IGH,H,WR,WI,Z,IERR)

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

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

LOW, IGH

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

are i n t e g e r i n p u t v a r i a b l e s i n d i c a t i n g the b o u n d a r y i n d i c e s for the b a l a n c e d m a t r i x . See s e c t i o n 3 of F269 for the d e t a i l s . If the m a t r i x is not b a l a n c e d , set LOW to 1 and IGH to N.

338

7.1-144

H

is a w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t N. On input, it c o n t a i n s the u p p e r H e s s e n b e r g m a t r i x . Note: HQR2 d e s t r o y s this u p p e r H e s s e n b e r g m a t r i x .

WR,WI

are w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e s of d i m e n s i o n at l e a s t N c o n t a i n i n g the r e a l and i m a g i n a r y parts, r e s p e c t i v e l y , of the e i g e n v a l u e s of the Hessenberg matrix. The e i g e n v a l u e s are u n o r d e r e d e x c e p t that c o m p l e x c o n j u g a t e pairs of e i g e n v a l u e s a p p e a r c o n s e c u t i v e l y w i t h the e i g e n v a l u e h a v i n g the p o s i t i v e i m a g i n a r y part first. is a w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l v a r i a b l e w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at least N. If the e i g e n v e c t o r s of the u p p e r H e s s e n b e r g m a t r i x are d e s i r e d , then on input, Z c o n t a i n s the i d e n t i t y m a t r i x of o r d e r N, and on o u t p u t , c o n t a i n s the real and i m a g i n a r y p a r t s of the e i g e n v e c t o r s of this H e s s e n b e r g m a t r i x . If the e i g e n v e c t o r s of a r e a l g e n e r a l m a t r i x a r e d e s i r e d , t h e n on input, Z c o n t a i n s the t r a n s f o r m a t i o n m a t r i x p r o d u c e d in ELTRAN or ORTRAN w h i c h r e d u c e d the g e n e r a l m a t r i x to H e s s e n b e r g form, and on output, c o n t a i n s the r e a l and i m a g i n a r y p a r t s of the e i g e n v e c t o r s of this r e a l g e n e r a l m a t r i x . If the J-th e i g e n v a l u e is real, the J-th c o l u m n of Z c o n t a i n s its e i g e n v e c t o r . If the J-th ~eigenvalue is c o m p l e x w i t h p o s i t i v e i m a g i n a r y part, the J-th and (J+l)-th c o l u m n s of Z c o n t a i n the r e a l and i m a g i n a r y p a r t s of its e i g e n v e c t o r . The c o n j u g a t e of this v e c t o r is the e i g e n v e c t o r for the c o n j u g a t e e i g e n v a l u e . The e i g e n v e c t o r s are not n o r m a l i z e d .

IERR

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

339

to is

7.1-145

B.

Error

Conditions

and

Returns.

If m o r e t h a n 30 i t e r a t i o n s are r e q u i r e d to d e t e r m i n e an e i g e n v a l u e , this s u b r o u t i n e t e r m i n a t e s w i t h IERR set to the i n d e x of the e i g e n v a l u e for w h i c h the f a i l u r e occurs. T h e e i g e n v a l u e s in the WR and WI arrays s h o u l d be c o r r e c t for i n d i c e s IERR+I,IERR+2,...,N, but no e i g e n v e c t o r s are c o m p u t e d . If all the e i g e n v a l u e s are d e t e r m i n e d iterations, IERR is set to zero.

C.

Applicability

and

within

30

Restrictions.

To d e t e r m i n e the e i g e n v a l u e s and e i g e n v e c t o r s of a real general matrix, HQR2 s h o u l d be p r e c e d e d by ELMHES (F273) or O R T H E S (F275) to p r o v i d e a s u i t a b l e u p p e r H e s s e n b e r g m a t r i x for HQR2 and by ELTRAN or ORTRAN to a c c u m u l a t e the t r a n s f o r m a t i o n s . It is r e c o m m e n d e d in g e n e r a l that BALANC used before ELMHES or ORTHES in w h i c h (F270) m u s t be used a f t e r HQR2.

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

OF M E T H O D

AND

(F269) be case BALBAK

ALGORITHM.

The e i g e n v a l u e s are d e t e r m i n e d by the QR method. The e s s e n c e of this m e t h o d is a p r o c e s s w h e r e b y a s e q u e n c e of u p p e r H e s s e n b e r g m a t r i c e s , u n i t a r i l y s i m i l a r to the o r i g i n a l H e s s e n b e r g m a t r i x , is f o r m e d w h i c h c o n v e r g e s to a q u a s i t r i a n g u l a r m a t r i x , that is, an u p p e r H e s s e n b e r g m a t r i x w h o s e e i g e n v a l u e s are the e i g e n v a l u e s of Ixl or 2x2 principal submatrices. T h e r a t e of c o n v e r g e n c e of this s e q u e n c e is i m p r o v e d by s h i f t i n g the o r i g i n at e a c h i t e r a t i o n . The a r i t h m e t i c t h r o u g h o u t the p r o c e s s is k e p t r e a l by c o m b i n i n g two i t e r a t i o n s into one, u s i n g two r e a l o r i g i n s h i f t s or a p a i r of c o m p l e x c o n j u g a t e o r i g i n shifts. Before each i t e r a t i o n , the last H e s s e n b e r g f o r m is c h e c k e d for a p o s s i b l e s p l i t t i n g into s u b m a t r i c e s . If a s p l i t t i n g o c c u r s , only the l o w e r s u b m a t r i x p a r t i c i p a t e s in the n e x t i t e r a t i o n . The similarity transformations used in e a c h i t e r a t i o n are a c c u m u l a t e d in the Z array. The o r i g i n s h i f t s at e a c h i t e r a t i o n are the e i g e n v a l u e s of the l o w e s t 2x2 principal minor. Whenever a lowest ixl or 2x2 p r i n c i p a l s u b m a t r i x f i n a l l y s p l i t s f r o m the r e s t of the m a t r i x , the e i g e n v a l u e s of this s u b m a t r i x are t a k e n to be e i g e n v a l u e s of the o r i g i n a l m a t r i x and the a l g o r i t h m p r o c e e d s w i t h the r e m a i n i n g s u b m a t r i x . T h i s p r o c e s s is c o n t i n u e d u n t i l the m a t r i x has s p l i t c o m p l e t e l y into s u b m a t r i c e s of

340

7.1-146

order i or 2. The t o l e r a n c e s in the s p l i t t i n g tests are proportional to the r e l a t i v e m a c h i n e p r e c i s i o n . The e i g e n v e c t o r s of this q u a s i - t r i a n g u l a r m a t r i x are d e t e r m i n e d by a b a c k s u b s t i t u t i o n p r o c e s s and then t r a n s f o r m e d to the e i g e n v e c t o r s of the o r i g i n a l matrix, using the i n f o r m a t i o n in Z. Some of the e i g e n v a l u e s may have b e e n i s o l a t e d on the d i a g o n a l by the s u b r o u t i n e B A L A N C (F269). This i n f o r m a t i o n is t r a n s m i t t e d to HQR2 t h r o u g h the p a r a m e t e r s LOW and IGH. As a result, HQR2 i m m e d i a t e l y e x t r a c t s the e i g e n v a l u e s in rows i to LOW-I and IGH+I to N, and so a p p l i e s the QR p r o c e d u r e to the s u b m a t r i x s i t u a t e d in rows and c o l u m n s LOW through IGH. This s u b r o u t i n e is a t r a n s l a t i o n of the A l g o l p r o c e d u r e w r i t t e n and d i s c u s s e d in d e t a i l by P e t e r s and W i l k i n s o n

HQR2 (i).

4. R E F E R E N C E S .

1)

5.

Peters, G. and W i l k i n s o n , J.H., E i g e n v e c t o r s of R e a l C o m p l e x M a t r i c e s by LR and QR T r i a n g u l a r i z a t i o n s , Num. Math. 1 6 , 1 8 1 - 2 0 4 (1970). ( R e p r i n t e d in H a n d b o o k A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , J. H. W i l k i n s o n - C. R e i n s c h , C o n t r i b u t i o n II/15, 372-395, S p r i n g e r - V e r l a g , 1971.)

and for

CHECKOUT. A.

Test

Cases.

See the s e c t i o n d i s c u s s i n g real g e n e r a l m a t r i c e s .

testing

of

the

codes

for

B. A c c u r a c y . The s u b r o u t i n e HQR2 is n u m e r i c a l l y s t a b l e (I); that is, each c o m p u t e d e i g e n v a l u e and its c o r r e s p o n d i n g e i g e n v e c t o r are exact for a m a t r i x close to the o r i g i n a l u p p e r H e s s e n b e r g matrix.

341

7.1-147

SUBROUTINE

HQR2(NM~N,LOW,IGH,H,WR,WI,Z,IERR)

INTEGER

X

I,J,K,L,M,N,EN,II,JJ,LL,MM,NA,NM,NN, 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

=

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

?

IERR = 0 NORM = 0.0 K = 1 ********** DO

40

50

60

70

80

50

I =

STORE ROOTS AND COMPUTE !, N

ISOLATED BY MATRIX NORM

BALANC **********

D O 40 J = K, N NORM = NORM + ABS(H(I,J)) K = I IF (I .GE. L O W WR(1) = H(I,I) WI(1) = 0.0 CONTINUE

.AND.

I

.LE.

IGH)

GO

TO

50

EN = IGH T=0.0 ********** SEARCH FOR NEXT E!GENVALUES ********** IF ( E N .LT. L O W ) G O T O 3 4 0 ITS = 0 N A = EN 1 E N M 2 = NA 1 ********** LOOK FOR SINGLE SMALL SUB-DIAGONAL ELEMENT FOR L=EN STEP -i UNTIL LOW DO -- ********** D O 80 L L = L O W , E N L = EN + LOW - LL I F (L .EQ. L O W ) G O T O I 0 0 S = ABS(H(L-I,L-I)) + ABS(H(L,L)) I F (S .EQ. 0 . 0 ) S = N O R M IF ( A B S ( H ( L , L - I ) ) .LE. MACHEP * S) G O T O I 0 0 CONTINUE

342

7.1-148

i00

********** FORM SHIFT ********** X = H(EN,EN) IF (L .EQ. E N ) G O T O 2 7 0 Y = H(NA,NA) W = H(EN,NA) * H(NA,EN) IF (L .EQ. N A ) G O T O 2 8 0 I F ( I T S .EQ. 30) G O T O I 0 0 0 IF ( I T S .NE. i0 . A N D . I T S .NE. 20) G O T O 1 3 0 ********** FORM EXCEPTIONAL SHIFT ********** T = T + X

120

DO 120 H(l,l)

130

S = X= Y = W = ITS

I = LOW, = H(I,I)

EN - X

ABS(H(EN,NA)) + ABS(H(NA,ENM2)) 0.75 * S X -0.4375 * S * S = ITS + i

• *********

LOOK FOR TWO CONSECUTIVE SMALL SUB-DIAGONAL ELEMENTS. FOR M=EN-2 S T E P -i U N T I L L D O - - * * * * * * * * * * D O 1 4 0 M M = L, E N M 2 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) G O T O 1 5 0 IF ( A B S ( H ( M , M - I ) ) * (ABS(Q) + ABS(R)) .LE. M A C H E P * 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

160 I = MP2, EN H(I,I-2) = 0.0 IF (I .EQ. M P 2 ) H(I,I-3) = 0.0 CONTINUE

GO

TO

160

********** DO

DOUBLE QR STEP INVOLVING ROWS COLUMNS M TO EN ********** 2 6 0 K = M, N A NOTLAS = K .NE. N A IF (K .EQ. M) G O T O 1 7 0 P = H(K,K-I) Q = H(K+I,K-I) R = 0.0

343

L TO

EN

AND

7. 1 - 1 4 9

IF (NOTLAS) R = H(K+2,K-I) X = ABS(P) + ABS(Q) + ABS(R) IF (X .EQ. 0 . 0 ) G O T O 2 6 0 P = P / X Q = Q / x R = R / X S = SIGN(SQRT(P*P+Q*Q+R*R),P) IF (K .EQ. M ) G O T O 1 8 0 H(K,K-I) = -S * X GO TO 190 I F (L .NE. M) H ( K , K - I ) = -H(K,K-I) P = P + S

170

180 190

x=p/s Y

=

Q

/ S

ZZ=R/S

200 210

e = Q / P R = R / e • ********* ROW MODIFICATION ********** D O 2 1 0 J = K, N P = H(K,J) + Q * H(K+I,J) IF ( ° N O T . N O T L A S ) GO TO 200 P = P + R * H(K+2,J) H(K+2,J) = H(K+2,J) - P * ZZ H(K+I,J) = H(K+I,J) - P * Y H(K,J) = H(K,J) - P * X CONTINUE

250

J = MiN0(EN,K+3) ********** COLUMN MODIFICATION ********** D O 2 3 0 I = i, J P = X * H(I,K) + Y * H(I,K+I) IF ( . N O T . N O T L A S ) GO TO 220 P = P + ZZ * H(I,K+2) H(l,K+2) = H(I,K+2) - P * R H(I,K+I) = H(I,K+I) - P * Q H(!~K) = N(l,K) - P CONTINUE ********** ACCUMULATE TRANSFORMATIONS ********** DO 250 I = LOW, IGN e = X * Z(I,K) + Y * Z(I,K+I) IF ( . N O T . N O T L A S ) GO TO 240 P = P + ZZ * Z(I,K+2) Z(I,K+2) = Z(I,K+2) - P * R Z(I,K+I) = Z(l,K+l) - P * Q Z(I,K) = Z(I,K) - e CONTINUE

260

CONTINUE

220 230

240

GO

TO

70

344

7. i- 1 5 0

C 270

C 280

C

********** ONE ROOT FOUND ********** H(EN,EN) = X + T WR(EN) = H(EN,EN) WI(EN) = 0.0 EN = NA G O T O 60 ********** TWO ROOTS FOUND ********** P = (Y - X) / 2 . 0 Q = P * P + W ZZ = S Q R T ( A B S ( Q ) ) H(EN,EN) = X + T X = H(EN,EN) H(NA,NA) = Y + T IF (Q .LT. 0 . 0 ) G O T O 3 2 0 ********** REAL PAIR ********** ZZ = P + SIGN(ZZ,P) WR(NA) = X + ZZ WR(EN) = WR(NA) IF (ZZ .NE. 0 . 0 ) W R ( E N ) = 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

C

290 C

300 C

310

R = SQRT (P*P+Q*Q) P = P / R Q = Q / R ********** 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 CONTINUE ********** COLUMN MODIFICATION ********** D O 3 0 0 I = i, E N ZZ = H(I,NA) H(I,NA) = Q * zz + P * H(I,EN) H(I,EN) = Q * H(I,EN) - P * ZZ CONTINUE ********** ACCUMULATE TRANSFORMATIONS ********** DO 310 I = LOW, IGH ZZ = Z ( I , N A ) Z(I,NA) = Q * ZZ + P * Z(I,EN) Z(I,EN) = Q * Z(I,EN) - P * ZZ CONTINUE GO

TO

330

345

7. 1 - 1 5 1

C 320

330 C C 340 C

C 600

C

610 620

630

C 640

650 700 C

********** COMPLEX PAIR ***~****** WR(NA) = X + P WR(EN) = X + P W I ( ~ A ) = zz W I ( E N ) = -ZZ EN = ENM2 GO TO 60 ********** ALL ROOTS FOUND. BACKSUBSTITUTE TO FIND VECTORS OF UPPER TRIANGULAR FORM ********** IF ( N O R M oEQ. 0 . 0 ) G O T O i 0 0 1 ********** F O R E N = N S T E P -i U N T I L 1 D O -- * * * * * * * * * * D O 8 0 0 N N = i, N EN = N + I - NN P = WR(EN) Q = WI(EN) NA = EN - 1 IF (q) 7 1 0 , 6 0 0 , 8 0 0 ********** REAL VECTOR ********** M = EN H(EN,EN) = 1.0 IF ( N A .EQ. 0) G O T O 8 0 0 ********** FOR I=EN-I STEP -I UNTIL i DO -- ********** D O 7 0 0 II = i, N A I = EN II W = H(I,I) - e R = H(l,EN) IF (M .GT. N A ) G O T O 6 2 0 D O 6 1 0 J = M, N A R = R + H(I,J) * II(J,EN) IF ( W I ( I ) .GE. 0 . 0 ) G O T O 6 3 0 ZZ = W S = R GO TO 700 M = I IF ( W I ( 1 ) .RE. 0 . 0 ) G O T O 6 4 0 T = W I F (W .EQ. 0 . 0 ) r = M A C H E P * NORM H(I,EN) = -R / T GO TO 700 ********** SOLVE REAL EQUATIONS ********** X = H(I,I+I) Y = H(I+I,I) Q = (WR(1) -P) * (WR(1) -P)+ WI(1) T = (X * S - Z Z * R) / Q H(I,EN) = T IF (ABS(X) .LE. A B S ( Z Z ) ) GO TO 650 H(I+I,EN) = ( - R - W * T) / X GO TO 700 H(I+I,EN) = (-S - Y * T) / ZZ CONTINUE ********** END REAL VECTOR ********** GO TO 800

346

* WI(1)

7.1-152

C 710 C C

720

730

C

********** M = NA *********~

COMPLEX

VECTOR

**********

LAST VECTOR COMPONENT CHOSEN IMAGINARY SO T H A T EIGENVECTOR MATRIX IS T R I A N G U L A R ********** IF ( A B S ( H ( E N , N A ) ) .LE. A B S ( H ( N A , E N ) ) ) G O T O 7 2 0 H(NA,NA) = Q / H(EN,NA) H(NA,EN) = -(H(EN,EN) - P) / H ( E N , N A ) G O TO 7 3 0 Z3 = C M P L X ( 0 . 0 , - H ( N A , EN)) / CMPLX(H(NA,NA)-P,Q) H(NA,NA) = REAL(Z3) H(NA,EN) = AIMAG(Z3) H(EN,NA) = 0.0 H(EN,EN) = 1.0 E N M 2 = NA - i IF ( E N M 2 .EQ. 0) GO T O 8 0 0 ********** FOR I=EN-2 S T E P -i U N T I L 1 D O -- * * * * * * * * * * D O 7 9 0 II = I, E N M 2 I = N A - II W = H(I,I) - e RA = 0.0 SA = H(I,EN) DO

760

760 J = M, N A RA = RA + H(I,J) SA = SA + H ( I , J ) CONTINUE

* H(J,NA) * H(J,EN)

IF ( W I ( I ) .GE. 0 . 0 ) G O T O 7 7 0 ZZ = W R = RA S = SA GO TO 790 770 M = I IF ( W I ( I ) .NE. 0.0) G O TO 780 Z3 = C M P L X ( - R A , - S A ) / CMPLX(W,Q) H(I,NA) = REAL(Z3) H(I,EN) = AIMAG(Z3) GO T O 7 9 0 ********** SOLVE COMPLEX EQUATIONS ********** 780 X = H(I,I+I) Y = H(I+I,I) V R = ( W R ( I ) - P) * ( W R ( I ) - P) + W I ( I ) * WI(I) - Q * q vI = ( W R ( I ) - P) * 2.0 * Q IF (VR .EQ. 0 . 0 . A N D . VI .EQ. 0 . 0 ) V R = M A C H E P * NORM X * (ABS(W) + ABS(Q) + ABS(X) + ABS(Y) + ABS(ZZ)) Z3 = C M P L X ( X * R - Z Z * R A + Q * S A , X * S - Z Z * S A - Q * R A ) / CMPLX(VR,Vl) H(I,NA) = REAL(Z3) H(I,EN) = AIMAG(Z3) IF ( A B S ( X ) .LE. A B S ( Z Z ) + 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

790 800

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) CONTINUE ********** END COMPLEX VECTOR ********** CONTINUE ********** END BACK SUBSTITUTION. VECTORS OF ISOLATED ROOTS ********** D O 8 4 0 1 = i, N IF (I oGE. L O W . A N D . I .LE. I G H ) G O T O 8 4 0 DO 820 Z(I,J)

820 840

CONTINUE **********

DO

MULTIPLY BY TRANSFORMATION MATRIX TO GIVE VECTORS OF ORIGINAL FULL MATRIX. F O R J = N S T E P -I U N T I L LOW DO -- ********** 880 JJ = LOW~ N J = N + LOW - JJ M = MIN0(J,IGH) DO

880 1 = LOW, ZZ = 0.0 DO ZZ

860

880

J = It N = H(I,J)

860 K = LOW, M = ZZ + Z(I,K) * H(K,J)

Z(l,J) CONTINUE GO TO I001 **********

i000 i001

IERR = RETURN END

IGH

=

ZZ

SET ERROR EIGENVALUE

-- NO CONVERGENCE TO AFTER 30 ITERATIONS

EN

348

AN **********

7. 1-154

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F285-2

PACKAGE

(EISPACK)

HTRIBK

A F o r t r a n IV S u b r o u t i n e to B a c k T r a n s f o r m the E i g e n v e c t o r s of that S y m m e t r i c T r i d i a g o n a l M a t r i x D e t e r m i n e d by HTRIDI.

May, July,

1972 1975

I. P U R P O S E . The F o r t r a n IV s u b r o u t i n e HTRIBK forms the e i g e n v e c t o r s of a c o m p l e x H e r m i t i a n m a t r i x f r o m the e i g e n v e c t o r s of that r e a l s y m m e t r i c t r i d i a g o n a l m a t r i x d e t e r m i n e d by H T R I D I (F284).

2. U S A G E . A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

HTRIBK(NM,N,AR,AI,TAU,M,ZR,ZI)

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

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to the row d i m e n s i o n of the t w o - d i m e n s i o n a l arrays AR, AI, ZR, and ZI as s p e c i f i e d in the D I M E N S I O N s t a t e m e n t s for AR, AI, ZR, and ZI in the c a l l i n g p r o g r a m . is an i n t e g e r input v a r i a b l e the o r d e r of the m a t r i x . N g r e a t e r than NM.

AR,AI

set e q u a l to m u s t be not

are w o r k i n g p r e c i s i o n r e a l i n p u t twodimensional variables with row dimension NM and c o l u m n d i m e n s i o n at l e a s t N. The s t r i c t l o w e r t r i a n g l e of AR and the f u l l l o w e r t r i a n g l e of AI c o n t a i n some i n f o r m a t i o n a b o u t the u n i t a r y t r a n s f o r m a t i o n s u s e d in the r e d u c t i o n to the t r i d i a g o n a l form. The r e m a i n i n g u p p e r p a r t s of the m a t r i c e s are a r b i t r a r y . See s e c t i o n 3 of F284 for the details.

349

7.1-155

B.

Error

TAU

is a w o r k i n g p r e c i s i o n r e a l i n p u t t w o dimensional variable with row dimension 2 and c o l u m n d i m e n s i o n at l e a s t N. TAU c o n t a i n s the r e m a i n i n g i n f o r m a t i o n a b o u t the unitary transformations. See s e c t i o n 3 of F284 for the d e t a i l s .

M

is an i n t e g e r i n p u t v a r i a b l e set e q u a l the n u m b e r of c o l u m n s of Z = (ZR,ZI) back transformed.

ZR, ZI

are working precision real two-dimensional variables with row dimension NM and c o l u m n dimension at l e a s t M. On i n p u t , the f i r s t M c o l u m n s of ZR c o n t a i n the r e a l eigenvectors to be b a c k t r a n s f o r m e d a n d the c o n t e n t s of ZI are immaterial. On o u t p u t , these M c o l u m n s of ZR and ZI contain the r e a l a n d i m a g i n a r y p a r t s , r e s p e c t i v e l y , of the t r a n s f o r m e d eigenvectors. The transformed eigenvectors are orthonormal if the i n p u t e i g e n v e c t o r s are orthonormal.

Conditions

and

to to be

Returns°

None°

Co

Applicability

and

Restrictions.

This subroutine s h o u l d be u s e d subroutine HTRIDI (F284).

3.

DISCUSSION

OF M E T H O D

AND

in

conjunction

with

the

ALGORITHM.

(say) h a s b e e n r e d u c e d S u p p o s e that the H e r m i t i a n m a t r i x C F by the s i m i l a r i t y to the t r i d i a g o n a l symmetric matrix transformation

F = V Q cqv where Q is a p r o d u c t of the u n i t a r y H e r m i t i a n m a t r i c e s e n c o d e d in the l o w e r t r i a n g l e s of AR and A!, a n d V is a u n i t a r y d i a g o n a l m a t r i x e n c o d e d in TAU. T h e n , g i v e n an array Z of c o l u m n v e c t o r s , HTRIBK c o m p u t e s the m a t r i x product QVZ. If the e i g e n v e c t o r s of F a r e c o l u m n s of the array Z, t h e n HTRIBK f o r m s the e i g e n v e c t o r s of C in their place. Since QV is u n i t a r y , v e c t o r E u c l i d e a n n o r m s are p r e s e r v e d . N o t e t h a t the l a s t c o m p o n e n t of e a c h transformed eigenvector is r e a l .

350

7.1-156

This subroutine is a complex analogue of the subroutine TRBAKI (F279) which is a t r a n s l a t i o n of the Algol procedure TRBAKI w r i t t e n and discussed in detail by Martin, Reinsch, and W i l k i n s o n (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., H o u s e h o l d e r ' s T r i d i a g o n a l i z a t i o n of a Symmetric Matrix, Num. Math. 11,181-195 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. W i l k i n s o n - C. Reinsch, C o n t r i b u t i o n 1I/2, 212-226, Springer-Verlag, 1971.)

2)

Mueller, D.J., Householder's and E i g e n s y s t e m s of H e r m i t i a n Num. Math. 8,72-92 (1966).

Method for Complex Matrices,

Matrices

5. CHECKOUT. A.

Test

Cases.

See the section discussing testing complex H e r m i t i a n matrices.

of the codes

for

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 H e r m i t i a n matrices. In these paths, this subroutine is n u m e r i c a l l y stable (1,2). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a m a t r i x close to the original matrix and the computed eigenvectors are close (but not n e c e s s a r i l y equal) to the eigenvectors of that matrix.

351

7.1-157

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

DO

50

K

=

DO

50

0) GO TO 2 0 0 TRANSFORM THE EIGENVECTORS OF T H E R E A L S Y M M E T R I C TR!DIAGONAL MATRIX TO T H O S E OF T H E H E R M I T I A N TRIDIAGONAL MATRIX. ********** I, N

50 J = Z!(K,J) ZR(K,J) CONTINUE

i~ M = -ZR(K,J) = ZR(K,J)

* TAU(e,K) * TAU(I,K)

C IF (N .EQ. i) G O T O 2 0 0 ********** RECOVER AND APPLY DO 1 4 0 ! = 2, N L = I - I H = AI(I,I) IF (H .EQ. 0 . 0 ) G O TO 140

C

THE

HOUSEHOLDER

MATRICES

**********

C DO

Ii0

1 3 0 J = i, S = 0.0 Sl = 0 . 0

M

DO

I, L AR(I,K) * ZR(K,J) - AI(I,K) * ZI(K,J) + AR(I,K) * ZI(K,J) + AI(I,K) * ZR(K,J)

Ii0 K = S = S + SI = SI CONTINUE • ********* DOUBLE S = (S / H) SI = (SI / DO

120 K = ZR(K,J) ZI(K,J) CONTINUE

120 130

DIVISIONS / H H) / H i, L = ZR(K,J) = ZI(K,J)

AVOID

-

S * AR(I,K) SI * A R ( I , K )

CONTINUE

140

CONTINUE

200

RETURN END

POSSIBLE

352

UNDERFLOW

+

**********

SI * A I ( I , K ) S * AI(I,K)

7.1-158

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F243

PACKAGE

(EISPACK)

HTRIB3

A F o r t r a n IV S u b r o u t i n e to B a c k T r a n s f o r m the E i g e n v e c t o r s of that S y m m e t r i c T r i d i a g o n a l M a t r i x D e t e r m i n e d by HTRID3.

July,

1975

1. P U R P O S E . The F o r t r a n IV s u b r o u t i n e HTRIB3 f o r m s the e i g e n v e c t o r s of a c o m p l e x H e r m i t i a n m a t r i x f r o m the e i g e n v e c t o r s of that r e a l s y m m e t r i c t r i d i a g o n a l m a t r i x d e t e r m i n e d by H T R I D 3 (F242).

2.

USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

HTRIB3(NM,N,A,TAU,M,ZR,ZI)

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

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

N

is an i n t e g e r i n p u t v a r i a b l e the o r d e r of the m a t r i x . N greater than NM.

A

is a w o r k i n g p r e c i s i o n real i n p u t twodimensional variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t N containing some i n f o r m a t i o n a b o u t the u n i t a r y t r a n s f o r m a t i o n s u s e d in the r e d u c t i o n to the t r i d i a g o n a l form. See s e c t i o n 3 of F242 for the details.

353

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

7.1-159

B.

Error

TAU

is a w o r k i n g p r e c i s i o n r e a l i n p u t twodimensional variable with row dimension 2 and c o l u m n d i m e n s i o n at l e a s t N. TAU c o n t a i n s the r e m a i n i n g i n f o r m a t i o n a b o u t the unitary transformations. See s e c t i o n 3 of F242 for the d e t a i l s .

M

is an i n t e g e r i n p u t v a r i a b l e set e q u a l the n u m b e r of c o l u m n s of Z = (ZR,ZI) back transformed.

ZR, ZI

are w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l variables with row dimension NM and c o l u m n d i m e n s i o n at l e a s t M. On input, the f i r s t M c o l u m n s of ZR c o n t a i n the real e i g e n v e c t o r s to be b a c k t r a n s f o r m e d and the c o n t e n t s of ZI are i m m a t e r i a l . On o u t p u t , these M c o l u m n s of ZR and ZI contain the r e a l and i m a g i n a r y p a r t s , r e s p e c t i v e l y , of the t r a n s f o r m e d e i g e n v e c t o r s . The t r a n s f o r m e d e i g e n v e c t o r s a r e o r t h o n o r m a l if the i n p u t e i g e n v e c t o r s are o r t h o n o r m a l .

Conditions

and

to to be

Returns,

None,

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

and

Restrictions.

This s u b r o u t i n e s h o u l d be u s e d subroutine H T R I D 3 (F242).

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

OF M E T H O D

AND

in c o n j u n c t i o n

with

the

ALGORITHM.

(say) has b e e n r e d u c e d S u p p o s e that the H e r m i t i a n m a t r i x C F by the s i m i l a r i t y to the t r i d i a g o n a l s y m m e t r i c m a t r i x transformation

F = V Q CQV where Q is a p r o d u c t of the u n i t a r y H e r m i t i a n m a t r i c e s e n c o d e d in A, and V is a u n i t a r y d i a g o n a l m a t r i x e n c o d e d in TAU. Then, g i v e n an a r r a y Z of c o l u m n v e c t o r s , HTRIB3 c o m p u t e s the m a t r i x p r o d u c t QVZ. If the e i g e n v e c t o r s of F are c o l u m n s of the a r r a y Z, t h e n HTRIB3 f o r m s the e i g e n v e c t o r s of C in t h e i r p l a c e . Since QV is u n i t a r y , v e c t o r E u c l i d e a n n o r m s are p r e s e r v e d . N o t e that the last c o m p o n e n t of e a c h t r a n s f o r m e d e i g e n v e c t o r 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 W i l k i n s o n (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., H o u s e h o l d e r ' s T r i d i a g o n a l i z a t i o n 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, C o n t r i b u t i o n 11/2, 212-226, Springer-Verlag, 1971.)

2)

Mueller, D.J., H o u s e h o l d e r ' s Method for Complex Matrices and Eigensystems of Hermitian Matrices, Num. Math. 8,72-92 (1966).

5. CHECKOUT. A. Test Cases. See the section discussing testing of the codes for complex Hermitian matrices.

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 H e r m i t i a n matrices. In these paths, this subroutine is n u m e r i c a l l y 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 n e c e s s a r i l y equal) to the eigenvectors of that matrix.

355

7.1-161

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

C C C

DO

50

K

=

0) G O T O 2 0 0 TRANSFORM THE EIGENVECTORS OF T H E R E A L S Y M M E T R I C TRiDIAGONAL MATRIX TO THOSE OF THE HERMITIAN TRIDIAGONAL MATRIX. ********** I, N

C DO

50

50 J = ZI(K,J) ZR(K,J) CONTINUE

I, M = -ZR(K,J) = ZR(K,J)

* TAU(2,K) * TAU(I,K)

IF (N .EQ. 1) G O T O 2 0 0 ********** RECOVER AND APPLY DO 140 I = 2, N L = I - i H = A ( I , I) IF (H .EQ. 0 . 0 ) G O T O 140 DO

130 J = i, S=0.0 Sl = 0 . 0

M

DO

I, L A(I,K) * + A(I,K)

THE

HOUSEHOLDER

MATRICES

**********

C

Ii0 C

Ii0 K = S = S + SI = Si CONTINUE • ********* DOUBLE S = (S / H) SI = (SI / DO

120 130

ZR(K,J) - A(K,I) * * ZI(K,J) + A(K,I)

DIVISIONS / H H) / H

AVOID

!20 K = ZR(K,J)

i, L = ZR(K,J)

-

S * A(I,K)

ZI(K,J)

=

-

SI

ZI(K,J)

CONTINUE CONTINUE

140

CONTINUE

200

RETURN END

POSSIBLE

356

*

A(I,K)

ZI(K,J) * ZR(K,J)

UNDEKFLOW

-

SI +

S

* A(K,I) *

A(K,I)

**********

7.1-162

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F284-2

PACKAGE

(EISPACK)

HTRIDI

A F o r t r a n IV S u b r o u t i n e to R e d u c e a C o m p l e x H e r m i t i a n M a t r i x to a R e a l S y m m e t r i c T r i d i a g o n a l M a t r i x U s i n g Unitary Transformations.

May, July,

1972 1975

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e NTRIDI reduces a complex H e r m i t i a n m a t r i x to a real s y m m e t r i c t r i d i a g o n a l m a t r i x u s i n g unitary similarity transformations. This r e d u c e d f o r m is u s e d by o t h e r s u b r o u t i n e s to f i n d the e i g e n v a l u e s a n d / o r e i g e n v e c t o r s of the o r i g i n a l m a t r i x . See s e c t i o n 2C for the specific routines.

2. USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

HTRIDI(NM,N,AR,AI,D,E,E2,TAU)

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

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to the row d i m e n s i o n of the t w o - d i m e n s i o n a l arrays AR and AI as s p e c i f i e d in the D I M E N S I O N s t a t e m e n t s for AR and AI in the c a l l i n g p r o g r a m . is an i n t e g e r input v a r i a b l e set e q u a l the order of the m a t r i x A = (AR,AI). m u s t be n o t g r e a t e r than NM.

357

to N

7. 1-163

AR,AI

are w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l variables with row dimension NM and c o l u m n d i m e n s i o n at l e a s t N. On input, AR and AI c o n t a i n the r e a l and i m a g i n a r y p a r t s , r e s p e c t i v e l y , of the H e r m i t i a n m a t r i x of order N to be r e d u c e d to t r i d i a g o n a l form. Only the f u l l lower t r i a n g l e s of the m a t r i c e s n e e d be s u p p l i e d . On o u t p u t , the s t r i c t l o w e r t r i a n g l e of AR and the full l o w e r t r i a n g l e of AI c o n t a i n some i n f o r m a t i o n a b o u t the u n i t a r y t r a n s f o r m a t i o n s u s e d in the r e d u c t i o n . The f u l l u p p e r t r i a n g l e of AR and the s t r i c t u p p e r t r i a n g l e of AI are u n a l t e r e d . See s e c t i o n 3 for the d e t a i l s . is a w o r k i n g p r e c i s i o n real o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g the d i a g o n a l e l e m e n t s of the real symmetric tridiagonal matrix. is a w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N c o n t a i n i n g , in its last N-I positions, the s u b d i a g o n a l e l e m e n t s of the t r i d i a g o n a l matrix. The e l e m e n t E(1) is set to zero.

B.

Error

E2

is a w o r k i n g p r e c i s i o n r e a l o u t p u t o n e d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N c o n t a i n i n g , in its last N-I positions, the s q u a r e s of the s u b d i a g o n a l e l e m e n t s of the t r i d i a g o n a l m a t r i x . The element E2(1) is set to zero. E2 n e e d n o t be d i s t i n c t from E (non-standard usage acceptable with at l e a s t t h o s e c o m p i l e r s i n c l u d e d in the c e r t i f i c a t i o n s t a t e m e n t ) , in w h i c h case no s q u a r e s are r e t u r n e d .

TAU

is a w o r k i n g p r e c i s i o n r e a l o u t p u t twodimensional variable with row dimension 2 and c o l u m n d i m e n s i o n at least N. TAU c o n t a i n s the r e m a i n i n g i n f o r m a t i o n a b o u t the unitary transformations. See s e c t i o n 3 for the d e t a i l s .

Conditions

and

Returns.

None.

358

7.1-164

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

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

If all the e i g e n v a l u e s of the o r i g i n a l m a t r i x are desired, this s u b r o u t i n e s h o u l d be f o l l o w e d by TQLI (F289), IMTQLI (F291), or T Q L R A T (F235). If all the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x are desired, this s u b r o u t i n e s h o u l d be f o l l o w e d by TQL2 (F290) or IMTQL2 (F292), and then by HTRIBK (F285). If some of the e i g e n v a l u e s of the o r i g i n a l m a t r i x are desired, this s u b r o u t i n e s h o u l d be f o l l o w e d by BISECT (F294) or T R I D I B (F237). If some of the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e should be f o l l o w e d by T S T U R M (F293), or by BISECT (F294) and T I N V I T (F223), or by T R I D I B (F237) and TINVIT, or by I M T Q L V (F234) and TINVIT, and then by H T R I B K (F285).

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

OF M E T H O D

AND A L G O R I T H M .

The t r i d i a g o n a l r e d u c t i o n is p e r f o r m e d in the f o l l o w i n g way. Starting with J=N, the e l e m e n t s in the J-th row to the left of the d i a g o n a l of (AR,AI) are first scaled, to avoid p o s s i b l e u n d e r f l o w in the t r a n s f o r m a t i o n that m i g h t r e s u l t in s e v e r e d e p a r t u r e from o r t h o g o n a l i t y . The sum of s q u a r e d magnitudes SIGMA of these scaled e l e m e n t s is next formed. Then, a v e c t o r U and a scalar

=

define

u u/2

an o p e r a t o r

P = I - UU

/H

w h i c h is u n i t a r y and H e r m i t i a n and for w h i c h the s i m i l a r i t y transformation PAP e l i m i n a t e s the e l e m e n t s in the J-th row of A to the left of the s u b d i a g o n a l and the s y m m e t r i c a l e l e m e n t s in the J-th column. The n o n - z e r o c o m p o n e n t s of U are the e l e m e n t s of the J-th row to the left of the d i a g o n a l w i t h the last of them a u g m e n t e d by the s q u a r e root of SIGMA times the s u b d i a g o n a l e l e m e n t d i v i d e d by its m a g n i t u d e . By s t o r i n g the t r a n s f o r m e d s u b d i a g o n a l e l e m e n t e l s e w h e r e and not o v e r w r i t i n g the c o l u m n e l e m e n t s e l i m i n a t e d in the t r a n s f o r m a t i o n , full i n f o r m a t i o n about P is saved for later use in HTRIBK. The t r a n s f o r m e d s u b d i a g o n a l e l e m e n t is then r e n d e r e d real by a d i a g o n a l unitary transformation.

359

7.1-165

The a b o v e steps are r e p e a t e d on f u r t h e r rows of the transformed A in r e v e r s e o r d e r u n t i l A is r e d u c e d s y m m e t r i c t r i d i a g o n a l form; that is, r e p e a t e d for J = N-I,N-2,...,3.

to

The p r o d u c t of the d i a g o n a l u n i t a r y t r a n s f o r m a t i o n s is a c c u m u l a t e d into a u n i t a r y d i a g o n a l m a t r i x w h o s e d i a g o n a l e l e m e n t s are s a v e d in TAU for later use in HTRIBK. This s u b r o u t i n e is a c o m p l e x a n a l o g u e of the s u b r o u t i n e TREDI (F277) w h i c h is a t r a n s l a t i o n of the A l g o l p r o c e d u r e TREDI w r i t t e n and d i s c u s s e d in d e t a i l by M a r t i n , R e i n s c h , and W i l k i n s o n (i). A similar Algol procedure HOUSEHOLDER HERMITIAN is d i s c u s s e d in d e t a i l by M u e l l e r (2).

4.

5.

REFERENCES.

!)

M a r t i n , R.S., R e i n s c h , C., and W i l k i n s o n , J.H., Householder's Tridiagonalization of a S y m m e t r i c M a t r i x , Num. Math, 1 1 , 1 8 1 - 1 9 5 (1968). ( R e p r i n t e d in H a n d b o o k for A u t o m a t i c C o m p u t a t i o n , V o l u m e !I, L i n e a r A l g e b r a ~ J. H. W i l k i n s o n - C. R e i n s c h , C o n t r i b u t i o n 11/2, 212-226, Springer-Verlag, 1971.)

2)

M u e l l e r ~ D.J., Householder's and E i g e n s y s t e m s of H e r m i t i a n Num. Math. 8 , 7 2 - 9 2 (1966).

M e t h o d for Matrices,

Complex

Matrices

CHECKOUT. A.

Test

Cases.

See the complex

section discussing testing Hermitian matrices.

of

the

codes

for

B. A c c u r a c y ~ The a c c u r a c y of HTRIDI can b e s t be d e s c r i b e d in terms of its role in those paths of EISPACK w h i c h find e i g e n v a l u e s and e i g e n v e c t o r s of c o m p l e x H e r m i t i a n matrices. In these paths, this s u b r o u t i n e is numerically s t a b l e (1,2). This s t a b i l i t y c o n t r i b u t e s to the p r o p e r t y of these paths that the c o m p u t e d e i g e n v a l u e s are the e x a c t e i g e n v a l u e s of a m a t r i x close to the o r i g i n a l m a t r i x and the c o m p u t e d e i g e n v e c t o r s are close (but not n e c e s s a r i l y equal) to the e i g e n v e e t o r s 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) TAU(2,N)

I00 C

C 120

130

140

150

160

= =

1.0 0.0

DO I00 I = i, N D(1) = AR(I,!) ********** F O R I = N S T E P -I U N T I L I D O -- * * * * * * * * * * D O 3 0 0 II = i, N I = N + 1 - II L = I - i H= 0.0 SCALE = 0.0 IF (L .LT. i) G O T O 130 ********** SCALE ROW (ALGOL TOL THEN NOT NEEDED) *~******** D O 120 K = i, L SCALE = SCALE + ABS(AR(!,K)) + ABS(AI(I,K)) IF ( S C A L E .NE. TAU(I,L) = 1.0 TAU(2,L) = 0.0 E(1) = 0.0 E2 (I) = 0 . 0 GO TO 290

0.0)

GO

TO

140

DO

1 5 0 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) CONTINUE

+ AI(I,K)

* AI(I,K)

E2(1) = SCALE * SCALE * H G = S Q R T (H) E(1) = SCALE * G F = CABS(CMPLX(AR(I,L),AI(I,L))) • ********* FORM NEXT DIAGONAL ELEMENT OF M A T R I X T ********** IF (F .EQ. 0 ° 0 ) G O T O 160 TAU(I,L) = (AI(I,L) * TAU(2,1) - AR(I,L) * TAU(I,I)) / F SI = ( A R ( I , L ) * TAU(2,1) + A I ( 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) G O T O 2 7 0 GO T O 170 TAU(I,L) = -TAU(I,I) SI = T A U ( 2 , ! ) AR(I,L) = G

361

7.1-167

170

F

=

0°0

DO

2 4 0 J = I, L g = 0.0 GI = 0.0 ********** FORM ELEMENT OF D O 1 8 0 K = i, J G = G + AR(J,K) * GI = GI - AR(J,K) CONTINUE

180

JPI = IF (L

7 + I oLT. JPI)

GO

A*U

**********

AR(I,K) + * AI(I,K)

TO

A!(J,K) * AI(I,K) + AI(J,K) * AR(I,K)

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) CONTINUE • ********* FORM ELEMENT OF P ********** E(J) = G / H TAU(2,J) = GI / H F = F + E(J) * AR(I,J) - TAU(2,J) * AI(I,J) CONTINUE

200 220

240

HH = F / (H + H) ********** FORM REDUCED A ********** D O 2 6 0 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 DO

260 K = AR(J,K)

I, J = AR(J,K)

AI(J,K)

=

+ -

X AI(J,K)

X 260

CONTINUE

270

DO

280

290

300

280 K = AR(I,K) AI(I,K) CONTINUE

i, L = SCALE = SCALE

TAU(2,L) = -SI HH = D(I) D(1) = AR(I,I) AR(I,I) = HH AI(I,I) = SCALE CONTINUE

*

* *

F * E(K) - G * AR(I,K) FI * TAU(2,K) + GI * AI(I,K) F * TAU(2,K) - G * AI(I,K) FI * E(K) - GI * AR(I,K)

AR(I,K) AI(I,K)

SQRT(H)

362

7.1-168

C RETURN END

363

7. i-!69

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F242

PACKAGE

(EISPACK)

HTRID3

A F o r t r a n IV S u b r o u t i n e to R e d u c e a C o m p l e x H e r m i t i a n M a t r i x , S t o r e d as a S i n g l e S q u a r e Array, to a Real Symmetric Tridiagonal Matrix Using Unitary Transformations.

July,

1975

Io P U R P O S E ° The F o r t r a n IV s u b r o u t i n e HTRID3 reduces a complex H e r m i t i a n m a t r i x , s t o r e d as a s i n g l e s q u a r e array, to a r e a l symmetric tridiagonal matrix using unitary similarity transformations. T h i s r e d u c e d f o r m is u s e d by o t h e r s u b r o u t i n e s to f i n d the e i g e n v a l u e s a n d / o r e i g e n v e c t o r s of the o r i g i n a l m a t r i x . See s e c t i o n 2C for the s p e c i f i c routines.

2. USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

HTRID3(NM,N,A,D,E,E2,TAU)

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

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

set e q u a l to m u s t be not

is a w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l v a r i a b l e w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at l e a s t N. On input, A c o n t a i n s the lower t r i a n g l e of the H e r m i t i a n m a t r i x of o r d e r N to be r e d u c e d to t r i d i a g o n a l form. If the real p a r t of A

364

7. 1-170

is d e n o t e d by AR and the i m a g i n a r y part by AI, then the full lower t r i a n g l e of AR s h o u l d be s t o r e d in the full lower t r i a n g l e of A and the s t r i c t lower t r i a n g l e of AI s h o u l d be s t o r e d in the t r a n s p o s e d p o s i t i o n s of the strict upper t r i a n g l e of A. No s t o r a g e is r e q u i r e d for the zero d i a g o n a l e l e m e n t s of AI. For e x a m p l e w h e n N=4, A should contain (AR(I,I) (AR(2,1) (AR(3,1) (AR(4,1)

AI(2,1) AR(2,2) AN(3,2) AR(4,2)

AI(3,1) AI(3,2) AR(3,3) AN(4,3)

AI(4,1) AI(4,2) AI(4,3) AN(4,4)

) ) ) ).

(If the u p p e r t r i a n g l e of AI is s t o r e d instead, the e i g e n v a l u e s are not c h a n g e d but the e i g e n v e c t o r s are c o n j u g a t e d . ) On output, A c o n t a i n s some i n f o r m a t i o n about the u n i t a r y t r a n s f o r m a t i o n s u s e d in the reduction. See s e c t i o n 3 for the details. is a w o r k i n g p r e c i s i o n real o u t p u t o n e d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N c o n t a i n i n g the d i a g o n a l e l e m e n t s of the real s y m m e t r i c t r i d i a g o n a l matrix. is a w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N c o n t a i n i n g , in its last N-I positions, the s u b d i a g o n a l e l e m e n t s of the t r i d i a g o n a l matrix. The e l e m e n t E(1) is set to zero. E2

is a w o r k i n g p r e c i s i o n real o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N c o n t a i n i n g , in its last N-I positions, the s q u a r e s of the s u b d i a g o n a l e l e m e n t s of the t r i d i a g o n a l matrix. The e l e m e n t E2(1) is set to zero. E2 n e e d not be d i s t i n c t from E (non-standard usage acceptable with at least those c o m p i l e r s i n c l u d e d in the certification statement), in w h i c h case no s q u a r e s are r e t u r n e d .

TAU

is a w o r k i n g p r e c i s i o n r e a l o u t p u t twod i m e n s i o n a l v a r i a b l e w i t h row d i m e n s i o n 2 and column d i m e n s i o n at least N. TAU c o n t a i n s the r e m a i n i n g i n f o r m a t i o n a b o u t the unitary transformations. See s e c t i o n 3 for the details.

365

7.1-171

B.

Error

Conditions

and

Returns.

None.

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

and

Restrictions.

If all the e i g e n v a l u e s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e s h o u l d b e f o l l o w e d by TQLI (F289), I M T Q L I (F291), or T Q L R A T (F235). If a l l the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e s h o u l d be f o l l o w e d by T Q L 2 (F290) or I M T Q L 2 (F292), and t h e n by HTRIB3 (F243) . If some of the e i g e n v a l u e s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e s h o u l d be f o l l o w e d by BISECT (F294) or T R I D I B (F237). If some of the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e s h o u l d be f o l l o w e d by T S T U R M (F293), or by B I S E C T (F294) and T I N V I T (F223), or by T R I D I B (F237) and TINVIT, or by I M T Q L V (F234) and T I N V I T , and then by H T R I B 3 (F243).

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

OF M E T H O D

AND

ALGORITHM.

The t r i d i a g o n a l r e d u c t i o n is p e r f o r m e d in the f o l l o w i n g way~ Starting with J=N, the e l e m e n t s in the J-th row to the left of the d i a g o n a l of A are f i r s t s c a l e d , to a v o i d p o s s i b l e u n d e r f l o w in the t r a n s f o r m a t i o n that m i g h t r e s u l t in severe departure from orthogonality. The s u m of s q u a r e d magnitudes SIGMA of t h e s e s c a l e d e l e m e n t s is n e x t formed. Then, a v e c t o r U and a s c a l a r

H = U U/2 define

an o p e r a t o r

P =

I - UU

/H

w h i c h is u n i t a r y and H e r m i t i a n and for w h i c h the s i m i l a r i t y transformation PAP e l i m i n a t e s the e l e m e n t s in the J-th r o w of A to the left of the s u b d i a g o n a l and the s y m m e t r i c a l e l e m e n t s in the J-th column.

366

7.1-172

The n o n - z e r o c o m p o n e n t s of U are the e l e m e n t s of the J-th row to the left of the d i a g o n a l w i t h the last of them a u g m e n t e d by the square root of SIGMA times the s u b d i a g o n a l e l e m e n t d i v i d e d by its m a g n i t u d e . By s t o r i n g the t r a n s f o r m e d s u b d i a g o n a l e l e m e n t e l s e w h e r e and not o v e r w r i t i n g the c o l u m n e l e m e n t s e l i m i n a t e d in the t r a n s f o r m a t i o n , full i n f o r m a t i o n about P is s a v e d for later use in HTRIB3. The t r a n s f o r m e d s u b d i a g o n a l e l e m e n t is then r e n d e r e d real by a d i a g o n a l unitary transformation. The a b o v e steps are r e p e a t e d on f u r t h e r rows of the transformed A in r e v e r s e order u n t i l A is r e d u c e d s y m m e t r i c t r i d i a g o n a l form; that is, r e p e a t e d for J = N-I,N-2,...,3.

to

The p r o d u c t of the d i a g o n a l u n i t a r y t r a n s f o r m a t i o n s is a c c u m u l a t e d into a u n i t a r y d i a g o n a l m a t r i x w h o s e d i a g o n a l e l e m e n t s are s a v e d in TAU for later use in HTRIB3. This s u b r o u t i n e is a c o m p l e x a n a l o g u e of the s u b r o u t i n e TRED3 (F228) w h i c h is a t r a n s l a t i o n of the A l g o l p r o c e d u r e TRED3 w r i t t e n and d i s c u s s e d in d e t a i l by M a r t i n ~ R e i n s c h , and W i l k i n s o n (I). A similar Algol procedure HOUSEHOLDER HERMITIAN is d i s c u s s e d in detail by M u e l l e r (2).

4. R E F E R E N C E S .

5.

i)

M a r t i n , R.S., R e i n s c h , C., and W i l k i n s o n , J.H., Householder's Tridiagonalization of a S y m m e t r i c M a t r i x , Num. Math. 1 1 , 1 8 1 - 1 9 5 (1968). ( R e p r i n t e d in H a n d b o o k for A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , J. H. W i l k i n s o n - C. R e i n s c h , C o n t r i b u t i o n 11/2, 212-226, Springer-Verlag, 1971.)

2)

M u e l l e r , D.J., Householder's and E i g e n s y s t e m s of H e r m i t i a n Num. Math. 8 , 7 2 - 9 2 (1966).

M e t h o d for Matrices,

Complex

Matrices

CHECKOUT. A.

Test

Cases°

See the s e c t i o n d i s c u s s i n g t e s t i n g complex Hermitian matrices.

367

of

the

codes

for

7.1-173

B°

Accuracy. The a c c u r a c y of HTRID3 can b e s t be d e s c r i b e d in terms of its r o l e in those p a t h s of EISPACK w h i c h find e i g e n v a l u e s and e i g e n v e c t o r s of c o m p l e x H e r m i t i a n matrices. In these paths, this s u b r o u t i n e is numerically s t a b l e (1,2). This s t a b i l i t y c o n t r i b u t e s to the p r o p e r t y of these p a t h s that the c o m p u t e d e i g e n v a l u e s are the exact e i g e n v a l u e s of a m a t r i x close to the o r i g i n a l m a t r i x and the c o m p u t e d e i g e n v e c t o r s are c l o s e (but not n e c e s s a r i l y equal) to the e i g e n v e c t o r s of that m a t r i x .

368

7.1-174

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

120

TAU(I,N) = 1.0 TAU(2,N) = 0.0 ********** F O R I = N S T E P -i U N T I L i D O -- * * * * * * * * * * D O 3 0 0 II = i~ N I = N + I - II L = I - i H = 0.0 SCALE = 0.0 IF (L .LT. i) G O T O 130 ********** SCALE ROW (ALGOL TOL THEN NOT NEEDED) ********** DO 120 K = i, L SCALE = SCALE + ABS(A(I,K)) + ABS(A(K,I)) IF ( S C A L E .NE. TAU(I,L) = 1.0 TAU(2,L) = 0.0

130

E(I)

E2(1) GO TO 140

150

160

170

=

0.0)

GO

TO

140

0.0 = 0.0 290

DO

1 5 0 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) CONTINUE

+

A(K,!)

* A(K,I)

E2(1) = SCALE * SCALE * H G -- S Q R T (I{) E(1) = SCALE * G F = CABS(CMPLX(A(I,L),A(L,I))) • ********* FORM NEXT DIAGONAL ELEMENT OF M A T R I X T ********** IF (F .EQ. 0 . 0 ) G O TO 1 6 0 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 2 7 0 GO T O 170 TAU(I,L) = -TAU(I,I) SI = T A U ( 2 , 1 ) A(I,L) = G F = 0.0

369

o

II

L...; L-~

11

~ 0

0 0

II

,~l o

00 o

t~

c~ 0

o'~ o

0

o

t~

I

I

tl

~

l

+

I,o I

H

+

11

¢-,o

I|

0

C~

t-t

H

+

Ix) C ) ¢7'

. t+.+ t";t'J H " , ~ I .0 ~ " II

(++,+ P,~ t',+:,

II r~

C.+~

h.."

II

0

L"x'J ~:" ¢--+

II

• +'++++++

:'~+J

~x~

~"

B+, ~ > c~ t-I II 0~+'+~ ( ~ , + - x C~ ~-'+'~ ~ ¢ ~ - ¢.-< r...+ +-~ ~ I-ol v ~ 4"

r-4

~e

¢'~ ix0

o

t--4

I

I,-.-t

~+. ~e

o o

;--+

Pe

['x'-J

Bx-J

L~

~

.++'+'x+

~

I

~t++ ~-~

C.+

+w+.+x~

t-'14 +

II >r'J ~ II r_.,, O ~ II •...+" +~;'+j I::~ L+~"J (~

(~I r..-~ ' ~

¢", II " ~

+

II

Ix~ P~ o

cb

tt

l'O

0

o

o

xJ

.

~

"~J ~ ~

+--t +----+

:+~

t.~

+

II

H

o

¢"b

I--:j

0

o

.++.+.

+ ~

i,+4 .+~+

+

¢+++..

~++'+ H c-x+

x--

+ + + :e,+ +

:g-+

i.-+ i..-..]

'.~

e..,+ [-rj

L'~ +...-, L- +

0

+,,~+

~>

II

Oo I10~'J

+

I

I+-1+

II

H

II

0

0

0

L~O

r_.+

O"

li 0

~:~

I1 0

U O

¢-,j

,k.n

'7+....,

7.1-176

290 300

T A U ( 2 , L ) = -SI D(1) = A ( I , I ) A(I,I) = SCALE CONTINUE

* SQRT(H)

RETURN END

371

7.1-177

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F234

PACKAGE

(EISPACK)

!MTQLV

A F o r t r a n IV S u b r o u t i n e to D e t e r m i n e the E i g e n v a l u e s of a S y m m e t r i c T r i d i a g o n a l Matrix.

July,

1975

I. PURPOSE. The F o r t r a n IV s u b r o u t i n e IMTQLV is a v a r i a n t of IMTQLI (F291) that d e t e r m i n e s the e i g e n v a l u e s of a s y m m e t r i c t r i d i a g o n a l m a t r i x u s i n g the i m p l i c i t QL m e t h o d , and a s s o c i a t e s w i t h them their c o r r e s p o n d i n g s u b m a t r i x indices. This f e a t u r e and the p r e s e r v a t i o n of the input m a t r i x m a k e it p o s s i b l e to later d e t e r m i n e the e i g e n v e c t o r s of the m a t r i x .

2. USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

IMTQLV(N,D,E,E2,W,

IND,IERR,RVI)

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

set

equal

to

is a w o r k i n g p r e c i s i o n real input oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N c o n t a i n i n g the d i a g o n a l e l e m e n t s of the symmetric tridiagonal matrix. is a w o r k i n g p r e c i s i o n real input oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N containing, in its last N-I positions, the s u b d i a g o n a l e l e m e n t s of the s y m m e t r i c tridiagonal matrix. E(1) is a r b i t r a r y .

372

7.1-178

E2

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

IND

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

IERR

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

RVI

B.

Error

to is

is a w o r k i n g p r e c i s i o n r e a l t e m p o r a r y oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N u s e d to copy the s u b d i a g o n a l a r r a y E w h i c h w o u l d o t h e r w i s e be d e s t r o y e d .

Conditions

and R e t u r n s .

If m o r e than 30 i t e r a t i o n s are r e q u i r e d to d e t e r m i n e an e i g e n v a l u e , IMTQLV terminates with IERR set to the i n d e x of the e i g e n v a l u e for w h i c h the f a i l u r e occurs. The e i g e n v a l u e s in the W a r r a y s h o u l d be c o r r e c t for i n d i c e s 1,2,...,IERR-I. These eigenvalues are o r d e r e d but are not n e c e s s a r i l y the s m a l l e s t IERR-I eigenvalues. If all the e i g e n v a l u e s are d e t e r m i n e d iterations, IERR is set to zero.

373

within

30

7.1-179

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

and

Restrictions.

The s u b r o u t i n e TQLI (F289) can also be u s e d to c o m p u t e the e i g e n v a l u e s of a s y m m e t r i c t r i d i a g o n a l m a t r i x . (No v a r i a n t of TQLI is a v a i l a b l e that a s s o c i a t e s s u b m a t r i x i n d i c e s w i t h the e i g e n v a l u e s . ) Note, h o w e v e r , that TQLI does not p e r f o r m w e l l on m a t r i c e s w h o s e s u c c e s s i v e row sums v a r y w i d e l y in m a g n i t u d e and are not s t r i c t l y i n c r e a s i n g f r o m the f i r s t to the last row. IMTQLV is not s e n s i t i v e to such row sums and is t h e r e f o r e e s p e c i a l l y r e c o m m e n d e d for s y m m e t r i c t r i d i a g o n a ! m a t r i c e s w h o s e s t r u c t u r e is not known. To d e t e r m i n e the e i g e n v a l u e s of a f u l l s y m m e t r i c m a t r i x , IMTQLV s h o u l d be p r e c e d e d by T R E D I (F277) to p r o v i d e a s u i t a b l e s y m m e t r i c t r i d i a g o n a l m a t r i x for IMTQLV. To d e t e r m i n e the e i g e n v a l u e s of a c o m p l e x H e r m i t i a n matrix, IMTQLV s h o u l d be p r e c e d e d by H T R I D I (F284) to p r o v i d e a s u i t a b l e real s y m m e t r i c t r i d i a g o n a l m a t r i x for IMTQLV. Note, h o w e v e r , that a l t h o u g h IMTQLV may perform better on s y m m e t r i c t r i d i a g o n a l m a t r i c e s p o o r l y s t r u c t u r e d in the a b o v e sense, TREDI and HTRIDI m a y also p e r f o r m p o o r l y on such f u l l s y m m e t r i c and c o m p l e x H e r m i t i a n matrices. Hence, any a d v a n t a g e in u s i n g IMTQLV over TQLI m a y be o v e r s h a d o w e d by a p o o r p e r f o r m a n c e in TREDI or HTRIDI. The e i g e n v a l u e s of c e r t a i n n o n - s y m m e t r i c tridiagonal m a t r i c e s can be c o m p u t e d using the c o m b i n a t i o n of FIGI (F280) and IMTQLV. See F280 for the d e s c r i p t i o n of this s p e c i a l class of m a t r i c e s . For such m a t r i c e s ~ IMTQLV s h o u l d be p r e c e d e d by FIGI to p r o v i d e a s u i t a b l e s y m m e t r i c m a t r i x for IMTQLV. To d e t e r m i n e e i g e n v e c t o r s a s s o c i a t e d w i t h the c o m p u t e d eigenvalues, !MTQLV s h o u l d be f o l l o w e d by TINVIT (F223) and the a p p r o p r i a t e b a c k t r a n s f o r m a t i o n s u b r o u t i n e -T R B A K I (F279) after TREDI, HTRIBK (F285) after H T R I D I , or B A K V E C (F281) after FIGI.

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

OF M E T H O D

AND

ALGORITHM.

The e i g e n v a l u e s are d e t e r m i n e d by the i m p l i c i t QL method. The e s s e n c e of this m e t h o d is a p r o c e s s w h e r e b y a s e q u e n c e of s y m m e t r i c t r i d i a g o n a l m a t r i c e s , u n i t a r i l y s i m i l a r to the o r i g i n a l s y m m e t r i c t r i d i a g o n a l m a t r i x , is f o r m e d w h i c h c o n v e r g e s to a d i a g o n a l m a t r i x . The rate of c o n v e r g e n c e of this s e q u e n c e is i m p r o v e d by i m p l i c i t l y s h i f t i n g the o r i g i n

374

7.1-180

at each i t e r a t i o n . B e f o r e each i t e r a t i o n , the s y m m e t r i c t r i d i a g o n a l m a t r i x is c h e c k e d for a p o s s i b l e s p l i t t i n g into submatrices. If a s p l i t t i n g o c c u r s , only the u p p e r m o s t s u b m a t r i x p a r t i c i p a t e s in the n e x t i t e r a t i o n . The e i g e n v a l u e s are o r d e r e d in a s c e n d i n g order as they are found. The o r i g i n shift at each i t e r a t i o n is the e i g e n v a l u e of the current uppermost 2x2 p r i n c i p a l m i n o r closer to the first d i a g o n a l e l e m e n t of this minor. W h e n e v e r the u p p e r m o s t ixl p r i n c i p a l s u b m a t r i x f i n a l l y splits f r o m the rest of the m a t r i x , its e l e m e n t is taken to be an e i g e n v a l u e of the o r i g i n a l m a t r i x and the a l g o r i t h m p r o c e e d s w i t h the r e m a i n i n g submatrix. This p r o c e s s is c o n t i n u e d u n t i l the m a t r i x has split c o m p l e t e l y into s u b m a t r i c e s of order i. The t o l e r a n c e s in the s p l i t t i n g tests are p r o p o r t i o n a l to the relative machine precision. This s u b r o u t i n e is a m o d i f i c a t i o n of the s u b r o u t i n e IMTQLI w h i c h is a t r a n s l a t i o n of the A l g o l p r o c e d u r e IMTQLI w r i t t e n and d i s c u s s e d in d e t a i l by M a r t i n and W i l k i n s o n (i) and m o d i f i e d by D u b r u l l e (2).

4.

REFERENCES. i)

M a r t i n , R.S. and W i l k i n s o n , J.H., The I m p l i c i t A l g o r i t h m , Num. Math. 1 2 , 3 7 7 - 3 8 3 (1968).

QL

2)

D u b r u l l e , A., A Short Note on the I m p l i c i t QL A l g o r i t h m , Num. Math. 15,450 (1970). ( C o m b i n e d W i t h (i) in H a n d b o o k for A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , J. H. W i l k i n s o n - C. R e i n s c h , C o n t r i b u t i o n II/4, 241-248, S p r i n g e r - V e r l a g , 1971.)

5. C H E C K O U T . A.

Test

Cases.

See the s e c t i o n d i s c u s s i n g t e s t i n g of the codes for c o m p l e x H e r m i t i a n , real s y m m e t r i c , real s y m m e t r i c t r i d i a g o n a l , and c e r t a i n real n o n - s y m m e t r i c tridiagonal matrices.

B.

Accuracy. The s u b r o u t i n e IMTQLV is n u m e r i c a l l y s t a b l e (1,2); that is, the c o m p u t e d e i g e n v a l u e s are close to those of the o r i g i n a l m a t r i x . In a d d i t i o n , they are the exact e i g e n v a l u e s of a m a t r i x close to the o r i g i n a l real s y m m e t r i c t r i d i a g o n a l 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

=

MACHEP IS A THE RELATIVE

MACHINE DEPENDENT PARAMETER SPECIFYING PRECISION OF F L O A T I N G POINT ARITHMETIC.

?

IERR = 0 K = 0 TAG = 0 DO

100

i 0 0 1 = i, N w(1) = D(I) IF (I .NE. i) CONTINUE

RVI(I-I)

=

E(i)

E2(1) = 0.0 RVI(N) = 0.0 DO

C

C

2 9 0 L = i, N J = 0 ********** LOOK FOR SMALL SUB-DIAGONAL ELEMENT ********** 105 D O ii0 M = L, N IF (M .EQ. N) GO TO 1 2 0 IF ( A B S ( R V I ( M ) ) .LE. M A C H E P * (ABS(W(M)) + ABS(W(M+I)))) X GO TO 120 ********** GUARD AGAINST UNDERFLOWED ELEMENT OF E2 * * * * * * * * * * IF ( E 2 ( M + I ) .EQ. 0 . 0 ) GO T O 125 ii0 CONTINUE 120 125 130

C

IF (M .LE. K) G O T O 1 3 0 IF (M ,NE. N) E 2 ( M + I ) = 0.0 K = M TAG = TAG + I P = W(L) IF (M .EQ. L) G O T O 2 1 5 IF (J .EQ. 30) GO T O i 0 0 0 J = J + i ********** FORM SHIFT ********** G = (W(L+I) - P) / ( 2 . 0 * R V I ( L ) ) R = SQRT (G'G+1.0) G = W(M) - P + RVI(L) / (g + S I G N ( R , G ) ) S = 1.0 C = 1,0 P = 0.0 MML = M - L

376

7.1-182

150

160

200

215

230 250 270 290

********** FOR I--M-I D O 2 0 0 I I = i, M M L I = M - II F = S * RVI(I) B = C * RVI(I) IF (ABS(F) .LT. C = G / F R = SQRT(C*C+I.0) RVI(I+I) = F * S = 1.0 / R C = C * S GO TO 160 S = F / G R = SQRT(S*S+I.0) RVI(I+I) = G * C = 1.0 / R S = S * C G = W(I+I) - P R = (W(1) - G) P = S * R W(I+I) = G + P G = C * R - B CONTINUE

i000 i001

-i

UNTIL

ABS(G))

GO

L

TO

DO

--

I = 1 W(I) = IND(I) CONTINUE

IERR = RETURN END

P =

**********

150

R

R

*

S +

2.0

*

C

*

B

W(L) = W(L) - P RVI(L) = G RVI(M) = 0.0 GO TO 105 ********** ORDER EIGENVALUES ********** I F (L . E Q . I) G O T O 2 5 0 ********** FOR I=L STEP -i UNTIL 2 DO -D O 2 3 0 I I = 2, L I = L 4. 2 - I I I F (P . G E . W ( I - I ) ) GO TO 270 w(i) = w(i-1) IND(I) = IND(I-I) CONTINUE

GO TO I001 **********

C C

STEP

**********

TAG

SET ERROR EIGENVALUE

-- NO AFTER

L

377

CONVERGENCE TO 30 ITERATIONS

AN **********

7.1-183

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F291

PACKAGE

(EISPACK)

IMTQLI

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

May,

1972

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e of a s y m m e t r i c t r i d i a g o n a l method.

IMTQLI matrix

d e t e r m i n e s the e i g e n v a l u e s u s i n g the i m p l i c i t QL

2. USAGE. A~

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

IMTQLI(N,D,E,IERR)

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

set

equal

to

is a w o r k i n g p r e c i s i o n r e a l o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N. On input, it c o n t a i n s the d i a g o n a l e l e m e n t s of the s y m m e t r i c t r i d i a g o n a l m a t r i x . On output, it c o n t a i n s the e i g e n v a l u e s of this m a t r i x in a s c e n d i n g order. is a w o r k i n g p r e c i s i o n r e a l o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N. On input, the last N-I p o s i t i o n s in this a r r a y c o n t a i n the s u b d i a g o n a l e l e m e n t s of the s y m m e t r i c t r i d i a g o n a l matrix. E(1) is arbitrary. N o t e that IMTQLI destroys E.

378

7.1-184

IERR

B.

Error

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

Conditions

to is

and R e t u r n s .

If m o r e than 30 i t e r a t i o n s are r e q u i r e d to d e t e r m i n e an e i g e n v a l u e , IMTQLI terminates with IERR set to the i n d e x of the e i g e n v a l u e for w h i c h the f a i l u r e occurs. The e i g e n v a l u e s in the D a r r a y s h o u l d be c o r r e c t for i n d i c e s 1,2,...,IERR-I. These eigenvalues are o r d e r e d but are not n e c e s s a r i l y the s m a l l e s t IERR-I eigenvalues. If all the e i g e n v a l u e s are d e t e r m i n e d iterations, IERR is set to zero.

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

and

within

30

Restrictions.

The s u b r o u t i n e TQLI (F289) can also be u s e d to c o m p u t e the e i g e n v a l u e s of a s y m m e t r i c t r i d i a g o n a l m a t r i x . N o t e , h o w e v e r , that TQLI does not p e r f o r m w e l l on m a t r i c e s w h o s e s u c c e s s i v e r o w sums v a r y w i d e l y in m a g n i t u d e and are not s t r i c t l y i n c r e a s i n g f r o m the f i r s t to the last row. IMTQLI is not s e n s i t i v e to s u c h row sums and is t h e r e f o r e e s p e c i a l l y r e c o m m e n d e d for s y m m e t r i c t r i d i a g o n a l m a t r i c e s w h o s e s t r u c t u r e is n o t known. To d e t e r m i n e the e i g e n v a l u e s of a f u l l s y m m e t r i c m a t r i x , IMTQLI s h o u l d be p r e c e d e d by T R E D I (F277) to p r o v i d e a s u i t a b l e s y m m e t r i c t r i d i a g o n a l m a t r i x for IMTQLI. To d e t e r m i n e the e i g e n v a l u e s of a c o m p l e x H e r m i t i a n matrix, IMTQLI s h o u l d be p r e c e d e d by H T R I D I (F284) to p r o v i d e a s u i t a b l e real s y m m e t r i c t r i d i a g o n a l m a t r i x for IMTQLI. Note, h o w e v e r , that a l t h o u g h IMTQLI may perform better on s y m m e t r i c t r i d i a g o n a l m a t r i c e s p o o r l y s t r u c t u r e d in the a b o v e sense, TREDI and HTRIDI m a y also p e r f o r m p o o r l y on such f u l l s y m m e t r i c and c o m p l e x H e r m i t i a n matrices. H e n c e , any a d v a n t a g e in u s i n g IMTQLI over TQLI m a y be o v e r s h a d o w e d b y a p o o r p e r f o r m a n c e in TREDI or HTRIDI.

379

7.1-185

The e i g e n v a l u e s of c e r t a i n n o n - s y m m e t r i c tridiagonal m a t r i c e s can be c o m p u t e d using the c o m b i n a t i o n of FIGI (F280) and IMTQLI. See F280 for the d e s c r i p t i o n of this s p e c i a l class of m a t r i c e s . For such m a t r i c e s , IMTQLI s h o u l d be p r e c e d e d by FIGI to p r o v i d e a s u i t a b l e s y m m e t r i c m a t r i x for IMTQLI. 3. D I S C U S S I O N

OF M E T H O D

AND

ALGORITHM.

The e i g e n v a l u e s are d e t e r m i n e d by the i m p l i c i t QL method. The e s s e n c e of this m e t h o d is a p r o c e s s w h e r e b y a s e q u e n c e of s y m m e t r i c t r i d i a g o n a l m a t r i c e s , u n i t a r i ! y s i m i l a r to the o r i g i n a l s y m m e t r i c t r i d i a g o n a l m a t r i x , is f o r m e d w h i c h c o n v e r g e s to a d i a g o n a l m a t r i x . The rate of c o n v e r g e n c e of this s e q u e n c e is i m p r o v e d by i m p l i c i t l y s h i f t i n g the o r i g i n at each i t e r a t i o n . B e f o r e each i t e r a t i o n , the s y m m e t r i c t r i d i a g o n a ! m a t r i x is c h e c k e d for a p o s s i b l e s p l i t t i n g into submatrices. If a s p l i t t i n g o c c u r s , o n l y the u p p e r m o s t submatrix participates in the n e x t i t e r a t i o n . The e i g e n v a l u e s are o r d e r e d in a s c e n d i n g o r d e r as they are found. The o r i g i n shift at each i t e r a t i o n is the e i g e n v a l u e of the current uppermost 2x2 p r i n c i p a l m i n o r c l o s e r to the first d i a g o n a l e l e m e n t of this m i n o r . W h e n e v e r the u p p e r m o s t ixl p r i n c i p a l s u b m a t r i x f i n a l l y s p l i t s f r o m the rest of the m a t r i x , its e l e m e n t is t a k e n to be an e i g e n v a l u e of the o r i g i n a l m a t r i x and the a l g o r i t h m p r o c e e d s w i t h the r e m a i n i n g submatrix. This p r o c e s s is c o n t i n u e d u n t i l the m a t r i x has split c o m p l e t e l y into s u b m a t r i c e s of order i. The t o l e r a n c e s in the s p l i t t i n g tests are p r o p o r t i o n a l to the relative machine precision. This s u b r o u t i n e is a t r a n s l a t i o n of the A l g o l p r o c e d u r e IMTQLI w r i t t e n and d i s c u s s e d in d e t a i l by M a r t i n and Wilkinson (I) and m o d i f i e d by D u b r u l l e (2).

4.

REFERENCES. i)

M a r t i n , R.S. and W i l k i n s o n , J.H., The I m p l i c i t A l g o r i t h m , Num. Math. 1 2 , 3 7 7 - 3 8 3 (1968).

2)

D u b r u l l e , A.~ A Short N o t e on the I m p l i c i t A l g o r i t h m , Num~ Math. 15,450 (1970). ( C o m b i n e d W i t h (I) in H a n d b o o k for A u t o m a t i c v o l u m e II, L i n e a r A l g e b r a , J. H. W i l k i n s o n Contribution II/4, 2 4 1 - 2 4 8 , S p r i n g e r - V e r l a g ,

380

QL

QL Computation, C. R e i n s c h , 1971.)

7.1-186

5. CHECKOUT. A. Test

Cases.

See the section discussing testing of the codes for complex Hermitian, real symmetric, real symmetric tridiagonal, and certain real n o n - s y m m e t r i c tridiagonal matrices. B. Accuracy. The subroutine IMTQLI is n u m e r i c a l l y stable (1,2); that is, the computed eigenvalues are close to those of the original matrix. In addition, they are the exact eigenvalues of a matrix close to the original real symmetric tridiagonal matrix.

381

7. 1 - 1 8 7

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

**********

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

MACHEP

=

?

IERR = 0 IF (N .EQ.

100

DO i00 E(I-I)

i)

i = 2, = E(I)

GO

TO

I001

N

-- 0 . 0

E(N)

DO

2 9 0 L = i, N J = 0 ********** LOOK FOR 105 D O I i 0 M = L, N I F (M . E Q . N) IF (ABS(E(M)) X GO TO 120 i i0 CONTINUE 120

P

=

SMALL

SUB-DIAGONAL

GO TO 120 .LE. M A C H E P

*

ELEMENT

(ABS(D(M))

**********

+

ABS(D(M+I))))

D(L)

IF (M .EQ. L) ~O TO 215 IF (J .EQ. 30) G O T O i 0 0 0 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 + S I G N ( R , G ) ) S = 1.0 C = 1.0 P = 0.0 MML = M - L ********** FOR I=M-I STEP -I UNTIL L DO D O 2 0 0 II = I, M M L I = M - !I

F B

= =

s C

* *

E(I) E(I)

IF ( A B S ( F ) .LT. A B S ( G ) ) C = G / F R = SQRT(C*C+I.O) E(I+I) = F * R

s=

i.o / R

C = C GO TO

* S 160

382

GO

TO

150

--

**********

7. 1 - 1 8 8

150

S = F / G R = SQRT(S*S+I.O) E(I+I) = G * R

c=

i.o / R

S = S * C G = D(I+I) - e R = (D(1) - G) P = S * R D(I+I) = G + P G = C * R - B CONTINUE

160

200

*

S +

2.0

*

C

*

B

230

D(L) = D(L) - P E(L) = G E(M) = 0.0 GO TO 105 ********** ORDER EIGENVALUES ********** IF (L . E Q . i) G O T O 2 5 0 ********** FOR I=L STEP -i U N T I L 2 D O -D O 2 3 0 I I = 2, L I = L + 2 - II I F (e . G E . D ( I - I ) ) GO TO 270 D(1) = D(I-I) CONTINUE

250 270 290

I = 1 D(I) = CONTINUE

215

GO C C

TO

IERR = RETURN END

P

i001

********** i000 i001

**********

SET ERROR EIGENVALUE

-- NO AFTER

L

383

CONVERGENCE TO 30 ITERATIONS

AN **********

7.1-189

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F292

PACKAGE

(EISPACK)

IMTQL2

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

May,

and

1972

I. P U R P O S E . The F o r t r a n IV s u b r o u t i n e IMTQL2 d e t e r m i n e s the e i g e n v a l u e s and e i g e n v e c t o r s of a s y m m e t r i c t r i d i a g o n a l m a t r i x . IMTQL2 uses the i m p l i c i t QL m e t h o d to c o m p u t e the e i g e n v a l u e s and a c c u m u l a t e s the QL transformations to c o m p u t e the eigenvectors. The e i g e n v e c t o r s of a f u l l s y m m e t r i c m a t r i x can a l s o be c o m p u t e d d i r e c t l y by I M T Q L 2 , if T R E D 2 (F278) has b e e n u s e d to r e d u c e this m a t r i x to t r i d i a g o n a l form.

2. U S A G E . A.

Calling The

Sequence°

SUBROUTINE SUBROUTINE

statement

is

IMTQL2(NM,N,D,E,Z,IERR)

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

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

N

is an i n t e g e r i n p u t v a r i a b l e the o r d e r of the m a t r i x . N g r e a t e r than NM.

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

is a w o r k i n g p r e c i s i o n r e a l o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N. On input, it c o n t a i n s the d i a g o n a l e l e m e n t s of the s y m m e t r i c t r i d i a g o n a l m a t r i x . On o u t p u t , it c o n t a i n s the e i g e n v a l u e s of this m a t r i x in a s c e n d i n g order.

384

7.1-190

is a w o r k i n g p r e c i s i o n r e a l o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N. On input, the last N-I p o s i t i o n s in this a r r a y c o n t a i n the s u b d i a g o n a l e l e m e n t s of the s y m m e t r i c t r i d i a g o n a l m a t r i x . E(1) is arbitrary. N o t e that IMTQL2 destroys E. is a w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t N. If the e i g e n v e c t o r s of the s y m m e t r i c t r i d i a g o n a l m a t r i x are d e s i r e d , then on input, Z c o n t a i n s the i d e n t i t y m a t r i x of o r d e r N, and on o u t p u t , c o n t a i n s the o r t h o n o r m a l e i g e n v e c t o r s of this t r i d i a g o n a l m a t r i x . If the e i g e n v e c t o r s of a full s y m m e t r i c m a t r i x are d e s i r e d , then on input, Z c o n t a i n s the t r a n s f o r m a t i o n m a t r i x p r o d u c e d in TRED2 w h i c h r e d u c e d the full m a t r i x to t r i d i a g o n a l form, and on output, c o n t a i n s the o r t h o n o r m a l e i g e n v e c t o r s of this full s y m m e t r i c matrix. IERR

B. E r r o r

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

Conditions

to is

and R e t u r n s .

If m o r e than 30 i t e r a t i o n s are r e q u i r e d to d e t e r m i n e an e i g e n v a l u e , IMTQL2 terminates with IERR set to the i n d e x of the e i g e n v a l u e for w h i c h the f a i l u r e occurs. T h e e i g e n v a l u e s a n d e i g e n v e c t o r s in the D and Z a r r a y s s h o u l d be c o r r e c t for i n d i c e s 1,2,...,IERR-I, b u t the e i g e n v a l u e s are u n o r d e r e d . If all the e i g e n v a l u e s are d e t e r m i n e d iterations, IERR is set to zero.

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

and

within

30

Restrictions.

The s u b r o u t i n e TQL2 (F290) can also be u s e d to c o m p u t e the e i g e n v a l u e s and e i g e n v e c t o r s of a s y m m e t r i c tridiagonal matrix. Note, h o w e v e r , that TQL2 does not p e r f o r m w e l l on m a t r i c e s w h o s e s u c c e s s i v e r o w sums v a r y w i d e l y in m a g n i t u d e and are not s t r i c t l y i n c r e a s i n g f r o m the f i r s t to the last row. IMTQL2 is n o t s e n s i t i v e to s u c h row sums and is t h e r e f o r e e s p e c i a l l y r e c o m m e n d e d for s y m m e t r i c t r i d i a g o n a l m a t r i c e s w h o s e s t r u c t u r e is not known.

385

7.1-191

To d e t e r m i n e the e i g e n v a l u e s and eigenvectors of a full symmetric matrix, IMTQL2 should be preceded by TRED2 (F278) to provide a suitable symmetric tridiagonal m a t r i x for IMTQL2. To determine the eigenvalues and e i g e n v e c t o r s of a complex H e r m i t i a n matrix, IMTQL2 should be preceded by HTR!DI (F284) to provide a suitable real symmetric t r i d i a g o n a l matrix for IMTQL2, and the input array Z to IMTQL2 should be i n i t i a l i z e d to the identity matrix. IMTQL2 should then be followed by HTRIBK (F285) to back transform the e i g e n v e c t o r s from IMTQL2 into those of the original matrix. Note~ however, that although !MTQL2 may p e r f o r m better on s y m m e t r i c t r i d i a g o n a l matrices poorly s t r u c t u r e d in the above sense, TRED2 and HTRIDI may also p e r f o r m poorly on such full symmetric and complex H e r m i t i a n matrices. Hence, any a d v a n t a g e in using IMTQL2 over TQL2 may be o v e r s h a d o w e d by a poor p e r f o r m a n c e in TRED2 or HTRIDI. The eigenvalues and e i g e n v e c t o r s of certain nonsymmetric tridiagonal matrices can be computed using the c o m b i n a t i o n of FIGI2 (F222) and IMTQL2. See F222 for the d e s c r i p t i o n of this special class of matrices. For such matrices, IMTQL2 should be preceded by FIGI2 to p r o v i d e a suitable symmetric m a t r i x for IMTQL2.

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

OF M E T H O D

AND ALGORITHM.

The e i g e n v a ! u e s are d e t e r m i n e d by the implicit QL method. The essence of this method is a process w h e r e b y a sequence of symmetric t r i d i a g o n a l matrices, unitarily similar to the o r i g i n a l symmetric t r i d i a g o n a l matrix, is formed which converges to a d i a g o n a l matrix. The rate of convergence of this sequence is improved by i m p l i c i t l y shifting the origin at each iteration~ Before each iteration, the symmetric t r i d i a g o n a l m a t r i x is checked for a possible splitting into submatrices. If a splitting occurs, only the uppermost s u b m a t r i x p a r t i c i p a t e s in the next iteration. The similarity t r a n s f o r m a t i o n s used in each iteration are a c c u m u l a t e d in the Z array, p r o d u c i n g the o r t h o n o r m a l e i g e n v e c t o r s for the original matrix. Finally, the eigenvalues are ordered in a s c e n d i n g order and the e i g e n v e e t o r s are ordered consistently. The origin shift at each iteration is the e i g e n v a l u e of the current u p p e r m o s t 2x2 p r i n c i p a l minor closer to the first diagonal element of this minor. W h e n e v e r the uppermost ixl p r i n c i p a l s u b m a t r i x 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 m a t r i x has split completely into submatrices of order i. The tolerances in the splitting tests are p r o p o r t i o n a l to the relative machine precision. This subroutine is a translation of the Algol procedure IMTQL2 written and discussed in detail by Martin and W i l k i n s o n (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 Algorithm, Num. Math. 15,450 (1970). (Combined With (i) in H a n d b o o k for Automatic Volume II, Linear Algebra, J. H. Wilkinson C o n t r i b u t i o n 11/4, 241-248, Springer-Verlag,

QL Computation, C. Reinsch, 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 n o n - s y m m e t r i c tridiagonal matrices.

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

387

7.1-193

SUBROUTINE

IMTQL2(NM,N,D,E,Z,IERR)

INTEGER I,J,K,L,M,N, II,NM,MML,IERR R E A L D (N) , E ( N ) , Z ( N M , N ) REAL B,C,F,G,P,R,S,MACHEP REAL SQRT,ABS,SiGN C C C C C

**********

MACHEP

=

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

?

IERR = 0 I F (N .EQ.

i00

i)

DO i00 E(I-I)

I = 2, = E(1)

E(N)

0.0

=

GO

TO

I001

N

DO

2 4 0 L = I, N J = 0 ********** LOOK FOR 105 D O i i 0 M = L, N IF (M .EQ. N) IF ( A B S ( E ( M ) ) X GO TO 120 Ii0 CONTINUE 120

SMALL

SUB-DIAGONAL

GO TO 120 oLE. M A C H E P

*

(ABS(D(M))

P = D (L) IF (M .EQ. L) G O T O 2 4 0 IF (J . E Q . 30) G O T O I 0 0 0 J = J + 1 ********** FORM SHIFT ********** G = (D(L+I) - P) / ( 2 . 0 * E ( L ) ) R = S Q R T ( G * G + I . 0) G = D(M) - P + E(L) / (G + S I G N ( R , G ) ) S = 1.0 C = 1.0 P = 0.0 MML = M - L ********** FOR I=M-I S T E P -I U N T I L L D O D O 2 0 0 II = I, M M L I = M - I! F = S * E(1) B = C * E(1) IF ( A B S ( F ) .LT. A B S ( 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

ELEMENT

--

**********

+

ABS(D(M+I))))

**********

7.1-194

150

160

180 200

240

S = F / G R = SQRT(S*S+I.0) E(I+I) = G * R C= 1.0 /R S = S * C G = D(I+I) - P R = (D(1) - G) * S + 2 . 0 * C P = S * R D(I+I) = G + P G = C * R - B • ********* FORM VECTOR ********** D O 1 8 0 K = I, N F = Z(K,I+I) Z(K,I+I) = S * Z(K,I) + C Z(K,I) = C * Z(K,I) - S * CONTINUE

*

B

* F

F

CONTINUE D(L) = D(L) E(L) = G E(M) = 0.0 GO TO 105 CONTINUE ********** ORDER D O 3 0 0 I I = 2, N I = II - i K = I e = D(1)

P

EIGENVALUES

EIGENVECTORS

**********

DO

260

260 J = II, N IF ( D ( J ) .GE. K = J P = D(J) CONTINUE

AND

IF (K . E Q . I) D(K) = D(1) D(1) = P

GO

P)

GO

TO

300

TO

260

DO

280 300

2 8 0 J = I, N P = Z(J,l) Z(J,I) = Z(J,K) Z(J,K) = P CONTINUE

CONTINUE GO TO i001 **********

C C i000 i001

IERR = RETURN END

SET ERROR EIGENVALUE

-- NO AFTER

L

389

CONVERGENCE TO 30 I T E R A T I O N S

AN **********

7.1-195

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F288-2

PACKAGE

(EISPACK)

iNVIT

A F o r t r a n IV S u b r o u t i n e to D e t e r m i n e T h o s e E i g e n v e c t o r s of a Real U p p e r H e s s e n b e r g M a t r i x C o r r e s p o n d i n g to S p e c i f i e d E i g e n v a l u e s .

May, July,

1.

1972 1975

PURPOSE. The F o r t r a n IV s u b r o u t i n e INVIT c o m p u t e s the e i g e n v e c t o r s of a r e a l u p p e r H e s s e n b e r g m a t r i x c o r r e s p o n d i n g to s p e c i f i e d eigenvalues using inverse iteration.

2. U S A G E . A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

INVlT(NM,NgA,WR,WI,SELECT,MM,M,Z~ IERR,RMI,RVI,RV2)

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

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

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

is a w o r k i n g p r e c i s i o n r e a l i n p u t twod i m e n s i o n a l v a r i a b l e w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at l e a s t N containing the u p p e r H e s s e n b e r g m a t r i x .

390

7.1-196

WR,WI

are w o r k i n g p r e c i s i o n real o n e - d i m e n s i o n a l v a r i a b l e s of d i m e n s i o n at least N. On input, they c o n t a i n the real and i m a g i n a r y parts, r e s p e c t i v e l y , of the e i g e n v a l u e s of the H e s s e n b e r g matrix. The e i g e n v a l u e s n e e d not be ordered, e x c e p t that c o m p l e x conjugate eigenvalues must appear c o n s e c u t i v e l y and e i g e n v a l u e s of any s u b m a t r i x of the input H e s s e n b e r g m a t r i x m u s t h a v e i n d i c e s in WR,WI w h i c h lie b e t w e e n the b o u n d a r y i n d i c e s for that submatrix. T h e s e o r d e r i n g c o n s t r a i n t s are s a t i s f i e d by the o u t p u t e i g e n v a l u e s f r o m HQR (F286). On output, the e i g e n v a l u e s are u n a l t e r e d , e x c e p t that the real parts of close e i g e n v a l u e s m a y be p e r t u r b e d s l i g h t l y in an a t t e m p t to o b t a i n i n d e p e n d e n t eigenvectors.

SELECT

is a l o g i c a l o n e - d i m e n s i o n a l variable d i m e n s i o n at least N. On input, the e l e m e n t s flag those e i g e n v a l u e s w h o s e e i g e n v e c t o r s are desired. If both of of c o m p l e x c o n j u g a t e e i g e n v a l u e s are flagged, the s e c o n d flag is set false only the e i g e n v e c t o r c o r r e s p o n d i n g to first of these is c o m p u t e d .

MM

of true a pair and the

is an i n t e g e r input v a r i a b l e set equal to an upper b o u n d for the n u m b e r of columns r e q u i r e d to store the real and i m a g i n a r y parts of the r e q u e s t e d e i g e n v e c t o r s . The e i g e n v e c t o r c o r r e s p o n d i n g to a real (complex) e i g e n v a l u e r e q u i r e s one (two) column(s). is an i n t e g e r o u t p u t v a r i a b l e set equal to the n u m b e r of c o l u m n s a c t u a l l y u s e d to store the e i g e n v e c t o r s . is a w o r k i n g p r e c i s i o n real o u t p u t twod i m e n s i o n a l v a r i a b l e w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at least MM c o n t a i n i n g the e i g e n v e c t o r s c o r r e s p o n d i n g to the f l a g g e d e i g e n v a l u e s . The real and i m a g i n a r y parts of c o m p l e x e i g e n v e c t o r s are s t o r e d in c o n s e c u t i v e columns w i t h the real part first. The e i g e n v e c t o r s are p a c k e d into the c o l u m n s of Z s t a r t i n g at the f i r s t column.

391

7.1-197

IERR

B.

Error

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

to is

RM 1

is a w o r k i n g p r e c i s i o n r e a l t e m p o r a r y a r r a y v a r i a b l e of d i m e n s i o n at l e a s t N*N. This a r r a y h o l d s the t r i a n g u l a r i z e d f o r m of the upper Hessenberg m a t r i x u s e d in the i n v e r s e iteration process.

RVI,RV2

are working precision real temporary onedimensional v a r i a b l e s of d i m e n s i o n at l e a s t N. T h e y h o l d the a p p r o x i m a t e eigenvectors during the inverse iteration process.

Conditions

and

Returns.

If m o r e t h a n MM c o l u m n s of Z are n e c e s s a r y to s t o r e the e i g e n v e c t o r s corresponding to the f l a g g e d eigenvalues, INVIT terminates with IERR set to -(2*N+I). In t h i s c a s e , M is e i t h e r MM or MM-I a n d is the n u m b e r of c o l u m n s of Z containing eigenvectors already computed. If n o n e of the i n i t i a l v e c t o r s for the i n v e r s e i t e r a t i o n p r o c e s s p r o d u c e s an a c c e p t a b l e approximation to an eigenvector, INVIT terminates the c o m p u t a t i o n for t h a t eigenvector and sets IERR to -K where K is the i n d e x of the a s s o c i a t e d eigenvalue. If t h i s f a i l u r e o c c u r s for m o r e t h a n o n e e i g e n v a l u e , the last occurrence is r e c o r d e d in IERR. T h e c o l u m n s of Z corresponding to f a i l u r e s of the a b o v e s o r t a r e set to z e r o v e c t o r s . If b o t h of t h e a b o v e e r r o r c o n d i t i o n s o c c u r , INVIT terminates with IERR s e t to -(N+K) where K is the i n d e x of the l a s t e i g e n v a l u e w h o s e i n v e r s e i t e r a t i o n process failed. T h e c o l u m n s of Z corresponding to f a i l u r e s in the i n v e r s e i t e r a t i o n p r o c e s s a r e set to zero vectors, a n d in t h i s c a s e , M is the n u m b e r of c o l u m n s of Z containing eigenvectors already computed. If n e i t h e r sets IERR

of the a b o v e to z e r o .

392

error

conditions

occurs,

INVIT

7.1-198

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

and

Restrictions.

To d e t e r m i n e e i g e n v e c t o r s c o r r e s p o n d i n g to some of the e i g e n v a l u e s of a r e a l g e n e r a l m a t r i x , INVIT s h o u l d be p r e c e d e d by E L M H E S (F273) or O R T H E S (F275) and HQR (F286). ELMHES or ORTHES provides a suitable upper H e s s e n b e r g m a t r i x for INVIT and HQR d e t e r m i n e s the e i g e n v a l u e s of this H e s s e n b e r g m a t r i x . INVIT should then be f o l l o w e d by E L M B A K (F274) or O R T B A K (F276) to b a c k t r a n s f o r m the e i g e n v e c t o r s f r o m INVIT into t h o s e of the o r i g i n a l m a t r i x . Note: the u p p e r H e s s e n b e r g m a t r i x and the two a d j a c e n t s u b d i a g o n a l s m u s t be s a v e d b e f o r e HQR, since HQR d e s t r o y s this p a r t of A. It is r e c o m m e n d e d in g e n e r a l that B A L A N C (F269) be used before ELMHES or ORTHES in w h i c h case BALBAK (F270) m u s t be u s e d a f t e r ELMBAK or ORTBAK. In this i m p l e m e n t a t i o n , the a r i t h m e t i c t h r o u g h o u t e x c e p t for c o m p l e x d i v i s i o n a b s o l u t e value.

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

OF M E T H O D

AND

is real and c o m p l e x

ALGORITHM.

The e i g e n v e c t o r s are d e t e r m i n e d by i n v e r s e i t e r a t i o n . In INVIT, this is a p r o c e s s w h e r e b y a v e c t o r X1 s a t i s f y i n g the matrix linear equation U'X1 = X0 is c o m p u t e d , w h e r e X0 is an i n i t i a l v e c t o r and U is the u p p e r t r i a n g u l a r f a c t o r in the LU d e c o m p o s i t i o n of the m a t r i x B-W*I with partial pivoting. W is an a p p r o x i m a t e e i g e n v a l u e of a leading submatrix B of the H e s s e n b e r g m a t r i x in A. The vector X1 is a c c e p t e d as an e i g e n v e c t o r of B if the n o r m of X1 is s u f f i c i e n t l y l a r g e r than the n o r m of X0. This e i g e n v e c t o r of B is t r a n s f o r m e d to an e i g e n v e c t o r of A by s i m p l y a p p e n d i n g zero c o m p o n e n t s to it. The c o m p u t a t i o n s for the real and c o m p l e x e i g e n v e c t o r s are separate. In the real case, the f a c t o r U in the LU d e c o m p o s i t i o n is s t o r e d in the full l o w e r t r i a n g l e of the array RMI, and in the c o m p l e x case, the r e a l p a r t of U is s t o r e d in the f u l l l o w e r t r i a n g l e of RMI and the i m a g i n a r y part of U is s t o r e d in the u p p e r t r i a n g l e of RMI above the s u p e r d i a g o n a l a u g m e n t e d by the two c o l u m n s of Z that w i l l later s t o r e the c o m p l e x e i g e n v e c t o r . (Internally, RMI is t r e a t e d as a t w o - d i m e n s i o n a l NxN array.) The a c c e p t a n c e c r i t e r i o n for X1 is a g r o w t h test of its norm. If MACHEP d e n o t e s the r e l a t i v e m a c h i n e p r e c i s i o n , then c u r r e n t l y , X1 is r e j e c t e d as an e i g e n v e e t o r if SQRT(UK)*!!B!!*MACHEP*!!XI!!

393

.LT.

!!X0!!/10.0

7.1-199

where UK is the order of the s u b m a t r i x B whose e i g e n v e c t o r is b e i n g c o m p u t e d and the n o r m !! !! is the i n f i n i t y norm. At m o s t UK orthogonal initial vectors X0 are t r i e d to o b t a i n the r e q u i r e d g r o w t h . If no v e c t o r is a c c e p t e d , the p a r a m e t e r !ERR is set to i n d i c a t e this failure and !NVIT p r o c e e d s to c o m p u t e the n e x t e i g e n v e c t o r . The real p a r t s of c l o s e or i d e n t i c a l e i g e n v a l u e s w h o s e e i g e n v e c t o r s are d e s i r e d m a y be p e r t u r b e d s l i g h t l y in an a t t e m p t to o b t a i n i n d e p e n d e n t e i g e n v e c t o r s (if they e x i s t ) . If r e q u i r e d , such p e r t u r b a t i o n s are p o s i t i v e and s m a l l m u l t i p l e s of MACHEP*Z!B!!. This s u b r o u t i n e is a t r a n s l a t i o n of the A l g o l p r o c e d u r e INVIT w r i t t e n and d i s c u s s e d in d e t a i l by P e t e r s and W i l k i n s o n (i)°

4o

REFERENCES.

i)

5.

P e t e r s , G. and W i l k i n s o n , J.H., The C a l c u l a t i o n of S p e c i f i e d E i g e n v e c t o r s by I n v e r s e I t e r a t i o n , H a n d b o o k A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , J. H. W i l k i n s o n - C, R e i n s c h , C o n t r i b u t i o n II/18, 418-439, Springer-Verlag, 1971.

for

CHECKOUT. A.

Test

Cases.

See the s e c t i o n d i s c u s s i n g real general matrices.

testing

of

the

codes

for

B° A c c u r a c y . T h e a c c u r a c y of INVIT can b e s t be d e s c r i b e d in terms of its r o l e in t h o s e p a t h s of EISPACK w h i c h find e i g e n v a l u e s and e i g e n v e c t o r s of real u p p e r H e s s e n b e r g matrices. In these paths, this s u b r o u t i n e is n u m e r i c a l l y s t a b l e (i)o This s t a b i l i t y c o n t r i b u t e s to the p r o p e r t y of t h e s e p a t h s that each c o m p u t e d e i g e n v a l u e and its c o r r e s p o n d i n g e i g e n v e c t o r are e x a c t for a m a t r i x c l o s e to the o r i g i n a l u p p e r H e s s e n b e r g matrix.

394

7.1-200

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

=

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

?

IERR = 0 UK = 0 S = i **********

C C C

IP N1

= 0 = N -

IP

=

0, i, -i,

REAL EIGENVALUE FIRST OF C O N J U G A T E S E C O N D OF C O N J U G A T E

120

140

9 8 0 K : i, N IF ( W I ( K ) .EQ. 0 . 0 .OR. IP .LT. 0) GO T O i00 IP = i IF ( S E L E C T ( K ) .AND. SELECT(K+I)) SELECT(K+1) = .FALSE. IF ( . N O T . SELECT(K)) GO T O 9 6 0 IF ( W I ( K ) .RE. 0 . 0 ) S = S + I IF (S .GT. M M ) GO TO i 0 0 0 IF (UK .GE. K) G O T O 2 0 0 ********** CHECK FOR POSSIBLE SPLITTING ********** DO 120 U K = K, N IF (UK .EQ. N) G O T O 140 IF ( A ( U K + I , U K ) .EQ. 0 . 0 ) GO TO 140 CONTINUE ********** COMPUTE INFINITY N O R M OF L E A D I N G UK BY UK [HESSENBERG) MATRIX ********** NORM = 0.0 MP = 1 DO

160

180

**********

1

DO

i00

COMPLEX PAIR COMPLEX PAIR

180 1 = X=0.0

i,

UK

DO 160 J = MP, U K X = X + ABS(A(I,J)) IF (X .GT. MP = I CONTINUE

NORM)

NORM

= X

395

7.1-201

**********

200

C C 220 240

260

EPS3 REPLACES ZERO PIVOT IN DECOMPOSITION AND CLOSE ROOTS ARE MODIFIED BY EPS3 ********** IF ( N O R M . E Q . 0 . 0 ) N O R M = i ° 0 EPS3 = MACHEP * NORM ********** GROWTO IS T H E C R I T E R I O N FOR THE GROWTH ********** UKROOT = SQRT(FLOAT(UK)) GROWTO = 1.0E-I / UKROOT RLAMBD = WR(K) ILAMBD = WI(K) IF (K .EQ. i) G O T O 2 8 0 KMI = K - I GO TO 240 ********** PERTURB EIGENVALUE IF I T I S C L O S E TO ANY PREVIOUS EIGENVALUE ********** RLAMBD = RLAMBD + EPS3 ********** FOR I=K-I STEP -i UNTIL 1 DO -- ********** D O 2 6 0 I I = i, K M I I = K - II IF ( S E L E C T ( l ) .AND. ABS(WR(1)-RLAMBD) .LT. E P S 3 .AND. ABS(WI(1)-ILAMBD) .LT. E P S 3 ) G O T O 2 2 0 X CONTINUE

C WR(K) = ********** IPI = K WR(IPI) **********

C

C C 280

MP

=

DO

320

RLAMBD PERTURB CONJUGATE EIGENVALUE TO MATCH ********** + IP = RLAMBD FORM UPPER HESSENBERG A-RLAMBD*I (TRANSPOSED) AND INITIAL REAL VECTOR **********

!

C I =

I,

UK

C DO 300 RMI(J,I)

320

MP, UK = A(I,J)

J

=

RMI(I,I) MP = I RVI(1) = CONTINUE

=

300

RMI(I,I)

- RLAMBD

EPS3

ITS = 0 IF ( I L A M B D .NE. 0 . 0 ) G O T O 5 2 0 ********** REAL EIGENVALUE. TRIANGULAR DECOMPOSITION REPLACING ZERO PIVOTS BY I F ( U K ~EQ. i) G O T O 4 2 0 DO

4 0 0 I = 2, U K MP = I m 1 IF (ABS(RMI(MP,

I))

.LE.

396

WITH EPS3

INTERCHANGES, **********

ABS(RMI(MP,MP)))

GO

TO

360

7.1-202

DO

3 4 0 J = MP, U K Y = RMI(J,I) RMI(J,I) = RMI(J,MP) RMI(J,MP) = Y CONTINUE

340 360

IF ( R M I ( M P , M P ) .EQ. 0 . 0 ) R M I ( M P , M P ) X = RMI(MP,I) / RMI(MP,MP) IF (X .EQ. 0 . 0 ) G O T O 4 0 0 DO 380 RMI(J,I)

380 400 420

440

520

=

=

I, UK RMI(J,I)

- X

EPS3

* RMI(J,MP)

CONTINUE IF ( R M I ( U K , U K ) .EQ. 0 . 0 ) R M I ( U K , U K ) = EPS3 ********** BACK SUBSTITUTION FOR REAL VECTOR F O R I = U K S T E P -i U N T I L 1 D O -- * * * * * * * * * * D O 5 0 0 II = i, U K I = U K + 1 - II Y = R V I (I) IF (I .EQ. UK) G O T O 4 8 0 IPI = I + 1 DO 460 J = IPI, Y = Y - RMI(J,I)

460 480 500

J

=

RVI(1) CONTINUE

= Y

UK * RVI(J)

/ RMI(I,I)

GO TO 7 4 0 ********** COMPLEX EIGENVALUE. TRIANGULAR DECOMPOSITION WITH INTERCHANGES, REPLACING ZERO PIVOTS BY E P S 3 . STORE IMAGINARY PARTS IN U P P E R T R I A N G L E STARTING AT (1,3) ********** NS = N - S Z(I,S-I) = -ILAMBD Z(I,S) = 0.0 IF (N .EQ. 2) GO T O 5 5 0 RMI(I,3) = -ILAMBD Z(I,S-I) = 0.0 IF (N .EQ. 3) G O T O 5 5 0

540

DO 540 I = RMI(I,I) =

550

DO

4, N 0.0

6 4 0 I = 2, U K MP = I - I W = RMI(MP,I) IF (I .LT. N) T = R M I ( M P , I+I) IF (I .EQ. N) T = E ( M P , S - I ) X = RMI(MP,MP) * RMI(MP,MP) + IF (W * W .LE. X) G O T O 5 8 0

397

T

* T

7. 1 - 2 0 3

X = RMI(MP,MP) / W Y = T / W RMI(MP,MP) = W IF (I . L T . N) R M I ( M P , I + I ) = 0.0 I F (I .EQ. N) Z ( M P , S - I ) = 0.0 DO

555 560

570

580

600

5 6 0 J = !, U K W = RMI(J,I) RMI(J,I) = RMI(J,MP) - X RMI(J,MP) = W I F (J .LT. N I ) G O T O 5 5 5 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) RMI(MP,J+2) = 0.0 CONTINUE

615 620

- Y

* W

RMI(I,!) = RMI(I,I) - Y * ILAMBD IF (I oLT. N I ) G O T O 5 7 0 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 ) G O T O 6 0 0 RMI(MP,MP) = EPS3 IF (I . L T . N) R M I ( M P , I + I ) = 0.0 I F (I .EQ. N) Z ( M P , S - I ) = 0.0 T = 0.0 X = EPS3 * EPS3 w = w / x X = RMI(MP,MP) * W Y = -T * W DO

610

* W

620 J IF (J

= I, U K .LT. N I ) G O T O 6 1 0 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) CONTINUE

398

+ Y

* T

7.1-204

IF

.LT. N I ) G O T O 6 3 0 NS Z(I,L) = Z(I,L) - ILAMBD GO TO 640 RMI(I,I+2) = RMI(I,I+2) CONTINUE L

630 640

650 655 C C 660

(I

=

I

-

ILAMBD

I F ( U K .LT. N I ) GO T O 6 5 0 L = UK - NS T = Z (UK, L) GO TO 655 T = RMI(UK,UK+2) IF (RMI(UK,UK) .EQ. 0 . 0 . A N D . T .EQ. 0 . 0 ) R M I ( U K , U K ) ********** BACK SUBSTITUTION FOR COMPLEX VECTOR F O R I = U K S T E P -I U N T I L 1 DO -- ********** D O 7 2 0 II = i, U K I = U K + i - II X = R V I (I) Y = 0.0 IF (I .EQ. U K ) G O T O 7 0 0 IPI = I + i DO

680 J = IPI, UK IF (J .LT. N I ) G O T O 6 7 0 L = J NS T = Z(I,L) GO TO 675 T = RMI(I,J+2) X = X - RMI(J,I) * RVI(J) Y = Y - RMI(J,I) * RV2(J) CONTINUE

670 675 680 700

IF (I .LT. N t ) L = I - NS T = Z(I,L) GO TO 715 T = RMI(I,I+2)

710

715

720

740

z3

= CMPLX(X,Y)

GO

TO

* RV2(J) * RVI(J)

710

/ CMPLX(RMI(I,I),T)

RVI(I) = REAL(Z3) RV2(I) = AIMAG(Z3) CONTINUE ********** ACCEPTANCE TEST EIGENVECTOR AND ITS = ITS + 1 NORM = 0.0 NORMV = 0.0 DO

+ T - T

FOR REAL OR COMPLEX NORMALIZATION **********

7 8 O I = i, U K IF ( I L A M B D .EQo 0 . 0 ) X = ABS(RVI(I)) IF ( I L A M B D .NE. 0 . 0 ) X = C A B S ( C M P L X ( R V I ( I ) , R V 2 ( I ) ) ) IF ( N O R M V .GE. X) G O T O 7 6 0 N O R M V -- X J = I

399

=

EPS3

7.1-205

760 780

NORM CONTINUE

= NORM

+

X

C IF (NORM ,LT. G R O W T O ) GO TO 840 ********** ACCEPT VECTOR ********** X = RVI(J) IF (ILAMBD .EQ. 0 . 0 ) X = 1 . 0 / X IF ( I L A M B D .NE. 0 . 0 ) Y = R V 2 ( J )

C

DO

8 2 0 ! = I~ U K IF ( I L A M B D .NE. 0 . 0 ) G O z(i,s) = RVI(I) * X GO TO 820 Z3 = C M P L X ( R V I ( 1 ) , R V 2 ( 1 ) ) Z(I,S-I) = REAL(Z3) Z(I,S) = AIMAG(Z3) CONTINUE

800

820

840

I F ( U K .EQ° N) G O T O 9 4 0 J = UK + I GO TO 900 ********** IN-LINE PROCEDURE FOR A NEW STARTING VECTOR IF ( I T S .GE. U K ) G O T O 8 8 0 X = UKROOT Y = E P S 3 1 (X + 1 . 0 ) RVI(1) = EPS3 DO 860 RVI(1)

860

880

900

920 940 960 980

TO

1 = = Y

2,

800

/ CMPLX(X,Y)

CHOOSING **********

UK

J = UK - ITS + i RVI(J) = RVI(J) - EPS3 * X IF (!LAMBD .EQ. 0 . 0 ) G O T O 4 4 0 GO TO 660 • ********* SET ERROR -- UNACCEPTED EIGENVECTOR J = ! I E R R = -K • ********* SET REMAINING VECTOR COMPONENTS TO D O 9 2 0 1 = J, N z(i,s) = o.o IF ( ! L A M B D .NE. 0 . 0 ) Z ( I , S - I ) = 0.0 CONTINUE S = S + 1 IF (ie .EQ. IF (IP ,EQ. CONTINUE GO

TO

(-i)) i) IP

Ie = = -i

0

i001

400

**********

ZERO

**********

7.1-206

C C

**********

SET ERROR -- UNDERESTIMATE SPACE REQUIRED ********** i000 IF (IERR . N E . 0) I E R R = IERR - N IF (IERR . E Q . 0) I E R R = - ( 2 * N + i) i001M = S - 1 - IABS(IP) RETURN END

401

OF

EIGENVECTOR

7.1-207

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F276-2

PACKAGE

(EISPACK)

ORTBAK

A F o r t r a n IV S u b r o u t i n e to B a c k T r a n s f o r m the E i g e n v e c t o r s of that U p p e r H e s s e n b e r g M a t r i x D e t e r m i n e d by ORTHES.

May, July,

1972 1975

I. P U R P O S E ° The F o r t r a n IV s u b r o u t i n e ORTBAK forms the e i g e n v e c t o r s a real g e n e r a l m a t r i x f r o m the e i g e n v e c t o r s of that u p p e r H e s s e n b e r g m a t r i x d e t e r m i n e d by O R T H E S (F275).

of

2. U S A G E . A.

Calling The

Sequence°

SUBROUTINE SUBROUTINE

statement

is

O R T B A K ( N M , LOW, I G N , A , O R T , M , Z )

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

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

LOW,IGH

are i n t e g e r i n p u t v a r i a b l e s i n d i c a t i n g the b o u n d a r y i n d i c e s for the b a l a n c e d m a t r i x . See s e c t i o n 3 of F269 for the d e t a i l s . If the m a t r i x is n o t b a l a n c e d , set LOW to 1 and IGH to the order of the m a t r i x .

A

is a w o r k i n g p r e c i s i o n real i n p u t twod i m e n s i o n a l v a r i a b l e w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at l e a s t IGH. The s t r i c t l o w e r t r i a n g l e of A c o n t a i n s some i n f o r m a t i o n a b o u t the o r t h o g o n a !

402

7.1-208

t r a n s f o r m a t i o n s used in the r e d u c t i o n to the H e s s e n b e r g form. The r e m a i n i n g u p p e r part of the m a t r i x is a r b i t r a r y . See s e c t i o n 3 of F275 for the d e t a i l s . ORT

is a w o r k i n g p r e c i s i o n real o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t IGH. On input, ORT contains further information about the o r t h o g o n a l t r a n s f o r m a t i o n s u s e d in the r e d u c t i o n by ORTHES. See s e c t i o n 3 of F275 for the d e t a i l s . ORT is u s e d for temporary storage within ORTBAK and is not restored.

M

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

input v a r i a b l e c o l u m n s of Z

set e q u a l to to be b a c k

is a w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t M. On input, the f i r s t M c o l u m n s of Z c o n t a i n the real and i m a g i n a r y p a r t s of the e i g e n v e c t o r s to be back transformed. On o u t p u t , these M c o l u m n s of Z c o n t a i n the r e a l and i m a g i n a r y p a r t s of the t r a n s f o r m e d eigenvectors.

B.

Error

Conditions

and

Returns.

None.

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

and

Restrictions.

This s u b r o u t i n e s h o u l d be u s e d subroutine O R T H E S (F275).

in

conjunction

The r e a l and i m a g i n a r y parts of an e i g e n v e c t o r be s t o r e d in c o n s e c u t i v e c o l u m n s of Z.

3.

DISCUSSION

OF M E T H O D

AND

with

the

need

ALGORITHM.

S u p p o s e that the m a t r i x C (say) has b e e n upper Hessenberg form F s t o r e d in A by transformation

F = Q CQ

403

r e d u c e d to the the s i m i l a r i t y

not

7.1-209

where Q is a p r o d u c t of the o r t h o g o n a l m a t r i c e s e n c o d e d in ORT and in a l o w e r t r i a n g l e of A under F. Then, g i v e n an array Z of c o l u m n v e c t o r s , ORTBAK c o m p u t e s the m a t r i x product QZ. If the r e a l and i m a g i n a r y p a r t s of the e i g e n v e c t o r s of F are c o l u m n s of the a r r a y Z, then ORTBAK f o r m s the e i g e n v e c t o r s of C in t h e i r place. This subroutine ORTBAK written W i l k i n s o n (I).

4.

REFERENCES°

i)

5.

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

M a r t i n , R.S. and W i l k i n s o n , J.H., Similarity Reduction of a G e n e r a l M a t r i x to H e s s e n b e r g Form, Num. Math. 1 2 , 3 4 9 - 3 6 8 (1968). ( R e p r i n t e d in H a n d b o o k for A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , J. H. W i l k i n s o n - C. R e i n s c h , C o n t r i b u t i o n 11/13, 339-358, Springer-Verlag, 1971.)

CHECKOUT. Ao

Test

Cases.

See the s e c t i o n d i s c u s s i n g real general matrices.

testing

of

the

codes

for

Bo A c c u r a c y ~ The a c c u r a c y of ORTBAK can b e s t be d e s c r i b e d in terms of its r o l e in t h o s e p a t h s of EISPACK which find e i g e n v a l u e s and e i g e n v e c t o r s of r e a l g e n e r a l m a t r i c e s . In these p a t h s , this s u b r o u t i n e is n u m e r i c a l l y s t a b l e (I). This s t a b i l i t y c o n t r i b u t e s to the p r o p e r t y of t h e s e p a t h s that e a c h c o m p u t e d e i g e n v a l u e and its c o r r e s p o n d i n g e i g e n v e c t o r are e x a c t for a m a t r i x c l o s e to the o r i g i n a l m a t r i x .

404

7. 1 - 2 1 0

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 2 0 0 LA = IGH - 1 KPI = LOW + 1 IF (LA .LT. K P I ) G O TO 2 0 0 ********** FOR MP=IGH-I S T E P -I U N T I L DO 140 M M = K P I , L A MP = LOW + IGH - MM IF ( A ( M P , M P - I ) .EQ. 0 . 0 ) G O T O 1 4 0 MPI = MP + 1

i00

DO i00 ORT(1) DO

ii0

DO

--

**********

1 = MPI, IGH = A(I,MP-I)

130 J G=O.0

i,

=

M

DO i i 0 1 = MP, I G H G = G + ORT(1) * Z(I,J) • ********* DIVISOR BELOW IS N E G A T I V E OF H F O R M E D IN DOUBLE DIVISION AVOIDS POSSIBLE UNDERFLOW G = (G / O R T ( M P ) ) / A(MP,MP-I) DO 1 2 0 Z(l,J)

120 130

LOW+I

I

=

= MP, IGH Z(l,J) + G

* ORT(1)

CONTINUE

140

CONTINUE

200

RETURN END

405

ORTHES. **********

7.1-2!1

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F275

PACKAGE

(EISPACK)

ORTHES

A F o r t r a n IV S u b r o u t i n e to R e d u c e a Real G e n e r a l M a t r i x to Upper Hessenberg Form Using Orthogonal Transformations.

May,

1972

!. P U R P O S E . The F o r t r a n IV s u b r o u t i n e ORTHES r e d u c e s a real g e n e r a l m a t r i x to u p p e r H e s s e n b e r g f o r m u s i n g o r t h o g o n a l s i m i l a r i t y transformations. This r e d u c e d f o r m is u s e d by o t h e r s u b r o u t i n e s to find the e i g e n v a l u e s a n d / o r e i g e n v e c t o r s of the o r i g i n a l m a t r i x . See s e c t i o n 2C for the s p e c i f i c routines,

2. U S A G E . A,

Calling The

Sequence,

SUBROUTINE SUBROUTINE

statement

is

ORTHES(NM,N,LOW, IGH,A,ORT)

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

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

N

is an i n t e g e r i n p u t v a r i a b l e the o r d e r of the m a t r i x A. greater than NM.

LOW~IGH

are i n t e g e r i n p u t v a r i a b l e s i n d i c a t i n g the b o u n d a r y i n d i c e s for the b a l a n c e d m a t r i x . See s e c t i o n 3 of F269 for the d e t a i l s . If the m a t r i x is n o t b a l a n c e d , set LOW to 1 and !GH to N.

406

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

7.1-212

B.

Error

A

is a w o r k i n g p r e c i s i o n real t w o - d i m e n s i o n a l variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t N. On input, A c o n t a i n s the m a t r i x of o r d e r N to be r e d u c e d to H e s s e n b e r g form. On output, A c o n t a i n s the u p p e r H e s s e n b e r g m a t r i x as w e l l as some i n f o r m a t i o n about the o r t h o g o n a l t r a n s f o r m a t i o n s used in the r e d u c t i o n . See s e c t i o n 3 for the details.

0RT

is a w o r k i n g p r e c i s i o n real o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t IGH c o n t a i n i n g the r e m a i n i n g i n f o r m a t i o n about the o r t h o g o n a l t r a n s f o r m a t i o n s . See s e c t i o n 3 for the d e t a i l s . Only components LOW+I through IGH are a c t u a l l y used by ORTHES.

Conditions

and

Returns.

None.

C.

Applicability

and

Restrictions.

If all the e i g e n v a l u e s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e s h o u l d be f o l l o w e d by HQR (F286). If all the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e s h o u l d be f o l l o w e d by O R T R A N (F221) and H Q R 2 (F287). If some of the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e s h o u l d f o l l o w e d by H Q R (F286), INVIT (F288), and ORTBAK (F276) .

be

The subroutine ORTHES e x e c u t e s s l o w e r than its counterpart E L M H E S (F273), w h i c h uses e l e m e n t a r y similarity transformations. ORTHES is, h o w e v e r , m o r e a c c u r a t e in s o m e cases. It is r e c o m m e n d e d that ELMHES be used in g e n e r a l . If the m a t r i x has e l e m e n t s of w i d e l y v a r y i n g m a g n i t u d e s , the l a r g e r ones s h o u l d be in the top l e f t - h a n d corner.

407

7.1-213

3.

DISCUSSION Suppose

OF M E T H O D that

AND

ALGORITHM.

the m a t r i x

A

( T (0 (0

=

A

X B 0

has

the f o r m

Y ) Z) R)

where T and R are u p p e r t r i a n g u l a r m a t r i c e s , B is a s q u a r e m a t r i x s i t u a t e d in r o w s and c o l u m n s LOW through IGH, and X, Y, and Z are r e c t a n g u l a r m a t r i c e s of the appropriate dimensions. T h e n the s u b r o u t i n e ORTHES p e r f o r m s o r t h o g o n a l s i m i l a r i t y t r a n s f o r m a t i o n s to r e d u c e to H e s s e n b e r g form. The H e s s e n b e r g r e d u c t i o n is p e r f o r m e d in the f o l l o w i n g way. Starting with J = L O W , the e l e m e n t s in the J-th column below the d i a g o n a l are f i r s t s c a l e d , to a v o i d p o s s i b l e u n d e r f l o w in the t r a n s f o r m a t i o n that m i g h t r e s u l t in s e v e r e d e p a r t u r e f r o m orthogonality. The sum of s q u a r e s SIGMA of t h e s e s c a l e d e l e m e n t s is n e x t f o r m e d . Then, a v e c t o r U and a s c a l a r T

define

an

H

=

=

i-

U U/2

operator T p

uu

/H

w h i c h is o r t h o g o n a l and s y m m e t r i c and for w h i c h the similarity transformation PAP e l i m i n a t e s the e l e m e n t s the J-th c o l u m n of A b e l o w the s u b d i a g o n a l .

in

The n o n - z e r o c o m p o n e n t s of U are the e l e m e n t s of the J-th c o l u m n b e l o w the d i a g o n a l w i t h the f i r s t of t h e m a u g m e n t e d by the s q u a r e root of SIGMA p r e f i x e d by the s i g n of the subdiagonal element. By s a v i n g this c o m p o n e n t in the a r r a y ORT and not o v e r w r i t i n g the c o l u m n e l e m e n t s e l i m i n a t e d in the t r a n s f o r m a t i o n , f u l l i n f o r m a t i o n on ~ is s a v e d for l a t e r use in ORTRAN and ORTBAK. The t r a n s f o r m a t i o n r e p l a c e s the s u b d i a g o n a l e l e m e n t w i t h s q u a r e root of SIGMA p r e f i x e d by sign o p p o s i t e to that the r e p l a c e d e l e m e n t . The a b o v e steps are r e p e a t e d on f u r t h e r c o l u m n s of transformed A until B is r e d u c e d to H e s s e n b e r g is, r e p e a t e d for J = LOW+I,LOW+2,...,IGH-2. This s u b r o u t i n e ORTHES written W i l k i n s o n (i).

the form;

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

408

the of

that

7. 1-214

4. R E F E R E N C E S .

l)

M a r t i n , R.S. and W i l k i n s o n , J.H., Similarity Reduction of a G e n e r a l M a t r i x to H e s s e n b e r g Form, Num. Math. 1 2 , 3 4 9 - 3 6 8 (1968). ( R e p r i n t e d in H a n d b o o k for A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , J. H. W i l k i n s o n - C. R e i n s c h , C o n t r i b u t i o n 11/13, 339-358, Springer-Verlag, 1971.)

5. C H E C K O U T . A.

Test

Cases.

See the s e c t i o n d i s c u s s i n g real general matrices.

testing

of

the

codes

for

B. A c c u r a c y . The a c c u r a c y of ORTHES can b e s t be d e s c r i b e d in terms of its role in those paths of EISPACK w h i c h find e i g e n v a l u e s and e i g e n v e c t o r s of real g e n e r a l m a t r i c e s . In these paths, this s u b r o u t i n e is n u m e r i c a l l y s t a b l e (I). This s t a b i l i t y c o n t r i b u t e s to the p r o p e r t y of these paths that each c o m p u t e d e i g e n v a l u e and its c o r r e s p o n d i n g e i g e n v e c t o r are exact for a m a t r i x hlose to the o r i g i n a l matrix.

409

7.1-215

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 ( L A oLT. K P I )

GO

TO

200

DO

90

180 M = KPI, LA H = 0.0 ORT(M) = 0.0 SCALE = 0.0 ********** SCALE COLUMN (ALGOL D O 90 I = M, I G H SCALE = SCALE + ABS(A(I,M-I))

TOL

THEN

NOT

NEEDED)

M

--

**********

I00

IF ( S C A L E .EQ. 0.0) GO TO 180 MP = M + IGH ********** FOR I=IGH S T E P -i U N T I L D O i 0 0 II = M, I G H ! = MP - II ORT(1) = A(I,M-I) / SCALE H = H + ORT(1) * ORT(1) CONTINUE

ii0

G = -SIGN(SQRT(H),ORT(M)) H = H - ORT(M) * G O R r (M) = ORT (M) - G • ********* FORM (I-(U*UT)/H) * A ********** D O 1 3 0 J = M, N F = 0.0 • ********* FOR I=IGH STEP -I UNTIL M DO -D O I i 0 II = M ~ I G H I = MP II F = F + ORr(1) * A(I,J) CONTINUE

DO

**********

**********

C F

=

F

/ H

C 120 130

140

DO 120 A(I,J)

! = M, I G H = A(I,J) -

F

*

ORT(1)

CONTINUE ********** FORM (I-(U*UT)/H)*A*(I-(U*UT)/H) D O 1 6 0 I = I, I G H 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

180 200

F

DO 150 A(I,J)

150 160

=

/ H J =

= M, I G H A(I,J) -

F

*

CONTINUE ORT(M) = A(M,M-I) CONTINUE

SCALE * = SCALE

ORT(M) * G

RETURN END

411

ORT(J)

7.1-217

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F221-2

PACKAGE

(EISPACK)

ORTRAN

A F o r t r a n IV S u b r o u t i n e to A c c u m u l a t e the T r a n s f o r m a t i o n s in the R e d u c t i o n of a R e a l G e n e r a l M a t r i x by ORTHES.

May, July,

1972 1975

I. P U R P O S E . The F o r t r a n IV s u b r o u t i n e ORTRAN a c c u m u l a t e s the o r t h o g o n a l s i m i l a r i t y t r a n s f o r m a t i o n s u s e d in the r e d u c t i o n of a r e a l g e n e r a l m a t r i x to u p p e r H e s s e n b e r g f o r m by O R T H E S (F275).

2. U S A G E . A.

Calling The

Sequence°

SUBROUTINE SUBROUTINE

statement

is

ORTRAN(NM,N,LOW, IGH,A,ORT,Z)

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

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

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

LOW, IGH are i n t e g e r i n p u t v a r i a b l e s i n d i c a t i n g the b o u n d a r y i n d i c e s for the b a l a n c e d m a t r i x . See s e c t i o n 3 of F269 for the d e t a i l s . If the m a t r i x is not b a l a n c e d , set LOW to 1 and IGH to N.

412

7.1-218

A

is a w o r k i n g p r e c i s i o n r e a l i n p u t twodimensional variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t IGH. The s t r i c t lower t r i a n g l e of A c o n t a i n s some i n f o r m a t i o n about the o r t h o g o n a l t r a n s f o r m a t i o n s used in the r e d u c t i o n to the H e s s e n b e r g form. The r e m a i n i n g u p p e r p a r t of the m a t r i x is a r b i t r a r y . See s e c t i o n 3 of F275 for the details.

ORT

is a w o r k i n g p r e c i s i o n r e a l o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t IGH. On input, ORT contains further information a b o u t the o r t h o g o n a l t r a n s f o r m a t i o n s u s e d in the r e d u c t i o n by ORTHES. See s e c t i o n 3 of F275 for the d e t a i l s . ORT is u s e d for temporary storage within ORTRAN and is not restored. is a w o r k i n g p r e c i s i o n r e a l o u t p u t twod i m e n s i o n a l v a r i a b l e w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at l e a s t N. It c o n t a i n s the t r a n s f o r m a t i o n m a t r i x p r o d u c e d in the r e d u c t i o n by ORTHES to the u p p e r H e s s e n b e r g form.

B.

Error

Conditions

and

Returns.

None.

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

and

Restrictions.

If all the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e f o l l o w s ORTHES (F275) and s h o u l d be f o l l o w e d by HQR2 (F287). O t h e r w i s e , this s u b r o u t i n e w i l l not o r d i n a r i l y be used.

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

OF M E T H O D

AND

ALGORITHM.

S u p p o s e that the m a t r i x C (say) has b e e n r e d u c e d to the upper Hessenberg form F s t o r e d in A by the s i m i l a r i t y transformation T

F = Q CQ where Q is a p r o d u c t of the o r t h o g o n a l m a t r i c e s e n c o d e d in ORT and in a l o w e r t r i a n g l e of A under F. Then, ORTRAN accumulates Q into the a r r a y Z.

413

7.1-219

This s u b r o u t i n e is a t r a n s l a t i o n of the A l g o l p r o c e d u r e ORTRANS w r i t t e n and d i s c u s s e d in d e t a i l by P e t e r s and W i l k i n s o n (i).

4. R E F E R E N C E S .

l)

P e t e r s ~ G. and W i l k i n s o n , J.H., E i g e n v e c t o r s of Real C o m p l e x M a t r i c e s by LR and QR T r i a n g u l a r i z a t i o n s , Numo Math. 1 6 , 1 8 1 - 2 0 4 (1970). ( R e p r i n t e d in H a n d b o o k A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , J. H. W i l k i n s o n - C. R e i n s c h , C o n t r i b u t i o n 11/15, 372-395, S p r i n g e r - V e r l a g , 1971.)

and for

5. C H E C K O U T . A.

Test

Cases~

See the s e c t i o n d i s c u s s i n g real general matrices.

testing

of

the

codes

for

B. A c c u r a c y . The a c c u r a c y of ORTRAN can b e s t be d e s c r i b e d in terms of its role in those p a t h s of EISPACK w h i c h find e i g e n v a l u e s and e i g e n v e c t o r s of real g e n e r a l m a t r i c e s . In these paths, this s u b r o u t i n e is n u m e r i c a l l y stable (i). This s t a b i l i t y c o n t r i b u t e s to the p r o p e r t y of these p a t h s that each c o m p u t e d e i g e n v a l u e and its corresponding e i g e n v e c t o r are exact for a m a t r i x close to the o r i g i n a l m a t r i x .

414

7.1-220

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 **~******* DO 80 I =

60

80

INITIALIZE i~ N

DO 60 J = i, Z(l,J) = 0.0 z(I,I) CONTINUE

:

Z TO

IDENTITY

MATRIX

N

1.0

KL = IGH - LOW - 1 IF (EL .LT. I) GO TO 2 0 0 ***me***** FOR MP=IGH-I S T E P -i U N T I L D O 140 M M = i, K L M P = IGH MM IF ( A ( M P , M P - I ) .EQ. 0 . 0 ) G O TO 1 4 0 MPI = MP + i

I00

DO i00 ORT(1) DO

ii0

LOW+I

DO

--

**********

I = MPI, IGH = A(I,MP-I)

130 J G=0.0

= MP,

IGH

DO II0 I = MP, IGH G = G + ORT(1) * Z(I,J) • ********* DIVISOR BELOW IS N E G A T I V E OF H F O R M E D IN DOUBLE DIVISION AVOIDS POSSIBLE UNDERFLOW g = (G / O R T ( M P ) ) / A(MP,MP-I) DO 120 Z(I,J)

120 130

***~******

I = MP, IGH = Z(l,J) + G

* ORT(1)

CONTINUE

140

CONTINUE

200

RETURN END

415

ORTHES. *********~

7. 1-221

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F298-2

PACKAGE

(EISPACK)

RATQR

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

May, July,

1972 1975

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e RATQR d e t e r m i n e s the a l g e b r a i c a l l y s m a l l e s t or l a r g e s t e i g e n v a l u e s of a s y m m e t r i c t r i d i a g o n a l m a t r i x u s i n g the r a t i o n a l QR method with Newton corrections.

2. USAGE. Ao

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

RATQR(N~EPSI,D,E,E2, M,W, I N D , B D , T Y P E , I D E F , I E R R )

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

set

equal

to

is a w o r k i n g p r e c i s i o n r e a l v a r i a b l e . On input, EPSI s p e c i f i e s a t o l e r a n c e for the t h e o r e t i c a l a b s o l u t e e r r o r of the c o m p u t e d eigenva!ues. If MACHEP d e n o t e s the r e l a t i v e m a c h i n e p r e c i s i o n , then if the input EPSI is less t h a n MACHEP times the m a g n i t u d e of any of the c o m p u t e d e i g e n v a l u e s , it is r e s e t to a d e f a u l t v a l u e d e s c r i b e d in s e c t i o n 3. The t h e o r e t i c a l a b s o l u t e e r r o r in the K-th e i g e n v a l u e is u s u a l l y not g r e a t e r than K times the output EPSI.

416

7.1-222

is a w o r k i n g p r e c i s i o n r e a l i n p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g the d i a g o n a l e l e m e n t s of the symmetric tridiagonal matrix. is a w o r k i n g p r e c i s i o n r e a l i n p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g , in its last N-I positions, the s u b d i a g o n a l e l e m e n t s of the s y m m e t r i c tridiagonal matrix. E(1) is a r b i t r a r y . E2

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

M

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to the n u m b e r of e x t r e m e e i g e n v a l u e s d e s i r e d .

W

is a w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g the M e x t r e m e e i g e n v a l u e s of the s y m m e t r i c t r i d i a g o n a l m a t r i x . If the s m a l l e s t e i g e n v a l u e s h a v e b e e n found, they are in a s c e n d i n g o r d e r in W. If the l a r g e s t e i g e n v a l u e s h a v e b e e n found, they are in d e s c e n d i n g order in W. W n e e d not be d i s t i n c t f r o m D.

IND

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

BD

is a w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N. BD(K) is a t i g h t e r b o u n d than K*EPSI for the t h e o r e t i c a l e r r o r of the K-th eigenvalue W(K), K = 1,2,...,M. BD need not be d i s t i n c t f r o m E2.

417

7.1-223

B.

Error

TYPE

is a l o g i c a l i n p u t v a r i a b l e set true s m a l l e s t e i g e n v a l u e s are to be f o u n d f a l s e if the l a r g e s t e i g e n v a l u e s are found.

IDEF

is an i n t e g e r i n p u t v a r i a b l e set to 1 if the s y m m e t r i c t r i d i a g o n a l m a t r i x is k n o w n to be p o s i t i v e d e f i n i t e , set to -i if the m a t r i x is k n o w n to be n e g a t i v e d e f i n i t e , and set to 0 otherwise.

IERR

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

Conditions

and

if the and set to be

to is

Returns.

If IDEF is set to 1 and TYPE is set true w h e n the i n p u t m a t r i x is n o t p o s i t i v e d e f i n i t e , or if IDEF is set to -i and TYPE is set f a l s e w h e n the m a t r i x is not n e g a t i v e d e f i n i t e , RATQR terminates with IERR set to 6*N+I. No e i g e n v a l u e s are c o m p u t e d . Note: this e r r o r r e t u r n may a l s o be m a d e if M has b e e n i n a d v e r t e n t l y s p e c i f i e d g r e a t e r than N. If s u c c e s s i v e i t e r a t e s to the K-th e i g e n v a l u e are not strictly monotone increasing, RATQR t e r m i n a t e s the c a l c u l a t i o n for that e i g e n v a l u e w i t h IERR set to 5*N+K. The sum of all the s h i f t s up to this p o i n t is t a k e n as the e i g e n v a l u e and the p r o g r a m p r o c e e d s to the next eigenvalue calculation. If this f a i l u r e o c c u r s for m o r e t h a n one e i g e n v a l u e , the l a s t o c c u r r e n c e is r e c o r d e d in IERR. If n e i t h e r of the is set to zero.

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

and

above

error

conditions

occurs,

IERR

Restrictions.

To d e t e r m i n e e x t r e m e e i g e n v a l u e s of a f u l l s y m m e t r i c matrix, RATQR s h o u l d be p r e c e d e d by T R E D I (F277) p r o v i d e a s u i t a b l e s y m m e t r i c t r i d i a g o n a l m a t r i x for RATQR.

to

To d e t e r m i n e e x t r e m e e i g e n v a l u e s of a c o m p l e x H e r m i t i a n matrix, RATQR s h o u l d be p r e c e d e d by H T R I D I (F284) to p r o v i d e a s u i t a b l e r e a l s y m m e t r i c t r i d i a g o n a l m a t r i x for RATQR.

418

7.1-224

To d e t e r m i n e e x t r e m e e i g e n v a l u e s of c e r t a i n n o n symmetric tridiagonal matrices, RATQR s h o u l d be p r e c e d e d by F I G I (F280) to p r o v i d e a s u i t a b l e s y m m e t r i c t r i d i a g o n a l m a t r i x for RATQR. See F280 a d e s c r i p t i o n of this s p e c i a l class of m a t r i c e s .

for

To d e t e r m i n e e i g e n v e c t o r s a s s o c i a t e d w i t h the c o m p u t e d eigenvalues, RATQR s h o u l d be f o l l o w e d by TINVlT (F223) and the a p p r o p r i a t e b a c k t r a n s f o r m a t i o n s u b r o u t i n e -T R B A K I (F279) after TREDI, HTRIBK (F285) after H T R I D I , or B A K V E C (F281) after FIGI. The s u b r o u t i n e T R I D I B (F237) m o r e a c c u r a t e than RATQR if clustered.

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

OF M E T H O D

AND

is g e n e r a l l y f a s t e r the e i g e n v a l u e s are

and

ALGORITHM.

The e i g e n v a l u e s are d e t e r m i n e d by the r a t i o n a l QR method with Newton corrections. The e s s e n c e of this m e t h o d is a p r o c e s s w h e r e b y a s e q u e n c e of s y m m e t r i c t r i d i a g o n a l m a t r i c e s , u n i t a r i l y s i m i l a r to the o r i g i n a l s y m m e t r i c t r i d i a g o n a l m a t r i x w i t h s h i f t e d o r i g i n , is f o r m e d w h i c h c o n v e r g e s to a m a t r i x w i t h zero d i a g o n a l e l e m e n t s . The origin shifts using the N e w t o n step i m p r o v e the c o n v e r g e n c e r a t e of the s e q u e n c e . The a l g o r i t h m a p p l i e s to the d e t e r m i n a t i o n of the algebraically smallest eigenvalues. D is f i r s t c o p i e d into W and IDEF into v a r i a b l e JDEF. If TYPE is false, RATQR then r e v e r s e s the signs of the e l e m e n t s of W and negates JDEF. Next, the s u b d i a g o n a l e l e m e n t s are t e s t e d for n e g l i g i b i l i t y . If an e l e m e n t is c o n s i d e r e d n e g l i g i b l e , its s q u a r e is set to zero, and so the m a t r i x s p l i t s into a d i r e c t s u m of submatrices. T h e n if JDEF is not i or if JDEF is 1 and the G e r s c h g o r i n l o w e r b o u n d for the s m a l l e s t e i g e n v a l u e is p o s i t i v e , the o r i g i n is f i r s t s h i f t e d so that the G e r s c h g o r i n l o w e r b o u n d for the t r a n s l a t e d m a t r i x is zero. S t a r t i n g f r o m the n e w o r i g i n , two QR d e c o m p o s i t i o n s are p e r f o r m e d p r o v i d i n g w i t h a d d i t i o n a l c a l c u l a t i o n s the N e w t o n step by w h i c h the o r i g i n is a g a i n s h i f t e d . This p r o c e s s is r e p e a t e d u n t i l a d i a g o n a l e l e m e n t of one of the i n t e r m e d i a t e matrices becomes negligible. T h e n the sum of the o r i g i n s h i f t s is t a k e n as an e i g e n v a l u e , the m a t r i x is d e f l a t e d by d e l e t i n g the row and c o l u m n w i t h the n e g l i g i b l e d i a g o n a l e l e m e n t (the l o c a t i o n of this row s e r v e s to i d e n t i f y the s u b m a t r i x to w h i c h the e i g e n v a l u e b e l o n g s ) , a n d the c o m p l e t e p r o c e s s is r e p e a t e d on the d e f l a t e d m a t r i x .

419

7.1-225

If at any s t a g e MACHEP times the a b s o l u t e s u m of the o r i g i n shifts exceeds EPSI, EPSI is r e s e t to this q u a n t i t y . A d i a g o n a l e l e m e n t is c o n s i d e r e d n e g l i g i b l e if it is no g r e a t e r than the c u r r e n t EPSI. At e a c h i t e r a t i o n , n e g l i g i b l e s q u a r e d s u b d i a g o n a l e l e m e n t s ( e a r l i e r c o p i e d into BD) are set to zero to a v o i d u n d e r f l o w s w h i c h w o u l d o t h e r w i s e occur. The a l g o r i t h m a s s u m e s a f t e r the i n i t i a l o r i g i n s h i f t that the m a t r i x is p o s i t i v e d e f i n i t e , and so can e x p e c t d i a g o n a l e l e m e n t s of c e r t a i n i n t e r m e d i a t e m a t r i c e s to be p o s i t i v e . If any of t h e s e are n e g a t i v e , then !ERR is f l a g g e d i n d i c a t i n g that !DEF was set e r r o n e o u s l y . A l s o , b e c a u s e the m a t r i x is p o s i t i v e d e f i n i t e , the s u m of the o r i g i n s h i f t s m u s t increase. If the sum does not i n c r e a s e , this is c o n s i d e r e d an i r r e g u l a r end of i t e r a t i o n and IERR is f l a g g e d . In this case, the c u r r e n t s u m of the o r i g i n s h i f t s is t a k e n as an e i g e n v a l u e , and the m a t r i x is d e f l a t e d by d e l e t i n g the r o w and c o l u m n c o r r e s p o n d i n g to the s m a l l e s t d i a g o n a l element. F i n a l l y , if TYPE of the e l e m e n t s of

is false, W.

RATQR

again

reverses

the s i g n s

This s u b r o u t i n e is a t r a n s l a t i o n of the A l g o l p r o c e d u r e RATQR w r i t t e n and d i s c u s s e d in d e t a i l by R e i n s c h and B a u e r (i).

4.

REFERENCES°

i)

5.

R e i n s c h , C. and Bauer, F.L., R a t i o n a l QR T r a n s f o r m a t i o n W i t h N e w t o n S h i f t for S y m m e t r i c T r i d i a g o n a l M a t r i c e s , Num. Math. 1 1 , 2 6 4 - 2 7 2 (1968). ( R e p r i n t e d in H a n d b o o k for A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , J. H. W i l k i n s o n - C. R e i n s c h , C o n t r i b u t i o n 11/6, 2 5 7 - 2 6 5 , Springer-Verlag, 1971.)

CHECKOUT. A~

Test

Cases~

See the s e c t i o n d i s c u s s i n g t e s t i n g of the codes for c o m p l e x H e r m i t i a n , r e a l s y m m e t r i c , real s y m m e t r i c t r i d i a g o n a l , and c e r t a i n real n o n - s y m m e t r i c tridiagonal matrices.

420

7.1-226

B. A c c u r a c y . The s u b r o u t i n e RATQR is n u m e r i c a l l y s t a b l e w h e n l i m i t e d to the c o m p u t a t i o n of a few e i g e n v a l u e s that are not t i g h t l y c l u s t e r e d (i); that is, the c o m p u t e d e i g e n v a l u e s are close to those of the o r i g i n a l matrix. In a d d i t i o n , they are the exact e i g e n v a l u e s of a m a t r i x close to the o r i g i n a l real s y m m e t r i c t r i d i a g o n a l 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 R E A L 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

=

MACHEP IS A THE RELATIVE

?

2O

IERR = 0 JDEF = IDEF ********** COPY D O 20 I = I, N W(I) = D(I)

40

IF ( T Y P E ) J = ! GO TO 400 ERR = 0.0 s

=

MACHINE DEPENDENT PARAMETER SPECIFYING PRECISION OF F L O A T I N G POINT ARITHMETIC.

GO

D ARRAY

TO

INTO

W

**********

40

o.o

**********

LOOK FOR SMALL SUB-DIAGONAL ENTRIES INITIAL SHIFT FROM LOWER GERSCHGORIN C O P Y E2 A R R A Y I N T O BD * * * * * * * * * *

AND DEFINE BOUND.

TOT = W(1) Q = 0.0 J = 0 DO

60 80

I00

i 0 0 1 = I, N P = Q IF (I .EQ. i) G O T O 60 IF (P °gr. M A C H E P * (ABS(D(1)) + E2(1) = 0.0 BD(1) = E2(1) • ********* C O U N T A L S O IF E L E M E N T OF IF ( E 2 ( 1 ) .EQ. 0 . 0 ) J = J + I lED(l) = J Q= 0,0 IF (I .RE. N) Q = A B S ( E ( I + I ) ) TOT = AMINI (W(1)-P-Q,TOT) CONTINUE IF

(JDEF

.EQ°

I

.AND.

II0

DO Ii0 1 = I, N W(1) = W(1) - TOT

140

GO TO TOT =

TOT

.LT.

160 0.0

422

0.0)

ABS(D(I-I))))

E2

HAS

GO

TO

GO

UNDERFLOWED

140

TO

80

**********

7.1-228

160 180

190

200 210

220

240 260

D O 3 6 0 K = i, M ********** NEXT QR TRANSFORMATION ********** TOT = TOT + S DELTA = W(N) - S I = N F = ABS(MACHEP*TOT) IF ( E P S I . L T . F) E P S I = F IF ( D E L T A .GT. EPSI) GO TO 190 IF ( D E L T A .LT. (-EPSI)) GO TO i000 GO TO 300 *~******** REPLACE SMALL SUB-DIAGONAL SQUARES BY ZERO TO REDUCE THE INCIDENCE OF U N D E R F L O W S *********e IF (K .EQ. N) G O T O 2 1 0 K1 = K + 1 DO 200 J = KI, N IF ( B D ( J ) .LE. (MACHEP*(W(J)+W(J-I))) ** 2) B D ( J ) = 0.0 CONTINUE F = BD(N) / DELTA QP = DELTA + F P = 1.0 IF (K .EQ. N) G O T O 2 6 0 K1 = N - K ~********~ FOR I=N-I STEP -I UNTIL K D O -D O 2 4 0 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 ( D E L T A .GT. E P S I ) GO TO 220 IF ( D E L T A .LT. (-EPSI)) GO TO i000 GO TO 300 F = BD(1) / Q QP = DELTA + F BD(I+I) = QP * E P CONTINUE

**********

W(K) = QP S = QP / P IF ( T O T + S . G T . T O T ) G O T O 1 8 0 **~******* 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 300

320 340

2 8 0 J = K, N IF ( W ( J ) ~GT. DELTA) GO TO 280 I = J DELTA = W(J) CONTINUE ********** CONVERGENCE ********** IF (I . L T . N) B D ( I + I ) = BD(1) * F II = I N D ( 1 ) IF (I o E Q . K) G O T O 3 4 0 KI = I - K **~******* FOR J=I-i STEP -i UNTIL K D O 3 2 0 J J = I, K1 J = I - JJ W(J+I) = W(J) - S BD(J+I) = BD(J) IND(J+I) = IND(J) CONTINUE

360

W(K) = TOT ERR = ERR + BD(K) = ERR IND(K) = II CONTINUE

400 5O0

IF ( T Y P E ) GO TO I001 F = BD(1) E2(1) = 2.0 BD(1) = F J = 2 ********** NEGATE ELEMENTS D O 5 0 0 1 = i, N W(1) : -W(1)

i000 i001

/ QP

DO

--

**********

ABS(DELTA)

JDEF = -JDEF GO TO (40,1001), J ********** SET ERROR IERR = 6 * N + 1 RETURN END

--

OF

IDEF

424

W

FOR

LARGEST

SPECIFIED

VALUES

INCORRECTLY

**********

***~******

7.1-230

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F303

A Fortran

PACKAGE

(EISPACK)

RG

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

July,

and

1975

I. P U R P O S E . The F o r t r a n IV s u b r o u t i n e RG calls the r e c o m m e n d e d s e q u e n c e of s u b r o u t i n e s f r o m the e i g e n s y s t e m s u b r o u t i n e p a c k a g e EISPACK to d e t e r m i n e the e i g e n v a l u e s and e i g e n v e c t o r s (if d e s i r e d ) of a real g e n e r a l m a t r i x .

2.

USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

RG(NM,N,A,WR,W!,MATZ,Z,IVI,FVI,IERR)

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

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

N

is an i n t e g e r i n p u t v a r i a b l e the o r d e r of the m a t r i x A. g r e a t e r than NM.

A

is a w o r k i n g p r e c i s i o n real t w o - d i m e n s i o n a l v a r i a b l e w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at least N. On input, A c o n t a i n s the real g e n e r a l m a t r i x of o r d e r N w h o s e e i g e n v a l u e s and e i g e n v e c t o r s are to be found. On o u t p u t , A has b e e n d e s t r o y e d .

425

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

7.1-231

WR,WI

are w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e s of d i m e n s i o n at l e a s t N c o n t a i n i n g the real and i m a g i n a r y p a r t s , r e s p e c t i v e l y , of the e i g e n v a l u e s of the r e a l general matrix. The e i g e n v a l u e s are u n o r d e r e d e x c e p t that c o m p l e x c o n j u g a t e p a i r s of e i g e n v a l u e s a p p e a r c o n s e c u t i v e l y w i t h the e i g e n v a l u e h a v i n g the p o s i t i v e i m a g i n a r y part first.

MATZ

is an i n t e g e r input v a r i a b l e set e q u a l to zero if only e i g e n v a l u e s are d e s i r e d ; o t h e r w i s e it is set to any n o n - z e r o i n t e g e r for b o t h e i g e n v a l u e s and e i g e n v e c t o r s . is, if MATZ is n o n - z e r o , a w o r k i n g precision real output two-dimensional variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t N c o n t a i n i n g the r e a l and i m a g i n a r y p a r t s of the e i g e n v e e t o r s . If the J-th e i g e n v a l u e is r e a l , the J-th c o l u m n of Z c o n t a i n s its e i g e n v e c t o r . If the J-th e i g e n v a l u e is c o m p l e x w i t h p o s i t i v e i m a g i n a r y part, the J-th and (J+l)-th c o l u m n s of Z c o n t a i n the r e a l and i m a g i n a r y p a r t s of its e i g e n v e c t o r . The c o n j u g a t e of this v e c t o r is the e i g e n v e c t o r for the c o n j u g a t e e i g e n v a l u e . The e i g e n v e c t o r s are not n o r m a l i z e d . If MATZ is zero, Z is not r e f e r e n c e d and can be a dummy variable.

IVl

is an i n t e g e r t e m p o r a r y o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N.

FVI

is a w o r k i n g p r e c i s i o n t e m p o r a r y oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N.

IERR

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

426

to is

7.1-232

B.

Error

Conditions

and

Returns.

If N is g r e a t e r t h a n NM, the with IERR set e q u a l to IO*N.

subroutine

If m o r e t h a n 30 iterations are required an e i g e n v a l u e , the s u b r o u t i n e terminates e q u a l to the i n d e x of the e i g e n v a l u e f o r failure occurs. The eigenvalues in the a r r a y s s h o u l d be c o r r e c t for i n d i c e s IERR+I,IERR+2,...,N, b u t no e i g e n v e c t o r s If a l l the e i g e n v a l u e s are determined iterations, IERR is set to zero.

C.

Applicability

and

terminates

to d e t e r m i n e with IERR set w h i c h the WR and WI are

within

computed. 30

Restrictions.

This subroutine can be u s e d to f i n d a l l the e i g e n v a l u e s and a l l the e i g e n v e c t o r s (if d e s i r e d ) of a r e a l g e n e r a l matrix.

3.

DISCUSSION This from real To

OF M E T H O D

AND

ALGORITHM.

s u b r o u t i n e c a l l s the r e c o m m e n d e d s e q u e n c e of s u b r o u t i n e s EISPACK to f i n d t h e e i g e n v a l u e s and eigenvectors of a general matrix.

f i n d e i g e n v a l u e s o n l y , the s e q u e n c e is the f o l l o w i n g . BALANC to b a l a n c e a r e a l g e n e r a l m a t r i x . E L M H E S - to r e d u c e the b a l a n c e d m a t r i x to an u p p e r Hessenberg matrix using elementary transformations. HQR - to d e t e r m i n e the e i g e n v a l u e s of the o r i g i n a l m a t r i x f r o m the H e s s e n b e r g m a t r i x . -

To f i n d e i g e n v a l u e s and e i g e n v e c t o r s , the s e q u e n c e is the following. BALANC to b a l a n c e a r e a l g e n e r a l m a t r i x . E L M H E S - to r e d u c e the b a l a n c e d m a t r i x to an u p p e r Hessenberg matrix using elementary transformations. E L T R A N - to a c c u m u l a t e t h e t r a n s f o r m a t i o n s f r o m the Hessenberg reduction. HQR2 to d e t e r m i n e the e i g e n v a l u e s and eigenvectors of the b a l a n c e d m a t r i x f r o m the H e s s e n b e r g matrix. B A L B A K - to b a c k t r a n s f o r m the e i g e n v e c t o r s to t h o s e of the o r i g i n a l m a t r i x . -

-

427

7. 1-233

4.

REFERENCES~ I)

5.

G a r b o w , B.S. A p r i l , 1974.

and

Dongarra,

J.J.,

EISPACK

Path

Chart,

CHECKOUT~ A.

Test

Cases~

See the s e c t i o n d i s c u s s i n g real general matrices. B.

testing

of

the

codes

for

Accuracy. T h e a c c u r a c y of RG can b e b e s t d e s c r i b e d in terms of its r o l e in t h o s e p a t h s of E I S P A C K (I) w h i c h find e i g e n v a l u e s and e i g e n v e c t o r s of r e a l g e n e r a l m a t r i c e s . In t h e s e p a t h s , this s u b r o u t i n e is, in p r a c t i c e , numerically stable. T h i s s t a b i l i t y c o n t r i b u t e s to the p r o p e r t y of t h e s e p a t h s that e a c h c o m p u t e d e i g e n v a l u e and its c o r r e s p o n d i n g e i g e n v e c t o r are e x a c t for a m a t r i x c l o s e to the o r i g i n a l m a t r i x .

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) I N T E G E R 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 E L M H E S ( N M , N , I S I , I S 2 , A , IVI) IF (MATZ .RE. 0) GO TO 20 * * * * * * * * * * FIND E I G E N V A L U E S ONLY * * * * * * * * * * CALL HQR(NM,N, ISI,IS2,A,WR,WI,IERR) GO TO 50 * * * * * * * * * * FIND BOTH E I G E N V A L U E S AND E I G E N V E C T O R S 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 R E T U R N END

429

7.1-235

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F304

A Fortran

(EISPACK)

RS

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

July,

i.

PACKAGE

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

and

1975

PURPOSE. The F o r t r a n IV s u b r o u t i n e RS c a l l s the r e c o m m e n d e d s e q u e n c e of s u b r o u t i n e s f r o m the e i g e n s y s t e m s u b r o u t i n e p a c k a g e EISPACK to d e t e r m i n e the e i g e n v a l u e s and e i g e n v e c t o r s (if d e s i r e d ) of a r e a l s y m m e t r i c m a t r i x .

2. U S A G E . A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

RS(NM,N,A,W,MATZ,Z,FVI,FV2,1ERR)

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

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

N

is an i n t e g e r i n p u t v a r i a b l e the o r d e r of the m a t r i x A. greater than NM.

A

is a w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l v a r i a b l e w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at l e a s t N. On i n p u t , A c o n t a i n s the r e a l s y m m e t r i c m a t r i x of o r d e r N w h o s e e i g e n v a l u e s and e i g e n v e c t o r s are to be f o u n d . O n l y the f u l l l o w e r t r i a n g l e of A n e e d be s u p p l i e d . On o u t p u t , the f u l l u p p e r t r i a n g l e of A is u n a l t e r e d .

430

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

7.1-236

W

is a w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g the e i g e n v a l u e s of the r e a l s y m m e t r i c m a t r i x in a s c e n d i n g order.

MATZ

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to zero if only e i g e n v a l u e s are d e s i r e d ; o t h e r w i s e it is set to any n o n - z e r o i n t e g e r for b o t h e i g e n v a l u e s and e i g e n v e c t o r s . is, if MATZ is n o n - z e r o , a w o r k i n g p r e c i s i o n real output t w o - d i m e n s i o n a l v a r i a b l e w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at l e a s t N c o n t a i n i n g the eigenvectors. The e i g e n v e c t o r s are orthonormal. If MATZ is zero, Z is not r e f e r e n c e d and can be a d u m m y v a r i a b l e .

FVI,FV2

are w o r k i n g dimensional

precision variables

temporary oneof d i m e n s i o n at

least

N.

IERR

B.

Error

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

Conditions

and

to is

Returns.

If N is g r e a t e r than NM, the with IERR set e q u a l to 10*N.

subroutine

terminates

If m o r e than 30 i t e r a t i o n s are r e q u i r e d to d e t e r m i n e an e i g e n v a l u e , the s u b r o u t i n e t e r m i n a t e s w i t h IERR set e q u a l to the i n d e x of the e i g e n v a l u e for w h i c h the failure occurs. The e i g e n v a l u e s and e i g e n v e c t o r s in the W and Z a r r a y s s h o u l d be c o r r e c t for i n d i c e s 1,2,...,IERR-I. If all the e i g e n v a l u e s are d e t e r m i n e d iterations, IERR is set to zero.

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

and

within

30

Restrictions.

This s u b r o u t i n e can be u s e d to f i n d all the e i g e n v a l u e s and all the e i g e n v e c t o r s (if d e s i r e d ) of a r e a l symmetric matrix.

4,31

7.1-237

3.

DISCUSSION This from real To

OF M E T H O D

AND

ALGORITHM.

s u b r o u t i n e calls the r e c o m m e n d e d s e q u e n c e of s u b r o u t i n e s EISPACK to f i n d the e i g e n v a l u e s a n d e i g e n v e c t o r s of a symmetric matrix.

find e i g e n v a l u e s only, the s e q u e n c e is the f o l l o w i n g . TREDI to r e d u c e a r e a l s y m m e t r i c m a t r i x to a symmetric tridiagonal matrix using orthogonal transformations. T Q L R A T - to d e t e r m i n e the e i g e n v a l u e s of the o r i g i n a l m a t r i x f r o m the s y m m e t r i c t r i d i a g o n a l m a t r i x . -

To find e i g e n v a l u e s and e i g e n v e c t o r s , the s e q u e n c e is the following. TRED2 to r e d u c e a r e a l s y m m e t r i c m a t r i x to a s y m m e t r i c t r i d i a g o n a l m a t r i x u s i n g and accumulating orthogonal transformations. TQL2 - to d e t e r m i n e the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x f r o m the s y m m e t r i c tridiagonal matrix. -

4,

REFERENCES. i)

5.

G a r b o w , B.S. A p r i l , 1974.

and

Dongarra~

J.J.,

EISPACK

Path

Chart,

CHECKOUT. A.

Test

Cases.

See the s e c t i o n d i s c u s s i n g real symmetric matrices. B.

testing

of

the

codes

for

Accuracy° T h e a c c u r a c y of RS can b e s t be d e s c r i b e d in terms of its r o l e in t h o s e p a t h s of E I S P A C K (i) which find e i g e n v a l u e s and e i g e n v e c t o r s of r e a l s y m m e t r i c m a t r i c e s . In t h e s e p a t h s , this s u b r o u t i n e is n u m e r i c a l l y stable. This s t a b i l i t y c o n t r i b u t e s to the p r o p e r t y of t h e s e p a t h s that the c o m p u t e d e i g e n v a l u e s are the e x a c t e i g e n v a l u e s of a m a t r i x c l o s e to the o r i g i n a l m a t r i x and the c o m p u t e d e i g e n v e c t o r s are c l o s e (but n o t n e c e s s a r i l y e q u a l ) to the e i g e n v e c t o r s of that m a t r i x .

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) I E R R = i0 * N GO TO 50

GO

TO

I0

I0 IF (MATZ .NE. 0) GO TO 20 * * * * * * * * * * F I N D E I G E N V A L U E S ONLY * * * * * * * * * * CALL TREDI(NM~N,A,W,FVI,FV2) CALL TQLRAT(N~W,FV2,1ERR) GO TO 50 ********** FIND BOTH EIGENVALUES AND EIGENVECTORS 20 C A L L TRED2(NM,N,A,W,FVI,Z) CALL TQL2(NM,N,W, FVI,Z,IERR) 50 R E T U R N END

433

7.1-239

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F307

A F o r t r a n IV D r i v e r S u b r o u t i n e E i g e n v e c t o r s of a R e a l

PACKAGE

(EISPACK)

RSP

to D e t e r m i n e the E i g e n v a l u e s Symmetric Packed Matrix.

July,

and

1975

I. P U R P O S E . The F o r t r a n IV s u b r o u t i n e RSP calls the r e c o m m e n d e d s e q u e n c e of s u b r o u t i n e s f r o m the e i g e n s y s t e m s u b r o u t i n e package EISPACK to d e t e r m i n e the e i g e n v a l u e s and e i g e n v e c t o r s (if d e s i r e d ) of a r e a l s y m m e t r i c p a c k e d m a t r i x .

2. U S A G E . A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

RSP(NM,N,NV,A,W,MATZ,Z,FVI,FV2,IERR)

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

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

N

is an i n t e g e r i n p u t v a r i a b l e the o r d e r of the m a t r i x A. greater than NM.

NV

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to the d i m e n s i o n of the a r r a y A as s p e c i f i e d in the D I M E N S I O N s t a t e m e n t for A in the calling program. NV m u s t not be less than N*(N+I)/2.

434

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

7.1-240

A

is a w o r k i n g p r e c i s i o n real o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t NV. On input, A c o n t a i n s the l o w e r t r i a n g l e , s t o r e d r o w - w i s e , of the r e a l s y m m e t r i c p a c k e d m a t r i x of o r d e r N whose eigenvalues and e i g e n v e c t o r s are to be found. For e x a m p l e if N=3, A should contain (A(I,I),A(2,1),A(2,2),A(3,1),A(3,2),A(3,3)) w h e r e the s u b s c r i p t s for e a c h e l e m e n t refer to the r o w and c o l u m n of the e l e m e n t in the standard two-dimensional representation. On output, A has b e e n d e s t r o y e d .

W

is a w o r k i n g p r e c i s i o n real o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N c o n t a i n i n g the e i g e n v a l u e s of the r e a l s y m m e t r i c p a c k e d m a t r i x in a s c e n d i n g order.

MATZ

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to zero if only e i g e n v a l u e s are d e s i r e d ; o t h e r w i s e it is set to any n o n - z e r o i n t e g e r for b o t h e i g e n v a l u e s and e i g e n v e c t o r s . is, if MATZ is n o n - z e r o , a w o r k i n g p r e c i s i o n real o u t p u t t w o - d i m e n s i o n a l v a r i a b l e w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at l e a s t N c o n t a i n i n g the eigenvectors. The e i g e n v e c t o r s are orthonormal. If MATZ is zero, Z is not r e f e r e n c e d and can be a d u m m y v a r i a b l e .

FVI,FV2

IERR

B.

Error

are w o r k i n g dimensional N.

precision variables

t e m p o r a r y oneof d i m e n s i o n at

least

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

Conditions

and

is

Returns.

If N is g r e a t e r than NM, the with IERR set equal to 10*N. If NV is less terminates with

to

than N*(N+I)/2, IERR set e q u a l

435

subroutine

the to

terminates

subroutine 20*N.

7.1-241

If m o r e than 30 i t e r a t i o n s are r e q u i r e d to d e t e r m i n e an e i g e n v a l u e , the s u b r o u t i n e t e r m i n a t e s w i t h IERR set e q u a l to the i n d e x of the e i g e n v a l u e for w h i c h the failure occurs. The e i g e n v a l u e s and e i g e n v e c t o r s in the W and Z a r r a y s s h o u l d be c o r r e c t for i n d i c e s 1,2,...,IERR-Io If all the e i g e n v a l u e s are d e t e r m i n e d iterations, IERR is set to zero.

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

and

within

30

Restrictions.

T h i s s u b r o u t i n e can be u s e d to find all the e i g e n v a l u e s and all the e i g e n v e c t o r s (if d e s i r e d ) of a r e a l symmetric packed matrix.

3.

DISCUSSION This from real To

OF M E T H O D

AND

ALGORITHM.

s u b r o u t i n e calls the r e c o m m e n d e d s e q u e n c e of s u b r o u t i n e s EISPACK to f i n d the e i g e n v a l u e s and e i g e n v e c t o r s of a symmetric packed matrix.

find e i g e n v a ! u e s only, the s e q u e n c e is the f o l l o w i n g . TRED3 to r e d u c e a r e a l s y m m e t r i c p a c k e d m a t r i x to a symmetric tridiagonal matrix using orthogonal transformations. T Q L R A T - to d e t e r m i n e the e i g e n v a l u e s of the o r i g i n a l m a t r i x f r o m the s y m m e t r i c t r i d i a g o n a l m a t r i x . -

To find e i g e n v a ! u e s and e i g e n v e c t o r s , the s e q u e n c e is the following. TRED3 - to r e d u c e a r e a l s y m m e t r i c p a c k e d m a t r i x to a symmetric tridiagonal matrix using orthogonal transformations. TQL2 to d e t e r m i n e the e i g e n v a l u e s and e i g e n v e c t o r s of the s y m m e t r i c t r i d i a g o n a l m a t r i x . TRBAK3 to b a c k t r a n s f o r m the e i g e n v e c t o r s to those of the o r i g i n a l m a t r i x . -

-

4.

REFERENCES. I)

5.

G a r b o w ~ B.S. A p r i l , 1974.

and

Dongarra,

J.J.,

EISPACK

Path

Chart,

CHECKOUT. A.

Test

Cases.

See the s e c t i o n d i s c u s s i n g t e s t i n g real symmetric packed matrices.

436

of

the

codes

for

7.1-242

B. A c c u r a c y . The a c c u r a c y of RSP can b e s t be d e s c r i b e d in terms of its role in those paths of E I S P A C K (i) w h i c h find e i g e n v a l u e s and e i g e n v e c t o r s of real s y m m e t r i c p a c k e d matrices. In these paths, this s u b r o u t i n e is n u m e r i c a l l y stable. This s t a b i l i t y c o n t r i b u t e s to the p r o p e r t y of these p a t h s that the c o m p u t e d e i g e n v a l u e s are the exact e i g e n v a l u e s of a m a t r i x close to the o r i g i n a l m a t r i x and the c o m p u t e d e i g e n v e c t o r s are close (but not n e c e s s a r i l y equal) to the e i g e n v e c t o r s of that matrix.

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 ! E R R = i0 * N GO TO 50 5 IF (NV .GE. (N * (N + i)) I E R R = 20 * N GO TO 50

/ 2)

GO

I0 C A L L TRED3(N,NV,A,W, FVI,FV2) IF ( M A T Z .NE. O) GO TO 20 ********** FIND EIGENVALUES ONLY CALL TQLRAT(N,W,FV2,1ERR) GO TO 50 ********** FIND BOTH EIGENVALUES 20 DO 40 I = i, N DO 30

40

50

30 J = i, N Z ( J , I ) = 0.0 CONTINUE

Z(I,I) CONTINUE

=

1.0

CALL TQL2(NM,N,W, FVI,Z,IERR) IF ( I E R R .NE. 0) GO TO 50 CALL TRBAK3(NM,N,NV,A,N,Z) RETURN END

438

TO

i0

**********

AND

EIGENVECTORS

**********

7.1-244

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F305

PACKAGE

(EISPACK)

RST

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

July,

and

1975

I. P U R P O S E . The F o r t r a n IV s u b r o u t i n e RST calls the r e c o m m e n d e d s e q u e n c e of s u b r o u t i n e s f r o m the e i g e n s y s t e m s u b r o u t i n e package EISPACK to d e t e r m i n e the e i g e n v a l u e s and eigenvectors (if d e s i r e d ) of a r e a l s y m m e t r i c t r i d i a g o n a l matrix.

2.

USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

RST(NM,N,W,E,MATZ,Z,IERR)

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

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

N

is an i n t e g e r i n p u t v a r i a b l e the o r d e r of the m a t r i x . N g r e a t e r than NM.

W

is a w o r k i n g p r e c i s i o n real o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N. On input, it c o n t a i n s the d i a g o n a l e l e m e n t s of the real s y m m e t r i c t r i d i a g o n a l m a t r i x . On o u t p u t , it c o n t a i n s the e i g e n v a l u e s of the m a t r i x in a s c e n d i n g order.

439

set e q u a l to m u s t not be

7.1-245

is a w o r k i n g p r e c i s i o n r e a l o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N. On i n p u t ~ it c o n t a i n s the s u b d i a g o n a l e l e m e n t s of the m a t r i x in its last N-I positions. E(1) is a r b i t r a r y . On o u t p u t , E has b e e n destroyed. MATZ

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to zero if o n l y e i g e n v a l u e s are d e s i r e d ; o t h e r w i s e it is set to any n o n - z e r o i n t e g e r for b o t h e i g e n v a l u e s a n d e i g e n v e c t o r s . is, if MATZ is n o n - z e r o , a w o r k i n g precision real output two-dimensional variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t N c o n t a i n i n g the eigenvectors. The e i g e n v e c t o r s a r e orthonormal. If MATZ is zero, Z is not r e f e r e n c e d and can be a d u m m y v a r i a b l e .

!ERR

B.

Error

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

Conditions

and

to is

Returns°

If N is g r e a t e r t h a n NM, the with IERR set e q u a l to IO*N.

subroutine

terminates

If m o r e t h a n 30 i t e r a t i o n s are r e q u i r e d to d e t e r m i n e an e i g e n v a l u e , the s u b r o u t i n e t e r m i n a t e s w i t h !ERR set e q u a l to the i n d e x of the e i g e n v a l u e for w h i c h the failure occurs. The e i g e n v a l u e s a n d e i g e n v e c t o r s in the W and Z a r r a y s s h o u l d be c o r r e c t for i n d i c e s 1,2,o~.,IERR-I. If all the e i g e n v a l u e s are d e t e r m i n e d iterations~ IERR is set to zero.

C,

Applicability

and

within

30

Restrictions°

This s u b r o u t i n e can be u s e d to find all the e i g e n v a l u e s and all the e i g e n v e c t o r s (if d e s i r e d ) of a r e a l symmetric tridiagonal matrix.

440

7.1-246

3. D I S C U S S I O N This from real To

OF M E T H O D

AND

ALGORITHM.

s u b r o u t i n e calls the r e c o m m e n d e d s e q u e n c e of s u b r o u t i n e s EISPACK to find the e i g e n v a l u e s a n d e i g e n v e c t o r s of a symmetric tridiagona! matrix.

find e i g e n v a l u e s only, the s e q u e n c e is the f o l l o w i n g . IMTQLI - to d e t e r m i n e the e i g e n v a l u e s of a real symmetric tridiagonal matrix.

To find e i g e n v a l u e s and e i g e n v e c t o r s , the s e q u e n c e is the following. I M T Q L 2 - to d e t e r m i n e the e i g e n v a l u e s and e i g e n v e c t o r s of a r e a l s y m m e t r i c t r i d i a g o n a l m a t r i x .

4.

REFERENCES. i)

5.

G a r b o w , B.S. A p r i l , 1974.

and D o n g a r r a ,

J°J.,

EISPACK

Path

Chart,

CHECKOUT. A.

Test

Cases.

See the s e c t i o n d i s c u s s i n g real symmetric tridiagonal

t e s t i n g of matrices.

the

codes

for

B. A c c u r a c y . The s u b r o u t i n e RST is n u m e r i c a l l y s t a b l e ; that is, the c o m p u t e d e i g e n v a l u e s are c l o s e to t h o s e of the o r i g i n a l matrix. In a d d i t i o n , they are the exact e i g e n v a l u e s of a m a t r i x c l o s e to the o r i g i n a l real s y m m e t r i c t r i d i a g o n a l m a t r i x and the c o m p u t e d e i g e n v e c t o r s are c l o s e (but not n e c e s s a r i l y equal) to the e i g e n v e c t o r s of that m a t r i x .

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) I E R R = i0 * N GO TO 50 i0

20

TO

i0

IF ( M A T Z .NE. 0) G O TO 20 ********** FIND EIGENVALUES ONLY CALL IMTQLI(N~W,E,IERR) GO TO 50 ********** FIND BOTH EIGENVALUES DO 40 I = I, N DO

30

J =

z(J,I)

30

GO

i, =

N 0o0

CONTINUE z(~,i)

=

i.o

40

CONTINUE

50

CALL IMTQL2(NM,N,W,E,Z,IERR) RETURN END

442

**********

AND

EIGENVECTORS

**********

7.1-248

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F306

PACKAGE

(EISPACK)

RT

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

July,

and

1975

i. P U R P O S E . T h e F o r t r a n IV s u b r o u t i n e RT c a l l s the r e c o m m e n d e d s e q u e n c e of s u b r o u t i n e s f r o m the e i g e n s y s t e m s u b r o u t i n e p a c k a g e EISPACK to d e t e r m i n e the e i g e n v a l u e s a n d e i g e n v e c t o r s (if d e s i r e d ) of a c e r t a i n r e a l t r i d i a g o n a l m a t r i x . The p r o p e r t y of the m a t r i x r e q u i r e d for u s e of this s u b r o u t i n e is that the p r o d u c t s of p a i r s of c o r r e s p o n d i n g o f f - d i a g o n a l e l e m e n t s be all n o n - n e g a t i v e , and f u r t h e r if e i g e n v e c t o r s are d e s i r e d , no p r o d u c t be zero u n l e s s b o t h f a c t o r s are zero.

2. U S A G E . A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

RT(NM~N~A,W,MATZ,Z~FVI,IERR)

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

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

443

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

7.1-249

is a w o r k i n g p r e c i s i o n r e a l i n p u t t w o dimensional variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t 3 containing the r e a l t r i d i a g o n a l m a t r i x of o r d e r N whose eigenvalues and eigenvectors a r e to be found. Its s u b d i a g o n a l e l e m e n t s are s t o r e d in the l a s t N-I p o s i t i o n s of the f i r s t c o l u m n , its d i a g o n a l e l e m e n t s a r e s t o r e d in the s e c o n d c o l u m n , and its s u p e r d i a g o n a l e l e m e n t s a r e s t o r e d in the f i r s t N-I positions of the t h i r d c o l u m n . Elements A(I,I) and A(N,3) are a r b i t r a r y . is a w o r k i n g p r e c i s i o n real output onedimensional v a r i a b l e of d i m e n s i o n at l e a s t N containing the e i g e n v a l u e s of the r e a l t r i d i a g o n a l m a t r i x in a s c e n d i n g o r d e r . MATZ

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to z e r o if o n l y e i g e n v a l u e s are desired; o t h e r w i s e it is set to any n o n - z e r o i n t e g e r for both eigenvalues and e i g e n v e c t o r s . is, if MATZ is n o n - z e r o , a w o r k i n g precision real output two-dimensional variable with row dimension NM and column d i m e n s i o n at l e a s t N containing the eigenvectors. The eigenvectors are not normalized. If MATZ is z e r o , Z is n o t referenced a n d can be a d u m m y v a r i a b l e .

B.

Error

FVI

is a w o r k i n g p r e c i s i o n temporary onedimensional v a r i a b l e of d i m e n s i o n at l e a s t N.

!ERR

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

Conditions

If N with

and

is

Returns.

is g r e a t e r t h a n NM, the IERR set e q u a l to 10*N.

If the p r o d u c t the s u b r o u t i n e and no r e s u l t s

to

of A(I,I) terminates computed.

and with

subroutine

A(I-I,3) IERR set

terminates

is n e g a t i v e , e q u a l to N+I

If the p r o d u c t is z e r o w i t h o n e f a c t o r n o n - z e r o , a n d MATZ is n o n - z e r o , the s u b r o u t i n e terminates with IERR set e q u a l to 2*N+I and no r e s u l t s c o m p u t e d .

444

7.1-250

If m o r e t h a n 30 i t e r a t i o n s are r e q u i r e d to d e t e r m i n e an e i g e n v a l u e , the s u b r o u t i n e t e r m i n a t e s w i t h IERR set e q u a l to the i n d e x of the e i g e n v a l u e for w h i c h the f a i l u r e occurs. The e i g e n v a l u e s a n d e i g e n v e c t o r s in the W and Z a r r a y s s h o u l d be c o r r e c t for i n d i c e s 1,2,...,IERR-I. If all the e i g e n v a l u e s are d e t e r m i n e d iterations, IERR is set to zero.

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

and

within

30

Restrictions.

This s u b r o u t i n e can be u s e d to find all the e i g e n v a l u e s and all the e i g e n v e c t o r s (if d e s i r e d ) of a c e r t a i n real tridiagonal matrix.

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

OF M E T H O D

AND

ALGORITHM.

This s u b r o u t i n e calls the r e c o m m e n d e d s e q u e n c e of s u b r o u t i n e s from EISPACK to f i n d the e i g e n v a l u e s and e i g e n v e c t o r s of a certain real tridiagonal matrix. To

find e i g e n v a l u e s only, the s e q u e n c e is the f o l l o w i n g . FIGI to t r a n s f o r m a c e r t a i n r e a l t r i d i a g o n a l m a t r i x into a s y m m e t r i c t r i d i a g o n a l m a t r i x . IMTQLI - to d e t e r m i n e the e i g e n v a l u e s of the o r i g i n a l m a t r i x f r o m the s y m m e t r i c t r i d i a g o n a l m a t r i x . -

To find e i g e n v a l u e s and e i g e n v e c t o r s , the s e q u e n c e is the following. FIGI2 - to t r a n s f o r m a c e r t a i n r e a l t r i d i a g o n a l m a t r i x into a s y m m e t r i c t r i d i a g o n a l m a t r i x , a c c u m u l a t i n g the t r a n s f o r m a t i o n s . IMTQL2 to d e t e r m i n e the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x f r o m the s y m m e t r i c tridiagonal matrix. -

4.

REFERENCES. i)

5.

G a r b o w , B.S. A p r i l , 1974.

and

Dongarra,

J.J.,

EISPACK

Path

Chart,

CHECKOUT. A.

Test

Cases.

See the s e c t i o n d i s c u s s i n g c e r t a i n real n o n - s y m m e t r i c B.

Accuracy.

445

t e s t i n g of the codes for tridiagonal matrices.

7,1-251

The a c c u r a c y of RT can b e s t be d e s c r i b e d in terms of its role in t h o s e p a t h s of E I S P A C K (i) w h i c h find e i g e n v a l u e s and e i g e n v e c t o r s of c e r t a i n r e a l n o n symmetric tridiagonal matrices. In these p a t h s , this s u b r o u t i n e is n u m e r i c a l l y stable. This s t a b i l i t y c o n t r i b u t e s to the p r o p e r t y of t h e s e p a t h s that the c o m p u t e d e i g e n v a l u e s are the e x a c t e i g e n v a l u e s of a m a t r i x c l o s e to the o r i g i n a l m a t r i x and the c o m p u t e d e i g e n v e c t o r s a r e c l o s e (but not n e c e s s a r i l y equal) to the e i g e n v e c t o r s of that m a t r i x .

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) I E R R = i0 * N GO TO 50

GO TO

I0

I0 IF (MATZ .NE. 0) GO TO 20 * * * * * * * * * * F I N D E I G E N V A L U E S 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 C A L L FIGI2(NM,N,A,W, FVI,Z,IERR) IF (IERR .NE. O) GO TO 50 CALL IMTQL2(NM,N,W,FVI,Z,IERR) 50 R E T U R N END

447

**********

7. 1-253

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F223-2

A Fortran

PACKAGE

TINVIT

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

May, July,

(EISPACK)

Some E i g e n v e c t o r s Matrix.

1972 1975

io P U R P O S E ° The F o r t r a n IV s u b r o u t i n e TINVIT determines those e i g e n v e c t o r s of a s y m m e t r i c t r i d i a g o n a l m a t r i x c o r r e s p o n d i n g to a set of o r d e r e d a p p r o x i m a t e e i g e n v a l u e s ~ u s i n g i n v e r s e iteration.

2. U S A G E . A.

Calling The

Sequence°

SUBROUTINE SUBROUTINE

statement

is

T I N V I T ( N M , N , D , E , E 2 , M , W , IND,Z, IERR,RVI,RV2,RV3,RV4,RV6)

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

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

N

is an i n t e g e r i n p u t v a r i a b l e the o r d e r of the m a t r i x . N g r e a t e r than NM.

D

is a w o r k i n g p r e c i s i o n r e a l i n p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N c o n t a i n i n g the d i a g o n a l e l e m e n t s of the symmetric tridiagonal matrix.

448

set e q u a l to m u s t be not

7.1-254

is a w o r k i n g p r e c i s i o n r e a l i n p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g , in its last N-I positions, the s u b d i a g o n a l e l e m e n t s of the s y m m e t r i c tridiagonal matrix. E(1) is a r b i t r a r y . E2

is a w o r k i n g p r e c i s i o n real i n p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N c o n t a i n i n g , in its last N-I positions, the s q u a r e s of the c o r r e s p o n d i n g e l e m e n t s of E w i t h zeros c o r r e s p o n d i n g to n e g l i g i b l e e l e m e n t s of E, (The s u c c e s s i v e s u b m a t r i c e s are l o c a t e d f r o m the zeros of E2.) If MACHEP d e n o t e s the r e l a t i v e m a c h i n e precision, then E(I) is c o n s i d e r e d n e g l i g i b l e if it is not larger than the p r o d u c t of MACHEP and the sum of the m a g n i t u d e s of D(I) and D(I-I). E2(1) should contain 0.0 if the e i g e n v a l u e s are in a s c e n d i n g o r d e r and 2.0 if the e i g e n v a l u e s are in d e s c e n d i n g order. If subroutine B I S E C T (F294) or T R I D I B (F237) has b e e n u s e d to d e t e r m i n e the e i g e n v a l u e s , their o u t p u t E2 a r r a y is s u i t a b l e for i n p u t to TINVIT.

M

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to the n u m b e r of s p e c i f i e d e i g e n v a l u e s for w h i c h the c o r r e s p o n d i n g e i g e n v e c t o r s are to be d e t e r m i n e d .

W

is a w o r k i n g p r e c i s i o n r e a l i n p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least M c o n t a i n i n g the M specified eigenvalues of the s y m m e t r i c t r i d i a g o n a l m a t r i x . The e i g e n v a l u e s m u s t be in e i t h e r a s c e n d i n g or d e s c e n d i n g o r d e r in W. The o r d e r i n g is r e q u i r e d to i n s u r e the d e t e r m i n a t i o n of independent orthogonal eigenvectors associated with close eigenvalues.

IND

is an i n t e g e r input o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t M c o n t a i n i n g the s u b m a t r i x i n d i c e s a s s o c i a t e d w i t h the corresponding M e i g e n v a l u e s in W. E i g e n v a l u e s b e l o n g i n g to the f i r s t s u b m a t r i x have index i, t h o s e b e l o n g i n g to the s e c o n d submatrix have index 2, etc. If BISECT or TRIDIB has b e e n u s e d to d e t e r m i n e the e i g e n v a l u e s , their o u t p u t IND a r r a y is s u i t a b l e for input to TINVIT.

449

7.1-255

is a w o r k i n g p r e c i s i o n r e a l o u t p u t twodimensional variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t M. It contains M o r t h o n o r m a l e i g e n v e c t o r s of the symmetric tridiagonal matrix corresponding to the M e i g e n v a l u e s in W. !ERR

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

to is

RVI,RV2,RV3 are w o r k i n g p r e c i s i o n r e a l t e m p o r a r y oned i m e n s i o n a l v a r i a b l e s of d i m e n s i o n at l e a s t N u s e d to s t o r e the m a i n d i a g o n a l and the two a d j a c e n t d i a g o n a l s of the t r i a n g u l a r m a t r i x p r o d u c e d in the i n v e r s e i t e r a t i o n process. RV4,RV6

B.

Error

are w o r k i n g p r e c i s i o n real t e m p o r a r y o n e d i m e n s i o n a l v a r i a b l e s of d i m e n s i o n at l e a s t N. RV4 h o l d s the m u l t i p l i e r s of the G a u s s i a n e l i m i n a t i o n step in the i n v e r s e iteration process. RV6 h o l d s the a p p r o x i m a t e e i g e n v e c t o r s in this p r o c e s s .

Conditions

and

Returns~

If m o r e t h a n 5 i t e r a t i o n s are r e q u i r e d to d e t e r m i n e an eigenvector, TINVIT t e r m i n a t e s the c o m p u t a t i o n for t h a t e i g e n v e c t o r and s e t s IERR to -R where R is the i n d e x of the e i g e n v e c t o r . If this f a i l u r e o c c u r s for m o r e than one e i g e n v e c t o r , the last o c c u r r e n c e is r e c o r d e d in IERR. The c o l u m n s of Z c o r r e s p o n d i n g to f a i l u r e s of the a b o v e sort are set to zero v e c t o r s . If a l l the e i g e n v e c t o r s a r e d e t e r m i n e d iterations, IERR is set to zero.

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

and

within

5

Restrictions.

To d e t e r m i n e s o m e of the e i g e n v a ! u e s and e i g e n v e c t o r s of a full symmetric matrix, TINVIT s h o u l d be p r e c e d e d by T R E D I (F277) to p r o v i d e a s u i t a b l e s y m m e t r i c t r i d i a g o n a l m a t r i x for B I S E C T (F294), T R I D I B (F237), or ! M T Q L V (F234) w h i c h can t h e n be used to d e t e r m i n e the e i g e n v a l u e s . It s h o u l d be f o l l o w e d by TRBAKI (F279) to b a c k t r a n s f o r m the e i g e n v e c t o r s f r o m TINVIT into t h o s e of the o r i g i n a l m a t r i x .

450

7.1-256

To d e t e r m i n e some of the e i g e n v a l u e s and e i g e n v e c t o r s of a complex Hermitian matrix, TINVlT s h o u l d be p r e c e d e d by H T R I D I (F284) to p r o v i d e a s u i t a b l e r e a l s y m m e t r i c t r i d i a g o n a l m a t r i x for B I S E C T (F294), T R I D I B (F237), or I M T Q L V (F234). It s h o u l d then be f o l l o w e d by H T R I B K (F285) to b a c k t r a n s f o r m the e i g e n v e c t o r s f r o m TINVIT into those of the o r i g i n a l m a t r i x . Some of the e i g e n v a l u e s and e i g e n v e c t o r s of c e r t a i n n o n s y m m e t r i c t r i d i a g o n a l m a t r i c e s can be c o m p u t e d u s i n g the c o m b i n a t i o n of FIGI (F280), B I S E C T (F294) or TRIDIB (F237), TINVlT, and B A K V E C (F281). See F280 for the d e s c r i p t i o n of this s p e c i a l c l a s s of m a t r i c e s . For these m a t r i c e s , TINVIT s h o u l d be p r e c e d e d by FIGI to p r o v i d e a s u i t a b l e s y m m e t r i c m a t r i x for BISECT or TRIDIB. It s h o u l d then be f o l l o w e d by BAKVEC to b a c k t r a n s f o r m the e i g e n v e c t o r s f r o m TINVIT into those of the o r i g i n a l m a t r i x . The c o m p u t a t i o n of the e i g e n v e c t o r s by i n v e r s e i t e r a t i o n r e q u i r e s that the p r e c i s i o n of the e i g e n v a l u e s be c o m m e n s u r a t e w i t h s m a l l r e l a t i v e p e r t u r b a t i o n s of the o r d e r of MACHEP in the m a t r i x e l e m e n t s . For m o s t s y m m e t r i c t r i d i a g o n a l m a t r i c e s , it is e n o u g h that the a b s o l u t e e r r o r in the e i g e n v a l u e s for w h i c h e i g e n v e c t o r s are d e s i r e d be a p p r o x i m a t e l y MACHEP times a n o r m of the m a t r i x . But some m a t r i c e s r e q u i r e a s m a l l e r a b s o l u t e e r r o r , p e r h a p s as s m a l l as MACHEP times the e i g e n v a l u e of s m a l l e s t m a g n i t u d e .

3.

DISCUSSION

OF M E T H O D

AND ALGORITHM.

The c a l c u l a t i o n s p r o c e e d as f o l l o w s . First, the E2 array is i n s p e c t e d for the p r e s e n c e of a zero e l e m e n t d e f i n i n g a submatrix. The e i g e n v a l u e s b e l o n g i n g to this s u b m a t r i x are i d e n t i f i e d by their c o m m o n s u b m a t r i x i n d e x in IND. The e i g e n v e c t o r s of the s u b m a t r i x are then c o m p u t e d by inverse iteration. First, the LU d e c o m p o s i t i o n of the s u b m a t r i x w i t h an a p p r o x i m a t e e i g e n v a l u e s u b t r a c t e d f r o m its d i a g o n a l e l e m e n t s is a c h i e v e d by G a u s s i a n e l i m i n a t i o n u s i n g partial pivoting. The m u l t i p l i e r s d e f i n i n g the lower triangular matrix L are s t o r e d in the t e m p o r a r y a r r a y RV4 and the u p p e r t r i a n g u l a r m a t r i x U is s t o r e d in the three temporary arrays RVI, RV2, and RV3. S a v i n g these q u a n t i t i e s in RVl, RV2, RV3, and RV4 avoids repeating the LU d e c o m p o s i t i o n if f u r t h e r i t e r a t i o n s are r e q u i r e d . An a p p r o x i m a t e v e c t o r , s t o r e d in RV6, is c o m p u t e d s t a r t i n g f r o m an i n i t i a l v e c t o r , and the n o r m of the a p p r o x i m a t e v e c t o r is c o m p a r e d w i t h a n o r m of the s u b m a t r i x to d e t e r m i n e w h e t h e r the g r o w t h is s u f f i c i e n t to a c c e p t it as an eigenvector. If this v e c t o r is a c c e p t e d , its E u c l i d e a n n o r m

451

7.1-257

is m a d e u s e d as vector, times.

I, If the g r o w t h is n o t s u f f i c i e n t , this v e c t o r is the i n i t i a l v e c t o r in c o m p u t i n g t h e n e x t approximate This i t e r a t i o n p r o c e s s is r e p e a t e d at m o s t 5

E i g e n v e c t o r s c o m p u t e d in the a b o v e w a y c o r r e s p o n d i n g to w e l l s e p a r a t e d e i g e n v a l u e s of this s u b m a t r i x w i l l be o r t h o g o n a l . H o w e v e r , e i g e n v e c t o r s c o r r e s p o n d i n g to c l o s e e i g e n v a l u e s of this s u b m a t r i x m a y not be s a t i s f a c t o r i l y o r t h o g o n a l . Hence, to i n s u r e o r t h o g o n a l e i g e n v e c t o r s ~ each a p p r o x i m a t e v e c t o r is m a d e o r t h o g o n a l to t h o s e p r e v i o u s l y c o m p u t e d e i g e n v e c t o r s w h o s e e i g e n v a l u e s are c l o s e to the c u r r e n t e i g e n v a l u e . If the o r t h o g o n a l i z a t i o n p r o c e s s p r o d u c e s a zero v e c t o r , a c o l u m n of the i d e n t i t y m a t r i x is u s e d as an i n i t i a l v e c t o r for the n e x t i t e r a t i o n . I d e n t i c a l e i g e n v a l u e s are p e r t u r b e d s l i g h t l y in an a t t e m p t to obtain independent eigenvectors. T h e s e p e r t u r b a t i o n s are not r e c o r d e d in the e i g e n v a l u e a r r a y W. The a b o v e s t e p s are r e p e a t e d e i g e n v e c t o r s are c o m p u t e d .

on

each

submatrix

until

all

the

This s u b r o u t i n e is a s u b s e t ( e x c e p t for the r e s o l u t i o n of non-convergent e i g e n v e c t o r s ) of the F o r t r a n s u b r o u t i n e T S T U K M (F293), w h i c h is a t r a n s l a t i o n of the A l g o l p r o c e d u r e TR!STURM w r i t t e n and d i s c u s s e d in d e t a i l by P e t e r s and Wilkinson (I)°

4.

REFERENCES.

i)

5.

P e t e r s , Go and W i l k i n s o n , J.H., The C a l c u l a t i o n of S p e c i f i e d E i g e n v e c t o r s by I n v e r s e I t e r a t i o n , H a n d b o o k A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , J. H. W i l k i n s o n - C. R e i n s c h , C o n t r i b u t i o n 11/18, 418-439, Springer-Verlag, 1971.

CHECKOUT. A.

Test

Cases°

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

452

for

7.1-258

B. A c c u r a c y . The a c c u r a c y of TINVIT can b e s t be d e s c r i b e d in terms of its r o l e in those p a t h s of EISPACK w h i c h find e i g e n v a l u e s and e i g e n v e c t o r s of r e a l s y m m e t r i c m a t r i c e s and m a t r i x s y s t e m s . In t h e s e p a t h s , this s u b r o u t i n e is n u m e r i c a l l y s t a b l e (i). This s t a b i l i t y c o n t r i b u t e s to the p r o p e r t y of t h e s e p a t h s that the c o m p u t e d e i g e n v a l u e s are the e x a c t e i g e n v a l u e s of a m a t r i x or s y s t e m close to the o r i g i n a l m a t r i x or s y s t e m and the c o m p u t e d e i g e n v e c t o r s are c l o s e (but not n e c e s s a r i l y equal) to the e i g e n v e c t o r s of that m a t r i x or system.

453

7.1-259

SUBROUTINE

TINVIT(NM,N,D,E,E2,M,W,IND,Z, IERR,RVI,RV2,RV3,RV4,RV6)

X C

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) C C C C C

**********

MACHEP

C I00

=

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

?

IERR = 0 IF (M .EQ. 0) G O T O TAG = 0 ORDER = 1.0 - E2(1) Q = 0 ********** ESTABLISH P = Q + I

I001

AND

PROCESS

NEXT

SUBMATRIX

**********

C DO

120 140

1 2 0 Q = P, N I F (Q . E Q . N) G O T O 1 4 0 IF (E2(Q+I) .EQ. 0 . 0 ) G O T O 1 4 0 CONTINUE ********** FIND VECTORS BY INVERSE TAG = TAG + 1 S = 0

~*********

DO

490

500 C C C C

9 2 0 R = i, M IF (!ND(R) .NEo T A G ) G O T O ITS = 1 Xl = W ( R ) IF (S .ME. 0) G O T O 5 1 0 ********** CHECK FOR ISOLATED XU = 1.0 IF (P .ME. Q) G O T O 4 9 0 RV6(P) = 1.0 GO TO 870 NORM = ABS(D(P)) IP = P + i

ITERATION

920

ROOT

**********

D O 5 0 0 I = IP, Q NORM = NORM + ABS(D(1)) + ABS(E(1)) ********** E P S 2 IS T H E C R I T E R I O N FOR GROUPING, EPS3 REPLACES ZERO PIVOTS AND EQUAL ROOTS ARE MODIFIED BY EPS3, E P S 4 IS T A K E N V E R Y S M A L L T O A V O I D OVERFLOW EPS2 = 1.0E-3 * NORM EPS3 = MACHEP * NORM UK = FLOAT(Q-P+I)

454

**********

7.1-260

505

510

520

EPS4 = UK * EPS3 UK = EPS4 / SQRT(UK) S = P GROUP = 0 GO TO 520 • ********* LOOK FOR CLOSE OR COINCIDENT ROOTS ********** IF ( A B S ( X I - X 0 ) .GE. E P S 2 ) G O T O 5 0 5 GROUP = GROUP + I IF ( O R D E R * (XI - X 0 ) . L E . 0 . 0 ) X I = X 0 + O R D E R * EPS3 • ********* ELIMINATION WITH INTERCHANGES AND INITIALIZATION OF VECTOR ********** V = 0.0 DO

5 8 0 1 = P, Q R V 6 (I) = U K IF (I .EQ. P) G O T O 5 6 0 IF ( A B S ( E ( 1 ) ) .LT. A B S ( U ) ) GO TO 540 ********** WARNING -- A DIVIDE CHECK MAY OCCUR HERE 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) R V 3 ( I - I ) = E(I+I) U = V XU * RV2(I-I) V = -XU * RV3(I-I) GO TO 580

C C

540

xu

= E(I)

RV4(1)

IF **********

/ U

= XU

RVI(I-I)

560 580

= 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 RVI(Q) RV2(Q)

600

620

.EQ. 0 . 0 ) U = E P S 3 = u = 0.0 RV3(Q) = 0.0 ********** BACK SUBSTITUTION F O R I = Q S T E P -I U N T I L P D O - - * * * * * * * * * * D O 6 2 0 II = P, Q I = P + Q - II RV6(I) = (RV6(I) - U * RV2(I) - V * RV3(I)) / RVI(I) V = U U = R V 6 (I) CONTINUE ********** ORTHOGONALIZE WITH RESPECT TO PREVIOUS MEMBERS OF GROUP ********** IF ( G R O U P .EQ. O) G O T O 7 0 0 J = R

455

7.1-261

DO 630

6 8 0 J J = I, G R O U P J = J - 1 IF ( I N D ( J ) oNE. T A G ) XU = 0.0

640

DO xu

6 4 0 1 = P, Q = xu + RV6(!)

660

DO 660 RV6(1)

680

CONTINUE

700

NORM

720

DO 720 NORM =

740

=

I = P, Q = RV6(1)

*

GO

TO

630

Z(I,J)

- XU

* Z(I,J)

0.0 I = P, NORM +

Q ABS(RV6(I))

I F ( N O R M . G E . !.0) G O T O 8 4 0 ******~*** FORWARD SUBSTITUTION IF ( I T S .EQ. 5) G O T O 8 3 0 IF ( N O R M .NE. 0 . 0 ) G O T O 7 4 0 RV6(S) = EPS4 S = S + I IF (S .GT. Q) S = P GO TO 780 XU = EPS4 / NORM

**********

C 760 C C 780 C C C

800 820

C 830

C C 840

DO 760 RV6(I) • *********

1 = P, Q = RV6(I) * XU ELIMINATION OPERATIONS ON NEXT VECTOR ITERATE ********** D O 8 2 0 I = IP, Q U = R V 6 (I) • ********* IF RVI(I-I) .EQ. E(1), A ROW INTERCHANGE WAS PERFORMED EARLIER IN THE TRIANGULARIZATION PROCESS ********** IF ( R V I ( I - I ) .NE. E(I)) GO TO 800 u = ~v6(i-1) RV6(I-I) = RV6(I) RV6(1) = U - RV4(1) * RV6(I-I) CONTINUE ITS = ITS + ! GO TO 600 ********** SET ERROR -IERR = -R XU = 0.0 GO T O 8 7 0 ********** NORMALIZE SO 1 AND EXPAND U = 0.0

NON-CONVERGED

EIGENVECTOR

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

456

**********

7.1-262

860

D O 8 6 0 I = P, Q u = u + RV6(1)**2

C XU

=

1.0

/ SQRT(U)

C 870 880

DO 8 8 0 Z(I,R)

I = i, = 0.0

N

900

DO 9 0 0 Z(I,R)

I = P, Q = RV6(I)

C * XU

C 920

X0 = CONTINUE

X1

C I001

IF (Q RETURN END

.LT.

N)

GO

TO

I00

457

7.!-263

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F235

PACKAGE

(EISPACK)

TQLRAT

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

July,

1975

I. P U R P O S E . The F o r t r a n IV s u b r o u t i n e of a s y m m e t r i c t r i d i a g o n a l the QL method.

TQLRAT matrix

d e t e r m i n e s the e i g e n v a l u e s u s i n g a r a t i o n a l v a r i a n t of

2. USAGE. A.

Calling The

Sequences

SUBROUTINE SUBROUTINE

statement

is

TQLRAT(N,D,E2,1ERR)

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

is an i n t e g e r i n p u t v a r i a b l e the o r d e r of the m a t r i x .

set

equal

to

is a w o r k i n g p r e c i s i o n real o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N. On input, it c o n t a i n s the d i a g o n a l e l e m e n t s of the s y m m e t r i c t r i d i a g o n a l m a t r i x . On o u t p u t , it c o n t a i n s the e i g e n v a l u e s of this m a t r i x in a s c e n d i n g order. E2

is a w o r k i n g p r e c i s i o n r e a l o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N. On input, the last N-I p o s i t i o n s in this a r r a y c o n t a i n the s q u a r e s of the s u b d i a g o n a l e l e m e n t s of the s y m m e t r i c t r i d i a g o n a l matrix. E2(1) is a r b i t r a r y . N o t e that TQLRAT destroys E2.

458

7.1-264

IERR

B. E r r o r

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

Conditions

and

to is

Returns.

If m o r e than 30 i t e r a t i o n s are r e q u i r e d to d e t e r m i n e an e i g e n v a l u e , TQLRAT terminates with IERR set to the i n d e x of the e i g e n v a l u e for w h i c h the f a i l u r e occurs. The e i g e n v a l u e s in the D a r r a y s h o u l d be c o r r e c t for i n d i c e s 1,2,...,IERR-I. These eigenvalues are o r d e r e d but are not n e c e s s a r i l y the s m a l l e s t IERR-I eigenvalues. If all the e i g e n v a ! u e s are d e t e r m i n e d iterations, IERR is set to zero.

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

and

within

30

Restrictions.

To d e t e r m i n e the e i g e n v a l u e s of a f u l l s y m m e t r i c m a t r i x , TQLRAT s h o u l d be p r e c e d e d by T R E D I (F277) to p r o v i d e a s u i t a b l e s y m m e t r i c t r i d i a g o n a l m a t r i x for TQLRAT. To d e t e r m i n e the e i g e n v a l u e s of a c o m p l e x H e r m i t i a n matrix, TQLRAT s h o u l d be p r e c e d e d by H T R I D I (F284) to p r o v i d e a s u i t a b l e r e a l s y m m e t r i c t r i d i a g o n a l m a t r i x for TQLRAT. TQLRAT does not p e r f o r m w e l l on m a t r i c e s w h o s e s u c c e s s i v e row sums v a r y w i d e l y in m a g n i t u d e and are not s t r i c t l y i n c r e a s i n g f r o m the f i r s t to the last row. The subroutine I M T Q L I (F291) is not s e n s i t i v e to such row sums and is t h e r e f o r e r e c o m m e n d e d for s y m m e t r i c t r i d i a g o n a l m a t r i c e s w h o s e s t r u c t u r e is not known.

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

OF M E T H O D

AND

ALGORITHM.

The e i g e n v a l u e s are d e t e r m i n e d by a r a t i o n a l v a r i a n t of the QL method. The e s s e n c e of this m e t h o d is a p r o c e s s w h e r e b y a s e q u e n c e of s y m m e t r i c t r i d i a g o n a l m a t r i c e s , u n i t a r i l y s i m i l a r to the o r i g i n a l s y m m e t r i c t r i d i a g o n a l m a t r i x , is f o r m e d w h i c h c o n v e r g e s to a d i a g o n a l m a t r i x . The rate of c o n v e r g e n c e of this s e q u e n c e is i m p r o v e d by s h i f t i n g the o r i g i n at each i t e r a t i o n . B e f o r e the i t e r a t i o n s for each e i g e n v a l u e , the s y m m e t r i c t r i d i a g o n a l m a t r i x is c h e c k e d for a p o s s i b l e s p l i t t i n g into s u b m a t r i c e s . If a s p l i t t i n g o c c u r s , only the u p p e r m o s t s u b m a t r i x p a r t i c i p a t e s in the n e x t iteration. The e i g e n v a l u e s are o r d e r e d in a s c e n d i n g o r d e r as they are found.

459

7.1-265

The origin shift at each iteration is the eigenvalue of the current u p p e r m o s t 2x2 p r i n c i p a l minor closer to the first diagonal element of this minor. W h e n e v e r the uppermost Ixl p r i n c i p a l s u b m a t r i x finally splits from the rest of the matrix, its element is taken to be an e i g e n v a l u e of the original m a t r i x and the a l g o r i t h m proceeds with the remaining submatrix. This process is continued until the m a t r i x has split completely into submatrices of order i. The tolerances in the splitting tests are p r o p o r t i o n a l to the relative m a c h i n e precision. This s u b r o u t i n e is a t r a n s l a t i o n of the Algol p r o c e d u r e TQLRAT w r i t t e n and discussed in detail by Reinsch (I). It is a r a t i o n a l variant of the s u b r o u t i n e TQLI which is a t r a n s l a t i o n of the Algol p r o c e d u r e TQLI w r i t t e n and discussed in detail by Bowdler, Martin, Reinsch, and W i l k i n s o n (2).

4. REFERENCES.

1)

Reinsch, C.H.~ A Stable R a t i o n a l QR A l g o r i t h m for C o m p u t a t i o n of the E i g e n v a l u e s of an Hermitian, T r i d i a g o n a l 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 A l g o r i t h m s for Symmetric Matrices, Num. Math. 11,293-306 (1968). (Reprinted in H a n d b o o k for Automatic Computation, Volume II, Linear Algebra, J. H. W i l k i n s o n - Co Reinsch, C o n t r i b u t i o n 11/3, 227-240, S p r i n g e r - V e r l a g , 1971.)

the

5. CHECKOUT. A,

Test

Cases.

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

Bo Accuracy, The s u b r o u t i n e TQLRAT is n u m e r i c a l l y stable (1,2); that is, the computed e i g e n v a l u e s are close to those of the original matrix. In addition, they are the exact e i g e n v a l u e s of a m a t r i x close to the original real symmetric t r i d i a g o n a l 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 IS A M A C H I N E DEPENDENT PARAMETER SPECIFYING THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC. **********

MACHEP

=

?

IERR = 0 IF (N .EQ.

i00

i)

GO

TO

I001

D O i 0 0 1 = 2, N E2(I-I) = E2(1) F = 0.0 B = 0.0 E2 (N) =

0.0

DO

105

ii0 120

130

140

2 9 0 L = I, N J = 0 H = MACHEP * (ABS(D(L)) + SQRT(E2(L))) I F (B .GT. H) G O T O 1 0 5 B = H C = B * B • ********* LOOK FOR SMALL SQUARED SUB-DIAGONAL ELEMENT D O I I 0 M = L, N IF ( E 2 ( M ) .LE. C) G O T O 1 2 0 • ********* E2(N) IS A L W A Y S ZERO, SO T H E R E IS N O E X I T THROUGH THE BOTTOM OF THE LOOP ********** CONTINUE

I F (M .EQo L) G O T O 2 1 0 I F (J .EQ. 30) G O T O i 0 0 0 J = J + I ********** FORM SHIFT ********** LI = L + I S = SQRT(E2(L)) G = D(L) P = ( D ( L I ) - G) / ( 2 . 0 * S) R = SQRT(P*P+I.0) D ( L ) = S / (e + S I G N ( R , P ) ) H = G - D(L) DO 140 1 = LI, N D(I) = D(I) - H F = F + H

461

**********

7.1-267

********** RATIONAL G = D (M) IF (G ,EQ, 0 . 0 ) H = G S

=

MML

200

QL G

=

TRANSFORMATION

**********

B

0,0 =

M

-

L

********** FOR !=M-I S T E P -I U N T I L D O 2 0 0 II = I, M M L 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 . E Q . 0 . 0 ) G = B H = G * P / R CONTINUE

L

DO

--

**********

230

E2(L) = S * G D(L) = H ********** GUARD AGAINST UNDERFLOW IN CONVERGENCE TEST IF (H . E Q . 0 . 0 ) G O T O 2 1 0 IF ( A B S ( E 2 ( L ) ) .LE. ABS(C/H)) GO TO 210 E2(L) = H * E2(L) IF ( E 2 ( L ) .NE. 0.0) GO TO 130 P = D(L) + F ********** ORDER EIGENVALUES ********** I F (L , E Q . i) G O T O 2 5 0 ********** F O R I = L S T E P -i U N T I L 2 DO -- ********** D O 2 3 0 I I = 2, L I = L + 2 - II IF (P .GE. D ( I - I ) ) GO TO 270 D(!) = D (I-I) CONTINUE

250 270 290

I = 1 D(1) = CONTINUE

C

210 C C

GO TO I001 ********** I000 i001

IERR = RETURN END

P

SET ERROR EIGENVALUE

-- NO CONVERGENCE TO AFTER 30 ITERATIONS

L

462

AN **********

**********

7.1-268

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F289-2

PACKAGE

(EISPACK)

TQLI

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

May, July,

1972 1975

i. PURPOSE. The F o r t r a n IV s u b r o u t i n e of a s y m m e t r i c t r i d i a g o n a l

TQLI determines m a t r i x u s i n g the

the e i g e n v a l u e s QL method.

2. USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

TQLI(N,D,E,IERR)

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

set

equal

to

is a w o r k i n g p r e c i s i o n real o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N. On input, it c o n t a i n s the d i a g o n a l e l e m e n t s of the s y m m e t r i c t r i d i a g o n a l matrix. On output, it c o n t a i n s the e i g e n v a ! u e s of this m a t r i x in a s c e n d i n g order. is a w o r k i n g p r e c i s i o n real o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N. On input, the last N-I p o s i t i o n s in this array c o n t a i n the s u b d i a g o n a l e l e m e n t s of the s y m m e t r i c t r i d i a g o n a ! matrix. E(1) is arbitrary. N o t e that TQLI destroys E.

463

7.1-269

IERR

B.

Error

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

Conditions

and

to is

Returns°

If m o r e t h a n 30 i t e r a t i o n s are r e q u i r e d to d e t e r m i n e an e i g e n v a l u e , TQLI terminates with IERR set to the i n d e x of the e i g e n v a l u e for w h i c h the f a i l u r e o c c u r s . T h e e i g e n v a l u e s in the D a r r a y s h o u l d be c o r r e c t for indices 1,2,o..,IERR-I. T h e s e e i g e n v a l u e s are o r d e r e d b u t a r e n o t n e c e s s a r i l y the s m a l l e s t IERR-I eigenvalues. If all the e i g e n v a l u e s are d e t e r m i n e d iterations, IERR is set to zero.

C.

Applicability

and

within

30

Restrictions.

To d e t e r m i n e the e i g e n v a l u e s of a f u l l s y m m e t r i c m a t r i x , TQLI s h o u l d be p r e c e d e d by TREDI (F277) to p r o v i d e a s u i t a b l e s y m m e t r i c t r i d i a g o n a l m a t r i x for TQLI. To d e t e r m i n e the e i g e n v a l u e s of a c o m p l e x H e r m i t i a n matrix, TQLI s h o u l d be p r e c e d e d by H T R I D I (F284) p r o v i d e a s u i t a b l e real s y m m e t r i c t r i d i a g o n a l m a t r i x TQLI.

to for

TQLI does not p e r f o r m w e l l on m a t r i c e s w h o s e s u c c e s s i v e row sums v a r y w i d e l y in m a g n i t u d e and are not s t r i c t l y i n c r e a s i n g f r o m the f i r s t to the last row. The subroutine I M T Q L ! (F291) is n o t s e n s i t i v e to s u c h row sums and is t h e r e f o r e r e c o m m e n d e d for s y m m e t r i c t r i d i a g o n a l m a t r i c e s w h o s e s t r u c t u r e is not known.

3.

DISCUSSION

OF M E T H O D

AND

ALGORITHM.

The e i g e n v a l u e s are d e t e r m i n e d by the QL method. The e s s e n c e of this m e t h o d is a p r o c e s s w h e r e b y a s e q u e n c e of s y m m e t r i c t r i d i a g o n a l m a t r i c e s , u n i t a r i l y s i m i l a r to the o r i g i n a l s y m m e t r i c t r i d i a g o n a l m a t r i x , is f o r m e d w h i c h c o n v e r g e s to a d i a g o n a l m a t r i x . The r a t e of c o n v e r g e n c e of this s e q u e n c e is i m p r o v e d by s h i f t i n g the o r i g i n at e a c h iteration° B e f o r e the i t e r a t i o n s for each e i g e n v a l u e , the s y m m e t r i c t r i d i a g o n a l m a t r i x is c h e c k e d for a p o s s i b l e s p l i t t i n g into s u b m a t r i c e s . If a s p l i t t i n g o c c u r s , only the u p p e r m o s t s u b m a t r i x p a r t i c i p a t e s in the n e x t i t e r a t i o n . The e i g e n v a l u e s are o r d e r e d in a s c e n d i n g o r d e r as they are found.

464

7.1-270

The origin shift at each iteration is the eigenvaiue of the current u p p e r m o s t 2x2 p r i n c i p a l minor closer to the first diagonal element of this minor. Whenever the u p p e r m o s t 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 a l g o r i t h m proceeds with the remaining submatrix. This process is continued until the m a t r i x has split c o m p l e t e l y into submatrices of order I. The tolerances in the splitting tests are p r o p o r t i o n a l to the relative machine precision. This subroutine is a translation of the Algol procedure TQLI w r i t t e n and d i s c u s s e d in detail by Bowdler, Martin, Reinsch, and W i l k i n s o n (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 H a n d b o o k for Automatic Computation, Volume II, Linear Algebra, J. H. W i l k i n s o n - C. Reinsch, C o n t r i b u t i o n 11/3, 227-240, 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 n o n - s y m m e t r i c tridiagonal matrices.

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

465

7.1-271

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 IS A M A C H I N E DEPENDENT PARAMETER SPECIFYING THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC. **********

MACHEP

=

?

IERR = 0 IF (N .EQ.

i)

GO

TO

I001

C 100

DO i00 E(I-I)

I = 2, = E(1)

N

F = 0.0 B = 0.0 E(N) = 0.0 DO

ii0 120 130

140

2 9 0 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 ********** D O I i 0 M = L, N IF (ABS(E(M)) .LE. B) G O T O 1 2 0 • ********* E ( N ) IS A L W A Y S ZERO, SO THERE IS N O E X I T THROUGH THE BOTTOM OF THE LOOP ********** CONTINUE IF (M °EQ. L) G O T O 2 1 0 IF (J ,EQ. 3 0 ) G O T O I 0 0 0 J = J + 1 ********** FORM SHIFT ********** L1 = L + 1 G = D (L) e = ( D ( L I ) - G) / ( 2 . 0 * E ( L ) ) R = SQRT(P*P+I.0) D ( L ) = E ( L ) / (e + S I G N ( R , P ) ) H = G - D(L) DO 140 D(1) = F

=

F

I = LI, N D(i) - H +

H

********** QL P = D (M) C = i°0 S

=

MML

TRANSFORMATION

**********

0.0

= M

- L

466

7.1-272

********** FOR I--M-I S T E P -I UNTIL L DO -D O 2 0 0 I I = i, M M L I = MII 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 150

160 200

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 * CONTINUE

g

+

S

*

D(1))

230

E(L) = S * P D(L) = C * P IF ( A B S ( E ( L ) ) .GT. B) G O T O 1 3 0 P = D(L) + F • ********* ORDER EIGENVALUES ********** IF (L . E Q . I) G O T O 2 5 0 • ********* FOR I=L STEP -i U N T I L 2 DO D O 2 3 0 I I = 2, L I = L + 2 - II IF (P o G E . D ( I - I ) ) GO TO 270 D(1) = D(I-I) CONTINUE

250 270 290

I = 1 D(I) = CONTINUE

210

GO TO I001 ********** i000 i001

IERR = RETURN END

--

**********

P

SET ERROR EIGENVALUE

-- NO AFTER

L

467

CONVERGENCE TO 30 ITERATIONS

AN **********

7.1-273

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F290-2

PACKAGE

(EISPACK)

TQL2

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

May, July,

1,

and

1972 1975

PURPOSE. The F o r t r a n IV s u b r o u t i n e TQL2 d e t e r m i n e s the e i g e n v a l u e s and e i g e n v e c t o r s of a s y m m e t r i c t r i d i a g o n a l m a t r i x . TQL2 u s e s the QL m e t h o d to c o m p u t e the e i g e n v a l u e s and a c c u m u l a t e s the QL transformations to c o m p u t e the eigenvectors. T h e e i g e n v e c t o r s of a f u l l s y m m e t r i c m a t r i x can also be c o m p u t e d d i r e c t l y by TQL2, if T R E D 2 (F278) has b e e n u s e d to r e d u c e this m a t r i x to t r i d i a g o n a l form.

2. USAGE. A.

Calling The

Sequence~

SUBROUTINE SUBROUTINE

statement

is

TQL2(NM,N,D,E,Z,IERR)

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

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

set e q u a l to m u s t be not

is a w o r k i n g p r e c i s i o n r e a l o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N. On input, it c o n t a i n s the d i a g o n a l e l e m e n t s of the s y m m e t r i c t r i d i a g o n a l m a t r i x . On o u t p u t , it c o n t a i n s the e i g e n v a l u e s of this m a t r i x in a s c e n d i n g order.

468

7. 1-274

is a w o r k i n g p r e c i s i o n real o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N. On input, the l a s t N-I p o s i t i o n s in this a r r a y c o n t a i n the s u b d i a g o n a l e l e m e n t s of the s y m m e t r i c t r i d i a g o n a l m a t r i x . E(1) is arbitrary. N o t e that TQL2 destroys E. is a w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t N. If the e i g e n v e c t o r s of the s y m m e t r i c t r i d i a g o n a l m a t r i x are d e s i r e d , then on input, Z c o n t a i n s the i d e n t i t y m a t r i x of o r d e r N, and on o u t p u t , c o n t a i n s the o r t h o n o r m a l e i g e n v e c t o r s of this t r i d i a g o n a l m a t r i x . If the e i g e n v e c t o r s of a f u l l s y m m e t r i c m a t r i x are d e s i r e d , then on input, Z c o n t a i n s the t r a n s f o r m a t i o n m a t r i x p r o d u c e d in TRED2 w h i c h r e d u c e d the full m a t r i x to t r i d i a g o n a l form, and on o u t p u t , c o n t a i n s the o r t h o n o r m a l e i g e n v e e t o r s of this f u l l symmetric matrix. IERR

B.

Error

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

Conditions

and

to is

Returns.

If m o r e than 30 i t e r a t i o n s are r e q u i r e d to d e t e r m i n e an e i g e n v a l u e , TQL2 terminates with IERR set to the i n d e x of the e i g e n v a l u e for w h i c h the f a i l u r e occurs. The e i g e n v a l u e s and e i g e n v e c t o r s in the D and Z a r r a y s s h o u l d be c o r r e c t for i n d i c e s 1,2,...,IERR-I, b u t the e i g e n v a l u e s are u n o r d e r e d . If all the e i g e n v a l u e s are d e t e r m i n e d iterations, IERR is set to zero.

C.

Applicability

and

within

30

Restrictions.

To d e t e r m i n e the e i g e n v a l u e s and e i g e n v e c t o r s of a full symmetric matrix, TQL2 s h o u l d be p r e c e d e d by TRED2 (F278) to p r o v i d e a s u i t a b l e s y m m e t r i c t r i d i a g o n a l m a t r i x for TQL2.

469

7ol-275

To d e t e r m i n e the e i g e n v a l u e s and e i g e n v e c t o r s of a complex Hermitian matrix, TQL2 s h o u l d be p r e c e d e d by H T R I D I (F284) to p r o v i d e a s u i t a b l e r e a l s y m m e t r i c t r i d i a g o n a l m a t r i x for TQL2, and the input a r r a y Z to TQL2 s h o u l d be i n i t i a l i z e d to the i d e n t i t y m a t r i x . TQL2 s h o u l d then be f o l l o w e d by H T R I B K (F285) to b a c k t r a n s f o r m the e i g e n v e c t o r s f r o m TQL2 into those of the original matrix. TQL2 does not p e r f o r m w e l l on m a t r i c e s w h o s e s u c c e s s i v e r o w sums v a r y w i d e l y in m a g n i t u d e and are not s t r i c t l y i n c r e a s i n g f r o m the f i r s t to the last row. The subroutine I M T Q L 2 (F292) is not s e n s i t i v e to such r o w sums and is t h e r e f o r e r e c o m m e n d e d for s y m m e t r i c t r i d i a g o n a l m a t r i c e s w h o s e s t r u c t u r e is not known.

3.

DISCUSSION

OF M E T H O D

AND

ALGORITHM.

The e i g e n v a l u e s are d e t e r m i n e d by the QL method. The e s s e n c e of this m e t h o d is a p r o c e s s w h e r e b y a s e q u e n c e of s y m m e t r i c t r i d i a g o n a l m a t r i c e s , u n i t a r i l y s i m i l a r to the o r i g i n a l s y m m e t r i c t r i d i a g o n a ! m a t r i x , is f o r m e d w h i c h c o n v e r g e s to a d i a g o n a l m a t r i x . The rate of c o n v e r g e n c e of this s e q u e n c e is i m p r o v e d by s h i f t i n g the o r i g i n at e a c h iteration. B e f o r e the i t e r a t i o n s for e a c h e i g e n v a l u e , the s y m m e t r i c t r i d i a g o n a l m a t r i x is c h e c k e d for a p o s s i b l e s p l i t t i n g into s u b m a t r i c e s . If a s p l i t t i n g o c c u r s , only the u p p e r m o s t s u b m a t r i x p a r t i c i p a t e s in the n e x t i t e r a t i o n . The similarity transformations u s e d in e a c h i t e r a t i o n are a c c u m u l a t e d in the Z array, p r o d u c i n g the o r t h o n o r m a l e i g e n v e c t o r s for the o r i g i n a l m a t r i x . F i n a l l y , the e i g e n v a l u e s are o r d e r e d in a s c e n d i n g o r d e r and the e i g e n v e c t o r s are o r d e r e d c o n s i s t e n t l y . The o r i g i n s h i f t at each i t e r a t i o n is the e i g e n v a l u e of the current uppermost 2x2 p r i n c i p a l m i n o r c l o s e r to the f i r s t d i a g o n a l e l e m e n t of this m i n o r . W h e n e v e r the u p p e r m o s t Ixl p r i n c i p a l s u b m a t r i x f i n a l l y s p l i t s f r o m the r e s t of the m a t r i x , its e l e m e n t is t a k e n to be an e i g e n v a l u e of the o r i g i n a l m a t r i x and the a l g o r i t h m p r o c e e d s w i t h the r e m a i n i n g submatrix. This p r o c e s s is c o n t i n u e d u n t i l the m a t r i x has s p l i t c o m p l e t e l y into s u b m a t r i c e s of order I. The t o l e r a n c e s in the s p l i t t i n g tests are p r o p o r t i o n a l to the relative machine precision. This s u b r o u t i n e is a t r a n s l a t i o n of the A l g o l p r o c e d u r e TQL2 w r i t t e n and d i s c u s s e d in d e t a i l by B o w d l e r , M a r t i n , R e i n s c h , and W i l k i n s o n (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 H a n d b o o k for Automatic Computation, Volume II, Linear Algebra, J. H. W i l k i n s o n - C. Reinsch, C o n t r i b u t i o n II/3, 227-240, 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 n o n - s y m m e t r i c tridiagonal matrices.

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 n e c e s s a r i l y equal) to the eigenvectors of that matrix.

471

7.1-277

SUBROUTINE

TQL2(NM,N,D,E,Z,IERR)

C 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 IS A THE RELATIVE

MACHINE DEPENDENT PARAMETER SPECIFYING PRECISION OF FLOATING POINT ARITHMETIC.

********** MACHEP

=

?

IERR = 0 IF (N .EQ.

100

DO I00 E(I-t)

I)

1 = 2, = E(I)

GO

TO

i001

N

F = 0.0 B = 0.0 E(N) = 0.0 DO

ii0 120 130

140

2 4 0 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 ********** D O I i 0 M = L, N IF (ABS(E(M)) . L E . B) G O T O 1 2 0 • ********* E ( N ) IS A L W A Y S ZERO, SO THERE IS N O E X I T THROUGH THE BOTTOM OF THE LOOP ********** CONTINUE

I F (M .EQ. L) G O T O 2 2 0 IF (J .EQ. 3 0 ) G O T O i 0 0 0 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 + S I G N ( R , P ) ) H = G D(L) DO 140 O(1) =

I = LI, N D(1) - H

C C

F = F + H ********** QL P = D (M) C : 1.0 S

=

MML

TRANSFORMATION

**********

0.0

= M

- L

472

O3

II

II

~'

~

~

II

~

I-4 ~--.

-

o

II

tl

w

H

I!

0

0

0

•

II

11

0

0

2

O

""

~;I tZl c~ t:~ ~..~

0

t ~ ~ ~..~ . - ~ .-"~ ~.'~

ff'~ 0

t~ 0

OX 0

I'o O0 0

~

~

II

II

I

M

II

II

H

0 0

0 ~

C~

I--I

C~

H

L'~

0

r,~

0

.~ o

H

~,'0

~

LO O

0

0 0

;'l-J •

"..-/ h~i >d -I- "--"

.,--. I ~

0"~

, - ' , ~'J , " , , •--- -

I..o o

f'~

C~

0

o o

c3

~ ~

0

00 o

~::;q II

~'-~ [;~ v~

-

I

~-"

L'q ~-

ii

~

n

o~i

0 It

I

l:~. ~, i---i

",..~

~'~ ~

<:~

0

x.. ~.~ x..H

x-.

0

It

II

II

II

"~'o

r.~ c~ ,.-.~

t--I

0

il

I|

II

II

~o

0

0

0

i-I

"

0~ ~s'~ ".-~ ~...~

H

~

c

II

H

:~

~

I!

I

II

II

o o

0

I !

t~ 0

I

!

tl

0

X-,

..j 00

?

7.1-279

C 300

CONTINUE

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

C C i000 i001

IERR = RETURN END

SET ERROR EIGENVALUE

-- NO CONVERGENCE TO AFTER 30 ITERATIONS

L

474

AN **********

7. 1-280

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F279-2

PACKAGE

(EISPACK)

TRBAKI

A F o r t r a n IV S u b r o u t i n e to B a c k T r a n s f o r m the E i g e n v e c t o r s of that S y m m e t r i c T r i d i a g o n a l M a t r i x D e t e r m i n e d by TREDI.

May, July,

1972 1975

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e TRBAKI forms the e i g e n v e c t o r s a real s y m m e t r i c m a t r i x f r o m the e i g e n v e c t o r s of that s y m m e t r i c t r i d i a g o n a l m a t r i x d e t e r m i n e d by T R E D I (F277).

2.

of

USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

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

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

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

set e q u a l to m u s t be not

is a w o r k i n g p r e c i s i o n r e a l i n p u t twod i m e n s i o n a l v a r i a b l e w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at l e a s t N. The s t r i c t l o w e r t r i a n g l e of A c o n t a i n s some i n f o r m a t i o n a b o u t the o r t h o g o n a l t r a n s f o r m a t i o n s u s e d in the r e d u c t i o n to the t r i d i a g o n a l form. The r e m a i n i n g u p p e r p a r t of the m a t r i x is a r b i t r a r y . See s e c t i o n 3 of F277 for the details.

475

7.1-281

is a w o r k i n g p r e c i s i o n real i n p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g , in its last N-I positions, the s u b d i a g o n a l e l e m e n t s of the t r i d i a g o n a l matrix. The e l e m e n t E(1) is a r b i t r a r y . T h e s e e l e m e n t s s e r v e to p r o v i d e the r e m a i n i n g i n f o r m a t i o n about the o r t h o g o n a l transformations. is an i n t e g e r the n u m b e r of transformed.

input variable c o l u m n s of Z

set e q u a l to to be b a c k

is a w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t M. On input, the f i r s t M c o l u m n s of Z c o n t a i n the e i g e n v e c t o r s to be b a c k t r a n s f o r m e d . On o u t p u t , t h e s e c o l u m n s of Z c o n t a i n the t r a n s f o r m e d eigenvectors. The t r a n s f o r m e d e i g e n v e c t o r s are o r t h o n o r m a l if the i n p u t e i g e n v e c t o r s are o r t h o n o r m a l .

B.

Error

Conditions

and

Returns~

None~

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

and

Restrictions~

This s u b r o u t i n e s h o u l d be used subroutine T R E D I (F277).

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

OF M E T H O D

AND

in

conjunction

with

the

ALGORITHM.

(say) has b e e n r e d u c e d S u p p o s e that the s y m m e t r i c m a t r i x C F by the s i m i l a r i t y to the t r i d i a g o n a l s y m m e t r i c m a t r i x transformation T F = Q CQ where Q is a p r o d u c t of the o r t h o g o n a l s y m m e t r i c m a t r i c e s e n c o d e d in E and in the s t r i c t l o w e r t r i a n g l e of A. Then, g i v e n an a r r a y Z of c o l u m n v e c t o r s , TRBAKI c o m p u t e s the matrix product QZ. If the e i g e n v e c t o r s of F are c o l u m n s of the a r r a y Z, then TRBAKI f o r m s the e i g e n v e c t o r s of C in t h e i r place. Since Q is o r t h o g o n a l , v e c t o r E u c l i d e a n n o r m s are p r e s e r v e d .

476

7.1-282

This s u b r o u t i n e is a t r a n s l a t i o n of the A l g o l p r o c e d u r e TRBAKI w r i t t e n and d i s c u s s e d in d e t a i l by M a r t i n , R e i n s c h , and W i l k i n s o n (I).

4. R E F E R E N C E S .

l)

5.

M a r t i n , R.S., R e i n s c h , C., and W i l k i n s o n , J.H., Householder's Tridiagonalization of a S y m m e t r i c M a t r i x , Num. Math. 1 1 , 1 8 1 - 1 9 5 (1968). ( R e p r i n t e d in H a n d b o o k for A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , J. H. W i l k i n s o n - C. R e i n s c h , C o n t r i b u t i o n II/2, 2 1 2 - 2 2 6 , Springer-Verlag, 1971.)

CHECKOUT. A.

Test

Cases.

See the s e c t i o n d i s c u s s i n g real s y m m e t r i c m a t r i c e s .

testing

of

the codes

for

B. A c c u r a c y . The a c c u r a c y of TRBAKI can best be d e s c r i b e d in terms of its role in those paths of EISPACK w h i c h find e i g e n v a l u e s and e i g e n v e c t o r s of real s y m m e t r i c m a t r i c e s and m a t r i x systems. In these paths, this s u b r o u t i n e is n u m e r i c a l l y s t a b l e (I). This s t a b i l i t y c o n t r i b u t e s to the p r o p e r t y of these paths that the c o m p u t e d e i g e n v a l u e s are the exact e i g e n v a l u e s of a m a t r i x or s y s t e m close to the o r i g i n a l m a t r i x or s y s t e m and the c o m p u t e d e i g e n v e c t o r s are close (but not n e c e s s a r i l y equal) to the e i g e n v e c t o r s of that m a t r i x or system.

477

7.1-283

SUBROUTINE

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

INTEGER I,J,K,L,M,N,NM R E A L A ( N M , N ) , E (N), Z ( N M , M ) REAL S

Ii0

IF IF

(M (N

.EQ. .EQ.

0) i)

DO

140 I = 2~ N L = I - 1 IF (E(I) .EQ.

0.0)

DO

M

130 J = S=Oo0

GO GO

I,

TO TO

200 200

GO

140

DO I i 0 K = i, L s = s + A(I~K) * Z(K,J) • ********* DIVISOR BELOW IS N E G A T I V E OF H F O R M E D IN DOUBLE DIVISION AVOIDS POSSIBLE UNDERFLOW

S = (S / A ( i , L ) ) DO 1 2 0 Z(K,J)

120 130

TO

K = i, L = Z(K,J) +

/

E(I)

S * A(I,K)

CONTINUE

140

CONTINUE

200

RETURN END

478

TREDI. **********

7.1-284

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F229

PACKAGE

(EISPACK)

TRBAK3

A F o r t r a n IV S u b r o u t i n e to Back T r a n s f o r m the E i g e n v e c t o r s of that S y m m e t r i c T r i d i a g o n a l M a t r i x D e t e r m i n e d by TRED3.

July,

1975

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e TRBAK3 forms the e i g e n v e c t o r s a real s y m m e t r i c m a t r i x f r o m the e i g e n v e c t o r s of that s y m m e t r i c t r i d i a g o n a l m a t r i x d e t e r m i n e d by T R E D 3 (F228).

of

2. USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

TRBAK3(NM,N,NV,A,M,Z)

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

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

N

is an i n t e g e r input v a r i a b l e the order of the m a t r i x . N g r e a t e r than NM.

NV

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to the d i m e n s i o n of the a r r a y A as s p e c i f i e d in the D I M E N S I O N s t a t e m e n t for A in the calling program. NV m u s t be not less than N* (N+I) 12.

A

is a w o r k i n g p r e c i s i o n r e a l i n p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N*(N+I)/2 c o n t a i n i n g i n f o r m a t i o n about the o r t h o g o n a l t r a n s f o r m a t i o n s u s e d in the r e d u c t i o n to the t r i d i a g o n a l form. See s e c t i o n 3 of F228 for the details.

479

set e q u a l to m u s t be not

7.1-285

M

is an i n t e g e r i n p u t v a r i a b l e the n u m b e r of c o l u m n s of Z transformed.

set e q u a l to to be b a c k

is a w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t M. On input, the f i r s t M c o l u m n s of Z c o n t a i n the e i g e n v e c t o r s to be b a c k t r a n s f o r m e d . On output, these c o l u m n s of Z c o n t a i n the t r a n s f o r m e d eigenvectors. The t r a n s f o r m e d e i g e n v e c t o r s are o r t h o n o r m a l if the i n p u t e i g e n v e c t o r s are o r t h o n o r m a l .

B.

Error

Conditions

and R e t u r n s ~

None.

C.

Applicability

and

Restrictions.

This s u b r o u t i n e s h o u l d be u s e d subroutine T R E D 3 (F228).

3~

DISCUSSION

OF M E T H O D

AND

in c o n j u n c t i o n

with

the

ALGORITHM.

(say) has b e e n r e d u c e d S u p p o s e that the s y m m e t r i c m a t r i x C F by the s i m i l a r i t y to the t r i d i a g o n a l s y m m e t r i c m a t r i x transformation T F = Q CQ where Q is a p r o d u c t of the o r t h o g o n a l s y m m e t r i c m a t r i c e s e n c o d e d in A. Then, g i v e n an a r r a y Z of c o l u m n v e c t o r s , TRBAK3 c o m p u t e s the m a t r i x p r o d u c t Qz. If the e i g e n v e c t o r s of F are c o l u m n s of the a r r a y Z, then TRBAK3 f o r m s the e i g e n v e c t o r s of C in their p l a c e . Since Q is o r t h o g o n a l , v e c t o r E u c l i d e a n n o r m s are p r e s e r v e d . This s u b r o u t i n e is a t r a n s l a t i o n of the A l g o l p r o c e d u r e TRBAK3 w r i t t e n and d i s c u s s e d in d e t a i l by M a r t i n , R e i n s c h , and W i l k i n s o n (I).

480

7.1-286

4. REFERENCES.

1)

Martin, R.S., Reinsch, C., and Wilkinson, J.H., H o u s e h o l d e r ' s T r i d i a g o n a l i z a t i o n of a Symmetric Matrix, Num. Math. 11,181-195 (1968). (Reprinted in H a n d b o o k 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.

See the section discussing testing real symmetric packed matrices.

of the codes

for

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

481

41 O0 I'O

0 0 0

0

0

0

C) 0

bo 0

H

N..

!

II

.,-~ ~:~ ~ 0

0

C~

~a

0

0

D~

0 t~

t~ 0~

0

tJ

~'0 II ~ . ~

~'- C')

C~

0

~I

t,~

II

C~

I---I ~

C~

~"~°

II

~ II 0

0

0

0

II II

b~

Hk.~

U

11 0

C~

H

0

°

O 0 O 0

O 0

0

"

H

v~

~ t n

Z

ba

H

C3

N

t~

t"z~

0

c~ t~

'7

7.1-288

NATS' P R O J E C T

EIGENSYSTEM

SUBROUTINE F277-2

A Fortran

PACKAGE

(EISPACK)

TREDI

IV S u b r o u t i n e to R e d u c e a Real S y m m e t r i c to a S y m m e t r i c T r i d i a g o n a l M a t r i x U s i n g Orthogonal Transformations.

May, July,

Matrix

1972 1975

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e TREDI r e d u c e s a real s y m m e t r i c m a t r i x to a s y m m e t r i c t r i d i a g o n a l m a t r i x u s i n g o r t h o g o n a l similarity transformations. This r e d u c e d f o r m is u s e d by o t h e r s u b r o u t i n e s to find the e i g e n v a l u e s a n d / o r e i g e n v e c t o r s of the o r i g i n a l m a t r i x . See s e c t i o n 2C for the s p e c i f i c routines.

2. USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

TREDI(NM,N,A,D,E,E2)

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

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

N

is an i n t e g e r input v a r i a b l e the o r d e r of the m a t r i x A. g r e a t e r than NM.

A

is a w o r k i n g p r e c i s i o n r e a l t w o - d i m e n s i o n a l variable with row dimension NM and c o l u m n d i m e n s i o n at least N. On input, A c o n t a i n s the s y m m e t r i c m a t r i x of o r d e r N to be r e d u c e d to t r i d i a g o n a l form. Only the f u l l lower t r i a n g l e of the m a t r i x n e e d be

483

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

7. 1 - 2 8 9

supplied. On o u t p u t , the s t r i c t lower t r i a n g l e of A contains information about the o r t h o g o n a ! t r a n s f o r m a t i o n s u s e d in the reduction. T h e f u l l u p p e r t r i a n g l e of A is u n a l t e r e d . See s e c t i o n 3 for the details. is a w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g the d i a g o n a l e l e m e n t s of the tridiagonal matrix. is a w o r k i n g p r e c i s i o n real o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g , in its last N-I positions, the s u b d i a g o n a l e l e m e n t s of the t r i d i a g o n a l matrix. The e l e m e n t E(1) is set to zero. E2

Bo

Error

is a w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g , in its last N-I positions, the s q u a r e s of the s u b d i a g o n a l e l e m e n t s of the t r i d i a g o n a l m a t r i x . The e l e m e n t E2(1) is set to zero. E2 n e e d n o t be d i s t i n c t from E (non-standard usage acceptable with at l e a s t t h o s e c o m p i l e r s i n c l u d e d in the c e r t i f i c a t i o n s t a t e m e n t ) , in w h i c h case no s q u a r e s are r e t u r n e d .

Conditions

and

Returns.

None.

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

and

Restrictions.

If all the e i g e n v a l u e s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e s h o u l d be f o l l o w e d by TQLI (F289), I M T Q L I (F291), or T Q L R A T (F235). If some of the e i g e n v a l u e s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e s h o u l d be f o l l o w e d by BISECT (F294) or T R I D I B (F237). If some of the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e s h o u l d be f o l l o w e d by T S T U R M (F293), or b y B I S E C T (F294) and T I N V I T (F223), or by T R I D I B (F237) and TINVIT, or by I M T Q L V (F234) and T I N V I T , and then by T R B A K I (F279).

484

7.1-290

If all the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x are d e s i r e d , s u b r o u t i n e T R E D 2 (F278) s h o u l d be used rather than TREDI to p e r f o r m the t r i d i a g o n a l r e d u c t i o n , and s h o u l d be f o l l o w e d by TQL2 (F290) or I M T Q L 2 (F292). If the m a t r i x has e l e m e n t s the s m a l l e r ones s h o u l d be

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

OF M E T H O D

AND

of w i d e l y v a r y i n g m a g n i t u d e s , in the top l e f t - h a n d corner.

ALGORITHM.

The t r i d i a g o n a l r e d u c t i o n is p e r f o r m e d in the f o l l o w i n g way. Starting with J=N, the e l e m e n t s in the J-th row to the left of the d i a g o n a l are f i r s t s c a l e d , to a v o i d p o s s i b l e u n d e r f l o w in the t r a n s f o r m a t i o n that m i g h t r e s u l t in s e v e r e departure from orthogonality. The sum of s q u a r e s SIGMA of these s c a l e d e l e m e n t s is n e x t f o r m e d . Then, a v e c t o r U and a scalar

H define

an

--

T U U/2

operator T P = I - UU

/H

w h i c h is o r t h o g o n a l and s y m m e t r i c and for w h i c h the similarity transformation PAP e l i m i n a t e s the e l e m e n t s in the J-th row of A to the left of the s u b d i a g o n a l and the s y m m e t r i c a l e l e m e n t s in the J-th column. The n o n - z e r o c o m p o n e n t s of U are the e l e m e n t s of the J-th row to the left of the d i a g o n a l w i t h the last of them a u g m e n t e d by the s q u a r e root of SIGMA p r e f i x e d by the s i g n of ~ the s u b d i a g o n a l element. By s t o r i n g the t r a n s f o r m e d s u b d i a g o n a l e l e m e n t in E(J) and not o v e r w r i t i n g the row e l e m e n t s e l i m i n a t e d in the t r a n s f o r m a t i o n , f u l l i n f o r m a t i o n about P is s a v e d for later u~e in YRBAKI. The t r a n s f o r m a t i o n sets E2(J) e q u a l to SIGMA e q u a l to the s q u a r e root of SIGMA p r e f i x e d by to that of the r e p l a c e d s u b d i a g o n a l e l e m e n t .

and sign

E(J) opposite

The a b o v e steps are r e p e a t e d on f u r t h e r r o w s of the transformed A in r e v e r s e o r d e r u n t i l A is r e d u c e d to t r i d i a g o n a l form; that is, r e p e a t e d for J = N-I,N-2,...,3. Only the e l e m e n t s in the lower t r i a n g l e of A are a c c e s s e d , and a l t h o u g h the d i a g o n a l e l e m e n t s are m o d i f i e d in the a l g o r i t h m , they are r e s t o r e d to their o r i g i n a l c o n t e n t s by the end of the s u b r o u t i n e , thus p r e s e r v i n g the f u l l u p p e r t r i a n g l e of A.

485

7.1-291

This s u b r o u t i n e is TREDI w r i t t e n and and W i l k i n s o n (I).

4.

REFERENCES°

I)

5.

a t r a n s l a t i o n of the A l g o l p r o c e d u r e d i s c u s s e d in d e t a i l by M a r t i n ~ R e i n s c h ,

M a r t i n , R~S°~ R e i n s c h , C.~ and W i l k i n s o n ~ J.H., Householder's Tridiagonalization of a S y m m e t r i c M a t r i x , Num. Math. 1 1 , 1 8 1 - 1 9 5 (1968). ( R e p r i n t e d in H a n d b o o k for A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , Jo H. W i l k i n s o n - C. R e i n s c h , C o n t r i b u t i o n II/2, 2 1 2 - 2 2 6 , Springer-Verlag~ 1971.)

CHECKOUT. A.

Test

Cases.

See the s e c t i o n d i s c u s s i n g real s y m m e t r i c m a t r i c e s .

testing

of

the

codes

for

B. A c c u ~ a c y o The a c c u r a c y of TREDI can b e s t be d e s c r i b e d in terms of its role in those paths of EISPACK w h i c h find e i g e n v a l u e s and e i g e n v e c t o r s of real s y m m e t r i c m a t r i c e s and m a t r i x s y s t e m s . In these paths, this s u b r o u t i n e is n u m e r i c a l l y s t a b l e (I). This s t a b i l i t y c o n t r i b u t e s to the p r o p e r t y of these paths that the c o m p u t e d e i g e n v a l u e s are the exact e i g e n v a l u e s of a m a t r i x or s y s t e m c l o s e to the o r i g i n a l m a t r i x or s y s t e m and the c o m p u t e d e i g e n v e c t o r s are c l o s e (but not n e c e s s a r i l y equal) to the e i g e n v e c t o r s of that m a t r i x 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

I00 C

C 120

130

140

150

D O i 0 0 1 = i, N D(I) = A(I,I) ********** F O R I = N S T E P -i U N T I L 1 DO -D O 3 0 0 II = i, N I = N + 1 - II L = I - i H=0.0 SCALE = 0.0 IF (L .LT. i) G O T O 1 3 0 ********** SCALE ROW (ALGOL TOL THEN NOT D O 1 2 0 K = i, L SCALE = SCALE + ABS(A(I,K)) IF ( S C A L E .NE. E(I) -- 0 . 0 E2(1) = 0.0 GO TO 290

0.0)

1 5 0 K = i, L A(!,K) = A(I,K) H = H + A(I,K) CONTINUE

GO

TO

140

DO

/

*

SCALE A(I,K)

E2(I) = SCALE * SCALE * F = A(I,L) G = -SIGN(SQRT(H),F) E(1) = SCALE * G H = H - F * G A(I,L) = F - G I F (n .EQ. I) G O T O 2 7 0 F = 0.0

H

DO

180

2 4 0 J = i, L G = 0.0 ********** FORM ELEMENT OF A*U D O 1 8 0 K = I, J C = C + A(J,K) * A(I,K) JPI = IF (L

200 220 240

J + i .LT. J P I )

GO

TO

DO 200 K = JPI, L G = G + A(K,J) * A(I,K) • ********* FORM ELEMENT OF P E(J) = G / H F = F + E(J) * A(I,J) CONTINUE

487

**********

220

**********

**********

NEEDED)

**********

7.1-293

C

H C

=

F

/

(~

+

H)

********** FORM REDUCED D O 2 6 0 J = I, L F = A(I,J) G = E(J) - H * F E(J) = G DO

260

260 K A(J,K) CONTINUE

270 280

DO 280 A(I,K)

290

300

K =

= =

A

i, J A(J,K)

= I, L SCALE *

**********

-

F

A(I,K)

H = D(i) D(I) = A(I,I) A(I,I) = CONTINUE RETURN END

488

*

E(K)

-

G

*

A(I,K)

7.1-294

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F278-2

PACKAGE

(EISPACK)

TRED2

A F o r t r a n IV S u b r o u t i n e to R e d u c e a R e a l S y m m e t r i c to a S y m m e t r i c T r i d i a g o n a l M a t r i x A c c u m u l a t i n g Orthogonal Transformations.

May, July,

Matrix the

1972 1975

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e TRED2 reduces a real symmetric m a t r i x to a s y m m e t r i c t r i d i a g o n a l m a t r i x u s i n g and accumulating orthogonal similarity transformations. This r e d u c e d f o r m and the t r a n s f o r m a t i o n m a t r i x are u s e d by subroutine TQL2 (F290) or IMTQL2 (F292) to find the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x .

2. USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

TRED2(NM,N,A,D,E,Z)

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

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

489

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

7.1-295

is a w o r k i n g p r e c i s i o n r e a l i n p u t twod i m e n s i o n a l v a r i a b l e w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at l e a s t N. A c o n t a i n s the s y m m e t r i c m a t r i x of o r d e r N to be r e d u c e d to t r i d i a g o n a l form. O n l y the f u l l l o w e r t r i a n g l e of the m a t r i x n e e d be supplied. is a w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g the d i a g o n a l e l e m e n t s of the tridiagonal matrix. is a w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g ~ in its l a s t N-I positions, the s u b d i a g o n a l e l e m e n t s of the t r i d i a g o n a l matrix. The e l e m e n t E(1) is set to zero. is a w o r k i n g p r e c i s i o n r e a l o u t p u t twodimensional variable with row dimension and c o l u m n d i m e n s i o n at l e a s t N. It c o n t a i n s the o r t h o g o n a l t r a n s f o r m a t i o n m a t r i x p r o d u c e d in the r e d u c t i o n to the t r i d i a g o n a l form.

Be

Error

Conditions

and

NM

Returns°

None.

C.

Applicability

and

Restrictions.

If all the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e s h o u l d be f o l l o w e d by T Q L 2 (F290) or I M T Q L 2 (F292). If s o m e o t h e r c o m b i n a t i o n of e i g e n v a l u e s and e i g e n v e c t o r s is d e s i r e d , s u b r o u t i n e T R E D I (F277) s h o u l d be u s e d r a t h e r t h a n TRED2 to p e r f o r m the tridiagonal reduction. If the m a t r i x has e l e m e n t s the s m a l l e r ones s h o u l d be Parameters

A

and

Z

need

490

of w i d e l y v a r y i n g m a g n i t u d e s , in the top l e f t - h a n d corner. not

be

distinct.

7.1-296

3.

DISCUSSION The all

OF M E T H O D

AND

ALGORITHM.

l o w e r t r i a n g l e of A subsequent operations

is i n i t i a l l y c o p i e d into are p e r f o r m e d on Z.

Z

and

The t r i d i a g o n a l r e d u c t i o n is p e r f o r m e d in the f o l l o w i n g way. Starting with J=N, the e l e m e n t s in the J-th row to the left of the d i a g o n a l are f i r s t s c a l e d , to a v o i d p o s s i b l e u n d e r f l o w in the t r a n s f o r m a t i o n that m i g h t r e s u l t in s e v e r e departure from orthogonality. The sum of s q u a r e s SIGMA of t h e s e s c a l e d e l e m e n t s is n e x t f o r m e d . Then, a v e c t o r U and a scalar T H = U U/2 define

an

operator T P = I - UU

/H

w h i c h is o r t h o g o n a l and s y m m e t r i c and for w h i c h the slmllarmty transformation PAP e l i m i n a t e s the e l e m e n t s in the J-th row of A to the left of the s u b d i a g o n a l and the s y m m e t r i c a l e l e m e n t s in the J-th column. °

°

The n o n - z e r o c o m p o n e n t s of U are the e l e m e n t s of the J-th row to the left of the d i a g o n a l w i t h the l a s t of them a u g m e n t e d by the s q u a r e r o o t of SIGMA p r e f i x e d by the s i g n of the s u b d i a g o n a l e l e m e n t . By s t o r i n g the t r a n s f o r m e d s u b d i a g o n a l e l e m e n t in E(J) and n o t o v e r w r i t i n g the row e l e m e n t s e l i m i n a t e d in the t r a n s f o r m a t i o n , f u l l i n f o r m a t i o n about P is s a v e d for l a t e r a c c u m u l a t i o n of t r a n s f o r m a t i o n s . The t r a n s f o r m a t i o n sets SIGMA p r e f i x e d by s i g n subdiagonal element.

E(J) e q u a l to the o p p o s i t e to that of

s q u a r e root of the r e p l a c e d

The a b o v e s t e p s are r e p e a t e d on f u r t h e r rows of the transformed A in r e v e r s e o r d e r u n t i l A is r e d u c e d to t r i d i a g o n a l form; that is, r e p e a t e d for J = N-I,N-2,...,3. F i n a l l y , the o r t h o g o n a l t r a n s f o r m a t i o n m a t r i x is a c c u m u l a t e d in Z as the p r o d u c t of the N-2 o p e r a t o r s d e f i n e d in the tridiagonal reduction. T h i s s u b r o u t i n e is a t r a n s l a t i o n of the A l g o l p r o c e d u r e TRED2 w r i t t e n and d i s c u s s e d in d e t a i l by M a r t i n , R e i n s c h , and W i l k i n s o n (I).

491

7.1-297

4. R E F E R E N C E S .

1)

M a r t i n , R.S., R e i n s c h , C., and W i l k i n s o n , J.H., Householder's Tridiagonalization of a S y m m e t r i c M a t r i x , Num. Math. 1 1 , 1 8 1 - 1 9 5 (1968). ( R e p r i n t e d in H a n d b o o k for A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , J. H. W i l k i n s o n - C. R e i n s c h , C o n t r i b u t i o n 11/2, 212-226, Springer-Verlag, 1971.)

5~ C H E C K O U T . A.

Test

Cases~

See the s e c t i o n d i s c u s s i n g real s y m m e t r i c m a t r i c e s .

testing

of

the

codes

for

B. A c c u r a c y . The a c c u r a c y of TRED2 can b e s t be d e s c r i b e d in terms of its r o l e in those paths of EISPACK w h i c h find e i g e n v a l u e s and e i g e n v e c t o r s of real s y m m e t r i c m a t r i c e s and m a t r i x systems. In these p a t h s , this s u b r o u t i n e is n u m e r i c a l l y s t a b l e (i). This stability contributes to the p r o p e r t y of these paths that the c o m p u t e d e i g e n v a l u e s are the exact e i g e n v a l u e s of a m a t r i x or s y s t e m close to the o r i g i n a l m a t r i x or s y s t e m and the c o m p u t e d e i g e n v e c t o r s are close (but not n e c e s s a r i l y equal) to the e i g e n v e c t o r s of that m a t r i x or system.

492

7.1-298

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

I 0 0 J = I, I Z(l,J) = A(I,J) CONTINUE

120

IF (N .EQ. I) G O T O 3 2 0 ********** FOR I=N STEP -i UNTIL 2 DO -D O 3 0 0 II = 2, N I = N + 2 - II L = I - 1 H = 0.0 SCALE = 0.0 IF (L ,LT. 2) G O T O 1 3 0 ********** SCALE ROW (ALGOL TOL THEN NOT D O 1 2 0 K = I, L SCALE = SCALE + ABS(Z(I,K))

130

IF ( S C A L E .NE. E(1) = Z(l,L) GO T O 2 9 0

140

DO

150

0.0)

GO

TO

140

1 5 0 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 DO

180

2 4 0 J = I, L Z(J,Z) = Z(I,J)

/ i

G = 0.0 ********** FORM ELEMENT OF A*U D O 1 8 0 K = i, J G = G + Z(J,K) * Z(I,K) JPI = IF (L

J + 1 .LT. J P I )

GO

TO

C 200

DO 200 K = JPI, L G = g + Z(K,J) * Z(I,K)

493

220

**********

**********

NEEDED)

**********

7.1-299

220 240

********** FORM ELEMENT OF E(J) = G / H F = F + E(J) * Z(l,J) CONTINUE

HH

=

F

/

(H

+

260

260 K Z(J,K) CONTINUE

= =

D(1) CONTINUE

320

D(1) = 0.0 ~(I) = o.o ********** ACCUMULATION D O 5 0 0 I = I, N L = I - i IF (D(I) oEQ. 0.0) 360 J G=0~0

=

I,

DO

360

380

360 K Z(K,J) CONTINUE

500

= =

F

DO

L

J

Z(J,I) CONTINUE

=

I,

OF

GO

*

E(K)

-

TRANSFORMATION

TO

380

L *

i, L Z(K,J)

GO

Z(I,J) 400

-

L

D(I) = Z(I,I) Z(I,i) = 1.0 IF (L . L T . I) 400

**********

G

*

Z(I,K)

H

D O 3 4 0 K = i, G = G + Z(I,K)

340

A

i, J Z(J,K)

290 300

DO

=

**********

H)

********** FORM REDUCED D O 2 6 0 J = I, L F = Z(I,J) G = E(J) - HH * F E(J) = G DO

P

=

0.0

=

0.0

TO

Z(K,J)

-

G

500

CONTINUE RETURN END

494

*

Z(K,I)

MATRICES

**********

7.1-300

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F228

PACKAGE

(EISPACK)

TRED3

A F o r t r a n IV S u b r o u t i n e to R e d u c e a R e a l S y m m e t r i c M a t r i x , S t o r e d as a O n e - D i m e n s i o n a l A r r a y , to a S y m m e t r i c Tridiagonal Matrix Using Orthogonal Transformations.

July,

1975

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e TRED3 r e d u c e s a real s y m m e t r i c m a t r i x , s t o r e d as a o n e - d i m e n s i o n a l array, to a s y m m e t r i c tridiagonal matrix using orthogonal similarity transformations. This r e d u c e d f o r m is u s e d by o t h e r s u b r o u t i n e s to find the e i g e n v a l u e s a n d / o r e i g e n v e c t o r s of the o r i g i n a l m a t r i x . See s e c t i o n 2C for the s p e c i f i c routines.

2. U S A G E . A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

TRED3(N,NV,A,D,E,E2)

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

is an i n t e g e r i n p u t v a r i a b l e the o r d e r of the m a t r i x A.

NV

is an i n t e g e r input v a r i a b l e set equal to the d i m e n s i o n of the a r r a y A as s p e c i f i e d in the D I M E N S I O N s t a t e m e n t for A in the calling program. NV m u s t be not less than N* (N+I) 12.

A

is a w o r k i n g p r e c i s i o n r e a l o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N*(N+I)/2. On input, A c o n t a i n s the lower t r i a n g l e of the s y m m e t r i c m a t r i x of order N to be r e d u c e d to t r i d i a g o n a l form, p a c k e d rowwise. For e x a m p l e if N=3, A should contain

495

set

equal

to

7.1-301

(A(i, I),A(2, i) ,A(2,2) ,A(3, I ) , A ( 3 , 2 ) ,A(3,3)) w h e r e the s u b s c r i p t s for e a c h e l e m e n t r e f e r to the row and c o l u m n of the e l e m e n t in the standard two-dimensional representation. On output, A c o n t a i n s i n f o r m a t i o n a b o u t the o r t h o g o n a l t r a n s f o r m a t i o n s u s e d in the reduction. See s e c t i o n 3 for the details. is a w o r k i n g p r e c i s i o n real o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g the d i a g o n a l e l e m e n t s of the tridiagonal matrix. is a w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g , in its last N-I positions, the s u b d i a g o n a l e l e m e n t s of the t r i d i a g o n a l matrix. The e l e m e n t E(1) is set to zero. E2

B.

Error

is a w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N c o n t a i n i n g , in its last N-I positions, the s q u a r e s of the s u b d i a g o n a l e l e m e n t s of the t r i d i a g o n a l m a t r i x . The e l e m e n t E2(1) is set to zero. E2 n e e d not be d i s t i n c t from E (non-standard usage acceptable with at l e a s t t h o s e c o m p i l e r s i n c l u d e d in the c e r t i f i c a t i o n s t a t e m e n t ) , in w h i c h case no s q u a r e s are r e t u r n e d .

Conditions

and

Returns.

None°

C.

Applicability

and

Restrictions.

If all the e i g e n v a l u e s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e s h o u l d be f o l l o w e d by TQLI (F289), I M T Q L I (F291), or T Q L R A T (F235). If some of the e i g e n v a l u e s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e s h o u l d be f o l l o w e d by BISECT (F294) or T R ! D I B (F237). If some of the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x are d e s i r e d , this s u b r o u t i n e s h o u l d be f o l l o w e d by T S T U R M (F293), or by B I S E C T (F294) and T I N V I T (F223), or by T R I D I B (F237) and TINVIT, or by I M T Q L V (F234) and T I N V I T , and then by T R B A K 3 (F229).

496

7.1-302

If all the e i g e n v a l u e s and e i g e n v e c t o r s of the o r i g i n a l m a t r i x are d e s i r e d , s u b r o u t i n e T R E D 2 (F278) s h o u l d be u s e d r a t h e r than TRED3 to p e r f o r m the t r i d i a g o n a l r e d u c t i o n , and s h o u l d be f o l l o w e d by TQL2 (F290) or I M T Q L 2 (F292). In this case, the p a c k e d f o r m of the m a t r i x c a n n o t be used, but the e i g e n v e c t o r s can s h a r e the s p a c e r e q u i r e d for the m a t r i x . If the m a t r i x has e l e m e n t s the s m a l l e r ones s h o u l d be

3.

DISCUSSION

OF M E T H O D

AND

of w i d e l y v a r y i n g at the top.

magnitudes,

ALGORITHM.

D i s c u s s i o n of the a l g o r i t h m is f a c i l i t a t e d if the m a t r i x is c o n s i d e r e d square. The i m p l e m e n t a t i o n , h o w e v e r , a c h i e v e s s i g n i f i c a n t s t o r a g e e c o n o m y by s p e c i f y i n g o n l y the lower t r i a n g l e to be s t o r e d and p a c k e d o n e - d i m e n s i o n a l l y . The t r i d i a g o n a l r e d u c t i o n is p e r f o r m e d in the f o l l o w i n g way. Starting with J=N, the e l e m e n t s in the J-th row to the left of the d i a g o n a l are f i r s t scaled, to a v o i d p o s s i b l e u n d e r f l o w in the t r a n s f o r m a t i o n that m i g h t r e s u l t in s e v e r e departure from orthogonality. The sum of s q u a r e s SIGMA of these s c a l e d e l e m e n t s is n e x t formed. Then, a v e c t o r U and a scalar T H

define

an

=

u

u/2

operator T P = I -UU

/H

w h i c h is o r t h o g o n a l and s y m m e t r i c and for w h i c h the similarity transformation PAP e l i m i n a t e s the e l e m e n t s in the J-th row of A to the left of the s u b d i a g o n a l and the s y m m e t r i c a l e l e m e n t s in the J-th column. The n o n - z e r o c o m p o n e n t s of U are the e l e m e n t s of the J-th r o w to the left of the d i a g o n a l w i t h the last of them a u g m e n t e d b y the s q u a r e r o o t of SIGMA p r e f i x e d by the s i g n of the s u b d i a g o n a l e l e m e n t . By s t o r i n g the t r a n s f o r m e d s u b d i a g o n a l e l e m e n t in E(J) and not o v e r w r i t i n g the r o w e l e m e n t s e l i m i n a t e d in the t r a n s f o r m a t i o n , f u l l i n f o r m a t i o n about P is s a v e d for later use in TRBAK3. The t r a n s f o r m a t i o n sets E2(J) e q u a l to SIGMA e q u a l to the s q u a r e r o o t of SIGMA p r e f i x e d by to that of the r e p l a c e d s u b d i a g o n a l element.

497

and sign

E(J) opposite

7.1-303

The a b o v e s t e p s are r e p e a t e d on f u r t h e r transformed A in r e v e r s e o r d e r u n t i l t r i d i a g o n a l form~ that is, r e p e a t e d for

rows of the A is r e d u c e d to J = N-I,N-2,...,3o

This s ~ b r o u t i n e is a t r a n s l a t i o n of the A l g o l p r o c e d u r e TRED3 w r i t t e n and d i s c u s s e d in d e t a i l by M a r t i n , R e i n s c h , and W i l k i n s o n (i).

4.

REFERENCES°

i)

5.

M a r t i n ~ R~So, R e i n s c h , C.~ and W i l k i n s o n , J.H., Householder's Tridiagonalization of a S y m m e t r i c M a t r i x , Num. Math. 1 1 , 1 8 1 - 1 9 5 (1968). ( R e p r i n t e d in H a n d b o o k for A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , Jo H~ W i l k i n s o n - C. R e i n s c h , C o n t r i b u t i o n 11/2, 2 1 2 - 2 2 6 , Springer-Verlag, 1971.)

CHECKOUT~ A.

Test

Cases~

See the s e c t i o n d i s c u s s i n g t e s t i n g real s y m m e t r i c p a c k e d m a t r i c e s .

of

the

codes

for

B. A c c u r a c y ° T h e a c c u r a c y of TRED3 can b e s t be d e s c r i b e d in terms of its r o l e in t h o s e p a t h s of EISPACK w h i c h find e i g e n v a l u e s and e i g e n v e c t o r s of r e a l s y m m e t r i c p a c k e d matrices. In t h e s e p a t h s , this s u b r o u t i n e is n u m e r i c a l l y s t a b l e (I). This s t a b i l i t y c o n t r i b u t e s to the p r o p e r t y of t h e s e p a t h s that the c o m p u t e d e i g e n v a l u e s are the e x a c t e i g e n v a l u e s of a m a t r i x c l o s e to the o r i g i n a l m a t r i x and the c o m p u t e d e i g e n v e c t o r s are c l o s e (but n o t n e c e s s a r i l y equal) to the e i g e n v e c t o r s of that m a t r i x .

498

7.1-304

SUBROUTINE

TRED3(N,NV,A,D,E,E2)

INTEGER I,J,K,L,N,II,IZ,JK,NV R E A L A ( N V ) , D (N), E (N), E 2 (N) REAL F,G,H,HH,SCALE REAL SQRT,ABS,SIGN

120

130

********** FOR I=N STEP -I UNTIL 1 DO -DO 3 0 0 I I = i, N I = N + i - II L = I - 1 IZ = (I * L) / 2 H = 0.0 SCALE = 0.0 IF (L . L T . i) G O T O 1 3 0 ********** SCALE ROW (ALGOL TOL THEN NOT D O 1 2 0 K = I, L IZ = IZ + 1 D(K) = A(IZ) SCALE = SCALE + ABS(D(K)) CONTINUE IF ( S C A L E .NE. E(I) = 0.0 E2(1) = 0.0 GO TO 290

0.0)

GO

TO

140

C 140

150

DO

1 5 0 K = I, L D(K) = D(K) / SCALE H = H + D(K) * D(K) CONTINUE

E2(1) = SCALE * SCALE * H F = D (L) G = - S I G N ( S Q R T (H), F) E(1) = SCALE * G H = H - F * G D(L) = F - g A(IZ) = SCALE * D(L) I F (L .EQ. i) G O T O 2 9 0 F = 0.0 DO

180

2 4 0 J = i, L G = 0.0 J K = (J * ( J - l ) ) / 2 • ********* FORM ELEMENT OF A*U D O 1 8 0 K = i, L JK = JK + 1 IF (K . G T . J) J K = J K G = G + A(JK) * D(K) CONTINUE

499

**********

+

K

-

2

**********

NEEDED)

**********

7.1-305

240

********** FORM ELEMENT OF E(J) = G / H F = F + E(J) * D(J) CONTINUE

HH

=

F

/

(H

+

260 290 300

260 K = JK = JK A(JK) = CONTINUE D(1) = A(IZ+!) CONTINUE

A(IZ+I) = SCALE

**********

H)

JK = 0 ********** FORM REDUCED D O 2 6 0 J = I, L F = D(J) G = E(J) - HH * F E(J) = G DO

P

i, J + 1 A(JK)

*

A

-

**********

F

*

SQRT(H)

RETURN END

500

E(K)

-

G

*

D(K)

7.1-306

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F237

A Fortran

PACKAGE

(EISPACK)

TRIDIB

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

July,

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

1975

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e e i g e n v a l u e s of a s y m m e t r i c specified boundary indices

TRIDIB determines those tridiagonal matrix between using Sturm sequencing.

2. USAGE. A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

TRIDIB(N,EPSI,D,E,E2,LB,UB, MII,M,W, IND,IERR,RV4,RV5)

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

set

equal

to

EPSI

is a w o r k i n g p r e c i s i o n r e a l v a r i a b l e . On input, it s p e c i f i e s an a b s o l u t e error t o l e r a n c e for the c o m p u t e d e i g e n v a l u e s . If the input EPSI is n o n - p o s i t i v e , it is r e s e t to a d e f a u l t v a l u e d e s c r i b e d in s e c t i o n 2C.

D

is a w o r k i n g p r e c i s i o n r e a l i n p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g the d i a g o n a l e l e m e n t s of the symmetric tridiagonal matrix. is a w o r k i n g p r e c i s i o n real i n p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N c o n t a i n i n g , in its last N-I positions, the s u b d i a g o n a l e l e m e n t s of the s y m m e t r i c tridiagonal matrix. E(1) is a r b i t r a r y .

501

7,1-307

E2

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

LB,UB

are w o r k i n g p r e c i s i o n r e a l o u t p u t v a r i a b l e s set to the l o w e r and u p p e r e n d p o i n t s , r e s p e c t i v e l y , of an i n t e r v a l c o n t a i n i n g e x a c t l y the d e s i r e d e i g e n v a l u e s . See s e c t i o n 2C for f u r t h e r d e t a i l s .

MII

is an i n t e g e r i n p u t v a r i a b l e s p e c i f y i n g the l o w e r i n d e x of the set of d e s i r e d ( s m a l l e s t ) eigenvalues.

M

is an i n t e g e r i n p u t v a r i a b l e s p e c i f y i n g the n u m b e r of e i g e n v a l u e s d e s i r e d . The upper index, M 2 2 , of the set is t h e n o b t a i n e d i n t e r n a l l y as M22=MII+M-I.

W

is a w o r k i n g p r e c i s i o n real o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t M c o n t a i n i n g the M e i g e n v a l u e s of the symmetric tridiagonal matrix between boundary indices MII and M22. The e i g e n v a l u e s are in a s c e n d i n g o r d e r in W.

IND

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

IERR

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

RV4,RV5

to is

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

502

7.1-308

B.

Error

Conditions

and

Returns.

If e x a c t l y m u l t i p l e e i g e n v a l u e s p r e v e n t the d e t e r m i n a t i o n of an a p p r o p r i a t e LB, TRIDIB terminates w i t h no e i g e n v a l u e s c o m p u t e d , and IERR is set to 3*N+I. In this case, the r e t u r n e d v a l u e s of LB and UB d e f i n e the G e r s c h g o r i n i n t e r v a l c o n t a i n i n g all the e i g e n v a l u e s of the m a t r i x . If, a f t e r d e t e r m i n i n g LB, e x a c t l y m u l t i p l e e i g e n v a l u e s p r e v e n t the d e t e r m i n a t i o n of an a p p r o p r i a t e UB, TRIDIB t e r m i n a t e s w i t h no e i g e n v a l u e s c o m p u t e d , and IERR is set to 3"N+2. In this case, the r e t u r n e d v a l u e of UB is the u p p e r b o u n d for the G e r s c h g o r i n i n t e r v a l c o n t a i n i n g all the e i g e n v a l u e s of the m a t r i x . If n e i t h e r of the is set to zero.

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

and

above

error

conditions

occurs,

IERR

Restrictions.

To d e t e r m i n e some of the e i g e n v a l u e s of a full s y m m e t r i c matrix, TRIDIB s h o u l d be p r e c e d e d by T R E D I (F277) to p r o v i d e a s u i t a b l e s y m m e t r i c t r i d i a g o n a l m a t r i x for TRIDIB. To d e t e r m i n e some of the e i g e n v a l u e s of a c o m p l e x Hermitian matrix, TRIDIB s h o u l d be p r e c e d e d by HTRIDI (F284) to p r o v i d e a s u i t a b l e real s y m m e t r i c t r i d i a g o n a l m a t r i x for TRIDIBo Some of the e i g e n v a l u e s of c e r t a i n n o n - s y m m e t r i c t r i d i a g o n a l m a t r i c e s can be c o m p u t e d u s i n g the c o m b i n a t i o n of FIGI (F280) and TRIDIB. See F280 for the d e s c r i p t i o n of this s p e c i a l class of m a t r i c e s . For these m a t r i c e s , TRIDIB s h o u l d be p r e c e d e d by FIGI to p r o v i d e a s u i t a b l e s y m m e t r i c m a t r i x for TRIDIB. To d e t e r m i n e e i g e n v e c t o r s a s s o c i a t e d w i t h the c o m p u t e d eigenvalues, TRIDIB s h o u l d be f o l l o w e d by TINVIT (F223) and the a p p r o p r i a t e b a c k t r a n s f o r m a t i o n s u b r o u t i n e -T R B A K I (F279) after TREDI, HTRIBK (F285) after HTRIDI, or B A K V E C (F281) after FIGI. The s u b r o u t i n e s TQLI (F289), IMTQLI (F291), and T Q L R A T (F235) d e t e r m i n e all the e i g e n v a l u e s of a s y m m e t r i c t r i d i a g o n a l m a t r i x f a s t e r than TRIDIB determines 25 p e r c e n t of them. Hence~ if m o r e than 25 p e r c e n t of t h e m are d e s i r e d , it is r e c o m m e n d e d that TQLI, IMTQLI, or TQLRAT be used.

503

7.1-309

If it is p r e f e r r e d to s p e c i f y the i n t e r v a l (LB,UB) to be s e a r c h e d for e i g e n v a l u e s r a t h e r than the b o u n d a r y indices MII and M22, use s u b r o u t i n e B I S E C T (F294) instead. The p r e c i s i o n of the c o m p u t e d e i g e n v a l u e s is c o n t r o l l e d t h r o u g h the p a r a m e t e r EPSI. To o b t a i n e i g e n v a l u e s a c c u r a t e to w i t h i n a c e r t a i n a b s o l u t e error, EPSI s h o u l d be set to that error. In p a r t i c u l a r , if MACHEP d e n o t e s the r e l a t i v e m a c h i n e p r e c i s i o n ~ then to o b t a i n the e i g e n v a l u e s to an a c c u r a c y c o m m e n s u r a t e w i t h s m a l l r e l a t i v e p e r t u r b a t i o n s of the o r d e r of MACHEP in the m a t r i x e l e m e n t s , it is e n o u g h for m o s t t r i d i a g o n a l m a t r i c e s that EPSI be a p p r o x i m a t e l y MACHEP times a n o r m of the m a t r i x . But s o m e m a t r i c e s r e q u i r e a s m a l l e r EPSI for this a c c u r a c y , p e r h a p s as s m a l l as MACHEP times the e i g e n v a l u e of s m a l l e s t m a g n i t u d e in (LB,UB). Note, h o w e v e r , that if EPSI is s m a l l e r than r e q u i r e d , TRIDIB w i l l p e r f o r m u n n e c e s s a r y b i s e c t i o n steps to d e t e r m i n e the e i g e n v a l u e s . For f u r t h e r d i s c u s s i o n of EPSI, see r e f e r e n c e (i). If the i n p u t EPSI is n o n - p o s i t i v e , TRIDIB r e s e t s it, for e a c h s u b m a t r i x , to -MACHEP times the l - n o r m of the s u b m a t r i x and u s e s its m a g n i t u d e . This v a l u e is t e n t a t i v e l y c o n s i d e r e d a d e q u a t e for c o m p u t i n g the e i g e n v a l u e s to an a c c u r a c y c o m m e n s u r a t e w i t h s m a l l r e l a t i v e p e r t u r b a t i o n s of the o r d e r of MACHEP in the matrix elements.

3.

DISCUSSION

OF M E T H O D

AND

ALGORITHM.

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

by

the m e t h o d

of b i s e c t i o n

The c a l c u l a t i o n s p r o c e e d as f o l l o w s . First, the s u b d i a g o n a l e l e m e n t s are t e s t e d for n e g l i g i b i l i t y . If an e l e m e n t is c o n s i d e r e d n e g l i g i b l e , its s q u a r e is set to zero, and so the m a t r i x s p l i t s into a d i r e c t sum of s u b m a t r i c e s . At the same time, the G e r s c h g o r i n i n t e r v a l k n o w n to c o n t a i n all the e i g e n v a l u e s of the m a t r i x is d e t e r m i n e d . Then, an i n t e r v a l (LB,UB) is d e t e r m i n e d , u s i n g a b i s e c t i o n p r o c e s s p r o c e e d i n g f r o m the G e r s c h g o r i n b o u n d s , that c o n t a i n s e x a c t l y eigenvalues MII through M22. N e x t , a s u b m a t r i x is e x a m i n e d for its e i g e n v a l u e s in the interval (LB,UB). Its G e r s c h g o r i n i n t e r v a l is d e t e r m i n e d and u s e d to r e f i n e the i n t e r v a l (LB,UB). If the input EPSI is n o n - p o s i t i v e , it is r e s e t to the d e f a u l t v a l u e d e s c r i b e d in s e c t i o n 2C. Then, s u b i n t e r v a l s , each e n c l o s i n g an e i g e n v a l u e in (LB,UB), are s h r u n k u s i n g a b i s e c t i o n p r o c e s s

504

7.1-310

u n t i l the e n d p o i n t s of e a c h s u b i n t e r v a l are close e n o u g h to be a c c e p t e d as an e i g e n v a l u e of the s u b m a t r i x . H e r e the e n d p o i n t s of each s u b i n t e r v a l are close e n o u g h w h e n they differ by less than MACHEP times twice the sum of the m a g n i t u d e s of the e n d p o i n t s plus the a b s o l u t e error t o l e r a n c e EPSI. The s u b m a t r i x e i g e n v a l u e s are then m e r g e d found e i g e n v a l u e s into an o r d e r e d set. The above steps are r e p e a t e d eigenvalues between boundary computed.

on each indices

with

submatrix MII and

previously

until M22

all are

This s u b r o u t i n e is a t r a n s l a t i o n of the A l g o l p r o c e d u r e BISECT w r i t t e n and d i s c u s s e d in d e t a i l by Barth, M a r t i n , W i l k i n s o n (I). A similar Algol procedure TRISTURM is d i s c u s s e d in d e t a i l by P e t e r s and W i l k i n s o n (2); a s u b s e t it has b e e n t r a n s l a t e d as s u b r o u t i n e B I S E C T (F294).

the

and of

4. R E F E R E N C E S .

i)

Barth, W., M a r t i n , R.S., and W i l k i n s o n , J.H., C a l c u l a t i o n of the E i g e n v a l u e s of a S y m m e t r i c T r i d i a g o n a l M a t r i x by the M e t h o d of B i s e c t i o n , Num. Math. 9 , 3 8 6 - 3 9 3 (1967). ( R e p r i n t e d in H a n d b o o k for A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , J. H. W i l k i n s o n - C. R e i n s c h , C o n t r i b u t i o n 11/5, 249-256, Springer-Verlag, 1971.)

2)

Peters, G. and W i l k i n s o n , J.H., The C a l c u l a t i o n of S p e c i f i e d E i g e n v e c t o r s by I n v e r s e I t e r a t i o n , H a n d b o o k A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , J. H. W i l k i n s o n - C. R e i n s c h , C o n t r i b u t i o n 11/18, 418-439, Springer-Verlag, 1971.

5. C H E C K O U T . A.

Test

Cases.

See the s e c t i o n d i s c u s s i n g t e s t i n g of the codes for c o m p l e x H e r m i t i a n , real s y m m e t r i c , real s y m m e t r i c t r i d i a g o n a l , and c e r t a i n real n o n - s y m m e t r i c tridiagonal matrices.

505

for

7.1-311

B. A c c u r a c y ~ The s u b r o u t i n e TRIDIB is n u m e r i c a l l y s t a b l e (1,2); that is, the c o m p u t e d e i g e n v a l u e s are close to those of the o r i g i n a l m a t r i x . In a d d i t i o n , they are the exact e i g e n v a l u e s of a m a t r i x close to the o r i g i n a l 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 ********** DO

MACHEP IS A THE RELATIVE

MACHINE DEPENDENT PARAMETER SPECIFYING PRECISION OF F L O A T I N G POINT ARITHMETIC.

?

LOOK FOR INTERVAL I, N

SMALL SUB-DIAGONAL CONTAINING ALL THE

40 I = XI = U U = 0.0 IF (I .NE. N) U = A B S ( E ( I + I ) ) XU = AMINI(D(1)-(XI+U),XU) X0 = AMAXI(D(1)+(XI+U),X0) IF (I .EQ. I) G O T O 20 IF ( A B S ( E ( 1 ) ) .GT. M A C H E P * X G O T O 40 20 E2(1) = 0.0 40 CONTINUE

50

60 65 70

ENTRIES AND EIGENVALUES

(ABS(D(1))

+

ABS(D(I-I))))

XI = A M A X I ( A B S ( X U ) , A B S ( X 0 ) ) * MACHEP * FLOAT(N) XU = XU - XI TI = X U X0 = X0 + X1 T2 = X0 • ********* DETERMINE AN INTERVAL CONTAINING EXACTLY THE DESIRED EIGENVALUES ********** P = i Q = N M1 = MII - i IF (MI .EQ. 0) G O T O 75 ISTURM = i V = XI Xl = ( X U + X 0 ) * 0.5 IF (XI .EQ. V) G O T O 9 8 0 GO TO 320 IF (S - M I ) 6 5 , 73, 70 X U = XI G O T O 50 X 0 = X1 G O T O 50

507

DETERMINE **********

AN

7. 1 - 3 1 3

73 75

80 85 90

i00

X U = X1 T1 = X 1 M22 = M1 + M IF ( M 2 2 .EQo N) G O T O 9 0 X 0 = T2 ISTURM = 2 GO TO 50 IF (S - M 2 2 ) 65, 8 5 , 70 T2 = XI Q = 0 R = 0 ********** ESTABLISH AND PROCESS NEXT INTERVAL BY THE GERSCHGORIN IF (R .EQ, M) G O T O i 0 0 1 TAG = TAG + i P = Q + i xu = D(P) XO = D(P) U = 0o0

SUBMATRIX, REFINING BOUNDS **********

DO

Ii0

120 140

180

200

220

1 2 0 Q = P, N X1 = U U = 0.0 V = 0.0 IF (Q .EQ. N) G O T O i i 0 U = ABS(E(Q+I)) V = E2(Q+I) X U = A M I N I (D (Q) - ( X l + U ) , x u ) x0 = AMAXI(D(Q)+(XI+U),X0) IF (V .EQo 0 , 0 ) G O T O 1 4 0 CONTINUE

XI = A M A X I ( A B S ( X U ) , A B S ( X 0 ) ) * MACHEP IF ( E P S I ,LE. 0 . 0 ) E P S I = - X I IF (P .NE. Q) G O T O i S 0 • ********* CHECK FOR ISOLATED ROOT WITHIN IF (TI ,GT. D ( P ) .OR. D ( P ) .GE. T 2 ) G O T O MI = P M2 = P R V 5 (e) = D ( P ) GO TO 900 XI = X I * F L O A T ( Q - P + I ) L B = A M A X I (TI , X U - X I ) UB = AMINI(T2,X0+XI) XI = LB ISTURM = 3 GO TO 320 MI = S + 1 X1 = UB I STURM = 4 GO TO 320 M2 = S IF (MI .GT. M 2 ) G O T O 9 4 0

508

INTERVAL 940

**********

7.1-314

********** FIND X0 = UB ISTURM = 5

ROOTS

BY

BISECTION

**********

DO

240 C C C 250 C

260

240 I = MI, M2 RV5(1) = UB RV4(1) = LB CONTINUE ********** LOOP FOR K-TH EIGENVALUE F O R K = M 2 S T E P -i U N T I L M 1 D O - (-DO- NOT USED TO LEGALIZE COMPUTEE-GO-TO) K = M2 XU = LB ********** F O R I = K S T E P -i U N T I L M I D O - - * * * * * * * * * * D O 2 6 0 II = M I , K I = M I + K - II IF (XU .GE. R V 4 ( 1 ) ) GO TO 260 XU = R V 4 (I) GO T O 2 8 0 CONTINUE

**********

C 280

C

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

325 330 340

360

380

400

3 4 0 1 = P, Q IF (U .NE. 0 . 0 ) G O T O 3 2 5 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 ********** I F (S .GE. K) G O T O 4 0 0 XU = Xl IF (S .GE. M I ) G O T O 3 8 0 RV4(MI) = El GO TO 300 RV4(S+I) = XI IF ( R V S ( S ) .GT. XI) RVS(S) = El GO TO 300 X O = X1 GO TO 300

509

7.1-315

C 420

********** RV5(K)

=

= K I IF (K . G E . **********

K-TH X1

EIGENVALUE

FOUND

**********

K

C

MI) GO TO 250 ORDER EIGENVALUES TAGGED WITH THEIR SUBMATRIX ASSOCIATIONS **********

C

900

S R J K DO

= = = =

R R + 1 M1

M2

-

9 2 0 L = i, I F (J . G T . I F (K . G T . IF (RV5(K)

M1

+

1

R S) G O T O 9 1 0 M2) GO TO 940 .GE. W(L)) GO

TO

915

DO

905 910

915 920 940

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

W(L) = RV5(K) IND(L) = TAG K = K + i GO TO 920 7 = J + I CONTINUE I F (q ~ L T . GO TO i001 **********

980 IERR = 3 i001LB = TI UB = T2 RETURN END

*

N)

GO

TO

I00

SET ERROR -- INTERVAL CANNOT BE EXACTLY THE DESIRED EIGENVALUES N + ISTURM

510

FOUND CONTAINING **********

7.1-316

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F293-2

PACKAGE

(EISPACK)

TSTURM

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

May, July,

and

1972 1975

i. P U R P O S E . The F o r t r a n IV s u b r o u t i n e TSTURM d e t e r m i n e s those e i g e n v a l u e s of a s y m m e t r i c t r i d i a g o n a l m a t r i x in a s p e c i f i e d i n t e r v a l and their c o r r e s p o n d i n g e i g e n v e c t o r s , u s i n g S t u r m s e q u e n c i n g and i n v e r s e i t e r a t i o n .

2. U S A G E . A.

Calling The

Sequence.

SUBROUTINE SUBROUTINE

statement

is

TSTURM(NM,N,EPSI,D,E,E2,LB,UB, MM,M,W,Z,IERR,RVI,RV2,RV3, RV4,RV5,RV6)

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

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

EPS 1

set e q u a l to m u s t be not

is a w o r k i n g p r e c i s i o n real v a r i a b l e . On input, it s p e c i f i e s an a b s o l u t e e r r o r t o l e r a n c e for the c o m p u t e d e i g e n v a l u e s . If MACHEP d e n o t e s the r e l a t i v e m a c h i n e p r e c i s i o n , then EPSI s h o u l d be c h o s e n so that the a c c u r a c y of these e i g e n v a l u e s is

511

7.1-317

commensurate with relative perturbations the o r d e r of MACHEP in the m a t r i x elements. If the input EPSI is n o n p o s i t i v e , it is r e s e t to a d e f a u l t v a l u e d e s c r i b e d in s e c t i o n 2C.

of

is a w o r k i n g p r e c i s i o n r e a l i n p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least N c o n t a i n i n g the d i a g o n a l e l e m e n t s of the symmetric tridiagonal matrix. is a w o r k i n g p r e c i s i o n real i n p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N c o n t a i n i n g , in its last N-I positions, the s u b d i a g o n a l e l e m e n t s of the s y m m e t r i c tridiagonal matrix. E(1) is a r b i t r a r y . E2

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

LB,UB

are w o r k i n g p r e c i s i o n real i n p u t v a r i a b l e s s p e c i f y i n g the l o w e r and u p p e r e n d p o i n t s , r e s p e c t i v e l y , of the i n t e r v a l to be s e a r c h e d for the e i g e n v a l u e s . If LB is not less than UB, TSTURM c o m p u t e s no e i g e n v a l u e s or e i g e n v e c t o r s . See s e c t i o n 2C for f u r t h e r details.

MM

is an i n t e g e r i n p u t v a r i a b l e set e q u a l to an u p p e r b o u n d for the n u m b e r of e i g e n v a l u e s in the i n t e r v a l (LB,UB). is an i n t e g e r the n u m b e r of the i n t e r v a l

o u t p u t v a r i a b l e set e q u a l to e i g e n v a l u e s f o u n d to lie in (LB,UB).

is a w o r k i n g p r e c i s i o n r e a l o u t p u t oned i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least MM c o n t a i n i n g the M e i g e n v a l u e s of the s y m m e t r i c t r i d i a g o n a l m a t r i x in the i n t e r v a l (LB,UB). If the m a t r i x does n o t s p l i t into s u b m a t r i c e s , the e i g e n v a l u e s are in a s c e n d i n g o r d e r in W. If the m a t r i x does split, the e i g e n v a l u e s for e a c h s u b m a t r i x are in a s c e n d i n g o r d e r in W.

512

7.1-318

is a w o r k i n g p r e c i s i o n r e a l o u t p u t twodimensional variable with row dimension NM and c o l u m n d i m e n s i o n at l e a s t MM. It contains M o r t h o n o r m a l e i g e n v e c t o r s of the symmetric tridiagonal matrix corresponding to the M e i g e n v a l u e s in W. IERR

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

to is

RVI,RV2,RV3 are w o r k i n g p r e c i s i o n real t e m p o r a r y o n e d i m e n s i o n a l v a r i a b l e s of d i m e n s i o n at l e a s t N u s e d to s t o r e the m a i n d i a g o n a l and the two a d j a c e n t d i a g o n a l s of the t r i a n g u l a r m a t r i x p r o d u c e d in the i n v e r s e i t e r a t i o n process. RV4,RVS,RV6 are w o r k i n g p r e c i s i o n r e a l t e m p o r a r y oned i m e n s i o n a l v a r i a b l e s of d i m e n s i o n at l e a s t N. RV4 and RV5 h o l d the l o w e r and u p p e r b o u n d s for the e i g e n v a l u e s in the b i s e c t i o n process. In a d d i t i o n , RV4 h o l d s the m u l t i p l i e r s of the G a u s s i a n e l i m i n a t i o n step in the i n v e r s e i t e r a t i o n p r o c e s s . RV6 h o l d s the a p p r o x i m a t e e i g e n v e c t o r s in this process.

B.

Error

Conditions

and

Returns.

If M exceeds MM, TSTURM t e r m i n a t e s w i t h no e i g e n v a l u e s or e i g e n v e c t o r s c o m p u t e d , and IERR is set to 3*N+I. In this case, the o u t p u t p a r a m e t e r M is the n u m b e r of e i g e n v a l u e s f o u n d to lie in (LB,UB). If m o r e t h a n 5 i t e r a t i o n s are r e q u i r e d to d e t e r m i n e an eigenvector, TSTURM terminates with IERR set to 4*N+R, w h e r e R is the i n d e x of the e i g e n v e c t o r for w h i c h the f a i l u r e o c c u r s . The e i g e n v a l u e s and e i g e n v e c t o r s in the W and Z a r r a y s s h o u l d be c o r r e c t for i n d i c e s 1,2,...~R-I. If M does not e x c e e d MM and all the determined within 5 iterations, IERR

513

e i g e n v e c t o r s are is set to zero.

7. 1-319

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

and

Restrictions.

To d e t e r m i n e some of the e i g e n v a l u e s and e i g e n v e c t o r s of a full symmetric matrix, TSTURM s h o u l d be p r e c e d e d by TREDI (F277) to p r o v i d e a s u i t a b l e s y m m e t r i c t r i d i a g o n a l m a t r i x for TSTURM. It s h o u l d then be f o l l o w e d by T R B A K I (F279) to b a c k t r a n s f o r m the eigenvectors from TSTURM into t h o s e of the o r i g i n a l matrix. To d e t e r m i n e s o m e of the e i g e n v a l u e s and e i g e n v e c t o r s of a complex Hermitian matrix, TSTURM s h o u l d be p r e c e d e d by H T R I D I (F284) to p r o v i d e a s u i t a b l e r e a l s y m m e t r i c t r i d i a g o n a l m a t r i x for TSTURM. It s h o u l d then be f o l l o w e d by H T R I B K (F285) to b a c k t r a n s f o r m the eigenvectors from TSTURM into t h o s e of the o r i g i n a l matrix. Some of the e i g e n v a l u e s and e i g e n v e c t o r s of c e r t a i n n o n s y m m e t r i c t r i d i a g o n a l m a t r i c e s can be c o m p u t e d u s i n g the c o m b i n a t i o n of FIGI (F280), T S T U R M , and BAKVEC (F281). See F280 for the d e s c r i p t i o n of this s p e c i a l class of m a t r i c e s . For t h e s e m a t r i c e s , TSTURM should be p r e c e d e d by FIGI to p r o v i d e a s u i t a b l e s y m m e t r i c m a t r i x for TSTURM. It s h o u l d then be f o l l o w e d by BAKVEC to b a c k t r a n s f o r m the e i g e n v e c t o r s f r o m TSTURM into those of the o r i g i n a l m a t r i x . The i n t e r v a l (LB,UB) is f o r m a l l y h a l f - o p e n , not i n c l u d i n g the u p p e r e n d p o i n t UB. H o w e v e r , b e c a u s e of r o u n d i n g e r r o r s , the true e i g e n v a l u e s v e r y c l o s e to the e n d p o i n t s of the i n t e r v a l m a y be e r r o n e o u s l y c o u n t e d or missed. The i n p u t i n t e r v a l (LB,UB) m a y be r e f i n e d i n t e r n a l l y to a s m a l l e r i n t e r v a l k n o w n to c o n t a i n all the e i g e n v a l u e s in (LB,UB). This i n s u r e s that TSTURM w i l l not p e r f o r m u n n e c e s s a r y b i s e c t i o n steps to d e t e r m i n e the e i g e n v a l u e s in (LB,UB). The c o m p u t a t i o n of the e i g e n v e c t o r s by i n v e r s e i t e r a t i o n r e q u i r e s that the p r e c i s i o n of the e i g e n v a l u e s be c o m m e n s u r a t e w i t h s m a l l r e l a t i v e p e r t u r b a t i o n s of the o r d e r of MACHEP in the m a t r i x e l e m e n t s . For most s y m m e t r i c t r i d i a g o n a l m a t r i c e s , it is e n o u g h that the absolute error EPSI in the e i g e n v a l u e s for w h i c h e i g e n v e c t o r s are d e s i r e d be a p p r o x i m a t e l y MACHEP times a n o r m of the m a t r i x . But some m a t r i c e s r e q u i r e a smaller EPSI, p e r h a p s as s m a l l as MACHEP times the e i g e n v a l u e of s m a l l e s t m a g n i t u d e in the i n t e r v a l (LB,UB). N o t e , h o w e v e r , that if EPSI is s m a l l e r than necessary, TSTURM will perform unnecessary bisection s t e p s to d e t e r m i n e the e i g e n v a l u e s . For f u r t h e r d i s c u s s i o n of EPSI, see r e f e r e n c e (2).

514

7.1-320

If the i n p u t EPSI is n o n - p o s i t i v e , TSTURM r e s e t s it, for each s u b m a t r i x , to -MACHEP times the 1 - n o r m of the s u b m a t r i x and u s e s its m a g n i t u d e . This v a l u e is c o n s i d e r e d a d e q u a t e for m o s t s y m m e t r i c t r i d i a g o n a l m a t r i c e s and is r e c o m m e n d e d for use g e n e r a l l y . If TSTURM t e r m i n a t e s w i t h a v e c t o r e r r o r exit, a s m a l l e r EPSI m a y be m o r e s u c c e s s f u l .

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

OF M E T H O D

AND

ALGORITHM.

The e i g e n v a l u e s are d e t e r m i n e d by a p p l i e d to the S t u r m s e q u e n c e and d e t e r m i n e d by i n v e r s e i t e r a t i o n .

the m e t h o d of b i s e c t i o n the e i g e n v e c t o r s are

The c a l c u l a t i o n s p r o c e e d as f o l l o w s . First, the s u b d i a g o n a l e l e m e n t s are tested for n e g l i g i b i l i t y . If an e l e m e n t is c o n s i d e r e d n e g l i g i b l e , its s q u a r e is set to zero, and so the m a t r i x s p l i t s into a d i r e c t sum of s u b m a t r i c e s . Then, the S t u r m s e q u e n c e for the e n t i r e m a t r i x is e v a l u a t e d at UB and LB g i v i n g the n u m b e r of e i g e n v a l u e s of the m a t r i x less t h a n UB and LB respectively. The d i f f e r e n c e is the n u m b e r of e i g e n v a l u e s in (LB,UB). Next, a s u b m a t r i x is e x a m i n e d for its e i g e n v a l u e s in the interval (LB,UB). The G e r s c h g o r i n i n t e r v a l , k n o w n to c o n t a i n all the e i g e n v a l u e s , is d e t e r m i n e d and u s e d to r e f i n e the i n p u t i n t e r v a l (LB,UB). If the input EPSI is n o n p o s i t i v e , it is reset to the d e f a u l t v a l u e d e s c r i b e d in s e c t i o n 2C. Then, s u b i n t e r v a l s , each e n c l o s i n g an e i g e n v a l u e in (LB,UB), are s h r u n k u s i n g a b i s e c t i o n p r o c e s s u n t i l the e n d p o i n t s of each s u b i n t e r v a l are c l o s e e n o u g h to be a c c e p t e d as an e i g e n v a l u e of the s u b m a t r i x . Here the e n d p o i n t s of each s u b i n t e r v a l are close e n o u g h w h e n they d i f f e r by less than MACHEP times twice the s u m of the m a g n i t u d e s of the e n d p o i n t s plus the a b s o l u t e e r r o r t o l e r a n c e EPSI. The e i g e n v e c t o r s of the same s u b m a t r i x are then c o m p u t e d by inverse iteration. First, the LU d e c o m p o s i t i o n of the s u b m a t r i x w i t h an a p p r o x i m a t e e i g e n v a l u e s u b t r a c t e d f r o m its d i a g o n a l e l e m e n t s is a c h i e v e d by G a u s s i a n e l i m i n a t i o n u s i n g partial pivoting. The m u l t i p l i e r s d e f i n i n g the lower triangular matrix L are s t o r e d in the t e m p o r a r y a r r a y RV4 and the u p p e r t r i a n g u l a r m a t r i x U is s t o r e d in the three temporary arrays RVl, RV2, and RV3. S a v i n g these q u a n t i t i e s in RVI, RV2, RV3, and RV4 avoids repeating the LU d e c o m p o s i t i o n if f u r t h e r i t e r a t i o n s are r e q u i r e d . An a p p r o x i m a t e v e c t o r , s t o r e d in RV6, is c o m p u t e d s t a r t i n g f r o m an i n i t i a l v e c t o r , and the n o r m of the a p p r o x i m a t e v e c t o r is c o m p a r e d w i t h a n o r m of the s u b m a t r i x to d e t e r m i n e w h e t h e r the g r o w t h is s u f f i c i e n t to a c c e p t it as an eigenveetor. If this v e c t o r is a c c e p t e d , its E u c l i d e a n n o r m

515

7.1-321

is m a d e used as vector. times.

I~ If the g r o w t h is not s u f f i c i e n t , this v e c t o r is the i n i t i a l v e c t o r in c o m p u t i n g the n e x t a p p r o x i m a t e This i t e r a t i o n p r o c e s s is r e p e a t e d at m o s t 5

E i g e n v e c t o r s c o m p u t e d in the above w a y c o r r e s p o n d i n g to w e l l s e p a r a t e d e i g e n v a l u e s of this s u b m a t r i x w i l l be o r t h o g o n a l . However, eigenvectors corresponding to close e i g e n v a l u e s of this s u b m a t r i x may not be s a t i s f a c t o r i l y orthogonal. Hence, to i n s u r e o r t h o g o n a l e i g e n v e c t o r s , each a p p r o x i m a t e v e c t o r is m a d e o r t h o g o n a ! to those p r e v i o u s l y c o m p u t e d e i g e n v e c t o r s w h o s e e i g e n v a l u e s are close to the c u r r e n t e i g e n v a l u e . If the o r t h o g o n a l i z a t i o n p r o c e s s p r o d u c e s a zero v e c t o r , a c o l u m n of the i d e n t i t y m a t r i x is u s e d as an i n i t i a l v e c t o r for the next i t e r a t i o n . I d e n t i c a l e i g e n v a l u e s are p e r t u r b e d s l i g h t l y in an a t t e m p t to obtain independent eigenvectors. These perturbations are not r e c o r d e d in the o u t p u t e i g e n v a l u e a r r a y W. The above steps are r e p e a t e d e i g e n v a l u e s in the i n t e r v a l e i g e n v e c t o r s are c o m p u t e d .

on each (LB,UB)

s u b m a t r i x u n t i l all the and their c o r r e s p o n d i n g

This s u b r o u t i n e is a t r a n s l a t i o n of the A l g o l p r o c e d u r e TRISTURM w r i t t e n and d i s c u s s e d in d e t a i l by P e t e r s and Wilkinson (I).

4.

REFERENCES.

i)

z)

5.

P e t e r s , G. and W i l k i n s o n , J.H., The C a l c u l a t i o n of S p e c i f i e d E i g e n v e c t o r s by I n v e r s e I t e r a t i o n , H a n d b o o k A u t o m a t i c C o m p u t a t i o n , V o l u m e II, L i n e a r A l g e b r a , J. H. W i l k i n s o n - C. R e i n s c h , C o n t r i b u t i o n 11/18, 418-439, Springer-Verlag, 1971. Barth, W., M a r t i n , R.S., and W i l k i n s o n , J.H., C a l c u l a t i o n of the E i g e n v a l u e s of a S y m m e t r i c M a t r i x by the M e t h o d of B i s e c t i o n , Num. Math. 9 , 3 8 6 - 3 9 3 (1967).

Tridiagonal

CHECKOUT° A.

Test

Cases~

See the s e c t i o n d i s c u s s i n g t e s t i n g of the codes for c o m p l e x H e r m i t i a n , real s y m m e t r i c , real s y m m e t r i c tridiagonal, and c e r t a i n real n o n - s y m m e t r i c tridiagonal matrices.

B.

Accuracy.

516

for

7.1-322

The s u b r o u t i n e TSTURM is n u m e r i c a l l y s t a b l e (1,2); that is, the c o m p u t e d e i g e n v a l u e s are close to those of the o r i g i n a l matrix. In a d d i t i o n , they are the exact e i g e n v a l u e s of a m a t r i x close to the o r i g i n a l real s y m m e t r i c t r i d i a g o n a l m a t r i x and the c o m p u t e d e i g e n v e c t o r s are close (but not n e c e s s a r i l y equal) to the e i g e n v e c t o r s of that m a t r i x .

517

7.1-323

SUBROUTINE

TSTURM(NM,N,EPSI,D,E,E2,LB,UB,MM,M,W,Z, IERR,RVI,RV2,RV3,RV4,RVS,RV6)

X INTEGER X REAL X REAL X REAL

I,J,K,M,N,P,Q,R,S,II,IP,JJ,MM,MI,M2,NM,ITS, !ERK,GROUP,ISTURM D(N),E(N),E2(N),W(MM),Z(NM,MM), RVI (N),RV2(N),RV3(N),RV4(N),RV5(N),RV6(N) U,V,LB,TI,T2,UB,UK,XU,X0,XI,EPSI,EPS2,EPS3,EPS4, NORM,MACHEP SQRT,ABS,AMAXI,AMINI,FLOAT

**********

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

MACHEP

C

C C

C C

=

?

IERR = 0 TI = L B T2 = UB ********** LOOK FOR SMALL SUB-DIAGONAL ENTRIES ********** D O 40 I = i, N IF (I .EQ. I) G O T O 2 0 IF ( A B S ( E ( 1 ) ) .GT. M A C H E P * (ABS(D(1)) + ABS(D(I-I)))) X GO TO 40 20 E2(1) = 0.0 40 CONTINUE ********** DETERMINE THE NUMBER OF EIGENVALUES IN THE INTERVAL ********** P=I Q = N XI = UB ISTURM = 1 GO TO 320 60 M = S XI = L B ISTURM = 2 GO TO 320 80 M = M - S IF (M .GT. M M ) G O T O 9 8 0 Q = 0 R = 0 ********** ESTABLISH AND PROCESS NEXT SUBMATRIX, REFINING INTERVAL BY THE GERSCHGORIN BOUNDS *****~**** i 0 0 I F (R .EQ. M) G O T O I 0 0 1 P = Q + I XU

=

D(P)

X0 = D(P) U=O.O

518

7.1-324

DO

ii0

120

1 2 0 Q = P, N X1 = U U = 0.0 V = 0.0 IF (Q .EQ. N) G O T O I i 0 U = A B S (E ( Q + I ) ) v = E2(Q+I) XU = AMINI(D(Q)-(XI+U),XU) X0 = AMAXI(D(Q)+(XI+U),X0) IF (V .EQ. 0 . 0 ) G O T O 1 4 0 CONTINUE

C 140

160

180

200

220

Xl = AMAXI(ABS(XU),ABS(XO)) * MACHEP IF ( E P S I .LE. 0 . 0 ) E P S I = - X I IF (P .NE. Q) G O T O 1 8 0 • ********* CHECK FOR ISOLATED ROOT WITHIN IF (TI .GT. D ( P ) .OR. D ( P ) .GE. T 2 ) G O T O R = R + 1 DO 160 Z(I,R)

I = I, = 0.0

INTERVAL 940

**********

N

W(R) = D(P) Z(P,R) = 1.0 GO TO 940 X1 = X1 * FLOAT(Q-P+I) LB = AMAXI(TI,XU-XI) UB = AMINI(T2,X0+XI) X1 = LB ISTURM = 3 GO TO 320 MI = S + i Xl = U B ISTURM = 4 GO TO 320 M2 = S I F (MI . G T . M 2 ) G O T O • ********* FIND ROOTS X0 = UB ISTURM = 5

940 BY BISECTION

**********

DO

240

250

240 I = MI, M2 R V 5 (I) = U B RV4(I) = LB CONTINUE ********** LOOP FOR K-TH EIGENVALUE F O R K = M 2 S T E P -i U N T I L M 1 (-DO- NOT USED TO LEGALIZE K = M2 XU = LB

519

DO -COMPUTEE-GO-TO)

**********

7.1-325

260

********** FOR I=K STEP -i UNTIL M1 DO 260 II = M!, K I = M 1 + K - II IF ( X U . G E . R V 4 ( I ) ) GO TO 260 XU = RV4(1) GO TO 280 CONTINUE

DO

--

**********

C 280 C

I F (XO . G T . R V 5 ( K ) ) X0 = RV5(K) ********** NEXT BISECTION STEP ********** 300 X1 = (XU + X 0 ) * 0 . 5 IF ( ( X 0 - X U ) .LE. (2.0 * MACHEP * X (ABS(XU) + ABS(X0)) + ABS(EPSI))) GO TO 420 ********** IN-LINE PROCEDURE FOR STURM SEQUENCE ********** 320 S = P - 1 U=I.0 DO

325 330 340

360

380

400

420

3 4 0 1 = P, Q I F (U .NE. 0 . 0 ) G O T O 3 2 5 V = ABS(E(1)) / MACHEP GO TO 330 V = E2(I) / U U = D(1) - El - V I F (U .LT. 0 . 0 ) S = S + i CONTINUE

GO TO (60,80,200,220,360), !STURM ********** REFINE INTERVALS ********** IF (S . G E . K) G O T O 4 0 0 XU = X1 I F (S a G E . M I ) G O T O 3 8 0 RV4(MI) = XI GO TO 300 RV4 (S+I) = X1 IF (RV5(S) .GT. X I ) R V 5 ( S ) = X1 GO TO 300 X 0 = X1 GO T O 3 0 0 ********** K-TH EIGENVALUE FOUND ********** R V 5 (K) = X 1 K = K - 1 IF (K .GE. M I ) G O T O 2 5 0 ***~****** FIND VECTORS BY INVERSE ITERATION NORM = ABS(D(P)) IP = P + i

C 500

D O 5 0 0 I = IP, Q NORM = NORM + ABS(D(1))

+

ABS(E(1))

520

**********

7.1-326

**********

E P S 2 IS T H E C R I T E R I O N FOR GROUPING, EPS3 REPLACES ZERO PIVOTS AND EQUAL ROOTS ARE MODIFIED BY EPS3, E P S 4 IS T A K E N V E R Y S M A L L T O A V O I D 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 920 K = MI, M2 R = R + I ITS = 1 W(R) = RV5(K) X l = R V 5 (K) ********** LOOK FOR CLOSE OR COINCIDENT ROOTS IF (K .EQ. M I ) G O T O 5 2 0 IF (XI - X 0 .GE. E P S 2 ) G R O U P = -i GROUP = GROUP + 1 IF (XI .LE. X 0 ) X l = X 0 + E P S 3 ********** ELIMINATION WITH INTERCHANGES AND INITIALIZATION OF V E C T O R **********

**********

DO

520

v=o.o DO

5 8 0 I = P, Q R V 6 (I) = U K IF (I .EQ. P) IF ( A B S ( E ( 1 ) ) XU = U / E(1) RV4(1) = XU RVI(I-I)

540

560 580

=

GO TO 560 .LT. A B S ( U ) )

E(I)

RV2(I-I) = D ( 1 ) - XI RV3(I-I) = 0.0 IF (I .NE. Q) R V 3 ( 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)

=

RV2(I-I) RV3(I-I)

= V = 0.0

u

-

=

D(I)

IF (I CONTINUE

.NE.

GO

-- E ( I + I )

U

Xl

-

Q)V

IF (U .EQ. 0 . 0 ) R V I (Q) = U RV2(Q) = 0.0 RV3(Q) = 0.0

U =

XU

*

V

= E(I+I)

EPS3

521

TO

540

**********

7.1-327

C C

**********

600

620 C

C

BACK SUBSTITUTION FOR I=Q STEP -I UNTIL P DO -- ********** D O 6 2 0 II = P, Q I = P + Q - II RV6(1) = (RV6(1) - U * RV2(1) - V * RV3(1)) / RVI(1) V = U U = R V 6 (I) CONTINUE ********** ORTHOGONALIZE WITH RESPECT TO PREVIOUS MEMBERS OF GROUP ********** IF ( G R O U P . E Q . 0) G O T O 7 0 0 DO

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

640

DO XU

6 4 0 ! = P, Q = XU + RV6(1)

660

DO 660 RV6(1)

1 = P, Q = RV6(1)

JJ

* Z(I,J)

- XU

* Z(I,J)

C 680

CONTINUE

700

NORM

720

DO 720 NORM =

C =

0.0

C

740

760

780 C C C

800 820

1 = P, NORM +

Q ABS(RV6(I))

IF ( N O R M oGE. 1 . 0 ) G O T O 8 4 0 ********** FORWARD SUBSTITUTION IF ( I T S .EQ. 5) G O T O 9 6 0 I F ( N O R M .NE. 0 . 0 ) G O T O 7 4 0 RV6(S) = EPS4 S = S + 1 IF (S .GT. Q) S = P GO TO 780 XU = EPS4 / NORM DO 760 l{V6(I) • *********

**********

I = P, Q = RV6(I) * XU ELIMINATION OPERATIONS ON NEXT VECTOR ITERATE ********** D O 8 2 0 I = IP, Q U = R V 6 (I) • ********* IF R V I ( I - I ) .EQ. E ( 1 ) , A R O W I N T E R C H A N G E WAS PERFORMED EARLIER IN THE TRIANGULARIZATION PROCESS ********** IF ( R V I ( I - I ) .NE. E ( 1 ) ) GO TO 800 U = RV6 (I-I) RV6(I-I) = RV6(1) RV6(1) = U - RV4(1) * RV6(I-I) CONTINUE

522

7.1-328

840

860

ITS = ITS + 1 GO TO 600 ********** NORMALIZE SO i AND EXPAND U = 0.0 D O 8 6 0 1 = P, q U = U + RV6(1)**2 XU

=

1.0

/

SQRT(U)

880

DO 880 Z(I,R)

1 =

900

DO 900 Z(I,R)

1 = P, Q = RV6(1)

920

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

X0 = CONTINUE

= I, 0.0

N

*

XU

XI

940

IF (Q .LT. N) G O T O i 0 0 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 U B = T2 RETURN END

523

7.2-I

NATS

EIGENSYSTEM

PROJECT

SUBROUTINE F299-2

PACKAGE

(EISPACK)

EISPAC

A C o n t r o l P r o g r a m for the E i g e n s y s t e m P a c k a g e (F269 to F298 and F 2 2 0 to F247).

May, July,

1972 1975

i. P U R P O S E ~ The F o r t r a n IV and 0 S / 3 6 0 - 3 7 0 a s s e m b l y l a n g u a g e s u b r o u t i n e E I S P A C ( t o g e t h e r w i t h its a s s o c i a t e d " k e y w o r d " entry points) is d e s i g n e d to s i m p l i f y the s o l u t i o n of the s t a n d a r d and g e n e r a l i z e d m a t r i x e i g e n p r o b l e m s u s i n g the s u b r o u t i n e s in the eigensystem package (F269-F298, F220-F247). It thus may be used to c o m p u t e some or all of the e i g e n v a l u e s , w i t h or without eigenvectors, of c o m p l e x g e n e r a l , c o m p l e x H e r m i t i a n , real g e n e r a l , real s y m m e t r i c , r e a l s y m m e t r i c t r i d i a g o n a l , c e r t a i n real n o n - s y m m e t r i c tridiagonal, and real s y m m e t r i c b a n d m a t r i c e s ; and it m a y also be u s e d to c o m p u t e some or all of the e i g e n v a l u e s , w i t h or w i t h o u t e i g e n v e c t o r s , for the real s y m m e t r i c g e n e r a l i z e d e i g e n p r o b l e m , or all of the e i g e n v a l u e s , w i t h or w i t h o u t e i g e n v e c t o r s , for the real nonsymmetric generalized eigenproblem. EISPAC offers the f o l l o w i n g a d v a n t a g e s if y o u w i s h to solve an e i g e n p r o b l e m : !o You d e s c r i b e the p r o b l e m to EISPAC in simple, f a m i l i a r terms° 2~ U s i n g y o u r d e s c r i p t i o n , EISPAC automatically s e l e c t s s u b r o u t i n e s to solve y o u r p r o b l e m and e x e c u t e s them in the p r o p e r order and w i t h p a r a m e t e r s p a s s e d f r o m one to a n o t h e r in the p r o p e r way. In general, EISPAC s e l e c t s the s e q u e n c e of s u b r o u t i n e s in the e i g e n s y s t e m p a c k a g e w h i c h w i l l solve y o u r p r o b l e m as r a p i d l y as p o s s i b l e w i t h r e a s o n a b l e a s s u r a n c e of s t a b i l i t y in the c a l c u l a t i o n s . 3~ E I S P A C loads each s e l e c t e d s u b r o u t i n e only as it is r e q u i r e d , thus m a k i n g a v a i l a b l e for d a t a s t o r a g e as m u c h m e m o r y as p o s s i b l e . On the other hand, if s u f f i c i e n t m e m o r y is a v a i l a b l e , the s u b r o u t i n e s used are r e t a i n e d in m e m o r y and are not r e l o a d e d w h e n you r e p e a t e d l y call EISPAC to solve the same problem. (See s e c t i o n 3 below.) 4. E I S P A C a l l o c a t e s and frees any n e c e s s a r y a u x i l i a r y storage automatically.

524

7.2-2

5. Use of EISPAC m i n i m i z e s the n u m b e r of c h a n g e s you m u s t m a k e to y o u r p r o g r a m if y o u w i s h to solve a s l i g h t v a r i a t i o n of y o u r o r i g i n a l p r o b l e m or if you w i s h to take a d v a n t a g e of n e w m e t h o d s w h e n they are introduced. 6. E I S P A C is c a l l e d as a s u b r o u t i n e f r o m y o u r own driver program. Thus the m a t r i x w h o s e e i g e n s y s t e m is b e i n g c o m p u t e d may itself be the r e s u l t of other c o m p u t a t i o n s in y o u r p r o g r a m , and the c o m p u t e d e i g e n s y s t e m m a y c o n v e n i e n t l y be u s e d in f u r t h e r calculations. Thus EISPAC r e l i e v e s you of h a v i n g to d e v e l o p a d e t a i l e d k n o w l e d g e of the a p p l i c a b i l i t y , e f f i c i e n c y , and c a l l i n g s e q u e n c e s of the i n d i v i d u a l EISPACK subroutines.

2.

USAGE. A.

Calling

Sequence.

EISPAC e m p l o y s v a r i a b l e l e n g t h p a r a m e t e r lists and " k e y w o r d " p a r a m e t e r s to s i m p l i f y s p e c i f i c a t i o n of y o u r p r o b l e m and to g r o u p r e l a t e d s u b p a r a m e t e r s . An o v e r v i e w of the calls to EISPAC is g i v e n by the p r o t o t y p e c a l l s below; s p e c i f i c calls for d i f f e r e n t c l a s s e s of m a t r i c e s are d i s c u s s e d in s e c t i o n 2.B. T h e p r o t o t y p e call e i g e n p r o b l e m is: CALL E I S P A C (NM, (.0.), V E C T O R SU~R ( . . . ) )

to

EISPAC

for

the

standard

N, M A T R I X (...), BAND (...), V A L U E S (...), M E T H O D (...), E R R O R (...),

where NM

is an i n t e g e r v a r i a b l e w h i c h s u p p l i e s the row (first) d i m e n s i o n of any twod i m e n s i o n a l a r r a y s a p p e a r i n g in the call to E I S P A C (as that d i m e n s i o n is s p e c i f i e d in the D I M E N S I O N s t a t e m e n t s for them in the c a l l i n g p r o g r a m ) . For e x a m p l e , if your program contains arrays dimensioned: A(50,50), Z(50,50) w h i c h a p p e a r in the call to E I S P A C , and the o r d e r of the e i g e n p r o b l e m b e i n g s o l v e d is 25, then N M = 50 and N = 25.

525

7.2-3

is an i n t e g e r v a r i a b l e w h i c h s u p p l i e s the order of the i n p u t m a t r i x . N is c h e c k e d to v e r i f y that it is n e i t h e r g r e a t e r than NM nor less t h a n i. MATRIX,

BAND, V A L U E S , V E C T O R , M E T H O D , ERROR, SUBR are k e y w o r d p a r a m e t e r s . T h e y a c c e p t sets of s u b p a r a m e t e r s w h i c h d e f i n e the e i g e n p r o b l e m b e i n g solved. (These s u b p a r a m e t e r s are d i s c u s s e d in d e t a i l in section 2.C below.) Keyword parameters not n e e d e d to s p e c i f y a p a r t i c u l a r p r o b l e m are o m i t t e d f r o m the call to EISPAC; t h o s e a p p e a r i n g m a y a p p e a r in any order.

The p r o t o t y p e call e i g e n p r o b l e m is: CALL E I S P A C (NM, (...), V E C T O R

to

EISPAC

for

the g e n e r a l i z e d

N, M A T A (..o), M A T B (...), E R R O R (...),

(...), V A L U E S SUBR (.o.))

where MATA and MATB replace MATRIX as k e y w o r d parameters. Note: MATRIX and MATA are a l t e r n a t e f o r m s of the same k e y w o r d and can be u s e d interchangeably. To use E I S P A C , y o u m u s t i n c l u d e a p r i v a t e l i b r a r y DD card for E I S P A C L B (the d y n a m i c load l i b r a r y , see section 3 b e l o w ) in the G O - s t e p of y o u r job. This card a s s o c i a t e s EISPACLB w i t h the d a t a s e t w h e r e the load m o d u l e s for EISPAC and the e i g e n s y s t e m p a c k a g e subroutines reside. If y o u are u s i n g a t y p i c a l F o r t r a n c a t a l o g e d p r o c e d u r e , this card is: //GO.EISPACLB

DD D I S P = S H R , D S N A M E = . . .

S i m i l a r l y , if y o u are u s i n g the TSO time s y s t e m ~ y o u s h o u l d e x e c u t e the command: ALLOC before

FiLE(EISPACLB)

executing

your

DATASET(...)

sharing

SHR

program.

F i n a l l y , if you w i s h to use EISPAC from a PL/I ( C h e c k o u t or O p t i m i z e r ) p r o g r a m by m e a n s of the interlanguage communication facility, you should write a s i m p l e F o r t r a n s u b r o u t i n e w h i c h is c a l l e d f r o m y o u r P L / I p r o g r a m and w h i c h in t u r n calls E!SPAC as d e s c r i b e d below. T h i s is n e c e s s a r y b e c a u s e EISPAC makes certain ( n o n - s t a n d a r d ) a s s u m p t i o n s a b o u t the F o r t r a n e n v i r o n m e n t of the p r o g r a m c a l l i n g it w h i c h m a y not be s a t i s f i e d

526

7.2-4

w h e n the p r o g r a m is w r i t t e n in PL/I. The F o r t r a n program calling EISPAC s h o u l d h a v e as p a r a m e t e r s v a r i a b l e s to be p a s s e d to EISPAC; y o u s h o u l d take that the v e c t o r s and a r r a y s a p p e a r in D I M E N S I O N s t a t e m e n t s in it. Thus for the e x a m p l e c o n c l u d i n g s e c t i o n on real s y m m e t r i c m a t r i c e s in s e c t i o n 2.B b e l o w , the F o r t r a n s u b r o u t i n e c a l l e d by y o u r P L / I p r o g r a m s h o u l d l o o k like: S U B R O U T I N E E I S C A L (N, A, W, Z) INTEGER N R E A L * 8 A ( N , N ) , W(N), Z(N,N) CALL E I S P A C (N, N, M A T R I X ('REAL, V A L U E S (W), V E C T O R (Z)) RETURN END

A,

the care the

'SYMMETRIC'),

This e x a m p l e a s s u m e s that the P L / I a r r a y s c o r r e s p o n d i n g to the m a t r i c e s A and Z are d i m e n s i o n e d e x a c t l y NxN, and h e n c e that the p a r a m e t e r NM can be r e p l a c e d by N. In the P L / I c a l l i n g p r o g r a m , EISCAL w o u l d be declared: DCL

EISCAL

ENTRY

(FIXED B I N A R Y ( 3 1 , 0 ) , (*,*) F L O A T D E C I M A L ( 1 6 ) , (*) FLOAT DECIMAL(16), (*,*) F L O A T D E C I M A L ( 1 6 ) ) O P T I O N S (FORTRAN) E X T E R N A L ;

You m u s t p r o v i d e a DD card or a l l o c a t i o n for F T 0 6 F 0 0 1 , the s t a n d a r d F o r t r a n o u t p u t file, b e c a u s e F o r t r a n a u t o m a t i c a l l y tries to open it. This f i l e s h o u l d be a s s o c i a t e d w i t h the same d a t a s e t as the o u t p u t f r o m the P L / I p r o g r a m , so that EISPAC e r r o r m e s s a g e s , if any, a p p e a r w i t h it. F i n a l l y , if you are u s i n g the P L / I C h e c k o u t c o m p i l e r , y o u n e e d to s p e c i f y the o p t i o n S I Z E ( - n K ) to the e x e c u t i o n step to r e s e r v e d y n a m i c s t o r a g e for EISPAC; at a m i n i m u m n=14, and it m u s t be l a r g e e n o u g h to a c c o m m o d a t e any t e m p o r a r y a r r a y s that are a l l o c a t e d . (An i n s u f f i c i e n t l y large v a l u e of n w i l l r e s u l t in e i t h e r of the s y s t e m c o m p l e t i o n codes 804 or 80A (see s e c t i o n 2.D).) The u s e of EISPAC to s o l v e v a r i o u s k i n d s of e i g e n p r o b l e m s is i l l u s t r a t e d in the f o l l o w i n g section. Y o u m a y w i s h to read f i r s t the e x a m p l e s for the type of m a t r i x y o u h a v e and then c o n s u l t s e c t i o n 2.C for f u r t h e r d e t a i l s a b o u t the k e y w o r d s u b p a r a m e t e r s . (Note that in these e x a m p l e s the c o n t i n u a t i o n s y m b o l w h i c h m u s t a p p e a r in c o l u m n 6 of a F o r t r a n c o n t i n u a t i o n card has b e e n o m i t t e d . )

527

7.2-5

B.

EISPAC

Examples

Complex

for

General

The b a s i c (WR, WI) is:

Different

Classes

of M a t r i c e s .

Matrix

call, w h i c h finds all of the e i g e n v a l u e s of the c o m p l e x g e n e r a l m a t r i x (AR, AI),

(NM, N, M A T R I X ('C0MPLSX', AR, A!), (WR, WZ))

CALL EISPAC

VALUES

If you w i s h to find all of the e i g e n v e c t o r s (ZR, ZI), add: V E C T O R (ZR, ZI). If you w i s h to find all of the e i g e n v a l u e s and only s e l e c t e d e i g e n v e c t o r s ~ add: V E C T O R (ZR, ZI, MM, M, SELECT). If y o u METHOD

prefer ('NO',

not to b a l a n c e 'BALANCE').

If you w i s h to use similarities, add: Thus a call to find of the e i g e n v e c t o r s

the m a t r i x ,

e l e m e n t a r y i n s t e a d of u n i t a r y METHOD ('ELEMENTARY')~ all of the e i g e n v a l u e s and some of a c o m p l e x g e n e r a l m a t r i x is:

CALL E I S P A C (NM, N, M A T R I X V A L U E S (WR, WI), V E C T O R SELECT))

Complex

Hermitian

add:

( ' C O M P L E X ' , AR, (ZR, ZI, MM, M,

AI),

Matrix

R e c a l l that a c o m p l e x H e r m i t i a n m a t r i x is a m a t r i x w h i c h is e q u a l to its c o m p l e x c o n j u g a t e transpose. If you w i s h to s o l v e an e i g e n p r o b l e m for a c o m p l e x s y m m e t r i c m a t r i x (a m a t r i x w h i c h is equal to its transpose without conjugation), you m u s t f o l l o w the c o m p l e x g e n e r a l m a t r i x examples. The b a s i c W of the

call, w h i c h finds complex Hermitian

CALL E I S P A C (NM, 'HERMITIAN'),

528

all of matrix

the e i g e n v a l u e s (AR, AI), is:

N, M A T R I X ( ' C O M P L E X ' , V A L U E S (W))

AR,

AI,

7.2-6

If the complex Hermitian m a t r i x is packed into a single two-dimensional array, HP, substitute for M A T R I X ('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 V A L U E S (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 (WR, WI)

call, which finds all of the eigenvalues of the real general matrix A, is:

CALL EISPAC (NM, N, MATRIX (WR, WI))

('REAL',

A), VALUES

If you wish to find all of the eigenvectors add: VECTOR (ZP).

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 METHOD ('NO', 'BALANCE').

the matrix,

add:

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 e i g e n v a ! u e s of a real g e n e r a l m a t r i x w i t h o u t b a l a n c i n g and using o r t h o g o n a l s i m i l a r i t i e s is: CALL EiSPAC (NM, N, M A T R I X (WR, WI), M E T H O D ('NO', 'ORTHOGONAL'))

Real N o n - S y m m e t r i c

Tridiagonal

('REAL', A), V A L U E S 'BALANCE',

Matrix

The f o l l o w i n g e x a m p l e s a p p l y only if the p r o d u c t s of c o r r e s p o n d i n g o f f - d i a g o n a l e l e m e n t s of the t r i d i a g o n a l m a t r i x all are n o n - n e g a t i v e . (Read n o t e 4 b e l o w for an a d d i t i o n a l r e s t r i c t i o n if you w i s h to c o m p u t e e i g e n v e c t o r s . ) O t h e r w i s e the real g e n e r a l m a t r i x e x a m p l e s m u s t be followed. The b a s i c call, w h i c h finds all of the e i g e n v a l u e s W of the real t r i d i a g o n a l m a t r i x UST, is: CALL E I S P A C (NM, N, M A T R I X ('REAL', ' T R I D I A G O N A L ' ) , V A L U E S (W))

UST,

If you w i s h to find only the e i g e n v a ! u e s in the interval (RLB,RUB), s u b s t i t u t e for V A L U E S (W) (see note 3): V A L U E S (W, MM, M, RLB, RUB). A l t e r n a t i v e l y , if you w i s h to find e x a c t l y M e i g e n v a l u e s , s t a r t i n g from the Mll-th smallest one, s u b s t i t u t e for V A L U E S (W): V A L U E S (W, MII, M). (See n o t e s 1 and 3.) If you w i s h to find the e i g e n v e c t o r s Z c o r r e s p o n d i n g to the e i g e n v a l u e s found, add: V E C T O R (Z). Thus a call to find e x a c t l y M eigenvalues, s t a r t i n g f r o m the Mll-th s m a l l e s t one, of a real n o n - s y m m e t r i c t r i d i a g o n a l m a t r i x is: CALL EISPAC (NM, N, M A T R I X ('REAL', UST, ' T R I D I A G O N A L ' ) , V A L U E S (W, MII, M))

Real

Symmetric

Matrix

The b a s i c call, w h i c h finds all of the e i g e n v a l u e s W of the real s y m m e t r i c m a t r i x A, is (see n o t e 2):

530

7.2-8

CALL EISPAC (NM, N, M A T R I X ('REAL', ' S Y M M E T R I C ' ) , V A L U E S (W))

A,

If the real s y m m e t r i c m a t r i x is p a c k e d into a s i n g l e o n e - d i m e n s i o n a l array, SP, s u b s t i t u t e for M A T R I X ('REAL', A, ' S Y M M E T R I C ' ) : M A T R I X ('REAL', SP, 'SYMMETRIC', 'PACKED'). If you wish to find only the e i g e n v a l u e s in the interval (RLB,RUB), s u b s t i t u t e for V A L U E S (W) (see note 3): V A L U E S (W, MM, M, RLB, RUB). A l t e r n a t i v e l y , if you w i s h to find e x a c t l y M e i g e n v a l u e s , s t a r t i n g f r o m the Mll-th smallest one, s u b s t i t u t e for V A L U E S (W): V A L U E S (W, MII, M). (See notes I and 3.) If you w i s h to find the e i g e n v e c t o r s Z c o r r e s p o n d i n g to the e i g e n v a l u e s found, add: V E C T O R (Z). Thus a call to find all of the e i g e n v a l u e s and e i g e n v e c t o r s of a real s y m m e t r i c m a t r i x is: CALL EISPAC (NM, N, M A T R I X ('REAL', ' S Y M M E T R I C ' ) , V A L U E S (W), V E C T O R

Real

Symmetric

Tridiagonal

A, (Z))

Matrix

The basic call, w h i c h finds all of the e i g e n v a l u e s W of the real s y m m e t r i c t r i d i a g o n a l m a t r i x ST, is (see note 2): CALL EISPAC (NM, N, M A T R I X ('REAL', ST, ' S Y M M E T R I C ' , ' T R I D I A G O N A L ' ) , V A L U E S (W)) If you wish to find only the e i g e n v a l u e s in the interval (RLB,RUB), s u b s t i t u t e for V A L U E S (W) (see note 3): V A L U E S (W, MM, M, RLB, RUB). A l t e r n a t i v e l y , if you w i s h to find e x a c t l y M e i g e n v a l u e s , s t a r t i n g from the Mll-th smallest one, s u b s t i t u t e for V A L U E S (W): VALUES (W, MII, M). (See notes i and 3.) If you w i s h to find the e i g e n v e c t o r s Z c o r r e s p o n d i n g to the e i g e n v a l u e s found, add: V E C T O R (Z).

531

7.2-9

Thus real

a call to find some of the e i g e n v a l u e s s y m m e t r i c t r i d i a g o n a l m a t r i x is:

of

CALL E I S P A C (NM, N, M A T R I X ('REAL', ST, 'SYMMETRIC', 'TRIDIAGONAL'), V A L U E S (W, M, RLB, RUB))

Real .

.

.

.

Symmetric .

.

.

.

.

.

.

.

.

.

.

Band .

.

.

.

.

.

a

MM,

Matrix .

.

The b a s i c call, w h i c h finds all of the e i g e n v a l u e s W of the real s y m m e t r i c b a n d m a t r i x SB, is (see n o t e s 2 and 6): CALL E I S P A C (NM, 'SYMMETRIC'),

N, M A T R I X ('REAL', SB, BAND (MB), V A L U E S (W))

If you w i s h to find only the e i g e n v a l u e s in interval (RLB,RUB), s u b s t i t u t e for VALUES (see n o t e 3): V A L U E S (W, MM, M, RLB, RUB).

the (W)

Alternatively, if you w i s h to find e x a c t l y M eigenvalues, s t a r t i n g f r o m the Mll-th smallest one, s u b s t i t u t e for V A L U E S (W): V A L U E S (W, MII, M). (See n o t e s 1 and 3.) If y o u w i s h to find the e i g e n v e c t o r s Z corresponding to the e i g e n v a l u e s found, add: V E C T O R (Z). Thus real

a call to find symmetric band

CALL E I S P A C (NM, 'SYMMETRIC'), RLB, RUB))

Generalized

Real

some of the m a t r i x is:

eigenvalues

of a

N, M A T R I X ('REAL', SB, BAND (MB), V A L U E S (W, MM,

Symmetric

Matrix

M,

Systems

T h e r e are t h r e e forms of the r e a l s y m m e t r i c g e n e r a l i z e d e i g e n p r o b l e m that can be s o l v e d w i t h EISPAC: n a m e l y , the forms Ax = ( l a m b d a ) B x , ABx = (lambda)x, and BAx = (lambda)x, w h e r e A and B are b o t h s y m m e t r i c and B is p o s i t i v e 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 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 Z corresponding to the eigenvalues found, add: VECTOR (Z). 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 N o n - S y m m e t r i c

Matrix

System

The basic call, which finds all of the eigenvalues (ALPHAR/BETA, ALPHAI/BETA) for the real non~ symmetric generalized e i g e n p r o b l e m Ax = (lambda)Bx, is (see note 8): CALL EISPAC ('REAL',

(NM, N, MATA ('REAL', A), MATB B), VALUES (ALPHAR, ALPHAI, BETA))

If you wish to find all of the eigenvectors, of the system, add: VECTOR (ZP).

533

ZP,

7.2-11

Thus a call to find all of the e i g e n v a l u e s and e i g e n v e c t o r s of a real n o n - s y m m e t r i c g e n e r a l i z e d s y s t e m is: CALL E I S P A C (NM, N, M A T A ('REAL ~ , A), M A T B ('REAL', B), V A L U E S (ALPHAR, A L P H A I , BETA), V E C T O R (ZP))

C~ M e a n i n g s

of K e y w o r d

Subparameters 'REAL'

for

Subparameters.

MATRIX,

MATA,

and

MATB:

s p e c i f i e s that the m a t r i x w h o s e e i g e n s y s t e m is to be c o m p u t e d is real. (See n o t e 9.)

'COMPLEX' s p e c i f i e s that the m a t r i x w h o s e e i g e n s y s t e m is to be c o m p u t e d is c o m p l e x . (See n o t e 9.) AR,

A~

AI

B

are long p r e c i s i o n real t w o - d i m e n s i o n a l v a r i a b l e s w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at least N. T h e y supply, r e s p e c t i v e l y , the r e a l and i m a g i n a r y p a r t s of the c o m p l e x m a t r i x w h o s e e i g e n s y s t e m is to be c o m p u t e d . In the n o n - H e r m i t i a n case, the i n f o r m a t i o n in the f u l l AR and AI a r r a y s s p e c i f i e s the m a t r i x , and all of it is d e s t r o y e d . In the H e r m i t i a n case, the i n f o r m a t i o n in the full lower t r i a n g l e of AR and the s t r i c t lower t r i a n g l e of AI s p e c i f i e s the m a t r i x , and is d e s t r o y e d as w e l l as the d i a g o n a l of AI; the f u l l u p p e r t r i a n g l e of AR and the s t r i c t u p p e r t r i a n g l e of AI are left u n a l t e r e d . are long p r e c i s i o n real t w o - d i m e n s i o n a l v a r i a b l e s w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at least N. They supply the real m a t r i c e s w h o s e e i g e n s y s t e m is to be c o m p u t e d . (For the s t a n d a r d e i g e n p r o b l e m , only A is s u p p l i e d . ) In the n o n - s y m m e t r i c case, the i n f o r m a t i o n in the f u l l A and B a r r a y s s p e c i f i e s the m a t r i c e s , and all of it is d e s t r o y e d . In the s y m m e t r i c s t a n d a r d case~ the i n f o r m a t i o n in the f u l l lower t r i a n g l e of A s p e c i f i e s the m a t r i x ; that in the s t r i c t l o w e r t r i a n g l e m a y be d e s t r o y e d , and that in the full u p p e r t r i a n g l e is left

534

7.2-12

unaltered. In the s y m m e t r i c g e n e r a l i z e d case, the i n f o r m a t i o n in the f u l l u p p e r t r i a n g l e s of A and B s p e c i f i e s the m a t r i c e s ; the f u l l lower t r i a n g l e of A and the s t r i c t lower t r i a n g l e of B are d e s t r o y e d , and the s t r i c t u p p e r t r i a n g l e of A and the f u l l u p p e r t r i a n g l e of B are left u n a l t e r e d . UST

is a long p r e c i s i o n r e a l t w o - d i m e n s i o n a l v a r i a b l e w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at least 3. It s u p p l i e s a real non-symmetric tridiagonal matrix whose s u b d i a g o n a l e l e m e n t s are s t o r e d in the last N-I p o s i t i o n s of the f i r s t column, w h o s e d i a g o n a l e l e m e n t s are s t o r e d in the s e c o n d column, and w h o s e s u p e r d i a g o n a l e l e m e n t s are s t o r e d in the f i r s t N-I p o s i t i o n s of the third column. UST(I,I) and UST(N,3) are a r b i t r a r y . N o n e of the i n f o r m a t i o n in UST is d e s t r o y e d . The n o n - s y m m e t r i c t r i d i a g o n a l m a t r i x s u p p l i e d by UST must h a v e the a d d i t i o n a l s p e c i a l p r o p e r t y that the p r o d u c t s of c o r r e s p o n d i n g o f f - d i a g o n a l e l e m e n t s all are n o n - n e g a t i v e . (Read n o t e 4 for an a d d i t i o n a l r e s t r i c t i o n on UST if e i g e n v e c t o r s are b e i n g c o m p u t e d . ) V i o l a t i o n of t h e s e r e s t r i c t i o n s on UST c a u s e s an EISPAC execution phase error (see s e c t i o n 2.D below).

ST

is a long p r e c i s i o n real t w o - d i m e n s i o n a l variable with row dimension NM and c o l u m n d i m e n s i o n at least 2. It s u p p l i e s a r e a l symmetric tridiagonal matrix whose s u b d i a g o n a l e l e m e n t s are s t o r e d in the last N-I p o s i t i o n s of the f i r s t c o l u m n and w h o s e d i a g o n a l e l e m e n t s are s t o r e d in the s e c o n d column. ST(I,1) is a r b i t r a r y . The i n f o r m a t i o n in the s u b d i a g o n a l (first column) o n l y is d e s t r o y e d .

HP

is a long p r e c i s i o n real t w o - d i m e n s i o n a l variable with row dimension NM and c o l u m n d i m e n s i o n at least N. On input, HP c o n t a i n s the lower t r i a n g l e of a p a c k e d c o m p l e x H e r m i t i a n m a t r i x of o r d e r N whose e i g e n s y s t e m is to be c o m p u t e d . If the real part of the m a t r i x is d e n o t e d by AR and the i m a g i n a r y part by AI, then the f u l l

535

7.2-13

lower t r i a n g l e of AR s h o u l d be stored in the full lower t r i a n g l e of HP, and the s t r i c t lower t r i a n g l e of AI should be stored in the strict upper t r i a n g l e of HP in t r a n s p o s e d form. For e x a m p l e w h e n N=4, HP should contain (AR(I,I) (AR(2,1) (AR(3,1) (AR(4,1)

AI(2,1) AR(2,2) AR(3,2) AR(4,2)

All of the destroyed. SP

AI(3,1) AI(3,2) AR(3,3) AR(4,3)

information

in

HP

A!(4,1) AI(4,2) AI(4,3) AR(4,4)

) ) ) ).

is

is a long p r e c i s i o n real o n e - d i m e n s i o n a l v a r i a b l e w i t h d i m e n s i o n at least N*(N+I)/2. It s u p p l i e s the lower t r i a n g l e of a real s y m m e t r i c m a t r i x A of order N, packed row-wise. For e x a m p l e w h e n N=3, SP should contain (A(I,I),A(2,1),A(2,2),A(3,1),A(3,2),A(3,3)) w h e r e the s u b s c r i p t s of each e l e m e n t refer to the row and c o l u m n of the e l e m e n t in the standard two-dimensional representation. All of the i n f o r m a t i o n in SP is destroyed.

SB

is a long p r e c i s i o n real t w o - d i m e n s i o n a l variable with row dimension NM and column d i m e n s i o n at least MB. It s u p p l i e s the lower t r i a n g l e of a real s y m m e t r i c m a t r i x A of order N in b a n d f o r m w i t h half bandwidth MB. The l o w e s t s u b d i a g o n a l of the m a t r i x is s t o r e d in the last N+I-MB p o s i t i o n s of the f i r s t c o l u m n of SB, the n e x t s u b d i a g o n a l in the last N+2-MB p o s i t i o n s of the s e c o n d column, f u r t h e r d i a g o n a l s s i m i l a r l y , and f i n a l l y the p r i n c i p a l d i a g o n a l in the N p o s i t i o n s of the last column. C o n t e n t s of s t o r a g e l o c a t i o n s not part of the m a t r i x are arbitrary. For e x a m p l e , w h e n N=5 and MB=3, SB should contain (

*

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

536

*

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

A(I,I)

)

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

7.2-14

All of the destroyed.

information

in

SB

'HERMITIAN', 'SYMMETRIC', 'TRIDIAGONAL' DEFINITE' , 'NEGATIVE DEFINITE', 'PACKED s p e c i f y that the m a t r i x w h o s e is to be found has the stated property. (See also notes I, 'ABX=LX',

Subparameter MB

'POSITIVE I eigensystem special 2, and 9.)

'BAX=LX' (as s u b p a r a m e t e r s for MATB) s p e c i f y the c o r r e s p o n d i n g v a r i a n t of the real s y m m e t r i c g e n e r a l i z e d e i g e n p r o b l e m . for

BAND:

is an integer v a r i a b l e w h i c h s u p p l i e s the half b a n d w i d t h of a real s y m m e t r i c band matrix. It is d e f i n e d as the n u m b e r .of a d j a c e n t d i a g o n a l s , i n c l u d i n g the p r i n c i p a l d i a g o n a l , r e q u i r e d to s p e c i f y the n o n - z e r o p o r t i o n of the lower t r i a n g l e of the matrix.

Subparameters WR,

is

WI

for

VALUES:

are long p r e c i s i o n real o n e - d i m e n s i o n a l v a r i a b l e s of d i m e n s i o n at least N. They receive, r e s p e c t i v e l y , the real and i m a g i n a r y parts of the N complex e i g e n v a l u e s computed.

W

is a long p r e c i s i o n real o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at least s u f f i c i e n t (N, MM, or M) to hold the e i g e n v a l u e s . It r e c e i v e s the N (M) eigenvalues computed.

MM

is an integer v a r i a b l e which, w h e n it is a s u b p a r a m e t e r to VALUES, s u p p l i e s a m a x i m u m for the n u m b e r of e i g e n v a l u e s e x p e c t e d in the i n t e r v a l (RLB,RUB); m o r e than MM e i g e n v a l u e s in (RLB,RUB) is an error. The d i m e n s i o n of W, and the c o l u m n d i m e n s i o n of ZR and ZI or Z if used, m u s t be at least MM.

M

is an i n t e g e r v a r i a b l e which, w h e n it is a s u b p a r a m e t e r to VALUES, d e n o t e s the n u m b e r of e i g e n v a l u e s a c t u a l l y s t o r e d in W. It is s u p p l i e d (in c o n j u n c t i o n w i t h MII) by the user if a s p e c i f i e d n u m b e r of e i g e n v a l u e s is to be computed. It is set by the p r o g r a m , if an i n t e r v a l (RLB,RUB) has b e e n s p e c i f i e d , to the n u m b e r of e i g e n v a l u e s a c t u a l l y found.

537

7.2-15

RLB,

RUB

are long p r e c i s i o n real v a r i a b l e s w h i c h d e f i n e an i n t e r v a l to be s e a r c h e d for eigenvalues. The e i g e n v a l u e s f o u n d lie in the i n t e r v a l ( R L B , R U B ) , w h i c h is c l o s e d on the left and o p e n on the right; if RLB is not less than RUB, no e i g e n v a l u e s are found. (RLB,RUB) m u s t not c o n t a i n m o r e than MM eigenvalueso

MII

is an i n t e g e r v a r i a b l e w h i c h , w h e n it is a s u b p a r a m e t e r to V A L U E S , s u p p l i e s the i n d e x of the s m a l l e s t e i g e n v a l u e to be c o m p u t e d .

EPS 1

is a long p r e c i s i o n real v a r i a b l e w h i c h s u p p l i e s an a b s o l u t e e r r o r t o l e r a n c e for the c o m p u t e d e i g e n v a l u e s ; if the input v a l u e of EPSI is n o n - p o s i t i v e , a d e f a u l t v a l u e w i l l be used. (See n o t e 3.)

ALPHAR,

ALPHAI, BETA are long p r e c i s i o n real o n e - d i m e n s i o n a l v a r i a b l e s w i t h d i m e n s i o n at l e a s t N which r e c e i v e the c o m p l e x e i g e n v a l u e s for a real non-symmetric generalized eigenproblem. The r e a l part of each e i g e n v a l u e is g i v e n by ALPHAR(I)/BETA(I) and the i m a g i n a r y p a r t by ALPHAI(I)/BETA(1). (See n o t e 8.)

'LARGEST', 'SMALLEST' s p e c i f y that the M l a r g e s t or s m a l l e s t e i g e n v a l u e s are to be c o m p u t e d if the rational QR m e t h o d has b e e n s e l e c t e d ° In this c a s e s u b s t i t u t e for VALUES(W): V A L U E S (W, M, ' L A R G E S T ' ) or V A L U E S (W, M, 'SMALLEST'), respectively° (See n o t e s i and 9.) Subparameters ZR,

ZP

ZI

for

VECTOR:

are long p r e c i s i o n real t w o - d i m e n s i o n a l v a r i a b l e s w i t h row d i m e n s i o n NM and c o l u m n d i m e n s i o n at l e a s t s u f f i c i e n t (N, MM, or M) to h o l d the e i g e n v e c t o r s . They r e c e i v e , r e s p e c t i v e l y , the r e a l and i m a g i n a r y p a r t s of the N (M) eigenvectors computed. is a long p r e c i s i o n r e a l t w o - d i m e n s i o n a l v a r i a b l e w i t h r o w and c o l u m n d i m e n s i o n s as d e s c r i b e d for ZR and ZI. It r e c e i v e s N (M) columns which represent eigenvectors of a r e a l g e n e r a l m a t r i x or m a t r i x system. To c o n s e r v e s t o r a g e s t h e s e e i g e n v e c t o r s are s t o r e d in ZP in p a c k e d form:

538

7.2-16

c o r r e s p o n d i n g to a real e i g e n v a l u e , one c o l u m n r e p r e s e n t i n g the real e i g e n v e c t o r is s t o r e d ; c o r r e s p o n d i n g to a c o m p l e x c o n j u g a t e pair of e i g e n v a l u e s , two c o n s e c u t i v e c o l u m n s r e p r e s e n t i n g the r e a l and i m a g i n a r y p a r t s of the e i g e n v e c t o r c o r r e s p o n d i n g to the first, or f i r s t f l a g g e d (see SELECT below), of the pair are stored. For e x a m p l e , s u p p o s e all of the e i g e n v e c t o r s of a r e a l g e n e r a l m a t r i x are b e i n g c o m p u t e d . If the K-th e i g e n v a l u e is real (WI(K) = 0) t h e n ZP(K) is the c o r r e s p o n d i n g e i g e n v e c t o r . If the K-th and (K+l)-th e i g e n v a l u e s are a c o m p l e x c o n j u g a t e pair (with WI(K) .GT. 0) then ZP(K) is the r e a l part and ZP(K+I) is the i m a g i n a r y part of the e i g e n v e c t o r c o r r e s p o n d i n g to the K-th eigenvalue. The c o n j u g a t e of this v e c t o r is the e i g e n v e c t o r for the c o n j u g a t e e i g e n v a l u e . ( E x a m p l e F o r t r a n s t a t e m e n t s for u n p a c k i n g the e i g e n v e c t o r s m a y be f o u n d in s e c t i o n

2.3.2

of

(6).)

is a long p r e c i s i o n real t w o - d i m e n s i o n a l v a r i a b l e w i t h r o w and c o l u m n d i m e n s i o n s as d e s c r i b e d for ZR and ZI. It r e c e i v e s the N (M) eigenvectors computed. When all of the e i g e n v e c t o r s of a real s y m m e t r i c (full) m a t r i x or g e n e r a l i z e d m a t r i x s y s t e m are b e i n g c o m p u t e d , the a r r a y A which s u p p l i e s the input m a t r i x m a y be u s e d for Z; the e i g e n v e c t o r s t h e n o v e r w r i t e the input m a t r i x . MM

is an i n t e g e r v a r i a b l e w h i c h , w h e n it is a s u b p a r a m e t e r to V E C T O R , s u p p l i e s the m a x i m u m n u m b e r of c o l u m n s of ZR and ZI or ZP w h i c h w i l l be used. The c o l u m n d i m e n s i o n of ZR and ZI or ZP m u s t be at l e a s t MM.

M

is an i n t e g e r v a r i a b l e w h i c h , w h e n it is a s u b p a r a m e t e r to V E C T O R , r e c e i v e s the n u m b e r of c o l u m n s used to s t o r e e i g e n v e c t o r s in ZR and ZI or ZP.

SELECT

is a l o g i c a l o n e - d i m e n s i o n a l v a r i a b l e of d i m e n s i o n at l e a s t N w h o s e true e l e m e n t s flag those e i g e n v a l u e s of a real or c o m p l e x g e n e r a l m a t r i x w h o s e e i g e n v e c t o r s are to be computed. If e i g e n v e c t o r s of a real g e n e r a l m a t r i x are b e i n g c o m p u t e d and b o t h of a pair of c o m p l e x c o n j u g a t e e i g e n v a l u e s

539

7.2-17

are f l a g g e d , the s e c o n d flag is set false and only the e i g e n v e e t o r c o r r e s p o n d i n g to the f i r s t of the pair is c o m p u t e d . An error r e s u l t s if MM is s m a l l e r than the n u m b e r of c o l u m n s r e q u i r e d to hold the selected eigenvectors. Subparameters

for

METHOD:

(See n o t e 9 c o n c e r n i n g parameters.)

alphanumeric

'ORTHOGONAL' s p e c i f i e s that o r t h o g o n a l s i m i l a r i t i e s ( i n s t e a d of e l e m e n t a r y s i m i l a r i t i e s ) are to be used to r e d u c e a r e a l g e n e r a l m a t r i x to u p p e r H e s s e n b e r g form. R e d u c t i o n by o r t h o g o n a l s i m i l a r i t i e s is s o m e w h a t slower than that by e l e m e n t a r y s i m i l a r i t i e s ~ but in some cases it m a y i m p r o v e the a c c u r a c y of the c o m p u t e d e i g e n s y s t e m . In p a r t i c u l a r , if y o u w i s h to c a l c u l a t e the c o n d i t i o n n u m b e r s for the c o m p u t a t i o n of the e i g e n s y s t e m of a m a t r i x (see (3), po 199 and (4), pp. 86-89), you s h o u l d use the c o n d i t i o n - n u m b e r - p r e s e r v i n g orthogonal transformations. 'ELEMENTARY' s p e c i f i e s that e l e m e n t a r y s i m i l a r i t i e s ( i n s t e a d of u n i t a r y s i m i l a r i t i e s ) are to be u s e d on a c o m p l e x g e n e r a l m a t r i x (the LR r a t h e r than the QR transformation). E l e m e n t a r y s i m i l a r i t i e s are s o m e w h a t f a s t e r than u n i t a r y s i m i l a r i t i e s , but in some cases d i m i n i s h the a c c u r a c y of the c o m p u t e d (complex general) eigensystem. ~NO',

'BALANCE' s p e c i f i e s that a real or c o m p l e x g e n e r a l m a t r i x is not to be b a l a n c e d b e f o r e its e i g e n s y s t e m is c o m p u t e d . In g e n e r a l , b a l a n c i n g i m p r o v e s the a c c u r a c y of the c o m p u t e d e i g e n s y s t e m and r e q u i r e s v e r y l i t t l e a d d i t i o n a l c o m p u t a t i o n time.

'RATQR T

s p e c i f i e s that the r a t i o n a l QR m e t h o d is to be used to c o m p u t e a few of the l a r g e s t or s m a l l e s t e i g e n v a l u e s . (See n o t e i.)

540

7.2-18

Subparameter IERROR

Subparameter USUB

for

ERROR:

is an integer variable which receives a value indicating whether certain errors occurred during the solution of the eigensystem. See section 2.D below. for

SUBR:

is a user-supplied subroutine with following parameter list: USUB (SUBRNO, NM, N, AR, AI, ZI, MM, M, RLB, RUB, EPSI, IDEF, SMLSTV, IERROR, LOW, D, E, E2, IND, INT, ORTR, ORTI, MII, NV, MB, BR, DL, ALPHAI, BETA).

the

WR, Wl, ZR, SELECT, UPP, BND, SCALE, TAU, ALPHAR,

The keyword parameter SUBR (USUB) may be added to any EISPAC call. (Note that USUB must be m e n t i o n e d 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 E i g e n s y s t e m 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 Eigenvalues.

or Smallest

The recommended procedure for computing a few of the extreme eigenvalues of a real symmetric or complex H e r m i t i a n 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 m a t r i x is positive (negative) definite, you may indicate so by adding the subparameter 'POSITIVE DEFINITE' ('NEGATIVE DEFINITE') to MATRIX, e.g.,

541

7.2-19

M A T R I X ('REAL', ST, ~ S Y M M E T R I C ' , 'TR!DIAGONAL' 'POSITIVE DEFINITE'), METHOD ('RATQR'), V A L U E S (W, M, ' S M A L L E S T ' ) . C o m p u t a t i o n a l e c o n o m y r e s u l t s only w h e n the l a r g e s t (smallest) e i g e n v a l u e s of a n e g a t i v e (positive) d e f i n i t e m a t r i x are sought. N o t e that s u b p a r a m e t e r W to VALUES m u s t be of d i m e n s i o n at least N, if the r a t i o n a l QR method is used, even t h o u g h only M e i g e n v a l u e s are requested. Note

Note

2:

~HERM!TIAN'

For are

a real m a t r i x , synonymous.

3:

EPSI

as

for

Real

Matrices.

~HERMiTIAN'

a Subparameter

to

and

'SYMMETRIC'

VALUES.

EPSI is a long p r e c i s i o n real v a r i a b l e w h i c h s u p p l i e s an a b s o l u t e error t o l e r a n c e for the c o m p u t e d e i g e n v a l u e s w h e n only a few e i g e n v a l u e s (or a few e i g e n v a l u e s and their c o r r e s p o n d i n g eigenvectors) are b e i n g c a l c u l a t e d for the s t a n d a r d or g e n e r a l i z e d r e a l s y m m e t r i c p r o b l e m s ; or for the non-symmetric g e n e r a l i z e d p r o b l e m w h e r e all e i g e n v a l u e s and p o s s i b l y e i g e n v e c t o r s are b e i n g found. If the input v a l u e of EPSI is nonp o s i t i v e , a s u i t a b l e d e f a u l t value, w h i c h is r e l a t e d to the m a c h i n e p r e c i s i o n and the n o r m of the m a t r i x , is u s e d in p l a c e of EPSI; this same d e f a u l t is u s e d if EPSI is not s u p p l i e d to EiSPAC. The input value, if any, of EPSI is not a l t e r e d w h e n the d e f a u l t v a l u e is e m p l o y e d ; h o w e v e r , for the s t a n d a r d p r o b l e m only, the (last) d e f a u l t v a l u e used m a y be e x a m i n e d by m e a n s of a user s u b r o u t i n e s u p p l i e d as the s u b p a r a m e t e r to SUBR (see above). To s u p p l y EPSI to E!SPAC, s u b s t i t u t e for the r e c o m m e n d e d call to VALUES: V A L U E S (W, MM, M, RLB, RUB, EPSI) or VALUES (ALPHAR, ALPHAI, BETA, EPSI) as a p p r o p r i a t e . If e i g e n v a l u e s only (no e i g e n v e c t o r s ) are b e i n g computed, EPSI may be u s e d to c o n t r o l the tradeoff b e t w e e n c o m p u t a t i o n time and a b s o l u t e a c c u r a c y of the c o m p u t e d e i g e n v a l u e s , if less (or more) a c c u r a c y than that g i v e n by the d e f a u l t v a l u e of EPSI is r e q u i r e d .

542

7.2-20

If e i g e n v a l u e s and t h e i r c o r r e s p o n d i n g e i g e n v e c t o r s are b e i n g c o m p u t e d , e x t r e m e care m u s t be taken in c h o o s i n g a v a l u e for EPSI o t h e r than the d e f a u l t , since if EPSI is too large, the e i g e n v e c t o r s may be p o o r b e c a u s e the e i g e n v a l u e s are not s u f f i c i e n t l y a c c u r a t e ; w h e r e a s if EPSI is s m a l l e r than n e c e s s a r y for c o n v e r g e n c e , the a d d i t i o n a l a c c u r a c y of the c o m p u t e d e i g e n v a l u e s w i l l not i n c r e a s e the a c c u r a c y of the e i g e n v e c t o r s . For f u r t h e r d i s c u s s i o n , or in case of d i f f i c u l t y , see section 2.3.3 of (6), and also the NATS s u b r o u t i n e d o c u m e n t s for F 2 2 3 TINVIT, F294 BISECT, F 2 3 7 TRIDIB, and F239 QZIT (2). Note

4:

Class which

of N o n - S y m m e t r i c Eigenvectors may

Tridiagonal be Found.

Matrices

for

The class of real n o n - s y m m e t r i c t r i d i a g o n a l m a t r i c e s for w h i c h e i g e n v e c t o r s can be c o m p u t e d is s o m e w h a t m o r e r e s t r i c t e d than that for w h i c h e i g e n v a l u e s can be found. For the e i g e n v e c t o r c o m p u t a t i o n to be s u c c e s s f u l , not only m u s t the p r o d u c t s of c o r r e s p o n d i n g o f f - d i a g o n a l e l e m e n t s all be n o n - n e g a t i v e , but also w h e n such a p r o d u c t is zero~ the c o r r e s p o n d i n g o f f - d i a g o n a l e l e m e n t s m u s t b o t h be zero. Note

5:

'UNITARY'

for

Real

For a r e a l m a t r i x , are s y n o n y m o u s . Note

6:

Symmetric

Band

Matrices.

'UNITARY'

Matrices

and

of Half

'ORTHOGONAL'

Bandwidth

2.

If MB is s p e c i f i e d as 2 for a real s y m m e t r i c band m a t r i x , EISPAC s e l e c t s the same s u b r o u t i n e s as if 'TRIDIAGONAL' h a d b e e n s p e c i f i e d as a s u b p a r a m e t e r to MATRIX. Note

7:

Generalized

Problem

Matrix

Subparameters.

As d i s c u s s e d e a r l i e r , for a p r o b l e m to be c l a s s i f i e d "Real S y m m e t r i c G e n e r a l i z e d " , the A and B i n p u t m a t r i c e s m u s t each be s y m m e t r i c w i t h B positive definite. U n l e s s ' S Y M M E T R I C ' is s p e c i f i e d as a s u b p a r a m e t e r to MATA and b o t h ' S Y M M E T R I C ' and ' P O S I T I V E D E F I N I T E ' are s p e c i f i e d as s u b p a r a m e t e r s to MATB, EISPAC w i l l select a p a t h c o r r e s p o n d i n g to the real n o n - s y m m e t r i c g e n e r a l i z e d case i n s t e a d (and a s s u m e s t o r a g e of the full A and B matrices).

543

7.2-21

Note

8:

Eigenvalues Problem.

for

the N o n - S y m m e t r i c

Generalized

The d i v i s i o n s ALPHAR(1)/BETA(1) and ALPHAI(1)/BETA(1) to o b t a i n the real and i m a g i n a r y parts of the e i g e n v a l u e s for the real n o n - s y m m e t r i c g e n e r a l i z e d p r o b l e m are left to the user. The arrays ALPHAR, ALPHAI, and BETA t h e m s e l v e s are r e t u r n e d i n s t e a d , b e c a u s e they h a v e m o r e i n f o r m a t i o n than the q u o t i e n t s w h e n B (or b o t h A and B) is n e a r l y s i n g u l a r . Indeed, if B is s i n g u l a r , at least one e l e m e n t of BETA w i l l be zero and d i v i s i o n dare not be a t t e m p t e d . Note

9:

N e g a t i o n and A b b r e v i a t i o n Subparameters.

of A l p h a n u m e r i c

Any alphanumeric subparameter (e.g., 'BALANCE') is n e g a t e d if its i m m e d i a t e l y p r e c e d i n g s u b p a r a m e t e r is 'NO', 'NON', or 'NOT' S i m i l a r l y , the subparameters 'YES', 'IS', 'USE', and 'DO' act as i d e n t i t y a l p h a n u m e r i c s u b p a r a m e t e r s . These c o n v e n t i o n s are u s e f u l w h e n you d e s i r e to use a single EISPAC call to c o m p u t e the e i g e n s y s t e m of a m a t r i x w h i c h s o m e t i m e s is to be b a l a n c e d and s o m e t i m e s not, say, since the s u b p a r a m e t e r 'NO' or 'YES' m a y be an a l p h a n u m e r i c v a r i a b l e . Any a l p h a n u m e r i c s u b p a r a m e t e r m a y be a b b r e v i a t e d by e n o u g h of its i n i t i a l l e t t e r s to u n a m b i g u o u s l y d i s t i n g u i s h it f r o m all other a l p h a n u m e r i c subparameters. For p r o t e c t i o n a g a i n s t a m b i g u i t i e s a r i s i n g f r o m the f u t u r e i n t r o d u c t i o n of n e w alphanumeric subparameters, y o u s h o u l d use at least three (perhaps four) letter a b b r e v i a t i o n s w h e n they exist. The a l p h a n u m e r i c s u b p a r a m e t e r s c u r r e n t l y in use are l i s t e d b e l o w ( s y n o n y m s are s e p a r a t e d by commas, a n t o n y m s by h y p h e n s ) : DO', 'IS', 'USE ~, 'YES' NO', 'NON', 'NOT' R E A L ~ - 'COMPLEX' HERMITIAN' 'GENERAL' (see n o t e 2) S Y M M E T R I C ' - 'GENERAL' TRIDIAGONAL' - 'FULL' POSITIVE DEFINITE' NEGATIVE DEFINITE' BALANCE' ORTHOGONAL' - 'ELEMENTARY' ~UNITARY' 'ELEMENTARY' (see n o t e 5) ~AX=LBX', 'AZ=WBZ' 'ABX=LX', 'ABZ=WZ' 'BAX=LX' 'BAZ=WZ' 'LARGEST ~ - 'SMALLEST' -

-

544

7.2-22

As a f i n a l e x a m p l e i l l u s t r a t i n g t h e s e c o n c e p t s , s u p p o s e you w i s h to c o m p u t e the e i g e n v a l u e s and e i g e n v e c t o r s of an order N real g e n e r a l m a t r i x w i t h o u t b a l a n c i n g and u s i n g o r t h o g o n a l t r a n s f o r m a t i o n s , w i t h r e t r i e v a l of the e r r o r i n d i c a t o r and calls to a u s e r s u b r o u t i n e , in a program with variables dimensioned: A(100,100), WR(100), WI(100), Z(100,100). T h e n two of s e v e r a l p o s s i b l e calls are: CALL E I S P A C (i00, N, M A T R I X ('REAL', A), V A L U E S (WR, WI), V E C T O R (Z), M E T H O D ( ' O R T H O G O N A L ' , 'NO', ' B A L A N C E ' ) , E R R O R (IERROR), SUBR (USUB)) C A L L E I S P A C (i00, N, M A T R I X ('NOT', ' C O M P L E X ' , A), M E T H O D ('USE', 'ORTHOG', 'NO' 'NO' 'NO', 'BALAN'), V A L U E S (WR, WI), V E C T O R (Z), SUBR (USUB), E R R O R (IERROR)) ( R e c a l l in the last e x a m p l e that k e y w o r d p a r a m e t e r s can a p p e a r in any o r d e r in the third p a r a m e t e r p o s i t i o n and b e y o n d . )

D.

Error

Conditions

and

Returns.

T h r e e types of e r r o r s can o c c u r in EISPAC: "decision p h a s e " e r r o r s , " e x e c u t i o n p h a s e " e r r o r s , and " l i n k a g e " errors. (See s e c t i o n 3 below.) Decision phase errors arise when EISPAC d e t e c t s a m i s t a k e or i n c o n s i s t e n c y in the f o r m of the p a r a m e t e r s it r e c e i v e s . Execution p h a s e e r r o r s are t h o s e w h i c h it d e t e c t s d u r i n g the e x e c u t i o n of the e i g e n s y s t e m - p a c k a g e subroutines themselves. D e c i s i o n p h a s e e r r o r s a l w a y s r e s u l t in a m e s s a g e d e s c r i b i n g the e r r o r and the f u r t h e r m e s s a g e " E X E C U T I O N C O N T I N U I N G " or " E X E C U T I O N T E R M I N A T E D " and the a p p r o p r i a t e action. Execution phase errors always r e s u l t in a m e s s a g e d e s c r i b i n g the e r r o r and t e r m i n a t i o n of e x e c u t i o n , u n l e s s the ERROR k e y w o r d was s u p p l i e d (see b e l o w ) . L i n k a g e e r r o r s may o c c u r e i t h e r d u r i n g the d e c i s i o n or e x e c u t i o n p h a s e s and a l w a y s c a u s e t e r m i n a t i o n of execution. Linkage error 00 a r i s e s w h e n the i n t e r n a l file n a m e EISPACLB has not b e e n a s s o c i a t e d w i t h a d a t a s e t v i a a DD c a r d or A L L O C command. Linkage error 01 a r i s e s w h e n such an a s s o c i a t i o n has b e e n m a d e but a r e q u e s t e d s u b r o u t i n e or p h a s e of EISPAC c a n n o t be f o u n d in the a s s o c i a t e d d a t a s e t . In this case, c h e c k that it c o n t a i n s the r e q u i r e d e i g e n s y s t e m - p a c k a g e s u b r o u t i n e s and the p h a s e s of EISPAC. (See s e c t i o n s 3 and 5 b e l o w . )

545

7.2-23

You m a y m o d i f y the b e h a v i o r of EiSPAC w h e n an e x e c u t i o n p h a s e e r r o r is d e t e c t e d by s u p p l y i n g the ERROR keyword. W h e n it is s u p p l i e d , its s u b p a r a m e t e r IERROR is set to a v a l u e c h a r a c t e r i z i n g the e r r o r and r e t u r n is m a d e to the c a l l i n g p r o g r a m (i.e., e x e c u t i o n is not t e r m i n a t e d ) . F u r t h e r m o r e , y o u m a y s u p p r e s s the p r i n t i n g of the e r r o r m e s s a g e by s e t t i n g IERROR to the value -755 870 989 before calling EISPAC. A n o n - z e r o v a l u e of IERROR on r e t u r n f r o m EISPAC i n d i c a t e s that an e x e c u t i o n p h a s e e r r o r has o c c u r r e d . If IERROR is p o s i t i v e , the c o m p u t a t i o n has b e e n a b a n d o n e d , and few, if any, u s e f u l r e s u l t s h a v e b e e n produced. H o w e v e r , if IERROR is n e g a t i v e , the c o m p u t a t i o n has b e e n c o n t i n u e d d e s p i t e the e r r o r ( s ) and some m e a n i n g f u l r e s u l t s h a v e b e e n p r o d u c e d ; use of the ERROR k e y w o r d thus p e r m i t s y o u to r e c o v e r t h e s e results. The values IERROR m a y a s s u m e and t h e i r s i g n i f i c a n c e are d i s c u s s e d below. (See a l s o (2) and (6) . ) V a l u e of iERROR

Error Msg. No. None

Significance No e x e c u t i o n

phase

errors

occurred.

I

O0

The c a l c u l a t i o n of the l-th e i g e n v a l u e f a i l e d to c o n v e r g e . If the e i g e n s y s t e m of a r e a l or c o m p l e x g e n e r a l m a t r i x or for a n o n - s y m m e t r i c g e n e r a l i z e d p r o b l e m was b e i n g computed, eigenvalues I+I,I+2,...,N s h o u l d be c o r r e c t ; o t h e r w i s e , eigenvalues 1,2,...,I-I s h o u l d be correct.

N+I

0i

For a real n o n - s y m m e t r i c tridiagonal matrix, A(I,I)*A(I-I,3) .LT. 0, v i o l a t i n g the r e s t r i c t i o n d i s c u s s e d above. No u s e f u l r e s u l t s are produced.

2*N+I

02

For the e i g e n v e c t o r s of a real n o n symmetric tridiagonal matrix, A(I,I) and A(I-I,3) v i o l a t e d the r e s t r i c t i o n of n o t e 4, above. All e i g e n v a l u e s , b u t no e i g e n v e c t o r s , are correct.

546

7.2-24

3*N+I

03

Either: (i) Parameter MM specified i n s u f f i c i e n t s t o r a g e to h o l d all of the e i g e n v a l u e s in the i n t e r v a l (RLB,RUB). The only u s e f u l r e s u l t is M, w h i c h c o n t a i n s the n u m b e r of e i g e n v a l u e s w h i c h lie in the interval. Or: (2) It is n o t p o s s i b l e to c o m p u t e exactly M eigenvalues (starting f r o m the M l l - t h ) b e c a u s e of exact m u l t i p l i c i t y at i n d e x MII. No u s e f u l r e s u l t s are p r o d u c e d .

3"N+2

04

It is not p o s s i b l e to c o m p u t e e x a c t l y M e i g e n v a l u e s ( s t a r t i n g f r o m the M l l - t h ) b e c a u s e of exact m u l t i p l i c i t y at i n d e x MII+M-I. No u s e f u l r e s u l t s are p r o d u c e d .

4*N+I

None

5*N+I

05

The M l a r g e s t or s m a l l e s t e i g e n v a l u e s w e r e b e i n g c o m p u t e d by the r a t i o n a l QR m e t h o d and the I-th e i g e n v a l u e f a i l e d to c o n v e r g e . All e i g e n v a l u e s p r o b a b l y h a v e some a c c u r a c y , b u t no s t r o n g e r s t a t e m e n t can be made.

6*N+I

06

The M l a r g e s t or s m a l l e s t e i g e n v a l u e s w e r e b e i n g c o m p u t e d by the r a t i o n a l QR m e t h o d , the m a t r i x was s p e c i f i e d n e g a t i v e or p o s i t i v e d e f i n i t e , but the c o m p u t a t i o n s u g g e s t s it m a y not be; try a g a i n o m i t t i n g the d e f i n i t e n e s s specification. No u s e f u l r e s u l t s are produced.

7*N+I

07

The e i g e n s y s t e m for a real s y m m e t r i c generalized problem was being c o m p u t e d and the m a t r i x s u p p l i e d to MATB was not p o s i t i v e d e f i n i t e . No u s e f u l r e s u l t s are p r o d u c e d .

50

The c a l c u l a t i o n of one or m o r e e i g e n v e c t o r s i n c l u d i n g the l-th f a i l e d to c o n v e r g e . All eigenvalues and the n o n - z e r o e i g e n v e c t o r s are correct.

-I

Not

used

547

in

EISPAC.

7.2-25

-(N+I)

None

2*N+I)

52

3*N+I)

None

Both error 50 below occurred.

above

and

error

52

Parameter MM specified insufficient c o l u m n s to h o l d the s e l e c t e d eigenvectors. A l l e i g e n v a l u e s and the f i r s t MM c o l u m n s of (ZR, ZI) or Z are c o r r e c t . This error above will n o r m a l l y be but m a y be subroutine

p r e d i c t s that e r r o r 02 occur. It w i l l not returned from EISPAC o b s e r v e d w h e n the u s e r is e m p ! o y e d .

In a d d i t i o n to the a b o v e e r r o r s w h i c h are d i a g n o s e d by EISPAC, o t h e r e r r o r s m a y p r o d u c e S y s t e m / 3 6 0 - 3 7 0 c o m p l e t i o n codes (SCC). The m o s t c o m m o n l y p r o d u c e d c o m p l e t i o n codes and t h e i r m e a n i n g s in c o n j u n c t i o n w i t h EISPAC are the f o l l o w i n g : 804

T h e r e was not e n o u g h s t o r a g e to d y n a m i c a l l y load a r e q u e s t e d s u b r o u t i n e . Provide more s t o r a g e (region), r e d u c e the size of the e i g e n p r o b l e m b e i n g solved, or c h o o s e a p a t h w h i c h r e q u i r e s less t e m p o r a r y s t o r a g e (see (I) and (6)). The m i n i m u m s t o r a g e r e q u i r e m e n t for EISPAC is a p p r o x i m a t e l y 2 2 , 0 0 0 ( d e c i m a l ) b y t e s on S y s t e m / 3 6 0 - 3 7 0 .

606

Same

80A

T h e r e was not e n o u g h s t o r a g e t e m p o r a r y v e c t o r or m a t r i x ~ u n d e r S C C 8 0 4 above.

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

and

as

SCC804

above. to a l l o c a t e a See s u g g e s t i o n s

Restrictions°

EiSPAC is a p p l i c a b l e to the s o l u t i o n of the s t a n d a r d and g e n e r a l i z e d e i g e n s y s t e m p r o b l e m s for the c l a s s e s of m a t r i c e s for w h i c h e x a m p l e s are g i v e n above. For f u r t h e r d e t a i l s on a p p l i c a b i l i t y , see (6), or c o n s u l t the " E I S P A C E i g e n s y s t e m P a t h C h a r t " (I) to d e t e r m i n e w h i c h s u b r o u t i n e s are u s e d in the p a t h of i n t e r e s t and then the NATS s u b r o u t i n e d o c u m e n t s (2) for t h o s e subroutines.

548

7.2-26

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

OF M E T H O D

AND

ALGORITHM.

EISPAC c o n s i s t s of t h r e e m a j o r parts, the p a r a m e t e r i n t e r p r e t e r phase, the d e c i s i o n phase, and the e x e c u t i o n phase, w h i c h are c o - o r d i n a t e d by a s u p e r v i s o r . The s u p e r v i s o r e m p l o y s b r i e f a s s e m b l y l a n g u a g e r o u t i n e s to count the n u m b e r of s u b p a r a m e t e r s s u p p l i e d to each of the k e y w o r d s and the n u m b e r of p a r a m e t e r s s u p p l i e d to EISPAC itself. It then loads the p a r a m e t e r - i n t e r p r e t e r p h a s e d y n a m i c a l l y and p a s s e s the p a r a m e t e r i n f o r m a t i o n to it. The p a r a m e t e r - i n t e r p r e t e r p h a s e a n a l y z e s the p a r a m e t e r s , checks t h e m for c o n s i s t e n c y , s u p p l i e s d e f a u l t s for o m i t t e d optional parameters, and p r o d u c e s a c h a r a c t e r i z a t i o n of the p r o b l e m they specify. It r e t u r n s this c h a r a c t e r i z a t i o n and s t a n d a r d i z e d list of p a r a m e t e r s to the s u p e r v i s o r .

a

If errors h a v e b e e n d e t e c t e d in the p a r a m e t e r - i n t e r p r e t e r phase, the s u p e r v i s o r loads an error m e s s a g e m o d u l e d y n a m i c a l l y w h i c h prints error m e s s a g e s and w h i c h m a y terminate execution. O t h e r w i s e , the s u p e r v i s o r loads a d e c i s i o n p h a s e a p p r o p r i a t e to the p r o b l e m b e i n g solved and p a s s e s the c h a r a c t e r i z a t i o n to it. The d e c i s i o n p h a s e d e t e r m i n e s the "path", or s e q u e n c e , of e i g e n s y s t e m - p a c k a g e s u b r o u t i n e s and a u x i l i a r y a c t i o n s (e.g., t e m p o r a r y s t o r a g e a l l o c a t i o n s ) n e e d e d to solve the s p e c i f i e d e i g e n p r o b l e m . It then r e t u r n s a r e p r e s e n t a t i o n of this p a t h to the s u p e r v i s o r . The s u p e r v i s o r then calls the e x e c u t i o n phase, w h i c h i n t e r p r e t s the r e p r e s e n t a t i o n of the path (and i n f o r m a t i o n about order of e x e c u t i o n ) to load d y n a m i c a l l y the r e q u i r e d e i g e n s y s t e m s u b r o u t i n e s and to a l l o c a t e and free n e e d e d t e m p o r a r y storage. (Loading, a l l o c a t i n g , and f r e e i n g are p e r f o r m e d by o p e r a t i n g s y s t e m r e q u e s t s c o n t a i n e d in b r i e f assembly language routines.) W h e n e x e c u t i o n is c o m p l e t e , or as soon as a f a t a l error occurs, the e x e c u t i o n p h a s e r e t u r n s to the s u p e r v i s o r . If e x e c u t i o n p h a s e e r r o r s have o c c u r r e d and error m e s s a g e s are to be p r i n t e d (see s e c t i o n 2.D above), the s u p e r v i s o r loads the error m e s s a g e m o d u l e d y n a m i c a l l y and p r i n t s them; e x e c u t i o n t e r m i n a t e s or c o n t i n u e s as d e s c r i b e d above. When execution continues, the s u p e r v i s o r r e t u r n s the r e s u l t s of the c o m p u t a t i o n to the c a l l i n g program. C e r t a i n e c o n o m i e s of e x e c u t i o n are p o s s i b l e w h e n EISPAC is c a l l e d r e p e a t e d l y to solve the same e i g e n p r o b l e m . A f t e r the f i r s t e x e c u t i o n of the path for the p r o b l e m , u s a b l e copies of the e i g e n s y s t e m - p a c k a g e s u b r o u t i n e s for it may r e m a i n in m e m o r y (if s u f f i c i e n t s t o r a g e is a v a i l a b l e ) , and if so they are r e u s e d w i t h o u t b e i n g r e l o a d e d on s u b s e q u e n t e x e c u t i o n s of the path.

549

7.2-27

The design and i m p l e m e n t a t i o n of EISPAC are highly modular, so that additional subroutines and paths can be added relatively easily and with only a m i n i m u m of disturbance to existing paths. This modular design of EISPAC and the p h i l o s o p h y behind it are discussed in detail in (7).

4. REFERENCES~

i)

Boyle, J~M., Hauser, C.H., and Rothaar, H.R., EISPAC E i g e n s y s t e m Package Path Chart, R e l e a s e 2, Argonne N a t i o n a l Laboratory, Applied M a t h e m a t i c s Division, February, 1975.

2)

NATS Project, E i g e n s y s t e m Subroutine Package Subroutines F269 to F298 and F220 to F247.

3)

Wilkinson, J.H. and Reinsch, C., H a n d b o o k for Automatic Computation, Volume II, Linear Algebra, Springer-Verlag,

(EISPACK),

(i97i). 4)

Wilkinson, J.H., The Algebraic Eigenvalue Oxford, C l a r e n d o n Press (1965).

5)

Rutishauser, H., I n t e r f e r e n c e With an Algol-Procedure, Annual Review in Automatic Programming, Vol. 2 (R. Goodman, Ed.), P e r g a m o n Press, (1961).

6)

This publication. (Reference retained to resolve User Guide pointers, thus enabling c o m p a t i b i l i t y with d i s t r i b u t e d documentation.)

7)

Boyle, J.M. and Grau, A.Ao, Modular Design of a UserOriented Control P r o g r a m for EISPACK, Applied M a t h e m a t i c s D i v i s i o n T e c h n i c a l M e m o r a n d u m No. 242, Argonne National Laboratory, Argonne, Illinois 60439, November 1973.

5. PROGRAM

Problem,

STATISTICS.

A. A d d i t i o n a l

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 p r o g r a m 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 a d d i t i o n , the other p h a s e s of EISPAC c o n t a i n entry p o i n t s w i t h the n a m e s DGNHEP, DGSHEP, DIDFEP, DSNHEP, EGNHEP, EGSHEP, ERMSEP, ERSEP, ESNHEP, FIDFEP, IBCMEP, IBCOM#, ICHREP, INTREP, and LKUPEP. T h e s e entry p o i n t s w i l l not, h o w e v e r , c o n f l i c t w i t h those in y o u r p r o g r a m , since these p h a s e s are loaded d y n a m i c a l l y .

B. C o m m o n

Storage.

None.

C.

Space

Requirements.

The parts of EISPAC loaded w i t h your p r o g r a m (subroutine EISPAC and the s u p e r v i s o r ) r e q u i r e 2738 (HEX) = 10040 (DECIMAL) bytes under F O R T R A N H, OPT=2, R e l e a s e 21.7 of 0S/360. However, EISPAC r e q u i r e s an a d d i t i o n a l a m o u n t of s t o r a g e for the d y n a m i c a l l y l o a d e d s u b r o u t i n e s and the t e m p o r a r y a r r a y s some of t h e m require. At a m i n i m u m , this r e q u i r e m e n t is 2EA0 (HEX) = 11936 (DECIMAL) bytes for the p a r a m e t e r i n t e r p r e t e r p h a s e of EISPAC. D u r i n g e x e c u t i o n , up to 3100 (HEX) = 12544 (DECIMAL) bytes are r e q u i r e d for the a p p r o p r i a t e e x e c u t i o n p h a s e of EISPAC and a t y p i c a l EISPACK s u b r o u t i n e , plus w h a t e v e r a d d i t i o n a l s t o r a g e is n e e d e d for d y n a m i c a l l y a l l o c a t e d t e m p o r a r y arrays. See (I) and (2) for f u r t h e r i n f o r m a t i o n for e s t i m a t i n g this dynamically-determined a m o u n t of storage.

6.

CHECKOUT. A.

Test

Cases.

EISPAC has b e e n tested on the same m a t r i c e s separate EISPACK subroutines. See S e c t i o n " V A L I D A T I O N OF E I S P A C K " .

as have 3 --

B. A c c u r a c y . The a c c u r a c y of EISPAC d e p e n d s d i r e c t l y u p o n the s u b r o u t i n e s u s e d f r o m the EISPACK p a c k a g e (2). C o n s u l t the p a t h chart (i) to learn w h i c h s u b r o u t i n e s h a v e b e e n s e l e c t e d , and then r e f e r e n c e the s e p a r a t e a c c u r a c y s t a t e m e n t s that a p p l y to these s u b r o u t i n e s .

551

the