Lecture Notes in Computer Science Edited by G. Goos and J. Hartmanis
6 B. T. Smith. J. M. Boyle • J. J. Dongarra B. S. ...
12 downloads
494 Views
19MB Size
Report
This content was uploaded by our users and we assume good faith they have the permission to share this book. If you own the copyright to this book and it is wrongfully on our website, we offer a simple DMCA procedure to remove your content from our site. Start by pressing the button below!
Report copyright / DMCA form
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
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
",..~
~'~ ~