ebooksclub.org matrix eigensystem routines eispack guide lecture notes in computer science vol 6
TRANSCRIPT
Lecture Notes in Computer Science Edited by G. Goos and J. Hartmanis
6
B. T. Smith. J. M. Boyle B. S. Garbow. Y. Ikebe C. B. Moler
• J. J. Dongarra • V. C. Klema
Matrix Eigensystem EISPACK Guide Second Edition
Routines -
I I I II III
Springer-Verlag Berlin.Heidelberg. New York 19 76
Editorial Board P. Brinch Hansen ° D. Gries • C. Moler . G. SeegmLiller o J. Stoer N. Wirth
Dr. Brian T. Smith Applied Mathematics Division Argonne National Laboratory 9700 South Cass Avenue Argonne, IL 60439/USA
Library of Congress Cataloging in Publication Data
Main entry under title:
Matrix eigensystem r~atines.
(Lectures notes in computer science ; 6) includes bibliog#aphi es. i. EZSPACK (Computer program) Z. Smith~
B~ian T. ZL Series. QA193. M57 1976 512.9'43' 0285425 76-2662
AMS Subject Classif icat ions (1970): 15A18, 65F15 CR Subject Classif icat ions (1974): 5.14
ISBN 3-540-07546q 2. Aufiage Springer-Verlag Berlin • Heidelberg • New York ISBN 0-387-07546-1 2nd edition Springer-Verlag New York • Heidelberg • Berlin ISBN 3-540-06710-8 1, Aufiage Springer-Verlag Berl in. Heidelberg. New York ISBN 0-387-06710-8 1st edition Springer-Vedag New York " Heidelberg . Berlin
This work is subject to copyright. All rights are reserved, whether the whole or part of the material is concerned, specifically those of translation, re- printing, re-use of illustrations, broadcasting, reproduction by photocopying machine or similar means, and storage in data banks.
Under § 54 of the German Copyright Law where copies are made for other than private use, a fee is payable to the publisher, the amount of the fee to be determined by agreement with the publisher.
© by Springer-Vertag Berlin • Heidelberg 1976 Printed in Germany Printing and binding: Beltz Offsetdruck, Hemsbach/Bergstr.
PREFACE TO THE SECOND EDITION
The EISPACK eigensystem package as documented in the first edition of
this guide has expanded in both depth and breadth in its second release.
A set of subroutines affording additional variants for the six problem
classes encompassed in the first release has been added. Another set of
additional subroutines has extended the applicability of EISPACK to new
problem classes; prominent among these are the real symmetric band
standard eigenproblem, the symmetric and non-symmetric real generalized
eigenproblems, and the singular value decomposition of an arbitrary matrix.
The EISPAC control program has also been extended to include most of the
newer capability afforded by the additional subroutines in the package.
However, except for the documentation of the EISPAC control program, the
scope of this edition of the guide is still limited to the original six
problem classes and therefore includes additionally only the first of the
two sets of newer subroutines added to EISPACK. Restricting the scope in
this manner has markedly reduced both the time otherwise required to produce
the book and its potential size. It has also enabled timely updating of
the listings and documents of those earlier subroutines that have been
improved in this release. A subsequent volume in this series is planned
that will include the other new subroutines and cover the additional problem
classes that can now be handled by the package.
EISPACK is a product of the NATS (N_ational Activity to T_est S_oftware)
Project ([3],[4],[5]) which has been guided by the principle that the effort
to produce high quality mathematical software is justified by the wide
use of that software in the scientific community. EISPACK has been dis-
tributed to several hundred computer centers throughout the world since
the package was first released in May, ]972, and now the second release
is available as described in Section 5.
Building a systematized collection of mathematical software is
necessarily a collaborative undertaking demanding the interplay of a
variety of skills; we wish to acknowledge a few whose roles were especially
crucial during the preparation of the second release. J. Wilkinson per-
sisted in his encouragement of the project and his counsel was often sought
during his frequent visits to North America. Organization and direction
came from W. Cowell and J. Pool, utilizing funds provided by the National
Science Foundation and the Energy Research and Development Administration.
The field testing was carried out at the installations listed in Section 5
through the sustained efforts of M. Berg, A. Cline, D. Dodson, B. Einarsson,
S. Eisenstat, I~ Farkas~ P. Fox, C. Frymann, H. Happ, L. Harding, H. Hull,
D. Kincaid, P. Messina, M. Overton, R. Raffenetti, J. Stein, J. Walsh, and
J. Wang. Appreciation is also expressed for the very important feedback
received from users not formally associated with the testing effort.
Finally, we acknowledge the skill and cooperation of our typist, J. Beumer.
iV
TABLE OF CONTENTS
SECTION 1
INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
i. Organization of the guide . . . . . . . . . . . . . . . . . . . . .
2. Accuracy of the EISPACK subroutines . . . . . . . . . . . . . . . .
SECTION 2
HOW TO USE EISPACK . . . . . . . . . . . . . . . . . . . . . . . . . .
i. Recommended basic paths in EISPACK . . . . . . . . . . . . . . . .
i.i All eigenvalues and corresponding eigenvectors of a
complex general matrix . . . . . . . . . . . . . . . . . . .
1.2 All eigenvalues of a complex general matrix .........
1.3 All eigenvalues and selected eigenvectors of a complex general matrix . . . . . . . . . . . . . . . . . . . . . . .
1.4 All eigenvalues and corresponding eigenvectors of a complex Hermitian matrix . . . . . . . . . . . . . . . . . .
1.5 All eigenvalues of a complex Hermitian matrix ........
1.6 Some eigenvalues and corresponding eigenvectors of a complex Hermitian matrix . . . . . . . . . . . . . . . . . .
1.7 Some eigenvalues of a complex Hermitian matrix .......
1.8 All eigenvalues and corresponding eigenvectors of a real general matrix . . . . . . . . . . . . . . . . . . . . . . .
1.9 All eigenvalues of a real general matrix ..........
i. I0 All eigenvalues and selected eigenvectors of a real general matrix . . . . . . . . . . . . . . . . . . . . . . .
I.ii All eigenvalues and corresponding eigenvectors of a real symmetric matrix . . . . . . . . . . . . . . . . . . . . . .
1.12 All eigenvalues of a real symmetric matrix .........
1.13 Some eigenvalues and corresponding eigenvectors of a real symmetric matrix . . . . . . . . . . . . . . . . . . . . . .
1.14 Some eigenvalues of a real symmetric matrix .........
14
16
17
19
21
22
24
26
28
30
32
34
35
37
1.15 All eigenvalues and corresponding eigenvectors of a real symmetric tridiagonal matrix . . . . . . . . . . . . . . . .
1.16 All eigenvalues of a real symmetric tridiagonal matrix . . .
1.17 Some eigenvalues and corresponding eigenvectors of a real symmetric tridiagonal matrix . . . . . . . . . . . . . . . .
1.18 Some eigenvalues of a real symmetric tridiagonal matrix. . ,
1.19 All eigenvalues and corresponding eigenvectors of a special
real tridiagonal matrix . . . . . . . . . . . . . . . . . . .
1.20 All eigenvalues of a special real tridiagonal matrix ....
1o21 Some eigenvalues and corresponding eigenvectors of a special
real tridiagonal matrix . . . . . . . . . . . . . . . . . . .
1.22 Some eigenvalues of a special real tridiagonal matrix ....
2. Variations of the recommended EISPACK paths . . . . . . . . . . . .
2.1 Non-balancing of complex and real general matrices .....
2.2 Orthogonal reduction transformations to real Hessenberg
form . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 The implicit and explicit QL algorithms . . . . . . . . . . .
2.4 The rational QR algorithm for finding a few extreme
eigenvalues . . . . . . . . . . . . . . . . . . . . . . . . .
2.5 The use of TSTURM as an alternate to BISECT-TINVIT .....
2.6 Elementary similarity transformations for complex
general matrices . . . . . . . . . . . . . . . . . . . . . .
2.7 IMTQLV-TINVIT pairing in paths for partial eigensystems. .
2.8 Specification of boundary eigenvalue indices to the
bisection process . . . . . . . . . . . . . . . . . . . . . .
2,9 Packed representations of real symmetric and complex
Hermitian matrices . . . . . . . . . . . . . . . . . . . . .
3. Additional information and examples . . . . . . . . . . . . . . . .
3.1 Selecting the eigenvectors of real and complex general
matrices . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 Unpacking the eigenvectors of a real general matrix .....
39
41
43
46
48
50
52
55
57
59
62
65
68
71
74
76
78
80
83
84
88
VI
3.3 The EPSI parameter . . . . . . . . . . . . . . . . . . . . . 91
3.4 Relative efficiencies of computing partial and complete
eigensystems . . . . . . . . . . . . . . . . . . . . . . . . 95
3.5 Determination of the signs of the eigenvalues ........ 98
3.6 Orthogonal similarity reduction of a real matrix to
quasi-triangular form . . . . . . . . . . . . . . . . . . . . 100
3.7 Additional facilities of the EISPAC control program ..... 102
3.8 Non-zero values of IERR . . . . . . . . . . . . . . . . . . . 111
3.9 Examples illustrating the use of the EISPACK subroutines
and the control program . . . . . . . . . . . . . . . . . . . 115
SECTION 3
VALIDATION OF EISPACK . . . . . . . . . . . . . . . . . . . . . . . . . 124
SECTION 4
EXECUTION TIMES FOR EISPACK . . . . . . . . . . . . . . . . . . . . . . 127
i. Tables of execution times . . . . . . . . . . . . . . . . . . . . . 128
2. Repeatability and reliability of the measured execution times. . . 177
3. Dependence of the execution times upon the matrix ......... 178
4. Extrapolation of timing results to other machines and compilers. 180
5. The sample matrices for the timing results . . . . . . . . . . . . 182
SECTION 5
CERTIFICATION AND AVAILABILITY OF EISPACK . . . . . . . . . . . . . . . 185
SECTION 6
DIFFERENCES BETWEEN THE EISPACK SUBROUTINES AND THE HANDBOOK ALGOL
PROCEDURES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
SECTION 7
DOCUMENTATION AFD SOURCE LISTINGS . . . . . . . . . . . . . . . . . . . 194
i. EISPACK subroutines . . . . . . . . . . . . . . . . . . . . . . . . 196
2. EISPAC control program . . . . . . . . . . . . . . . . . . . . . . 524
VII
LIST OF TABLES
7-9°
10-12.
13-15.
16-18.
19-21.
22-24.
25-27.
28-30.
31-33.
34-36.
37-39.
40-42.
43-45.
46-48.
49.
i. Sections describing the recommended basic paths in EISPACK . . . 13
2. ISUBNO values and parameter names for subroutine calls from
EISPAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
3. Summary of values of IERR . . . . . . . . . . . . . . . . . . . . 112
4-6. Execution times on the IBM 370/195 at Argonne National
Laboratory . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Execution times on the IBM 360/75 at University of Illinois. . . 133
Execution times on the IBM 370/168 at University of Michigan . . 136
Execution times on the IBM 370/165 at The University of Toronto. 139
Execution times on the Burroughs 6700 at University of
California, San Diego . . . . . . . . . . . . . . . . . . . . . . 142
Execution times on the CDC 6600 at Kirtland Air Force Base . . . 145
Execution times on the CDC 6600 at NASA Langley Research Center. 148
Execution times on the CDC 7600 at National Center for
Atmospheric Research . . . . . . . . . . . . . . . . . . . . . . 151
Execution times on the CDC 6400 at Northwestern University . . 154
Execution times on the CDC 6400/6500 at Purdue University. . . 157
Execution times on the CDC 6600/6400 at The University of Texas. 160
Execution times on the Honeywell 6070 at Bell Laboratories . 163
Execution times on the Univac 1110 at The University of
Wisconsin . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Execution times on the DEC PDP-10 at Yale University ...... 169
Execution times on the Amdahl 470V/6 at University of Michigan . 172
Execution times for the EISPACK driver subroutines over various
computer systems . . . . . . . . . . . . . . . . . . . . . . . . 175
50. Execution times for the EISPAC control program on the
IBM 370/195 at Argonne National Laboratory . . . . . . . . . . . 176
REFERENCES
i°
2.
3.
4.
5.
6.
7.
Wilkinson, J. H. and Reinsch, C., Handbook for Automatic Computation,
Volume II, Linear Algebra, Part 2, Springer-Verlag, New York,
Heidelberg, Berlin, 1971.
Wilkinson, J. _~., The Algebraic Eigenvalue Problem, Clarendon Press,
Oxford, 1965.
Boyle, J. M., Cody, W. J., Cowell, W. R., Garbow, B. S., Ikebe, Y.,
Moler, C. B°, and Smith, B. T., NATS, A Collaborative Effort to Cer-
tify and Disseminate Mathematical Software, Proceedings 1972 National
ACM Conference, Volume II, Association for Computing Machinery,
New York, 1972, pp. 630-635.
Smith, B. T., The NATS Project, A National Activity to Test Software,
SHARE SSD 228, October, 1972, item C-5732, pp. 35-42.
Smith, B. T., Boyle, J. M., Cody, W. J., The NATS Approach to Quality
Software, Software for Numerical Mathematics, D. J. Evans, ed., Academic
Press, London, New York, 1974, pp. 393-405.
Boyle, J. M. and Grau, A. A., Modular Design of a User-Oriented
Control Program for EISPACK, Technical Memorandum No. 242, Applied
Mathematics Division, Argonne National Laboratory, 1973.
Garbow, B. S., E!SPACK - A Package of Matrix Eigensystem Routines,
Computer Physics Co~nunications, North-Holland, Amsterdam, Vol. 7,
1974, pp. 179-184.
1.0-i
Section i
INTRODUCTION
The package of Fortran IV programs given the acronym EISPACK is a
systematized collection of subroutines which compute the eigenvalues
and/or eigenveetors of six classes of matrices; namely, complex general,
complex Hermitian, real general, real symmetric, real symmetric tridiagonal,
and special real tridiagonal matrices. The subroutines are based mainly
upon Algol procedures published in the Handbook series of Springer-Verlag
by Wilkinson and Reinsch [i], have been adapted and thoroughly tested on
several different machines, and have been certified and are supported by
the NATS project [3,4,5]. The machines for which they are certified in-
clude IBM 360-370, CDC 6000-7000, Univac iii0, Honeywell 6070, DEC PDP-10,
and Burroughs 6700.
This manual is a user guide to EISPACK and to a control program
EISPAC available with the IBM version of the package. It contains pro-
gram segments which illustrate each of the basic computations with EISPACK
and discusses variants of these that provide mild tradeoffs of efficiency,
storage, and accuracy. Other sections of the guide discuss the validation
procedures used for testing EISPACK, report execution times of the EISPACK
subroutines on several machines, advertise the certified status and avail-
ability of EISPACK, and describe the major differences between the published
Algol procedures in [i] and their Fortran counterparts. The final section
includes detailed documentation with Fortran listings of each EISPACK sub-
routine and the document for the control program.
Section !.i
ORGANIZATION OF THE GUIDE
i.i-I
This guide is organized for the convenience, hopefully, of the user.
Material most pertinent to the basic uses of the package and the control
program appears in the early sections and references the more detailed
and specific information in later sections. Here follows a brief descrip-
tion of the organization of the guide.
The remaining subsection of this introduction is a general statement
with regard to the expected accuracy of the results from EISPACK. This
statement is based upon the careful and detailed analyses of Wilkinson and
others. Only a brief overview is provided in this subsection and the
interested reader is directed to [I] and [2] for more detailed statements
of accuracy.
Section 2 is divided into a prologue and three major subsections.
The prologue introduces the concept of an EISPACK path, discusses the
economies that can be realized with the use of the control program if avail
able, and instructs on the selection among the 22 basic paths. The first
subsection establishes several conventions that are useful in clarifying
the discussions of the paths. It then details the 22 basic paths and
associated control program calls in the form of program segments. Each
program segment is introduced by a brief description of the problem it
solves and any specific considerations needed for the path, and is
followed by a summary of array storage requirements for the path and
sample execution times on the IBM 370/195 computer. The next subsection
describes possible variants of the 22 basic paths, focusing on those con-
ditions for which the variants are to be preferred. The last subsection
provides further information about specific details of EISPACK and the
1.1-2
control program and suggests several additional applications of the
package. Complete sample programs illustrating the use of EISPACK and
EISPAC to solve a specified eigenproblem appear at the end of this
subsection.
Section 3 outlines the validation procedures for EISPACK that led to
the certification of the package. Section 4 reports sample execution
times of the individual subroutines and of several of the program segments
of Section 2 and also discusses such considerations as the dependence of
the execution times upon the matrix and the computer. The statement of
certification for EISPACK, the machines and operating systems on which
it has been certified, and its availability appear in Section 5. Section
6 itemizes the principal differences between the Fortran subroutines and
their Algol antecedents published in [I]. Finally, the documentation and
Fortran listing for each subroutine appear in edited form in Section 7.
1.2-i
Section 1.2
ACCURACY OF THE EISPACK SUBROUTINES
The most useful statement that can be made with regard to the accuracy
of the EISPACK subroutines is that they are based on algorithms which are
numerically stable; that is~ for every computed eigenpair (%,z) asso-
ciated with a matrix A, there exists a matrix E with norm small compared
to that of A for which % and z are an exact eigenpair of A+E. This back-
ward or inverse approach in describing the accuracy of the subroutines is
necessitated by the inherent properties of the problem which, in general,
preclude the more familiar forward approach. However, for real symmetric
and complex Hermitian matrices the forward approach also applies, and in-
deed is a consequence of the backward analysis. For these matrices the
eigenvalues computed by EISPACK must be close to the exact ones, but a
similar claim for the eigenvectors is not possible. What is true in this
case is that the computed eigenvectors will be closely orthogonal if the
subroutines that accumulate the transformations are used.
The size of E, of course, is crucial to a meaningful statement of
accuracy, and the reader is referred to the detailed error analyses of
Wilkinson and others ([1],[2]). In our many tests of EISPACK, we have
seldom observed an E with norm larger than a small multiple of the product
of the order of the matrix A, its norm, and the precision of the machine.
2.0-1
Section 2
HOW TO USE EISPACK
This section is designed to provide, in readily accessible form, the
basic information you need to correctly use subroutines from EISPACK to
solve an eigenproblem. The way in which this information is presented
is influenced by the design of the eigensystem package; hence we will
first consider briefly the global structure of EISPACK.
EISPACK is capable of performing 22 different basic computations,
plus several variations of them. If each of these computations (and var-
iations) were performed completely within a single EISPACK subroutine,
the package would be unwieldy indeed. It also would be highly redundant,
since the same steps appear in many of the computations. To avoid these
problems, the subroutines in EISPACK are designed so that each performs
a basic step which appears in one or more of the computations. (See [7]
for an introduction to the modularization of EISPACK.) Consequently,
the redundancy (hence the size) of the package is minimized.
Another consequence is that, in general, more than one subroutine from
EISPACK is required to perform a given computation. These subroutines must
of course be called in the correct order and with the proper parameters;
in addition, some computations also require certain auxiliary actions,
e.g., initializing parameters and testing for errors. Throughout the re-
mainder of this book such an ordered set of subroutine calls and associated
auxiliary actions will be called an EISPACK path.
As a result of this structure the documentation for the use of EISPACK
comprises two main parts: a description of the basic paths and their var-
iations, and a description of the individual subroutines in EISPACK. The
information about the paths constitutes the remainder of this section
while the subroutine documentation is collected in Section 7.
2.0-2
The path descriptions are divided into three parts. Section 2.1
describes the 22 basic paths and includes a table to facilitate reference
to them. Section 2.2 describes some of the variations of these paths and
suggests when such variations might be useful. Section 2.3 contains cer-
tain additional information about and examples of the use of EISPACK. To
keep the descriptions of the basic paths and their variants simple~ we
have omitted much of the detailed information (e.g., the meanings of non-
zero error indicators and the descriptions of certain parameters) and
collected it in Section 2.3. Detailed information about each subroutine
may be obtained from the documentation for the individual subroutines in
Section 7. We hope, however, that the information given in this section
will be sufficient to permit you to correctly solve most eigenproblems.
The detail of path information that you must know to solve certain
basic eigenproblems can be reduced by using an appropriate driver sub-
routine to build the desired path from other EISPACK members. Applica-
bility of the driver subroutines is limited to those problems where all
eigenvalues and eigenvectors or all eigenvalues only are desired. There
is a driver subroutine for each class of matrices handled by the package;
driver subroutine calls corresponding to twelve of the 22 basic paths are
given as part of the discussion of the paths in this section.
Substantial further reduction in the detail of path information
that you must know to solve an eigenproblem, with wider applicability,
can be achieved by use of a control program, called EISPAC, which is
available with the IBM version of the eigensystem package [6]. (It is
only practical to implement this control program on those computing sys-
tems which adequately support execution-time loading of subroutines.)
EISPAC accepts a relatively straightforward problem description stated
2.0-3
in terms of the properties of the input matrix and the kinds of results
required. It checks this description for consistency, automatically
selects and executes the appropriate path, and then returns the results
to your program. Thus EISPAC not only simplifies the use of the eigen-
system package, but also enhances its robustness by eliminating the
possibility of making errors in transcribing a path.
To use EISPAC, you call it with a set of parameters which describes
the problem you wish to solve, and which enables EISPAC to choose the
appropriate path. EISPAC calls corresponding to the 22 basic paths (and
most of their variations) are given as a further part of the discussion
of the paths in this section. Note that in order to use EISPAC~ you must
provide system control cards defining the file from which the EISPACK
subroutines are to be loaded; this and other detailed information on the
use of EISPAC can be found in its subroutine document in Section 7.2.
2.1-I
Section 2.1
RECOMMENDED BASIC PATHS IN EiSPACK
This section describes how to use EISPACK to compute some or all of
the eigenvalues, or some or all of the eigenvalues and their correspond-
ing eigenvectors, for the six classes of matrices mentioned in Section I.
The paths recommended here provide accurate solutions for their respective
eigenproblems using a minimum of storage. Under some circumstances,
variations of these paths (using different subroutines) may provide
slightly more accurate or speedier solutions; these variations are dis-
cussed in Section 2.2.
To determine the recommended path to solve your particular eigen-
problem, consult Table I at the end of this section. First, decide to
which of the six classes of matrices listed across the top of the table
your matrix belongs. In general, the computation will be more accurate
and efficient if you use any known special properties of the matrix to
place it in the most specialized applicable class. Thus a matrix which
is real symmetric is better classified so, than as real general or complex.
On the other hand, some special properties cannot be utilized; for example,
a complex matrix, even though known to be symmetric (not Hermitian), must
be classified as complex general.
Next, determine which of the problem classifications listed down the
left side of Table 1 most closely matches the subset of eigenvalues and
eigenvectors you wish to find. The table entry so determined indicates
the subsection which describes the recommended path for your problem.
(If variations of the path exist, the subsection will refer you to Sec-
tion 2.2 for them.) For example, if you have a full (not tridiagonal)
2.1-2
real symmetric matrix and you wish to find all its eigenvalues and their
corresponding eigenvectors, the table directs you to Section 2.1.11.
Each subsection to which the table refers provides just the infor-
mation you need to use the described path correctly. It begins with a
statement of the problem and an identification of the main input and
result variables. The subroutine calls and auxiliary statements consti-
tuting the path are given and are followed by the corresponding driver
subroutine call, if applicable, and the EISPAC call. Next is a descrip-
tion of additional parameters (if any) appearing in the path and a brief
summary of the disposition of the results of the computation. Dimension
information for the arrays appearing in the path and a summary of the
total amount of array storage used is then given. These are followed by
indicative timing results. (Timing considerations are discussed more
fully in Section 4.) The subsection concludes with references to appli-
cable subsections of Section 2.2.
We have employed a few conventions in these subsections to streamline
the presentation of information. One of these concerns the types of the
parameters. Except for SELECT (and TYPE in Section 2.2.4), to which type
LOGICAL applies, all parameters have their Fortran implied type: those
beginning with I, J, K, L, M, or N are type INTEGER, and the others are
what will be called working preci~on~ which denotes either type REAL or
type DOUBLE PRECISION depending on the version of EISPACK being used.
A second convention concerns certain parameters which are used only
to pass intermediate results from one subroutine to another. The roles
of these parameters are not described in the subsections, since only their
type and dimension need be known to execute a path correctly. To facili-
tate recognition of these parameters, they are written in lower case~
2.1-3
employing a systematic nomenclature. Their names are composed of f or i
to indicate type (working precision or integer), s, v, or m to indicate
dimensionality (scalar, vector, or matrix), and a serial number. Thus
fv2 is used for the first working precision temporary vector to appear
in a given paths
A third convention is used to indicate how the array parameters in
a path are dimensioned. It employs two "variables" ~ and ~, which must
be replaced in array declarator statements by Fortran integer constants.
The parameters NM and MM communicate the values of these constants to
array declarator statements in the EISPACK subroutines; therefore NMmust
be set to the constant used for ~ and MM set to that used for ~. It
is of utmost importance that whenever a path is executed, N and, if used~
M, satisfy N ~r~ and M in; otherwise unpredictable errors will occur.
An example may help clarify the use of ~ and ~. Suppose you are
using the path described in Section 2.1.13. Considering only the parameters
Aj W, and Z, the dimension information is stated there as A(~,~), W(~),
and Z(nm,~). If the largest matrix for which you intend to use this
paah is of order 50, and if you do not expect to compute more than i0
eigenvalues and eigenvectors, you might use the array deelarator statement
DIMENSION A(50,50) ,W(IO) ,Z(50, i0)
together with
NM= 50
MM= i0
You would, of course~ set N to the actual order of the matrix A for each
execution of the path; it must satisfy N ~ 50. Similarly, M will be set
10
2.1-4
(by the path) to the number of eigenvalues determined; it must satisfy
M< i0.
The summary of the total amount of array storage used by a path is
given in terms of the order parameters N and M, rather than in terms of
nm and turn. Thus it represents the minimum array storage required to
execute the path for a given order matrix, achieved when ~ is equal to
N and ~ is equal to M. Note that when using the EISPAC control program
you need not dimension any parameters which do not appear in the call to
EISPAC (i.e., those named according to the second convention above) since
it allocates them for you. This does not, however, reduce the minimum
storage required, which remains as indicated in the summary.
A fourth convention relates to the calls to driver subroutines when
eigenvalues only are computed. In such a case the formal parameter(s)
corresponding to the eigenvector matrix Z or (ZR, ZI), although required,
is(are) not referenced in the subroutine; the variable name DUMMY will
appear instead at the corresponding position(s) in the calling statement.
A final convention concerns the handling of execution errors in a
path. Certain EISPACK subroutines may fail to satisfactorily perform
their step of the computation; in this case an error parameter, universally
denoted by IERR, is set to a non-zero value indicating the type of error
which occurred. In many cases the execution of a path must not be allowed
to continue after such an error; hence a conditional branch to statement
number 99999 is inserted in each path after each subroutine call which
may set the parameter IERR. Appropriate action at statement 99999 might
be to print IERR and stop. Each distinct error that can occur in EISPACK
produces one of a unique set of values for IERR. The possible values of
IERR and their meanings, together with an indication of whether or not any
11
2. i-5
partial results have been correctly computed, are summarized in Section
2.3.8; more detailed information on IERR can be obtained by consulting
the documents for the individual subroutines. If you are using EISPAC~
it will print a message describing any errors which occur and terminate
execution, unless you elect to examine !ERR as discussed in Section 2.3.7
and in the EISPAC document.
In summary, to select the recommended EISPACK path to solve your
eigenproblem, consult Table I and then read the subsection to which it
refers in light of the above conventions, Note that in order to ensure
correct execution of the path, you must, in addition to providing input
data and result storage, do the following: provide arrays for storage of
intermediate or temporary results, call the subroutines in the path in
the correct order, pass parameters from one call to the next exactly as
described, and perform certain auxiliary actions. Alternatively, if the
control program EISPAC is included in your version of EISPACK, you may
simply call it and let it perform these tasks for you.
12
2.1-6
TABLE 1
SECTIONS DESCRIBING THE RECOMMENDED BASIC PATHS IN EISPACK
lass of X
Classification~
All Eigenvalues & Corresponding Eigenvectors
All Eigenvalues
All Eigenvalues & Selected Eigenvectors
Some Eigenvalues & Corresponding Eigenvectors
Some Eigenvalues
Real Complexl Complex Real Real Symmetric GeneraliHemitianGeneral Symmetric Tridiagonali
2.1.1 2.1.4 2.1.8 2.1.11
2.1.2 2.1.5
2.1.3
Special Real
Tridiagonal
2.1.6
2.1.7
2.1.9
2.1.10
2.1.12
2.1.13
2.1.14
2.1.15 2.1.19
2.1.16 2.1.20
2.1.17 2.1.21
2. I. 18 2.1.22
13
2.1-7
Section 2.1.i
ALL EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A COMPLEX GENERAL MATRIX
To determine all the eigenvalues (WR,WI) and their corresponding
eigenvectors (ZR,ZI) of a complex general matrix (AR,AI) of order N, the
recommended E!SPACK path is:
CALL CBAL(NM,N,AR,AI,isl,is2,fvl)
CALL CORTH(N~M,N,isl,is2,AR,AI,fv2,fv3)
CALL COMQR2(NM,N,isl,is2,fv2,fv3,AR,AI,WR,WI,ZR,ZI,IERR)
IF (IERR .NE. 0) GO TO 99999
CALL CBABK2(NM,N,is!,is2,fvI,N,ZR,ZI)
or, using driver subroutine CG:
CALL CG(NM,N,AR,AI,WR,WI, I,ZR,ZI,fV2 ,fv2,fv3 ,IERR)
IF (IERR .NE. 0) GO TO 99999
or, using EISPAC:
CALL EISPAC(NM,N,MATRIX('COMPLEX',AR,AI),VALUES(WR,WI),VECTOR(ZR, ZI))
This path destroys AR and AI.
Suitable dimensions for the arrays are: AR(nm,~m), Al(~,nm), WR(nm),
Wl(r~n), ZR(~,ryn), Zi(r~m,r~m), fv1(r~), fv2(~n), and fv3(r~).
The array storage required to execute this path is 4N 2 + 5N working
precision words.
Indicative execution times for this path (run on an IBM 370/195) are
.038, .24, 1.7, and 13 seconds for sample matrices of order I0, 20, 40, and
80 respectively.
14
2.1-8
Variants of this path omit the balancing of the input matrix or sub
stitute elementary for unitary transformations; see Sections 2.2.1 and
2.2.6.
15
2.1-9
Section 2ol.2
ALL EIGENVALUES OF A COMPLEX GENERAL MATRIX
To determine all the eigenvalues (WR, WI) of a complex general matrix
(AR,A!) of order N, the recommended EISPACK path is:
CALL CBAL(NM,N,AR,AI,isl,is2,fvl)
CALL CORTH(I~i,N,isl,is2,AR,AI,fv2,fv3)
CALL COMQR(NM, N,isl,is2,AR,AI,WR,WI,IERR)
IF (IERR .NE. 0) GO TO 99999
or~ using driver subroutine CG:
CALL CG(NM,N,AR,AI,WR,WI,O,DUMMY,DUMMY,fvl,fv2,fv3,1ERR)
IF (IERR .NE. 0) GO TO 99999
or, using EiSPAC:
CALL EISPAC(NM, N,MATR!X('COMPLEX',AR,AI),VALUES(WR,WI))
This path destroys AR and AI.
Suitable dimensions for the arrays are: AR(z~n,nm), Al(nm,~), WR(nm),
Wl(nm), fv1(r~), fv2(nm), and fv3(nm).
The array storage required to execute this path is 2N 2 + 5N working
precision words~ (2N working precision words could be saved by using
WR and WI for fv2 and fv3; another N working precision words could be
saved by identifying ~1 and fv2.)
Indicative execution times for this path (run on an IBM 370/195) are
.022, .12, °78, and 5.7 seconds for sample matrices of order I0, 20, 40, and
80 respectively.
Variants of this path omit the balancing of the input matrix or sub-
stitute elementary for unitary transformations; see Sections 2.2.1 and 2.2.6.
16
2. i-i0
Section 2.1.3
ALL EIGENVALUES AND SELECTED EIGENVECTORS OF A COMPLEX GENERAL MATRIX
To determine all the eigenvalues (WR,WI) and certain eigenveetors
(ZR, ZI) (those corresponding to eigenvalues flagged by .TRUE. elements
in the LOGICAL array SELECT) of a complex general matrix (AR,AI) of
order N, the reco~ended EISPACK path is:
CALL CBAL(NM,N,AR,AI,isl,is2,fvl)
CALL CORTH(NM, N,isl,is2,AR,AI,fv2,fv3)
DO i00 1 = i, N
DO 50 J = I, N
fm/(I,J) = AR(I,J)
~m2(l,J) = AI(I,J)
50 CONTINUE
i00 CONTINUE
CALL COMQR(NM,N,isl,i82,~l,fm2,WR,WI,IERR)
IF (IERR .NE. 0) GO TO 99999
CALL CINVIT(NM, N,~m,AI,WR,WI,SELECT,MM, M, ZR, ZI,IERR,fml,fm2,fv4,fv5)
IF (IERR .NE. 0) GO TO 99999
CALL CORTB(NM, isl,is2,AR,AI,fv2,fv3,M, ZR, ZI)
CALL CBABK2(NM,N,isl,is2,fvl,M,ZR,ZI)
or, using EISPAC:
CALL EISPAC(NM,N,MATRIX('COMPLEX',AR,AI),VALUES(WR,WI),
VECTOR(ZR,ZI,MM,M, SELECT))
See Section 2.3.1 for a discussion of the SELECT array. Upon comple
tion of the path, M is set to the number of columns of ZR and ZI used,
17
2.1-11
and provided MM is sufficiently large, the computed eigenvectors corres-
ponding to the flagged eigenvalues are stored in the first M columns of
ZR and ZI. If MM is not sufficiently large, then IERR is set non-zero,
M is set to MM, and only the first M selected vectors are computed
provided that the interrupted path is completed. (IERR is also set non-
zero if a vector fails to converge.) This path destroys AR and AI.
Suitable dimensions for the arrays are: AR(~,~), AI(~,~),
WR(nm), Wl(nJn), ZR(nm,mm), Zl(nm,mm), SELECT(nm), fml(nm,nm), fm2(nm,nm),
fvl(nm), fv2(nm), fv3(n~m), fv4(nm), and ~5(nm).
The array storage required to execute this path is 4N 2 + N(2M+7)
working precision words and N logical words.
Indicative execution times for this path (run on an IBM 370/195),
when computing all N eigenvectors, are .040, .22, 1.3, and 9.7 seconds for
sample matrices of order i0, 20, 40, and 80 respectively. Extrapolation
of these execution times for cases where M is less than N is discussed in
Section 4.
Variants of this path omit the balancing of the input matrix or sub-
stitute elementary for unitary transformations; see Sections 2.2.1 and
2.2.6.
18
2.1-12
Section 2.1.4
ALL EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A COMPLEX HERMITIAN MATRIX
To determine all the eigenvalues W and their corresponding eigenvectors
(ZR,ZI) of a complex Hermitian matrix (AR,AI) of order N, the recommended
EISPACK path is:
CALL HTRIDI (NM,N,AR,AI ,W,fv2 ,fv l ,fml)
DO i00 1 = I, N
DO 50 J = i, N
ZR(I,J) = 0.0
50 CONTINUE
ZR(I,I) = 1.0
i00 CONTINUE
CALL TQL2(NM,N,W,fv2,ZR,IERR)
IF (IERR .NE. O) GO TO 99999
CALL HTRIBK(NM,N,AR,AI,fm2,N,ZR,ZI)
or, using driver subroutine CH:
CALL CH(NM,N,AR,AI,W,I,ZR,ZI,fv2,fvJ,fmI,IERR)
IF (IERR .NE. O) GO TO 99999
or, using EISPAC:
CALL EISPAC(NM,N,MATRIX('COMPLEX',AR,AI,'HERMITIAN'),VALUES(~),VECTOR(ZR,ZI))
This path returns the eigenvalues in ascending order and a set of complex
orthonormal eigenvectors; it preserves the full upper triangle of All and
the strict upper triangle of AI.
19
2.1-13
Suitable dimensions for the arrays are: AR(r~n,~), Al(~,r~n), W(~),
ZR(n~n,nm), ZI (nm,nm), fvl (nm), and fml(2,nm).
The array storage required to execute this path is 4N 2 . 4N working
precision words.
Indicative execution times for this path (run on an IBM 370/195) are
.011, .065, °44, and 3.2 seconds for sample matrices of order i0, 20, 40,
and 80 respectively.
Variants of this path substitute the implicit for the explicit QL
shift or proceed from a packed form representation of the input matrix;
see Sections 2.2.3 and 2.2.9.
20
2.1-14
Section 2.1.5
ALL EIGENVALUES OF A COMPLEX HERMITIAN MATRIX
To determine all the eigenvalues W of a complex Hermitian matrix (AR,AI)
of order N, the recommended EISPACK path is:
CALL HTRIDI(NM, N,AR,AI,W,fvl,fv2,fm2)
CALL TQLRAT(N,W,fv2,1ERR)
IF (IERR .NE. 0) GO TO 99999
or, using driver subroutine CH:
CALL CH(NM,N,AR,AI,W,O,DUMMY,DUMMY,fvl,fv2,fmT,IERR)
IF (IERR .NE. O) GO TO 99999
or, using EISPAC:
CALL EISPAC(NM,N,MATRIX('COMPLEX',AR,AI,'HERMITIAN'),VALUES(W))
This path returns the eigenvalues in ascending order; it preserves the
full upper triangle of AR and the strict upper triangle of AI.
Suitable dimensions for the arrays are: AR(n~n,nm), AI(mm,nm), W(nm),
fvl(nm), fv2(nm), and fml(2,nm).
The array storage required to execute this path is 2N 2 + 5N working
precision words.
Indicative execution times for this path (run on an IBM 370/195) are
.005, .022, .14, and 1.0 seconds for sample matrices of order I0, 20, 40,
and 80 respectively.
Variants of this path substitute the explicit or implicit for the
rational QL shift or proceed from a packed form representation of the
input matrix; see Sections 2.2.3 and 2.2.9.
2~
2.1-15
Section 2.1.6
SOME EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A COMPLEX HERMiTIAN MATRIX
To determine the eigenvalues W in an interval extending from RLB to
RUB, together with their corresponding eigenvectors (ZR,ZI), of a complex
Hermitian matrix (AR,AI) of order N, the recommended EISPACK path is:
CALL HTRIDI (NM,N ,AR,AI ~7 ,fv2 ,fv 3 ,fml )
EPSI = 0~0
CALL BISECT (N, EPS 1 ,fvi ,fv2 ,fv3 ,RLB ,RUB ,MM,M ,w,ivl, IERR,fv4 ,fvS)
IF (IERR ~NE. 0) GO TO 99999
CALL TINVIT(NM,N,fvl,fv2,fv3,M,W,ivl ,ZR,!ERR,fv4,fv5,fv6,fv7,fvS)
IF (IERR ~NE. 0) GO TO 99999
CALL HTRIBK(NM,N,AR,AI ,fml ,M,ZR, ZI)
or, using EISPAC:
CALL EISPAC(I~M,N,MATRIX('COMPLEX',AR,AI,'HERMITIANI),
VALUES(W,MM,M,RLB,RUB),VECTOR(ZR,ZI))
The parameter EPSI is used to control the accuracy of the eigenvalue
computation° Setting it to zero or calling EISPAC without supplying it
causes the use of a default value suitable for most matrices. Further in-
formation about the use of EPSI can be found in Section 2.3.3 and in the
BISECT and EISPAC documents~ Upon completion of the path, M is set to
the number of eigenvalues determined to lie in the interval defined by
RLB and RUB and, provided M !MM, the eigenvalues are in ascending order
in W and their corresponding complex orthonormal eigenvectors are in the
first M columns of ZR and ZI. Note that, should the computed M be greater
than MM, BISECT sets iERR non-zero and does not compute any eigenvalues.
22
2.1-16
This path preserves the full upper triangle of AR and the strict upper tri-
angle of AI.
Suitable dimensions for the arrays are: AR(~,~), AI(~,r~n), W(~),
ZR(~w,~), ZI(~,~), fv1(r~), fv2Ozw), fv3(nm), fv4(r~w), fv5(~), fv6(r~n),
fv?(~), fv8(~), fml(2,~), and ivl(~).
The array storage required to execute this path is 2N 2 + I0N + M(2N+I)
working precision words and M integer words.
Indicative execution times for this path (run on an IBM 370/195), when
computing all N eigenvalues and eigenvectors, are .023, .I0, .52, and 3.2
seconds for sample matrices of order i0, 20, 40, and 80 respectively.
Extrapolation of these execution times for cases where M is less than N is
discussed in Section 4.
Variants of this path substitute the rational QR method or the implicit
QL method for the bisection process, allow the specification of boundary
eigenvalue indices instead of an interval to the bisection process, combine
the determination of the eigenvalues and eigenveetors of the symmetric
tridiagonal form into a single subroutine, or proceed from a packed form
representation of the input matrix; see Sections 2.2.4, 2.2.7, 2.2.8, 2.2.5,
and 2.2.9.
23
2.1-17
Section 2.1.7
SOME EiGENVALUES OF A COMPLEX HERMITIAN ~TRIX
To determine the eigenvalues W in an interval extending from RLB to RUB
of a complex Hermitian matrix (AR,AI) of order N, the recommended EISPACK
path is:
CALL HTRIDl(mi,N,AR,Al,~1,fv2,fv3,fm2)
EPSI = 0.0
CALL BISECT(N,EPSI,fv2,fv2,fv3,RLB,RUB,MM,M,W,iv2,1ERR,fv4,fv5)
IF (IERi oNE. 0) GO TO 99999
or, using EISPAC:
CALL EISPAC (NM~N ,MATRIX( ~ COMPLEX I ,AR,AI , ' HEP~MITIAN ' ) ,VALUES (W,~I,M,_R~B ,RUB) )
The parameter EPSI is used to control the accuracy of the eigenvalue
computation. Setting it to zero or calling EISPAC without supplying it
causes the use of a default value suitable for most matrices. Further infor-
nmtion about the use of EPSI can be found in Section 2.3.3 and in the BISECT
and EISPAC documents. Upon completion of the path, M is set to the number
of eigenvalues determined to lie in the interval defined by RLB and RUB
and, provided M ~MM, the eigenvalues are in ascending order in W. Note
that, should the computed M be greater than MM, BISECT sets IERR non-zero
and does not compute any eigenvalues. This path preserves the full upper
triangle of AR and the strict upper triangle of AI.
Suitable dimensions for the arrays are: AR(nm,nm), Al(nm,~), W(mm),
fv1(nm), fv2(nm), fv3(nm), fv4(nm), fv5(nm), fm1(2,nm), and ivl(mm).
The array storage required to execute this path is 2N 2 + 7N + M working
precision words and M integer words.
24
2.1-18
Indicative execution times for this path (run on an IBM 370/195), when
computing all N eigenvalues, are .019, .072, .32, and 1.7 seconds for sample
matrices of order i0, 20, 40, and 80 respectively. Extrapolation of these
execution times for cases where M is less than N is discussed in Section 4.
Variants of this path substitute the rational QR method for the bi-
section process, allow the specification of boundary eigenvalue indices
instead of an interval to the bisection process, or proceed from a packed
form representation of the input matrix; see Sections 2.2.4, 2.2.8, and 2.2.9.
25
2.1-19
Section 2~1.8
ALL EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A REAL GENERAL MATRIX
To determine all the eigenvalues (WR,WI) and their corresponding eigen-
vectors Z of a real general matrix A of order N, the recommended EISPACK
path is:
CALL BALANC (NM,N ,A,isl ,is2,fvl)
CALL ELMHES (NM,N ,is I ,is 2 ,A,ivl )
CALL ELTRAN(NM,N,isl,is2,A,ivl ,Z)
CALL HQR2 (NM,N ,is I ,is2 ,A,WR,WI, Z, IERR)
IF (IERR .NE. 0) GO TO 99999
CALL BALBAK(NM,N,isl ,is2 ,fvl ,N,Z)
or, using driver subroutine RG:
CALL RG(NM,N,A,WR,WI,I,Z,ivl,fvI,IERR)
IF (IERR oNE. 0) GO TO 99999
or, using EISPAC:
CALL EISPAC(NM,N,MATRIX('REAL',A),VALUES(WR,WI),VECTOR(Z))
Pairs of complex eigenvalues are stored in consecutive elements of (WR,WI)
with that member of the pair with positive imaginary part first. The corres-
ponding columns of Z contain the real and imaginary parts, respectively, of
the eigenvector associated with the eigenvalue of positive imaginary part.
See Section 2.3.2 for a discussion of the eigenveetor packing into Z. This
path destroys A.
Suitable dimensions for the arrays are: A(~n,~), WR(~), WI(~),
Z (~,~) , fvl (~), and ivl (nm).
26
2.1-20
The array storage required to execute this path is 2N 2 + 3N working pre
cision words and N integer words.
Indicative execution times for this path (run on an IBM 370/195) are
.019, .I0, .66, and 4.6 seconds for sample matrices of order I0, 20, 40,
and 80 respectively.
Variants of this path omit the balancing of the input matrix or sub-
stitute orthogonal for elementary reduction transformations; see Sections
2.2.1 and 2.2.2.
27
2.1-21
Section 2.1.9
ALL EIGENVALUES OF A REAL GENERAL MATRIX
To determine all the eigenvalues (WR,WI) of a real general matrix A of
order N, the recommended EISPACK path is:
CALL BALANC (NM,N ,A,isl ,is2 ,fvl )
CALL ELMHES (NM,N,isl ,is2,A,ivl)
CALL HQR(NM,N,isl ,is2 ,A,WR,WI ,IERR)
IF (IERR .NE. 0) GO TO 99999
or, using driver subroutine RG:
CALL RG(NM,N,A,WR,WI,O,DUMMY,iVl,fu2,!ERR)
IF (IERR .NE. 0) GO TO 99999
or, using EISPAC:
CALL EISPAC (NM,N ,MATRIX ( ' REAL ' ,A) ,VALUES (WR,WI))
Complex eigenvalue pairs are stored in consecutive elements of (WR,WI)
with that member of the pair with positive imaginary part first. This path
destroys A.
Suitable dimensions for the arrays are: A(r~n,r~n), WR(~), WI(~),
fvl (~), and iv1(~) °
The array storage required to execute this path is N 2 + 3N working pre-
cision words and N integer words. (N working precision words could be saved
by using WR or WI for fvl.)
Indicative execution times for this path (run on an IBM 370/195) are
.012, .056, o31, and 1.9 seconds for sample matrices of order I0, 20, 40,
and 80 respectively.
28
2.1-22
Variants of this path omit the balancing of the input matrix or sub-
stitute orthogonal for elementary reduction transformations; see Sections
2.2.1 and 2.2.2.
29
2.1-23
Section 2.1.10
ALL EIGENVALUES AND SELECTED EIGENVECTORS OF A REAL GENERAL MATRIX
To determine all the eigenvalues (WR,WI) and certain eigenvectors Z
(those corresponding to eigenvalues flagged by .TRUE. elements in the LOGICAL
array SELECT) of a real general matrix A of order N, the recommended EISPACK
path is:
CALL BALANC(NM,N,A,is2,is2,fvl)
CALL ELMHES(NM,N,is2,is2,A,iv2)
DO i00 1 = I, N
DO 50 J = I, N
fml(l,J) = A(I,J)
50 CONTINUE
I00 CONTINUE
CALL HQR(NM,N,isl,is2,fm2,WR,WI,IERR)
IF (IERR ,NE. 0) GO TO 99999
CALL INVIT(NM,N,A,WR,WI,SELECT,MM,M,Z,IERR,fmi,fv2,fv3)
IF (IERR .NE. 0) GO TO 99999
CALL ELMBAK(NM,isl,i82,A,iVI,M,Z)
CALL BALBAK(NM,N,isi,is2,fvl,M,Z)
or, using EISPAC:
CALL EISPAC(NM,N,MATRIX('REAL',A),VALUES(WR,WI),VECTOR(Z,MM,M,SELECT))
Complex eigenvalue pairs are stored in consecutive elements of (WR,WI)
with that member of the pair with positive imaginary part first. See Section
2.3.1 for a discussion of the SELECT array. Note in particular that if both
elements of SELECT corresponding to a pair of complex (conjugate) eigenvalues
30
2.1-24
are set to .TRUE., the second element will be reset to .FALSE.
Upon completion of the path, M is set to the number of columns of Z
used, and provided MM is sufficiently large, the computed eigenvectors cor-
responding to the flagged eigenvalues are stored in the first M columns of
Z. Note that the real and imaginary parts, respectively, of an eigenvector
corresponding to a complex eigenvalue occupy two consecutive columns of Z.
If MM is not sufficiently large, then IERR is set non-zero, M is set to MM
or MM-I, and only the selected vectors that can be stored in M columns of
Z are computed provided that the interrupted path is completed. (IERR is
also set non-zero if a vector fails to converge.) See Section 2.3.2 for a
discussion of the eigenvector packing into Z. This path destroys A.
Suitable dimensions for the arrays are: A(nm,nm), WR(nm), Wl(nm),
Z (~,mm), SELECT (nm), fro1 (nm,~), fvl (~), fv2 (nm), fv3 (r~m), and iv1 (nm).
The array storage required to execute this path is 2N 2 + N(M+5) work-
ing precision words, N logical words, and N integer words.
Indicative execution times for this path (run on an IBM 370/195), when
computing all possible (M=N) eigenvectors, are .019, .093, .53, and 3.5
seconds for sample matrices of order I0, 20, 40, and 80 respectively.
Extrapolation of these execution times for cases where M is less than N is
discussed in Section 4.
Variants of this path omit the balancing of the input matrix or sub-
stitute orthogonal for elementary reduction transformations; see Sections
2.2oi and 2.2.2.
31
2.1-25
Section 2.1.11
ALL EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A REAL SYMMETRIC MATRIX
To determine all the eigenvalues W and their corresponding eigenvectors
Z of a full real symmetric matrix A of order N, the recommended EISPACK path
is:
CALL TRED2(NM,N,A,W,fV2 ,Z)
CALL TQL2 (NM,N ,W,fV2 ,Z, IERR)
IF (iERR .NE. O) GO TO 99999
or, using driver subroutine RS:
CALL RS(NM,N,A~W,I,Z,fvi,fv2,1ERR)
IF (IERR oNE. O) GO TO 99999
or, using EISPAC:
CALL EISPAC(NM,N,Y~TRIX('REAL',A,'SYMMETRIC'),VALUES(W),VECTOR(Z))
This path returns the eigenvalues in ascending order and a set of ortho-
normal eigenvectors; it leaves A unaltered.
Suitable dimensions for the arrays are: A(nm,nm), W(r~), Z(~,nm),
a n d fvi (nm)~
The array storage required to execute this path is 2N 2 + 2N working
precision words. However, for this particular path the eigenvectors can
overwrite the input matrix if the same array parameter is used for both A
and Z, thereby reducing the storage required to N 2 + 2N working precision
words.
Indicative execution times for this path (run on an IBM 370/195) are
~007, ~036, .22, and 1.5 seconds for sample matrices of order i0, 20, 40,
and 80 respectively.
32
2.1-26
A variant of this path substitutes the implicit for the explicit QL
shift; see Section 2.2.3.
33
2.1-27
Section 2.1.12
ALL EIGENVALUES OF A REAL SYMMETRIC MATRIX
To determine ali the eigenvalues W of a full real symmetric matrix A
of order N~ the recommended EISPACK path is:
CALL TREDI(NM,N,A,W,fvl,fv2)
CALL TQLRAT(N,W,~,IERR)
IF (IERR 0NE. 0) GO TO 99999
or, using driver subroutine RS:
CALL RS(NM, N,A,W,O,DUMMY,fv2,fv2,1ERR)
IF (IERR .NE. 0) GO TO 99999
or, using EISPAC:
CALL EISPAC(NM,N,MATRIX('REAL',A,'SYMMETRIC'),VALUES(W))
This path returns the eigenvalues in ascending order; it preserves the
full upper triangle of A~
Suitable dimensions for the arrays are: A(~,n~), W(~), fvi(nm),
and fv2 (rim).
The array storage required to execute this path is N 2 + 3N working
precision words~
Indicative execution times for this path (run on an IBM 370/195) are
.003, .011, ~055, and .33 seconds for sample matrices of order i0, 20, 40,
and 80 respectively.
Variants of this path substitute the explicit or implicit for the
rational QL shift or proceed from a packed form representation of the
input matrix; see Sections 2.2.3 and 2.2.9.
34
2.1-28
Section 2.1.13
SOME EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A REAL SYMMETRIC MATRIX
To determine the eigenvalues W in an interval extending from RLB to
RUB, together with their corresponding eigenvectors Z, of a full real
symmetric matrix A of order N, the recommended EISPACK path is:
CALL TREDI (NM,N,A,fN2 ,fv2 ,fv3)
EPSI = 0.0
CALL BISECT(N,EPSI,fvl,fv2,fv3,RLB,RUB,MM,M,W,iv2,1ERR,fv4,fv5)
IF (IERR .NE. 0) GO TO 99999
CALL TINVIT (NM,N ,fv2 ,fv2 ,fv3 ,M,W ,iv2, Z, IERR ,fv4 ,fv5 ,fv6 ,fvf ,fvS)
IF (IERR .NE. 0) GO TO 99999
CALL TRBAKI(NM,N,A,fV2,M,Z)
or, using EISPAC:
CALL EISPAC(NM,N,MATRIX('REAL',A,'SYMMETRIC'),VALUES(W,MM,M,RLB,RUB),VECTOR(Z))
The parameter EPSI is used to control the accuracy of the eigenvalue
computation. Setting it to zero or calling EISPAC without supplying it
causes the use of a default value suitable for most matrices. Further in-
formation about the use of EPSI can be found in Section 2.3.3 and in the
BISECT and EISPAC documents. Upon completion of the path, M is set to the
number of eigenvalues determined to lie in the interval defined by RLB and
RUB and, provided M !MM, the eigenvalues are in ascending order in W and
their corresponding orthonormal eigenvectors are in the first M columns of
Z. Note that, should the computed M be greater than MM, BISECT sets IERR
non-zero and does not compute any eigenvalues. This path preserves the
full upper triangle of A.
35
2.1-29
Suitable dimensions for the arrays are: A(nm,nm), W(m~n), Z(nm,m3n),
fvl(n~n), fv2(nm), fv3(nm), fv4(nm), fv5(nm), ~6(nm), fvF(~n), fv8(nm),
and ivl(~n).
The array storage required to execute this path is N 2 + 8N + M(N+I)
working precision words and M integer words.
Indicative execution times for this path (run on an IBM 370/195), when
computing all N eigenvalues and eigenvectors, are .020, .075, .33, and 1.6
seconds for sample matrices of order I0, 20, 40, and 80 respectively.
Extrapolation of these execution times for cases where M is less than N
is discussed in Section 4.
Variants of this path substitute the rational QR method or the implicit
QL method for the bisection process, allow the specification of boundary
eigenvalue indices instead of an interval to the bisection process, combine
the determination of the eigenvalues and eigenvectors of the tridiagonal
form into a single subroutine, or proceed from a packed form representation
of the input matrix; see Sections 2.2.4, 2.2.7, 2.2.8, 2.2.5, and 2.2.9.
36
2.1-30
Section 2.1.14
SOME EIGENVALUES OF A REAL SYMMETRIC MATRIX
To determine the eigenvalues W in an interval extending from RLB to
RUB of a full real symmetric matrix A of order N, the recommended EISPACK
path is:
CALL TREDI (NM,N ,A,fvl ,fv2 ,fv3)
EPSI = 0.0
CALL BISECT (N,EPS 1 ,fv l ,fv2 ,fv3 ,RLB ,RUB ,MM,M,W ,iVl ,IERR,fv4 ,fv5)
IF (IERR .NE. 0) GO TO 99999
or, using EISPAC:
CALL EISPAC(NM,N,MATRIX('REAL',A,'SYMMETRIC'),VALUES(W,MM,M,RLB,RUB))
The parameter EPSI is used to control the accuracy of the eigenvalue
computation. Setting it to zero or calling EISPAC without supplying it
causes the use of a default value suitable for most matrices. Further
information about the use of EPSI can be found in Section 2.3.3 and in
the BISECT and EISPAC documents. Upon completion of the path, M is set
to the number of eigenvalues determined to lie in the interval defined by
RLB and RUB and, provided M !MM, the eigenvalues are in ascending order
in W. Note that, should the computed M be greater than MM, BISECT sets
IERR non-zero and does not compute any eigenvalues. This path preserves
the full upper triangle of A.
Suitable dimensions for the arrays are: A(nm,rm0, W(mm), fvl (rim),
fv2(nm), fv3(nm), fv4(nm), fv5(nm), and ivl(mm).
The array storage required to execute this path is N 2 + 5N + M
working precision words and M integer words.
37
2.1-31
Indicative execution times for this path (run on an IBM 370/195),
when computing all N eigenvalues, are .017, .061, .24, and 1.0 seconds for
sample matrices of order i0, 20, 40, and 80 respectively. Extrapolation
of these execution times for cases where M is less than N is discussed in
Section 4o
Variants of this path substitute the rational QR method for the bi-
section process, allow the specification of boundary eigenvalue indices
instead of an interval to the bisection process~ or proceed from a packed
form representation of the input matrix; see Sections 2.2.4~ 2.2.8, and 2.2.9.
38
2.1-32
Section 2.1.15
ALL EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A REAL SYMMETRIC TRIDIAGONAL MATRIX
A real symmetric tridiagonal matrix of order N can be presented to
EISPACK as a two-column array (or as two N-component vectors), the sub-
diagonal elements in the last N-I positions of the first column and the
diagonal elements in the second column. The first element in the first
column is arbitrary.
To determine all the eigenvalues W and their corresponding eigen-
vectors Z of a real symmetric tridiagonal matrix A of order N, the
recommended EISPACK path is:
DO i00 1 = i, N
DO 50 J = i, N
Z(l,J) = 0.0
50 CONTINUE
Z(I,I) = 1.0
W(1) = A(I,2)
fv2(i) = A(I,I)
I00 CONTINUE
CALL IMTQL2 (NM,N ,W,fv 2, Z, IERR)
IF (IERR .NE. 0) GO TO 99999
or, using driver subroutine RST:
CALL RST(NM,N,W,fu2, I,Z,IERR)
IF (IERR .NE. 0) GO TO 99999
39
2 .1 -33
or, using EISPAC:
CALL EISPAC (NM,N ,MATRIX ( v REAL v ,A, T SY~iETRIC ' , ' TR!D!AGONAL ' ) ,
VALUES(W),VECTOR(Z))
This path returns the eigenvalues in ascending order and a set of
orthonormal eigenvectors. Copying A into W and fvl preserves A of
course which would otherwise be destroyed. EISPAC, however, preserves
only the second column (diagonal elements) of A.
Suitable dimensions for the arrays are: A(nm,2), W(nm), Z(nm,nm),
and fvl (rim)°
The array storage required to execute this path is N 2 + 4N working
precision words. (2N working precision words could be saved by trans-
mitting the columns of A itself in place of fvl and W. Similarly, A(I,2)
could be transmitted to EISPAC in place of W.)
Indicative execution times for this path (run on an IBM 370/195) are
.005, .026, o15, and .97 seconds for sample matrices of order I0, 20, 40,
and 80 respectively.
A variant of this path substitutes the explicit for the implicit QL
shift; see Section 2.2.3.
40
2.1-34
Section 2.1.16
ALL EIGENVALUES OF A REAL SYMMETRIC TRIDIAGONAL MATRIX
A real symmetric tridiagonal matrix of order N can be presented to
EISPACK as a two-column array (or as two N-component vectors), the sub-
diagonal elements in the last N-I positions of the first column and the
diagonal elements in the second column. The first element in the first
column is arbitrary.
To determine all the eigenvalues W of a real symmetric tridiagonal
matrix A of order N, the recommended EISPACK path is:
DO i00 1 = i, N
W(1) = A(I,2)
fv1(~) = A(I,I)
i00 CONTINUE
CALL IMTQLI(N,W,fv2,1ERR)
IF (IERR .NE. 0) GO TO 99999
or, using driver subroutine RST:
CALL RST(NM,N,W,fV2,0,DUMMY,IERR)
IF (IERR .NE. 0) GO TO 99999
or, using EISPAC:
CALL EISPAC(NM,N,MATRIX('REAL',A,'SYMMETR!C','TRIDIAGONAL'),VALUES(W))
This path returns the eigenvalues in ascending order. Copying A into
W and fvl preserves A of course which would otherwise be destroyed. EISPAC,
however, preserves only the second column (diagonal elements) of A.
Suitable dimensions for the arrays are: A(nm,2), W(nm), and fv1(nm).
41
2.1-35
The array storage required to execute this path is 4N working preci-
sion words° (2N working precision words could be saved by transmitting
the columns of A itself in place of fvl and W, Similarly, A(I,2) could
be transmitted to EISPAC in place of W.)
Indicative execution times for this path (run on an IBM 370/195) are
.003, .011, .042, and .16 seconds for sample matrices of order i0, 20, 40,
and 80 respectively.
Variants of this path substitute the explicit or its rational refor-
mulation for the implicit QL shift; see Section 2.2.3.
42
2.1-36
Section 2.1.17
SOME EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A REAL SYMMETRIC TRIDIAGONAL MATRIX
A real symmetric tridiagonal matrix of order N can be presented to
EISPACK as a two-column array (or as two N-component vectors), the sub-
diagonal elements in the last N-I positions of the first column and the
diagonal elements in the second column. The first element in the first
column is arbitrary.
To determine the eigenvalues W in an interval extending from RLB to
RUB, together with their corresponding eigenvectors Z, of a real symmetric
tridiagonal matrix A of order N, the recommended EISPACK path is:
DO i00 1 = I, N
f~1(1) = A(I,2)
IF (I .EQ. i) GO TO i00
fv~(i) = k(I,1)
fv3(1) = A(I,I)**2
i00 CONTINUE
EPSI = 0.0
CALL BISECT (N ,EPSI ,fVl ,fv2 ,fv3,RLB ,RUB ,MM,M,W,ivl ,IERR,fv4 ,fv5)
IF (IEILR .NE. 0) GO TO 99999
CALL TINVIT (NM,N ,fv 2 ,fv2 ,fv3 ,M,W,ivl ,Z ,IERR,fv4 ,fv5 ,fv6 ,fv7 ,fvS)
IF (IERR .NE. 0) GO TO 99999
or, using EISPAC:
CALL EISPAC(NM,N,MATRIX('REAL',A,'SYMMETRIC','TRIDIAGONAL'),
VALUES(W,MM,M,RLB,RUB),VECTOR(Z))
43
2.1-37
The parameter EPSi is used to control the accuracy of the eigenvalue
computation. Setting it to zero or calling EISPAC without supplying it
causes the use of a default value suitable for most matrices. Further
information about the use of EPSI can be found in Section 2.3.3 and in
the BISECT and EISPAC documents. Upon completion of the path, M is set
to the number of eigenvalues determined to lie in the interval defined
by RLB and RUB and, provided M ! ~i, the eigenvalues are in ascending
order in W and their corresponding orthonormal eigenvectors are in the
first M columns of Z. Note that, should the computed M be greater than
MM, BISECT sets IERR non-zero and does not compute any eigenvalues. This
path leaves A unaltered.
Suitable dimensions for the arrays are: A(nm,2), W(mm), Z(nm,~wn),
fvl(nm), fv2(nm), fv3(nm), fv4(n~), fv5(nm), fv6(nm), fvT(nm), fvS(nrn),
and ivi (~)o
The array storage required to execute this path is I0N + M(N+I)
working precision words and M integer words. (2N working precision words
could be saved by transmitting the columns of A itself in place of fvN
and fv2, still preserving A.)
Indicative execution times for this path (run on an IBM 370/195), when
computing all N eigenvalues and eigenvectors, are .017, .059, .22, and
.84 seconds for sample matrices of order I0, 20, 40, and 80 respectively.
Extrapolation of these execution times for cases where M is less than N
is discussed in Section 4.
Variants of this path substitute the rational QR method or the implicit
QL method for the bisection process, allow the specification of boundary
eigenvalue indices instead of an interval to the bisection process, or
44
2.1-38
cosine the determination of the eigenvalues and eigenvectors of the
matrix into a single s~routine; see Sections 2.2.4, 2.2.7, 2.2.8, and
2.2.5.
45
2.1-39
Section 2.1o18
SOME EIGENVALb~S OF A REAL SYMMETRIC TRIDIAGONAL .MATRIX
A real symmetric tridiagonal matrix of order N can be presented to
EISPACK as a two-column array (or as two N-component vectors), the sub-
diagonal elements in the last N-I positions of the first column and the
diagonal elements in the second column~ The first element in the first
column is arbitrary.
To determine the eigenvalues W in an interval extending from RLB to
RUB of a real symmetric tridiagonal matrix A of order N, the recommended
EISPACK path is:
DO i00 1 = i, N
fvl(1) = A(I,2)
IF (I .EQ. I) GO TO I00
fv~(1) = A(~,I)
fv3(I) = A(I,I)**2
i00 CONTINUE
EPSI = 0.0
CALL BISECT(N,EPSI,fvl,fv2,fv3,RLB,RUB,MM,M,W,iVI,IERR,fv4,fv5)
IF (IERR .NE. 0) GO TO 99999
or, using EISPAC:
CALL EISPAC (NM,N,MATRIX( 'REAL v ,A, 'SYMMETRIC' , 'TRIDIAGONAL' ) ,
VALUES (W ,MM,M,RLB ,RUB) )
The parameter EPSI is used to control the accuracy of the eigenvalue
computation. Setting it to zero or calling EISPAC without supplying it
causes the use of a default value suitable for most matrices. Further
46
2.1-40
information about the use of EPSI can be found in Section 2.3.3 and in
the BISECT and EISPAC documents. Upon completion of the path, M is set
to the number of eigenvalues determined to lie in the interval defined
by RLB and RUB and, provided M~MM, the eigenvalues are in ascending
order in W. Note that, should the computed M be greater than MMj BISECT
sets IERRnon-zero and does not compute any eigenvalues. This path
leaves A unaltered.
Suitable dimensions for the arrays are: A(~n,2), W(mm), fv2(nm),
fv2(n~), fv3(n~m), fv4(nm), fv5(r~), and ivl (~).
The array storage required to execute this path is 7N + M working
precision words and M integer words. (2N working preciaion words could
be saved by transmitting the columns of A itself in place of fv2 and fvl,
still preserving A.)
Indicative execution times for this path (run on an IBM 370/195),
when computing all N eigenvalues, are .016, .055, .20, and .76 seconds
for sample matrices of order I0, 20, 40, and 80 respectively. Extrapola-
tion of these execution times for cases where M is less than N is dis-
cussed in Section 4.
Variants of this path substitute the rational QR method for the bi-
section process or allow the specification of boundary eigenvalue indices
instead of an interval to the bisection process; see Sections 2.2.4 and
2.2.8.
47
2.1-41
Section 2.1o19
ALL EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A SPECIAL REAL TRIDIAGONAL MATRIX
A real tridiagona! matrix of order N which, although not symmetric,
has the property that products of pairs of corresponding off-diagonal
elements are all non-negative~ and zero only when both factors are zero,
can be presented to EISPACK as a three-column array. The subdiagonal
elements are stored in the last N-I positions of the first column, the
diagonal elements in the second column, and the superdiagonal elements in
the first N-I positions of the third column. The first element in the
first column and the last element in the third column are arbitrary.
To determine all the eigenvalues W and their corresponding eigen-
vectors Z of such a real tridiagonal matrix A of order N, the recommended
EISPACK path is:
CALL FIGI2(NM,N,A,W,fVi,Z,IERR)
IF (IERR ~NE. 0) GO TO 99999
CALL IMTQLe(NM,N,W,fvI,Z,IERR)
IF (IERR .NE. 0) GO TO 99999
or, using driver subroutine RT:
CALL RT(NM,N,A,W,I,Z,~i,IERR)
IF (IERR .h~. 0) GO TO 99999
or, using EISPAC:
CALL EiSPAC(NM,N,MATRIX('REAL',A,'TRIDIAGONAL'),VALUES(W),VECTOR(Z))
This path returns the eigenvalues in ascending order and a set of (non-
orthonorma!) eigenvectors; it leaves A unaltered. Note that a non-zero
48
2.1-42
value of IERR from FIGI2 is indicative of an input matrix which lacks the
required property.
Suitable dimensions for the arrays are: A(nm,3), W(nm), Z(nm,nm),
and fvl (rim).
The array storage required to execute this path is N 2 + 5N working
precision words.
Indicative execution times for this path (run on an IBM 370/195) are
.006, .027, .15, and .97 seconds for sample matrices of order I0, 20, 40,
and 80 respectively.
A variant of this path substitutes the explicit for the implicit QL
shift; see Section 2.2.3.
49
2.1-43
Section 2.1.20
ALL EIGENVALUES OF A SPECIAL REAL TRiDIAGONAL MATRIX
A real tridiagonal matrix of order N which, although not symmetric,
has the property that products of pairs of corresponding off-diagonal
elements are all non-negative, can be presented to EISPACK as a three-
column array. The subdiagonal elements are stored in the last N-I
positions of the first column, the diagonal elements in the second column,
and the superdiagonal elements in the first N-I positions of the third
column. The first element in the first column and the last element in
the third column are arbitrary.
To determine all the eigenvalues W of such a real tridiagonal matrix
A of order N, the recommended EISPACK path is:
CALL FiGI(NM,N,A,W,fv2,fv2,1ERR)
IF (IERR ~NE. 0) GO TO 99999
CALL IP~QLI (N,W,fv2 ,IERR)
IF (IERR oNE. O) GO TO 99999
or, using driver subroutine RT:
CALL RT(~I,N,A,W,0,DU~Y,fv2,1ERR)
IF (IERR ~NE. 0) GO TO 99999
or, using EISPAC:
CALL El SPAC (NM, N, MATRIX (' REAL ' ,A ,' TRID IAGONAL ' ) ,VALUE S (W))
This path returns the eigenvalues in ascending order; it leaves A
unaltered. Note that a non-zero value of IERR from FiGI is indicative
of an input matrix which lacks the required property.
50
2.1-44
Suitable dimensions for the arrays are: A(rtm,3), W(nm), and fvl(nm).
The array storage required to execute this path is 5N working pre-
cision words.
Indicative execution times for this path (run on an IBM 370/195) are
.003, .012, .044, and .16 seconds for sample matrices of order i0, 20, 40,
and 80 respectively.
Variants of this path substitute the explicit or its rational refor-
mulation for the implicit QL shift; see Section 2.2.3.
51
2.1-45
Section 2.1.21
SOME EIGENVALUES AND CORRESPONDING EIGENVECTORS OF A SPECIAL REAL TRiDIAGONAL MATRIX
A real tridiagonal matrix of order N which, although not symmetric,
has the property that products of pairs of corresponding off-diagonal
elements are all non-negative, and zero only when both factors are zero,
can be presented to EISPACK as a three-column array. The subdiagonal
elements are stored in the last N-I positions of the first column, the
diagonal elements in the second column, and the superdiagonal elements
in the first N-! positions of the third column. The first element in
the first column and the last element in the third column are arbitrary.
To determine the eigenvalues W in an interval extending from RLB to
RUB 9 together with their corresponding eigenvectors Z, of such a real
tridiagonal matrix A of order N, the recommended EISPACK path is:
CALL FIGI(NM,N,A,fvl,fv2,fv3,1ERR)
IF (IERR .NE. 0) GO TO 99999
EPSI = 0.0
CALL BISECT(N,EPSI,ful,f~2,fv3,RLB,RUB,MM,M,W,iVI,IERR,fv4,fv5)
IF (iERR ~NE. O) GO TO 99999
CALL TINVIT(NM,N,fv2,fu2,fv3,M,w,iv2,Z,IERR,fu4,fv5,fv6,fv?,fvS)
IF (IERR .NE. O) GO TO 99999
CALL BAKVEC(hrM,N,A,fv2,M,Z,IERR)
IF (lEER ~NE. 0) GO TO 99999
or, using EISPAC:
CALL EISPAC(NM,N,MATRIX('REAL~,A,'TRIDIAGONALT),
VALUES(W,MM,M,RLB,RUB),VECTOR(Z))
52
2.1-46
The parameter EPSI is used to control the accuracy of the eigenvalue
computation. Setting it to zero or calling EISPAC without supplying it
causes the use of a default value suitable for most matrices. Further
information about the use of EPSI can be found in Section 2.3.3 and in
the BISECT and EISPAC documents. Upon completion of the path, M is set
to the number of eigenvalues determined to lie in the interval defined
by RLB and RUB and, provided M ! ~, the eigenvalues are in ascending
order in W and their corresponding (non-orthonormal) eigenvectors are
in the first M columns of Z. Note that, should the computed M be greater
than MM, BISECT sets IERR non-zero and does not compute any eigenvalues.
This path leaves A unaltered. Note that a non-zero value of IERR from
either FIGI or BAKVEC is indicative of an input matrix which lacks the
required property.
Suitable dimensions for the arrays are: A(nm,3), W(n~n), Z(nm,mm),
fv1(nm), fv2(nm), fv3(n~), fv4(nm), fv5(nm), fv6(nm), fvT(nm), fv8(nm),
and ivl(~).
The array storage required to execute this path is IIN + M(N+I)
working precision words and M integer words.
Indicative execution times for this path (run on an IBM 370/195),
when computing all N eigenvalues and eigenvectors, are .018, .060, .22, and
.84 seconds for sample matrices of order i0, 20, 40, and 80 respectively.
Extrapolation of these execution times for cases where M is less than N
is discussed in Section 4.
Variants of this path substitute the rational QR method or the
implicit QL method for the bisection process, allow the specification of
boundary eigenvalue indices instead of an interval to the bisection
process, or combine the determination of the eigenvalues and eigenvectors
53
2.1-47
of the s~-mmetrized matrix into a single subroutine; see Sections 2.2.4,
2.2.7, 2.2.8, and 2.2.5.
54
2.1-48
Section 2.1.22
SOME EIGENVALUES OF A SPECIAL REAL TRIDIAGONAL MATRIX
A real tridiagonal matrix of order N which, although not symmetric,
has the property that products of pairs of corresponding off-diagonal
elements are all non-negative, can be presented to EISPACK as a three-
column array. The subdiagonal elements are stored in the last N-I
positions of the first column, the diagonal elements in the second
column, and the superdiagonal elements in the first N-I positions of
the third column. The first element in the first column and the last
element in the third column are arbitrary.
To determine the eigenvalues W in an interval extending from RLB
to RUB of such a real tridiagonal matrix A of order N, the recommended
EISPACK path is:
CALL FIGI(NM,N,A,fvl,fv2,fv3,1ERR)
IF (IERR .NE. 0) GO TO 99999
EPSI = 0.0
CALl. BISECT(N,EPSI,fv2,fv2,fv3,RLB,RUB,MM,M,W,ivl,IERR,fv4,fv5)
IF (IERR .NE. 0) GO TO 99999
or, using EISPAC:
CALl EISPAC(NM,N,MATRIX('REAL',A,'TRIDIAGONAL'),VALUES(W,MM,M,RLB,RUB))
The parameter EPSI is used to control the accuracy of the eigenvalue
computation. Setting it to zero or calling EISPAC without supplying it
causes the use of a default value suitable for most matrices. Further
information about the use of EPSI can be found in Section 2.3.3 and in the
BISECT and EISPAC documents. Upon completion of the path, M is set to the
55
2.1-49
number of eigenva!ues determined to lie in the interval defined by RLB
and RUB and, provided M ~MM, the eigenvalues are in ascending order
in W. Note that, should the computed M be greater than ~, BISECT sets
IERRnon-zero and does not compute any eigenvalues. This path leaves A
unaltered. Note that a non-zero value of IERR from FIGI is indicative
of an input matrix which lacks the required property.
Suitable dimensions for the arrays are: A(nm,3), W(~v~), fv2(nm),
fv2(~), fv3(nm), fv4(nm), fv5(nm), and ivl(mm).
The array storage required to execute this path is 8N + M working
precision words and M integer words.
Indicative execution times for this path (run on an IBM 370/195),
when computing all N eigenvalues, are .016, .055, .20, and °76 seconds for
sample matrices of order I0, 20, 40, and 80 respectively. Extrapolation
of these execution times for cases where M is less than N is discussed
in Section 4.
Variants of this path substitute the rational QR method for the bi-
section process or allow the specification of boundary eigenvalue indices
instead of an interval to the bisection process; see Sections 2.2.4 and
2.2.8.
58
2.2-I
Section 2.2
VARIATIONS OF THE RECOMMENDED EISPACK PATHS
This section describes variants of the recommended paths given in
Section 2.1. These variants are obtained by modifying one or more of
the call or ancillary statements in the recommended paths; they provide
some additional or alternate capability. The variant paths are related
to considerations of: whether or not complex and real general matrices
should be balanced; the use of orthogonal similarities in place of
elementary similarities for reducing a real general matrix to upper
Hessenberg form; choosing between the implicit and explicit versions of
the QL algorithm for finding all eigenvalues and eigenvectors, or all
eigenvalues only, of matrices which can be reduced to real symmetric tri-
diagonal form; the use of the rational QR algorithm for finding a few
extreme eigenvalues of matrices which can be reduced to real symmetric
tridiagonal form; the use of the single subroutine TSTURM to find some
eigenvalues and their corresponding eigenvectors of matrices which can be
reduced to real symmetric tridiagonal form; the use of elementary simi-
larities in place of unitary similarities for a complex general matrix;
possible economies realizable with a variant of the implicit QL algorithm
when partial eigensystems are determined; specification of boundary
eigenvalue indices to the bisection process instead of an interval; and
availability of storage economies when algorithms that proceed from packed
representations of real symmetric and complex Hermitian matrices are used.
Each of the subsections describing these variations discusses the
advantages and disadvantages of using the variant instead of the recom-
mended paths and includes an indication of why the routines used in the
recommended paths were chosen. The descriptions of the variant paths
57
2.2-2
differ from those of the recommended paths in Section 2.1 in that the
variants are described in terms of modifications to the recommended
paths; differences in storage requirements are similarly described. In
order to illustrate the modifications, one example of the several variant
paths is also given in each subsection~
58
2.2-3
Section 2.2.1
NON-BALANCING OF COMPLEX AND REAL GENERAL MATRICES
All of the recommended paths in EISPACK for complex general and real
general matrices employ the subroutines CBAL and BALANC, respectively, to
"balance" the matrix before computing its eigensystem ([i], pp. 315-326).
This operation includes two distinct functions: Permutation of the rows
and columns of the matrix to display any isolated eigenvalues, and equili-
bration of the remaining portion of the matrix.
The first part of the operation attempts to permute the rows and
columns of the matrix in such a way as to render portions of the matrix
triangular (column-wise at the top or row-wise at the bottom) so that
some eigenvalues are isolated on the diagonal. Any eigenvalues so iso-
lated are available without further computation and the order of the
remaining eigenproblem is reduced.
The equilibration process is then applied to the part of the matrix
(rows and columns is1 through is2) remaining after any isolated eigen-
values have been displayed. It consists of exact diagonal similarity
transformations chosen to make the sums of the magnitudes of the elements
in corresponding rows and columns more nearly equal. (Note that real
symmetric and complex Hermitian matrices are by nature balanced.) This
process may reduce the norm of the matrix thereby placing tighter bounds
on the rounding errors that can be made by the routines which follow.
The choice of whether to balance or not depends on several factors,
some of which are hard to assess a priori. Clearly balancing costs some
time. However, it is an N 2 process and becomes less significant as N
increases; in no case have we observed it to constitute more than 7% of
the time for an entire path (see Section 4.3). It may also happen that
59
2.2-4
the eigenvalues computed for an already nearly-equilibrated matrix are
slightly more accurate if balancing is omitted; however, balancing can
never increase the error bounds predicted by the backward error analysis.
Moreover, balancing obtains isolated eigenvalues exactly whatever be
their condition numbers, and their isolation reduces the effective order
of the matrix passed to the N 3 algorithms which follow. Beyond this,
the equilibration process can make dramatic improvements in the accuracy
of the computed eigenvalues for certain matrices. It is for these reasons
that balancing is used in the recommended paths.
To use the paths of Sections 2.1.1-2.1.3 and 2.1.8-2.1.10 without
balancing the matrix, the calls to CBAL or BALANC should be replaced by
the two statements
is1 = I
is2 = N
Also, calls to B~BAK or CBABK2, which transform the eigenvectors of the
balanced matrix into eigenvectors of the original matrix, should be re-
moved altogether~ To use the control program EISPAC without balancing,
the keyword parameter METHOD with alphanumeric subparameters vNO~,
'BALANCE' should be inserted into the calls to EISPAC given in these
sections.
For example (of. Section 2.1.1), to determine all of the eigenvalues
(WR,WI) and their corresponding eigenvectors (ZR,ZI) of a complex general
matrix (AR,AI) of order N without balancing, the EISPACK path is:
60
2 . 2 - 5
isl = 1
is2 = N
CALL CORTH(NM,N,isl,is2,AR,AI,fv2,fv3)
CALL COMQR2(NM,N,isl,is2,fv2,fv3,AR,AI,WR,WI,ZR,ZI,IERR)
IF (IERR .NE. 0) GO TO 99999
or, using EISPAC:
CALL EISPAC(NI4,N,MATRIX('COMPLEX',AR,AI),VALUES(WR,WI),
VECTOR(ZR,ZI),METHOD('NO','BALANCE'))
The storage requirements for each of the paths without balancing is
reduced from that of the corresponding path with balancing by N working
precision words (array parameter fv2). The reduction in computation time
from not balancing has never exceeded 7% of the total path time in our
experiments. On the other hand, a substantial increase in total path
time from not balancing could occur in cases where balancing would iso-
late some eigenvalues, since isolation of values reduces the effective
order of the eigensystem to be solved.
61
2.2-6
Section 2.2.2
ORTHOGONAL REDUCTION TRANSFORMATIONS TO REAL HESSENBERG FORM
EISPACK contains two sets of subroutines which transform a real
general matrix to upper Hessenberg form~ accumulate the transformations,
and backtransform the eigenvectors. These sets consist of ELMHES,
ELTRAN, and ELMBAK~ which employ elementary similarity transformations,
and 0RTHES, ORTRAN, and ORTBAK, which employ orthogonal similarity
transformations~
The use of orthogona! similarities to reduce a matrix to upper
Hessenberg form may be valuable in two respects. First, they preserve
the Frobenius norm of the matrix and the condition numbers of the eigen-
values ([i], ppo 339-358), whereas elementary similarities do not. Thus,
elementary similarities may increase the norm of the reduced matrix,
which in turn increases the bounds on the rounding errors that can be
made by the eigenvalue-finding routines HQR and HQR2; in this case, use
of orthogonal similarities will guarantee a tighter bound on the errors.
Matrices for which orthogonal similarities improve the accuracies of the
computed eigenvalues, however, occur rarely in practice.
A second application of the routines which employ orthogonal simi-
larities is their possible use with a modified version of HQR2 to compute
the orthogona! similarity transformation which reduces a real general
matrix to quasi-triangular form; this application is discussed in Section
2.3.6.
The disadvantage of the routines which implement orthogonal similar-
ities is their longer execution time. ORTHES requires more than twice as
much time as ELMHES (on the IBM 370/195), and ORTBAK takes about half
again as long as ELMBAK. ORTRAN requires about one-fourth the time of
62
2.2-7
ORTHES, while the time for ELTRAN, never large, becomes negligible with
increasing order (see Section 4). For this reason, elementary similarities
are used in the recommended paths of Sections 2.1.8-2.1.10. Note, however,
that although the orthogonal subroutines individually take more time, only
a small increase in total path time usually results and occasionally even
a decrease in total path time attributable to a decrease in the execution
time for HQR or HQR2. Experiments using orthogonal similarities have
resulted in increases as much as 20% but some decreases of 5% were also
observed.
To use orthogonal instead of elementary similarities in these paths,
replace the names ELMIIES, ELTRAN, and ELMBAK with ORTHES, ORTRAN, and
ORTBAK, respectively, wherever they appear, substituting the array
parameter fv4 for ivl. To use the control program EISPAC with orthogonal
similarities, the keyword parameter METHOD with alphanumeric subparameter
'ORTHOGONAL' should be inserted into the calls to EISPAC given in these
sections.
For example (cf. Section 2.1.8), to determine all of the eigenvalues
(WR,WI) and their corresponding eigenvectors Z of a real general matrix A
of order N using orthogonal transformations, the EISPACK path is:
CALL BALANC(NM,N,A,isl,is2,fvl)
CALL ORTHES(NM, N,isl,is2,A,fv4)
CALL ORTRAN(NM,N,isl,is2,A,fv4,Z)
CALL HQR2(NM, N,isi,is2,A,WR,WI,Z,IERR)
IF (IERR .NE. 0) GO TO 99999
CALL BALBAK(NM,N,is2,is2,fv2,N,Z)
or, using EISPAC:
63
2.2-8
CALL EISPAC(NM,N,MATRIX('REAL',A),VALUES(WR,WI),VECTOR(Z),
METHOD('ORTHOGONALT))
Suitable dimensions for the arrays are as given in Sections 2.1.8-
2.1.10 with fv4(r~) replacing iv1(r~). The array storage requirements
are thus decreased by N integer words and increased by N working pre-
cision words.
64
2.2-9
Section 2.2.3
THE IMPLICIT AND EXPLICIT QL ALGORITHMS
EISPACK contains two pairs of subroutines plus one unpaired subrou-
tine which can be used to compute all eigenvalues, or all eigenvalues
and eigenvectors, of a matrix which is in real symmetric tridiagonal form.
One pair of programs, TQLI and TQL2, is based on the QL algorithm with
explicit shifts; the other pair, IMTQLI and IMTQL2, is based on essen-
tially the same algorithm, but with implicit shifts. Corresponding
members of these pairs are functionally identical and may be substituted
for one another in a path without changing either the parameter list or
the rest of the path.
The unpaired subroutine is TQLRAT, used in the recommended paths that
determine all eigenvalues only of a complex Hermitian or real symmetric
matrix. TQLRAT is a rational reformulation of TQLI; it is formally equivalent
to TQLI, employing explicit shifts, but requires many fewer arithmetic
operations and, in particular, eliminates the calculation of most of the
square roots.
Although functionally identical, the subroutines based on the implicit
and explicit algorithms do differ, however, in the way rounding errors
affect the computed results. These differences are most pronounced for
matrices whose elements vary in a regular way over several orders of mag-
nitude, and one sometimes wants to compute the small eigenvalues to high
accuracy relative to themselves, rather than relative to the norm of the
matrix. To insure that this high accuracy is achieved, the rows and
columns of such matrices should be permuted (if possible) so that the
matrix (aij) is "graded increasingly," i.e., so that laij I approximately
increases as i and j increase, as in the 7 x 7 tridiagonal matrix:
85
2.2-10
a.~ = !02(i-I), i = 1,2,~..,7 11
= = 10 2i-1, ai~i+ 1 ai+l, i i = 1,2,.o.~6
a.. = 0 otherwise. lj
When a tridiagonal matrix is presented so that it is graded increas-
ingly, the routines based on both the implicit and explicit algorithms
compute the eigenvalues with high accuracy relative to themselves. How-
ever, if the matrix is presented so that it is graded decreasingly, the
routines based on the implicit algorithm may still compute the eigenvalues
with fairly high relative accuracy, whereas the routines based on the ex-
plicit algorithm will almost certainly produce large relative errors in
the smaller eigenvalues. Examples of the performance of the algorithms
on graded matrices are given in ([i], pp. 227-248). The paired subroutines
are nearly equal in speed, since the amount of work for a single iteration
is essentially the same in both; however, for graded matrices the implicit
algorithm may require a few more iterations to obtain its greater accuracy.
Because of their more consistent performance on graded matrices, IMTQLI
and IMTQL2 are recommended for tridiagonal matrices.
What of full complex Hermitian and real symmetric matrices? It is
not clear that the algorithms which reduce such matrices to tridiagonal
form always preserve grading; furthermore, in such matrices they may
introduce errors large enough to prevent either the implicit or explicit
algorithm from finding the smaller eigenvalues with high relative accuracy.
Historically, the explicit algorithm was introduced first and was con-
siderably faster than early versions of the implicit algorithm; hence it
was favored for use in the paths for full matrices. Although further
testing may show that the implicit algorithm has superior reliability,
66
2.2-11
especially for graded full matrices, the advantage is not yet clear
enough to cause replacement of the codes based on the explicit algorithm
in the full-matrix paths.
The calling sequence for TQLI differs from that of TQLRAT only in
transmitting array parameter fvl instead of fv2. This difference
though makes it possible to conserve N working precision words in the
path by not allocating fv2. For example, to find all the eigenvalues W
of a full real symmetric matrix A of order N using TQLI (compare Section
2.1.12), the EISPACK path is:
CALL TREDI(NM,N,A,W,~I,fv2)
CALL TQLI(N,W,fV2,1ERR)
IF (IERR .NE. 0) GO TO 99999
To interchange QL algorithms in the recommended paths of Sections
2.1.4-2.1.5, 2.1.11-12, 2.1.15-16, and 2.1.19-20 (after formal replace-
ment of TQLRAT by TQLI) you need only interchange the names in the call
statements. For instance, to find all the eigenvalues W of a full real
symmetric matrix A of order N using the implicit QL algorithm (compare
with above), the EISPACK path is:
CALL TREDI (NM, N,A,W,fvI ,fvl )
CALL IMTQLI(N,W,fVI,!ERR)
IF (IERR .NE. 0) GO TO 99999
It is not possible to interchange QL algorithms when using the control
program EISPAC. Storage requirements for the implicit paths are identical
and indicative timings closely similar (see Section 4) to those for the
explicit paths.
67
2.2-12
Section 2.2.4
THE RATIONAL QR ALGORITHM FOR FINDING A FEW EXTREME EIGENVALUES
All of the recommended EISPACK paths that determine a subset of the
eigenvalues of a matrix employ subroutine BISECT, which computes those
eigenvalues of a real symmetric tridiagonal matrix which lie in an inter-
val determined by the values of the parameters RLB and RUB. EISPACK
contains an alternate subroutine which can be used, with minor modifica-
tions to these paths, in place of BISECT. This subroutine, called RATQR,
computes a specified number of the smallest or largest eigenvalues. Be-
cause of this difference in the method of specifying the selected eigen-
values, BISECT and RATQR are not directly interchangeable. (See Section
2.2.8 for a discussion of another alternate subroutine to BISECT whose
capability includes that of RATQR with better stability and which is
directly interchangeable with BISECT.)
Although RATQRmight appear to be easier to use than BISECT when
some of the extreme eigenvalues are desired, the accumulation of rounding
errors with the determination of each successive eigenvalue may render
the later eigenvalues insufficiently accurate for some applications.
For instance, this accumulation of error can be particularly troublesome
if corresponding eigenvectors are to be computed by subroutine TINVIT,
for even when maximum accuracy is requested from RATQR (by setting
EPSI = 0.0, see Section 2.3.3), an eigenvalue may not be accurate enough
to satisfy TINVIT~s rather strict convergence test for the corresponding
eigenvector iteration~ This problem is especially likely to occur if too
many eigenvalues are requested from RATQR, or if some of the requested
values are tightly clustered.
68
2.2-13
To use RATQR to compute the M smallest (say) eigenvalues of a matrix
which has been reduced to symmetric tridiagonal form, calls to BISECT of
the form:
CALL BISECT(N,EPSI,fv2,fvZ,fv3,RLB,RUB,I~4,M,W,ivl,!ERR,fv4,fv5)
in the recommended paths in EISPACK should be replaced by:
TYPE = .TRUE.
IDEF = 0
CALL RATQR(N, EPS 1 ,fvl ,fu2,fu 3,M,W, ivl ,fv4, TYPE, IDEF, IERR)
Here TYPE is a LOGICAL variable which specifies whether the M smallest or
M largest eigenvalues are desired, according as it is .TRUE. or .FALSE.
IDEF can be used to specify that the matrix is known to be positive or
negative definite, according as it is +i or -I; a value of 0 is used to
indicate either that the definiteness of the matrix is not known, or that
it is not definite. Specifying the matrix to be definite will save some
computation time when IDEF is +i and TYPE is .TRUE. or when IDEF is -i
and TYPE is .FALSE.; however, if later the matrix turns out not to be
definite as specified, RATQR will terminate with IERR non-zero and with-
out computing any eigenvalues. Upon successful return from RATQR, the
computed eigenvalues are to be found in W in increasing order if TYPE is
.TRUE. and in decreasing order if TYPE is .FALSE.
To request the control program EISPAC to employ RATQR in place of
BISECT, modify the illustrated calls for the recommended paths by adding
the keyword parameter METHOD with alphanumeric subparameter 'RATQR' and
by changing the subparameters to the VALUES keyword to W, M, and 'SMALLEST ~
or 'LARGEST' as desired. To specify the definiteness of the input matrix,
69
2.2-14
insert the alphanumeric subparameter 'POSITIVE DEFINITE' or 'NEGATIVE
DEFINITE ~ in the IIATRIX keyword anywhere after A (or AI).
For exmmple, to determine the M smallest eigenvalues W of a full
real symmetric positive definite matrix A of order N, the path of Section
2.1.14 becomes:
CALL TREDI (m~,N ,A,fvl ,fv2 ,fv3)
EPSI = 0.0
TYPE = .TRUE.
IDEF = i
CALL RATQR(N,EPSI,fvl,fv2,fv3,M,W,iv2,fv4,TYPE,IDEF,IERR)
IF (IERR .NE. 0) GO TO 99999
or, using EISPAC:
CALL EISPAC(NM,N,MATRIX(~REAL',A,'SYMMETRIC','POSITIVE DEFINITE'),
VALUES(W,M,'SMALLEST'),METNOD('RATQR'))
Suitable dimensions for the arrays are: A(~m,nm), W(nm), fv1(nm),
fv2(~), fv3(r~n), fv4(~), and ivl(nm). Note that storage for W and iv1
must be of length nm, even though only M eigenvalues are requested,
The array- storage required to execute this path is N 2 + 5N working
precision words and N integer words. The arrays fvl and fv3 may be
identified with W and fv4 respectively, thereby reducing the working
precision storage required to N 2 + 3N words.
70
2.2-15
Section 2.2.5
THE USE OF TSTURMAS AN ALTERNATE TO BISECT-TINVlT
Those recommended paths of Section 2.1 which at some stage compute
some eigenvalues and eigenvectors of symmetric tridiagonal matrices all
call subroutine BISECT followed by subroutine TINVIT. Alternatively,
calls to these two subroutines can be replaced by a single call of sub-
routine TSTURMwhich combines their two separate functions. TSTURM is
the translation of the corresponding Handbook algorithm ([I], pp. 418-439);
TINVIT was additionally written to extend the capability of eigenvector
determination by inverse iteration to matrices whose eigenvalues have been
computed by subroutines other than BISECT. Thus paths including RATQR
(see Section 2.2.4), I~QLV (see Section 2.2.7), and TRIDIB (see Section
2.2.8) were made available.
Substitution of TSTURM for BISECT and TINVIT in the paths has only a
negligible effect on execution time. Three possible differences in the
computed results may occur, however: The ordering of the eigenvalues (and
eigenvectors) may differ, there may be tiny differences in the eigenvector
components, and the action taken upon the occurrence of an eigenvector
convergence failure is different. The difference in ordering can occur
only if the symmetric tridiagonal matrix breaks into submatrices; TSTURM
orders the eigenvalues locally within submatrices, while BISECT orders the
eigenvalues globally for the entire matrix. Differences in the eigenvec-
tors can result only from the different order in which the eigenvectors
associated with close eigenvalues are orthogonalized in TSTURM and TINVIT;
for such differences to exist there would have to be at least three close
eigenvalues within the same submatrix. Finally, TSTURM returns immediately
upon failure of an eigenvector to converge; in contrast, TINVIT sets the
71
2.2-16
vector to zero and continues. On balance, it thus appears that there is
really no reason to choose TSTUIhM over BISECT-TINVIT, except that only
one subroutine call has to be written instead of two.
To use TSTURM to determine the eigenvalues W in an interval extend-
ing from RLB to RUB, together with their corresponding eigenvectors Z, of
any matrix of order N which can be reduced to a symmetric tridiagonal
matrix, the section of coding of the form:
CALL BISECT(N,EPSI,fvl,fv2,fv3,RLB,RUB,MM,M,W,ivl,IERR,fv4,fv5)
IF (IERR oNE. 0) GO TO 99999
CALL TINVIT (NM,N,fvl ,fv2 ,fv3,M,W,ivl ,Z,IERR,fv4 ,fv5,fv6 ,fvf ,fvS)
IF (IERR .NE. 0) GO TO 99999
in the recommended paths in EISPACK should be replaced by:
CALL TSTURM(NM,N,EPSI,fv2 ,fv2,fv3,RLB,RUB,MM,M,W,Z,iERR,
fv4,fvS ,fv6 ,fv7 ,fv8 ,fv9)
IF (iERR .NE. 0) GO TO 99999
Thus, for example, the recommended path of Section 2.1.13 for some
eigenvalues and eigenvectors of a real symmetric matrix A of order N using
TSTURMbecomes:
CALL TREDI (NM,N,A,fvl ,fv2,fv3)
EPSI = 0.0
CALL TSTURM(NM,N ,EPSI ,fvl ,fv2 ,fv3,RLB ,RUB ,MM,M,W,Z ,IERR,
fv4 ,fvS ,fv6 ,fv7 ,fvS ,fv9 )
IF (IERR ~NE. 0) GO TO 99999
CALL TRBAKI (NM,N ,A,fv2 ,M,Z)
72
2.2-17
The control program EISPAC does not utilize TSTURM.
The error parameter IERR from TSTURM combines the separate roles
of the error parameters from BISECT and TINVIT. Note that one addi-
tional working precision array fvg, dimensioned fvg(~), is required but
that the integer array ivl is not required, thus increasing the minimum
storage requirements by N working precision words while releasing M
integer words.
73
2 .2 -18
Section 2.2.6
ELEMENTARY SIMILARITY TRANSFORMATIONS FOR COMPLEX GENERAL MATRICES
EiSPACK contains two sets of subroutines which transform a complex
general matrix to upper Hessenberg form, determine all its eigenvalues
and eigenvectors or all eigenvalues only and, in the case where only
selected eigenvectors of the Hessenberg matrix have been determined,
backtransform these eigenvectors. One set consists of CORTH, COMQR,
COMQR2, and CORTB, which employ unitary similarity transformations,
and the other set consists of COMHES, COMLR, COMLR2, and COMBAK, which
employ stabilized elementary similarity transformations. In particular,
COMQR and COMQR2 implement the QR algorithm, while COMLR and COIo~R2
implement the LR algorithm.
Elementary transformations are faster than unitary transformations
(see Section 4), but their use can increase the norm of the matrix
which in turn increases the bounds on the rounding errors that can be
made in the determination of the eigenvalues and eigenvectors. This
increase of norm and rounding errors has been occasionally observed in
the LR iterative step; the tendency in these instances has been for the
more pronounced growth to occur away from the subdiagonal and diagonal
of the (Hessenberg) matrix, causing little o~ no deterioration in the
eigenvalues but sometimes substantial loss of accuracy in the eigen-
vectors. (The IERR parameter gives no warning unless an eigenva!ue
fails to converge.)
Since loss of accuracy, when it occurs, is associated with increase
of norm, subroutine CO}~R2 arranges to compute and return the norm of
the final reduced (triangular) matrix for inspection by the user. If
the norm has grown by several orders of magnitude, the user should be
wary of possible significant loss of accuracy.
74
2.2-19
To use elementary instead of unitary similarities in these paths,
replace the names CORTH, COMQR, COMQR2, and CORTB with COMHES, COMLR,
COMLR2, and COMBAK, respectively, wherever they appear, substituting the
array parameter iv2 for the pair fv2, fv3. To use the control program
EISPAC with elementary similarities, the keyword parameter METHOD with
alphanumeric subparameter 'ELEMENTARY' should be inserted into the calls
to EISPAC given in these sections.
For example (cf. Section 2.1.1), to determine all the eigenvalues
(WR,WI) and their corresponding eigenvectors (ZR,ZI) of a complex general
matrix (AR,AI) of order N using elementary transformations, the EISPACK
path is:
CALL CBAL(NM,N,AR,AI,isl,is2,fvl)
CALL COMHES(N~.i,N,isT,is2,AR,AI,iv2)
CALL COMLR2(NM,N,isl,is2,ivl,AR.AI,WR,WI,ZR,ZI,IERR)
IF (IERR .NE. O) GO TO 99999
CALL CBABK2(NM,N,is2,is2,fV2,N,ZR,ZI)
or, using EISPAC:
CALL EISPAC(NM,N,MATRIX('COMPLEX',AR,AI),VALUES(~,WI),
VECTOR(ZR,ZI),METHOD('ELEMENTARY'))
Suitable dimensions for the arrays are as given in Sections 2.1.1 -
2.1.3 with iv1(nm) replacing fv2(~),fv3(~). The array storage require-
ments are thus decreased by 2N working precision words and increased by
N integer words.
75
2.2-20
Section 2.2.7
IMTQLV-TINVIT PAIRING IN PATHS FOR PARTIAL EIGENSYSTEMS
Each of the recommended paths of Section 2.1 that determine some
eigenvalues and corresponding eigenvectors of a matrix that has been
reduced to real symmetric tridiagonal form include a pairing of subrou-
tines BISECT and TINVIT, BISECT to determine the eigenvalues and TINVIT
to determine the corresponding eigenvectors. But with the awareness
that the several subroutines in EISPACK based on the QL algorithm can
compute all the eigenvalues in about the time required for BISECT to
compute 25% of them, it would seem that users could improve efficiency
in certain problem situations by computing all the eigenvalues with a
faster subroutine and then specifying a subset of eigenvalues for which
the corresponding eigenvectors would then be determined with TINVIT.
This faster subroutine, however, must additionally be able to
detect and communicate possible blocking of the tridiagonal form, as
does BISECT, to enable TINVIT to determine independent and orthogonal
eigenvectors corresponding to possibly multiple eigenvalues.
It turns out that the implicit QL algorithm as implemented in sub-
routine IMTQLI was readily extendible to detect the blocking, and thus
was born subroutine IMTQLV for inclusion in paths that determine the
partial eigensystem of a matrix that has been reduced to real symmetric
tridiagonal form.
For example (cf. Section 2.1.13), to determine the three smallest
eigenvalues W, together with their corresponding eigenvectors Z, of a
full real symmetric matrix A of order N, one possible EISPACK path is:
76
2.2-21
CALL TREDI (NM,N,A,fvl,fv2,fv3)
CALL LMTQLV(N,fvl,fv2,fv3,W,ivl,IERR,fv4)
IF (IERR .NE. 0) GO TO 99999
CALL TINVIT(NM, N,fvl,fv2,fv3,3,W,ivl,Z,IERR,fv4,fv5,fv6,fvF,fv8)
IF (IERR .NE. 0) GO TO 99999
CALL TRBAKI(NM,N,A,fu2,3,Z)
The control program EISPAC does not utilize IMTQLV.
The parameter list to IMTQLV is a subset of the corresponding
parameter list to BISECT and, similarly to BISECT and in contrast to
IMTQLI, the input tridiagonal matrix is preserved. The array storage
required to execute this variant path is the same as that for the path
of Section 2.1.13.
77
2 .2 -22
Section 2.2.8
SPECIFICATION OF BOUNDARY EIGENVALUE INDICES TO THE BISECTION PROCESS
All of the recommended paths of Section 2.1 that determine a subset
of the eigenvalues of a matrix require the specification of an interval
(RLB,RUB) containing the eigenvalues of interest to subroutine BISECT.
It may sometimes be preferred to specify the eigenvaiues by their
indices in the ordered set; e.g., the three smallest eigenvalues or the
second largest eigenvalue. Substitution of subroutine TRIDIB for BISECT
enables this option~ In particular, TRIDiB includes the capability for
which subroutine RATQR was designed (cf. Section 2.2.4); although slower,
TRIDIB is numerically stable and is therefore recommended generally in
preference to RATQR.
The parameter list for TRID!B is the same as that for BISECT with
the exception of RLB, RUB, MM, and M. RLB, RUB, and M are still present
with reversed roles -- M now specifies the number of eigenvalues desired
and RLB and RUB are output parameters which define an interval containing
exactly the desired eigenvalues. MM is replaced by MII which specifies
the index of the smallest desired eigenvalue.
To request the control program EISPAC to employ TRIDIB in place of
BISECT, change the subparameters to the VALUES keyword from (W,MM,M, RLB,
RUB) to (W,MII,M).
So, for example (cf. Section 2.1.14), to determine exactly M eigen-
values W, starting from the Mll-th smallest one, of a full real symmetric
matrix A of order N, the EISPACK path is:
78
2.2-23
CALL TREDI (NM, N,A,fv2,fv2,fv3)
EPSI = 0.0
CALL TRIDIB(N,EPSI,fv2,fv2,fv3,RLB,RUB,MII,M,W,ivI,IERR,fv4,fv5)
IF (IERR .NE. 0) GO TO 99999
or, using EISPAC:
CALL EISPAC(NM,N,MATRIX('REAL',A,'SYMMETRIC'),VALUES(W,MII,M))
Array storage requirements for paths with TRIDIB are identical to
those for the corresponding paths with BISECT; execution times are very
little different (see Section 4).
79
2.2-24
Section 2.2~9
PACKED REPRESENTATIONS OF REAL SYMMETRIC AND COMPLEX HERMITIAN MATRICES
The algorithms implemented in EISPACK for real symmetric and complex
Hermitian matrices access only the full lower triangles of the matrices;
in order to best take advantage of the storage savings realizable since
the upper triangles are not required, subroutines are included in EISPACK
that proceed from packed representations of the input matrices.
In the real symmetric case, the lower triangle of the matrix is
packed row-wise into a one-dimensional array; subroutines TRED3 and TRBAK3
replace TREDI and TRBAKI, respectively, in the corresponding explicit
paths, driver subroutine RSP replaces RS where applicable, or 'PACKED'
is specified to EISPAC. For example (cf. Section 2.1.13), to determine
some eigenvalues W and corresponding eigenvectors Z of a real symmetric
matrix A of order N in packed representation, the EISPACK path is:
CALL TRED3 (N, NV,A,fvl ,fv2 ,fv3)
EPSI = 0.0
CALL BISECT(N,EPSI,fvl ,fv2,fu3,RLB,RUB,MM,M,W,iV2 ,IERR,fu4,fv5)
IF (IERR oNE. 0) GO TO 99999
CALL TINVIT(NM,N,fvl,fv2,fv3,M,W,ivl,Z,IERR,fv4,fv5,fv6,fv7,fvS)
IF (IERR .NE. O) GO TO 99999
CALL TRBAK3 (NM, N, NV,A,M, Z)
or, using EISPAC:
CALL EISPAC (NM,N,MATRiX(~ REAL ' ,A, 'SYMMETRIC', 'PACKED' ),
VALUES (W,MM,M,RLB, RUB), VECTOR(Z) )
NV communicates the dimension of A and therefore must be at least
N (N+I)/2.
80
2.2-25
The array storage required to execute this path is N2/2 + 17N/2 +
M(N+I) working precision words and M integer words. Driver subroutine
RSP can be used with real symmetric matrices in packed representation
in the corresponding paths to where RS is used with matrices in standard
representation. Its calling sequence is identical to that of RS except
for the inclusion of NV in the position after N. But for the case where
all eigenvalues and eigenvectors are determined, RS is preferred because
it affords optimal consolidation of storage when the eigenvectors over-
write the input matrix and, further, implements a more efficient algorithm
than does RSP.
In the complex Hermitian case, the lower triangle of the matrix is
packed into a single two-dimensional array, the real parts of the elements
in the full lower triangle and the imaginary parts of the elements in the
transposed positions of the strict upper triangle. Subroutines HTRID3
and HTRIB3 replace HTRIDI and HTRIBK, respectively, in the corresponding
paths or 'PACKED' is specified to EISPAC. For example (cf. Section 2.1.4),
to determine all eigenvalues and corresponding eigenvectors of a complex
Hermitian matrix in packed representation, the EISPACK path is:
CALL HTRID3 (NM,N,A,W, fv2 ,fvl ,fml )
DO i00 I = i, N
DO 50 J = I, N
ZR(I,J) = 0.0
50 CONTINUE
ZR(I,I) = 1.0
I00 CONTINUE
CALL TQL2(NM,N,W,fVI,ZR, IERR)
IF (IERR .NE. 0) GO TO 99999
CALL HTRIB3(NM,N,A,fml,N,ZR,ZI)
81
2 .2-26
or, using EISPAC:
CALL EISPAC(NM,N,MATRIX('COMPLEX',A,A,'HERMITIAN','PACKED~),
VALUES(W)~VECTOR(ZR,ZI))
The array storage required to execute this path is 3N 2 + 4N working
precision words.
There is no driver subroutine in EISPACK for use with packed
complex Hermitian matrices. Execution times for the packed real
symmetric and complex Hermitian subroutines are not markedly different
from those of their standard counterparts; see Section 4.
82
2.3-1
Section 2.3
ADDITIONAL INFORMATION AND EXAMPLES
This section contains additional information about and examples of
the use of EISPACK and the control program which are either too detailed
to be included in the discussion of a particular path, or which apply to
more than one path. The specific topics covered include the setting of
the LOGICAL vector SELECT used in the paths for computing selected
eigenvectors of real and complex general matrices; the packing of the
eigenvectors of real general matrices; considerations regarding the user-
supplied error tolerance in the computation of the eigenvalues of matrices
which can be reduced to real symmetric tridiagonal form; the relative
efficiencies of computing partial and complete eigensystems; two special
computations: a determination of the number of positive (or negative)
eigenvalues of matrices which can be reduced to real symmetric tridiagonal
form; and the orthogonal similarity reduction of a real matrix to quasi-
triangular form; the examination of the IERR parameter and intermediate
results when using the control program EiSPAC; and a summary of the possi-
ble values of IERR and their meanings. The section concludes with two
complete example driver programs illustrating the use of EISPACK and the
control program EISPAC.
83
2.3-2
Section 2.3.1
SELECTING THE EIGENVECTORS OF REAL AND COMPLEX GENERAL MATRICES
The computation of selected eigenvectors of real and complex general
matrices by the subroutines INVIT and CINVIT is controlled by the LOGICAL
array parameter SELECT and to some extent by the parameter MM. The con-
siderations involved in setting SELECT and determining ~ (MM = ~), the
column dimension of the eigenvector arrays, are discussed separately for
real and complex matrices.
For complex matrices, the elements of SELECT are in one-to-one cor-
respondence with the computed eigenvalues. They are examined in order
and the eigenvectors corresponding to the eigenvalues tagged by .TRUE.
elements in SELECT are computed. These complex eigenvectors are stored
in successive columns of the eigenvector arrays ZR and ZI; hence the number
of .TRUE. elements in SELECT must not exceed the column dimension rf~ of
the arrays ZR and ZI. The parameter MM communicates this column dimension;
should more than MM columns be required, the computation stops when the
arrays are full and IERR is set non-zeros In any event, when the eigen-
vector subroutine (CINVIT) returns to the calling program, M is set to the
number of columns actually used to store the eigenvectors.
For real matrices, setting SELECT and determining a suitable value for
ff~a priori are complicated by the convention used to pack the eigenvectors
into Z, discussed in detail in Section 2.3.2. It is assumed that conjugate
pairs of complex eigenvalues are consecutive in WR and WI. Again, the ele-
ments of SELECT are in one-to-one correspondence with the computed eigen-
values but the number of columns used in the eigenvector matrix Z may be
more than the number of .TRUE. elements of SELECT.
84
2.3-3
The elements of SELECT are examined in order and the eigenvectors
corresponding to the eigenvalues flagged by .TRUE. elements are computed,
except as restricted below. If a flagged eigenvalue is real, the corres-
ponding real eigenvector is stored in one column of Z. If the flagged
eigenvalue is complex, and its flagged conjugate does not precede it, the
real and imaginary parts of the corresponding eigenvector are stored in
two consecutive columns of Z with the real part first. If the flagged
eigenvalue is complex and its flagged conjugate precedes it, no eigenvector
is computed and the corresponding element of SELECT is reset .FALSE. This
convention guarantees that no more than N columns of Z are required to store
the eigenvectors; it is not a serious restriction since the eigenvector
corresponding to the conjugate value is the conjugate of the computed
eigenvectoro
Because of the complicated algorithm for selecting eigenvectors and
packing them into Z, the a priori determination of the column dimension
~rl of Z is difficult. If the number of .TRUE. elements in SELECT is
known, then a safe choice for ~ is the smaller of twice this number and
N. Again MM must be set to ~ and communicates the column dimension of
Z; should more than MM columns be required, the computation in INVlT stops
when no more eigenvectors can be stored and IERR is set non-zero. In any
event, when INVIT returns to the calling program, M is set to the number
of columns of Z actually used to store the eigenvectors. Note that when
MM is too small, the returned value of M can be either MM-I or MM.
The chief complication towards setting the elements of SELECT to
compute the required eigenvectors is that the eigenvalues of a real or
complex general matrix are not generally computed in a predictable order.
Hence one cannQt decide a priori which elements of SELECT should be set.
85
2.3-4
Two possibilities exist: One is to execute the eigenvalues-only path,
examine the computed eigenvalues, set SELECT as required and then (with
a further run) execute the path for all eigenvalues and some eigenvectors.
The other is to interrupt the all-eigenvalues-some-eigenvectors path after
the computation of the eigenvalues, to set SELECT at that point using a
program segment, and to resume execution of the path.
As an example of this latter possibility, suppose that for a real
general matrix you wish to compute the eigenvectors corresponding to those
eigenvalues the sum of whose real and imaginary parts is non-negative and
you know that there are no more than five such values. Then the path with
interruption becomes:
CALL BALANC(NM,N,A,isl,is2,fvl)
CALL ELMHES(NM,N,isl,is2,A,ivl)
DO 200 I = i, N
DO I00 J = I, N
ym1(I,J) = A(I,J)
i00 CONTINUE
200 CONTINUE
CALL HQR(N~,N,isi,is2,f~2,WR,WI,IERR)
IF (IERR .NEo 0) GO TO 99999
DO 300 I = I, N
SELECT(1) = (WR(1)+WI(I)) .GE. 0.0
300 CONTINUE
CALL INVIT(NM, N,A,WR,WI,SELECT,MM,M,Z,IERR,fml,fv2,fv3)
IF (IERR .NE. 0) GO TO 99999
CALL ELMBAK(NM, isl,is2,A,iv2,M,Z)
CALL BALBAK(NM,N,isi,is2,fvI,M,Z)
86
2.3-5
An example illustrating the corresponding interruption of the path
when using EISPAC is given in Section 2.3.7; the unpacking of the eigen-
vectors in Z is discussed in Section 2.3.2. Note that in the above
example no attempt is made to avoid flagging both eigenvalues of a complex
conjugate pair; as discussed above, INVIT will automatically reset the
flag corresponding to the second eigenvalue in the pair. Unless it is
known that some of the five possible eigenvalues are real, Z should be
dimensioned Z(~,I0) and MM set to i0.
87
2.3-6
Section 2.3.2
UNPACKING THE EIGENVECTORS OF A REAL GENERAL MATRIX
Since for a real general matrix the complex eigenvalues and their
corresponding eigenvectors occur as conjugate pairs and therefore both
members of such a pair are determined once the real and imaginary parts
of one member are known, only N 2 real numbers are required to recover
all the eigenVectors of such a matrix. The EISPACK routines which com-
pute the eigenvectors of real general matrices take advantage of this
fact (and so save storage) by packing both real and complex eigenvectors
into one N by N matrix.
In order to determine whether a given column of the matrix of eigen-
vectors represents a real eigenvector, the real part of a complex eigen-
vector, or the imaginary part of a complex eigenvector, the imaginary
part of the corresponding eigenvalue must be examined. In addition, the
flags in the SELECT array must also be taken into account if only some
eigenvectors have been computed. Perhaps the clearest way to describe
how this packing is done is to present program segments which unpack the
matrix of eigenvectors into two separate matrices representing the real
and imaginary parts of the eigenvectors.
First, suppose that you have computed all the eigenvalues and eigen-
vectors of a real general matrix according to Section 2.1.8. The following
program segment unpacks the matrix Z of eigenvectors into matrices ZR and
ZI, dimensioned ZR(~,nm) and ZI(r~,nm). Note that this program segment
utilizes the property of the EISPACK programs that for real general
matrices the eigenvalues of each complex conjugate pair are ordered so
that the eigenvalue of positive imaginary part appears first in (WR,WI).
88
2.3-7
DO 150 K = i, N
IF (WI(K) .NE. 0.0) GO TO ii0
DO I00 J = i, N
ZR(J,K) = Z(J,K)
ZI(J,K) = 0.0
i00 CONTINUE
GO TO 150
ii0 IF (WI(K) .LT. 0.0) GO TO 130
DO 120 J = i, N
ZR(J,K) = Z(J,K)
ZI(J,K) = Z(J,K+I)
120 CONTINUE
GO TO 150
130 DO 140 J = I, N
ZR(J,K) = ZR(J,K-I)
ZI(J,K) = -ZI(J,K-I)
140 CONTINUE
150 CONTINUE
Note that this program segment has been designed so that Z and ZR can be
the same matrix; if they are, then the fourth and tenth statements can
be omitted.
When only some of the eigenvectors have been computed, the packed
form of storage is somewhat more complicated than when all the eigenvectors
have been computed because of its interaction with the SELECT array (see
Section 2.3.1). The following program segment illustrates one way to
unpack the eigenvectors from the M columns of Z. It places each selected
eigenvector into the columns of full square matrices ZR and ZI whose index
89
2.3-8
is that of the corresponding eigenvalue; the remaining columns are not
set.
I= i
DO 130 K = I, N
IF (.NOT. SELECT(K)) GO TO 130
IF (WI(K) oNE. 0.0) GO TO II0
DO i00 J = !, N
ZR(J,K) = Z(J,I)
ZI(J,K) = 0.0
i00 CONTINUE
I=I+l
GO TO 130
ii0 DO 120 J = I, N
ZR(J,K) = Z(J,I)
ZI(J,K) = Z(J,I+i)
120 CONTINUE
I=I+2
130 CONTINUE
Note that if both members of a pair of complex eigenvalues were flagged
by .TRUE. elements in SELECT, subroutine INVIT resets the flag corres-
ponding to the second member of the pair to .FALSE. (see Section 2.3.1);
thus additional program must be supplied to store the eigenvector corres
ponding to the second member.
90
2.3-9
Section 2.3.3
THE EPSI PARAMETER
As discussed in Section i, the various versions of the subroutines
in EISPACK are designed to provide the best accuracy possible given the
working precisions of the particular machines for which they are avail-
able. For most of the subroutines, accuracy is controlled by an internal
variable, MACHEP ("machine epsilon"), whose value reflects the precision
of the machine arithmetic and should not be altered. However, user con-
trol of accuracy is possible with four of the subroutines in EISPACK
which are used in those paths that compute some eigenvalues (with or
without eigenvectors) of matrices which can be reduced to real symmetric
tridiagonal form. This accuracy control is provided by the parameter
EPSI, which principally affects the precision of the eigenvalues, and thus
the eigenvectors as well, but which also has some effect on computation
time. Some of the considerations helpful in choosing EPSI are discussed
briefly below; further information can be found in the respective documents
for the subroutines and in the Handbook ([i], pp. 249-256). Note in the
discussion below that any property described for subroutine BISECT also
applies to subroutine TRIDIB.
In subroutine BISECT, the computation of an eigenvalue is considered
to have converged when the refined interval [XU,X0] known to contain the
eigenvalue satisfies the condition:
xo - x~ ! 2 × ~mCHEe × (ix01 + Ix~I) + EPSl
This condition has the character of a relative accuracy test for eigen-
values whose magnitudes are large with respect to EPSI/>~CHEP, and that of
91
2.3-10
an absolute accuracy test for eigenvalues of small magnitude. EPSI is
thus an absolute error tolerance.
When the input value of EPSI is zero (or negative) as in the
recommended paths, BISECT automatically resets it to an appropriate de-
fault value for each submatrix; this default value is MACHEP times the
larger (in magnitude) Gerschgorin bound for the eigenvalues of that sub-
matrix. This value prevents the above termination criterion from
requiring ~'unreasonably" high accuracy in the eigenvalues which are near
zero. (In the implementation of BISECT, EPSI is actually set negative
when the default value is requested. This serves as a flag to cause the
recomputation of the default value for each submatrix; the returned value
of EPSI is this negative default value for the final submatrix.)
A positive input value for EPSI will not be reset in BISECT. When
the positive input value of EPSI exceeds the default value, the convergence
test is less stringent for eigenvalues of smaller magnitude, and computa-
tion time tends to be reduced. If EPSI is smaller than its default value,
the convergence test becomes more stringent and computation time tends to
increase. Care should be taken, however, not to specify a smaller value
for EPSI unless the small eigenvalues are known to be insensitive to
perturbations in the input matrix; otherwise the additional precision
will be meaningless. Although computation time tends to increase with
decreasing EPSI, the exact relationship is highly dependent on the particu-
lar matrix.
The eigenvalue calculation in subroutine TSTURM is essentially the
same as in BISECT~ and EPSI has the same role. However, choice of an
input value of EPSI larger than the default value may jeopardize the eigen-
vector calculation~ as discussed below.
92
2.3-11
The role of EPSI in subroutine RATQR is different than in BISECT and
TSTURM. Here the convergence condition is simply
DELTA < EPSI
where DELTA is a byproduct of each iterative step in the computation of
the k th eigenvalue and kxEPSI is an estimate for the absolute error in
the current estimate of the eigenvalue. (The factor k in this bound
accounts for the accumulation of error in successive eigenvalues alluded
to in Section 2.2.4; see also [I], pp. 257-265.)
RATQR also chooses a default value of EPSI. It varies from iteration
to iteration and is MACHEP times the estimate of the smallest eigenvalue
of the current shifted matrix. If a positive value of EPSI is provided
as input, it will be used as long as it is larger than the default value
which represents the maximum relative accuracy reasonably attainable. An
EPSI larger than the default value may result in fewer iterations and
reduced computation time; you should choose it small enough so that you
are willing to tolerate an error of kxEPSI in the k th eigenvalue. (The
value of EPSI actually used for the final eigenvalue computed can be
found in EPSI upon return from RATQR.)
When eigenvectors are computed by the method of inverse iteration,
the success of the computation depends critically on the accuracy of the
computed eigenvalues. Thus, when this method is used in conjunction with
one of the above eigenva!ue finders, as in TSTURM or when TINVIT follows
BISECT or RATQR, use of an EPSI larger than the default value may result
in failure of the eigenvector calculation to converge. Such failure
occasionally occurs even with the default value (especially in RATQR,
when a large number of eigenvalues is requested); for BISECT and TSTURM
93
2.3-12
only, this may be avoided by choosing an input value of EPSI smaller than
its default value.
The role of EPSI may be summarized as follows. All four of the
subroutines discussed employ a convergence criterion which combines a
relative error test using MACHEP and an absolute error test using the
specified EPSI (or a default). In BISECT, TRIDIB, and TSTURM, this combi-
nation is the sum of the two tolerances, while in RATQR it is the maximum.
To use a value of EPSI other than the default, the statement
EPSI = 0.0
in the paths should be replaced by a statement setting EPSI to the desired
value. When using the control program EISPAC, EPSI can be supplied for
the recommended paths only by adding EPSI as the last subparameter to the
VALUES parameter° Thus the VALUES parameter becomes:
~..VALUES(W,MM,M,RLB,RUB,EPSI)~...
With EISPAC, the input value of EPSI is not altered, even though the default
value may be used in the computation.
2.3-13
Section 2.3.4
RELATIVE EFFICIENCIES OF COMPUTING PARTIAL AND COMPLETE EIGENSYSTEMS
In this section, we compare the paths which compute complete eigen-
systems with those which compute partial eigensystems. Considering timing,
array storage, and accuracy requirements, the central issue is when it is
preferable to compute the complete eigensystem even when not required.
There are three cases: Eigenvalue-only paths for matrices that can be
reduced to real symmetric tridiagonal form, eigenvalue-eigenvector paths
for such matrices, and eigenvalue-eigenvector paths for general real or
complexmatrices.
For eigenvalues of matrices reduced to symmetric tridiagonal form,
the principal comparison is between subroutines BISECT and TQLRAT (or
TQLI). When the default value of EPSI is used in BISECT, TQLRAT is
faster to the point of computing all the values as fast as BISECT can
compute 25% of them. If less stringent accuracy requirements allow EPSI
to be specified larger (see Section 2.3.3), then the execution time for
BISECT decreases; at half accuracy, BISECT would be faster than TQLRAT
unless 50% or more of the eigenvalues were desired. Also, BISECT requires
the larger amount of working array storage (cf. Sections 2.1.16 and
2.1.18). Note, however, that the timing and storage d~fferences in these
individual subroutines may be small compared with the total requirements
of the path.
When eigenvectors of such matrices are also desired, then the prin-
cipal comparison is between the subroutine pair BISECT-TINVIT and TQL2.
(See Section 2.2.7 for the comparison between BISECT-TINVIT and variant
IMTQLV-TINVIT.) Here a factor in the timing is the identity of the
machine; the parallelism of the IBM 370/195 appears much better suited to
95
2.3-14
the algorithm of TQL2 than to BISECT-TINVIT. Consultation of the path
times in Section 4 is recommended towards choosing the faster path;
generally, paths with TQL2 are relatively more efficient at lower orders
than paths with BISECT-TINVIT and less efficient at higher orders. Array
storage for a partial set of eigenvectors is clearly less with TINVIT
than for the complete set of vectors with TQL2. However, it must also
be remembered that working array requirements for BISECT-TiNVIT exceed
those for TQL2 (of. Sections 2.1.15 and 2.1.17), and further, that if TQL2
follows TRED2 for a real symmetric matrix, the eigenvectors may overwrite
the input matrix (see Section 2.1.11).
The comparisons of the preceding paragraphs involving TQLRAT (or TQLI)
and TQL2 extend to IMTQLI and IMTQL2 as well, since their performances
and storage requirements are so closely similar. The execution times of
Section 4 also suggest RATQR as a viable replacement for BISECT in the
BISECT-TINVIT path. However, this is misleading in that the cited TINVIT
times are in paths with BISECT, and the corresponding timings with RATQR
could be significantly longer. This owes to the generally poorer accuracy
of the eigenvalues from RATQR, forcing extra, often futile iterations in
TINVIT.
Finally for general real and complex (Hessenberg) matrices, the prin-
cipal comparisons are between HQR-INVIT and HQR2, and between COMQR-CINVIT
and COMQR2. Here considerations are similar to the symmetric case;
inverse iteration is relatively more efficient with increasing order in
comparison to accumulation of transformations, and array storage compari-
sons depend vitally on the number of selected eigenvectors. Working array
requirements for the partial eigensystem paths are especially severe (cf.
Sections 2.1.1 and 2.1.3; also 2.1.8 and 2.1.10).
96
2.3-15
With regard to considerations of accuracy and reliability, the partial
eigensystem paths fall short of the complete eigensystem paths, but the
differences in performance are generally marginal. The weakest such path
is the variant RATQR-TINVIT for real symmetric matrices generally due to
the inaccuracies of the eigenvalues (see Section 2.2.4). Eigenvectors
from TINVITmay fail in their last few digits of being as precisely ortho-
gonal as from TQL2. Extreme sensitivity to the accuracy of the eigenvalues
ia a shortcoming of these paths, but on the other hand affords an a
posteriori check on the accuracy of the eigenvalues.
Thus, a recommendation with regard to the best path when only a
partial eigensystem is required involves a number of considerations.
Generally, we recorm~end the simpler-structured complete eigensystem paths
unless the penalty in time or storage is severe.
97
2.3-16
Section 2.3.5
DETERMINATION OF THE SIGNS OF THE EIGENVALUES
In the stability analysis of dynamic systems, one is frequently in-
terested in knowing the number of positive (or negative) eigenvalues rather
than the eigenvalues themselves. For real general and complex general
matrices the regular EISPACK paths must be used and the eigenvalues
actually computed; however, for nmtrices that can be reduced to real
symmetric tridiagonal form, time can be saved in realizing this objective
hy judicious choice of the EPSI accuracy-control parameter discussed in
Section 2.3.3.
This computation is available from the recommended paths for comput-
ing some eigenvalues of matrices which can be reduced to real symmetric
tridiagonal form as given in Sections 2.1.7, 2.1.14, 2.1.18, and 2.1.22,
when P~B~ RUB, and EPSI are set appropriately. It makes use of two prop-
erties of subroutine BISECT: (I) The first action in BISECT is to deter-
mine the number of eigenvalues in the interval from RLB to RUB and to set
M to that number, and (2) as soon as BISECT has determined intervals
containing eigenvalues which jointly satisfy the convergence criterion
discussed in Section 2.3.3, it terminates. Since EPSI appears as a term
in the right hand side of this criterion, termination will occur at least
as soon as the lengths of the intervals become less than EPSI. One need
only choose an initial value of EPSI which is as large as the length of
the interval from RLB to RUB, and BISECT will return almost immediately
with M set to the number of eigenvalues in the interval.
For examp!e~ suppose you wish to compute the number of eigenvalues
of a real symmetric matrix A of order N which lie on the non-negative real
axis and that you know that all the eigenvalues of A are less than
98
2.3-17
1.0 x 1035 . Then you might use the following path based on that of
Section 2.1.14.
RLB = 0.0
RUB = 1.0E35
EPSI = 1.0E35
CALL TRED 1 (NM,N ,A ,fvl ,fv2 ,fv3)
CALL BISECT (N, EPS i ,fvl ,fv2 ,fv3 ,RLB ,RUB ,MM,M,W,ivl, IERR,fv4 ,fv5)
Upon completion of the path, the value of M is the number of non-negative
eigenvalues. Note that this number is accurately determined despite the
high "error" tolerance EPSI, since it is obtained from a Sturm sequence
count which does not itself involve any convergence test.
99
2.3-18
Section 2.3.6
ORTHOGONAL SIMILARITY REDUCTION OF A REAL MATRIX TO QUASI-TRIANGULAR FORM
Schur~s Lemma asserts the existence of a unitary similarity trans-
formation which reduces any matrix to triangular form. For real matrices,
it may be of interest to compute the part of this transformation which can
be carried out without resort to complex arithmetic, that is, to compute
the matrix of the orthogonal transformation which reduces a real matrix
to quasi-triangular form. Quasi-triangular form falls short of triangular
form because it retains 2 × 2 blocks on the main diagonal which correspond
to complex conjugate pairs of eigenvalues.
The orthogonal quasi-triangularization of a real matrix can frequently
-I be used in place of the usual decomposition PJP (where J is a Jordan
canonical matrix) and is faster. As an example of its application, con-
sider the following problem in control theory. Suppose an m × n matrix X
is sought which satisfies the equation
AX+XB = C
where A, B and C are real m x m, n × n and m × n matrices respectively.
If the orthogonal (upper) quasi-triangularizations of A T = uLTu T and
B = VRV T are computed, and substituted into the equation, then the simpler
equation for Y
LY + YR = E
results where L and R are respectively lower and upper quasi-triangular
matrices and
X = UYV T and E = uTcv.
100
2.3-19
The columns of Y can now be determined successively by a process of for-
ward substitution, which is only sli~ntly complicated by the presence of
the 2 x 2 blocks on the diagonals of L and R.
The quasi-triangularization is carried out on the unbalanced matrix
A using the routines for orthogonal similarity reduction discussed in
Section 2.2.2 and a modified version of subroutine HQR2. It begins with
the use of ORTHES to reduce the matrix to upper-Hessenberg form followed
by ORTRAN to accumulate the transformations. The modified version of
HQR2, say HQRORT, completes the orthogonal reduction to quasi-triangular
form and accumulates the remaining transformations. It can be obtained
by changing tile statement labeled 60 in HQR2 (see Section 7) to:
60 IF (EN .LT. LOW) GO TO i001
(The statements beginning with that labeled 340 and ending with that im-
mediately preceding the statement labeled i000 may be deleted, if desired.)
The "path" for this computation is then:
isl = 1
is2 = N
CALL ORTHES (NM,N,isl ,is2,A,fvl)
CALL ORTRAN(NM,N,isl ,is2,A,fvl ,Z)
CALL HQRORT(NM,N,isl ,is2,A,WR,WI,Z,IERR)
Upon completion of this path, the eigenvalues are in (WR,WI) and the ortho-
gonal matrix which reduces A to quasi-triangular form is in Z.
2.3-20
Section 2.3.7
ADDITIONAL FACILITIES OF THE EISPAC CONTROL PROGRAM
The EISPAC control program has two facilities which increase its
flexibility and range of application. The first provides the opportunity
to examine the iERR parameter values returned by the EISPACK subroutines;
the second provides the opportunity to examine intermediate results as
the computation proceeds, much as can be done when the EISPACK subroutines
are called explicitly.
The facility to examine the value of IERR is invoked by setting an
integer variable, say IERROR, to zero and supplying it as the subparameter
of the keyword parameter ERROR in the call to EISPAC. For example, the
path of Section 2.1.9 becomes
IERROR = 0
CALL EISPAC(NM,N,MATRIX('REAL',A),VALUES(WR,WI),ERROR(IERROR))
To understand the effect of supplying the ERROR keyword, consider the be-
havior of EiSPAC when it is not supplied. When one of the subroutines
returns a non-zero value of IERR, EISPAC prints a message describing the
error and terminates execution of your program. When ERROR(IEPdlOR) is
supplied, EiSPAC behaves instead as follows: If no execution errors occur,
EISPAC returns to your program after execution of the path, and IERROR is
still equal to zero° If one of the routines returns a positive value of
IERR (a "fatal '~ error), EISPAC terminates the path, prints the error
message (unless suppressed by initializing IERROR to a machine dependent
value as described in Section 7.2), and then returns to your program with
IERROR equal to IERR~ Finally, if one of the routines returns a negative
value of IERR (a ~'non-fatal" error), EISPAC completes execution of the path
102
2.3-21
in order to produce some useful results, prints the error message, and
returns to your program with IERROR equal to IERR. Thus the principal
use of the IERR examination facility is to enable you to retrieve useful
partial results when a non-fatal error occurs; which results are useful
is described in the discussion of the particular path in Section 2.1 or
2.2 and is summarized in Table 3 of Section 2.3.8.
The EISPAC facility to examine intermediate results is provided by
a mode of operation in which EISPAC calls a user-supplied subroutine just
before execution of the path begins, and again after execution of each
subroutine and auxiliary action in it. One important application of
this facility occurs in those paths which compute selected eigenvectors
of real or complex general matrices, where the facility can be used to
examine the computed eigenvalues and to set the elements of the SELECT
array controlling which eigenvectors are computed.
To use this facility you must first create a subroutine to examine
the intermediate results. You are free to choose the name of the subrou-
tine, say USUB, but the parameter list and declaration statements must
correspond to:
SUBROUTINE USUB(ISUBNO,NrM, N,AR,AI,WR,WI,ZR,ZI,MM,M,RLB,RUB,EPSI,
X SELECT,IDEF,TYPE,IERR,LOW, IGH,BND,D,E,E2,IN~,INT,ORT,SCALE,TAU)
REAL*8 AR(NM,NM) ,AI(NM,NM) ,WR(NM) ,WI(NM) ,ZR(NM,NM) ,ZI (NM,NM) ,RLB,RUB,
X EPS i, BND(N) ,D(N) ,E(N) ,E2 (N), ORT (N) ,SCALE(N) ,TAU (2,N)
INTEGER ISUBNO,NM,N,MM,M, IDEF,IERR,LOW, iGH,IND(N),INT(N)
LOGICAL SELECT(NM),TYPE
In order to avoid Fortran errors it is important that the array parameters
be dimensioned as indicated (except that MMmay be used for the last
103
2.3-22
dimension of WR and of ZR and ZI, where appropriate), even though some
arrays might not appear relevant to a particular path.
You inform EISPAC that you wish to use the intermediate result
examination facility by inserting the keyword parameter SUBR with sub-
parameter USUB in the EISPAC call. Note that the statement EXTERNAL USUB
must also appear in your calling program.
When USUB is called by EISPAC, the value of the integer parameter
ISUBNO is set to indicate which EISPACK subroutine call or auxiliary ac-
tion has just been completed. It is zero when USUB is called just before
execution of the path begins. ISUBNO values in the range 100-299 signify
that the preceding action allocated or freed temporary storage, those in
the range 300-499 indicate auxiliary actions (initializing or copying
arrays, for example), and those beyond 500 correspond to calls to the
EISPACK subroutines as indicated in Table 2. Thus the value of ISUBNO
indicates where in the execution of a path USUB has been called, and can
be used to determine what action USUB is to take in examining the inter-
mediate results. Table 2 also indicates which of the parameters passed
to USUB appeared in the just-completed call to the EISPACK subroutine.
As an example of the use of this facility, suppose you wish to
interrupt the path of Section 2.1.10 and use a subroutine SETSEL to examine
the eigenvalues computed for a real general matrix and to set the SELECT
array to compute the eigenvectors corresponding to those eigenvalues with
sum of real and imaginary parts greater than or equal to zero. (This
example corresponds to that in Section 2.3.1.) Your driver program must
contain the statements
104
2.3-23
EXTERNAL SETSEL
CALL EISPAC(NM,N,MATRIX('REAL',A),VALUES(WR,WI),VECTOR(Z,MM,M, SELECT),
SUBR(SETSEL))
To determine how to write SETSEL, consult the definition of the path in
Section 2.1.10 in conjunction with Table 2. The eigenvalues are available
for examination after HQR and the logical array SELECT must be initialized
before INVIT (see Section 2.3.1), so the interruption must be made imme-
diately after the call to HQR. Table 2 indicates that this call in this
path has an associated ISUBNO of 517, and comparison of the HQR and INVIT
calls with those in Section 2.1.10 shows that the eigenvalues are in
(WR,WI) and the logical array is parameter SELECT. Hence the subroutine
might be written as follows:
SUBROUTINE SETSEL(ISUBNO,NM,N,AR,AI,WR,WI,ZR,ZI,MM,M,RLB,RUB,EPSI,
X SELECT,IDEF,TYPE,IERR,LOW, IGH,BND,D,E,E2,1ND,INT,ORT,SCALE~TAU)
REAL*8 AR (NM,NM) ,AI (NM,NM) ,WR(NM) ,WI (h~M), ZR(NM,MM), ZI (NM,MM) ,RLB ,RUB,
X EPS I,BND (N) ,D(N) ,E(N) ,E2 (N) ,ORT(N) ,SCALE(N) ,TAN (2,N)
INTEGER ISUBNO,NM,N,MM,M, IDEF,IERR,LOW,IGH,IND(N)~INT(N)
LOGICAL SELECT(NM),TYPE
IF (ISUBNO .NE. 517) RETURN
DO i0 1 = I, N
SELECT(l) = (WR(1)+WI(1)) .GE. 0.0DO
i0 CONTINUE
RETUPd~
END
105
2.3-24
SETSEL immediately returns after every call from EISPAC except when
ISUBNO is 517 (after HQR); then it examines the computed eigenvalues to
set SELECT. (Considerations regarding the setting of SELECT and choice
of MM are discussed in detail in Section 2.3.1.)
106
ISUBNO Value
532
509
515
539
526
504
501
507
508
502
505
506
503
565
566
564
567
563
2.3-25
TABLE 2
ISUBNO VALUES AND PARAMETER NAMES FOR SUBROUTINE CALLS FROM EISPAC
Subroutine Call*
BAKVEC (NM,N,AR,E,M, ZR,IERR)
BALANC (NM, N,AR,LOW,IGH, SCALE)
BALBAK (NM, N,LOW, IGH,SCALE,M,ZR)
BISECT (N,EPSI,AR(I,2),AR(I,I),E2,RLB,RUB,~I,M,WR, IND,
IERR,-,BND) in real symmetric tridiagonal paths
(2.1.17, 2.1.18)
BISECT (N,EPSI,D,E,E2,RLB,RUB,MM,M,WR, IND,IERR,-,BND)
in other paths
CBABK2 (IfM,N,LOW,IGH, SCALE,M,ZR,ZI)
CBAL (NM,N~AR,AI,LOW,IGH,SCALE)
CINVIT (NM,N,AR,AI,WR,WI,SELECT,MM,M,ZR,ZI,IERR,-,-,-,-)
COMBAK (NM, LOW, IGH,AR,AI,INT,M,ZR,ZI)
COMHES (NM,N,LOW,IGH,AR,AI,INT)
COMLR (NM,N,LOW,IGH,AR,AI,WR,WI,IERR)
in path for all values, no vectors (2.1.2), modified
COMLR (N,N,LOW,IGH,-,-,WR,WI,IERR)
in path for all values, selected vectors (2.1.3),
modified
COMLR2(NM,N,LOW,IGH,INT,AR,AI,WR,WI,ZR,ZI,IERR)
COMQR (NM,N,LOW,IGII,AR,AI,WR,WI,IERR)
in path for all values, no vectors (2.1.2)
COMQR (N,N,LOW,IGH,-,-,WR,WI,IERR)
in path for all values, selected vectors (2.1.3)
COMQR2 (NM,N,LOW,IGH,ORTR,ORTI,AR,AI,WR,WI~ZR,ZI,IERR)
CORTB (NM,LOW, IGH~AR,AI,ORTR,ORTI,M,ZR,ZI)
CORTH'(NM,N,LOW~IGH,AR,AI,ORTR,ORTI)
107
ISUBNO Value
519
510
512
530
531
529
516
517
514
523
553
521
525
560
552
554
2.3-26
TABLE 2 (Contd.)
ISUBNO VALUES AND PARAMETER NAMES FOR SUBROUTINE CALLS FROM EISPAC
Subroutine Call*
ELMBAK (NM,LOW, IGH,AR, INT,M,ZR)
ELMHES (NM,N,LOW,!GH,AR, INT)
ELTRAN (NM,N,LOW,IGH,AR,INT,ZR)
FIGI (NM,N,AR,WR,E,E,IERR)
in path for all values, no vectors (2.1.20)
F!GI (NM,N,AR,D,E,E2~IERR)
in paths for some values (2.1.21, 2.1.22)
FIGI2 (NM,N,AR,WR,E,ZR, IERR)
HQR (NM,N,LOW,IGH,AR,WR,WI,IERR)
in path for all values, no vectors (2.1.9)
HQR (N,N~LOW,IGH,-,WR,WI,IERR)
in path for all values, selected vectors (2.1.10)
HQR2 (NM,N,LOW,IGH,AR,WR,WI,ZR,IERR)
HTRIBK (NM~N,AR,AI,TAU,M,ZR,ZI)
HTRIB3 (NM,N,AR,TAU,M, ZR,ZI)
HTRIDI (NM,N,AR,AI,WR,E,E,TAU)
in path for all values and vectors (2.1.4)
HTRIDI (h~M,N,AR,AI,D,E,E2,TAU)
in paths for some values (2.1.6, 2.1.7)
HTRIDI (NM~N,AR,AI,WR,E,E2,TAU)
in path for all values, no vectors (2.1.5)
HTRID3 (NM, N,AR,WR,E,E,TAU)
in path for all values and vectors (2.1.4), modified
HTRID3 (NM,N,AR,D,E,E2,TAU)
in paths for some values (2.1.6, 2.1.7), modified
108
ISUBNO Value
561
(not used)
524
538
522
537
518
520
511
513
540
527
541
528
543
(not used)
2.3-27
TABLE 2 (Contd.)
ISUBNO VALUES AND PARAMETER NAMES FOR SUBROUTINE CALLS FROM EISPAC
Subroutine Call*
HTRID3 (NM, N,AR jWR,E ~ E2,TAU)
in path for all values, no vectors (2.1.5), modified
IMTQLV
IMTQL 1 (N,WR,E, IERR)
in certain real tridiagonal path (2.1.20)
IMTQLI (N,WR,AR(I, I) ,IERR)
in real symmetric tridiagonal path (2. I. 16)
IMTQL2 (NM, N, WR, E, ZR, IERR)
in certain real tridiagonal path (2.1.19)
l~ffQL2 (NM,N,WR,AR(I, I),ZR,IERR)
in real symmetric tridiagonal path (2. I. 15)
INVIT (NM~N,AR~WR~WI, SELECT ~MM,M 9 ZR~ IERR~ -,-,-)
ORTBAK (NM, LOW, IGH, AR, ORTR, M, ZR)
ORTHES (NM,N,LOW, IGH~AR,ORTR)
ORTRAN (NM, N, LOW, IGH,AR, ORTR, ZR)
RATQR (N,EPSI,AR(I, 2) ,AR(I, I) ,E2,M,WR, IND,BND,TYPE,IDEF,IERR)
in real symmetric tridiagonal paths (2. i. 17, 2. I. 18),
modified
RATQR (N, EPS I, D, E, E2,M,WR, IND, BND, TYPE, IDEF, IERR)
in other paths
TINVlT (NM,N,AR(I,2),AR(I,I),E2,M, WR,IND,ZR, IERR, , , , ,BND)
in real symmetric tridiagonal path (2.1.17)
TINVIT (NM,N~D~E~E2,MjWR~IND~ZR~IERR, , , , ~BND)
in other paths
TQLRAT (N,WR, E2, IERR)
TQLI
109
ISUBNO Value
542
536
557
534
535
533
555
556
562
559
558
(not used)
2.3-28
TABLE 2 (Contd.)
!SUBNO VALUES AND PARAMETER NAMES FOR SUBROUTINE CALLS FROM EISPAC
Subroutine Call*
TQL2 (NM,N,WR,E,ZR, IERR)
TRBAKI (NM,N,AR,E,M, ZR)
TRBAK3 (NM,N,NV,AR,M, ZR)
TREDI (NM, N,AR,WR,E,E2)
in path for all values, no vectors (2.1.12)
TREDI (NM,N,AR, D,E,E2)
in paths for some values (2.1.13, 2.1.14)
TRED2 (NM,N,AR,WR,E,ZR)
TRED3 (N,NV,AR,WR,E,E)
in path for all values and vectors (2.1.11), modified
TRED3 (N,NV,AR,D,E,E2)
in paths for some values (2.1.13, 2.1.14), modified
TRED3 (N,NV,AR,WR,E,E2)
in path for all values, no vectors (2.1.12), modified
TRIDIB (N,EPSI,AR(I,2),AR(I,I),E2,RLB,RUB,MII,M,WR, IND,IERR,BND,-)
in real symmetric tridiagonal paths (2.1.17, 2.1.18), modified
TRIDIB (N,EPSI,D,E,E2,RLB,RUB,MII,M,WR, IND,IERR, BND,-)
in other paths
TSTURM
* A dash at some position in a parameter list indicates a temporary storage array which is not passed to the user subroutine by EISPAC.
1t0
2.3-29
Section 2.3.8
NON-ZERO VALUES OF IERR
This section summarizes the non-zero values of the error parameter
IERR that can be returned by the EISPACK subroutines, either directly or
via the control program (see Section 2.3.7), when an execution error is
detected. Such execution errors are classified into two categories:
first, path-terminating errors, indicated by positive values of IERR and
signifying that although some possibly useful results have been obtained~
continued execution of the path is meaningless; second, non-terminating
errors, indicated by negative values of IERR and signifying that although
errors have already occurred, some further meaningful results may be ob-
tained if the remaining part of the path is executed. Each distinct error
that can occur in EISPACK corresponds to one of a unique set of values for
IERR, that one being a function of the order of the matrix.
The non-zero values of IERR are summarized in Table 3 at the end of
this section. To determine the significance of a particular value of
IERR, scan the column headed IERR for the expression with the value of
your particular error. The name of the subroutine that set the error
parameter is included in the list to the right; also given is the EISPAC
error message number and a brief description of the significance of the
error. More detailed information may be obtained from the documentation
for the particular subroutine in Section 7.
111
2.3- 30
TABLE 3
SUM21~RY OF VALUES OF IERR
IERR
i, INi~N
N+i, 2AiSN
2N+i, 2~iAN
3N+I
SUBROUTINES
CG,CH,COMLR~ COMLR2,COMQR, COMQR2,HQR, HQR2,1MTQLV, IMTQLI,IMTQL2, RG,RS,RSP,RST, RT,TQLRAT, TQLI,TQL2
FIGI,FIGI2
BAKVEC, FIGI2
BISECT, TRIDIB, TSTURM
EISPAC MESSAGE
00
Ol
02
03
SIGNIFICANCE OF THE ERROR
th The calculation of the i eigenvalue failed to converge. If CG, COMLR, COMLR2, COMQR, COMQR2, HQR, HQR2, or RG was being used, the eigenvalues i+l,i+2,...,N should be correct; otherwise, the eigen- values 1,2,...,i-i should be correct. In neither case are any eigenvectors correct.
For a real non-symmetric tri- diagonal matrix (aij), the
product of ai,i_ 1 and ai_l, i
is negative, violating the re- striction for special tri- diagonal matrices discussed in Sections 2.1.19-2.1.22. No useful results are produced.
For a real non-symmetric tri- diagonal matrix (aij) , one but
not both of ai,i_ 1 and ai_l, i
are zero. If FIGI2 was being used, no useful results are produced. If BAKVEC was being used, the eigenvalues computed earlier are correct, but the eigenvectors are not correct.
If BISECT or TSTURMwas being used, the parameter MM specified insufficient storage to hold all the eigenvalues in the interval (RLB,RUB). The only useful re- sult is M, which is set to the number of eigenvalues in this interval. If TRIDIB was being used, it is not possible to compute exactly M eigenvalues (starting from the Mll-th) be- cause of exact multiplicity at index MII. No useful results are produced.
I12
2.3-31
IERR
3N+2
4N+i, l~i~N
5N+i, l~i_<M
6N+I
-i, l~i~N
-N-i, l~i-<N
TABLE 3 (Contd.)
SUMMARY OF VALUES OF IERR
SUBROUTINES
TRIDIB
EISPAC MESSAGE SIGNIFICANCE OF THE ERROR
TSTURM
RATQR
RATQR
CINVIT, INVIT, TINVIT
C INV IT, INVIT
04
05
06
50
50,52
It is not possible to compute exactly M eigenvalues (starting from the Mll-th) because of exact multiplicity at index MII+M-I. No useful results are produced.
The calculation of the i th eigen- vector failed to converge. The eigenvalues 1,2,...,i-i and corresponding eigenvectors should be correct.
The calculation of one or more of the eigenvalues including the i th value failed to converge. All eigenvalues probably have some accuracy, but no stronger state- ment can be made.
The input matrix was specified as positive or negative definite (IDEF=±I) but the subroutine does not find it so; the subroutine should be re-entered specifying IDEF=0. No useful results are produced.
The calculation of one or more of the eigenvectors including the i th vector failed to converge; these vectors are set to zero. These failures may be caused by insuffi- cient accuracy of the corresponding eigenvalues. All non-zero eigen- vectors and their corresponding eigenvalues should be correct.
Both the error above (non- convergence) and the error below (insufficient storage) occurred with their respective results.
113
2.3-32
IERR SUBROUTINES
-2N-I CINVIT, INVIT
-3N-i, 2~i~N FIGI
TABLE 3 (Contd.)
SUMMARY OF VALUES OF IERR
EISPAC MESSAGE SIGNIFICANCE OF THE ERROR
52 The parameter MM specified in- sufficient columns to hold the selected eigenvectors. All eigen- values and the first M columns of (ZR, ZI) or of Z should be correct.
For a real non-symmetric tridiagonal matrix (aij), one but not both of
ai,i_ 1 and ai_l, i are zero. This
does not jeopardize the calculation of the eigenva!ues but invalidates any eigenvectors computed in this path. The error~ therefore~ acts here as a warning but becomes a path-terminating error in BAKVEC if it is subsequently called. (No error message is triggered here from EISPAC, but error message no. 02 will finally result if the VECTOR parameter has been supplied.)
I14
2 .3-33
Section 2.3.9
EXAMPLES ILLUSTRATING THE USE OF THE EISPACK SUBROUTINES AND THE CONTROL PROGRAM
We illustrate the use of Section 2 in preparing two programs to solve
the same eigenproblems, one program calling the EISPACK subroutines directly
and the other using the control program EISPAC. The problems are to find the
eigenvalues in the interval (0,3) and the corresponding eigenvectors of two
real symmetric matrices of orders 3 and 4, chosen to exhibit, respectively,
normal and abnormal path termination. The purpose of choosing these problems
is to illustrate the use of this publication in following a somewhat compli-
cated path; in practice, for such low order matrices, it is probably easier to
use the paths that compute the complete eigensystem.
The two sample programs are complete in that they contain input and out-
put statements; the data for each case and the computed results accompany the
program listing. For both programs, it is assumed that the EISPACK subroutines
are available in compiled form and that appropriate control cards are provided.
Note that the EISPAC sample program also assumes that the compiled form of
EISPAC is available, and may require additional control statements that point
to EISPAC and the EISPACK subroutines.
The EISPACK sample program is written in standard single precision
Fortran IV, while the EISPAC sample program is written in IBM's long precision
Fortran IV. Both programs use Fortran logical unit 5 for input and Fortran
logical unit 6 for output.
For these sample programs, we assume more generally that the order of
the input matrix will not exceed 20 and that the number of eigenvalues in the
interval (0,3) will not exceed 3. Thus the integer constants ~ and ~ dis-
cussed in Section 2.1 have the values 20 and 3 respectively.
115
2.3-34
Given the above eigenproblems, we are directed by Table 1 to Section
2.1.13. There, the appropriate calls to the EISPACK subroutines and to
EISPAC are displayed. Dimensions for the array variables in the sample pro-
grams depend upon ~ and mm and hence from the above discussion, the
declaration statements must be
workir~precision A(20,20),W(3),Z(20,3)
working precision FVI(20),FV2(20),FV3(20),FV4(20),FV5(20),FV6(20),
FV7(20),FVS(20)
INTEGER IV1(3)
To communicate these dimensions to the EISPACK subroutines and to EISPAC, the
parameters NM and MM are set to 20 and 3 respectively. Finally, variables
RLB and RUB are set to 0.0 and 3.0 respectively, specifying the interval to
be searched for the eigenvalues°
The matrices are read row-wise from unit 5 and printed row-wise on unit
6. The first sample matrix has one eigenvalue in the interval (0,3), which
with its corresponding eigenvector are printed on unit 6. The second sample
matrix has more than three eigenvalues in (0,3) and the path is terminated
after BISECT with IERR set to 13 = 3N+I. For this matrix, the EISPACK sample
program distinguishes this error at statement 99999 from other possible
errors~ prints the appropriate message on unit 6 and continues execution
(until a matrix of order zero is specified on unit 5). The EISPAC sample
program also distinguishes this error value from other possible error values,
prints a message numbered 03 on unit 6 and terminates execution. (See
Section 2.3.7 for use of the ERROR keyword parameter to continue execution.)
116
2.3-35
LISTING OF THE EISPACK SAMPLE PROGRAM
C C C
C
C
SAMPLE PROGRAM ILLUSTRATING THE USE OF THE EISPACK SUBROUTINES.
THIS PROGRAM READS A REAL SYN~METRIC MATRIX A FROM FORTRAN LOGICAL UNIT 5 AND COMPUTES EIGENVALUES W IN THE INTERVAL (0,3) AND THE ASSOCIATED ORTHONORMAL EIGENVECTORS SEE SECTION 2.1.13.
Z.
REAL SYMMETRIC MATRIX Aj NO LARGER THAN ORDER 20. REAL EIGENVALUES W, AT MOST 3 OF THEM. ORTHONORMAL EIGENVECTORS Z, AT MOST 3 OF THEM.
REAL A(20,20),W(3),Z(20,3) REAL RLB, RUB, EPS1
TEMPORARY STORAGE ARRAYS.
REAL FVI(20),FV2(20),FV3(20),FV4(20),FV5(20),FV6(20), + FV7(20),FV8(20) INTEGER IV1(3)
ROW AND COLUMN DIMENSION PARAMETERS ASSIGNED.
NM = 20 MM= 3
READ IN THE REAL SYMMETRIC MATRIX OF ORDER N ROW-WISE.
10 READ(5,20) N 20 FORMAT(I4)
IF (N .LE. 0) STOP
DO 40 I = i, N READ(5, 30) (A(I,J),J=I,N)
30 FORMAT(4Ei6.8) 40 CONTINUE
WRITE(6,50) N 50 FORMAT(///23H ORDER OF THE MATRIX IS, 14//16H MATRIX ELEMENTS)
DO 70 I = I, N WRITE(6,60) (A(I,J),J=I,N)
60 FORMAT(1X, 1P4E16.8) 70 CONTINUE
INITIALIZE THE INTERVAL (RLB, RUB).
RLB = 0.0 RUB = 3.0
117
2.3-36
LISTING OF THE EISPACK SAMPLE PROGRAM (Contd.)
90
THE FOLLOWING PATH IS COPIED FROM SECTION 2.1.13.
CALL TREDI(NM, N,A, FV1, FV2, FV3) EPSI : 0.0 CALL BISECT(N, EPSIp FVI, FV2, FV3, RLB, RUB, MM, M, W, IVl, IERR, FV4, FV5) IF (IERR .NE. 0) GO TO 99999 CALL TINVIT(NM, N~ FV1, FV2, FV3,M, W, IV1, Z, IERR, FV4, FV5, FV6, FV7, FVS) IF (IERR .ME. 0) GO TO 99999 CALL TRBAK I(NM, N, A, FV2, M, Z)
PRINT THE M EIGENVALUES AND CORRESPONDING EIGENVECTORS.
IF (M .EQ. 0) GO TO 88888 WRITE(6,90) M FORMAT(/47H NUMBER OF EIGENVALUES IN THE INTERVAL (0,3) IS,14)
DO ii0 I = i, M WRITE(6,100) W(I ) , (Z(J , I ) ,J=I ,N)
100 FORNAT(/11H EIGENVALUE/1X, 1PE16.8//14H CORRESPONDING, + 12H EIGENVECTOR/(1X, 3E16.8))
110 CONTINUE
C C C 88888 88100
C C C 99999
GO TO 10
THERE ARE NO EIGENVALUES IN (0,3).
WRITE(6,88100) FORMAT(43HONO EIGENVALUES OF A IN THE INTERVAL (0,3).) GO TO i0
HANDLING OF IERR PARAMETER
IF (IERR .GT. 0) GO TO 99200 IERR = -IERR WRITE(6,99100) IERR
99100 FORMAT(52HOAT LEAST ONE EIGENVECTOR FAILED TO CONVERGE, NAMELY, 15) GO TO 10
C 99200 WRITE(6,99300) M 99300 FORMAT(/35H NOT ENOUGH SPACE ALLOCATED FOR THE, 14,
+ 35H EIGENVALUES IN THE INTERVAL (0,3).) GO TO 10 END
1t8
2.3-37
LISTING OF THE EISPAC SAMPLE PROGRAM
SAMPLE PROGRAM ILLUSTRATING THE USE OF THE CONTROL PROGRAM EISPAC.
THIS PROGRAM READS A REAL SYMMETRIC MATRIX A FROM FORTRAN LOGICAL UNIT 5 AND COMPUTES EIGENVALUES W IN THE INTERVAL (0,3) AND THE ASSOCIATED ORTHONORMAL EIGENVECTORS SEE SECTION 2.1.13.
Z.
REAL SYMMETRIC MATRIX A, NO LARGER THAN ORDER 20. REAL EIGENVALUES W, AT MOST 3 OF THEM. ORTHONORMAL EIGENVECTORS Z, AT MOST 3 OF THEM.
REAL*8 A(20,20),W(3),Z(20,3) REAL*8 RLB, RUB~EPS1
ROW AND COLUMN DIMENSION PARAMETERS ASSIGNED.
NM=20 MM=3
READ IN THE REAL SYMMETRIC MATRIX OF ORDER N ROW-WISE.
10 REJ~D(5,20) N 20 FORMAT(I4)
IF (N .LE. 0) STOP
DO 40 I = 1, N READ(5,30) (A(I,J),J=I,N)
30 FORMAT(4D16.8) 40 CONTINUE
WRITE(6,50) N 50 FORMAT(///23H ORDER OF THE MATRIX IS,14//16H MATRIX ELEMENTS)
DO 70 1 = 1, N WRITE(6,60) (A(I,J),J=I,N)
60 FORMAT(1X, 1P4D16.8) 70 CONTINUE
INITIALIZE THE INTERVAL (RLB,RUB).
RLB = 0.0D0 RUB = 3.0D0
THE FOLLOWING CALL IS COPIED FROM SECTION 2.1.13.
CALL E I SPAC(NM, N, MATRI X( ' REAL ' ,A, ' SYMMETRIC ' ), + VALUES(W,MM, M, RLB, RUB),VECTOR(Z))
119
2.3-38
LISTING OF THE EISPAC SAMPLE PROGRAM (Contd.)
C C PRINT THE M EIGENVALUES AND CORRESPONDING EIGENVECTORS. C C ARE THERE ANY EIGENVALUES IN (0,3)? C
IF (M oNE. 0) GO TO 90 C C NO. C
WRITE(6,80) 80 FORMAT(43HONO EIGENVALUES OF A IN THE INTERVAL (0,3).)
GO TO 10 C C YES. C
90 WRITE(6pI00) M 100 FORMAT(/47H NUMBER OF EIGENVALUES IN THE INTERVAL (0,3) IS,14)
C DO 120 I=1, M
WRITE(6,110) W(1) , (Z (J , I ) , J= I ,N) 110 FORMAT(/11H EIGENVALUE/1X, 1PD16.8//14H CORRESPONDING,
+ 12H EIGENVECTOR/(1X,3D16.8)) 120 CONTINUE
C GO TO i0 END
120
2 ,3-39
DATA FOR THE SAMPLE PROGRAMS READ FROM UNIT 5
3 -i.0 1.0 -i.0 1.0 1.0 -i.0
-I.0 -i.0 1.0 4
1.875 -0.5 0.375 -0.5 2.25 -0.25 0.375 -0.25 2.125
-0.25 -0.375 -0.125 0
-0.25 -0. 375 -0.125 2. 125
121
OUTPUT FROM THE EISPACK SAMPLE PROGRAM PRINTED ON UNIT 6
ORDER OF THE MATRIX IS
3
MATRIX ELEMENTS
-1.00000000E 00
1.00000000E 00 -I.00000000E 00
1.00000000E 00
1.00000000E 00 -I.00000000E 00
-1.00000000E 00 -1.00000Q00E 00
1.00000000E 00
NUMBER OF EIGENVALUES IN THE INTERVAL (0,3) IS
1
EIGENVALUE
2.56154823E 00
CORRESPONDING EIGENVECTOR
-3.69047642E-01 -6.57192111E-01
6.57192290E-01
GQ
! O
ORDER OF THE MATRIX IS
4
MATRIX ELEMENTS
1.87500000E 00 -5.00000000E-01
3.75000000E-01 -2.50000000E-01
-5.00000000E-01
2.25000000E 00 -2.50000000E-01 -3.75000000E-01
3.75000000E-01 -2.50000000E-01
2.12500000E 00 -1.25000000E-01
-2.50000000E-01 -3.75000000E-01 -1.25000000E-01
2.12500000E 00
NOT ENOUGH SPACE ALLOCATED FOR THE
4 EIGENVALUES IN THE INTERVAL (0,3).
OUTPUT FROM THE EISPAC SAMPLE PROGRAM PRINTED ON UNIT 6
CO
ORDER OF THE MATRIX IS
3
MATRIX ELEMENTS
-I.00000000D 00
1.00000000D 00 -1.00000000D 00
1.00000000D 00
1.00000000D 00 -1.00000000D 00
-I.00000000D 00 -1.00000000D 00
1.00000000D 00
NUMBER OF EIGENVALUES IN THE INTERVAL (0,3) IS
EIGENVALUE
2.56155281D 00
CORRESPONDING EIGENVECTOR
-3.69048184D-01 -6.57192300D-01
6.57192300D-01
ORDER OF THE MATRIX IS
4
MATRIX ELEMENTS
1.87500000D 00 -5.00000000D-01
3.75000000D-01 -2.50000000D-01
-5.00000000D-01
2.25000000D 00 -2.50000000D-01 -3.75000000D-01
3.75000000D-01 -2.50000000D-01
2.12500000D 00 -1.25000000D-01
-2.50000000D-01 -3.75000000D-01 -1.25000000D-01
2.12500000D 00
EISPAC EXECUTION PHASE ERROR(S)...
03 PARAMETER MM SPECIFIED INSUFFICIENT STORAGE TO HOLD ALL EIGENVALUES IN THE INTERVAL LB TO UB.
EXECUTION TERMINATED.
I
3.0-1
Section 3
VALIDATION OF EISPACK
As part of its original development, EISPACK was subjected to thorough
testing designed to exercise every statement in each subroutine and path
in the package° Before a version of EISPACK is declared certified, however,
it must also be validated at one or more test sites not involved in the
adaptation. This validation has two important goals. One is to insure
that the adaptation has been carried out successfully and that EISPACK
performs as anticipated on that computer system. The second has been of
major importance in the development of EISPACK; it is to provide feedback
on the ease of use of EISPACK and its documentation. The procedures
included in and the philosophy behind this validation are discussed in
further detail in ([3],[5]).
Thus~ validation at test sites includes two kinds of testing. The
first employs tes~ drivers and a collection of 82 matrices supplied with
EISPACK; its purpose is to verify that the subroutines have been adapted
to the machine and system properly, and to obtain data which can later be
used as a check at other locations having the same computer system. These
test drivers and matrices are included on the tape from the distribution
center as described in Section 5.
The second kind of testing is the more informal; it seeks to employ
EISPACK in actual scientific computations to measure the ease of use of
the routines and their documentation. By its very nature, of course, this
informal testing is not repeatable.
In order to simplify the communication of the results of the formal
testing, a measure of performance for EISPACK, based on the backward error
analysis of Wilkinson and Reinsch ([1],[2]), was defined. It is computed as:
124
3.0-2
= max iNi!N
11Az i - Xizill 10.N.~.llAl[.llzill
where each pair %'i and z i is an eigenvalue and corresponding eigenvector
computed by EISPACK for the matrix A of order N, and where e is the pre-
cision of arithmetic on the test machine (called MACHEP in the subroutines).
The factor i0 in the formula for ~ was chosen empirically to obtain
the following criterion for the performance of EISPACK:
If ~ is less than i, EISPACK has performed satisfactorily (as well as
can be expected according to the backward error analysis for the particular
precision of arithmetic). If ~ is greater than i00, the performance is
deemed poor. Finally, if ~ is between 1 and I00, the performance is pro-
gressively marginal, and further investigation might be in order to verify
that no error has occurred.
This measure of performance is also useful as a check on the correct
installation of EISPACK; the residuals Az i - %izi are very sensitive to
small perturbations in I i and zi, and hence so is ~. ~ may thus reflect
small changes in the performance of EISPACK caused either by changes in the
subroutines themselves or by the hardware, operating system, compiler, or
library with which they are used. Hence it provides an excellent "quick
check" of the correct installation of E~SPACK on a hardware-software system.
If the values of ~ obtained from the test cases exactly duplicate those
obtained at the test site, it is virtually certain that EISPACK has been
correctly installed. If, however, the values of ~ differ, an error may
have occurred in the transmission or implementation of EISPACK, or the
hardware-software system may differ from that on which it was tested; such
differences should probably be investigated.
125
3.0-3
The collection of 82 test matrices has been accumulated from various
sources and provides a wide spectrum of test cases from trivial to patho-
logical. Most values of the performance index ~ for these test cases
were less than i for the systems on which EISPACK has been certified. The
weaker performances were generally observed in the paths where some eigen-
vectors were computed; that is, where the inverse iteration subroutines
(INVIT, CINVIT, TINVIT) were called.
126
4.0-I
Section 4
EXECUTION TIMES FOR EISPACK
In this section we display approximate execution times of the indi-
vidual subroutines and various paths in EISPACK measured with sample
matrices on many of the computer systems for which the subroutines have
been certified. The elements of the sample matrices are random numbers
sampled from uniform distributions. Tables of execution times appear
in the first subsection, and considerations regarding the reliability of
the timing measurements, their dependence upon the elements of the
matrices, and the extrapolation of these results to other machines are
discussed in later subsections. The section concludes with listings of
the program segments that generate the sample matrices.
127
4.1-1
Section 4.1
TABLES OF EXECUTION TIMES
For each of 15 computer systems there follow three tables displaying
sample execution times respectively for complex general matrices, real
general matrices~ and those matrices that can be reduced to real symmetric
tridiagonal form. A further table follows comparing the performances of
the computer systems with each other. Finally, one additional table is
included reporting path timings on the IBM 370/195 when the control program
EISPAC is used.
The tables report execution times both for the individual subroutines
and for many of the recommended paths. Each column of a table reports times
for a matrix of different order. The entries in any column are expressed
as multiples of the time unit that appears at the head of the column. The
time unit chosen is the absolute time for subroutine COMHES, ELMHES, or
TREDI as appropriate. A dash appears in place of an entry representing
an execution time too small to be measured within the resolution of the
clock.
For a subroutine that computes some eigenvalues or eigenvectors, the
tabulated time represents that required for the subroutine to compute
all eigenvalues or eigenvectors. The times for the eigenvector subroutines
INVIT~ CINVIT, and TINVIT are measured when the eigenvalues are provided
by the subroutines HQR, COMLR, and BISECT respectively; these times
could be significantly longer if less accurate eigenvalue subroutines
were substituted.
For paths where a driver subroutine exists, the time for the actual
call of the driver subroutine is recorded. For other paths, the entries
are built by summing the times for the separate suhroutines. The entries
128
4.1-2
for those paths that compute partial eigensystems are expressed as the
sum of two terms: the first term is the base time for the path and the
second term is that part which depends upon the number of eigenvalues
and eigenvectors computed. For complex general matrices, this latter
term is the product of the estimated time to compute one eigenvector and
M, the number of eigenvectors computed. For real general matrices, it
is the product of the estimated time to compute one column of the eigen-
vector matrix and M, the number of columns required to store the requested
eigenvectors. For matrices that can be reduced to real symmetric tri-
diagonal form, it is either the product of the estimated time to compute
one eigenvalue-eigenvector pair and M, the number of pairs computed, or
the product of the estimated time to compute one eigenvalue and M, the
number of eigenvalues computed. Program segments that generate the
sample matrices are listed in Section 4.5.
129
4.1-3
TABLE 4
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
COMPLEX GENERAL MATRICES
MACHINE: IBM 370/195, Fortran H, OPT=2 ARGONNE NATIONAL LABORATORY
SUBROUTINE
Time Unit (See)
CBAL CBABK2
COMHES COMBAK
CORTH CORTB
COMQR2 COMLR2
COMQR COMLR
CINVIT
ORDER OF MATRIX
N=I0 N=20 N=40 N=60 N=80
.002 .014 .099 .33 °86
o 17 .07 .03 .02 ~01 . II .05 .03 .02 .01
i i i 1 I .46 .53 .61 .66 .91
2.3 2.6 3,0 3.0 2.8 i,I 1.3 1.4 1.5 1.3
15 14 !4 14 13 ii i0 9.3 9,1 8.0
7.7 5.8 4.8 4.4 3.8 6.9 4.9 3.5 3.1 2.6
7.4 5.5 4.3 3.7 3.4
PATHS
CG (CBAL,CORTH,COMQR2,CBABK2)
CG (CBAL,CORTH,COMQR)
CBAL,CORTH,COMQR,CINVIT, CORTB~CBABK2
18
i0
I0+.86M
17 17 17 15
8.5 7.8 7.5 6.7
8.5+o34M 7.8+.14M 7.5+.09M 6.6+.06M
130
4. I-4
SUBROUTINE
Time Unit (Sec)
BALANC BALBAK
ELMHES ELTRAN ELMBAK
ORTHES ORTRAN ORTBAK
HQR2
HQR
INVIT
TABLE 5
SUMMARY OF EXECUTION TIM~S FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
REAL GENERAL MATRICES
MACHINE: IBM 370/195, Fortran H, OPT=2 ARGONNE NATIONAL LABORATORY
ORDER OF MATRIX
N= i0 N=20 N=40 N=60 N=80
.001 .006 .047 .15 .36
.40 .13 .05 .03 .02
.17 .07 .03 .02 .02
1 1 i 1 i .28 .13 .06 .04 .03 .63 .59 .60 .60 .64
2.6 2.7 2.7 2.6 2.6 .72 .60 .54 .52 .51
1.0 .91 .83 .79 .78
19 15 13 12 12
12 7.9 5.4 4.7 4.2
6.3 5.2 4.3 3.9 3.7
PATHS
RG (BALANC, ELMHES, ELTRAN, HQR2, BALBAK)
RG (BALANC,ELMHES,HQR)
BALANC, ELMHES, HQR, INVIT, ELMBAK ~ BALBAK
20
13
13+.71M
17 14 14 13
9.0 6.6 5.8 5.2
9 . 0+. 29M 6 . 5+. 12M 5.8+. 08M 5.3+. 05M
131
4. I-5
TABLE 6
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT
REDUCE FULL MATRICES TO REAL SYMMETRIC TRIDIAGONAL FORM
MACHINE: IBM 370/195, Fortran H, OPT=2 ARGONNE NATIONAL LABORATORY
SUBROUTINE
Time Unit (Sec)
N=IO
.001
ORDER OF MATRIX N=20 N=40 N=60
,007 .041 .12
N=80
.27
TREDI TRED2 TRED3 TRBAKI TRBAK3
1 1 1 1 1
1.6 1.8 2.0 2.1 2.2 ,98 i.i i.I 1.2 1.2
1.2 1.4 1.6 1.7 1.8 .85 I.i 1.3 1.5 1.5
HTRIDI HTRID3 HTRIBK HTRIB3
2.1 2.6 3.0 3.2 3.4 2.2 2.8 3.3 3.6 3.8 2.3 3.4 4.3 4.9 5.1 2.6 4.0 5.1 5.7 6,0
FIGI FIGI2 BAKVEC
13 ~05 °02 .01 °00 18 .i0 ~05 .03 ,02 I0 .05 ~03 .02 .01
TQL2 IMTQL2
TQLRAT TQLI IMTQLI
BISECT TRIDiB IMTQLV RATQR
TINVIT TSTURM
3.4 3.5 3.3 3.2 3.2 3,8 3.8 3.7 3.5 3.5
1.2 .67 °36 .24 ,18 2.1 1.5 ,94 .66 ,52 2.2 1.6 1.0 ,73 ,57
12 8.1 4.9 3.5 2.7 12 7.7 4.6 3.3 2.5 2.4 1.7 I. 1 .77 .60 2.6 2.2 1.5 1.2 .93
.95 ,64 ~40 .30 .30 13 8.6 5.3 3.8 3.0
PATHS
RS (TRED2,TQL2) RS (TREDI,TQLRAT) TREDI,BISECT,TINVIT,TRBAKI TREDI,BISECT
CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,TINVIT~HTRiBK HTRIDI,BISECT
5.0 5.3 5.3 5.3 5.3 2.2 1.7 1.3 1.2 1.2
I+i . 4M i+. 5 IM I+. 17M I+. 09M i+. 06M i+i. 2M i+. 40M I+. 12M I+. 06M i+. 03M
8.1 9.5 Ii II 12 3.3 3.3 3.3 3.5 3.6
2.1+1.5M 2.6+.61M 3.0+.24M 3.2+.15M 3.4+.IOM 2.1+1.2M 2.6+.40M 3.0+.12M 3.2+.06M 3.4+.03M
132
4.1-6
TABLE 7
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
COMPLEX GENERAL MATRICES
MACHINE: IBM 360/75, Fortran H, OPT=2 UNIVERSITY OF ILLINOIS
SUBROUTINE
Time Unit (See)
CBAL CBABK2
COMIIES COMBAK
CORTH CORTB
COMQR2 COMLR2
COMQR COMLR
CINVlT
ORDER OF MATRIX
N=20 N=40 N=60 N=80
.20 1.6 5.2 12
.04 .02 .01 .01
.05 .01 .01 .01
1 i i 1 .48 .52 .55 .55
2.2 2.3 2.3 2.4 1.2 1.2 1.2 1.3
15 14 14 14 7.7 6.6 6.5 6.3
5.7 4.7 4.5 4.4 3.5 2.4 2.3 2.1
3.2 2.4 2.2 2.1
PATHS
CG (CBAL, CORTH, COMQR2, CBABK2 )
CG (CBAL, CORTH, COMQR)
CBAL, CORTH, COMQR, CINVlT, CORTB, CBABK2
17 17 16 16
7.9 7.1 6.8 6.7
7.9+.22M 7.1+.09M 6.8+.06M 6.7+.04M
133
4.1-7
TABLE 8
Sb~MARY OF EXECUTION TIMES FOR THE E!SPACK SUBROUTINES INCLUDED IN THE PATHS FOR
HEAL GENERAL MATRICES
MACHINE: IBM 360/75, Fortran H, OPT=2 UNIVERSITY OF ILLINOIS
SUBROUTINE
Time Unit (Sec)
BALANC BALBAK
ELMHES ELTRAN ELMBAK
ORTHES ORTRAN ORTBAK
HQR2
HQR
INVIT
ORDER OF MATRIX
N=20 N=40 N=60 N=80
.063 .49 1.6 3.9
. II .04 .02 .02 ~03 .02 .02 °01
I 1 1 i .05 .03 .02 .01 .65 .60 .61 .60
2.5 2.4 2.3 2.3 .78 .69 .68 .67
I.i i.i I.i 1.0
17 14 14 13
8.0 5.8 5.2 4.6
3.7 3.1 2.9 2.7
PATHS
RG (BALANC,ELMIIES ,ELTRAN, NQR2, BALBAK)
RG (BALANC, ELMHES, HQR)
BALANC, ELMHES, HQR, INVIT, ELMBAK, BALBAK
18 15 15 14
9.1 6.8 6.2 5.7
9.1+.22M 6.8+.09M 6.2+.06M 5.7+.04M
134
4. i-8
TABLE 9
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT
REDUCE FULL MATRICES TO REAL SYMMETRIC TRIDIAGONAL FORM
MACHINE: IBM 360/75, Fortran H, OPT=2 UNIVERSITY OF ILLINOIS
SUBROUTINE ORDER OF MATRIX
N=20 N=40 N=60 N=80
Time Unit (See) .072 .48 1.6 3.5
TRED 1 TRED2 TRED3 TRBAKI TRBAK3
1 1 1 1 1.8 1.9 1.9 2.0 .96 .93 1.0 1.0
1.3 1.5 1.5 1.5 1.2 1.3 1.4 1.4
HTRIDI HTRID3 HTRIBK HTRIB3
2.9 3.2 3.4 3.5 3.0 3.3 3.6 3.7 4.1 4.6 5.0 5.1 4.4 5.0 5.5 5.6
FIGI FIGI2 BAKVEC
.01 .00
.01 .01
.02 .01
TQL2 IMTQL2
4.9 5.0 4.8 4.8 5.0 5.0 4.9 4.9
TQLRAT TQLI IMTQLI
.58 .32 .21 .15 1.3 .70 .47 .36 1.2 .71 .50 .38
BISECT TRIDIB IMTQLV RATQR
4.9 2.7 1.8 1.4 5.2 2.8 1.9 1.5 1.3 .75 .49 .38 2.2 1.4 .99 .79
TINVIT TSTURM
• 49 .34 .25 .28 5.5 3.1 2.2 1.7
PATHS
RS (TRED2,TQL2) RS (TREDI, TQLRAT) TREDI,BISECT,TINVIT,TRBAKI TREDI,BISECT
6.7 6.9 6.8 6.8 1.4 1.3 1.2 i.I
i+. 33M I+. 1 IM i+. 06M I+. 04M i+. 24M I+. 07M I+. 03M I+. 02M
CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,TINVlT,HTRIBK HTRIDI,BISECT
12 12 13 13 3.5 3.5 3.6 3.7
2.9+.47M 3.2+.19M 3.4+.12M 3.5+.09M 2.9+.24M 3.2+.07M 3.4+.03M 3.5+.02M
~85
4. i-9
TABLE i0
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
COMPLEX GENERAL MATRICES
MACHINE: IBM 370/168, Fortran H, OPT=2 UNIVERSITY OF MICHIGAN
SUBROUTINE
Time Unit (Sec)
CBAL CBABK2
COMHES COMBAK
CORTH CORTB
COMQR2 COMLR2
COMQR COMLR
CINVIT
ORDER OF MATRIX
N=I0 N=20 N=40 N=60 N=80
.008 °070 .57 2.0 4.7
.08 .03 .01 .01 .01 • 07 .03 ~01 .01 .01
! 1 1 1 1 • 47 .52 ,54 .55 ,58
2 .3 2 .3 2 .2 2 .2 2 .2 1.3 1.3 1.2 1.2 1.2
19 16 15 14 14 9.1 7.7 6.5 6.3 6.1
8.1 5.9 4.8 4.6 4.3 4.9 3.3 2.3 2.1 1.9
4.5 3.0 2.2 2.0 1.9
PATHS
CG (CBAL, CORTH~COMQR2,CBABK2)
CG (CBAL,CORTH,COMQR)
CBAL,CORTH,COMQR,CINVIT, CORTB~CBABK2
21
Ii
1 i+. 58M
19 17 17 16
8.1 7.0 6.7 6.4
8.2+.21M 7~O+.09M 6.7+.05M 6o4+.04M
136
4.1-10
TABLE Ii
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
REAL GENERAL MATRICES
MACHINE: IBM 370/168, Fortran H, OPT=2 UNIVERSITY OF MICHIGAN
SUBROUTINE
Time Unit (Sec)
BALANC BALBAK
ELMHES ELTRAN ELMBAK
ORTHE S ORTRAN ORTBAK
HQR2
HQR
INVIT
ORDER OF MATRIX
N=I0 N=20 N=40 N=60 N=80
.003 .020 .16 .56 1.4
.20 .07 .03 .02 .01
.14 .06 .03 .02 .01
i 1 i I 1 • 12 .05 .02 .01 .01 .56 .58 .59 .59 .60
2.7 2.5 2.4 2.3 2.3 .87 .81 .78 .77 . 76
1.4 1.3 1.2 1.2 1.2
23 18 15 15 14
13 8.8 6.1 5.5 4.9
4.7 3.6 2.8 2.6 2.4
PATHS
RG (BALANC~ELMIIES~ELTRAN~ HQR2,BALBAK)
RG (BALANC,ELMHES,HQR)
BAL~NC,ELMHES,HQR~INVlT~ ELMBAK, BALBAK
25
14
14+.54M
19 16 16 15
9.8 7.2 6.5 5.9
9.8+.21M 7.2+.09M 6.5+.05M 5.9+.04M
137
4.1-11
TABLE 12
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT
REDUCE FULL MATRICES TO REAL SYMMETRIC TRIDIAGONAL FORM
MACHINE: IBM 370/168, Fortran H, OPT=2 UNIVERSITY OF MICHIGAN
SUBROUTINE ORDER OF MATRIX
N=I0 N=20 N=40 N=60 N=80
Time Unit (See) ~004 .023 .16 .50 1,2
TRED 1 TRED2 TRED3 TRBAKI TRBAK3
1 I i 1 i 1,6 1.8 1.9 2.0 2.0 .98 °99 1.0 1.0 1.0
i.i 1.3 1.5 1.5 1,5 .99 1.2 1.4 1.5 1.5
HTRIDI HTRID3 HTRIBK HTRIB3
2.8 3.1 3.4 3.6 3.7 2.7 3.1 3.5 3.6 3.7 3.3 4.3 5.0 5.2 5.3 3.4 4.5 5.2 5.4 5.5
FiGI FIGI2 BAKVEC
.09 .03 .01 .00 ,00 ,12 .04 .02 ,01 .01 .i0 .05 .03 .02 .02
TQL2 IMTQL2
5.4 5.8 5.7 5.6 5.4 5.4 5.5 5.6 5.3 5.3
TQLRAT TQLI IMTQLI
1.2 .66 .34 .22 .16 2,3 1.4 .81 .55 ,42 2,3 1.5 .83 .56 .42
BISECT TRIDIB IMTQLV RATQR
TINVIT TSTUPd<
8.0 4.9 2.7 1.8 1.4 8.4 5.0 2.7 1.8 1.4 2.4 1.5 .85 .57 .44 2.8 2,1 1.4 1.0 ,80
.86 .54 .31 .23 °26 8,8 5.3 2.9 2.0 1.6
PATHS
RS (TRED2,TQL2) RS (TREDI,TQLRAT) TREDI,BISECT,TINVIT,TRBAKI
TREDI,BISECT
CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,TINVIT~HTRIBK HTRIDI,BISECT
7.0 7.6 7.6 7.6 7.4 2.2 1,7 1.3 1.2 1.2 I+I.0M i+. 34M i+. IIM I+.06M 1+. 04M I+. 80M I+. 24M i+. 07M I+. 03M I+. 02M
ii 13 14 14 14 4.1 3.8 3.8 3.8 3.8
2.8+1.2M 3.1+.48M 3.4+.20M 3.6+,12M 3.7+.09M 2.8+.80M 3.1+,24N 3.4+.07M 3.6+.03M 3.7+.02M
138
4.1-12
TABLE 13
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
COMPLEX GENERAL MATRICES
MACHINE: IBM 370/165, Fortran H Extended, OPTIMIZE(2) THE UNIVERSITY OF TORONTO
SUBROUTINE
Time Unit (Sec)
CBAL CBABK2
COMHES COMBAK
CORTH CORTB
COMQR2 COMLR2
COMQR COMLR
CINVIT
ORDER OF MATRIX
N=I0 N=20 N=40 N=60 N=80
.006 .043 .39 1.5 4.0
- .06 .03 .02 .01 - - .02 .02 .01
1 1 1 1 1
1 .53 .62 .71 .98
2 2.2 2.0 1.9 1.7 1 1.2 I. 1 .95 .85
17 16 13 12 i0 ii 9.3 7.5 6.5 5.9
8 5.9 4.3 3.7 3.2
6 4.1 2.7 2.2 1.9
7 4.8 3.3 2.6 2.5
PATHS
CG (CBAL,CORTH,COMQR2,CBABK2)
CG (CBAL,CORTH,COMQR)
CBAL,CORTH,COMQR,CINViT, CORTB,CBABK2
20 18 15 13 12
ii 8.2 6.4 5.6 4.9
10+.8M 8.2+.30M 6.4+.IIM 5.6+.06M 4.9+.04M
139
4.1-13
TABLE 14
SUMY~RY OF EXECUTION TIMES FOR THE E!SPACK SUBROUTINES INCLUDED IN THE PATHS FOR
REAL GENERAL MATRICES
MACHINE: IBM 370/165, Fortran H Extended, OPTIMIZE(2) THE UNIVERSITY OF TORONTO
SUBROUTINE
Time Unit (Sec)
BALANC BALBAK
ELMHES ELTRAN ELMBAK
ORTHES ORTRAN ORTBAK
HQR2
HQR
INVIT
ORDER OF MATRIX
N=20 N=40 N=60 N=80
.016 .12 .43 i.i
- .05 .03 .02
- . 0 3 . 0 2 . 0 2
1 1 1 1 - . 0 7 . 0 4 . 0 3
.62 .63 .66 .80
2.3 2.4 2.2 2.1 • 83 .75 .71 .64
1.2 I.i i.i .95
16 15 13 ii
8.5 5.9 4.9 4.1
4,2 3.7 3.1 2,8
PATHS
RG (BALANC, ELMHES, ELTRAN, HQR2, BALBAK)
RG (BALANC, ELMHES, HQR)
BALANC, ELMHES, HQR, INVIT, ELMBAK, BALBAK
18 16 14 12
9.1 6.8 5.9 5.1
9.5+.24M 7.0+.IIM 5.9+.06M 5.1+.05M
140
4.1-14
TABLE 15
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT
REDUCE FULL MATRICES TO REAL SYMMETRIC TRIDIAGONAL FORM
MACHINE: IBM 370/165, Fortran H Extended, OPTIMIZE(2) THE UNIVERSITY OF TORONTO
SUBROUTINE ORDER OF MATRIX
N=I0 N=20 N=40 N=60 N=80
Time Unit (Sec) .003 .017 .ii .35 .84
TREDI TRED2 TRED3 TRBAKI TRBAK3
i i i i 1 2 1.7 1.9 2.0 2.0 I .92 1.0 1.0 1.0 i 1.5 1.6 1.7 1.6 i i.i 1.3 1.3 1.3
HTRIDI HTRID3 HTRIBK HTRIB3
2 2.7 3.1 3.6 4.1 3 2.7 3.2 3.4 3.5 3 3.7 4.7 5.0 5.5 4 4.0 5.1 5.1 5.1
FIGI FIGI2 BAKVEC
- .01 .00 .04 .03 .02 .03 .02 .02
TQL2 IMTQL2
4 4.8 4.7 4.8 4.4 4 4.9 4.8 4.7 4.6
TQLRAT TQLI IMTQLI
2 .80 .42 .27 .19 2 1.5 .92 .61 .46 2 1.7 .96 .63 .47
BISECT TRIDIB IMTQLV RATQR
i0 6.7 3.9 2.6 1.9 9 6.5 3.8 2.6 1.9 3 1.7 .98 .64 .48 2 2.3 1.6 i.i .86
TiNVIT TSTURM
i . 76 .42 . 30 . 30 i0 7.3 4.2 2.9 2.2
PATHS
RS (TRED2,TQL2) RS (TRED i, TQLRAT) TREDI,BISECT,TINVIT,TRBAKI TREDI,BISECT
6 6.8 6.6 6.7 6.3 3 1.8 1.4 1.3 1.2
i+ 1 . 2M i+. 45M I+. 15M i+. 08M i+. 05M I+i. 0M i+. 34M i+. 10M i+. 04M i+. 02M
CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,TINVIT~HTRIBK HTRIDI,BISECT
ii 4
4+i. 4M 4+1.0M
ii 13 13 14 3.4 3.6 3.9 4.3
2.7+.56M 3.1+.22M 3.6+.13M 4.1+.IOM 2.7+.34M 3.1+.IOM 3.6+.04M 4.1+.02M
141
4.1-15
TABLE 16
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
COMPLEX GENERAL MATRICES
MACHINE: Burroughs 6700, Fortran IV (2.6) UNIVERSITY OF CALIFORNIA~ SAN DIEGO
SUBROUTINE
Time Unit (Sec)
CBAL CBABK2
COMHES COMBAK
CORTH CORTB
COMQR2 COMLR2
COMQR COMLR
CINVlT
ORDER OF MATRIX
N=I0 N=20 N=40 N=60
.27 2.1 17 59
. i0 .04 °02 .01
.05 .02 .01 .01
i 1 1 I .58 .56 .59 .59
1.7 1.6 1.6 1.6 .92 1.0 .99 .94
13 Ii i0 9.6 8.6 7.9 6.8 6.8
5.0 3.9 3.3 3.1 4.3 3.1 2.4 2.3
3.3 2.6 2.3 2.2
PATHS
CG (CBAL~CORTH,COMQR2,CBABK2)
CG (CBAL,CORTH, COMQR)
CBAL~CORTH,COMQR~CINVIT, CORTB~CBABK2
14 13 12 Ii
6.7 5.6 4.9 4.6
6.8+. 43M 5.5+. 18M 4.9+. 08M 4.8+. 05M
142
4.1-16
TABLE 17
SIIMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
REAL GENERAL MATRICES
MACHINE: Burroughs 6700, Fortran IV (2.6) UNIVERSITY OF CALIFORNIA, SAN DIEGO
SUBROUTINE
Time Unit (Sec)
BALANC BALBAK
ELMHES ELTR2uN ELMBAK
ORTHES ORTRAN ORTBAK
HQR2
HQR
INVIT
ORDER OF MATRIX
N=I0 N=20 N=40 N=60
.095 .79 6.3 20
.18 .06 .03 .02
.08 .04 .02 .01
1 1 i 1 .17 .07 .04 .03 • 57 .58 .59 .60
1.7 1.7 1.6 1.7 .83 .70 .66 .66
i.i .99 .94 1.0
12 9.9 8.9 8.8
6.3 4.3 3.6 3.1
3.1 2.4 2.1 2.1
PATHS
RG (BALANC,ELMHES,ELTRAN, HQR2,BALBAK)
RG (BALANC, ELMHES, HQR)
BALANC, ELMHES, HQR, INVIT ELMBAK, BALBAK
14 11 I0 9.9
7.8 5.4 4.5 4.3
7.5+. 38M 5.4+. 15M 4.6+. 07M 4. i+. 04M
143
4.1-17
TABLE 18
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT
REDUCE FULL MATRICES TO REAL SYMMETRIC TRIDIAGONAL FORM
MACHINE: Burroughs 6700, Fortran IV (2.6) UNIVERSITY OF CALIFORNIA, SAN DIEGO
SUBROUTINE ORDER OF MATRIX
N=IO N=20 N=40 N=60
Time Unit (Sec) .093 ~56 4.1 13
TRED i TRED2 TRED3 TRBAKI TRBAK3
i 1 1 I 1.6 1.9 2.0 2.2 .77 .82 .76 .80
I.I 1.5 1.6 1.8 I.i 1.4 1,5 1.6
HTRIDI HTRID3 HTRIBK HTRIB3
2.5 2.9 3.1 3.1 2.4 2.8 3.0 3.1 3.5 4.6 5.1 5.3 3.7 4.9 5.1 5.3
FIGI FIGI2 BAKVEC
.05 .01 .00 .00
.12 ,05 .03 .02
.09 .06 .03 .02
TQL2 IMTQL2
4.2 4,7 4.6 4.7 4.4 5.1 4.8 5.2
TQLRAT TQLI IMTQLI
.77 .38 .19 .13 i.I .68 .36 .25 1.2 .69 .37 .25
BISECT TRIDIB IMTQLV HATQR
3.7 2.1 I.I ,73 4.1 2.5 1.2 .83 i. 1 .61 .31 .22 1.4 I.I .62 ,46
TINVlT TSTURM
.68 o 43 .24 .19
5.0 3.0 1.5 i.I
PATHS
RS (TRED2,TQL2) RS (TREDI,TQLRAT) TREDI,BISECT,TINVlT,TRBAKI TREDI~BISECT
5.8 6.9 6.6 6.9 1.5 1.3 i.I i.i
I+. 55M i+. 20M I+. 07M I+. 04M I+. 37M i+. IIM i+. 03M I+.01M
CH (HTRIDI,TQL2,HTRiBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,TINVIT,HTRIBK HTRIDI,BISECT
ii 12 13 13 3.2 3.2 3.3 3,3
2.5+.79M 2,9+.35M 3.1+.16M 3.1+.IOM 2.5+.37M 2.9+.IIM 3.1+.03M 3.1+.OIM
144
4.1-18
TABLE 19
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
COMPLEX GENERAL MATRICES
MACHINE: CDC 6600, FTN (4.2) Compiler KIRTLAND AIR FORCE BASE
SUBROUTINE
Time Unit (Sec)
CBAL CBABK2
COMHES COMBAK
CORTH CORTB
COMQR2 COMLR2
COMQR COMLR
CINVIT
ORDER OF MATRIX
N=40 N=50 N=60 N=70 N=80
.52 1.0 1.8 2.8 4.2
1 1 1 1 1 .72 .57 .55 .56 .56
2.8 2.6 2.7 2.7 2.7 1.0 .96 .93 .95 .97
14 12 12 12 12 7.5 6.9 6.6 6.5 6.6
4.9 4.5 4.3 4.2 4.2 3.1 2.7 2.5 2.4 2.4
2.6 2.3 2.2 2.2 2.2
PATHS
CC (CBAL,CORTH,COMQR2,CBABK2)
CC (CBAL,CORTH,COMQR)
CBAL,CORTH,COMQR,CINVIT, CORTB,CBABK2
16 15 15 14 15
7.8 7.1 6,9 6.8 7.0
7.7+.09M 7.1+.07M 6.9+.05M 6.8+.04M 6.9+.04M
145
4.1-19
TABLE 20
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
REAL GENERAL MATRICES
MACHINE: CDC 6600, FTN (4.2) Compiler KIRTLAND AIR FORCE BASE
SUBROUTINE
Time Unit (Sec)
BALANC BALBAK
ELMHES ELTRAN ELMBAK
0RTHES ORTRAN ORTBAK
HQR2
HQR
INVIT
ORDER OF MATRIX
N=40 N=50 N=60 N=70 N=80
.25 .49 .80 1.4 2.0
1 1 1 1 1
.46 .59 °59 .61 °58
2.6 2.6 2.6 2.5 2.5 • 92 .81 •81 .76 .75
1.2 1.2 1.2 1.2 1.2
12 12 12 ii i0
5.1 4.9 4.6 4.0 3.8
2.8 2.7 2.7 2.5 2.4
PATHS
RG (BALANC, ELMHES, ELTRAN, HQR2, BALBAK)
RG (BALANC, ELMHES, HQR)
BALANC, ELMHES ,HQR, INVIT, ELMBAK, BALBAK
13 13 13 12 12
6.1 5.7 5.7 5.0 4.7
6.1+.08M 5.8+.07M 5.6+.05M 5.0+.04M 4.8+.04M
146
4.1-20
TABLE 21
Sb~MMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT
REDUCE FULL MATRICES TO REAL SY~fl~ETRIC TRIDIAGONAL FORM
MACHINE: CDC 6600, FTN (4.2) Compiler KIRTLANDAIR FORCE BASE
SUBROUTINE ORDER OF MATRIX
N=40 N=50 N=60 N=70 N=80
Time Unit (Sec) .19 .37 .60 .92 1.3
TRED 1 TRED2 TRED3 TRBAKI TRBAK3
1 1 1 1 1 2.2 2ol 2.1 2.2 2.2 1.8 1.8 1.7 1.8 1.7 1.7 1.7 1.7 1.8 1.8 1.9 1.9 2.0 2.1 2.0
HTRIDI HTRID3 HTRIBK HTRIB3
2.2 1.9 2.2 2.3 2.1 1.9 2.1 2.2 2.3 2.0 3.4 3.0 3.5 3.7 3.3 3.0 3.1 3.4 3.6 3.4
FIGI FIGI2 BAKVEC
TQL2 IMTQL2
4.2 4.0 4.0 4.2 4.0 4.5 4.3 4.4 4.4 4.4
TQLRAT TQLI IMTQLI
.39 .28 .25 .21 .19 • 63 .49 .42 .37 .32 .68 .56 .50 .44 .38
BISECT TRIDiB IMTQLV RATQR
6.2 4.9 4.2 3.7 3.2 6.0 4.8 4.2 3.6 3.2 .76 .62 .54 .47 .42
2.0 1.6 1.4 1.3 i.i
TINViT TSTURM
.52 .40 .39 .36 .40 6.6 5.3 4.6 4.1 3.7
PATHS
RS (TRED2,TQL2) RS (TREDI,TQLRAT) TREDI,BISECT,TINVIT,TRBAKI TREDI,BISECT
6.3 6.0 6.1 6.2 6.2 1.4 1.3 1.2 1.2 1.2
I+.21M I+. 14M I+. IIM I+.08M I+.07M
i+. 16M i+. IOM I+. 07M i+. 05M i+. 04M
CH (HTRIDI,TQL2,HTRIBK) CH (H~RIDI, TQLRAT) HTRIDI,BISECT,TINVIT,HTRIBK HTRIDI,BISECT
8.8 8.9 9.7 i0 9.2 2.1 2.3 2.5 2.6 2.3
2.2+.25M 2.~.15M 2.1+.11M 2.3+.09M 2.I+.07M 2.2+.16M 2.~.IOM 2.1+.07M 2.~.05M 2.1+.04M
147
4.1-21
TABLE 22
SUMMARY OF EXECUTION TIMES FOR ~IE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
COMPLEX GENERAL MATRICES
MACHINE: CDC 6600, FTN 4.3+P393 Compiler, OPT=I NASA LANGLEY RESEARCH CENTER
SUBROUTINE
Time Unit (Sec)
CBAL CBABK2
COMHES COMBAK
CORTH CORTB
COMQR2 COMLR2
COMQR COF~R
CINVIT
ORDER OF MATRIX
N=I0 N=20 N=40 N=60
°009 .063 .54 1.8
.24 . i0 .04 .03
• 12 . 04 .01 .01
I 1 1 1 °47 .60 .62 .64
1.8 1.6 1.6 1.6 .88 .90 .84 .79
16 15 13 13 9.9 8.0 6.9 7.0
7.4 5.9 4.5 4.3 5.5 3.9 2.8 2.8
3.8 2.8 2.2 2.1
PATHS
CG (CBAL,CORTH,COMQR2,CBABK2)
CG (CBAL,CORTH,COMQR)
CBAL,CORTH,COMQR,CINVIT, CORTB,CBABK2
18 17 14 14
9.5 7.6 6.2 5.9
9.4+.48M 7.6+.19M 6.2+.08M 5.9+.05M
148
4.1-22
TABLE 23
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
REAL GENERAL MATRICES
MACHINE: CDC 6600, FTN 4.3+P393 Compiler, OPT=I NASA LANGLEY RESEARCH CENTER
SUBROUTINE
Time Unit (Sec)
BALANC BALBAK
ELMHES ELTRAN ELMBAK
ORTHE S ORTRAN ORTBAK
HQR2
HQR
INVIT
ORDER OF MATRIX
N--10 N=20 N=40 N=60
.006 .032 .24 .77
.27 .17 .07 .05 - .05 • 03 .02
1 1 1 1 • 18 ° 06 . 04 . 02 .55 .58 .61 .61
1.8 2.0 2.2 2.2 .91 .73 .85 .82
i.I 1.3 1.3 1.3
13 14 14 12
6.9 6.7 6.2 4.8
3.6 3.3 3.1 2.9
PATHS
RG (BALANC,ELMHES,ELTRAN, HQR2,BALBAK)
RG (BALANC,ELMHES,HQR)
BALANC, E LMHE S, HQR, INVIT, ELMBAK, BALBAK
14 15 15 13
8.5 7.7 7.2 5.9
8.2+.41M 7.9+.20M 7.2+.09M 5.8+.06M
149
4.1-23
TABLE 24
SVMMARY OF EXECUTION TIMES FOR THE EiSPACK SUBROUTINES INCLUDED IN THE PATHS THAT
REDUCE FULL MATRICES TO HEAL SYMMETRIC TRIDIAGONAL FORM
MACHINE: CDC 6600, FTN 4.3+P393 Compiler, OPT=I NASA LANGLEY RESEARCH CENTER
SUBROUTINE
ORDER OF MATRIX N=I0 N=20 N=40 N=60
Time Unit (Sec)
TREDI TRED2 TRED3 TRBAKI TRBAK3
.006 ,030 .19 .58
1 1 i 1 1.6 1.8 2.0 2.0 1.2 1.5 1.7 1.8 1.2 1.4 1.6 1.7 1.2 1.5 1.8 1.7
HTRIDI HTRID3 HTRIBK HTRIB3
FIGI FIGI2 BAKVEC
1.7 2.1 2.4 2.5 1.8 2.3 2.6 2.6 1.9 2.7 3.2 3.5 1.9 2.7 3.2 3.2
.03 .01 .00
.07 .02 ,01
.05 .04 .02
TQL2 IMTQL2
TQLRAT TQLI IMTQLI
BISECT TRIDIB iMTQLV RATQR
TINVIT TSTURM
3.6 3.8 4.! 4.1 3.8 4.0 4.4 4.7
1.0 .58 .32 .25 1.5 .95 .55 .42 1.6 i.I .68 .51
15 9.2 5.5 3.9 14 9.1 5.5 3.9 1.5 1.2 .74 .53 3.6 2.8 2.0 1.5
.91 .67 .44 .32 15 9.7 5.8 4.3
PATHS
RS (TREDZ,TQL2) RS (TREDI,TQLRAT) TREDI,BISECT~TINVIT,TRBAKI
TREDI,BISECT
CH (HTRIDi,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,TINVIT,HTRIBK HTRIDI~BISECT
5.5 5.8 6.1 6.1 2.0 1.6 1.4 1.2 I+I.7M I+.56M I+.IgM I+.IOM I+I.5M ~.46M I+.I4M I+.06M
7.2 8.8 9.9 i0 2.6 2.7 2.7 2.6
1.7+1.7M 2.1+.63M 2,4+.23M 2.5+.13M I. 7+1.5M 2. I+. 46M 2.4+. 14M 2.5+. 06M
150
4.1-24
TABLE 25
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
COMPLEX GENERAL MATRICES
MACHINE: CDC 7600, Local Compiler NATIONAL CENTER FOR ATMOSPHERIC RESEARCH
SUBROUTINE
Time Unit (Sec)
CBAL CBABK2
COMHES COMBAK
CORTH CORTB
COMQR2 COMLR2
COMQR COMLR
CINVlT
ORDER OF MATRIX
N=I0 N--20 N=40 N=60 N=80
.002 .015 .ii .38 .89
- . i0 .05 .03 .02 - .05 .01 .01 .01
1 I i 1 1 i .57 .60 .61 .62
2 2.3 2.3 2.3 2.3 1 i.i i.i I.i i.i
15 15 13 13 13 i0 8.1 6.9 6.7 6.4
7 5.8 4.7 4.4 4.3 6 3.9 2.8 2.5 2.3
4 3.0 2.3 2.2 2.1
PATHS
CG (CBAL,CORTH,COMQR2,CBABK2)
CG (CBAL,CORTH,COMQR)
CBAL,CORTH,COMQR,CINVIT, CORTB,CBABK2
18
9
9+. 5M
17 16 15 15
8.0 7.1 6.7 6.6
8.2+. 21M 7. i+. 09M 6.8+. 05M 6.6+. 04M
151
4.1-25
TABLE 26
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
REAl, GENERAL MATRICES
MACHINE: CDC 7600, Local Compiler NATIONAL CENTER FOR ATMOSPHERIC RESEARCH
SUBROUTINE
Time Unit (Sec)
BALANC BALBAK
ELMHES ELTRAN ELMBAK
ORTHES ORTRAN ORTBAK
HQR2
HQR
INVIT
ORDER OF MATRIX
N=I0 N=20 N=40 N=60 N=80
• 001 .007 .050 .16 .38
- - .07 .05 .04 - - .02 .01 .01
1 i 1 1 i - - . 0 4 . 0 2 . 0 2
I .55 .60 .60 ,60
2 2.4 2.5 2.5 2.5 1 .81 .78 .78 .77 1 1.3 1.2 1.2 1,2
18 16 15 14 14
i0 7.4 5.8 5.2 4.8
4 3.4 3.0 2.8 2.7
PATHS
RG (BALANC, ELMHES, ELTRAN, HQR2, BALBAK)
RG (BALANC, ELMHES ,HQR)
BALANC~ELMHES,HQR, INVIT, ELMBAK~BALBAK
20
ii
II+.5M
17 16 15 15
8.6 6.9 6.3 5.8
8.4+.20M 6.9+.09M 6.3+.06M 5.8+.04M
152
4.1-26
TABLE 27
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT
REDUCE FULL MATRICES TO REAL SYMMETRIC TRIDIAGONAL FORM
MACHINE: CDC 7600, Local Compiler NATIONAL CENTER FOR ATMOSPHERIC RESEARCH
SUBROUTINE
Time Unit (Sec)
TREDI TRED 2 TRED3 TRBAKI TRBAK3
ORDER OF MATRIX N = I0 N=20 N=40 N=60 N=80
.001 .007 .040 .12 .28
i 1 i I 1 2 1.7 1.9 2.0 2.0 2 1.8 2.8 3.2 3.4 I 1.3 1.5 1.5 1.6 2 1.6 2.7 3.0 3.2
HTRIDI HTRID3 HTRIBK HTRIB3
2 2.1 2.4 2.6 2.6 2 2.2 2.5 2.6 2.7 2 2.5 3.1 3.3 3.4 2 2.6 3.2 3.4 3.5
FIGI FIGI2 BAKVEC
TQL2 IMTQL2
TQLRAT TQLI IMTQLI
BISECT TRIDIB IMTQLV RATQR
TINVIT TSTURM
- .01 .00 .02 .01 .01 .03 .02 .01
3 3.4 3.6 3.6 3.5 4 3.5 3.8 3.8 3.8
1 .69 .40 .28 .21 2 1.0 .65 .46 .36 2 1.2 .77 .55 .43
18 II 7.0 5.0 3.9 17 Ii 6.6 4.7 3.6 2 1.3 .82 .58 .45 3 2.7 1.9 1.5 1.2
1 .62 .42 .32 .33 18 ii 7.2 5.2 4.1
PATHS
RS (TRED2,TQL2) RS (TREDI,TQLRAT) TREDI~BISECT,TINVIT,TRBAKI TREDI,BISECT
CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI, TQLRAT) HTRIDI~BISECT,TINVIT,HTRIBK
HTRIDI~BISECT
5 5.1 5.5 5.6 5.5 2 1.6 1.4 1.3- 1.2
1+2.0M i+. 65M i+. 22M i+. 11M i+. 07M i+i. 8M i+. 56M i+. 17M I+. 08M i+. 05N
8 4
2+2. IM 2+i .8M
7.9 9.1 9.4 9.6 2.8 2.8 2.8 2.8
2.1+.71M 2.4+.26M 2.6+.14M 2.6+,09M 2.1+.56M 2.4+.17M 2.6+.08M 2.6+.05M
153
4.1-27
TABLE 28
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
COMPLEX GENERAL MATRICES
MACHINE: CDC 6400, FTN 3.0 Compiler, OPT=2 NORTHWESTERN UNIVERSITY
SUBROUTINE
Time Unit (Sec)
CBAL CBABK2
COMHES COMBAK
CORTH CORTB
COMQR2 COMLR2
COMQR COMLR
CINVIT
ORDER OF MATRIX
N=I0 N=20 N=40 N=60
.036 .29 2.2 7.5
o 19 .07 ~03 .02 .08 .03 .01 .01
i 1 1 1 .51 .54 .57 .58
2.5 2.4 2.4 2.4 1.2 1.2 1.2 1.2
18 16 15 14 9.7 7.9 6.5 6.5
8~.3 6.2 5.2 4.9 5.3 3.5 2.5 2.3
4.1 2.8 2.2 2.0
PATHS
CG (CBAL,CORTH,COMQR2,CBABK2)
CG (CBAL,CORTH,COMQR)
CBAL,CORTH,COMQR,CINVIT, CORTB,CBABK2
21 19 17 17
ii 8.7 7.6 7.3
II+.54M 8.7+.20M 7.6+.09M 7.3+.05M
154
4.1-28
TABLE 29
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCL~ED IN THE PATHS FOR
REAL GENERAL MATRICES
MACHINE: CDC 6400, FTN 3.0 Compiler, OPT=2 NORTHWESTERN UNIVERSITY
SUBROUTINE
Time Unit (Sec)
BALANC BALBAK
ELMHES ELTRAN ELMBAK
ORTHES ORTRAN ORTBAK
HQR2
HQR
INVIT
ORDER OF MATRIX
N=IO N=20 N=40 N=60 N=80
.016 .ii .83 2.7 6.3
.31 .14 .06 .04 .03 • 15 .05 .02 .01 .01
1 1 1 1 1 • 15 .06 .03 .02 .01
• 53 .54 .57 .57 .58
2.7 2.8 2.9 3.0 3.0 .83 .77 .77 .77 .77
1.3 1.2 1.2 1.2 1.2
17 15 14 13 13
i0 7.2 5.6 5.1 4.7
4.2 3.2 2.8 2.6 2.5
PATHS
RG (BALANC, EI~MHES, ELTRAN, HQR2, BALBAK)
RG (BALANC,ELMHES ,HQR)
BALANC, ELMHES, HQR, INVIT, ELMBAK, BALBAK
19
Ii
114-. 48M
16 15 14 14
8.3 6.7 6.1 5.7
8 . 3+. I£M 6.7+. 08M 6. I+. 05M 5.7+. 04M
155
4.1-29
TABLE 30
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT
REDUCE FULL MATRICES TO REAL SYMMETRIC TRIDIAGONAL FORM
MACHINE: CDC 6400, FTN 3.0 Compiler, OPT=2 NORTHWESTERN UNIVERSITY
SUBROUTINE
Time Unit (Sec)
TRED 1 TRED2 TILED3 TRBAKI TRBAK3
ORDER OF MATRIX N=I0 N=20 N=40 N=60 N=80
• 019 .ii .69 2.1 4.9
I 1 i i 1 1.7 1.8 1.9 2.0 2.0 1.2 1.3 1.5 1.6 1.6 I.i 1.3 1.5 1.5 1.5 I.i 1.3 1.5 1.6 1.7
HTRIDI HTRID3 HTRIBK HTRIB3
2.4 2.7 3.0 3.1 3.2 2.4 2.7 2.9 3.0 3.1 2.6 3.4 4.0 4.3 4.5 2.6 3.4 4.0 4.2 4.4
FiGI FIGI2 BAKVEC
.07 .03 .01 .00 .00
.12 .05 .02 .01 °01
.ii °06 °03 .02 .02
TQL2 !MTQL2
TQLRAT TQLI !MTQLI
BISECT TRIDIB IMTQLV RATQR
TINVIT TSTURM
4.2 4.5 4.7 4.7 4.7 4.4 4.7 4.9 4.9 4.9
I.i °66 .36 .24 .19 1.7 1o2 ~68 .48 .37 2.0 1.3 .77 .54 .41
9.8 6.2 3.5 2.5 1.9 i0 6°2 3.6 2.5 1.9 2.0 1.3 °79 .56 .43 3.1 2.4 1.6 1.2 .97
.94 .61 .37 .28 .31 II 6.7 3.9 2.8 2.2
PATHS
RS (TRED2,TQL2) RS (TREDI,TQLRAT) TREDI,BISECT,TINVIT,TRBAKI TREDI,BISECT
CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI~BISECT,TiNVIT~HTRIBK HTRIDI~BISECT
5.9 6.3 6.6 6.7 6.7 2.1 1.7 1.4 1.2 1.2 i+i .2M i+. 40M I+. 13M I+.07M I+.05M I+. 98M i+. 31M i+. 09M i+. 04M i+. 02M
9.2 i0 ii 12 12 3.5 3.4 3.4 3.4 3.4
2o4+1.3M 2.7+.51M 3.0+.20M 3.1+.12M 3.2+.08M 2.4+.98M 2.7+.31M 3.0+.09M 3.1+.04M 3.2+°02M
156
4.1-30
TABLE 31
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
COMPLEX GENERAL MATRICES
MACHINE: CDC 6400/6500, FUN Compiler PURDUE UNIVERSITY
SUBROUTINE
Time Unit (Sec)
CBAL CBABK2
COMHES COMBAK
CORTH CORTB
COMQR2 COMLR2
COMQR COMLR
CINVIT
ORDER OF MATRIX
N=IO N=20 N=40 N=60 N=80
.045 .35 2.7 9.2 22
• 13 .05 .02 .01 °01
• 07 .03 .01 .01 .01
1 1 i 1 1 • 58 .62 .64 • 65 .66
2.7 2.7 2.7 2.7 2.7 1.4 1.3 1.3 1.3 1.3
20 18 16 16 16 ii 8.7 7.4 7.1 6.7
9.5 7.4 6.4 6.2 5.8 5.7 3.8 2.7 2.4 2.2
3.9 2.9 2.4 2.2 2.2
PATHS
CG (CBAL, CORTH,COMQR2,CBABK2)
CG (CBAL,CORTH,COMQR)
CBAL,CORTH,COMQR,CINVlT, CORTB,CBABK2
23
12
12+.54M
20
i0
IO+.21M
19 19 18
9.1 8.9 8.5
9. I+.09M 8.9+.06M 8.5+.04M
157
4.1-31
TABLE 32
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
REAL GENERAL MATR!CES
MACHINE: CDC 6400/6500, FUN Compiler PUF~UE UNIVERSITY
SUBROUTINE
Time Unit (Sec)
BALANC BALBAK
EL~ES ELTRAN EL~b~K
ORTHES ORTRAN ORTBAK
HQR2
HQR
INVIT
ORDER OF MATRIX
N=I0 N=20 N=40 N=60 N=80
.018 .12 .90 3.0 6.9
• 25 • I0 .05 .03 .02 • 14 .06 .03 .02 .01
i I 1 i 1 17 .07 ,03 ,02 .02
.55 .60 .61 .62 ,63
2.6 2.7 2.7 2,8 2.8 .91 .83 .81 .81 ,81
1.4 1.3 1.3 1.3 1.2
33 31 30 30 29
18 14 12 II !0
5.1 4.9 4.6 4.6 4.6
PATHS
RG (BALANC,ELMIIES,ELTRAN, HQR2,BALBAK)
RG (BALANC,ELMHES,HQR)
BALANC,ELMHES,HQR, INViT, ELMBAK, BALBAK
35 32 31 31 30
19 15 13 12 ii
19+.58M 15+.28M 13+.13M 12+.09M II+.06M
158
4.1-32
TABLE 33
SLrMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT
REDUCE FULL MATRICES TO REAL SY~METRIC TRIDIAGONAL FORM
MACHINE: CDC 6400/6500, FUN Compiler PURDUE UNIVERSITY
SUBROUTINE
Time Unit (Sec)
TRED I TRED2 TRED3 TRBAKI TRBAK3
ORDER OF MATRIX N= i0 N=20 N=40 N=60 N=80
.024 .13 .81 2.5 5.6
1 1 I I I 1.7 1.8 1.9 2.0 2.0 .92 I.i 1.2 1.2 1.2
I.I 1.3 1.5 1.6 1.6 i.i 1.4 1.6 1.7 1.7
HTRIDI HTRID3 HTRIBK HTRIB3
2.4 2.8 3.2 3.4 3.5 2.6 3.1 3.5 3.7 3.9 2.8 3.7 4,5 4.9 5.1 3.0 4.0 4.9 5.3 5.5
FIGI FIGI2 BAKVEC
TQL2 IMTQL2
TQLRAT TQLI IMTQLI
BISECT TRIDIB IMTQLV RATQR
TINViT TSTIYRM
• 06 .02 . Ol . 00 . O0
. Ii .05 .02 .01 .01
.09 .05 .03 .02 .02
3.8 4.2 4.4 4.6 4,6 4.0 4.2 4.5 4.5 4.6
• 83 .51 .28 .19 .15 1.4 .92 .56 .39 .30 1.5 1.0 .62 .44 .34
9.4 6.1 3.6 2.5 2.0 9ol 5.9 3.5 2.5 1.9 1.7 i.I .70 .50 .39 2.9 2,3 1,6 1.2 .98
.97 .68 .43 .33 .37 i0 6.7 4.0 2.9 2.3
PATHS
RS (TRED2,TQL2) RS (TREDI,TQLRAT) TREDI,BISECT,TINVIT,TRBAKI TREDI,BISECT
CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,IQLRAT) HTRIDI,BISECT,TINVIT,HTRIBK HTRIDI~BISECT
5.4 6,0 6.4 6.6 6.6 1.9 1.5 1,3 1.2 I.i
i+i. 2M i+. 40M I+. 14M i+. 07M i+. 05M i+. 94M i+. 30M i+. 09M I+. 04M i+. 02M
9.0 i0 12 13 13 3.3 3.3 3.5 3.6 3.6
2.4+1.3M 2.8+.52M 3.2+.21M 3.4+.13M 3.5+.09M 2.4+.94M 2,8+.30M 3.2+.09M 3,4+.04M 3.5+.02M
159
4.1-33
TABLE 34
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
COMPLEX GENERAL MATRICES
MACHINE: CDC 6600/6400, RUN Compiler THE UNIVERSITY OF TEXAS
SUBROUTINE
Time Unit (See)
CBAL CBABK2
COlliES COMBAK
CORTH CORTB
COMQR2 COMLR2
COMQR COMLR
CINVIT
ORDER OF MATRIX
N=I0 N=20 N=40
.015 .084 .69
- ~17 .05 - - .02
1 I i - .64 .64
2.1 3.0 2.9 I.i 1.4 1.3
17 19 17 9.5 9.8 7.8
8.9 8.9 7.4 5.5 4.6 3.1
4.2 3.9 2.9
PATHS
CG (CBAL,CORTR,COMQR2,CBABK2)
CG (CBAL,CORTH,CO~R)
CBAL,CORTH,COMQR, CINVIT, CORTB~CBABK2
19 22 20
12 12 i0
19+.53M 12+.26M 10+.IIM
160
4.1-34
TABLE 35
SITMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
REAL GENERAL MATRICES
MACHINE: CDC 6600/6400, RUN Compiler THE UNIVERSITY OF TEXAS
SUBROUTINE
Time Unit (Sec)
BALANC BALBAK
ELMHES ELTRAN ELMBAK
ORTHES ORTRAN ORTBAK
HQR2
HQR
INVIT
ORDER OF MATRIX
N=20 N=40 N=60
.045 .24 .78
- .06 .06 - - .02
i 1 1 - - .04 .36 .73 .70
2.5 3.5 3.5 .73 .79 .77 .71 1.3 1.2
28 45 36
12 18 13
4.7 6.0 6.2
PATHS
RG (BALANC, ELMHES, ELTRAN, HQR2, BALBAK)
RG (BALANC, ELMHES, HQR)
B~C, EI~IHE S, HQR, INVIT, ELMBAK, BALBAK
N = 8 0
1.8
.05
.02
1 .03 .73
3.6 .77
1.2
36
13
6.4
29 46 37 37
13 19 14 14
13+.25M 19+.17M 14+.12M 14+.09M
161
4.1-35
TABLE 36
SUMMARY OF EXECUTION TIMES FOR THE EiSPACK SUBROUTINES ~CLUDED IN THE PATHS THAT
REDUCE FULL MATRICES TO HEAL SYMMETRIC TRIDIAGONAL FORM
MACHINE: CDC 6600/6400, RUN Compiler THE UNIVERSITY OF TEXAS
SUBROUTINE ORDER OF MATRIX
N=20 N=40 N=60 N=80
Time Unit (Sec)
TRED i TRED2 TRED3 TRBAKI TRBA-K3
HTRIDI HTRID3 HTRIBK HTRIB3
°033 .21 .63 1.4
1 1 i 1 1.9 2.1 2.1 2.1 1.8 1.6 1.7 1.7 1.7 1.8 1.8 1.9 2.0 2.1 2.2 2.3
2.9 3.1 3.3 3.4 3.5 3.5 3.7 3.9 3.7 4.5 4.8 5.1 4.2 4.9 5.3 5.6
FIGi FiGI2 BAKVEC
TQL2 IMTQL2
TQLRAT TQLI IMTQL 1
BISECT TRIDIB IMTQLV RATQR
TINVIT TSTURM
- - .02 °02
- - - ~02
4.4 4.3 4.2 4.2 4.6 4.8 4.8 4.5
.90 .39 .29 .21 1.2 .84 .60 °44 1.7 .92 .70 .53
12 6.8 4.9 3.8 12 6.8 4.8 3.8 2.3 I.I °79 .59 3.6 2.5 1.9 1.5
i.i .64 .51 .47 13 7.6 5.5 4.3
PATHS
RS (TRED2,TQL2) RS (TREDI, TQLRAT) TREDIgBISECT~TINV!T,T~AKI TREDI,BISECT
CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,T!NVlT,HTRIBK HTRIDI,BISECT
6.5 6.3 6.3 6.3 2.0 1.5 1.3 1.2
i+. 73M i+. 23M I+. 12M l+. 08M i+. 59M i+. 17M i+. 08M i+. 05M
Ii 12 12 13 3.8 3.6 3.5 3.6
2.9+.83M 3.1+.30M 3.3+.17M 3.4+.12M 2.9+.59M 3.1+.17M 3.3+.08M 3.4+.05M
162
4.1-36
TABLE 37
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
COMPLEX GENERAL MATRICES
MACHINE: Honeywell 6070 Fortran-Y(SR-F) Optimized BELL LABORATORIES
SUBROUTINE
Time Unit (Sec)
CBAL CBABK2
COMHES COMBAK
CORTH CORTB
COMQR2 COMLR2
COMQR COMLR
CINVIT
ORDER OF MATRIX
N=I0 N=20 N=40 N=60 N=80
.041 .31 2.5 8.6 20
.16 .07 .03 .'02 .02
.07 .03 .01 .01 .01
i i i 1 1 .46 .54 .56 .55 .55
2.4 2.5 2.6 2.5 2.5 I.i i.i 1.2 I.i i.I
14 13 ii U ii 8.2 6.7 5.7 5.7 5.4
6.2 4.7 3.7 3.5 3.4 4.5 2.9 2.1 2.0 1.8
4.3 3.1 2.4 2,3 2.2
PATHS
CG (CBAL,CORTH,COMQR2,CBABK2)
CG (CBAL,CORTH,COMQR)
CBAL,CORTH,COMQR, CINVIT, CORTB,CBABK2
17 15 14 14 13
8.8 7.3 6.3 6.0 6.0
8.7+.54M 7.3+.22M 6.3+.09M 6.1+.06M 5.9+.04M
163
4.1-37
TABLE 38
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
REAL GENERAL MATRICES
MACHINE: Honeywell 6070 Fortran-Y(SR-F) Optimized BELL LABORATORIES
SUBROUTINE
Time Unit (Sac)
BALANC BALBAK
ELMHES ELTRAN ELMBAK
0RTHES ORTRAN ORTBAK
HQR2
HQR
INVlT
ORDER OF MATRIX
N=I0 N=20 N=40 N=60 N=80
.009 .070 .54 1.8 4.3
.32 .12 .06 .04 .03
. 15 .06 °03 .02 .01
i 1 1 i i . 16 .07 .03 .02 .01
~52 .54 .56 .56 .56
2.9 3.0 3.1 3.1 3.1 .86 .81 .80 .79 .79
1.2 1.2 1.2 1.2 I~2
15 12 I i i0 i0
8.6 6.1 4.3 3.9 3.5
4.6 3.6 3.0 2.7 2.6
PATHS
RG (BALANC, ELMI~ S, ELTRAN, HQR2, BALBAK)
RG (BALANC,ELMHES ,HQR)
BALANC, ELMHES, HQR, INVIT, ELMBAK ~ BALBAK
16 14 12 ii II
i0 7.2 5.4 5.0 4.5
I0+.53M 7.2+.21M 5.4+.09M 5.0+.05M 4.5+.04M
4.1-38
TABLE 39
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT
REDUCE FULL MATRICES TO HEAL SYMMETRIC TRIDIAGONAL FORM
MACHINE: Honeywell 6070 Fortran-Y(SR-F) Optimized BELL LABORATORIES
SUBROUTINE ORDER OF MATRIX
N=IO N=20 N=40 N=60 N=80
Time Unit (Sec) .013 .078 .53 1.6 3.6
TREDI TRED2 TRED3 TRBAKI TRBAK3
1 1 1 1 1 1.4 1.8 1.9 2.0 2.0 I.i 1.2 1.2 1.2 1.3 .87 i.i 1.3 1.4 1.4
1.0 1.3 1.5 1.6 1.6
HTRIDI HTRID3 HTRIBK HTRIB3
2.6 3.0 3.3 3.4 3.5 2.7 3.1 3.5 3.6 3.7 2.9 3.8 4.5 4.7 4.9 2.9 3.8 4.5 4.8 4.9
FIGI FIGI2 BAKVEC
.i0 .03 .01 .00 .00
.14 .05 .02 .01 .01
.12 .06 .03 .02 .02
TQL2 IMTQL2
4.1 4.4 4.2 4.3 4.2 4.2 4.6 4.6 4.6 4.6
TQLRAT TQLI IMTQLI
I.i .60 .29 .21 .15 1.7 i.I .59 .42 .32 1.8 1.2 .65 .46 .34
BISECT TRIDIB IMTQLV RATQR
5.2 3.1 1.6 i.i .84 5.3 3.2 1.6 I.i .81 1.9 i.i .65 .45 .35 3.0 2.1 1.4 1.0 .82
TINVIT TSTURM
1.0 .67 .39 .31 .33 6.2 3.9 2.0 1.4 1.2
PATHS
RS (TRED2,TQL2) RS (TREDI,TQLRAT) TREDI,BISECT,TINVIT,TRBAKI TREDI,BISECT
5.5 6.4 6.0 6.4 6.2 2.0 1.6 1.3 1.2 i.i
i+. 7 IM i+. 24M i+. 08M I+. 05M i+. 03M I+. 52M i+. 15M i+. 04M i+. 02M i+. OIM
CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,TINVIT,HTRIBK HTRIDI,BISECT
9.9 ii 12 12 13 3.7 3.6 3.6 3.6 3.6
2.6+.91M 3.0+.38M 3.3+.16M 3.4+.IOM 3.5+.08M 2.6+.52M 3.Ot.15M 3.3+.04M 3.4+.02M 3.5+.01M
165
4.1-39
TABLE 40
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
COMPLEX GENERAL MATRICES
MACHINE: Univac iii0, Fortran V(9) Compiler THE UNIVERSITY OF WISCONSIN
SUBROUTINE
Time Unit (Sec)
CBAL CBABK2
COMHES COMBAK
CORTH CORTB
COMQR2 COMLR2
COMQR COMLR
CINVIT
ORDER OF MATRIX
N=I0 N=20 N=40 N=60 N=80
°025 .18 1.3 4.4 I0
. 16 .08 .04 .02 .02
.08 .03 .01 .01 ~01
1 1 1 1 1 .48 .53 .57 .58 °58
2.3 2.6 2.8 2.8 2.9 1.0 I.i i.i 1.2 1.2
13 12 ii ii II 9.4 7.5 6.3 6.3 6.1
6.2 4.8 3.9 3.9 3.6 5.5 3.6 2.5 2.4 2.2
4.7 3.4 2.7 2.4 2,3
PATHS
CG (CBAL,CORTH, COMQR2,CBABK2)
CG (CBAL,CORTH,COMQR)
CBAL,CORTH,COMQR,CINVIT, CORTB~CBABK2
16 15 14 14 14
8.7 7.4 6.7 6.7 6.5
8.7+.58M 7.4+.23M 6.7+.IOM 6.7+.06M 6.6+.04M
166
4.1-40
TABLE 41
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
REAL GENERAL MATRICES
MACHINE: Univac IIi0, Fortran V(9) Compiler THE UNIVERSITY OF WISCONSIN
SUBROUTINE
Time Unit (Sec)
BALANC BALBAK
ELMI{ES ELTRAN ELM~AK
ORTHES ORTRAN ORTBAK
HQR2
HQR
INVIT
ORDER OF MATRIX
N=I0 N=20 N=40 N=60 N=80
.009 .062 .45 1.5 3.4
.39 .17 .08 .05 .04
.Ii .05 .02 .02 .01
1 i 1 1 1 .16 .08 .03 .02 .02 .54 .57 .58 .59 .59
3.2 3.6 3.8 4.0 4.0 .72 .74 .76 .77 .78
1.1 1.1 1.2 1.2 1.2
15 13 Ii ii ii
8.5 6.3 4.7 4.3 3.9
5.6 4.6 4.0 3.8 3.7
PATHS
RG (BALANC, ELMHES, ELTRAN, HQR2, BALBAK)
RG (BALANC, ELMHES, HQR)
BALANC, ELMHES, HQR, INVIT, ELMBAK, BALBAK
L6 14 13 12 12
9.9 7.5 5.8 5.4 4.9
9.9+.63M 7.5+.26M 5.8+.12M 5.4+.07M 4.9+.05M
167
4.1-41
TABLE 42
S~RY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT
REDUCE FULL MATRICES TO REAL SYMMETRIC TRIDIAGONAL FORM
MACHINE: Un±vac Iii0, Fortran V(9) Compiler THE UNIVERSITY OF WISCONSIN
SUBROUTINE
ORDER OF MATRIX N=I0 N=20 N=40 N=60 N=80
Time Unit (Sec) .012 .065 .40 1.2 2.7
TRED 1 TRED2 TRED3 TRBAKI TRBAK3
! 1 i 1 1 1.5 1.7 1.9 1.9 2.0 1.3 1.7 2.0 2.2 2.3 .81 I.I 1.3 1.4 1.5
1.4 2.0 2.5 2.7 2.9
HTRIDI HTRID3 HTRIBK HTRIB3
2.3 2.5 2.7 2.9 2.9 2.1 2.4 2.7 2.8 2.9 2.2 3.0 3.8 4.1 4.3 2.2 3.1 3.8 4.1 4.3
FIGI FIGI2 BAKVEC
,08 .02 .01 ,00 .00 ,09 ,04 ,02 .01 .01 .08 °05 ,03 .02 .01
TQL2 IMTQL2
TQLRAT TQLI IMTQLI
BISECT TRIDIB IMTQLV RATQR
TINVIT TSTURM
3.4 3.8 4.0 4.1 4.2 3.6 4.0 4.4 4.4 4.3
.99 .63 .36 .26 .19 1.4 .96 .58 .41 .31 1.5 1.0 .64 .45 ,34
6.3 3.9 2.2 1.6 1.2 6.2 3.8 2.2 1.5 I.I 1.6 i. i .67 .47 .35 3.3 2.7 1.8 1.4 1.2
1.2 .82 .51 .39 .38 7.4 4.6 2.7 1.9 !.6
PATHS
RS (TRED2,TQL2) RS (TREDI,TQLRAT) TREDI,BISECT,TINVIT,TRBAKI
TREDI,BISECT
CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,TINVIT,HTRIBK HTRIDI,BISECT
4.9 5.5 5.8 6.0 6.2 2.0 1.6 1.4 1.2 1.2
I+. 83M i+. 29M i+. IOM i+. 06M i+. 04M I+. 63M i+. 19M i+. 06M I+. 03M i+. OIM
8.1 9.3 Ii Ii Ii 3.3 3.1 3.1 3.1 3.1
2.3+.97M 2.5+.39M 2.7+.16M 2.9+.IOM 2.9+,07M 2.3+.63M 2.5+,19M 2.7+.06M 2.9+.03M 2.9+.01M
168
4.1-42
TABLE 43
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
COMPLEX GENERAL MATRICES
MACHINE: DEC PDP-10, F40 Compiler YALE UNIVERSITY
SUBROUTINE
Time Unit (Sec)
CBAL CBABK2
COMHES COMBAK
CORTH CORTB
COMQR2 COMLR2
COMQR COMLR
CINVlT
ORDER OF MATRIX
N=I0 N=20 N=30 N=40
.29 2.4 8.3 20
.16 .07 .05 .04
.05 .03 .01 .01
i 1 i 1 • 57 .57 .58 .59
2.0 1.9 2.0 2.0 I.I I.i I.I i.i
13 ii ii ii 8.8 7.6 7.2 6.7
5.1 3.7 3.4 3.2 4.3 3.1 2.6 2.3
3.4 2.7 2.6 2.5
PATHS
CG (CBAL,CORTH,COMQR2,CBABK2)
CG (CBAL,CORTH,COMQR)
CBAL,CORTH,COMQR,CINVIT, CORTB,CBABK2
15 13 13 13
7.2 5.7 5.4 5.2
7.2+.46M 5.7+.19M 5.4+.12M 5.2+.09M
169
4.1-43
TABLE 44
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
REAL GENERAL MATRICES
MACHINE: DEC PDP-10, F40 Compiler YALE UNIVERSITY
SUBROUTINE
Time Unit (Sec)
BALA_NC BALBAK
ELegIES ELTRAN EI/iBAK
ORTHES ORTRAN ORTBAK
HQR2
HQR
INVIT
ORDER OF MATRIX
N=I0 N=20 N=30 N=40
.i0 .80 2.7 6°2
~27 . 12 ,08 .06 .12 °04 .03 .02
I I 1 i ,21 .08 ,06 .04 °54 ,58 ,59 .59
1.8 1.9 1.9 1.9 .75 .73 .73 .72
i.i i.i i.i I.i
12 ii 9.9 9.7
6.7 5.0 4.1 3.8
3.5 2.9 2.7 2.6
PATHS
RG (BALANC~ELMHES~ELTRAN, HQR2,BALBAK)
RG (BALANC,ELMHES,HQR)
BALANC, ELMIIE S, HQR, INVIT, EI2LBAK, BALBAK
14 12 ii II
7.9 6.2 5.2 4.9
8.0+.42M 6.2+.17M 5.2+.IIM 4.9+.08M
170
4.1-44
TABLE 45
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT
REDUCE FULL MATRICES TO REAL SYMMETRIC TRIDIAGONAL FORM
MACHINE: DEC PDP-10, F40 Compiler YALE UNIVERSITY
SUBROUTINE
Time Unit (Sec)
TREDI TRED2 TRED3 TRBAKI TRBAK3
N=I0 ORDER OF MATRIX
N=20 N=30 N=40
.i0 .64 2.0 4.7
1 1 i 1 1.8 2.0 2.0 2.1 .85 .87 .88 .88
1.2 1.5 1.6 1.7 i.i 1.4 1.5 1.5
HTRIDI HTRID3 HTRIBK HTRIB3
3.2 3.6 3.7 3.8 2.6 3.1 3.2 3.3 4.4 5.5 5.9 6.2 4.4 5.5 5.9 6.2
FIGi FIGI2 BAKVEC
TQL2 IMTQL2
TQLRAT TQLI IMTQLI
BISECT TRIDIB IMTQLV RATQR
TINVIT TSTURM
PATHS
.09 .01 .01 .01
.09 .05 .03 .02
.12 .07 .04 .03
3.7 4.2 4.1 4.0 3.9 4.5 4.2 4.3
.73 .42 .26 .20 1.0 .65 .42 .33 i.i .75 .48 .39
3.9 2.1 1.4 1.0 3.9 2.1 1.3 .99 1.2 .79 .51 .41 2.1 1.4 i.i .87
1.2 .70 .50 .39 5.0 2.8 1.8 1.4
RS (TRED2,TQL2) RS (TREDI,TQLRAT) TREDI,BISECT~TINVIT,TRBAKI TREDI~BISECT
CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI~BISECT~TINVIT~HTRIBK HTRIDI,BISECT
5.5 6.2 6.2 6.1 1.8 1.4 1.3 1.2
i+. 62M I+. 22M i+. 12M i+. 08M i+. 39M 1+. IOM I+. 05M i+. 03M
12 13 14 14 3.9 4.0 4.0 4.0
3.2+.94M 3.6+.41M 3.7+.26M 3.8+.19M 3.2+.39M 3.6+.IOM 3.7+.05M 3.8+.03M
171
4.1-45
TABLE 46
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
COMPLEX GENERAL MATRICES
MACHINE: Amdahl 470V/6, Fortran H, OPT=2 UNIVERSITY OF MICHIGAN
SUBROUTINE
Time Unit (Sec)
CBAL CBABK2
COMHES COMBAK
CORTH CORTB
COMQR2 COMLR2
COMQR COMLR
CINVIT
ORDER OF MATRIX
N=I0 N=20 N=40 N=60 N=80
.005 .040 .33 i. 1 2.8
.12 .05 .02 .01 .01
.07 .03 .02 .01 .01
1 1 i I i .46 .50 .54 .58 .60
2.4 2.3 2.2 2.2 2.1 1.3 1.3 1.2 1.2 i.i
18 15 13 13 12 9.4 8.1 6.7 6.5 6.2
8.0 5.7 4.5 4.2 3.9 5.1 3.4 2.4 2.2 2.0
4.8 3.3 2.5 2.2 2.3
PATHS
CG (CBAL,CORTH,COMQR2,CBABK2)
CG (CBAL,CORTH,COMQR)
CBAL,CORTH,COMQR,CINVIT, CORTB,CBABK2
20
ii
II+.62M
18 16 15 14
8.1 6.7 6.4 6.0
8.1+.23M 6.7+.09M 6.4+.06M 6.0+.04M
172
4.1-46
TABLE 47
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS FOR
REAL GENERAL MATRICES
MACHINE: Amdahl 470~/6, Fortran H, OPT=2 UNIVERSITY OF MICHIGAN
SUBROUTINE
Time Unit (Sec)
BALANC BALBAK
ELMHES ELTRAN ELMBAK
ORTHES ORTRAN ORTBAK
HQR2
HQR
INVlT
ORDER OF MATRIX
N=I0 N=20 N=40 N=60 N=80
.002 .014 .12 .41 .98
.24 .09 .04 .02 .02
.12 .05 .02 .02 .01
1 1 1 i I .16 .07 .03 .02 .02 .54 .57 .57 .58 .59
2.4 2.2 2.1 2.0 1.9 .81 .71 .65 .62 .60
1.2 I.i .98 .93 .90
20 16 12 12 II
12 7.7 5.2 4.5 3.9
4.5 3.4 2.7 2.4 2.3
PATHS
RG (BALANC, ELMHES, ELTRAN, HQR2, BALBAK)
RG (BALANC, ELMHES, HQR)
BALANC, ELMHES, HQR, INVIT, ELMBAK~ BALBAK
21
13
13+.51M
17 14 13 12
8.8 6.2 5.5 4.9
8.8+.20M 6.3+.08M 5.5+.05M 5.0+.04M
173
4.1-47
TABLE 48
SUMMARY OF EXECUTION TIMES FOR THE EISPACK SUBROUTINES INCLUDED IN THE PATHS THAT
REDUCE FULL MATRICES TO REAL SYMMETRIC TRIDIAGONAL FORM
MACHINE: Amdahl 470V/6, Fortran H, OPT=2 UNIVERSITY OF MICHIGAN
SUBROUTINE
Time Unit (Sec)
TREDI TRED2 TRED3 TRBAKI TRBAK3
N=IO ORDER OF MATRIX
N=20 N=40 N=60 N=80
.002 .013 .090 ,29 °70
i 1 i 1 i 1.6 1.8 2.0 2.0 2.0 .99 .98 1.0 .98 .96
1.2 1.4 1.6 1.6 1.6 1.0 1.2 1.4 1.4 1.4
HTRIDI HTRID3 HTRIBK HTRIB3
2.7 3.1 3.4 3.6 3.7 2.6 3.1 3.4 3.6 3.6 3.3 4.4 5.1 5.4 5.5 3.5 4.6 5.3 5.5 5.5
FIGI FiGI2 BAKVEC
TQL2 IMTQL2
TQLRAT TQLI IMTQLI
BISECT TRIDIB IMTQLV RATQR
TINVIT TSTURM
• 09 .03 .01 .00 .00 .15 ,06 .03 .02 .01 .I0 .06 .03 .02 .02
4.9 5.3 5.1 5.0 4.6 5.0 5.2 5.3 5.0 4.8
1.4 .81 .42 .27 . 19 2.3 1.5 .86 .57 .42 2.3 1.5 .88 .58 .43
ii 6.8 3.7 2.5 1.8 Ii 7.0 3.8 2.6 1.9 2.4 1.6 .89 .59 .43 3.4 2.6 1.7 1.2 .93
1.0 .67 .40 .29 .30 12 7.5 4.2 2.9 2.2
PATHS
RS (TRED2,TQL2) RS (TREDI,TQLRAT) TREDI,BISECT,TINVIT,TRBAKI TREDI,BISECT
CH (HTRIDI,TQL2,HTRIBK) CH (HTRIDI,TQLRAT) HTRIDI,BISECT,TINVIT,HTRIBK HTRIDI,BISECT
6.5 7.1 7.1 7.0 6.7 2.4 1.8 1.4 1.3 1.2 I+i. 3M I+. 44M I+. 14M i+. 07M I+. 05M I+ i. IM I+ . 34M I+. 09M i+. 04M I+ . 02M
ii 12 13 14 14 4.2 3.9 3.8 3.9 3.9
2.7+1.5M 3.1+.59M 3.4+.23M 3.6+.14M 3.7+.IOM 2.7+I.IM 3.1+.34M 3.4+.09M 3.6+.04M 3.7+.02M
174
4.1-48
TABLE 49
EXECUTION TIMES FOR SELECTED EISPACK DRIVER SUBROUTINES OVER VARIOUS COMPUTER SYSTEMS MEASVRED ON MATRICES OF ORDER 40
BOTH WITH EIGENVECTOR~ COMPUTED (I) AND WITHOUT (0)
MACHINE
Time Unit (Sec)
IBM 370/195 (ARGONNE NATIONAL LABORATORY)
IBM 360/75 (UNIVERSITY OF ILLINOIS)
IBM 370/168 (UNIVERSITY OF MICHIGAN)
IBM 370/165 (THE UNIVERSITY OF TORONTO)
CG(1) CG(O) RG(1) RG(O) RS(1) RS(O) CH(1)CH(~)
1.7 .77 .66 .31 .22 .055 .44 .14
i i 1 i 1 1 i 1
16 15 ii Ii 15 12 13 12
5.8 5.2 3.9 3.7 5.6 3.9 5.0 4.5
3.5 3.2 2.9 2.6 3.3 2.9 3.2 2.9
BURROUGHS 6700 118 108 95 92 125 82 122 i00 (UNIVERSITY OF CALIFORNIA,
SAN DIEGO) CDC 6600 5.0 5.3 4.9 4.9 5.5 5.0 3.7 3.0 (KIRTLAND AIR FORCE BASE)
CDC 6600 (NASA LANGLEY RESEARCH CENTER)
4.5 4.3 5.5 5.6 5.3 5.0 4.2 3.8
CDC 7600 i.i 1.0 1.2 I.i 1.0 I.i .81 .83 (NATIONAL CENTER FOR ATMOSPHERIC
RESEARCH) CDC 6400 22 22 19 18 21 18 17 17 (NORTHWESTERN UNIVERSITY)
CDC 6400/6500 (PURDUE UNIVERSITY)
CDC 6600/6400 (THE UNIVERSITY OF TEXAS)
HONEYWELL 6070 (BELL LABORATORIES)
UNIVAC III0 (THE UNIVERSITY OF WISCONSIN)
DEC PDP-IO (YALE UNIVERSITY)
AMDAHL 470V/6 (UNIVERSITY OF MICHIGAN)
31 32 42 38 24 20 22 21
8.2 8.9 17 15 6.1 5.9 5.6 5.6
21 20 9.9 9.4 15 13 14 14
Ii II 8.9 8.4 ii ii 9.8 9.2
155 135 104 98 132 106 146 139
3.1 2.9 2.4 2.3 2.9 2.4 2.7 2.6
175
PROBLEM CLASS
CG
CG
CG
CG
RG
RG
RG
RG
4.1-49
TABLE 50
SUMMARY OF EXECUTION TIMES FOR SELECTED PROBLEMS USING THE EISPAC CONTROL PROGRAM
MACHINE: IBM 370/195, Fortran H, OPT=2 ARGONNE NATIONAL LABORATORY
Time Unit: 1 second
EIGEN- EIGEN- TRANSFOR- VALUES VECTORS MATIONS
All All Unitary
All Some(M=N) Unitary
All All Elementary
All Some(M=N) Elementary
All All Elementary
All Some(M=N) Elementary
All All Orthogonal
All Some(M=N) Orthogonal
ORDER OF MATRIX
N=I0 N=20 N=40 N=60 N=80
RS All All
RS All None
RS Some(M=N) Some(M=N)
RS Some(M=N) None
.044 .25 1.7 5.7 13
.047 .22 1.3 4.2 9.6
.032 .16 1.0 3.3 7.6
.041 .17 ,92 2.7 6.7
CH All All
CH All None
CH Some(M=N) Some(M=N)
CH Some(M=N) None
.023 .i0 .63 2.0 4.5
.024 .095 .51 1.5 3.4
.026 .12 .72 2.3 5.2
,026 .i0 .59 1.8 4.0
,011 ,040 .22 .65 1.5
,007 .016 .059 .15 .33
,025 .080 .33 ,81 1.6
.022 .066 .24 .56 1.0
.016 .07 .44 1.4 3.4
.009 .026 .14 .42 1.0
.029 .ii .52 1.5 3.3
.023 .08 .33 .83 1.8
176
4.2-1
Section 4.2
REPEATABILITY AND RELIABILITY OF THE MEASURED EXECUTION TIMES
In the multi-program environment of modern computers, it is often
very difficult to reliably measure the execution time of a program. Sig-
nificant variations can occur depending on the load on the machine and
the amount of I/O interference. For the EISPACK subroutines in particular,
allowance has to be made also for the dependence of execution times upon
the matrix (see Section 4.3).
Towards improving the usefulness of the timing information for the
various machines, each subroutine was run a number of times on different
matrices and the average time reported. Also, the timing programs were
structured to perform no output until all the timings had been collected.
For the most part, the timing routines used to measure execution time
factor out external interrupts which may occur. The reported times, there-
fore, although not to be interpreted as absolute bounds, should be useful
in giving a feeling for the execution time required by the individual
subroutines or paths.
177
4.3-1
Section 4.3
DEPENDENCE OF THE EXECUTION TIMES UPON THE MATRIX
To characterize the dependence of the execution times of the EISPACK
subroutines upon the matrix, it is helpful to divide the subroutines into
three categories: first, the non-iterative reduction and back transforma-
tion subroutines; second, the iterative reduced-form eigenvalue-eigenvector
subroutines; and third, the semi-iterative subroutines which balance a
mmtrix and back transform the eigenvectors of the balanced matrix.
For the first category of subroutines, the execution times for all
non-sparse matrices of a given order are approximately constant, close to
those given in the tables of Section 4.1. For sparse matrices, some of
the reduction transformations may be skipped and the arithmetic unit may
consume less time to manipulate the many zero operands; however, except
for special sparse matrices, the decrease in execution time of these sub-
routines is marginal.
For the second category of subroutines, their execution times depend
greatly upon the structure of the input matrix (e.g., diagonally dominant,
blocked, sparse), the closeness of the eigenvalues, and the defectiveness
of the matrix. Based upon our experiments on the IBM 370/195, random
matrices tend to produce slower execution of category two subroutines, and
therefore the execution times given in the tables of Section 4.1 appear
to be near the maximum for these subroutines.
For the third category of subroutines, their execution times are
somewhat variable but, in general, are negligible compared with the execu-
tion times of paths in which they are included. For example, the algorithms
BALANC and BALBAK together require about 0.3% of the execution time in the
path BALANC-ELMHES-ELTRAN-HQR2-BALBAK used to find the complete eigensystem
178
4.3-2
of the order 80 real general matrix of Table 5, and CBAL and CBABK2 together
require an even smaller percentage of the time for the corresponding complex
matrix of Table 4. In contrast, we have contrived a matrix for which the
combination of BALANC and BALBAK requires 7% of the normal path time, but
this matrix represents an extreme case. More commonly, the execution
times for these subroutines are only a few percent of the total path times.
179
4.4-I
Section 4.4
EXTRAPOLATION OF TIMING RESULTS TO OTHER MACHINES AND COMPILERS
The extrapolation of timing results to other machines and compilers
may appear straightforward but can be grossly inaccurate if characteris-
tics of the particular machines and compilers are not carefully considered.
To illustrate this point, we make two comparisons: first, the execution
times of EISPACK on an IBM 360/75 and 370/195, and second, the execution
times of EISPACK compiled with the CDC 6600 Fortran RUN and FTN, OPT=I
compilers.
The eigensystems of several random matrices of order 80 were determined
using identical object modules on the IBM 360/75 and 370/195. The ratios
of the IBM 360/75 times to the 370/195 times show large variations from
subroutine to subroutine (compare Tables 4-6 with Tables 7-9). Many of
the ratios are between ii and 14, but at opposite extremes the ratio for
BISECT is 6.7 whereas for TQL2, 19.4.
These large variations in the ratios of execution times among the sub-
routines are attributable to the special architecture of the IBM 370/195;
namely, the buffered or two-level memory, the pipe line or parallel arith-
metic units, and the instruction stack. Some of the EISPACK subroutines
are able to take advantage of these special features of the 370/195 better
than others.
The compiler can also affect the relative efficiencies of EISPACK
subroutines. On two comparable CDC 6600 computers, one employing the
RUN compiler and the other the FTN, OPT=I compiler, the ratios of the
execution times for the EISPACK subroutines were determined (compare
Tables 22-24 with Tables 34-36). Many of the ratios are close to i, but
extremes as large as 2.2 for INVIT, 2.7 for HQR, and 3.0 for HQR2 obtain
180
4.4-2
for real general matrices of order 60.
It is clear from these examples that the relative efficiency of an
algorithm can be very machine and compiler dependent, and hence that the
extrapolation of our timing results to other systems must necessarily
include these nonsiderations.
181
4.5-1
Section 4.5
THE SAMPLE MATRICES FOR THE TIMING RESULTS
In this section, Fortran listings of the program segments which generate
the sample matrices for the timing results are provided. The matrix elements
are pseudo-random integers sampled from a uniform distribution on the inter-
val (-215,+215). A listing of the auxiliary subroutine RANDOM which generates
the random integers is also provided.
482
4.5-2
I0 20
COMPLEX GENERAL MATRIX
DO 20 I = I,N DO i0 d = I,N
CALL RANDOM (INIT, AR(I,J)) CALL RANDOM (INIT, AI(I,J))
CONTINUE CONTINUE
10 20 30
COMPLEX HERMITIAN MATRIX
IF (N .EQ. 1) GO TO 30 DO 20 I = 2,N
CALL RANDOM (INIT, AR(I-Ij I-l)) AI(I-I,I-1) = 0.0 DO 10 J = I,N
CALL RANDOM (INIT, AR(I-I,J)) AR(J, I-1) = AR(I-1,J) CALL RANDOM (INIT, AI(I-1,J)) AI(J,I-1) = -AI(I-1,J)
CONT I NUE CONT I NUE CALL RANDOM (INIT, AR(N,N)) AI(N,N) = 0.0
i0 20
COMPLEX HERMITIAN PACKED MATRIX
DO 20 i = I,N DO i0 d = I,N
CALL RANDOM (INIT, A(I,J)) CONTINUE
CONTINUE
C C
10 20
REAL GENERAL MATRIX
DO20 I = I,N DO I0 J = I,N
CALL RANDOM (INIT, A(I,J)) CONTINUE
CONT I NUE
REAL SYMMETRIC MATRIX
I0 20
DO20 I= I,N DO i0 a = I,N
CALL RANDOM (INIT, A(I,J)) A ( J , I ) = A ( I , J )
CONT I NUE CONT I NUE
183
4.5-3
REAL SYMMETRIC PACKED MATRIX
10
NNN = N*(N+I)/2 DO I0 I = I,NNN
CALL RANDOM (INIT, A(1)) CONTINUE
10 20 30
REAL SYMMETRIC TRIDIAGONAL MATRIX
CALL RANDOM (INIT, A(I,2)) IF (N .EQ. 1) GO TO 30 DO 20 I = 2,N
DO 10 J = 1,2 CALL RANDOM (INIT, A(I,J))
CONTINUE CONTINUE CONTINUE
SPECIAL REAL NON-SYMMETRIC TRIDIAGONAL MATRIX
DO 20 I = I,N DO I0 J = 1,3
CALL RANDOM (INIT, A(I,J)) 10 CONTINUE 20 CONTINUE
IF (N .EQ. i) GO TO 40 DO 30 I = 2,N
A( I , 1 ) = SIGN(A(I,1), A ( I - 1 , 3 ) ) 30 CONTINUE 40 CONTINUE
Subroutine R~NDOM:
SUBROUTINE RANDOM (INIT, X) REAL X INIT = MOD(3125*INIT, 65536) X = INIT - 32768 RETURN END
Subroutine RANDOM produces pseudo-random integer elements X
between -215 and 215 from a starting integer INIT. It was designed
so that it could be implemented in Fortran and would produce the same
set of pseudo-random numbers on different machines. As a result it
has some shortcomings as a random number generator, including a rather
short period of 214 numbers.
184
5.0-I
Section 5
CERTIFICATION ;aND AVAII~ILITY OF EISPACK
Under the auspices of the NATS Project, the subroutines constituting
Release 2 of EISPACK have been tested on and are certified for the follow-
ing computer systems and working precisions (test site names are indicated
in parentheses):
WORKING MACHINE OPERATING SYSTEM COMPILER PRECISION
IBM 370/195
IBM 360/75
IBM 370/168
IBM 360/75
IBM 370/165
BURROUGHS 6700
CDC 6600
CDC 6600
CDC 7600
CDC 6400
CDC 6400/6500
CDC 6600/6400
HONEYWELL 6070
UNIVAC Iii0
DEC PDP-IO
0S/360 (21.7) FTN IV G,H(21.7),WATFIV LONG (ARGONNE NATIONAL LABORATORY)
0S/360 (21.7) FTN IV H(21.7) LONG (UNIVERSITY OF ILLINOIS AT URBANA-CHAMPAIGN)
MTS FTN IV G,H LONG (UNIVERSITY OF MICHIGAN)
OS/360 (21.7) FTN IV H EXTENDED(2.1) LONG (STOCKHOLM DATA CENTER)
0S/360 (21.7) FTN IV H EXTENDED(2.1) LONG (THE UNIVERSITY OF TORONTO)
MCP 2.6 FORTRAN IV(2.6) SINGLE (UNIVERSITY OF CALIFORNIA, SAN DIEGO)
SCOPE 3.4.2 FTN(4.2) SINGLE (KIRTLAND AIR FORCE BASE/AF~rL)
KRONOS 2.1 RUN(2.3) SINGLE (ICASE/NASA LANGLEY RESEARCH CENTER)
(LOCAL) (LOCAL) SINGLE (NATIONAL CENTER FOR ATMOSPHERIC RESEARCH)
SCOPE 3.3 RUN(2.3) ,FTN(3.0) SINGLE (NORTHWESTERN UNIVERSITY)
(LOCAL) FUN SINGLE (PURDUE UNIVERSITY)
UT2D-85 RUN (60.2), MNF, RUh~/ SINGLE (THE UNIVERSITY OF TEXAS AT AUSTIN)
GECOS SR-F FORTRAN-Y (SR-F) SINGLE (BELL LABORATORIES AT MURRAY HILL)
EXEC-8 (31. 244) FORTRAN V(9) SINGLE (THE UNIVERSITY OF WISCONSIN)
TOPS-10 (506B) FORTRAN F40 SINGLE (YALE UNIVERSITY)
185
5.0-2
The control program EISPAC has been tested on and is certified for
the IBM systems at Argonne~ Illinois, Stockholm, and Toronto listed above.
Additional testing of EISPACK was carried out at Stanford University,
Harvard University, and on the Amdahl 470V/6 machine at University of
Michigan.
Certification implies the full support of the NATS project in the
sense that reports of poor or incorrect performance on at least the computer
system~ listed above will be examined and any necessary corrections made.
This support holds only when the software is obtained through the channels
indicated below and has not been modified; it will continue to hold through-
out the useful life of EISPACK or until, in the estimation of the developers,
the package is superseded or incorporated into other supported, widely-
available program libraries. The following individual serves as a contact
for information about EISPACK~ accepting reports from users concerning
performance:
Burton S. Garbow Applied Mathematics Division Argonne National Laboratory Argonne, Illinois 60439 U.S.A. Phone: 312-739-7711 x4342
EISPACK is distributed from the Argonne Code Center. Versions exist
for IBM 360-370, CDC 6000-7000, Univac iii0, Honeywell 6070, DEC PDP-IO,
and Burroughs 6700 machines~ Fortran source decks, documentation, and
testing aids will be transmitted as card images on a tape supplied by the
requester. The tape should have a rating of at least 800 bpi and be a
full 2400 feet long. The requester should specify the desired machine
version. The tape should be mailed to:
Argonne Code Center Bldg. 221 Argonne National Laboratory Argonne, Illinois 60439 U.S.A.
186
5.0-3
The tape will be returned parcel post unless the Code Center is requested
otherwise. It will be returned by air mail collect if the Code Center is
so authorized in writing and the postal service procedures permit such
shipment.
Certain international agreements pertain to the distribution of EISPACK
outside the United States by the Argonne Code Center. Information concern-
ing such distribution may be obtained from the Code Center.
187
6.0-!
Section 6
DIFFERENCES BETWEEN THE EISPACK SUBROUTINES AND THE HANDBOOK ALGOL PROCEDURES
This section describes, subroutine by subroutine, the major differ-
ences between the EiSPACK subroutines and their Algol antecedents in the
Handbook [I]. These differences fall into four categories: I) correction
of several errors, 2) minor algorithmic improvements, 3) changes based on
consideration of Fortran language efficiency, and finally, 4) changes to
better unify the individual programs into a package.
Some of the changes apply to EISPACK as a whole.
i) The base B of the floating point representation on the machine and
the machine precision MACHEP have become internally set variables in the
Fortran programs rather than parameters.
2) The orthogonaiity threshold parameter TOL has been removed from
the Householder reduction subroutines by substituting the alternate scaling
technique discussed in the "Organisational and Notational Details" section
of the Handbook, Contribution 11/2, p. 221.
3) The procedure CDIV called to perform complex division in the
Handbook procedures has been replaced by ordinary division operations with
complex-mode Fortran operands. The procedures CABS and CSQRT called to
perform complex modulus and complex square-root operations have been
replaced by references to corresponding members of the Fortran library
which use complex-mode operands.
4) The Handbook procedure-calls for row interchange in the balancing
process, for determination of Sturm counts in the bisection process, and
for selection of new trial vectors in the inverse iteration process have
been replaced by in-line Fortran coding.
] 88
6.0-2
Specific changes to individual members of EISPACK are as follows.
BALANC - IGH=I rather than IGH=0 is returned when the matrix can be per-
muted to triangular form; IGH is used as an array declarator
subscript in other subroutines and must not be "0".
TRED 1 - Unnecessary operations in the last reduction step that can
introduce roundoff error into the first diagonal element have
been skipped, enabling the resultant tridiagonal form to more
literally duplicate that from TRED2. Also see TRED2 below.
TRED 2 - The arithmetic operation G*(Z/H) is computed instead as (G/H)*Z,
enabling the resultant tridiagonal form to more literally dupli-
cate that from TREDI. The tridiagonal forms from TREDI and TRED2
are now identical (on most machines) except possibly for the sign
of the first subdiagonal element. This property in turn ensures
that TQLI and TQL2, or IMTQLI and IMTQL2, produce identical
eigenvalues in most cases.
TRED3 - As for TREDI.
TRBAKI - Instead of back transforming eigenvectors M1 through M2 as is
done in the Handbook, TRBAKI transforms eigenvectors i through
M. (The MI, M2 form of specification would be more natural if
subroutine BISECT were patterned after the Handbook BISECT
rather than the Handbook TSTURM.)
TRBAK3 - As for TRBAKI.
HQR - Provision for recognition of balancing parameters LOW and IGH
has been made. Also see HQR2 below.
189
6.0-3
HQR2 - Roots of a quadratic equation with discriminant zero are now
classified as real rather than complex as in the Handbook. This
change corrects an error which may otherwise be made in deter-
mining the corresponding eigenvectors. For consistency the
change has been made to HQR also.
- The last component of complex vectors of the reduced form is
initialized to (0,i) rather than (I,0), rendering the vector
matrix of the reduced form strictly triangular and thereby
simplifying the final transformation to the eigenvectors of the
original matrix.
INVIT - The complex eigenvector corresponding to either member of a pair
of conjugate complex eigenvalues may be obtained, not just the
one corresponding to the value with positive imaginary part.
However, if both are requested, only the eigenvector corresponding
to the eigenvalue with positive imaginary part is computed.
- The eigenvector growth requirement has been relaxed by a factor
of !0, reducing the number of convergence failures.
TSTURM - Small subdiagonal entries of the tridiagonal form are treated as
zeros in the computation but are not replaced by zeros in storage.
The subdiagonal array is required in TRBAKI and modification of
any of its elements by TSTURM introduces errors in the back
transformation.
- The input interval (RLB,RUB) is refined making use of Gerschgorin
bounds, thereby reducing the computation time of the bisection
process.
190
6.0-4
- The logical array INT has been eliminated by making use instead
of information present in the reduced triangular form and input
subdiagonal array.
BISECT - The bisection process of TSTURM is used instead of that in the
Handbook BISECT procedure. They differ primarily in the specifi-
cation of the subset of the eigenvalues to be computed.
- The eigenvalues are strictly ordered, rather than locally
ordered within submatrices as in TSTURM; they are tagged with
their submatrix associations by use of the array IND.
TRIDIB - As for BISECT except that the bisection process of the Handbook
BISECT procedure is used.
COMLR - Provision for recognition of balancing parameters LOW and IGH
has been made.
CINVIT - The vector growth requirement has been relaxed by a factor of I0,
reducing the number of convergence failures.
RATQR - The largest as well as the smallest eigenvalues can be requested.
The specification of "NEGATIVE DEFINITE" (when proper) improves
the determination of the largest values in the same way as
uPOSITIVE DEFINITE" does the smallest.
- An error return has been provided for an incorrectly specified
definiteness parameter.
- The incidence of underflow has been markedly reduced by replace-
ment of tiny squared subdiagonal elements by zeros at each
iteration.
191
6.0-5
- The eigenvalues are tagged with their submatrix associations by
use of the array IND. A further modification that saves the
input matrix makes it possible to link RATQRwith TINVIT to
compute the corresponding eigenvectors.
A number of the EISPACK subroutines which have no Handbook antecedents
are patterned closely after existing Handbook procedures.
CBAL is a complex analogue of BALANC,
CBABK2 is a complex analogue of BALBAK,
CORTH is a complex analogue of ORTHES,
CORTB is a complex analogue of ORTBAK,
COMQR is a unitary analogue of COMLR,
COMQR2 is a unitary analogue of COMLR2,
HTRIDI is a complex analogue of TREDi,
HTRIBK is a complex analogue of TRBAKI,
HTRID3 is a complex analogue of TRED3,
HTRIB3 is a complex analogue of TRBAK3,
IMTQLV is an extension of IMTQLI that tags the eigenvalues with their
submatrix associations as in BISECT,
TQLRAT is a rational variant of TQLI, and
TINVIT is that part of TSTURMwhich determines the eigenvectors after
the eigenvalues have been found.
Subroutines FIGI, FIGI2, and BAKVEC provide the EISPACK capability for
special nonsymmetric tridiagonal matrices not present in the Handbook pro-
cedures. They may be considered analogous to TREDI, TRED2, and TRBAKI
respectively.
192
6.0-6
Finally, various minor textual changes have been nmde to render the
first of each of the following pairs of subroutines a virtual subset of
the second: (COMLR,COMLR2), (HQR,HQR2), (TQLI,TQL2), (IM~QLI,IMTQL2), and
(BISECT,TSTURM).
193
7 . 0 - i
Section 7
DOCUMENTATION AN~ SOURCE LISTINGS
This section contains the documentation and source listings for the
EISPACK subroutines and the documentation for the control program EISPAC.
The subroutines appear in alphabetical order in Section 7.1 with the
source listing for each subroutine following its document. Section 7.2
contains the document for EISPAC, but because of its size and machine
dependencies the listing is not included.
Both the subroutine documents and source listings have been system-
atically edited for this publication to eliminate duplicate text; they
therefore differ from the nmterial distributed to requesters of EISPACK.
The statement of certification of item 6 has been removed from the
individual documents and appears here in Section 5. The reference to
this publication which appears in item 4 and the brief discussian of test-
ing that appears in items 5.A and 5.C of the distributed documents have
been removed; the latter has been replaced by a pointer to the more exten-
sive discussion of testing here in Section 3.
Two modifications have been made to the subroutine listings published
here. First, ~hey have been shortened by eliminating com~ents related to
usage, calling sequence, and error exits which basically duplicate text in
the documents, Second, statements initializing variables to machine-
dependent constants, which in each distributed version of EISPACK are
completed to contain the appropriate numerical values of these constants,
appear here as
MACHEP = ?
RADIX = #
194
7.0-2
(The correct value for MACHEP is the smallest positive working precision
floating point number which, when added to 1.0 using the working precision
addition operation on your machine, gives a number larger than 1.0; that
for RADIX is the floating point constant representing the base of the
floating point arithmetic on your machine.) Appropriate values of MACHEP
and RADIX for several machines are summarized in the following table.
MACHINE MACHEP RADIX
Burroughs 6700 2.**(-37) 8.
CDC 6000 and 7000 Series 2.**(-47) 2.
DEC PDP-10 2.**(-26) 2.
Honeywell 6070 2°**(-26) 2.
Univac iii0 2.**(-26) 2.
Except for the statements initializing MACHEP and RADIX, the published
listings are ANSI Fortran. The double precision version certified for
IBM equipment employs non-standard Fortran to the extent of using REAL*8
declarations and a small amount of complex double precision arithmetic.
For this version, the appropriate values of MACHEP and RADIX are 16.D0"*(-13)
and 16.D0.
195
7.1-!
NATS PROJECT
E!GENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F281-2 BAKVEC
A Fortran IV Subroutine to Back Transform the Eigenvectors of that Symmetric Tridiagonal Matrix Determined by FIGIo
May, 1972 July, 1975
I. PURPOSE
The Fortran IV subroutine BAKVEC forms the eigenvectors of a certain real non-symmetric tridiagonal matrix from the eigenvectors of that symmetric tridiagonal matrix determined by FIGI (F280).
2. USAGE.
A. Calling Sequence~
The SUBROUTINE statement is
SUBROUTINE BAKVEC(NM~N,T,E,M,Z,IERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays T and Z as specified in the DIMENSION statements for T and Z in the calling program°
N is an integer input variable set equal to the order of the matrix T. N must be not greater than NM.
is a working precision real input two- dimensional variable with row dimension NM and column dimension at least 3. T contains the non-symmetric tridiagonal matrix of order N in its first three columns. The subdiagonal elements are stored in the last N-I positions of the
196
7.1-2
M
IERR
first column. The diagonal elements are stored in the second column. The superdiagonal elements are stored in the first N-I positions of the third column. Elements T(I,I) and T(N,3) are arbitrary.
is a working precision real one-dimensional variable of dimension at least N. On input, the last N-I positions in this array contain the subdiagonal elements of the symmetric tridiagonal matrix. E(1) is arbitrary. Note that BAKVEC destroys E.
is an integer input variable set equal to the number of columns of Z to be back transformed.
is a working precision real two-dimensional variable with row dimension NM and column dimension at least M. On input, the first M columns of Z contain the eigenvectors to be back transformed. On output, these columns of Z contain the transformed eigenvectors. The transformed eigenvectors are not normalized.
is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
B. Error Conditions and Returns.
If E(1) is zero but either T(I,I) or T(I-I,3) is not zero, BAKVEC terminates with IERR set to 2*N+I and with no eigenvectors back transformed. In this case, the transformation by FIGI was not a similarity transformation.
If the above error condition does not occur, IERR is set to zero.
C. Applicability and Restrictions.
This subroutine should be used in conjunction with the subroutine FIGI (F280).
197
7.1-3
3. DISCUSSION OF METHOD AND ALGORITHM.
Suppose that the non-symmetric tridiagonal matrix T has been transformed to the tridiagonal symmetric matrix P by the similarity transformation
-i F = V TV
where V is the diagonal matrix defined in FIGI (F280). Then, given an array Z of column vectors, BAKVEC computes the matrix product VZ. If the eigenvectors of F are columns of the array Z, then BAKVEC forms the eigenvectors of T in their place.
This subroutine is an implementation of the algorithm discussed in detail by Wilkinson (i).
4. REFERENCES°
i) Wilkinson, J.H., The Algebraic Eigenvalue Problem, Oxford, Clarendon Press, 335-337 (1965).
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for certain real non-symmetric tridiagonal matrices.
B. Accuracy.
The accuracy of BAKVEC can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of certain real non- symmetric tridiagonal matrices. In these paths, this subroutine is numerically stable (I). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.
198
7.1-4
SUBROUTINE BAKVEC(NM,N,T,E,M,Z,IERR)
INTEGER I,J,M,N,NM,IERR REAL T(NM,3),E(N),Z(NM,M)
IERR = 0 IF (M .EQ. 0) GO TO i001 E(1) = 1 . 0
IF (N .EQ. i) GO TO i001
DO i00 1 = 2, N IF (E(1) .NEo 0.0) GO TO 80 IF (T(I,I) .NE. 0.0 .OR. T(I-I,3) .NE. 0.0) GO TO i000 E(I) = 1.0 GO TO I00
80 E(I) = E(I-I) * E(I) / r(I-l,3) 100 CONTINUE
DO 120 J = i, M
DO 120 I = 2, N Z(I,J) = Z(I,J) * E(I)
120 CONTINUE
GO TO i001 C ********** SET ERROR -- EIGENVECTORS CANNOT BE C FOUND BY THIS PROGRAM ********** i000 IERR = 2 * N + I I001 RETURN
END
199
7~i-5
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F269-2 BALANC
A Fortran IV Subroutine to Balance a Real General Matrix.
May, 1972 July, 1975
i. PURPOSE.
The Fortran IV subroutine BALANC balances a real general matrix and isolates eigenvalues whenever possible. Sums of the magnitudes of elements in corresponding rows and columns are made nearly equal by exact similarity transformations, and eigenvalues are isolated by permutation similarity transformations. Balancing reduces the 1-norm of the original matrix whenever sums of the magnitudes of elements in some row and corresponding column are markedly different, while at the same time leaving the eigenvalues unchanged. Reducing the norm in this way can improve the accuracy of the computed eigenvalues and/or eigenvectors.
2. USAGE.
Ao Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE BALANC(NM,N,A,LOW, IGH,SCALE)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification°
NM is an integer input variable set equal to the row dimension of the two-dimensional array A as specified in the DIMENSION statement for A in the calling program.
is an integer input variable set equal to the order of the matrix A. N must be not greater than NM.
200
7 .I-6
A is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. On input, A contains the matrix of order N to be balanced. On output, A contains the transformed matrix.
LOW, IGH are integer output variables indicating the boundary indices for the balanced matrix. See section 3 for the details.
SCALE is a working precision real output one- dimensional variable of dimension at least N containing information about the similarity transformations. See section 3 for the details.
B. Error Conditions and Returns.
None.
C. Applicability and Restrictions.
It is particularly advantageous to use BALANC whenever the sums of the magnitudes of elements in some row and corresponding column are quite different. Additionally, the execution time for BALANC is small compared with the execution time for the routines which determine the eigenvalues and/or eigenvectors. Hence it is recommended that BALANC be used generally.
The subroutine BALBAK (F270) should be used to retrieve the eigenvectors of the original matrix after the eigenvectors of the transformed matrix have been determined.
3. DISCUSSION OF METHOD AND ALGORITHM.
First BALANC determines a product P of permutation matrices such that
PAP ( T X Y )
= (0 B Z) (0 0 R)
where T and R are upper triangular matrices and B is a square matrix situated in rows and columns LOW through IGH with no zero off-diagonal rows or columns. X, Y, and Z are rectangular matrices of appropriate dimensions. The
201
7.1-7
diagonal elements of T and R are the isolated eigenvalues of A. In the exceptional case where B is empty, LOW = 1 and IGH = 0 -- however, i is returned as the output value of IGH.
Next, the subroutine BALANC determines iteratively a non- singular diagonal matrix D of order IGH-LOW+I such that
-I D BD
is a balanced matrix in the sense that the absolute sums of the magnitudes of elements in corresponding rows and columns of
-i D BD
are nearly equal° The diagonal elements of D are powers of the radix of the floating point arithmetic of the machine.
Upon completion of BALANC, the vector array SCALE contains the information about P and D necessary for BALBAK to retrieve the eigenvectors of the original matrix from the eigenvectors of the transformed matrix. The information is encoded as follows. I. The J-th and SCALE(J)-th rows and columns of the
original matrix have been permuted for J = 1,2,...,LOW-I,IGH+I,IGH+2,...,N.
2. SCALE(J) is the (J-LOW+l)-th diagonal element of D for J = LOW,LOW+I,...,IGH.
Upon completion of BALANC, the output matrix is
( T XD Y ) -I -i
( 0 D BD D Z )
( 0 0 R ).
This subroutine is a translation of the Algol procedure BALANCE written and discussed in detail by Parlett and Reinsch (I).
4. REFERENCES.
i) Parlett, B.N. and Reinsch, C., Balancing a Matrix for Calculation of Eigenvalues and Eigenvectors, Num. Math. 13,293-304 (1969). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinseh, Contribution Ii/ii, 315-326, Springer-Verlag, 1971.)
202
7.1-8
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for real general matrices.
B. Accuracy.
BALANC introduces no rounding errors (on a machine with at least one guard digit) since its only arithmetic is scaling the input matrix by powers of the radix.
203
7.1-9
SUBROUTINE BALANC(NM,N,A,LOW, IGH,SCALE)
INTEGER I,J,K,L,M,N,JJ,NM,!GH,LOW, IEXC
REAL A(NM,N),SCALE(N) REAL C,F,G,R,S,B2,RADIX
REAL ABS
LOGICAL NOCONV
********** RADIX IS A MACHINE DEPENDENT PARAMETER SPECIFYING THE BASE OF THE MACHINE FLOATING POINT REPRESENTATION.
RADIX = #
B2 = RADIX * RADIX
K = 1
L = N GO TO i00 • ********* IN-LINE PROCEDURE FOR ROW AND
COLUMN EXCHANGE ********~*
20 SCALE(M) = J IF (J .EQ. M) GO TO 50
DO 30 I = I, L F = A(I,J) A(I,J) = A(I,M)
A(I,M) = F
30 CONTINUE
DO 40 1 = K, N
F = A(J, I) A(J,I) = A(M,I)
A(M, I) = F 40 CONTINUE
C 50 GO TO (80, 130), !EXC
C ********** SEARCH FOR ROWS ISOLATING AN EIGENVALUE
C AND PUSH THEM DOWN **********
80 IF (L .EQ. i) GO TO 280
L = L - i C ********** FOR J=L STEP -I UNTIL 1 DO -- **********
i00 DO 120 JJ = i, L J = L + i - JJ
ii0
DO Ii0 I = i, L IF (! .EQ. J) GO TO ii0 IF (A(J,I) .NE. 0.0) GO TO 120
CONTINUE
M = L !EXC = 1 GO TO 20
120 CONTINUE
204
7 . 1 - 1 0
GO TO 140
********** SEARCH FOR COLUMNS ISOLATING AN EIGENVALUE AND PUSH THEM LEFT **********
130 K = K + 1
140 DO 170 J = K, L
150
DO 150 I = K, L IF (I .EQ. J) GO TO 150 IF (A(I,J) .NE. 0.0) GO TO 170
CONTINUE
M = K IEXC = 2 GO TO 20
170 CONTINUE
********** NOW BALANCE THE SUBMATRIX IN ROWS K TO L ********** DO 180 I = K, L
180 SCALE(I) = 1.0
********** ITERATIVE LOOP FOR NORM REDUCTION ********** 190 NOCONV = .FALSE.
DO 270 1 = K, L C = 0.0 R= 0.0
DO 200 J = K, L IF (J .EQ. I) GO TO 200 C = C + ABS(A(J,I)) R = R + ABS(A(I,J))
200 CONTINUE
C ********** GUARD AGAINST ZERO C OR R DUE TO UNDERFLOW ********** IF (C .EQ. 0.0 .OR. R .EQ. 0.0) GO TO 270 G = R / RADIX F=I.0 S = C + R
210 IF (C .GE. G) GO TO 220 F = F * RADIX C = C * B 2 GO TO 210
220 G = R * RADIX 230 IF (C .LT. G) GO TO 240
F = F / RADIX C = C / B2
GO TO 230 C ********** NOW BALANCE **********
240 IF ((C + R) / F .GE. 0.95 * S) GO TO 270 G=I.O/F SCALE(l) = SCALE(l) * F NOCONV = .TRUE.
250 DO 250 J = K, N
A(I,J) = A(I,J) * G
205
7.1-11
260 DO 260 J = I, L
A(J,I) = A(J,I) * F
270 CONTINUE
IF (NOCONV) GO TO 190
280 LOW = K
IGH = L
RETURN END
206
7.1-12
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F270-2 BALBAK
A Fortran IV Subroutine to Back Transform the Eigenvectors of that Real Matrix Transformed by BALANC.
May, 1972 July, 1975
i. PURPOSE.
The Fortran IV subroutine BALBAK forms the eigenvectors of a real general matrix from the eigenvectors of that matrix transformed by BALANC (F269).
2. USAGE.
A. Call~ng Sequence.
The SUBROUTINE statement is
SUBROUTINE BALBAK(NM,N,LOW, IGH, SCALE,M,Z)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional array Z as specified in the DIMENSION statement for Z in the calling program.
N is an integer input variable set equal to the number of components of the vectors in the array Z. N must be not greater than NM.
LOW, IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F269 for the details.
SCALE is a working precision real input one- dimensional variable of dimension at least N containing information about the transformations. See section 3 of F269 for the details.
207
7.1-13
is an integer input variable set equal to the number of columns of Z to be back transformed.
is a working precision real two-dimensional variable with row dimension NM and column dimension at least M. On input, the first M columns of Z contain the real and imaginary parts of the eigenvectors to be back transformed. On output, these M columns of Z contain the real and imaginary parts of the transformed eigenvectors.
B. Error Conditions and Returns.
None°
C. Applicability and Restrictions.
This subroutine should be used in conjunction with the subroutine BALANC (F269).
3. DISCUSSION OF METHOD AND ALGORITHM.
Using the notation of F269, the original matrix transformed into the matrix C by the similarity transformation
A is
-I C = G PAPG
where G is the diagonal matrix whose diagonal elements are 1.0 in positions 1 to LOW-I, 1.0 in positions IGH+I to N, and are the diagonal elements of D in positions LOW to IGH. Given an array Z of vectors, the subroutine BALBAK computes the matrix product PGZ. If the real and imaginary parts of the eigenvectors of C are columns of the array Z, then BALBAK forms the eigenvectors of A in their place. The information about P and D is encoded in the array SCALE. See section 3 of F269 for the details.
This subroutine is a translation of the Algol procedure BALBAK written and discussed in detail by Pariett and Reinsch (I).
208
7.1-14
4. REFERENCES.
1) Parlett, B.N. and Reinsch, C., Balancing a Matrix for Calculation of Eigenvalues and Eigenvectors, Num. Math. 13,293-304 (1969). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution II/Ii, 315-326, Springer-Verlag, 1971.)
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for real general matrices.
B. Accuracy.
BALBAK introduces no rounding errors (on a machine with at least one guard digit) since its only arithmetic is scaling the eigenvector matrix by powers of the radix.
209
7.1-15
SUBROUTINE BALBAK(NM,N,LOW, IGH, SCALE,M,Z)
INTEGER I~J,K,M,N,II,NM, IGH,LOW REAL SCALE(N),Z(NM,M) REAL S
IF (M ,EQ. 0) GO TO 200 IF (IGH .EQ. LOW) GO TO 120
I00
DO Ii0 i = LOW, IGH S = SCALE(l)
********** LEFT HAND EIGENVECTORS ARE BACK TRANSFORMED IF THE FOREGOING STATEMENT IS REPLACED BY S=I.O/SCALE(1). ***~******
DO i00 J = i, M Z(I,J) = Z(I,J) * S
ii0 CONTINUE ********- FOR I=LOW-I STEP -I UNTIL i~
IGH+I STEP 1 UNTIL N DO -- ********** 120 DO 140 ii = i, N
! = II IF (I .GE. LOW .AND. I .LE. IGH) GO TO 140 IF (I .LT. LOW) I = LOW - II K = SCALE(l) IF (K .EQ. I) GO TO 140
130
DO 130 J = i~ M S = Z(I,J) Z(I,J) = Z(K,J)
Z(K,J) = S CONTINUE
140 CONTINUE
200 RETURN END
210
7.1-16
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F294 BISECT
A Fortran IV Subroutine to Determine Some Eigenvalues of a Symmetric Tridiagonal Matrix.
May, 1972
I. PURPOSE.
The Fortran IV subroutine BISECT determines those eigenvalues of a symmetric tridiagonal matrix in a specified interval using Sturm sequencing.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE BISECT(N,EPSI,D,E,E2,LB,UB, MM,M,W,IND,IERR,RV4,RV5)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
N is an integer input variable set equal to the order of the matrix.
EPSI is a working precision real variable. On input, it specifies an absolute error tolerance for the computed eigenvalues. If the input EPSI is non-positive, it is reset to a default value described in section 2C.
D is a working precision real input one- dimensional variable of dimension at least N containing the diagonal elements of the symmetric tridiagonal matrix.
E is a working precision real input one- dimensional variable of dimension at least N containing, in its last N-I positions, the subdiagonal elements of the symmetric tridiagonal matrix. E(1) is arbitrary.
211
7.1-17
E2 is a working precision real one-dimensional variable of dimension at least N. On input s the last N-I positions in this array contain the squares of the subdiagonal elements of the symmetric tridiagonal matrix. E2(1) is arbitrary. On output, E2(1) is set to zero. If any of the elements in E are regarded as negligible, the corresponding elements of E2 are set to zero, and so the matrix splits into a direct sum of submatrices.
LB,UB are working precision real input variables specifying the lower and upper endpoints, respectively, of the interval to be searched for the eigenvalues. If LB is not less than UB, BISECT computes no eigenvalues. See section 2C for further details.
MM is an integer input variable set equal to an upper bound for the number of eigenvalues in the interval (LB,UB).
M is an integer output variable set equal to the number of eigenvalues determined to lie in the interval (LB,UB).
is a working precision real output one- dimensional variable of dimension at least MM containing the M eigenvalues of the symmetric tridiagonal matrix in the interval (LB,UB). The eigenvalues are in ascending order in W.
IND is an integer output one-dimensional variable of dimension at least MM containing the submatrix indices associated with the corresponding M eigenvalues in W. Eigenvalues belonging to the first submatrix have index I, those belonging to the second submatrix have index 2, etc.
IERR is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
RV4,RV5 are working precision real temporary one- dimensional variables of dimension at least N used to hold the lower and upper bounds for the eigenvalues in the bisection process.
212
7. 1-18
B. Error Conditions and Returns.
If M exceeds MM, BISECT terminates with no eigenvalues computed, and IERR is set to 3*N+I. Upon this error exit, M contains the number of eigenvalues determined to lie in (LB,UB).
If M does not exceed MM, IERR is set to zero.
C. Applicability and Restrictions.
To determine some of the eigenvalues of a full symmetric matrix, BISECT should be preceded by TREDI (F277) to provide a suitable symmetric tridiagonal matrix for BISECT.
To determine some of the eigenvalues of a complex Hermitian matrix, BISECT should be preceded by HTRIDI (F284) to provide a suitable real symmetric tridiagonal matrix for BISECT.
Some of the eigenvalues of certain non-symmetric tridiagonal matrices can be computed using the combination of FIGI (F280) and BISECT. See F280 for the description of this special class of matrices. For these matrices, BISECT should be preceded by FIGI to provide a suitable symmetric matrix for BISECT.
To determine eigenvectors associated with the computed eigenvalues, BISECT should be followed by TINVIT (F223) and the appropriate back transformation subroutine -- TRBAKI (F279) after TREDI, HTRIBK (F285) after HTRIDI, or BAKVEC (F281) after FIGI.
The subroutines TQLI (F289) and IMTQLI (F291) determine all the eigenvalues of a symmetric tridiagonal matrix faster than BISECT determines 25 percent of them. Hence, if more than 25 percent of them are desired, it is recommended that TQLI or IMTQLI be used.
The interval (LB,UB) is formally half-open, not including the upper endpoint UB. However, because of rounding errors, the true eigenvalues very close to the endpoints of the interval may be erroneously counted or missed.
The input interval (LB,UB) may be refined internally to a smaller interval known to contain all the eigenvalues in (LB,UB). This insures that BISECT will not perform unnecessary bisection steps to determine the eigenvalues in (LB,UB).
213
7,1-19
The precision of the computed eigenvalues is controlled through the parameter EPSI. To obtain eigenvalues accurate to within a certain absolute error, EPSI should be set to that error. In particular, if MACHEP denotes the relative machine precision, then to obtain the eigenvalues to an accuracy commensurate with small relative perturbations of the order of MACHEP in the matrix elements, it is enough for most tridiagonal matrices that EPSI be approximately MACHEP times a norm of the matrix. But some matrices require a smaller EPSI for this accuracy 9 perhaps as small as MACHEP times the eigenvalue of smallest magnitude in (LB,UB). Note, however, that if EPSI is smaller than required, BISECT will perform unnecessary bisection steps to determine the eigenvalues. For further discussion of EPSI, see reference (I).
If the input EPSI is non-positive, BISECT resets it, for each submatrix, to -MACHEP times the 1-norm of the submatrix and uses its magnitude. This value is tentatively considered adequate for computing the eigenvalues to an accuracy commensurate with small relative perturbations of the order of MACHEP in the matrix elements.
3. DISCUSSION OF METHOD AND ALGORITHM.
The eigenvalues are determined by the method of bisection applied to the Sturm sequence.
The calculations proceed as follows. First, the subdiagonal elements are tested for negligibility. If an element is considered negligible, its square is set to zero, and so the matrix splits into a direct sum of submatrices. Then, the Sturm sequence for the entire matrix is evaluated at UB and LB giving the number of eigenvalues of the matrix less than UB and LB respectively. The difference is the number of eigenvalues in (LB,UB).
Next, a submatrix is examined for its eigenvalues in the interval (LB,UB). The Gerschgorin interval, known to contain all the eigenvalues, is determined and used to refine the input interval (LB,UB). If the input EPSI is non- positive, it is reset to the default value described in section 2C~ Then, subintervals, each enclosing an eigenvalue in (LB,UB), are shrunk using a bisection process until the endpoints of each subinterval are close enough to be accepted as an eigenvalue of the submatrix. Here the endpoints of each subinterval are close enough when they differ by less than MACHEP times twice the sum of the magnitudes of the endpoints plus the absolute error tolerance EPSI.
214
7.1-20
The submatrix eigenvalues are then merged with previously found eigenvalues into an ordered set.
The above steps are repeated on each submatrix until all the eigenvalues in the interval (LB,UB) are computed.
This subroutine is a subset (except for the section merging eigenvalues of submatrices) of the Fortran subroutine TSTURM (F293), which is a translation of the Algol procedure TRISTURM written and discussed in detail by Peters and Wilkinson (2). A similar Algol procedure BISECT is discussed in detail by Barth, Martin, and Wilkinson (i).
4. REFERENCES.
i) Barth, W., Martin, R.S., and Wilkinson, J.H., Calculation of the Eigenvalues of a Symmetric Tridiagonal Matrix by the Method of Bisection, Num. Math. 9,386-393 (1967).
2) Peters, G. and Wilkinson, J.H., The Calculation of Specified Eigenvectors by Inverse Iteration, Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/18, 418-439, Springer-Verlag, 1971.
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for complex Hermitian, real symmetric, real symmetric tridiagonal, and certain real non-symmetric tridiagonal matrices.
B. Accuracy.
The subroutine BISECT is numerically stable (1,2); that is, the computed eigenvalues are close to those of the original matrix. In addition, they are the exact eigenvalues of a matrix close to the original real symmetric tridiagonal matrix.
215
7.1-21
C C
C
C C
SUBROUTINE BISECT(N,EPSI,D,E,E2,LB,UB,MM,M,W, IND,IERR,RV4,RV5)
INTEGER !,J,K)L,M,N,P,Q,R,S,II)MM,MI,M2,TAG,!ERR,ISTURM REAL D(N))E(N) ,E2(N),W(MM) ,RV4(N),RV5(N)
REAL U,V)LB,TI,T2,UB,XU,X0,XI,EPSI,MACHEP REAL ABS,AMAXI,AMiNI,FLOAT
INTEGER IND(MM)
********** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING
THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.
MACHEP = ?
IERR = 0
TAG = 0 TI = LB
T2 = UB C ********** LOOK FOR SMALL SUB-DIAGONAL ENTRIES **********
DO 40 I = i) N
IF (I .EQ. i) GO TO 20 IF (ABS(E(1)) .GT. MACHEP * (ABS(D(1)) + ABS(D(I-I))))
X GO TO 40 20 E2(1) = 0.0
40 CONTINUE C ********** DETERMINE THE NUMBER OF EIGENVALUES
C IN THE INTERVAL **********
P = !
q = N
XI = UB ISTURM = I GO TO 320
60 M = S XI = LB ISTURM = 2 GO TO 320
80 M = M - S IF (M .GT. MM) GO TO 980
Q = 0
R = 0 C ********** ESTABLISH AND PROCESS NEXT SUBMATRIX, REFINING
C INTERVAL BY THE GERSCHGORIN BOUNDS **********
i00 IF (R .EQ. M) GO TO I001
TAG = TAG + I P = Q + I
XU = D(P) xo = D(P) U = 0.0
216
7.1-22
DO 120 Q = P, N
X1 = U
U = 0.0 V = 0.0
IF (Q .EQ. N) GO TO ii0 U = ABS(E(Q+I)) V = E2(Q+I)
Ii0 XU = AMINI(D(Q)-(XI+U),XU)
X0 = AMAXI(D(Q)+(XI+U),X0)
IF (V °EQ. 0.0) GO TO 140 120 CONTINUE
140 X1 = AMAXI(ABS(XU),ABS(X0)) * MACHEP IF (EPSI .LE. 0.0) EPSI =-XI IF (P .NE. Q) GO TO 180
C ********** CHECK FOR ISOLATED ROOT WITHIN INTERVAL ********** IF (rl .GT. D(P) .OR. D(P) .GE. T2) GO TO 940 M1 = P
M2 = P
RVS(P) = D(P)
GO TO 9O0
180 XI = XI * FLOAT(Q-P+1)
LB = AMAXI (TI,XU-XI) UB = AMINI(T2,X0+XI) X1 = LB ISTURM = 3
GO TO 320 200 MI = S + 1
XI = UB ISTURM = 4
GO TO 320 220 M2 = S
IF (MI .GT. M2) GO TO 940
C ********** FIND ROOTS BY BISECTION ********** XO = UB
ISTURM = 5
C C
C
DO 240 I = MI, M2 RVS(I) = UB RV4 (I) = LB
240 CONTINUE
********** LOOP FOR K-TH EIGENVALUE
FOR K=M2 STEP -i UNTIL MI DO --
(-DO- NOT USED TO LEGALIZE COMPUTEE-GO-TO) ********** K = M2
250 XU = LB
********** FOR I=K STEP -I UNTIL M1 DO -- ********** DO 260 II = MI, K
I = M1 + K - II
IF (XU .GE. RV4(1)) GO TO 260 XU = RV4(1) GO TO 280
CONTINUE 260
217
7,1-23
C
280 IF (X0 oGT. RV5(K)) X0 = RVS(K) ********** NEXT BISECTION STEP **********
3 0 0 xl : (xu + x0) * 0.5 IF ((X0 - XU) .LE, (2.0 * MACHEP *
X (ABS(XU) + ABS(X0)) + ABS(EPSI))) GO TO 420
********** IN-LINE PROCEDURE FOR STURM SEQUENCE **********
320 S = P - I
U=I.0
325
330
3 4 0
DO 340 1 = P, Q
IF (U .NE. 0.0) GO TO 325 V = ABS(E(1)) / MACHEP
GO TO 330 V = E2(1) / U U = D(1) - Xl - V IF (U .LT. 0.0) S = S + !
CONTINUE
3 6 0
380
400
GO TO (60,80,200,220,360), ISTURM
********** REFINE INTERVALS ********** IF (S .GE. K) GO TO 400
XU = XI IF (S .GE. MI) GO TO 380
RV4(MI) = XI GO TO 300 RV4 (S+I) = XI IF (RV5(S) .GT. El) RV5(S) = XI
GO TO 300
X0 = X1
GO TO 300 ********** K-TH EIGENVALUE FOUND **********
420 RV5(K) = El
K = K - i IF (K ,GE. MI) GO TO 250 ********** ORDER EIGENVALUES TAGGED WITH THEIR
SUBMATRIX ASSOCIATIONS **********
900 S = R R = R + M2 - MI + i
J = i K = MI
DO 920 L = i, R IF (J .GT. S) GO TO 910
IF (K .GT. M2) GO TO 940 IF (RV5(K) .GE. W(L)) GO TO 915
905
DO 905 Ii = J, S
I = L + S - !! W(I+1) = W(I) IND(I+I) = IND(1)
CONTINUE
2 1 8
7 . 1 - 2 4
910 W(L) = RVS(K) IND (L) = TAG
K = K + I GO TO 920
915 J = J + I
920 CONTINUE
940 IF (Q .LT. N) GO TO I00
GO TO i001 *****~***~ SET ERROR -- UNDERESTIMATE OF NUMBER OF
EIGENVALUES IN INTERVAL **********
980 IERR = 3 * N + 1 I001LB = TI
UB = T2 RETURN END
219
7. 1-25
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F272-2 CBABK2
A Fortran IV Subroutine to Back Transform the Eigenvectors of that Complex Matrix Transformed by CBAL.
May, 1972 July, 1975
I~ PURPOSEs
The Fortran IV subroutine CBABK2 forms the eigenvectors of a complex general matrix from the eigenvectors of that matrix transformed by CBAL (F271).
2. USAGE.
A. Calling Sequencer
The SUBROUTINE statement is
SUBROUTINE CBABK2(NM,N,LOW, IGH, SCALE,M,ZR,ZI)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays ZR and ZI as specified in the DIMENSION statements for ZR and ZI in the calling program.
N is an integer input variable set equal to the number of components of the vectors in the array Z = (ZR,ZI). N must be not greater than NM.
LOW,!GH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F271 for the details.
SCALE is a working precision real input one- dimensional variable of dimension at least N containing information about the transformations. See section 3 of F271 for the details.
220
7.1-26
M
ZR,ZI
is an integer input variable set equal to the number of columns of Z = (ZR,ZI) to be back transformed.
are working precision real two-dimensional variables with row dimension NM and column dimension at least M. On input, the first M columns of ZR and ZI contain the real and imaginary parts, respectively, of the eigenvectors to be back transformed. On output, these M columns of ZR and ZI contain the real and imaginary parts of the transformed eigenvectors.
B. Error Conditions and Returns.
None.
C. Applicability and Restrictions.
This subroutine should be used in conjunction with the subroutine CBAL (F271).
3. DISCUSSION OF METHOD AND ALGORITHM.
Using the notation of F271, the original matrix A transformed into the matrix C by the similarity transformation
is
-i C = G PAPG
where G is the diagonal matrix whose diagonal elements are 1.0 in positions I to LOW-l, 1.0 in positions IGH+I to N, and are the diagonal elements of D in positions LOW to IGH. Given an array Z of vectors, the subroutine CBABK2 computes the matrix product PGZ. If the eigenvectors of C are columns of the array Z, then CBABK2 forms the eigenvectors of A in their place. The information about P and D is encoded in the array SCALE. See section 3 of F271 for the details.
This subroutine is a translation of the Algol procedure CBABK2 which is the analogue for complex matrices of the procedure BALBAK written and discussed in detail by Parlett and Reinsch (I).
221
7.1-27
4. REFERENCES~
i) Parlett~ B.N. and Reinsch~ C., Balancing a Matrix for Calculation of Eigenvalues and Eigenvectors, Num. Math. 13,293-304 (1969). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution II/ll, 315-326, Springer-Verlag, 1971.)
5, CHECKOUT~
A. Test Cases°
See the section discussing testing of the codes for complex general matrices.
B. Accuracy°
CBABK2 introduces no rounding errors (on a machine with at least one guard digit) since its only arithmetic is scaling the eigenvector matrix by powers of the radix.
222
7.1-28
SUBROUTINE CBABK2(NM,N,LOW, IGH, SCALE,M,ZR,ZI)
INTEGER I,J,K,M,N,II,NM,IGH,LOW
REAL SCALE(N),ZR(NM,M),ZI(NM,M) REAL S
IF (M .EQ. 0) GO TO 200 IF (IGH .EQ. LOW) GO TO 120
i00
DO II0 1 = LOW, IGH S = SCALE(l)
********** LEFT HAND EIGENVECTORS ARE BACK TRANSFORMED IF THE FOREGOING STATEMENT IS REPLACED BY S=I.0/SCALE(1). **********
DO i00 J = I, M ZR(I,J) = ZR(I,J) * S ZI(I,J) = ZI(I,J) * S
CONTINUE
ii0 CONTINUE
********** FOR I=LOW-I STEP -i UNTIL i, IGH+I STEP 1 UNTIL N DO -- **********
120 DO 140 II = i, N I = II
IF (I .GE. LOW .AND. I .LE. IGH) GO TO 140 IF (I .LT. LOW) I = LOW - II K = SCALE(l) IF (K .EQ. I) GO TO 140
130
DO 130 J = i, M S = ZR(I,J) ZR(I,J) = ZR(K,J) ZR(K,J) = S S = ZI(I,J) ZI(I,J) = ZI(K,J) ZI(K,J) = S
CONTINUE
140 CONTINUE
200 RETURN END
223
7. 1-29
NATS PROJECT
EiGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F271-2 CBAL
A Fortran IV Subroutine to Balance a Complex General Matrix.
May, 1972 July, i975
i. PURPOSE.
The Fortran IV subroutine CBAL balances a complex general matrix and isolates eigenvalues whenever possible. Sums of the magnitudes of elements in corresponding rows and columns are made nearly equal by exact similarity transformations, and eigenvalues are isolated by permutation similarity transformations. Balancing reduces the 1-norm of the original matrix whenever sums of the magnitudes of elements in some row and corresponding column are markedly different, while at the same time leaving the eigenvalues unchanged. Reducing the norm in this way can improve the accuracy of the computed eigenvalues and/or eigenvectors.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE CBAL(NM,N,AR,AI,LOW,IGH,SCALE)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays AR and AI as specified in the DIMENSION statements for AR and AI in the calling program.
N is an integer input variable set equal to the order of the matrix A = (AR,AI). N must be not greater than NM.
224
7.1-30
AR,AI are working precision real two-dimensional variables with row dimension NM and column dimension at least N. On input, AR and AI contain the real and imaginary parts, respectively, of the complex matrix of order N to be balanced. On output, AR and AI contain the real and imaginary parts of the transformed matrix.
LOW, IGH are integer output variables indicating the boundary indices for the balanced matrix. See section 3 for the details.
SCALE is a working precision real output one- dimensional variable of dimension at least N containing information about the similarity transformations. See section 3 for the details.
B. Error Conditions and Returns.
None.
C. Applicability and Restrictions.
It is particularly advantageous to use CBAL whenever the sums of the magnitudes of elements in some row and corresponding column are quite different. Additionally, the execution time for CBAL is small compared with the execution time for the routines which determine the eigenvalues and/or eigenvectors. Hence it is recommended that CBAL be used generally.
The subroutine CBABK2 (F272) should be used to retrieve the eigenvectors of the original matrix after the eigenvectors of the transformed matrix have been determined.
In this implementation, the arithmetic is real throughout.
3. DISCUSSION OF METHOD AND ALGORITHM.
First CBAL determines a product P such that
PAP (T X Y)
= (0 B Z) (0 0 R)
of permutation matrices
225
7.1-31
where T and R are upper triangular matrices and B is a square matrix situated in rows and columns LOW through IGH with no zero off-diagonal rows or columns. X, Y, and Z are rectangular matrices of appropriate dimensions. The diagonal elements of T and R are the isolated eigenvalues of A. In the exceptional case where B is empty, LOW = 1 and IGH = 0 -- however, I is returned as the output value of IGH.
Next, the subroutine CBAL determines iteratively a real non-singular diagonal matrix D of order IGH-LOW+I such that
-i D BD
is a balanced matrix in the sense that the sums of the magnitudes of elements in corresponding rows and columns of
-i D BD
are nearly equal° The diagonal elements of D are powers of the radix of the floating point arithmetic of the machine.
Upon completion of CBAL, the vector array SCALE contains the information about P and D necessary for CBABK2 to retrieve the eigenvectors of the original matrix from the eigenvectors of the transformed matrix. The information is
encoded as follows. I. The J-th and SCALE(J)-th rows and columns of the
original matrix have been permuted for J = 1,2,...,LOW-I,IGH+I,IGH+2,...,N.
2. SCALE(J) is the (J-LOW+l)-th diagonal element of D
for J = LOW,LOW+I,...,IGH. Upon completion of CBAL, the output matrix is
( T xo Y ) - 1 - 1
( 0 D BD D Z )
( 0 0 R ) .
This subroutine is a translation of the Algol procedure CBALANCE which is the analogue for complex matrices of the procedure BALANCE written and discussed in detail by Parlett and Reinsch (i).
226
7.1-32
4. REFERENCES.
~) Parlett, B.N. and Reinsch, C., Balancing a Matrix for Calculation of Eigenvalues and Eigenvectors, Num. Math. 13,293-304 (1969). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution II/ll, 315-326, Springer-Verlag, 1971.)
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for complex general matrices.
B. Accuracy.
CBAL introduces no rounding errors (on a machine with at least one guard digit) since its only arithmetic is scaling the input matrix by powers of the radix.
227
7~ 1-33
SUBROUTINE CBAL(NM,N,AR,AI,LOW,iGH,SCALE)
INTEGER !,J,K,L,M,N,JJ,NM,IGH,LOW,IEXC REAL AR(NM,N),AI(NM,N),SCALE(N)
REAL C,F,G,R,S,B2,RADIX REAL ABS
LOGICAL NOCONV
********** RADIX IS A MACHINE DEPENDENT PARAMETER SPECIFYING THE BASE OF THE MACHINE FLOATING POINT REPRESENTATION.
RADIX = #
B2 = RADIX * RADIX
K = 1
L = N GO TO i00 • ********* IN-LINE PROCEDURE FOR ROW AND
COLUMN EXCHANGE ********** 20 SCALE(M) = J
IF (J .EQ~ M) GO TO 50
DO 30 I = i, L
F = AR(I,J) AR(I,J) = AR(I,M)
AR(I,M) = F F = AI(I,J)
AI(I,J) = AI(I,M)
AI(I,M) = F
30 CONTINUE
DO 40 1 = K, N F = AR(J,I)
AR(J,I) = AR(M,I) AR(M,I) = F
F = AI(J,I) AI(J,I) = AI(M,I) AI (M, I) = F
40 CONTINUE
C 50 GO TO (80,130), IEXC
C ********** SEARCH FOR ROWS ISOLATING AN EIGENVALUE
C AND PUSH THEM DOWN **********
80 IF (L .EQ. i) GO TO 280 L = L - I
C ********** FOR J=L STEP -I UNTIL i DO -- **********
i00 DO 120 JJ = i, L J = L + i - JJ
ii0
DO ii0 i = I, L IF (I .EQ. J) GO TO ii0 IF (AR(J,I) .NE. 0.0.0R~ AI(J,I) .NE. 0.0) GO TO 120
CONTINUE
228
7.1-34
C
C C
C
C
M = L
IEXC = 1 GO TO 20
120 CONTINUE
GO TO 140
********** SEARCH FOR COLUMNS ISOLATING AN EIGENVALUE AND PUSH THEM LEFT **********
130 K = K + 1
140 DO 170 J = K, L
150
DO 150 1 = K, L IF (I .EQ. J) GO TO 150
IF (AR(I,J) .NE. 0.0 .OR. AI(I,J) .NE. 0.0) GO TO 170 CONTINUE
M = K IEXC = 2 GO TO 20
170 CONTINUE
********** NOW BALANCE THE SUBMATRIX IN ROWS K TO L ********** DO 180 I = K, L
180 SCALE(l) = 1.0
********** ITERATIVE LOOP FOR NORM REDUCTION ********** 190 NOCONV = .FALSE.
DO 270 1 = K, L C=0.0
R=0.0
DO 200 J = K, L
IF (J .EQ. I) GO TO 200 C = C + ABS(AR(J,I)) + ABS(AI(J,I))
R = R + ABS(AR(I,J)) + ABS(AI(I,J)) 200 CONTINUE
********** GUARD AGAINST ZERO C OR R DUE TO UNDERFLOW ********** IF (C .EQ. 0.0 .OR. R .EQ. 0.0) GO TO 270 G = R / RADIX F = 1.0
S = C +R 210 IF (C .GE. G) GO TO 220
F = F * RADIX C = C * B2 GO TO 210
220 G = R * RADIX
230 IF (C .LT. G) GO TO 240 F = F / RADIX C = C / B 2 GO TO 230
229
7. 1-35
240 ********** NOW BALANCE **********
IF ((C + R) / F .GE. 0.95 * S) GO TO 270 G = 1.0 / F SCALE(I) = SCALE(I) * F
NOCONV = ~TRUE.
250
DO 250 J = K~ N
AR(I,J) = AR(I,J) * G iI(I,J) = AI(I,J) * G
CONTINUE
260
DO 260 J = i, L
AR(J,I) = AR(J,I) * F AI(J,I) = AI(J,I) * F
CONTINUE
270 CONTINUE
IF (NOCONV) GO TO 190
280 LOW = K
IGH = L RETURN
END
230
7.1-36
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F301 CG
A Fortran IV Driver Subroutine to Determine the Eigenvalues and Eigenvectors of a Complex General Matrix.
July, 1975
i. PURPOSE.
The Fortran IV subroutine CG calls the recommended sequence of subroutines from the eigensystem subroutine package EISPACK to determine the eigenvalues and eigenvectors (if desired) of a complex general matrix.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE CG(NM,N,AR,AI,WR,WI,MATZ, ZR,ZI,FVI,FV2,FV3,1ERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays AR, AI, ZR, and ZI as specified in the DIMENSION statements for AR, AI, ZR, and ZI in the calling program.
is an integer input variable set equal to the order of the matrix A = (AR,AI). N must not be greater than NM.
AR,AI are working precision real two-dimensional variables with row dimension NM and column dimension at least N. On input, AR and AI contain the real and imaginary parts, respectively, of the complex general matrix of order N whose eigenvalues and eigenvectors are to be found. On output, AR and AI have been destroyed.
231
7.1-37
WR,WI are working precision real output one- dimensional variables of dimension at least N containing the real and imaginary parts, respectively, of the eigenvalues of the complex general matrix.
MATZ is an integer input variable set equal to zero if only eigenvalues are desired; otherwise it is set to any non-zero integer for both eigenvalues and eigenvectors.
ZR,ZI are, if MATZ is non-zero, working precision real output two-dimensional variables with row dimension NM and column dimension at least N containing the real and imaginary parts, respectively, of the eigenvectors. The eigenvectors are not normalized. If MATZ is zero, ZR and ZI are not referenced and can be dummy variables.
FVI,FV2,FV3 are working precision temporary one- dimensional variables of dimension at least N.
IERR is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
B. Error Conditions and Returns.
If N is greater than NM, the subroutine terminates with IERR set equal to 10*N.
If more than 30 iterations are required to determine an eigenwalue, the subroutine terminates with IERR set equal to the index of the eigenvalue for which the failure occurs. The eigenvalues in the WR and WI arrays should be correct for indices IERR+I,IERR+2,...,N, but no eigenvectors are computed.
If all the eigenvalues are determined within 30 iterations, IERR is set to zero.
C. Applicability and Restrictions.
This subroutine can be used to find all the eigenvalues and all the eigenvectors (if desired) of a complex general matrix.
232
7. 1-38
3. DISCUSSION OF METHOD AND ALGORITHM.
This subroutine calls the recommended sequence of subroutines from EISPACK to find the eigenvalues and eigenvectors of a complex general matrix.
To find eigenvalues only, the sequence is the following. C B A L - to balance a complex general matrix, CORTH - to reduce the balanced matrix to an upper
Hessenberg matrix using unitary transformations.
COMQR - to determine the eigenvalues of the original matrix from the Hessenberg matrix.
To find eigenvalues and eigenvectors, the sequence is the following.
C B A L - to balance a complex general matrix. CORTH - to reduce the balanced matrix to an upper
Hessenberg matrix using unitary transformations.
COMQR2 - to determine the eigenvalues and eigenvectors of the balanced matrix from the Hessenberg matrix.
C B A B K 2 - to backtransform the eigenvectors to those of the original matrix.
4. REFERENCES.
i) Garbow, B.S. and Dongarra, J.J., April, 1974.
EISPACK Path Chart,
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for complex general matrices.
B. Accuracy.
The accuracy of CG can be best described in terms of its role in those paths of EISPACK (I) which find eigenvalues and eigenvectors of complex general matrices. In these paths, this subroutine is numerically stable. This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original matrix.
233
7. 1-39
SUBROUTINE CG(NM,N,AR,AI,WR~WI,MATZ,ZR,ZI,FVI,FV2,FV3,1ERR)
INTEGER N,NM,ISI,IS2,1ERR,MATZ REAL AR(NM,N),AI(NM,N),WR(N),WI(N),ZR(NM,N),ZI(NM,N),
$ FVI(N),FV2(N),FV3(N)
IF (NoLE. NM) !ERR = i0 * N
GO TO 50
GO TO I0
I0 CALL CBAL(NM, N,AR,AI,ISI,IS2,FVI) CALL CORTH(NM,N,ISI,IS2,AR,AI,FV2,FV3) IF (MATZ .RE. 0) GO TO 20 ********** FIND EIGENVALUES ONLY ********** CALL COMQR(NM,N, ISI,IS2,AR,AI,WR,WI, IERR) GO TO 50 ********** FIND BOTH EIGENVALUES AND EIGENVECTORS **********
20 CALL COMQR2(NM~N, ISI,IS2,FV2,FV3~AR~AI~WR,WI,ZR,ZI,IERR) IF (IERR .RE. 0) GO TO 50 CALL CBABK2(NM~N,ISI,IS2~FVI,N,ZR,ZI)
50 RETURN END
234
7.1-40
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F302 CH
A Fortran IV Driver Subroutine to Determine the Eigenvalues and Eigenvectors of a Complex Hermitian Matrix.
July, 1975
i. PURPOSE.
The Fortran IV subroutine CH calls the recommended sequence of subroutines from the eigensystem subroutine package EISPACK to determine the eigenvalues and eigenveetors (if desired) of a complex Hermitian matrix.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE CH(NM,N,AR,AI,W,MATZ, ZR,ZI,FVI,FV2,FMI,IERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays AR, AI, ZR, and ZI as specified in the DIMENSION statements for AR, AI, ZR, and ZI in the calling program.
is an integer input variable set equal to the order of the matrix A = (AR,AI). N must not be greater than NM.
AR,AI are working precision real two-dimensional variables with row dimension NM and column dimension at least N. On input, AR and AI contain the real and imaginary parts, respectively, of the complex Hermitian matrix of order N whose eigenvalues and
235
7. 1-41
eigenvectors are to be found. Only the full lower triangle of AR and the strict lower triangle of AI need be supplied. On output, the full upper triangle of AR and the strict upper triangle of Ai are unaltered.
W is a working precision real output one- dimensional variable of dimension at least N containing the eigenvalues of the complex Hermitian matrix in ascending order.
MATZ is an integer input variable set equal to zero if only eigenvalues are desired; otherwise it is set to any non-zero integer for both eigenvalues and eigenvectors.
ZR,ZI are, if MATZ is non-zero, working precision real output two-dimensional variables with row dimension NM and column dimension at least N containing the real and imaginary parts, respectively, of the eigenvectors. The eigenvectors are orthonormal. If MATZ is zero, ZR and ZI are not referenced and can be dummy variables.
FVI,FV2 are working precision temporary one- dimensional variables of dimension at least N.
FMI is a working precision temporary two- dimensional variable with row dimension and column dimension at least N.
!ERR is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
B. Error Conditions and Returns.
If N is greater than NM, the subroutine terminates with IERR set equal to 10*N.
If more than 30 iterations are required to determine an eigenvalue, the subroutine terminates with IERR set equal to the index of the eigenvalue for which the failure occurs. The eigenvalues in the W array should be correct for indices 1,2,...,IERR-I, but no eigenvectors are computed.
236
7.1-42
If all the eigenvalues are determined within 30 iterations, IERR is set to zero.
C. Applicability and Restrictions.
This subroutine can be used to find all the eigenvalues and all the eigenvectors (if desired) of a complex Hermitian matrix.
3. DISCUSSION OF METHOD AND ALGORITHM.
This subroutine calls the recommended sequence of subroutines from EISPACK to find the eigenvalues and eigenvectors of a complex Hermitian matrix.
To find eigenvalues only, the sequence is the following. HTRIDI - to reduce a complex Hermitian matrix to a real
symmetric tridiagonal matrix using unitary transformations.
TQLRAT - to determine the eigenvalues of the original matrix from the real symmetric tridiagonal matrix.
To find eigenvalues and eigenvectors, the sequence is the following.
HTRIDI - to reduce a complex Hermitian matrix to a real symmetric tridiagonal matrix using unitary transformations.
TQL2 - to determine the eigenvalues and eigenveetors of the real symmetric tridiagonal matrix.
HTRIBK - to backtransform the eigenvectors to those of the original matrix.
4. REFERENCES.
i) Garbow, B.S. and Dongarra, J.J., April, 1974.
EISPACK Path Chart,
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for complex Hermitian matrices.
B. Accuracy.
237
7. 1-43
The accuracy of CH can best b e described in terms of its role in those paths of EISPACK (I) which find eigenvalues and eigenvectors of complex Hermitian matrices. In these paths, this subroutine is numerically stable. This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix,
238
7.1-44
C
SUBROUTINE CN(NM~N,AR,AI,W~MATZ,ZR,ZI,FVI,FV2,FMI,IERR)
INTEGER I,J,N,NM,IERR,MATZ REAL AR(NM,N),AI(NM,N),W(N),ZR(NM,N),ZI(NM,N),
$ FVI(N),FV2(N),FMI(2,N)
IF (N .LE. NM) GO TO i0 IERR = i0 * N GO TO 50
i0 CALL HTRIDI(NM,N,AR,AI,W,FVI,FV2,FMI) IF (MATZ .NE. 0) GO TO 20 ********** FIND EIGENVALUES ONLY ********** CALL TQLRAT(N,W,FV2,1ERR) GO TO 50 ********** FIND BOTH EIGENVALUES AND EIGENVECTORS **********
20 DO 40 I = i, N
30
DO 30 J = i, N ZR(J,I) = 0.0
CONTINUE
ZR(I,I) = 1.0 40 CONTINUE
CALL TQL2(NM,N,W,FVI,ZR,IERR) IF (IERR .NE. 0) GO TO 50 CALL HTR!BK(NM,N,AR,AI,FMI,N,ZR,ZI)
50 RETURN END
239
7.1-45
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F297-2 CINVIT
A Fortran IV Subroutine to Determine Those Eigenvectors of a Complex Upper Hessenberg Matrix Corresponding to Specified Eigenvalues.
May, 1972 July, 1975
i. PURPOSE.
The Fortran IV subroutine CINVIT computes the eigenvectors of a complex upper Hessenberg matrix corresponding to specified eigenvalues using inverse iteration.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE CINVlT(NM, N,AR,A!,WR,WI,SELECT, MM,M,ZR,ZI,IERR,RMI,RM2,RVI,RV2)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays AR, AI, ZR, and ZI as specified in the DIMENSION statements for AR, AI, ZR, and ZI in the calling program.
N is an integer input variable set equal to the order of the matrix A = (AR,AI). N must be not greater than NM.
AReAl are working precision real input two- dimensional variables with row dimension NM and column dimension at least N containing the real and imaginary parts 3 respectively~ of the complex upper Hessenberg matrix.
240
7.1-46
WR,WI are working precision real one-dimensional variables of dimension at least N. On input, they contain the real and imaginary parts, respectively, of the eigenvalues of the Hessenberg matrix. The eigenvalues need not be ordered, except that eigenvalues of any submatrix of the input Hessenberg matrix must have indices in WR,WI which lie between the boundary indices for that submatrix. These ordering constraints are satisfied by the output eigenvalues from COMLR (F295). On output, the eigenvalues are unaltered, except that the real parts of close eigenvalues may be perturbed slightly in an attempt to obtain independent eigenvectors.
SELECT is a logical input one-dimensional variable of dimension at least N whose true elements flag those eigenvalues whose eigenvectors are desired.
MM is an integer input variable set equal to an upper bound for the number of columns required to hold the desired eigenvectors.
M is an integer output variable set equal to the number of columns actually used to store the eigenvectors.
ZR,ZI are working precision real output two- dimensional variables with row dimension NM and column dimension at least MM containing the real and imaginary parts, respectively, of the eigenvectors corresponding to the flagged eigenvalues. The eigenvectors are packed into the columns of ZR and ZI starting at the first columns.
IERR is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
RMI,RM2 are working precision real temporary array variables of dimension at least N*N. These arrays holds the triangularized form of the upper Hessenberg matrix used in the inverse iteration process.
241
7.1-47
RVI,RV2 are working precision real temporary one- dimensional variables of dimension at least N. They hold the approximate eigenvectors during the inverse iteration process.
B. Error Conditions and Returns~
If more than MM eigenvectors are requested, CINVIT terminates with IERR set to -(2*N+I) and with the first MM eigenvectors in the arrays ZR and ZI. this case, M = MM.
In
If none of the initial vectors for the inverse iteration process produces an acceptable approximation to an eigenvector, CINVIT terminates the computation for that eigenvector and sets IERR to -K where K is the index of the associated eigenvalue. If this failure occurs for more than one eigenvalue, the last occurrence is recorded in IERR. The columns of ZR and ZI corresponding to failures of the above sort are set to zero vectors.
If both of the above error conditions occur, CINVIT terminates with IERR set to -(N+K) where K is the index of the last eigenvalue whose inverse iteration process failed. The columns of ZR and ZI corresponding to failures in the inverse iteration process are set to zero vectors, and in this case, M = MM.
If neither of the above error conditions occurs, CINVIT sets IERR to zero.
C. Applicability and Restrictions.
To determine eigenvectors corresponding to some of the eigenvalues of a complex general matrix, CINVlT should be preceded by COMHES (F282) and COMLR (F295). COMHES provides a suitable complex upper Hessenberg matrix for CINVIT and COMLR determines the eigenvalues of this Hessenberg matrix. CINVIT should then be followed by COMBAK (F283) to back transform the eigenvectors from CINVIT into those of the original matrix. Note: the upper Hessenberg matrix must be saved before COMLR, since COMLR destroys this part of A = (AR,AI).
It is recommended in general that CBAL (F271) be used before COMHES in which case CBABK2 (F272) must be used after COMBAK.
242
7.1-48
In this implementation, the arithmetic is real throughout except for complex division and complex absolute value.
3. DISCUSSION OF METHOD AND ALGORITHM.
The eigenvectors are determined by inverse iteration. In CINVIT, this is a process whereby a vector XI satisfying the matrix linear equation U'X1 = X0 is computed, where X0 is an initial vector and U is the upper triangular factor in the LU decomposition of the matrix B-W*I with partial pivoting. W is an approximate eigenvalue of a leading submatrix B of the Hessenberg matrix in A. The vector X1 is accepted as an eigenvector of B if the norm of XI is sufficiently larger than the norm of X0. This eigenvector of B is transformed to an eigenvector of A by simply appending zero components to it.
The real and imaginary parts of U are stored in the two real arrays RMI and RM2 respectively. Internally, RMI and RM2 are treated as two-dimensional NxN arrays.
The acceptance criterion for X1 is a growth test of its norm. If MACHEP denotes the relative machine precision, then currently, XI is rejected as an eigenvector if
SQRT(UK)*!!B!!*MACHEP*!!XI!! .LT. !!X0!!/10.0
where UK is the order of the submatrix B whose eigenvector is being computed and the norm !! !! is the infinity norm. At most UK orthogonal initial vectors XO are tried to obtain the required growth. If no vector is accepted, the parameter IERR is set to indicate this failure and CINVIT proceeds to compute the next eigenvector.
The real parts of close or identical eigenvalues whose eigenvectors are desired may be perturbed slightly in an attempt to obtain independent eigenvectors (if they exist). If required, such perturbations are positive and small multiples of MACHEP*I!B!!.
This subroutine is a translation of the Algol procedure CX INVIT written and discussed in detail by Peters and Wilkinson (i).
243
7. 1-49
4. REFERENCE$~
1) Peters, G. and Wilkinson, J.H., The Calculation of Specified Eigenvectors by Inverse Iteration, Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/18, 418-439, Springer-Verlag, 1971.
5. CHECKOUT.
Ao Test Cases°
See the section discussing testing of the codes for complex general matrices~
Bo Accuracy°
The accuracy of CINVIT can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of complex upper Hessenberg matrices. In these paths, this subroutine is numerically stable (i). This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original upper Hessenberg matrix~
244
7 • 1-50
SUBROUTINE CINVIT(NM,N,AR,AI,WR,WI,SELECT,MM,M,ZR,ZI, X IERR,RMI,RM2,RVI,RV2)
INTEGER I,J,K,M,N,S,II,MM,MP,NM,UK, IPI,ITS,KMI,IERR REAL AR(NM,N),AI(NM,N),WR(N),WI(N),ZR(NM,MM),ZI(NM,MM),
X RMI(N,N),RM2(N,N),RVI(N),RV2(N) REAL X,Y,EPS3,NORM,NORMV,GROWTO,ILAMBD,MACHEP,RLAMBD,UKROOT REAL SQRT,CABS,ABS,FLOAT LOGICAL SELECT(N) COMPLEX Z3 COMPLEX CMPLX REAL REAL,AIMAG
********** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.
MACHEP = ?
IERR = 0 UK = 0 S = I
DO 980 K = i, N IF (.NOT. SELECT(K)) GO TO 980 IF (S .GT. MM) GO TO i000 IF (UK .GE. K) GO TO 200
C ********** CHECK FOR POSSIBLE SPLITTING ********** DO 120 UK = K, N
IF (UK .EQ. N) GO TO 140 IF (AR(UK+I,UK) .EQ. 0.0 .AND. AI(UK+I,UK) .EQ. 0.0)
X GO TO 140 120 CONTINUE
C ********** COMPUTE INFINITY NORM OF LEADING UK BY UK C (HESSENBERG) MATRIX **********
140 NORM = 0.0 MP = I
C
DO 180 I = i, UK X = 0.0
160 DO 160 J = MP, UK X = X + CABS(CMPLX(AR(I,J),AI(I,J)))
180
IF (X °GT. NORM) NORM = X MP = I
CONTINUE
********** EPS3 REPLACES ZERO PIVOT IN DECOMPOSITION AND CLOSE ROOTS ARE MODIFIED BY EPS3 **********
IF (NORM .EQ. 0.0) NORM = 1.0 EPS3 = MACHEP * NORM
245
7.1-51
C ********** GROWTO IS THE CRITERION FOR GROWTH ********** UKROOT = SQRT(FLOAT(UK)) GROWTO = I,OE-I / UKROOT
200 RLAMBD = WR(K)
ILAMBD = WI(K) IF (K .EQ. i) GO TO 280 KMI = K - 1
GO TO 240
C ********** PERTURB EIGENVALUE IF IT IS CLOSE C TO ANY PREVIOUS EIGENVALUE **********
220 RLAMBD = RLAMBD + EPS3
C ********** FOR I=K-I STEP -I UNTIL 1 DO -- ********** 240 DO 260 II = i~ KMI
I = K - II IF (SELECT(I) .AND. ABS(WR(I)-RLAMBD) .LT. EPS3 .AND.
ABS(WI(I)-ILAMBD) .LT. EPS3) GO TO 220
CONTINUE X
260
280
300
320
C
C
C
C
C
WR(K) = RLAMBD ********** FORM UPPER HESSENBERG (AR,AI)-(RLAMBD,ILAMBD)*I
AND INITIAL COMPLEX VECTOR **********
MP = I
DO 320 I = i, UK
DO 300 J = MP, UK RMI(i,J) = AR(I,J) RM2(I,J) = AI(I,J)
CONTINUE
RMI(I,I) = RMI(I,I) - RLAMBD RM2(I,I) = RM2(I,I) - ILAMBD
MP = I RVI(1) = EPS3
CONTINUE ********** TRIANGULAR DECOMPOSITION WITH INTERCHANGES,
REPLACING ZERO PIVOTS BY EPS3 **********
IF (UK oEQ. I) GO TO 420
X
DO 400 ! = 2, UK
MP = I - 1 IF (CABS(CMPLX(RMI(I,MP),RM2(!,MP))) .LE.
CABS(CMPLX(RMI(MP,MP),RM2(MP,MP)))) GO TO 360
340
DO 340 J = MP, UK Y = RMI(I,J) RMI (I, J) = RMI (MP, J)
RMI(MP,J) = Y Y = RM2(I,J) RM2 (I, J) = RM2 (MP, J) RM2 (MP, J) = Y
CONTINUE
246
7.1-52
360
X
X
380
400
420
X
660
680
700
720
760 780
IF (RMI(MP,MP) .EQ. 0.0 .AND. RM2(MP,MP) .EQ. 0.0)
RMI(MP,MP) = EPS3 Z3 = CMPLX(RMI(I,MP),RM2(I,MP)) /
CMPLX(RMI(MP,MP),RM2(MP,MP)) X = REAL(Z3) Y = AIMAG(Z3) IF (X .EQ. 0.0 .AND. Y .EQ. 0.0) GO TO 400
DO 380 J = I, UK RMI(I,J) = RMI(I,J) - X * RMI(MP,J) + Y * RM2(MP,J) RM2(I,J) = RM2(I,J) - X * RM2(MP,J) - Y * RMI(MP,J)
CONTINUE
CONTINUE
IF (RMI(UK,UK) .EQ. 0.0 .AND. RM2(UK,UK) .EQ. 0.0) RMI(UK,UK) = EPS3
ITS = 0 ********** BACK SUBSTITUTION
FOR I--UK STEP -i UNTIL 1 DO -- ********** DO 720 II = i, UK
I = UK + 1 - II X = RVI (I) Y = 0.0 IF (I .EQ. UK) GO TO 700 IPI = I + i
DO 680 J = IPI, UK X = X - RMI(I,J) * RVI(J) + RM2(I,J) * RV2(J) Y = Y - RMI(I,J) * RV2(J) - RM2(I,J) * RVI(J)
CONTINUE
Z3 = CMPLX(X,Y) / CMPLX(RMI(I,I),RM2(I,I)) RVI(1) = REAL(Z3) RV2(1) = AIMAG(Z3)
CONTINUE ********** ACCEPTANCE TEST FOR EIGENVECTOR
AND NORMALIZATION ********** ITS = ITS + 1 NORM = 0.0 NORMV = 0.0
DO 780 1 = i, UK X = CABS (CMPLX(RVI (I), RV2 (I))) IF (NORMV .GE. X) GO TO 760 NORMV = X J = I NORM = NORM + X
CONTINUE
IF (NORM .LT. GROWTO) GO TO 840
247
7.1-53
********** ACCEPT VECTOR ********** X = RVI (J)
Y = RV2 (J)
820
DO 820 i = i, UK
Z3 = CMPLX(RVI(1),RV2(1)) / CMPLX(X,Y)
ZR(I,S) = REAL(Z3) ZI(I,S) = AIMAG(Z3)
CONTINUE
840
IF (UK .EQ. N) GO TO 940
J = UK + 1
GO TO 900
********** IN-LINE PROCEDURE FOR CHOOSING
A NEW STARTING VECTOR ********** IF (ITS .GE. UK) GO TO 880 X = UKROOT Y = EPS3 / (X + 1.0) RVI(1) = EPS3
DO 860 1 = 2, UK 860 RVI(I) = Y
J = UK - ITS + 1
RVI(J) = RVI(J) - EPS3 * X GO TO 660
• ********* SET ERROR -- UNACCEPTED EIGENVECTOR **********
880 J = I
IERR = -K • ********* SET REMAINING VECTOR COMPONENTS TO ZERO **********
900 DO 920 I = J, N ZR(I,S) = 0.0
Zi(I,S) = 0.0 920 CONTINUE
940 S = S + 1 980 CONTINUE
GO TO i001 C ********** SET ERROR -- UNDERESTIMATE OF EIGENVECTOR C SPACE REQUIRED **********
I000 IF (IERR .NE. 0) IERR = IERR - N IF (IERR oEQ. 0) IERR =-(2 * N + i)
I001M = S - i RETURN END
2 4 8
7.1-54
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F283-2 COMBAK
A Fortran IV Subroutine to Back Transform the Eigenvectors of that Upper Hessenberg Matrix Determined by COMHES.
May, 1972 July, 1975
I. PURPOSE.
The Fortran IV subroutine COMBAK forms the eigenvectors of a complex general matrix from the eigenvectors of that upper ~essenberg matrix determined by COMHES (F282).
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE COMBAK(NM,LOW, IGH,AR,AI,INT,M,ZR,ZI)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays AR, AI, ZR, and ZI as specified in the DIMENSION statements for AR, AI, ZR, and ZI in the calling program.
LOW, IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F271 for the details. If the matrix is not balanced, set LOW to i and IGH to the order of the matrix.
AR,AI are working precision real input two- dimensional variables with row dimension NM and column dimension at least IGH. Their lower triangles below the subdiagonal contain the multipliers which were used in
249
7.1-55
INT
M
ZR,ZI
the reduction to the Hessenberg form. The remaining upper parts of AR and AI are arbitrary. See section 3 of F282 for the details.
is an integer input one-dimensional variable of dimension at least IGH. INT identifies the rows and columns interchanged during the reduction by COMHES. See section 3 of F282 for the details.
is an integer input variable set equal to the number of columns of Z = (ZR,ZI) to be back transformed.
are working precision real two-dimensional variables with row dimension NM and column dimension at least M. On input, the first M columns of ZR and ZI contain the real and imaginary parts, respectively, of the eigenvectors to be back transformed. On output, these M columns of ZR and ZI contain the real and imaginary parts of the transformed eigenvectors.
B. Error Conditions and Returns.
None.
C. Applicability and Restrictions.
This subroutine should be used in conjunction with the subroutine COMHES (F282).
3. DISCUSSION OF METHOD AND ALGORITHM.
Suppose that the matrix upper Hessenberg form F transformation
C (say) has been reduced to the stored in A by the similarity
-i F = G CG
where G is a product of the permutation and elementary matrices encoded in INT and in a lower triangle of A under F respectively. Then, given an array Z of column vectors, COMBAK computes the matrix product GZ. If the eigenvectors of F are columns of the array Z, then COMBAK forms the eigenvectors of C in their place.
250
7.1-56
This subroutine is a translation of the Algol procedure COMBAK written and discussed in detail by Martin and Wilkinson (I).
4. REFERENCES.
1) Martin, R.S. and Wilkinson, J.H., Similarity Reduction of a General Matrix to Hessenberg Form, Num. Math. 12,349-368 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/13, 339-358, Springer-Verlag, 1971.)
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for complex general matrices.
B. Accuracy.
The accuracy of COMBAK can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of complex general matrices. In these paths, this subroutine is, in practice, numerically stable (i). This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix usually close to the original matrix.
251
7.1-57
C
C
SUBROUTINE COMBAK(NM,LOW, IGH,AR,A!,INT,M,ZR,ZI)
INTEGER I,J,M,LA,MM,MP,NM,IGH,KPI,LOW,MPI REAL AR(NM,IGH),AI(NM, IGH),ZR(NM,M),ZI(NM,M) REAL XR,XI INTEGER !NT(IGN)
IF (M oEQ. 0) GO TO 200 LA = IGH - 1 KPI = LOW + 1 IF (LA .LT. KPI) GO TO 200 ********** FOR MP=IGH-I STEP -i UNTIL LOW+I DO -- ********** DO 140 MM = KPI, LA
MP = LOW + IGH - MM MPI = MP + i
DO ii0 I = MPI, IGH XR = AR(I,MP-I) Xi = AI(I,MP-I) IF (XR .EQ. 0.0 .AND. XI .EQ. 0.0) GO TO ii0
i00
DO i00 J = i, M ZR(I,J) = ZR(I,J) + XR * ZR(MP,J) - XI * ZI(MP,J) Zl(l,J) = ZI(I,J) + XR * ZI(MP,J) + Xl * ZR(MP,J)
CONTINUE
Ii0 CONTINUE
I = !NT(MP) IF (! .EQ. MP) GO TO 140
130
DO 130 J = i, M XR = ZR(I,J) ZR(I,J) = ZR(MP,J) ZR(MP,J) = XR XI = Zl(l,J) ZI(I,J) = ZI(MP,J) ZI(MP,J) = XI
CONTINUE
140 CONTINUE
200 RETURN END
252
7.1-58
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F282-2 COMHES
A Fortran IV Subroutine to Reduce a Complex General Matrix to Complex Upper Hessenberg Form Using
Elementary Transformations.
May, 1972 July, 1975
i. PURPOSE.
The Fortran IV subroutine COMHES reduces a complex general matrix to complex upper Hessenberg form using stabilized elementary similarity transformations. This reduced form is used'by other subroutines to find the eigenvalues and/or eigenvectors of the original matrix. See section 2C for the specific routines.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE COMHES(NM,N,LOW~IGH,AR,AI,INT)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimenslonal arrays AR and AI as specified in the DIMENSION statements for AR and AI in the calling program.
is an integer input variable set equal to the order of the matrix A = (AR,AI). N must be not greater than NM.
LOW,IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F271 for the details. If the matrix is not balanced, set LOW to 1 and IGH to N.
253
7.1-59
AR,A!
INT
are working precision real two-dimensional variables with row dimension NM and column dimension at least N. On input, AR and AI contain the real and imaginary parts, respectively, of the complex matrix of order N to be reduced to Hessenberg form. On output, AR and AI contain the real and imaginary parts of the upper Hessenberg matrix as well as the multipliers used in the reduction. See section 3 for the details.
is an integer output one-dimensional variable of dimension at least IGH identifying the rows and columns interchanged during the reduction. See section 3 for the details. Only components LOW+I through IGH-I are actually used by COMHES.
B° Error Conditions and Returns.
None°
C. Applicability and Restrictions.
If all the eigenvalues of the original matrix are desired, this subroutine should be followed by COMLR (F295).
If all the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by COMLR2 (F296)o
If some of the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by COMLR (F295), CINVIT (F297), and COMBAK (F283).
In this implementation, the arithmetic is real throughout except for complex division.
3. DISCUSSION OF METHOD AND ALGORITHM.
Suppose that the matrix A has the form
( T X Y ) = (0 B Z)
(0 0 R)
254
7.1-60
where T and R are upper triangular matrices, B is a square matrix situated in rows and columns LOW through IGH, and X, Y, and Z are rectangular matrices of the appropriate dimensions. Then the subroutine COMHES performs permutation and elementary similarity transformations to reduce B to Hessenberg form.
The Hessenberg reduction is performed in the following way. Starting with J=LOW, a permutation similarity transformation is performed to stabilize the succeeding elementary transformations in the J-th column of A. Next, each non- zero element below the subdiagonal in the J-th column of A is eliminated using elementary similarity transformations.
The permutation similarity transformation is determined by searching for the element of maximum modulus in the J-th column below the subdiagonal. This element is placed into the subdiagonal position by a row interchange and the corresponding column interchange is made to complete the permutation transformation. The index of the row interchanged with the (J+l)-th row is stored in INT(J+I).
The elementary transformation consists of elementary row operations on the J-th column of A to eliminate the non- zero elements below the diagonal and the corresponding elementary column operations to complete the similarity. The multipliersused in this elimination process are stored in place of the eliminated elements. These multipliers as well as the row interchanges stored in INT are used later in COMBAK for the back transformation of the eigenvectors.
The above steps are repeated on further columns of the transformed A until B is reduced to Hessenberg form; that is, repeated for J = LOW+I,LOW+2,...,IGH-2.
This subroutine is a translation of the Algol procedure COMHES written and discussed in detail by Martin and Wilkinson (i).
4. REFERENCES.
i) Martin, R.S. and Wilkinson, J.H., Similarity Reduction of a General Matrix to Hessenberg Form, Num. Math. 12,349-368 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinseh, Contribution II/13, 339-358, Springer-Verlag, 1971.)
255
7.1-61
5. CHECKOUT°
A. Test Cases,
See the section discussing testing of the codes for complex general matrices.
B. Accuracy°
The accuracy of COMHES can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of complex general matrices. In these paths, this subroutine is, in practice, numerically stable (i). This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix usually close to the original matrix.
256
7.1-62
SUBROUTINE COMHES(NM,N,LOW, IGH,AR,AI,INT)
INTEGER I,J,M,N,LA,NM, IGH,KPI,LOW,MMI,MPI REAL AR(NM,N),AI(NM,N) REAL XR,XI,YR,YI REAL ABS INTEGER INT(IGH) COMPLEX Z3 COMPLEX CMPLX REAL REAL,AIMAG
LA = IGH - 1 KPI = LOW + 1 IF (LA .LT. KPI) GO TO 200
DO 180 M = KPI, LA MMI = M - 1
XR = 0.0 XI = 0.0 I = M
i00
DO i00 J = M, IGH IF (ABS(AR(J,MMI)) + ABS(AI(J,MMI))
.LE. ABS(XR) + ABS(XI)) GO TO i00 XR = AR(J,MMI) El = AI(J,MMI) I = J
CONTINUE
ii0
INT(M) = I IF (I .EQ. M) GO TO 130
********** INTERCHANGE ROWS AND COLUMNS OF AR AND AI ********** DO II0 J = MMI, N
YR = AR(I,J) AR(I,J) = AR(M,J) AR(M,J) = YR YI = AI(I,J) AI(I,J) = AI(M,J) AI(M,J) = YI
CONTINUE
120
130
DO 120 J = i, IGH YR = AR(J,I) AR(J,I) = AR(J,M) AR(J,M) = YR YI = AI(J,I) AI(J,I) = AI(J,M) AI(J,M) = YI
CONTINUE ********** END INTERCHANGE **********
IF (XR .EQ. 0.0 .AND. XI .EQ. 0.0) GO TO 180 MPI = M + i
257
7.1-63
DO 160 I = MPI, IGH
YR = AR(I,MMI) YI = AI(I,MMI)
IF (YR .EQ. 0.0 .AND. YI .EQ. 0.0) GO TO 160
Z3 = CMPLX(YR,YI) / CMPLX(XR,XI) YR = REAL(Z3) YI = AIMAG(Z3)
AR(I,MMI) = YR
AI(I,MMI) = YI
140
DO 140 J = M, N
AR(I,J) = AR(I,J) - YR * AR(M,J) + YI * AI(M,J)
AI(I,J) = AI(I,J) - YR * AI(M,J) - YI * AR(M,J)
CONTINUE
150
DO 150 J = I~ IGH AR(J,M) = AR(J,M) + YR * AR(J,I) - YI * AI(J,I) AI(J,M) = AI(J,M) + YR * AI(J,I) + YI * AR(J,I)
CONTINUE
160 CONTINUE
180 CONTINUE
200 RETURN
END
258
7.1-64
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F295-2 COMLR
A Fortran IV Subroutine to Determine the Eigenvalues of a Complex Upper Hessenberg Matrix.
May, 1972 July, 1975
I. PURPOSE.
The Fortran IV subroutine COMLR computes the eigenvalues of a complex upper Hessenberg matrix using the modified LR method.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE COMLR(NM,N,LOW, IGH,HR,HI,WR,WI,IERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays HR and HI as specified in the DIMENSION statements for HR and HI in the calling program.
N is an integer input variable set equal to the order of the matrix H = (HR,HI). N must be not greater than NM.
LOW,IGR are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F271 for the details. If the matrix is not balanced, set LOW to 1 and IGH to N.
259
7.1-65
HR,HI
WR,WI
!ERR
are working precision real two-dimensional variables with row dimension NM and column dimension at least N. On input, HR and HI contain the real and imaginary parts, respectively, of the complex upper Hessenberg matrix. Note: COMLR destroys this upper Hessenberg matrix.
are working precision real output one- dimensional variables of dimension at least N containing the real and imaginary parts, respectively, of the eigenvalues of the upper Hessenberg matrix.
is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
B. Error Conditions and Returns.
If more than 30 iterations are required to determine an eigenvalue~ this subroutine terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues in the WR and WI arrays should be correct for indices IERR+I,IERR+2,...,N.
If all the eigenvalues are determined within 30 iterations, IERR is set to zero.
C. Applicability and Restrictions.
To determine some of the eigenvectors of a complex Hessenberg matrix, COMLR should be followed by CiNVIT (F297) to compute those eigenvectors. Note, however, that the upper Hessenberg matrix must be saved before COMLR for later use of CINVIT, since COMLR destroys this upper Hessenberg matrix.
To determine the eigenvalues of a complex general matrix, COMLR should be preceded by COMHES (F282) to provide a suitable complex upper Hessenberg matrix for COMLR.
To determine some of the eigenvectors of a complex general matrix, COMLR should be preceded by COMHES (F282) and followed by CINVlT (F297) and COMBAK (F283). COMBAK back transforms the eigenvectors from CiNVIT into those of the complex general matrix. Note, as above, that the Hessenberg matrix must be saved before COMLR.
260
7.1-66
It is recommended in general that CBAL (F271) be used before COMHES in which case CBABK2 (F272) must be used after COMBAK if eigenvectors are computed.
The subroutine COMLR executes faster than its counterpart COMQR (F245) which uses unitary similarity transformations. COMQR is, however, more accurate in some cases. It is recommended that COMQR be used in general.
In this implementation, the arithmetic is real throughout except for complex square root and complex division.
3. DISCUSSION OF METHOD AND ALGORITHM.
The eigenvalues are determined by the modified LR method. The essence of this method is a process whereby a sequence of complex upper Hessenberg matrices, similar to the original Hessenberg matrix, is formed which converges to a triangular matrix. The factorization of H into upper (R) and lower (L) triangular matrices is stabilized by permutation similarity transformations at each stage. The rate of convergence of this sequence is improved by shifting the origin at each iteration. Before each iteration, the last Hessenberg form is checked for a possible splitting into submatrices. If a splitting occurs, only the lower submatrix participates in the next iteration.
The origin shift at each iteration is the eigenvalue of the lowest 2x2 principal minor closer to the second diagonal element of this minor. Whenever a lowest ixl principal submatrix finally splits from the rest of the matrix, its element is taken to be an eigenvalue of the original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of order I. The tolerances in the splitting tests are proportional to the relative machine precision.
Some of the eigenvalues may have been isolated on the diagonal by the subroutine CBAL (F271). This information is transmitted to COMLR through the parameters LOW and IGH. As a result, COMLR immediately extracts the eigenvalues in rows I to LOW-I and IGH+I to N, and so applies the LR procedure to the submatrix situated in rows and columns LOW through IGH.
This subroutine is a translation of the Algol procedure COMLR written and discussed in detail by Martin and Wilkinson (I).
261
7.1-67
4. REFERENCES.
1) Martin~ R.S. and Wilkinson, J.H., The Modified LR Algorithm for Complex Hessenberg Matrices, Num. Math. 12,369-376 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/16, 396-4039 Springer-Verlag, 1971.)
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for complex general matrices.
B. Accuracy°
The subroutine COMLR is usually numerically stable (I); that is, each computed eigenvalue is exact for a matrix usually close to the original upper Hessenberg matrix.
262
7.1-68
C C C C C
C
C
C C
SUBROUTINE COMLR(NM,N,LOW,IGH,HR,HI,WR,WI,IERR)
INTEGER I,J,L,M,N,EN,LL,MM,NM, IGH,IMI,ITS,LOW,MPI,ENMI,IERR REAL HR(NM,N),HI(NM,N),WR(N),WI(N) REAL SI,SR,TI,TR,XI,XR,YI,YR,ZZI,ZZR,MACHEP REAL ABS COMPLEX Z3 COMPLEX CSQRT,CMPLX REAL REAL,AIMAG
********** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.
MACHEP = ?
IERR = 0 ********** STORE ROOTS ISOLATED BY CBAL ********** DO 200 I = i, N
IF (I .GE. LOW .AND. I .LE. IGH) GO TO 200 WR(1) = HR(l,l) WI(1) = HI(I,I)
200 CONTINUE
EN = IGH TR = 0.0 TI = 0.0 ********** SEARCH FOR NEXT EIGENVALUE **********
220 IF (EN .LT. LOW) GO TO I001 ITS = 0 ENMI = EN - i ********** LOOK FOR SINGLE SMALL SUB-DIAGONAL ELEMENT
FOR L=EN STEP -i UNTIL LOW -- ********** 240 DO 260 LL = LOW, EN
L = EN + LOW - LL IF (L .EQ. LOW) GO TO 300 IF (ABS(HR(L,L-I)) + ABS(HI(L,L-I)) .LE.
X MACHEP * (ABS(HR(L-I,L-I)) + ABS(HI(L-I,L-I)) X + ABS(HR(L,L)) + ABS(HI(L,L)))) GO TO 300
260 CONTINUE ********** FORM SHIFT **********
300 IF (L .EQ. EN) GO TO 660 IF (ITS .EQ. 30) GO TO I000 IF (ITS .EQ. I0 .OR. ITS .EQ. 20) GO TO 320 SR = HR(EN,EN) SI = HI(EN,EN) XR = HR(ENMI,EN) * HR(EN,ENMI) - HI(ENMI,EN) * HI(EN,ENMI) XI = HR(ENMI,EN) * HI(EN,ENMI) + HI(ENMI,EN) * HR(EN,ENMI) IF (XR .EQ. 0.0 .AND. XI .EQ. 0.0) GO TO 340 YR = (HR(ENMI,ENMI) - SR) / 2.0 YI = (HI(ENMI,ENMI) - SI) / 2.0 Z3 = CSQRT(CMPLX(YR**2-YI**2+XR,2.0*YR*YI+XI)) ZZR = REAL(Z3) ZZI = AIMAG(Z3)
263
7 . 1 - 6 9
C
C
IF (YR * ZZR + YI * ZZI ,GE. 0.0) GO TO 310
ZZR = -ZZR ZZI = -ZZI
310 Z3 = CMPLX(XR,XI) / CMPLX(YR+ZZR,YI+ZZI)
SR = SR - REAL(Z3) SI = SI - AIMAG(Z3)
GO TO 340 • ********* FORM EXCEPTIONAL SHIFT **********
320 SR = ABS(HR(EN,ENMI)) + ABS(HR(ENMI,EN-2))
SI = ABS(HI(EN,ENMI)) + ABS(HI(ENMI,EN-2))
340 DO 360 1 = LOW, EN
HR(I,I) = HR(I,I) - SR HI(I,I) = HI(I,I) - SI
360 CONTINUE
TR = TR + SR
TI = TI + SI
ITS = ITS + 1 *~******** LOOK FOR TWO CONSECUTIVE SMALL
SUB-DIAGONAL ELEMENTS **********
XR = ABS(HR(ENMI,ENMI)) + ABS(HI(ENMI,ENMI))
YR = ABS(HR(EN,ENMI)) + ABS(HI(EN,ENMI))
ZZR = ABS(HR(EN,EN)) + ABS(HI(EN,EN)) ********** FOR M=EN-! STEP -I UNTIL L DO -- **********
DO 380 MM = L~ ENMI M = ENMI + L - MM
IF (M .EQ, L) GO TO 420
YI = YR YR = ABS(HR(M,M-I)) + ABS(HI(M,M-I))
XI = ZZR ZZR = XR XR = ABS(HR(M-I,M-I)) + ABS(HI(M-I,M-I)) IF (YR .LE. MACHEP * ZZR / YI * (ZZR + XR + XI)) GO TO 420
380 CONTINUE ********** TRIANGULAR DECOMPOSITION H=L*R **********
420 MPI = M + i
440
DO 520 ! = MPI, EN IMI = I - 1
XR = HR(IMI,IMI) XI = HI(IMI,IMI) YR = HR(I,IMI)
YI = RI(~I IMl) IF (ABS(XR) + ABS(XI) .GE. ABS(YR) + ABS(YI)) GO TO 460
********** INTERCHANGE ROWS OF HR AND HI **********
DO 440 J = IMI, EN ZZR = HR(IMI,J) HR(iMI ,J) = HR(I, J) HR(I, J) = ZZR ZZI = HI(IMI,J) HI (IMI,J) = HI (I, J) HI(I,J) = ZZI
CONTINUE
264
7. 1-70
460
480
Z3 = CMPLX(XR, XI) / CMPLX(YR,YI) WR(1) = 1.0 GO TO 480 Z3 = CMPLX(YR,YI) / CMPLX(XR,XI) WR(I) = -I.0 ZZR = REAL(Z3) ZZI = AIMAG(Z3) HR(I,IMI) = ZZR HI(I,IMI) = ZZI
500
DO 500 J = I, EN HR(I,J) = HR(I,J) - ZZR * HR(IMI,J) + ZZI * HI(IMI,J) HI(I,J) = HI(I,J) - ZZR * HI(IMI,J) - ZZI * HR(IMI,J)
CONTINUE
520 CONTINUE ********** COMPOSITION R*L=H ********** DO 640 J = MPI, EN
XR = HR(J,J-I) XI = Hl(J,J-l) HR(J,J-I) = 0.0 HI(J,J-I) = 0.0
********** INTERCHANGE COLUMNS OF HR AND HI, IF NECESSARY **********
IF (WR(J) .LE. 0.0) GO TO 580
540
DO 540 I = L, J ZER = HR(I,J-I) HR(I,J-I) = HR(I,J) HR(I,J) = ZZR ZZI = HI(I,J-I) HI(I,J-I) = HI(I,~) HI(I,J) = ZZI
CONTINUE
580
600
DO 600 I = L, J HR(I,J-I) = HR(I,J-I) + XR * HR(I,J) - XI * Hl(l,J) HI(I,J-I) = HI(I,J-I) + XR * HI(I,J) + XI * HR(I,J)
CONTINUE
640 CONTINUE
GO TO 240 ********** A ROOT FOUND **********
660 WR(EN) = HR(EN,EN) + TR WI(EN) = HI(EN,EN) + TI EN = ENMI GO TO 220
C ********** SET ERROR -- NO CONVERGENCE TO AN C EIGENVALUE AFTER 30 ITERATIONS ********** I000 IERR = EN i001 RETURN
END
265
7.1-71
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (E!SPACK)
F296-2 COMLR2
A Fortran IV Subroutine to Determine the Eigenvalues and Eigenvectors of a Complex Upper Hessenberg Matrix.
May, 1972 July, 1975
i. PURPOSE.
The Fortran IV subroutine COMLR2 computes the eigenvalues and eigenvectors of a complex upper Hessenberg matrix. COMLR2 uses the modified LR method to compute the eigenvalues and accumulates the LR transformations to compute the eigenvectors. The eigenvectors of a complex general matrix can also be computed directly by COMLR2, if COMHES (F282) has been used to reduce this matrix to Hessenberg form.
2. USAGE.
A. Calling Sequence°
The SUBROUTINE statement is
SUBROUTINE COMLR2(NM,N,LOW,IGH, INT,HR,HI, WR,WI,ZR,ZI,IERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays HR, HI, ZR, and ZI as specified in the DIMENSION statements for HR, HI, ZR, and ZI in the calling program.
is an integer input variable set equal to the order of the matrix H = (HR,HI). N must be not greater than NM.
266
7.1-72
LOW,IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F271 for the details. If the matrix is not balanced, set LOW to i and IGH to N.
INT is an integer input one-dimensional variable of dimension at least IGH. Only components LOW through IGH are used by COMLR2. If the eigenvectors of the Hessenberg matrix are desired, set INT(J)=J for J = LOW,LOW+I,...,IGH. If the eigenvectors of a complex general matrix are desired, INT contains information saved by COMHES identifying the rows and columns interchanged during the reduction to Hessenberg form.
HR,HI are working precision real two-dimensional variables with row dimension NM and column dimension at least N. On input, HR and HI contain the real and imaginary parts, respectively, of the complex upper Hessenberg matrix. If the eigenvectors of the Hessenberg matrix are desired, set the lower triangles of HR,HI below the subdiagonal to zero. If the eigenvectors of a complex general matrix are desired, the lower triangles of HR,HI contain the multipliers which are generated by COMHES in the reduction to the Hessenberg form. Note: COMLR2 destroys the upper Hessenberg portions of HR,HI, but returns in location HR(I,I) the norm of the triangularized matrix. See section 2C for the definition and significance of this quantity.
WR,WI are working precision real output one- dimensional variables of dimension at least N containing the real and imaginary parts, respectively, of the eigenvalues of the upper Hessenberg matrix.
ZR,ZI are working precision real output two- dimensional variables with row dimension NM and column dimension at least N containing the real and imaginary parts, respectively, of the eigenvectors. The eigenvectors are not normalized.
267
7. 1-73
IERR is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
B. Error Conditions and Returns.
If more than 30 iterations are required to determine an eigenvalue, this subroutine terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues in the WR and WI arrays should be correct for indices IERR+I,IERR+2,...,N, hut no eigenvectors are computed.
If all the eigenvalues are determined within 30 iterations, IERR is set to zero.
C. Applicability and Restrictions.
To determine the eigenvalues and eigenvectors of a complex general matrix, COMLR2 must be preceded by COMHES (F282) to provide a suitable complex Hessenberg matrix for COMLR2.
It is recommended in general that CBAL (F271) before COMHES in which case CBABK2 (F272) used after COMLR2.
be used must be
The subroutine COMLR2 may occasionally return poor results, especially in the eigenvectors, due to pronounced growth in the matrix elements that may occur during the LR iterations. A measure of this growth can be obtained from a comparison of the norm quantity returned in HR(I,I), defined as the sum of the absolute values of the real and imaginary components of all the elements of the triangularized matrix, with the corresponding norm of the vector of eigenvalues. This growth cannot occur in the QR algorithm embodied in subroutine COMQR2 (F246), the unitary counterpart of COMLR2. It is recommended that COMQR2, although slower, be used in general.
In this implementation, the arithmetic is real throughout except for complex square root and complex division.
268
7.1-74
3. DISCUSSION OF METHOD AND ALGORITHM.
The eigenvalues are determined by the modified LR method. The essence of this method is a process whereby a sequence of complex upper Hessenberg matrices, similar to the original Hessenberg matrix, is formed which converges to a triangular matrix. The factorization of H into upper (R) and lower (L) triangular matrices is stabilized by permutation similarity transformations at each stage. The rate of convergence of this sequence is improved by shifting the origin at each iteration. Before each iteration, the last Hessenberg form is checked for a possible splitting into submatrices. If a splitting occurs, only the lower submatrix participates in the next iteration. The similarity transformations used in each iteration are accumulated in the ZR and ZI arrays along with the reduction transformations for the original matrix.
The origin shift at each iteration is the eigenvalue of the lowest 2x2 principal minor closer to the second diagonal element of this minor. Whenever a lowest ixl principal submatrix finally splits from the rest of the matrix, its element is taken to be an eigenvalue of the original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of order I. The tolerances in the splitting tests are proportional to the relative machine precision. The eigenvectors of this triangular matrix are determined by back substitution, and then back transformed into those of the original matrix.
Some of the eigenvalues may have been isolated on the diagonal by the subroutine CBAL (F271). This information is transmitted to COMLR2 through the parameters LOW and IGH. As a result, COMLR2 immediately extracts the eigenvalues in rows 1 to LOW-I and IGH+I to N, and so applies the LR procedure to the submatrix situated in rows and columns LOW through IGH.
This subroutine is a translation of the Algol procedure COMLR2 written and discussed in detail by Peters and Wilkinson (i).
4. REFERENCES.
i) Peters, G. and Wilkinson, J.H., Eigenveotors of Real and Complex Matrices by LR and QR Triangularizations, Num. Math. 16,181-204 (1970). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/15, 372-395, Springer-Verlag, 1971.)
269
7.1-75
5. CHECKOUT.
A. Test Cases°
See the section discussing testing of the codes for complex general matrices.
B. Accuracy.
The subroutine COMLR2 is usually numerically stable (I); that is, each computed eigenvalue and its corresponding eigenvector are exact for a matrix usually close to the original upper Hessenberg matrix.
270
7.1-76
SUBROUTINE COMLR2(NM,N~LOW~IGH, INT,HR, HI,WR,WI,ZR,ZI,IERR)
INTEGER I,J,K,L,M,N,EN,II,JJ,LL,MM,NM,NN, IGH, IMI,IPI, X ITS,LOW,MPI,ENMI,IEND,IERR REAL HR(NM,N),HI(NM,N),WR(N),WI(N),ZR(NM, N),ZI(NM,N) REAL SI,SR,TI,TR,XI,XR,YI,YR,ZZI,ZZR,NORM,MACHEP REAL ABS INTEGER INT(IGH) INTEGER MIN0 COMPLEX Z3 COMPLEX CSQRT,CMPLX REAL REAL,AIMAG
********** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.
MACHEP = ?
IERR = 0
**~******* INITIALIZE EIGENVECTOR MATRIX ********** DO i00 I = 19 N
DO I00 J = i, N ZR(I,J) = 0.0 zi(I,J) = o.o
IF (l .EQ. J) ZR(I,J) = 1.0 i00 CONTINUE
********** FORM THE MATRIX OF ACCUMULATED TRANSFORMATIONS FROM THE INFORMATION LEFT BY COMHES **~*******
1END = IGH - LOW - i IF (1END .LE. O) GO TO 180 ********** FOR I=IGH-I STEP -I UNTIL LOW+I DO -- ********** DO 160 II = i, 1END
I = IGH - II IPI = I + i
120
DO 120 K = IPI, IGH ZR(K,I) = HR(K,I-I) ZI(K,I) = HI(K,I-I)
CONTINUE
J = INT(1)
IF (I .EQ. J) GO TO 160
140
DO 140 K = I, IGH ZR(I,K) = ZR(J,K) ZI(I,K) = ZI(J,K) ZR(J,K) = 0.0 ZI(J,K) = 0.0
CONTINUE
ZR(~,I) = 1.0 160 CONTINUE
271
7.1-77
********** STORE ROOTS ISOLATED BY CBAL **********
180 DO 200 1 = i, N IF (! .GE. LOW .AND, I .eE. IGH) GO TO 200
WR(I) = HR(I,I) WI(I) = HI(I,I)
200 CONTINUE
EN = IGH TR = 0.0 TI = 0.0
C ********** SEARCH FOR NEXT EIGENVALUE **********
"220 IF (EN .LT. LOW) GO TO 680
ITS = 0 ENMI = EN - I
C ********** LOOK FOR SINGLE SMALL SUB-DIAGONAL ELEMENT C FOR L=EN STEP -i UNTIL LOW DO -- **********
240 DO 260 LL = LOW, EN L = EN + LOW - LL IF (L .EQ. LOW) GO TO 300 IF (ABS(HR(L,L-I)) + ABS(HI(L,L-I)) .LE.
X MACHEP * (ABS(HR(L-I,L-I)) + ABS(HI(L-I,L-I)) X + ABS(HR(L,L)) + ABS(HI(L,L)))) GO TO 300
260 CONTINUE C ********** FORM SHIFT **********
300 IF (L .EQ. EN) GO TO 660 IF (rTS .EQo 30) GO TO i000 IF (ITS .EQ. i0 .OR. ITS .EQ. 20) GO TO 320
SR = HR(EN,EN) SI = HI(EN,EN) XR = HR(ENMI,EN) * HR(EN,ENMI) - HI(ENMI,EN) * HI(EN,ENMI) XI = HR(ENMI,EN) * HI(EN,ENMI) + HI(ENMI,EN) * HR(EN,ENMI) IF (XR .EQ. 0.0 .AND. XI .EQ. 0.0) GO TO 340
YR = (HR(ENMI,ENMI) - SR) / 2.0 YI = (HI(ENMI,ENMI) - SI) / 2.0 Z3 = CSQRT(CMPLX(YR**2-YI**2+XR,2.0*YR*YI+XI))
ZZR = REAL(Z3) ZZI = AIMAG(Z3) IF (YR * ZZR + YI * ZZI .GE. 0.0) GO TO 310
ZZR = -ZZR ZZI = -ZZI
310 Z3 = CMPLX(XR,XI) / CMPLX(YR+ZZR,YI+ZZI)
SR = SR - REAL(Z3) SI = SI - AIMAG(Z3) GO TO 340
C ********** FORM EXCEPTIONAL SHIFT ********** 320 SR = ABS(HR(EN,ENMI)) + ABS(HR(ENMI,EN-2))
SI = ABS(HI(EN,ENMI)) + ABS(HI(ENMI,EN-2))
340 DO 360 I = LOW, EN HR(I,I) = HR(I,I) - SR H!(i,l) = HI(I,I) - SI
360 CONTINUE
272
7 . 1 - 7 8
TR = TR + SR
TI = TI + SI
ITS = ITS + 1 ********** LOOK FOR TWO CONSECUTIVE SMALL
SUB-DIAGONAL ELEMENTS ********** XR = ABS(HR(ENMI,ENMI)) + ABS(HI(ENMI,ENMI)) YR = ABS(HR(EN,ENMI)) + ABS(HI(EN,ENMI))
ZZR = ABS(HR(EN,EN)) + ABS(HI(EN,EN))
********** FOR M=EN-I STEP -I UNTIL L DO -- ********** DO 380 MM = L, ENMI
M = ENMI + L - MM
IF (M .EQ. L) GO TO 420 YI = YR
YR = ABS(HR(M,M-I)) + ABS(HI(M,M-I)) XI = ZZR
ZZR = XR
XR = ABS(HR(M-I,M-I)) + ABS(HI(M-I,M-I))
IF (YR .LE. MACHEP * ZZR / YI * (ZZR + XR + XI)) GO TO 420 380 CONTINUE
********** TRIANGULAR DECOMPOSITION H=L*R ********** 420 MPI = M + i
440
DO 520 I = MPI, EN IMI = I - 1 XR = HR(IMI,IMI)
Xl = HI(IMI,IMI)
YR = HR(I,IMI) YI = HI(I,IMI)
IF (ABS(XR) + ABS(XI) .GE. ABS(YR) + ABS(YI)) GO TO 460 ********** INTERCHANGE ROWS OF HR AND HI **********
DO 440 J = IMI, N ZZR = HR(IMI,J) HR(IMI,J) = HR(I,J)
HR(I,J) = ZZR ZZI = HI(IMI,J) H!(IMI,J) = HI(I,J)
HI(I,J) = ZZI CONTINUE
460
480
Z3 = CMPLX(XR,XI) / CMPLX(YR,YI) WR(1) -- i. 0 GO TO 480
Z3 = CMPLX(YR,YI) / CMPLX(XR, XI) WR(I) = -i.0 ZZR = REAL(Z3)
ZZI = AIMAG(Z3) HR(I,IMI) = ZZR HI(I,IMI) = ZZI
500
DO 500 J = I, N
HR(I,J) = HR(I,J) - ZZR * HR(IMI,J) + ZZI * HI(IMI,J)
HI(I,J) = HI(I,J) - ZZR * HI(IMI,J) - ZZI * HR(IMI,J) CONTINUE
273
7.1-79
C
C
C
C
C
520 CONTINUE
********** COMPOSITION R*L=H ********** DO 640 J = MPI, EN
XR = HR(J,J-I)
XI = HI(J,J-I) HR(J,J-I) = 0.0
HI(J,J-I) = 0.0
********** INTERCHANGE COLUMNS OF HR, HI, ZR, AND ZI,
IF NECESSARY **********
IF (WR(J) .LE. 0.0) GO TO 580
540
DO 540 1 = i, J ZZR = HR(I,J-I)
HR(I,J-I) = HR(I,J)
HR(I,J) = ZZR ZZI = HI(I,J-I) HI(I,J-I) = HI(I,J)
HI(I,J) = ZZI CONTINUE
560
DO 560 I = LOW, IGH ZZR = ZR(I,J-I)
ZR(I,J-I) = ZR(I,J)
ZR(I,J) = ZZR ZZ! = ZI(I,J-I)
zI(i,J-1) = zI(i,J) ZI(I,J) = ZZ!
CONTINUE
580 DO 600 I = i, J HR(I,J-I) = HR(I,J-I) + XR * HR(I,J) - XI * HI(I,J) H!(I,J-!) = HI(I,J-I) + XR * HI(I,J) + XI * HR(I,J)
600 CONTINUE
• ********* ACCUMULATE TRANSFORMATIONS ********** DO 620 I = LOW, IGH
ZR(I,J-I) = ZR(I,J-I) + XR * ZR(I,J) - XI * ZI(I,J) Zi(I,J-I) = ZI(I,J-I) + XR * ZI(I,J) + XI * ZR(I,J)
620 CONTINUE
640 CONTINUE
GO TO 240 ********** A ROOT FOUND **********
660 HR(EN,EN) = HR(EN,EN) + TR WR(EN) = HR(EN,EN)
HI(EN,EN) = HI(EN,EN) + TI WI(EN) = Hi(EN,EN) EN = ENMI GO TO 220 ********** ALL ROOTS FOUND.
680 NORM = 0.0
BACKSUBSTITUTE TO FIND
VECTORS OF UPPER TRIANGULAR FORM **********
274
7. 1-80
DO 720 1 = I, N
DO 720 J = I, N NORM = NORM + ABS(HR(I,J)) + ABS(RI(I,J))
720 CONTINUE
HR(I,I) = NORM
IF (N .EQ. i .OR. NORM .EQ. 0.0) GO TO i001
********** FOR EN=N STEP -i UNTIL 2 DO -- ********** DO 800 NN = 2, N
EN = N + 2 - NN
XR = WR(EN)
XI = WI(EN)
ENMI = EN - i
********** FOR I=EN-I STEP -I UNTIL I DO -- **********
DO 780 II = I, ENMI I = EN - II
ZZR = HR(I,EN) ZZI = HI(I,EN)
IF (I .EQ. ENMI) GO TO 760 IPI = I + i
740
DO 740 J = IPI, ENMI
ZZR = ZZR + HR(I,J) * HR(J,EN) - HI(I,J) * HI(J,EN) ZZI = ZZI + HR(I,J) * HI(J,EN) + HI(I,J) * HR(J,EN)
CONTINUE
760
780
YR = XR - WR(1)
YI = XI - WI(1)
IF (YR .EQ. 0.0 .AND. YI .EQ. 0.0) YR = MACHEP * NORM Z3 = CMPLX(ZZR, ZZI) / CMPLX(YR,YI) HR(I,EN) = REAL(Z3) HI(I,EN) = AIMAG(Z3)
CONTINUE
C 800 CONTINUE
C ********** END BACKSUBSTITUTION ********** ENMI = N - i
C ********** VECTORS OF ISOLATED ROOTS ********** DO 840 I = I, ENMI
IF (I .GE. LOW .AND. I .LE. IGH) GO TO 840 IPI = I + 1
820
DO 820 J = IPI, N
ZR(I,J) = HR(I,J) zi(i,J) = HI(I,J)
CONTINUE
840 CONTINUE
275
7, 1-81
********** MULTIPLY BY TRANSFORMATION MATRIX TO GIVE
VECTORS OF ORIGINAL FULL MATRIX.
FOR J=N STEP -i UNTIL LOW+I DO -- **********
DO 880 JJ = LOW, ENMI
J = N + LOW - JJ
M = MIN0(J-I,IGH)
DO 880 i = LOW, IGH
ZZR = ZR(I,J)
ZZI = ZI(I,J)
860
DO 860 K = LOW, M
ZZR = ZZR + ZR(I,K) * HR(K,J) - ZI(I,K) * HI(K,J)
ZZI = ZZI + ZR(I,K) * HI(K,J) + ZI(I,K) * HR(K,J)
CONTINUE
ZR(I,J) = ZZR
ZI(i,J) = ZZI
880 CONTINUE
GO TO I001
C ********** SET ERROR -- NO CONVERGENCE TO AN
C EIGENVALUE AFTER 30 ITERATIONS **********
i000 IERR = EN
i001 RETURN
END
276
7,1-82
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F245 COMQR
A Fortran IV Subroutine to Determine the Eigenvalues of a Complex Upper Hessenberg Matrix.
July, 1975
!. PURPOSE.
The Fortran IV subroutine COMQR computes the eigenvalues of a complex upper Hessenberg matrix using the QR method.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE COMQR(NM~N,LOW,IGH,HR,HI~WR,WI,IERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays HR and HI as specified in the DIMENSION statements for HR and HI in the calling program.
is an integer input variable set equal to the order of the matrix H = (HR,HI). N must be not greater than NM.
LOW, IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F271 for the details. If the matrix is not balanced, set LOW to 1 and IGH to N.
277
7 . 1 - 8 3
HR,H!
WR,WI
IERR
are working precision real two-dimensional variables with row dimension NM and column dimension at least N. On input, HR and HI contain the real and imaginary parts, respectively, of the complex upper Hessenberg matrix. Note: COMQR destroys this upper Hessenberg matrix.
are working precision real output one- dimensional variables of dimension at least N containing the real and imaginary parts, respectively, of the eigenvalues of the upper Hessenberg matrix.
is an integer output variable set equal to an error completion code described in section 2B° The normal completion code is zero.
B. Error Conditions and Returns.
If more than 30 iterations are required to determine an eigenva!ue, this subroutine terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues in the WR and WI arrays should be correct for indices IERR+I,IERR+2,...,N.
If all the eigenvalues are determined within 30 iterations, IERR is set to zero.
C. Applicability and Restrictions.
To determine some of the eigenvectors of a complex Hessenberg matrix, COMQR should be followed by CINVIT (F297) to compute those eigenvectors. Note, however, that the upper Hessenberg matrix must be saved before COMQR for later use of CINVIT, since COMQR destroys this upper Hessenberg matrix.
To determine the eigenvalues of a complex general matrix, COMQR should be preceded by CORTH (F244) to provide a suitable complex upper Hessenberg matrix for COMQR.
To determine some of the eigenvectors of a complex general matrix, COMQR should be preceded by CORTH (F244) and followed by CINVIT (F297) and CORTB (F247). CORTB back transforms the eigenvectors from CINVIT into those of the complex general matrix. Note, as above, that the Hessenberg matrix must be saved before COMQR.
278
7.1-84
It is recommended in general that CBAL (F271) be used before CORTH in which case CBABK2 (F272) must be used after CORTB if eigenvectors are computed.
In this implementation, the arithmetic is real throughout except for complex square root and complex division.
3. DISCUSSION OF METHOD AND ALGORITHM.
The eigenvalues are determined by the QR method. The essence of this method is a process whereby a sequence of complex upper Hessenberg matrices, similar to the original Hessenberg matrix, is formed which converges to a triangular matrix. The rate of convergence of this sequence is improved by shifting the origin at each iteration. Before each iteration, the last Hessenberg form is checked for a possible splitting into submatrices. If a splitting occurs, only the lower submatrix participates in the next iteration.
The origin shift at each iteration is the eigenvalue of the lowest 2x2 principal minor closer to the second diagonal element of this minor. Whenever a lowest ixl principal submatrix finally splits from the rest of the matrix, its element is taken to be an eigenvalue of the original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of order i. The tolerances in the splitting tests are proportional to the relative machine precision.
The subdiagonal elements are rendered real initially by a diagonal unitary similarity transformation and maintained real throughout COMQR.
Some of the eigenvalues may have been isolated on the diagonal by the subroutine CBAL (F271). This information is transmitted to COMQR through the parameters LOW and IGH. As a result, COMQR immediately extracts the eigenvalues in rows i to LOW-1 and IGH+I to N, and so applies the QR procedure to the submatrix situated in rows and columns LOW through IGH.
This subroutine is a translation of a unitary analogue of the Algol procedure COMLR written and discussed in detail by Martin and Wilkinson (i). The unitary analogue substitutes for the LR algorithm the QR algorithm, written and discussed in detail by Francis (2).
279
7.1-85
4. REFERENCES.
i) Martin, RoS. and Wilkinson, J.H., The Modified LR Algorithm for Complex Hessenberg Matrices, Num. Math. 12,369-376 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/16, 396-403, Springer-Verlag, 1971.)
2) Francis, J.G.F., The QR Transformation - Parts 1 and 2, Comp. J. 4,265-271 and 332-345 (1961/62).
5. CHECKOUT.
A. Test Cases°
See the section discussing testing of the codes for complex general matrices.
B. Accuracy~
The subroutine COMQR is numerically stable (1,2); that is, each computed eigenvalue is exact for a matrix close to the original upper Hessenberg matrix.
280
7. 1-86
SUBROUTINE COMQR(NM,N,LOW,IGH,HR,HI,WR,WI,IERR)
INTEGER I,J,L,N,EN,LL,NM,IGH, ITS,LOW~LPI,ENMI,IERR REAL HR(NM,N),HI(NM,N),WR(N),WI(N) REAL SI,SR,TI,TR,XI,XR,YI,YR,ZZI,ZZR,NORM,MACHEP REAL SQRT~CABS,ABS INTEGER MIN0 COMPLEX Z3 COMPLEX CSQRT,CMPLX REAL REAL,AIMAG
********** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.
**********
MACHEP = ?
IERR = 0 IF (LOW .EQ. IGH) GO TO 180 ********** CREATE REAL SUBDIAGONAL ELEMENTS ********** L = LOW + I
DO 170 1 = L, IGH LL = MIN0(I+I,IGH) IF (HI(I,I-I) .EQ. 0.0) GO TO 170 NORM = CABS(CMPLX(HR(I,I-I),HI(I,I-I))) YR = HR(I,I-I) / NORM YI = HI(I,I-I) / NORM HR(I,I-I) = NORM HI(I,I-I) : 0.0
155
DO 155 J = I, IGH SI = YR * HI(I,J) - YI * HR(I,J) HR(I,J) : YR * HR(I,J) + YI * HI(I,J) HI(I,J) : SI
CONTINUE
160
DO 160 J = LOW, LL
SI = YR * HI(J,I) + YI * HR(J,I) HR(J,I) = YR * HR(J,I) - YI * HI(J,I) HI(J,I) = SI
CONTINUE
170 CONTINUE
********** STORE ROOTS ISOLATED BY CBAL ********** 180 DO 200 I = i, N
IF (I .GE. LOW .AND. I .LE. IGH) GO TO 200 WR(1) = HR(I,I) WI(I) = HI(I,I)
200 CONTINUE
EN = IGH TR = 0.0 TI = 0.0
281
7.1-87
C ********** SEARCH FOR NEXT EIGENVALUE ********** 220 IF (EN .LT. LOW) GO TO i001
ITS = 0 ENMI = EN - 1
C ********** LOOK FOR SINGLE SMALL SUB-DIAGONAL ELEMENT C FOR L=EN STEP -i UNTIL LOW -- **********
240 DO 260 LL = LOW, EN L = EN + LOW - LL IF (L .EQ. LOW) GO TO 300 IF (ABS(HR(L,L-I)) .LE.
X MACHEP * (ABS(HR(L-I,L-I)) + ABS(HI(L-I,L-I)) X + ABS(HR(L,L)) +ABS(HI(L,L)))) GO TO 300
260 CONTINUE
C ********** FORM SHIFT ********** 300 IF (L .EQ. EN) GO TO 660
IF (ITS .EQ. 30) GO TO I000 IF (ITS .EQ. I0 .OR. ITS .EQ. 20) GO TO 320 SR = HR(EN,EN) SI = HI(EN,EN) XR = HR(ENMI,EN) * HR(EN,ENMI) XI = HI(ENMI,EN) * HR(EN,ENMI) IF (XR .EQ. 0.0 .AND. XI .EQ. 0.0) GO TO 340 YR = (HR(ENMI,ENMI) - SR) / 2.0 YI = (HI(ENMI,ENMI) - SI) / 2.0 Z3 = CSQRT(CMPLX(YR**2-YI**2+XR,2.0*YR*YI+XI)) ZZR = REAL(Z3) ZZI = AIMAG(Z3) IF (YR * ZZR + YI * ZZI .GE. 0.0) GO TO 310
ZZR = -ZZR ZZI = -ZZI
310 Z3 = CMPLX(XR,XI) / CMPLX(YR+ZZR,YI+ZZI) SR = SR - REAL(Z3)
SI = SI - AIMAG(Z3) GO TO 340
C ********** FORM EXCEPTIONAL SHIFT ********** 320 SR = ABS(HR(EN,ENMI)) + ABS(HR(ENMI,EN-2))
Sl = 0.0
340 DO 360 1 = LOW, EN HR(l,l) = N R ( I , I ) - SR HI(I,I) = HI(I,I) - SI
360 CONTINUE
TR = TR + SR T! = TI + SI ITS = ITS + 1 ********** REDUCE TO TRIANGLE (ROWS) **********
LPI = L + 1
282
7.1-88
DO 500 I = LPI, EN
SR = HR(I,I-I)
HR(I,I-I) = 0.0
NORM = SQRT(HR(I-I,I-I)*HR(I-I,I-I)+HI(I-I,I-I)*HI(I-I,I-I)
+SR*SR)
XR = HR(I-I,I-I) / NORM
WR(I-I) = XR
XI = HI(I-I,I-I) / NORM
wi(i-1) = El HR(I-I,I-I) = NORM
HI(I-I,I-I) = 0.0
HI(I,I-I) = SR / NORM
490
DO 490 J = I, EN
YR = HR(I-I,J)
YI = HI(I-I,J)
ZZR = HR(I,J)
ZZI = HI(I,J)
HR(I-I,J) = XR * YR + XI * YI + HI(I,I-I) * ZZR
HI(I-I,J) = XR * YI - XI * YR + HI(I,I-I) * ZZI
HR(I,J) = XR * ZZR - Xl * ZZI - HI(I,I-I) * YR
~l(l,J) = XR * ZZI + Xl ~ ZZR - HI(I,I-I) * YI
CONTINUE
500 CONTINUE
SI = HI(EN,EN)
IF (Sl .EQ. 0.0) GO TO 540
NORM = CABS(CMPLX(HR(EN,EN),SI))
SR = HR(EN,EN) / NORM
SI = SI / NORM
HR(EN,EN) = NORM
HI(EN,EN) = 0.0
********** INVERSE OPERATION (COLUMNS) ****~*****
540 DO 600 J = LPI, EN
XR = WR(J-I)
XI = WI(J-I)
560
580
DO 580 I = L, J
YR = HR(I,J-I)
YI = 0.0
ZZR = HR(I,J)
ZZI = HI(I,J)
IF (I .EQ. J) GO TO 560
YI = HI(I,J-I)
HI(I,J-I) = XR * YI + XI ~ YR + HI(J,J-I) * ZZI
HR(I,J-I) = XR * YR - XI * YI + HI(J,J-I) * ZZR
HR(I,J) = XR * ZZR + Xl * ZZI - HI(J,J-I) * YR
HI(I,J) = XR * ZZI - XI * ZZR - HI(J,J-I) * YI CONTINUE
600 CONTINUE
283
7. 1-89
IF (SI .EQ~ 0.0) GO TO 240
DO 630 I = L, EN YR = HR(I,EN)
Yi = HI(I,EN)
HR(I,EN) = SR * YR - SI * YI HI(I,EN) = SR * YI + SI * YR
630 CONTINUE
GO TO 240 ********** A ROOT FOUND **********
660 WR(EN) = HR(EN,EN) + TR
WI(EN) = HI(EN,EN) + TI
EN = ENMI
GO TO 220 C ********** SET ERROR -- NO CONVERGENCE TO AN
C EIGENVALUE AFTER 30 ITERATIONS **********
I000 IERR = EN
I001 RETURN
END
284
7.1-90
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F246 COMQR2
A Fortran IV Subroutine to Determine the Eigenvalues and Eigenvectors of a Complex Upper Hessenberg Matrix.
July , 1975
I. PURPOSE.
The Fortran IV subroutine COMQR2 computes the eigenvalues and eigenvectors of a complex upper Hessenberg matrix. COMQR2 uses the QR method to compute the eigenvalues and accumulates the QR transformations to compute the eigenvectors. The eigenvectors of a complex general matrix can also be computed directly by COMQR2, if CORTH (F244) has been used to reduce this matrix to Hessenberg form.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE COMQR2(NM,N,LOW,IGH,ORTR,ORTI,HR,HI, WR,WI,ZR,ZI,IERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays HR, HI, ZR, and ZI as specified in the DIMENSION statements for HR, HI, ZR, and ZI in the calling program.
is an integer input variable set equal to the order of the matrix H = (HR,HI). N must be not greater than NM.
LOW,IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F271 for the details. If the matrix is not balanced, set LOW to 1 and IGH to N.
285
7 . 1 - 9 1
ORTR,ORT! are working precision real one-dimensional variables of dimension at least IGH. Only components LOW through IGH are used by COMQR2. If the eigenvectors of the Hessenberg matrix are desired, set ORTR(J)=ORTI(J)=0.0 for J = LOW,LOW+I,..°,IGH. If the eigenvectors of a complex general matrix are desired, ORTR and ORTI contain some information about the unitary transformations generated by CORTH during the reduction to the Hessenberg form.
HR,HI are working precision real two-dimensional variables with row dimension NM and column dimension at least N. On input, HR and HI contain the real and imaginary parts, respectively, of the complex upper Hessenberg matrix. If the eigenvectors of the Hessenberg matrix are desired, the lower triangles of HR,HI below the subdiagonal may be arbitrary. If the eigenvectors of a complex general matrix are desired, the lower triangles of HR,HI contain further information about the unitary transformations generated by CORTH in the reduction to the Hessenberg form. Note: COMQR2 destroys the upper Hessenberg portions of HR,HI.
WR,WI are working precision real output one- dimensional variables of dimension at least N containing the real and imaginary parts, respectively, of the eigenvalues of the upper Hessenberg matrix.
ZR, ZI are working precision real output two- dimensional variables with row dimension NM and column dimension at least N containing the real and imaginary parts, respectively, of the eigenvectors. The eigenvectors are not normalized.
IERR is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
286
7.1-92
B. Error Conditions and Returns.
If more than 30 iterations are required to determine an eigenvalue, this subroutine terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues in the WR and WI arrays should be correct for indices IERR+I,IERR+2,...,N, but no eigenvectors are computed.
If all the eigenvalues are determined within 30 iterations, IERR is set to zero.
C. Applicability and Restrictions.
To determine the eigenvalues and eigenvectors of a complex general matrix, COMQR2 must be preceded by CORTH (F244) to provide a suitable complex Hessenberg matrix for COMQR2.
It is recommended in general that CBAL (F271) be used before CORTH in which case CBABK2 (F272) must be used after COMQR2.
In this implementation, the arithmetic is real throughout except for complex square root and complex division.
3. DISCUSSION OF METHOD AND ALGORITHM.
The eigenvalues are determined by the QR method. The essence of this method is a process whereby a sequence of complex upper Hessenberg matrices, similar to the original Hessenberg matrix, is formed which converges to a triangular matrix. The rate of convergence of this sequence is improved by shifting the origin at each iteration. Before each iteration, the last Hessenberg form is checked for a possible splitting into submatrices. If a splitting occurs, only the lower submatrix participates in the next iteration. The similarity transformations used in each iteration are accumulated in the ZR and ZI arrays along with the reduction transformations for the original matrix.
The origin shift at each iteration is the eigenvalue of the lowest 2x2 principal minor closer to the second diagonal element of this minor. Whenever a lowest ixl principal submatrix finally splits from the rest of the matrix, its element is taken to be an eigenvalue of the original matrix and the algorithm proceeds with the remaining submatrix.
287
7.1-93
This process is continued until the matrix has split completely into submatrices of order i. The tolerances in the splitting tests are proportional to the relative machine precision. The eigenvectors of this triangular matrix are determined by back substitution, and then back transformed into those of the original matrix.
The subdiagonal elements are rendered real initially by a diagonal unitary similarity transformation and maintained real throughout COMQR2.
Some of the eigenvalues may have been isolated on the diagonal by the subroutine CBAL (F271). This information is transmitted to COMQR2 through the parameters LOW and IGH. As a result, COMQR2 immediately extracts the eigenvalues in rows i to LOW-I and IGH+I to N, and so applies the QR procedure to the submatrix situated in rows and columns LOW through IGHo
This subroutine is a translation of a unitary analogue of the Algol procedure COMLR2 written and discussed in detail by Peters and Wilkinson (I). The unitary analogue substitutes for the LR algorithm the QR algorithm, written and discussed in detail by Francis (2).
4. REFERENCES.
i) Peters, G~ and Wilkinson, J.H., Eigenvectors of Real and Complex Matrices by LR and QR Triangularizations, Num. Math. 16,181-204 (1970). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/15, 372-395, Springer-Verlag, 1971.)
2) Francis, J.G.F., The QR Transformation - Parts 1 and 2, Comp. J. 4,265-271 and 332-345 (1961/62).
5. CHECKOUT.
A. Test Cases°
See the section discussing testing of the codes for complex general matrices.
B. Accuracy.
The subroutine COMQR2 is numerically stable (1,2); that is, each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original upper Hessenberg matrix.
288
7.1-94
SUBROUTINE COMQR2(NM,N,LOW,IGH,ORTR,ORTI,HR,HI,WR,WI,ZR,ZI,IERR)
INTEGER I,J,K,L,M,N,EN,II,JJ,LL,NM,NN,IGH,IPI, X ITS,LOW,LPI,ENMI,IEND,IERR REAL HR(NM,N),HI(NM,N),WR(N),WI(N),ZR(NM,N),ZI(NM,N),
X ORTR(IGH),ORTI(IGH) REAL SI,SR, TI,TR,XI,XR,YI,YR,ZZI,ZZR,NORM,MACHEP REAL SQRT,CABS,ABS INTEGER MIN0 COMPLEX Z3 COMPLEX CSQRT,CMPLX REAL REAL,AIMAG
******~*** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.
**********
MACHEP = ?
IERR = 0
********** INITIALIZE EIGENVECTOR MATRIX ********** DO i00 I = I, N
DO I00 J = i, N ZR(I,J) = 0.0 ZI(I,J) = 0.0 IF (I .EQ. J) ZR(I,J) = 1.0
100 CONTINUE
C ********** FORM THE MATRIX OF ACCUMULATED TRANSFORMATIONS C FROM THE INFORMATION LEFT BY CORTH **********
1END = IGH - LOW - I IF (1END) 180, 150, 105
C ********** FOR I=IGH-I STEP -i UNTIL LOW+I DO -- ********** 105 DO 140 II = i, 1END
I = IGH - II
IF (ORTR(1) .EQ. 0.0 .AND. ORTI(1) .EQ. 0.0) GO TO 140 IF (HR(I,I-I) .EQ. 0.0 .AND. HI(I,I-I) .EQ. 0.0) GO TO 140
C ********** NORM BELOW IS NEGATIVE OF H FORMED IN CORTH ********** NORM = HR(I,I-I) * ORTR(1) + HI(I,I-I) * ORTI(1) IPI = I + I
Ii0
DO ii0 K = IPI, IGH ORTR(K) = HR(K,I-I) ORTI(K) = Hl(K,l-l)
CONTINUE
DO 130 J = I, IGH SR = 0.0 SI = 0.0
115
DO 115 K = I, IGH
SR = SR + 0RTR(K) * ZR(K,J) + ORTI(K) * ZI(K,J) SI = SI + ORTR(K) * ZI(K,J) - ORTI(K) * ZR(K,J)
CONTINUE
289
7.1-95
C
SR = SR / NORM
SI = SI / NORM
120
DO 120 K = I, IGH
ZR(K,J) = ZR(K,J) + SR * ORTR(K) - SI * ORTI(K) ZI(K,J) = ZI(K,J) + SR * ORTI(K) + SI * ORTR(K)
CONTINUE
130 CONTINUE
140 CONTINUE
********** CREATE REAL SUBDIAGONAL ELEMENTS ********** 150 L = LOW + 1
DO 170 I = L, IGH
LL = MINO(I+I,IGH)
IF (Hi(I,I-I) .EQ. 0.0) GO TO 170 NORM = CABS(CMPLX(HR(I,I-I),HI(I,I-I))) YR = HR(i,I-I) / NORM
YI = HI(I,I-I) / NORM ~R(I,I-I) = NORM
HI(I,I-I) = 0.0
155
DO 155 J = I, N
SI = YR * HI(I,J) - YI * HR(I,J) HR(I,J) = YR * HR(I,J) + YI * HI(I,J)
HI(I,J) = SI
CONTINUE
160
DO 160 J = I, LL
Sl = YR * HI(J,I) + YI * HR(J,I)
HR(J,I) = YR * HR(J,I) - YI * HI(J,I) HI(J,I) = SI
CONTINUE
165
DO 165 J = LOW, IGH SI = YR * ZI(J,I) + YI * ZR(J,I) zR(J,I) = YR * ZR(J,I) - ~I * ZI(J,I)
ZI(J,I) = SI CONTINUE
170 CONTINUE ********** STORE ROOTS ISOLATED BY CBAL **********
180 DO 200 I = i, N IF (I .GE. LOW .AND. I .LE. IGH) GO TO 20O WR(I) = H~(I,I)
WI(I) = HI(I,I) 200 CONTINUE
EN = IGH
TR = 0.0 TI = 0.0
290
7.1-96
C ********** SEARCH FOR NEXT EIGENVALUE **********
220 IF (EN .LT. LOW) GO TO 680 ITS = 0 ENMI = EN - i
C ********** LOOK FOR SINGLE SMALL SUB-DIAGONAL ELEMENT C FOR L=EN STEP -i UNTIL LOW DO -- **********
240 DO 260 LL = LOW, EN L = EN + LOW - LL IF (L .EQ. LOW) GO TO 300 IF (ABS(HR(L,L-I)) .LE.
X MACHEP * (ABS(HR(L-I,L-I)) + ABS(HI(L-I,L-I)) X + ABS(HR(L,L)) +ABS(HI(L,L)))) GO TO 300
260 CONTINUE C ********** FORM SHIFT **********
300 IF (L .EQ. EN) GO TO 660 IF (ITS .EQ. 30) GO TO I000 IF (ITS .EQ. i0 .OR. ITS .EQ. 20) GO TO 320 SR = HR(EN,EN) SI = HI(EN,EN)
XR = HR(ENMI,EN) * HR(EN,ENMI) XI = HI(ENMI,EN) * HR(EN,ENMI)
IF (XR .EQ. 0.0 .AND. XI .EQ. 0.0) GO TO 340 YR = (HR(ENMI,ENMI) - SR) / 2.0
YI = (HI(ENMI,ENMI) - SI) / 2.0 Z3 = CSQRT(CMPLX(YR**2-YI**2+XR,2.0*YR*YI+XI)) ZZR = REAL(Z3) ZZI = AIMAG(Z3)
IF (YR * ZZR + YI * ZZI .GE. 0.0) GO TO 310 ZZR = -ZZR ZZI = -ZZI
310 Z3 = CMPLX(XR, XI) / CMPLX(YR+ZZR,YI+ZZI) SR = SR - REAL(Z3) SI = SI - AIMAG(Z3) GO TO 340
C ********** FORM EXCEPTIONAL SHIFT ********** 320 SR = ABS(HR(EN,ENMI)) + ABS(HR(ENMI,EN-2))
SI = 0.0
340 DO 360 1 = LOW, EN HR(I,I) = HR(I,I) - SR HI(I,I) = HI(I,I) - SI
360 CONTINUE
TR = TR + SR TI = TI + SI ITS = ITS + 1
********** REDUCE TO TRIANGLE (ROWS) ********** LPI = L + i
291
7.1-97
X
DO 500 ! = LPI, EN
SR = HR(I,I-I)
HR(I,I-I) = 0.0
NORM = SQRT(HR(I-I,I-I)*HR(!-I,I-I)+HI(I-I,I-I)*HI(I-I,!-I)
+SR*SR)
XR = HR(I-I,I-I) / NORM
wR(I-l) = XR
XI = HI(I-I,I-I) / NORM
wi(i-l) = xI
HR(I-I,I-I) = NORM
HI(I-I,I-I) = 0.0
HI(!,!-1) = SR / NORM
490
DO 490 J = I, N
YR = HR(I-I,J)
YI = HI(!-I,J)
ZZR = HR(I,J)
ZZI = HI(I,J)
HR(I-I,J) = XR * YR + XI * YI + HI(I,I-I) * ZZR
HI(I-I,J) = XR * YI - XI * YR + HI(I,I-I) * ZZI
HR(I,J) = XR * ZZR - XI * ZZI - HI(I,I-I) * YR
HI(I,J) = XR * ZZI + XI * ZZR - HI(I,I-I) * YI
CONTINUE
500 CONTINUE
SI = HI(EN,EN)
IF (SI .EQ. 0.0) GO TO 540
NORM = CABS(CMPLX(HR(EN,EN),SI))
SR = HR(EN,EN) / NORM
SI = SI / NORM
HR(EN,EN) = NORM
HI(EN,EN) = 0.0
IF (EN .EQ. N) GO TO 540
IPI = EN + 1
DO 520 J = IPI, N
YR = HR(EN,J)
YI = HI(EN,J)
HR(EN,J) = SR * YR + SI * YI
HI(EN,J) = SR * YI - SI * YR
520 CONTINUE
• ********* INVERSE OPERATION (COLUMNS) **********
540 DO 600 J = LPI, EN
XR = WR(J-I)
xi = wi(J-1)
DO 580 I = I, J
YR = HR(I,J-l)
YI = 0.0
ZZR = HR(I,J)
ZZI = HI(I,J)
IF (I .EQ. J) GO TO 560
292
7.1-98
560
580
YI = HI(I,J-I) HI(I,J-I) = XR * YI + Xl * YR + HI(J,J-I) * ZZl
HR(I,J-I) = XR * YR - XI * YI + HI(J,J-I) * ZZR
HR(I,J) = XR * ZZR + XI * ZZI - HI(J,J-I) * YR
HI(I,J) = XR * ZZI - XI * ZZR - HI(J,J-I) * YI
CONTINUE
590
DO 590 I = LOW, IGH
YR = ZR(I,J-I)
YI = ZI(I,J-I)
ZZR = ZR(I,J)
ZZI = ZI(I,J) ZR(I,J-I) = XR * YR - XI * YI + HI(J,J-I) * ZZR
ZI(I,J-I) = XR * YI + XI * YR + HI(J,J-I) * ZZI
ZR(I,J) = XR * ZZR + XI * ZZI - HI(J,J-I) * YR
ZI(I,J) = XR * ZZI - Xl * ZZR - HI(J,J-I) * YI
CONTINUE
600 CONTINUE
IF (SI .EQ. 0.0) GO TO 240
DO 630 I = i~ EN
YR = HR(I,EN)
YI = HI(I,EN)
HR(I,EN) = SR * YR - SI * YI
HI(I,EN) = SR * YI + SI * YR
630 CONTINUE
DO 640 I = LOW, IGH
YR = ZR(I,EN)
YI = ZI(I,EN)
ZR(I,EN) = SR * YR - SI * YI
ZI(I,EN) = SR * YI + SI * YR
640 CONTINUE
GO TO 240
********** A ROOT FOUND **********
660 HR(EN,EN) = HR(EN,EN) + TR
WR(EN) = HR(EN,EN)
HI(EN,EN) = HI(EN,EN) + TI
WI(EN) = HI(EN,EN)
EN = ENMI
GO TO 220
********** ALL ROOTS FOUND.
680 NORM = 0.0
BACKSUBSTITUTE TO FIND
VECTORS OF UPPER TRIANGULAR FORM **********
DO 720 1 = i, N
DO 720 J = I, N
NORM = NORM + ABS(HR(I,J)) + ABS(HI(I,J))
720 CONTINUE
293
7.1-99
IF (N oEQ. i .OR. NORM .EQ. 0.0) GO TO I001 ********** FOR EN=N STEP -i UNTIL 2 DO -- **********
DO 800 NN = 2, N
EN = N + 2 - NN
XR = WR(EN) XI = WI(EN)
ENMI = EN - 1
********** FOR I=EN-I STEP -i UNTIL 1 DO -- ********** DO 780 II = I, ENMI
I = EN - II ZZR = HR(I,EN)
ZZI = HI(I,EN) IF (I .EQ. ENMI) GO TO 760
IPI = I + i
740
DO 740 J = IPI~ ENMI ZZR = ZZR + HR(I,J) * HR(J,EN) - HI(I,J) * HI(J,EN)
ZZ! = ZZI + HR(I,J) * HI(J,EN) + HI(I,J) * HR(J,EN)
CONTINUE
760
780
YR = XR - WR(1)
YI = Xi - WI(I)
IF (YR .EQ. 0.0 .AND. YI .EQ. 0.0) YR = MACHEP * NORM Z3 = CMPLX(ZZR,ZZI) / CMPLX(YR, YI)
HR(I,EN) = REAL(Z3) HI(I,EN) = AIMAG(Z3)
CONTINUE
C 800 CONTINUE
C ********** END BACKSUBSTITUTiON **********
ENMI = N - I C ********** VECTORS OF ISOLATED ROOTS **********
DO 840 ! = i, ENMI
IF (I .GE. LOW .AND. I .LE. IGH) GO TO 840
IPI = I + i
820
DO 820 J = IPI, N
ZR(!,J) = HR(I,J) ZI(I,J) = Hl(l,J)
CONTINUE
840 CONTINUE ********** MULTIPLY BY TRANSFORMATION MATRIX TO GIVE
VECTORS OF ORIGINAL FULL MATRIX.
FOR J=N STEP -I UNTIL LOW+I DO -- **********
DO 880 JJ = LOW, ENMI J = N + LOW - JJ M = MIN0(J-I,IGH)
DO 880 I = LOW, IGH ZZR = ZR(I,J) ZZI = ZI(I,J)
294
7 . 1 - 1 0 0
860
DO 860 K = LOW, M
ZZR = ZZR + ZR(I,K) * HR(K,J) - ZI(I,K) * HI(K,J)
ZZI = ZZI + ZR(I,K) * HI(K,J) + ZI(I,K) * HR(K,J) CONTINUE
ZR(I,J) = ZZR
ZI(I,J) = ZZI 880 CONTINUE
GO TO i001
C ********** SET ERROR -- NO CONVERGENCE TO AN C EIGENVALUE AFTER 30 ITERATIONS ********** i000 IERR = EN
i001 RETURN
END
295
7.1-101
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F247 CORTB
A Fortran IV Subroutine to Back Transform the Eigenvectors of that Upper Hessenberg Matrix Determined by CORTH.
July, 1975
I. PURPOSE.
The Fortran IV subroutine CORTB forms the eigenvectors of a complex general matrix from the eigenvectors of that upper Hessenberg matrix determined by CORTH (F244).
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE CORTB(NM,LOW, IGH,AR,AI,ORTR,ORTI, M,ZR,ZI)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays AR, AI, ZR, and ZI as specified in the DIMENSION statements for AR, AI, ZR, and ZI in the calling program.
LOW, IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F271 for the details. If the matrix is not balanced, set LOW to i and IGH to the order of the matrix.
AR,AI are working precision real input two- dimensional variables with row dimension NM and column dimension at least IGH. Their lower triangles contain some information about the unitary transformations used in
296
7.1-i02
the reduction to the Hessenberg form. The remaining upper parts of AR and AI are arbitrary. See section 3 of F244 for the details.
ORTR,ORTI are working precision real one-dimensional variables of dimension at least IGH. On input, ORTR and ORTI contain further information about the unitary transformations used in the reduction by CORTH. See section 3 of F244 for the details. ORTR and ORTI are used for temporary storage within CORTB and are not restored.
M is an integer input variable set equal to the number of columns of Z = (ZR,ZI) to be back transformed.
ZR,ZI are working precision real two-dimensional variables with row dimension NM and column dimension at least M. On input, the first M columns of ZR and ZI contain the real and imaginary parts, respectively, of the eigenvectors to be back transformed. On output, these M columns of ZR and ZI contain the real and imaginary Parts of the transformed eigenvectors.
B. Error Conditions and Returns.
None.
C. Applicability and Restrictions.
This subroutine should be used in conjunction with the subroutine CORTH (F244).
3. DISCUSSION OF METHOD AND ALGORITHM.
Suppose that the matrix upper Hessenberg form F transformation
c (say) has been reduced to the stored in A by the similarity
F = Q CQ
297
7.1-103
where Q is a product of the unitary matrices encoded in ORTR,ORTI and in a lower triangle of A under F. Then, given an array Z of column vectors, CORTB computes the matrix product QZ. If the eigenvectors of F are columns of the array Z, then CORTB forms the eigenvectors of C in their place.
This subroutine is a translation of a complex analogue of the Algol procedure ORTBAK written and discussed in detail by Martin and Wilkinson (i).
4. REFERENCES.
I) Martin~ R.S. and Wilkinson, J.H., Similarity Reduction of a General Matrix to Hessenberg Form, Num. Math. 12,349-368 (1968)o (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution II/13~ 339-358, Springer-Verlag, 1971.)
5. CHECKOUT.
A. Test Cases~
See the section discussing testing of the codes for complex general matrices.
B. Accuracy.
The accuracy of CORTB can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of complex general matrices. In these paths, this subroutine is numerically stable (i). This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original matrix.
298
7.1-104
C
C
SUBROUTINE CORTB(NM,LOW,IGH,AR,AI,ORTR,ORTI,M,ZR,ZI)
INTEGER I,J,M,LA,MM,MP,NM,IGH,KPI,LOW,MPI
REAL AR(NM, IGH),AI(NM,IGH),ORTR(IGH),ORTI(IGH),ZR(NM,M),ZI(NM,M) REAL H,GI,GR
IF (M .EQ. 0) GO TO 200 LA = IGH - 1 KPI = LOW + I IF (LA .LT. KPI) GO TO 200
********** FOR MP=IGH-I STEP -i UNTIL LOW+I DO -- ********** DO 140 MM = KPI, LA
MP = LOW + IGH - MM IF (AR(MP,MP-I) .EQ. 0.0 .AND. AI(MP,MF-I) .EQ. 0.0)
X GO TO 140
********** H BELOW IS NEGATIVE OF H FORMED IN CORTH ********** H = AR(MP,MP-I) * ORTR(MP) + AI(MP,MP-1) * ORTI(MP) MPI = MP + 1
100
DO i00 I = MPI, IGH ORTR(1) = AR(I,MP-I)
ORTI(1) = AI(I,MP-I) CONTINUE
DO 130 J = i, M
GR = 0.0 GI = 0.0
Ii0
DO Ii0 1 = MP, IGH
GR = GR + ORTR(1) * ZR(I,J) + ORTI(1) * ZI(I,J) GI = GI + ORTR(1) * ZI(I,J) - ORTI(1) * ZR(I,J)
CONTINUE
GR = GR / H
GI = GI / H
120
DO 120 I = MP, IGH
ZR(I,J) = ZR(I,J) + GR * ORTR(I) - GI * ORTI(1) ZI(I,J) = ZI(I,J) + GR * ORTI(1) + GI * ORTR(1)
CONTINUE
130 CONTINUE
140 CONTINUE
200 RETURN END
299
7.1-105
NATS PROJECT
EiGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F244 CORTH
A Fortran IV Subroutine to Reduce a Complex General Matrix to Upper Hessenberg Form Using Unitary Transformations.
July, 1975
i. PURPOSE.
The Fortran IV subroutine CORTH reduces a complex general matrix to complex upper Hessenberg form using unitary similarity transformations. This reduced form is used by other subroutines to find the eigenvalues and/or eigenvectors of the original matrix. See section 2C for the specific routines.
2. USAGE.
A, Calling Sequence,
The SUBROUTINE statement is
SUBROUTINE CORTH(NM,N,LOW, IGH,AR,AI,ORTR,ORTI)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification°
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays AR and AI as specified in the DIMENSION statements for AR and AI in the calling program.
N is an integer input variable set equal to
the order of the matrix A = (AR,AI). N must be not greater than NM.
LOW,IGH are integer input variables indicating the boundary indices for the balanced matrix, See section 3 of F271 for the details. If the matrix is not balanced, set LOW to I and IGH to N.
300
7.1-106
AR,AI are working precision real two-dimensional variables with row dimension NM and column dimension at least N. On input, AR and AI contain the real and imaginary parts, respectively, of the complex matrix of order N to be reduced to Hessenberg form. On output, AR and AI contain the real and imaginary parts of the upper Hessenberg matrix as well as some information about the unitary transformations used in the reduction. See section 3 for the details.
ORTR,ORTI are working precision real output one- dimensional variables of dimension at least IGH containing the remaining information about the unitary transformations. See section 3 for the details. Only components LOW+I through IGH are actually used by CORTH.
B. Error Conditions and Returns.
None.
C. Applicability and Restrictions.
If all the eigenvalues of the original matrix are desired, this subroutine should be followed by COMQR (F245).
If all the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by COMQR2 (F246).
If some of the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by COMQR (F245), CINVIT (F297), and CORTB (F247).
If the matrix has elements of widely varying magnitudes, the larger ones should be in the top left-hand corner.
3. DISCUSSION OF METHOD AND ALGORITHM.
Suppose that the matrix A = (AR,AI)
(T X Y) A = ( 0 B Z )
(0 0 R)
has the form
301
7.1-!07
where T and R are upper triangular matrices, B is a square matrix situated in rows and columns LOW through IGH, and X, Y, and Z are rectangular matrices of the appropriate dimensions. Then the subroutine CORTH performs unitary similarity transformations to reduce B to Hessenberg form.
The Hessenberg reduction is performed in the following way. Starting with J=LOW, the elements in the J-th column below the diagonal are first scaled, to avoid possible underflow in the transformation that might result in severe departure from orthogonality. The sum of squared magnitudes SIGMA of these scaled elements is next formed. Then, a vector U and a scalar
H = U U/2
define an operator
P = I - UU /H
which is unitary and Hermitian and for which the similarity transformation PAP eliminates the elements in the J-th column of A below the subdiagonal.
The non-zero components of U are the elements of the J-th column below the diagonal with the first of them augmented by the square root of SIGMA times the subdiagonal element divided by its magnitude. By saving this component in the array 0RTR,ORTI and not overwriting the column elements eliminated in the transformation~ full information on P is saved for later use in COMQR2 and CORTB.
The transformation replaces the subdiagonal element with the square root of SIGMA times the negative of the replaced element divided by its magnitude.
The above steps are repeated on further columns of the transformed A until B is reduced to Hessenberg form; that is, repeated for J = LOW+I,LOW+2,...,IGH-2.
This subroutine is a translation of a complex analogue of the Algol procedure ORTHES written and discussed in detail by Martin and Wilkinson (I).
302
7.1-108
4. REFERENCES.
1) Martin, R.S. and Wilkinson, J.H., Similarity Reduction of a General Matrix to Hessenberg Form, Num. Math. 12,349-368 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/13, 339-358, Springer-Verlag, 1971.)
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for complex general matrices.
B. Accuracy.
The accuracy of CORTH can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of complex general matrices. In these paths, this subroutine is numerically stable (i). This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original matrix.
303
7.1-109
90
i00
SUBROUTINE CORTH(NM,N,LOW, IGH,AR,AI,ORTR,ORTI)
INTEGER I,J,M,N,!I,JJ,LA,MP,NM, IGH,KPI,LOW
REAL AR(NM,N),AI(NM,N),ORTR(IGH),ORTI(IGH)
REAL F,G,H,FI,FR,SCALE
REAL SQRT,CABS,ABS
COMPLEX CMPLX
LA = IGH - 1
KPI = LOW + 1
IF (LA .LT. KPI) GO TO 200
DO 180 M = KPI, LA
H = 0.0 ORTR(M) = 0.0
ORTI(M) = 0.0 SCALE = 0 ~ 0
********** SCALE COLUMN (ALGOL TOL THEN NOT NEEDED) **********
DO 90 1 = M, IGH SCALE = SCALE + ABS(AR(I,M-I)) + ABS(AI(I,M-I))
IF (SCALE .EQ. 0.0) GO TO 180
MP = M + IGH ********** FOR I=IGH STEP -i UNTIL M DO -- **********
DO i00 II = M, IGH I = MP - II
ORTR(1) = AR(I,M-I) / SCALE ORTI(1) = AI(I,M-I) / SCALE H = H + ORTR(i) * ORTR(1) + ORrl(1) * ORTI(1)
CONTINUE
G = SQRT (H) F = CABS(CMPLX(ORTR(M),ORTI(M)))
IF (F .EQ. 0.0) GO TO 103
H = H + F * G
g = g / F ORTR(M) = (i.0 + G) * ORTR(M)
ORTI(M) = (i.0 + G) * ORTI(M)
GO TO 105
103 ORTR(M) = G AR(M,M-I) = SCALE
********** FORM (I-(U*UT)/H) * A **********
105 DO 130 J = M, N FR = 0.0 FI = 0 . 0
********** FOR I=IGH STEP -i UNTIL M DO -- **********
DO II0 II = M, IGH
I = MP - II FR = FR + ORTR(I) * AR(I,J) + ORTI(I) * AI(I,J)
FI = FI + ORTR(I) * AI(I,J) - ORTI(I) * AR(I,J)
II0 CONTINUE
304
7.1-110
FR = FR / H
FI = FI / H
120
DO 120 1 = M, IGH
AR(I,J) = AR(I,J) - FR * ORTR(1) + FI * ORTI(1)
AI(I,J) = AI(I,J) - FR ~ ORTI(1) - FI * ORTR(1)
CONTINUE
130 CONTINUE
~**~**** FORM (I-(U*UT)/H)*A*(I-(U*UT)/H) ***~*~***
DO 160 I = I s IGH
FR = 0.0
FI = 0.0
*******~** FOR J=IGH STEP -I UNTIL M DO -- *~**~****
DO 140 JJ = M, IGH
J = MP - JJ
FR = FR + ORTR(J) * AR(I,J) - ORTI(J) * AI(I,J)
FI = FI + ORTR(J) * AI(I,J) + ORTI(J) * AR(I,J) 140 CONTINUE
FR = FR / H
FI = FI / H
150
DO 150 J = M, IGH
AR(I,J) = AR(I,J) - FR * ORTR(J) - FI * ORTI(J)
AI(I,J) = AI(I,J) + FR * ORTI(J) - FI * ORTR(J)
CONTINUE
160 CONTINUE
ORTR(M) = SCALE * ORTR(M)
ORTI(M) = SCALE * ORTI(M)
AR(M,M-I) = -G * AR(M,M-I)
AI(M,M-I) = -G * AI(M,M-I)
180 CONTINUE
200 RETURN
END
305
7.1-111
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F274-2 ELMBAK
A Fortran IV Subroutine to Back Transform the Eigenvectors of that Upper Hessenberg Matrix Determined by ELMHES.
May, 1972 July, 1975
1. PURPOSE,
The Fortran IV subroutine ELMBAK forms the eigenvectors of a real general matrix from the eigenvectors of that upper Hessenberg matrix determined by ELMHES (F273).
2. USAGE.
A° Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE ELMBAK(NM, LOW,IGH,A, INT,M,Z)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dlmensional arrays A and Z as specified in the DIMENSION statements for A and Z in the calling program,
LOW, IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F269 for the details. If the matrix is not balanced, set LOW to I and IGH to the order of the matrix.
is a working precision real input two- dimensional variable with row dimension NM and column dimension at least IGH. Its lower triangle below the subdiagonal contains the multipliers which were used in the reduction to the Hessenberg form. The remaining upper part of A is arbitrary. See section 3 of F273 for the details.
306
7.1-112
INT is an integer input one-dimensional variable of dimension at least IGH. INT identifies the rows and columns interchanged during the reduction by ELMHES. See section 3 of F273 for the details.
is an integer input variable set equal to the number of columns of Z to be back transformed.
is a working precision real two-dimensional variable with row dimension NM and column dimension at least M. On input, the first M columns of Z contain the real and imaginary parts of the eigenvectors to be back transformed. On output, these M columns of Z contain the real and imaginary parts of the transformed eigenvectors.
B. Error Conditions and Returns.
None.
C. Applicability and Restrictions.
This subroutine should be used in conjunction with the subroutine ELMHES (F273).
The real and imaginary parts of an eigenvector need not be stored in consecutive columns of Z.
3. DISCUSSION OF METHOD AND ALGORITHM.
Suppose that the matrix upper Hessenberg form F transformation
C (say) has been reduced to the stored in A by the similarity
-i F = G CG
where G is a product of the permutation and elementary matrices encoded in INT and in a lower triangle of A under F respectively. Then, given an array Z of column vectors, ELMBAK computes the matrix product GZ. If the real and imaginary parts of the eigenvectors of F are columns of the array Z, then ELMBAK forms the eigenvectors of C in their place.
307
7.1-113
This subroutine is a translation of the Algol procedure ELMBAK written and discussed in detail by Martin and Wilkinson (i).
4o REFERENCES.
I) Martin, RoS. and Wilkinson~ J.H., Similarity Reduction of a General Matrix to Hessenberg Form, Num. Math. 12,349-368 (1968). (Reprinted in Handbook for $utomatie Computation, Volume II, Linear Algebra, J, H. Wilkinson - C. Reinsch, Contribution 11/13, 339-358, Springer-Verlag, 1971.)
5. CHECKOUT.
Ao Test Cases~
See the section discussing testing of the codes for real general matrices.
B. Accuracy~
The accuracy of ELMBAK can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real general matrices. In these paths, this subroutine is, in practice, numerically stable (i). This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original matrix.
308
7.1-114
SUBROUTINE ELMBAK(NM~LOW, IGH,A, INT,M,Z)
INTEGER I,J,M, LA,MM,MP,NM, IGH,KPI,LOW,MPI
REAL A(NM,IGH),Z(NM,M) REAL X INTEGER INT(IGH)
IF (M .EQ. 0) GO TO 200 LA = IGH - i KPI = LOW + i IF (LA .LT. KPI) GO TO 200 ********** FOR MP=IGH-I STEP -i UNTIL LOW+I DO -- ********** DO 140 MM = KPI, LA
MP = LOW + IGH - MM MPI = MP + i
DO ii0 I = MPI, IGH X = A(I,MP-I) IF (X .EQ. 0.0) GO TO ii0
i00 DO i00 J = i, M Z(I,J) = Z(I,J) + X * Z(MP,J)
ii0 CONTINUE
I = INT(MP) IF (I .EQ. MP) GO TO 140
130
DO 130 J = I, M X = Z(I,J) Z(I,J) = Z(MP,J) Z(MP,J) = X
CONTINUE
140 CONTINUE
200 RETURN END
309
7.1-115
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F273 ELMHES
A Fortran IV Subroutine to Reduce a Real General Matrix to Upper Hessenberg Form Using Elementary Transformations.
May, 1972
i. PURPOSE.
The Fortran IV subroutine ELMHES reduces a real general matrix to upper Hessenberg form using stabilized elementary similarity transformations. This reduced form is used by other subroutines to find the eigenvalues and/or eigenvectors of the original matrix. See section 2C for the specific routines.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE ELMHES(NM,N,LOW, IGH,A, INT)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional array A as specified in the DIMENSION statement for A in the calling program.
N is an integer input variable set equal to the order of the matrix A. N must be not
greater than NM.
LOW, IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F269 for the details. the matrix is not balanced, set LOW to and IGH to N.
If 1
310
7.1-I16
INT
is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. On input, A contains the matrix of order N to be reduced to Hessenberg form. On output, A contains the upper Hessenberg matrix as well as the multipliers used in the reduction. See section 3 for the details.
is an integer output one-dimensional variable of dimension at least IGH identifying the rows and columns interchanged during the reduction. See section 3 for the details. Only components LOW+I through IGH-I are actually used by ELMHES.
B. Error Conditions and Returns.
None.
C. Applicability and Restrictions.
If all the eigenvalues of the original matrix are desired, this subroutine should be followed by HQR (F286).
If all the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by ELTRAN (F220) and HQR2 (F287).
If some of the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by HQR (F286), INVIT (F288), and ELMBAK (F274).
The subroutine ELMHES executes faster than its counterpart ORTHES (F275), which uses orthogonal similarity transformations. ORTHES is, however, more accurate in some cases. It is recommended that ELMHES be used in general.
3. DISCUSSION OF METHOD AND ALGORITHM.
Suppose that the matrix A has the form
( T X Y ) = (0 B Z)
(0 0 R)
311
7.1-117
where T and R are upper triangular matrices, B is a square matrix situated in rows and columns LOW through IGH, and X, Y, and Z are rectangular matrices of the appropriate dimensions. Then the subroutine ELMHES performs permutation and elementary similarity transformations to reduce B to Hessenberg form.
The Hessenberg reduction is performed in the following way. Starting with J=LOW, a permutation similarity transformation is performed to stabilize the succeeding elementary transformations in the J-th column of A. Next, each non- zero element below the subdiagonal in the J-th column of A is eliminated using elementary similarity transformations.
The permutation similarity transformation is determined by searching for the element of maximum modulus in the J-th column below the subdiagonal. This element is placed into the suhdiagonal position by a row interchange and the corresponding column interchange is made to complete the permutation transformation. The index of the row interchanged with the (J+l)-th row is stored in INT(J+I).
The elementary transformation consists of elementary row operations on the J-th column of A to eliminate the non- zero elements below the subdiagonal and the corresponding elementary column operations to complete the similarity. The multipliers used in this elimination process are stored in place of the eliminated elements. These multipliers as well as the row interchange information in INT are used later in ELTRAN for the accumulation of the transformations and in ELMBAK for the back transformation of the eigenvectors,
The above steps are repeated on further columns of the transformed A untii B is reduced to Hessenberg form; that is, repeated for J = LOW+I,LOW+2,...,IGH-2.
This subroutine is a translation of the Algol procedure ELMHES written and discussed in detail by Martin and Wilkinson (I).
4. REFERENCES.
I) Martin, R.S. and Wilkinson, J.H., Similarity Reduction of a General Matrix to Hessenberg Form, Num. Math. 12,349-368 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/13, 339-358, Springer-Verlag, 1971.)
312
7.1-118
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for real general matrices.
B. Accuracy.
The accuracy of ELMHES can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real general matrices. In these paths, this subroutine is, in practice, numerically stable (I). This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original matrix.
313
7.1-119
C
i00
Ii0
120
130
140
150
160
SUBROUTINE ELMHES(NM,N,LOW,IGH,A,INT)
INTEGER I,J,M,N,LA,NM,IGH,KPI,LOW,MM1,MPI REAL A(NM,N) REAL X,Y
REAL ABS
INTEGER INT(IGH)
LA = IGH - 1
KPI = LOW + 1
IF (LA .LT. KPI) GO TO 200
DO 180 M = KPI, LA
MMI = M - i X = 0.0
I = M
DO i00 J = M, IGH IF (ABS(A(J,MMI)) .LE. ABS(X)) GO TO i00
X = A(J,MMI)
! = J
CONTINUE
INT (M) = I IF (I .EQ. M) GO TO 130
****22***2 INTERCHANGE ROWS AND COLUMNS OF A **,2,2,~,2
DO II0 J = MMI, N
Y = A(I,J)
A(I,J) = A(M,J) A(M,J) = Y
CONTINUE
DO 120 J = i, !GH
Y = A(J,I) A(J,I) = A(J,M)
A(J,M) = Y CONTINUE
********** END INTERCHANGE ********** IF (X .EQ. 0.0) GO TO 180
MPI = M + 1
DO 160 1 = MPI, IGH Y = A(I,MMI) IF (Y .EQ. 0.0) GO TO 160
Y = Y / X A(I,MMI) = Y
DO 140 J = M, N A(I,J) = A(I,J) - Y * A(M,J)
DO 150 J = i, IGH A(J,M) = A(J,M) + Y * A(J,I)
CONTINUE
3t4
7.1-120
C 180 CONTINUE
C 200 RETURN
END
315
7. 1-121
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F220 ELTRAN
A Fortran IV Subroutine to Accumulate the Transformations in the Reduction of a Real General Matrix by ELMHES.
May, 1972
I. PURPOSE.
The Fortran IV subroutine ELTRAN accumulates the stabilized elementary similarity transformations used in the reduction of a real general matrix to upper Hessenberg form by ELMHES (F273).
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE ELTRAN(NM,N,LOW,IGH,A,INT,Z)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays A and Z as specified in the DIMENSION statements for A and Z in the calling program.
N is an integer input variable set equal to the order of the matrix A. N must be not greater than NM.
LOW,IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F269 for the details. If the matrix is not balanced, set LOW to 1 and IGH to N.
316
7.1-122
A
INT
is a working precision real input two- dimensional variable with row dimension NM and column dimension at least IGH. Its lower triangle below the subdiagonal contains the multipliers which were used in the reduction to the Hessenberg form. The remaining upper part of A is arbitrary. See section 3 of F273 for the details.
is an integer input one-dimensional variable of dimension at least IGH. INT identifies the rows and columns interchanged during the reduction by ELMHES. See section 3 of F273 for the details.
is a working precision real output two- dimensional variable with row dimension NM and column dimension at least N. It contains the transformation matrix produced in the reduction by ELMHES to the upper Hessenberg form.
B. Error Conditions and Returns.
None.
C. Applicability and Restrictions.
If all the eigenvalues and eigenvectors of the original matrix are desired, this subroutine follows ELMHES (F273) and should be followed by HQR2 (F287). Otherwise, this subroutine will not ordinarily be used.
3. DISCUSSION OF METHOD AND ALGORITHM.
Suppose that the matrix upper Hessenberg form F transformation
C (say) has been reduced to the stored in A by the similarity
-I F = G CG
where G is a product of the permutation and elementary matrices encoded in INT and in a lower triangle of A under F respectively. Then, ELTRAN accumulates G the array Z.
This subroutine is a translation of the Algol procedure ELMTRANS written and discussed in detail by Peters and Wilkinson (i).
into
317
7.1-123
4. REFERENCES.
i) Peters, G. and Wilkinson, J.H., Eigenvectors of Real and Complex Matrices by LR and QR Triangularizations, Num. Math. 16,181-204 (1970). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/15, 372-395, Springer-Verlag, 1971.)
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for real general matrices.
B. Accuracy.
ELTRAN introduces no rounding errors since it only transfers the multipliers used in the reduction process into the eigenvector matrix.
318
7.1-124
C C
C
SUBROUTINE ELTRAN(NM,N,LOW~IGH,A, INT,Z)
INTEGER I~J,N,KL,MMDMP,NM,IGHjLOW~MPI REAL A(NM,IGH),Z(NM,N) INTEGER INT(IGH)
**mmmmm,,, INITIALIZE Z TO IDENTITY MATRIX ,mmm,m,mm, DO 80 I = lj N
DO 60 J = i, N 60 Z(l,J) = 0.0
Z(I,I) = 1.0 80 CONTINUE
KL = IGH - LOW - 1 IF (EL .LT. i) GO TO 200
*********m FOR MP=IGH-I STEP -I UNTIL LOW+I DO -- ********** DO 140 MM = i, KL
MP = IGH - MM MPI = MP + I
i 0 0 DO i00 I = MPI~ IGH Z(I,MP) = A(I,MP-I)
I = INT(MP) IF (I .EQ~ MP) GO TO 140
130
DO 130 J = MP, IGH Z(MP,J) = Z(I,J) Z(I,J) = 0.0
CONTINUE
Z(I,MP) = 1.0 140 CONTINUE
200 RETURN END
319
7.1-125
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F280-2 FIGI
A Fortran IV Subroutine to Transform a Certain Real Non-Symmetric Tridiagonal Matrix to a
Symmetric Tridiagonal Matrix.
May, 1972 July, 1975
I. PURPOSE.
The Fortran IV subroutine FIGI transforms a certain real non-symmetric tridiagonal matrix to a symmetric tridiagonal matrix. The property of the non-symmetric matrix required for use of this subroutine is that the products of pairs of corresponding off-diagonal elements be all non-negative. The transformed matrix is used by other subroutines to find the eigenvalues and/or eigenvectors of the original matrix. See section 2C for the specific routines.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE FIGI(NM,N,T,D,E,E2,1ERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional array T as specified in the DIMENSION statement for T in the calling program.
is an integer input variable set equal to the order of the matrix T. N must be not greater than NM.
320
7.1-126
E2
IERR
is a working precision real input two- dimensional variable with row dimension NM and column dimension at least 3. T contains the non-symmetric tridiagonal matrix of order N in its first three columns. The subdiagonal elements are stored in the last N-I positions of the first column. The diagonal elements are stored in the second column. The superdiagonal elements are stored in the first N-I positions of the third column. Elements T(I,I) and T(N,3) are arbitrary.
is a working precision real output one- dimensional variable of dimension at least N containing the diagonal elements of the tridiagonal symmetric matrix.
is a working precision real output one- dimensional variable of dimension at least N containing, in its last N-I positions, the subdiagonal elements of the tridiagonal symmetric matrix. The element E(1) is not referenced.
is a working precision real output one- dimensional variable of dimension at least N containing, in its last N-I positions, the squares of the subdiagonal elements of the tridiagonal symmetric matrix. The element E2(1) is not referenced. E2 need not be distinct from E (non-standard usage acceptable with at least those compilers included in the certification statement) s in which case no squares are returned.
is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
B. Error Conditions and Returns.
If the product of T(I,I) and T(I-I,3) is negative, FIGI terminates with IERR set to N+I. In this case, a symmetric matrix cannot be produced with this program.
If the product of T(I,I) and T(I-I,3) is zero but either T(I,I) or T(I-I,3) is not zero, FIGI sets IERR to -(3*N+I) and continues. If this occurs more than once, the last occurrence is recorded in IERR. See section 3.
321
7.1-127
If the products of all pairs of corresponding off- diagonal elements are non-negative, and zero only when both factors are zero, IERR is set to zero.
C. Applicability and Restrictions.
If all the eigenva!ues of the original matrix are desired, this subroutine should he followed by IMTQLI (F291).
If some of the eigenvalues of the original matrix are desired, this subroutine should be followed by BISECT (F294) or TRIDIB (F237).
If some of the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by TSTURM (F293), or by BISECT (F294) and TINVIT (F223), or by TRIDIB (F237) and TINVIT, or by !MTQLV (F234) and TINVlT, and then by BAKVEC (F281).
If all the eigenvalues and eigenvectors of the original matrix are desired, subroutine FIGI2 (F222) should be used rather than FIGI to perform the symmetrization, and should be followed by IMTQL2 (F292).
3. DISCUSSION OF METHOD AND ALGORITHM.
The transformation is performed in the following way° If the products of pairs of corresponding off-diagonal elements of T are all positive or if both elements are zero, a non- singular diagonal matrix V can be defined such that the similarity transformation
-i V TV
produces a symmetric tridiagona! matrix with diagonal D and subdiagonal E as follows:
D(J) = T(J,2), J:I,2,3, .... N, E(J) = SQRT(T(J,I) * T(J-I,3)), J:2,3, .... N.
The diagonal elements of the transformation matrix V are as follows:
v ( 1 , 1 ) : i . o ,
and for J=2,3,...,N V(J,J) = V(J-I,J-I) * SQRT(T(J,I) / T(J-I,3))
if T(J,I) * T(J-I,3) is positive, or
V(J,J) = 1.0 if both T(J,I) and T(J-I,3) are zero.
322
7.1-128
If the product of a pair of corresponding off-diagonal elements is zero but only one of the elements is zero, then the symmetric tridiagonal matrix defined above has the same eigenvalues as T but its eigenvectors are not simply related to those of T. In this case, the back transformation subroutine BAKVEC (F281), if called, will set an error flag indicating that the computed eigenvectors are not valid.
This subroutine is an implementation of the algorithm discussed in detail by Wilkinson (I).
4. REFERENCES.
i) Wilkinson, J.H., The Algebraic Eigenvalue Problem, Oxford, Clarendon Press, 335-337 (1965).
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for certain real non-symmetric tridiagonal matrices.
B. Accuracy.
The accuracy of FIGI can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of certain real non- symmetric tridiagonal matrices. In these paths, this subroutine is numerically stable (I). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.
323
7.1-129
SUBROUTINE FIGI(NM,N,T,D,E,E2,1ERR)
INTEGER I,N,NM,IERR REAL T(NM, 3) ,D (N), E (N), E2 (N) REAL SQRT
IERR = 0
DO I00 1 = !~ N IF (I .EQ. i) GO TO 90 E2(1) = T(I,I) * T(I-I,3) IF (E2(1)) I000, 60, 80 IF (r(l,l) .EQ. 0.0 .AND. r(l-l,3) .EQ. 0.0) GO TO 80 6O
********** SET ERROR -- PRODUCT OF SOME PAIR OF OFF-DIAGONAL ELEMENTS IS ZERO WITH ONE MEMBER NON-ZERO **********
IERR = -(3 * N + I) 80 E(1) = SQRT(E2(1)) 90 D(1) = T(I,2)
i00 CONTINUE
GO TO I001 ********** SET ERROR -- PRODUCT OF SOME PAIR OF OFF-DIAGONAL
ELEMENTS IS NEGATIVE ********** i000 IERR = N + I I001 RETURN
END
324
7.1-130
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F222 FIGI2
A Fortran IV Subroutine to Transform a Certain Real Non-Symmetric Tridiagonal Matrix to a Symmetric Tridiagonal Matrix
Accumulating the Diagonal Transformations.
May, 1972
i. PURPOSE.
The Fortran IV subroutine FIGI2 transforms a certain real non-symmetric tridiagonal matrix to a symmetric tridiagonal matrix using and accumulating diagonal similarity transformations. The property of the non-symmetric matrix required for use of this subroutine is that the products of pairs of corresponding off-diagonal elements be all non- negative, and zero only when both factors are zero. The symmetrized matrix and the transformation matrix are used by subroutine IMTQL2 (F292) to find the eigenvalues and eigenvectors of the original matrix.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE FIGI2(NM,N,T,D,E,Z,IERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays T and Z as specified in the DIMENSION statements for T and Z in the calling program.
is an integer input variable set equal to the order of the matrix T. N must be not greater than NM.
325
7.1-131
IERR
is a working precision real input two- dimensional variable with row dimension NM and column dimension at least 3. T contains the non-symmetric tridiagonal matrix of order N in its first three columns. The subdiagonal elements are stored in the last N-I positions of the first column. The diagonal elements are stored in the second column. The superdiagonal elements are stored in the first N-I positions of the third column. Elements T(I,!) and T(N,3) are arbitrary.
is a working precision real output one- dimensional variable of dimension at least N containing the diagonal elements of the tridiagonal symmetric matrix.
is a working precision real output one- dimensional variable of dimension at least N containing, in its last N-I positions, the subdiagonal elements of the tridiagonal symmetric matrix. The element E(1) is not referenced.
is a working precision real output two- dimensional variable with row dimension NM and column dimension at least N. It contains the diagonal transformation matrix produced in the symmetrization.
is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
B. Error Conditions and Returns.
If the product of T(i,I) and T(!-I,3) is negative, FIGI2 terminates with IERR set to N+I. If the product of T(I,I) and T(I-I,3) is zero but either T(I,I) or T(!-I,3) is not zero, FIGI2 terminates with IERR set to 2*N+I. In these cases, there does not exist a symmetrizing similarity transformation, essential for the validity of the later eigenvector computation.
If the products of all pairs of corresponding off- diagonal elements are non-negative, and zero only when both factors are zero, IERR is set to zero.
326
7.1-132
C. Applicability and Restrictions.
If all the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by IMTQL2 (F292).
If some other combination of eigenvalues and eigenvectors is desired, subroutine FIGI (F280) be used rather than FIGI2 to perform the symmetrization.
should
3. DISCUSSION OF METHOD AND ALGORITHM.
The transformation is performed in the following way. If the products of pairs of corresponding off-diagonal elements of T are all positive or if both elements are zero, a non- singular diagonal matrix Z can be defined such that the similarity transformation
-i Z TZ
produces a symmetric tridiagonal matrix with diagonal D and subdiagonal E as follows:
D(J) = T(J,2), J=1,2,3, .... N, E(J) = SQRT(T(J,I) * T(J-I,3)), J=2,3,...,N.
The diagonal elements of the transformation matrix follows:
Z are as
z(1,1) = 1.0,
and for J=2,3,...,N Z(J,J) = Z(J-I,J-I) * SQRT(T(J,I) / T(J-I,3))
if T(J,I) * T(J-I,3) is positive, or Z(J,J) = 1.0 if both T(J,I) and T(J-I,3) are zero.
This subroutine is an implementation of the algorithm discussed in detail by Wilkinson (i).
4. REFERENCES.
i) Wilkinson, J.H., The Algebraic Eigenvalue Problem, Oxford, Clarendon Press, 335-337 (1965).
327
7.1-133
5. CHECKOUT.
A. Test Cases°
See the section discussing testing of the codes for certain real non-symmetric tridiagonal matrices.
B, Accuracy,
The accuracy of FIGI2 can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of certain real non- symmetric tridiagonal matrices. In these paths, this subroutine is numerically stable (i). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.
328
7.1-134
C
C
C
C
C
C C
SUBROUTINE FIGI2(NM,N,T,D,E,Z,IERR)
INTEGER I,J,N,NM, IERR REAL T(NM,3),D(N),E(N),Z(NM, N) REAL H REAL SQRT
IERR = 0
DO i00 I = I, N
DO 50 J = i, N 50 Z(I,J) = 0.0
IF (I .EQ. 1) GO TO 70 H = T(I,I) * T(I-I,3) IF (H) 900, 60, 80
60 IF (T(I,I) .NE. 0.0 .OR. T(I-I,3) .NE. 0.0) GO TO I000 E(I) = 0.0
70 Z(I,I) = 1.0 GO TO 90
80 E(1) = SQRT(H) Z ( I , I ) = Z ( I - I , I - 1 ) * E ( I ) / T(I-I,3)
90 D(I) = T(I,2) i00 CONTINUE
GO TO i001
~***~***** SET ERROR -- PRODUCT OF SOME PAIR OF OFF-DIAGONAL ELEMENTS IS NEGATIVE **e*****e*
900 IERR = N + I GO TO 1001
********** SET ERROR -- PRODUCT OF SOME PAIR OF OFF-DIAGONAL ELEMENTS IS ZERO WITH ONE MEMBER NON-ZERO ~***e***~*
1000 IERR = 2 * N + I I001 RETURN
END
329
7. 1-135
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F286-2 HQR
A Fortran IV Subroutine to Determine the Eigenvalues of a Real Upper Hessenberg Matrix.
May, 1972 July, 1975
i. PURPOSE~
The Fortran IV subroutine HQR computes the eigenvalues of a real upper Hessenberg matrix using the QR method.
2. USAGE.
A. Calling Sequence°
The SUBROUTINE statement is
SUBROUTINE HQR(NM,N,LOW, IGH,H,WR,WI,IERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional array H as specified in the DIMENSION statement for H in the calling program.
is an integer input variable set equal to the order of the matrix H. N must be not greater than NM.
LOW,!GH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F269 for the details. If the matrix is not balanced, set LOW to 1 and IGH to N.
330
7.1-136
H
WR,WI
IERR
is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. On input, it contains the upper Hessenberg matrix. Note: HQR destroys this upper Hessenberg matrix as well as the two adjacent diagonals below it.
are working precision real output one- dimensional variables of dimension at least N containing the real and imaginary parts, respectively, of the eigenvalues of the Hessenberg matrix. The eigenvalues are unordered except that complex conjugate pairs of eigenvalues appear consecutively with the eigenvalue having the positive imaginary part first.
is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
B. Error Conditions and Returns.
If more than 30 iterations are required to determine an eigenvalue, this subroutine terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues in the WR and WI arrays should be correct for indices IERR+I,IERR+2,...,N.
If all the eigenvalues are determined within 30 iterations, IERR is set to zero.
C. Applicability and Restrictions.
To determine some of the eigenvectors of a real Hessenberg matrix, HQR should be followed by INVIT (F288) to compute those eigenvectors. Note, however, that the upper Hessenberg matrix must be saved before HQR for later use by INVIT.
To determine the eigenvalues of a real general matrix, HQR must be preceded by ELMHES (F273) or ORTHES (F275) to produce a suitable upper Hessenberg matrix for HQR.
331
7.1-137
To determine some of the eigenvectors of a real general matrix, HQR should be preceded by ELMHES (F273) or ORTHES (F275) and followed by INVIT (F288) and ELMBAK (F274) or ORTBAK (F276). ELMBAK or ORTBAK back transforms the eigenvectors from INVIT into those of the real general matrix. Note, however, that the upper Hessenberg matrix and the two adjacent diagonals below it must be saved before HQR for the later use by INVIT and ELMBAK or ORTBAK, since HQR destroys this portion of H.
It is recommended in general that BALANC (F269) be used before ELMHES or ORTHES in which case BALBAK (F270) must be used after ELMBAK or ORTBAK if eigenvectors are computed.
3. DISCUSSION OF METHOD AND ALGORITHM.
The eigenvalues are determined by the QR method. The essence of this method is a process whereby a sequence of upper Hessenberg matrices, unitarily similar to the original Hessenberg matrix, is formed which converges to a quasi- triangular matrix, that is, an upper Hessenberg matrix whose eigenva!ues are the eigenvalues of ixl or 2x2 principal submatrices. The rate of convergence of this sequence is improved by shifting the origin at each iteration. The arithmetic throughout the process is kept real by combining two iterations into one, using two real origin shifts or a pair of complex conjugate origin shifts. Before each iteration, the last Hessenberg form is checked for a possible splitting into submatrices. If a splitting occurs, only the lower submatrix participates in the next iteration.
The origin shifts at each iteration are the eigenvalues of the lowest 2x2 principal minor. Whenever a lowest ixl or 2x2 principal submatrix finally splits from the rest of the matrix, the eigenvalues of this submatrix are taken to be eigenvalues of the original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of order i or 2. The tolerances in the splitting tests are proportional to the relative machine precision.
Some of the eigenvalues may have been isolated on the diagonal by the subroutine BALANC (F269). This information is transmitted to HQR through the parameters LOW and IGH. As a result, HQR immediately extracts the eigenvalues in rows I to LOW-I and IGH+I to N, and so applies the QR procedure to the submatrix situated in rows and columns LOW through IGH.
332
7.1-138
This subroutine is a translation of the Algol procedure written and discussed in detail by Martin, Peters, and Wilkinson (i).
HQR
4. REFERENCES.
i) Martin, R.S., Peters, G., and Wilkinson, J.H., The QR Algorithm for Real Hessenberg Matrices, Num. Math. 14,219-231 (1970). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C° Reinsch, Contribution 11/14, 359-371, Springer-Verlag, 1971.)
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for real general matrices.
B. Accuracy.
The subroutine HQR is numerically stable (i); that is, each computed eigenvalue is exact for a matrix close to the original upper Hessenberg matrix.
333
7.1-139
SUBROUTINE HQR(NM,N,LOW, IGH,H,WR,WI,IERR)
INTEGER I,J,K,L,M,N,EN,LL,MM,NA,NM, IGH, ITS,LOW,MP2,ENM2,IERR
REAL H(NM,N),WR(N),WI(N) REAL P,Q,R,S,T,W,X,Y,ZZ,NORM,MACHEP
REAL SQRT,ABS,SIGN
INTEGER MIN0 LOGICAL NOTLAS
********** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING
THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.
MACHEP = ?
IERR = 0 NORM = 0.0
K = 1 ********** STORE ROOTS ISOLATED BY BALANC
AND COMPUTE MATRIX NORM ********** DO 50 I = i, N
40
DO 40 J = K, N
NORM = NORM + ABS(H(I,J))
K = I IF (I .GE. LOW .AND. I .LE. IGH) GO TO 50
WR(1) = H(I,I)
WI(I) = 0.0
50 CONTINUE
EN = !GH
T=0.0 C ********** SEARCH FOR NEXT EIGENVALUES **********
60 IF (EN .LT. LOW) GO TO i001
ITS = 0 NA = EN - 1
ENM2 = NA - 1 C ********** LOOK FOR SINGLE SMALL SUB-DIAGONAL ELEMENT C FOR L=EN STEP -I UNTIL LOW DO -- **********
70 DO 80 LL = LOW, EN L = EN + LOW - LL IF (L .EQ. LOW) GO TO i00
S = ABS(H(L-I,L-I)) + ABS(H(L,L)) IF (S ,EQ. 0.0) S = NORM IF (ABS(H(L,L-I)) .LE. MACHEP * S) GO TO I00
80 CONTINUE C ********** FORM SHIFT **********
!00 X = H(EN,EN) IF (L .EQ. EN) GO TO 270
Y = H(NA,NA) W = H(EN,NA) * H(NA,EN) IF (L .EQ. NA) GO TO 280 IF (ITS .EQ. 30) GO TO i000
334
7. 1-140
IF (ITS .NE. i0 .AND. ITS .NE. 20) GO TO 130
********** FORM EXCEPTIONAL SHIFT **********
T = T + X
DO 120 1 = LOW, EN
120 H(I,I) = H(!,I) - X
S = ABS(H(EN,NA)) + ABS(H(NA,ENM2)) X = 0.75 * S Y = X W = -0.4375 * S * S
130 ITS = ITS + 1
• ********* LOOK FOR TWO CONSECUTIVE SMALL SUB-DIAGONAL ELEMENTS.
FOR M--EN-2 STEP -I UNTIL L DO -- ********** DO 140 MM = L, ENM2
M = ENM2 + L - MM ZZ = H(M,M)
R -- X - ZZ S = Y - ZZ
P = (R * S - W) / H(M+I,M) + H(M,M+I) Q = H(M+I,M+I) - ZZ - R - S R = H(M+2,M+I)
S = ABS(P) + ABS(Q) + ABS(R) P = P / S
Q = Q / S R = R / S IF (M .EQ. L) GO TO 150
IF (ABS(H(M,M-I)) * (ABS(Q) + ABS(R)) .LE. MACHEP * ABS(P) X * (ABS(H(M-I,M-I)) + ABS(ZZ) + ABS(H(M+I,M+I)))) GO TO 150
140 CONTINUE
150 MP2 = M + 2
DO 160 I = MP2, EN
H(I,I-2) = 0.0
IF (I .EQ. MP2) GO TO 160 H(I,I-3) = 0.0
160 CONTINUE
********** DOUBLE QR STEP INVOLVING ROWS L TO EN AND COLUMNS M TO EN **********
DO 260 K = M, NA
NOTLAS = K .NE. NA
IF (K .EQ. M) GO TO 170 P = H(K,K-I) Q = H(K+I,K-I) R=O.0
IF (NOTLAS) R = H(K+2,K-I)
X = ABS(P) + ABS(Q) + ABS(R) IF (X .EQ. 0.0) GO TO 260 P = e / X
Q = Q / X R = ~ / X
335
7.1-141
170 S = SIGN(SQRT(P*P+Q*Q+R*R),P)
IF (K .EQ. M) GO TO 180
H(K,K-I) = -S * X
GO TO 190 180 IF (L .NE. M) H(K,K-I) = -H(K,K-I)
190 P = P + S x=e/s Y = Q / S zz =R / S Q = Q / e
R = R / P • ********* ROW MODIFICATION **********
DO 210 J = K, EN P = H(K,J) + Q * H(K+l,J) IF (.NOT. NOTLAS) GO TO 200
P = P + R * H(K+2,J) H(K+2,J) = H(K+2,J) - P * ZZ
200 H(K+I,J) = H(K+I,J) - P * Y
H(K,J) = H(K,J) - P * X
210 CONTINUE
220
230
J = MIN0(EN,K+3) ********** COLUMN MODIFICATION **********
DO 230 I = Ls J P = X * H(I,K) + Y * H(I,K+I)
IF (.NOT. NOTLAS) GO TO 220
P = P + EZ * H(I,K+2)
H(I,K+2) = H(I,K+2) - P * R
H(I,K+I) = H(I,K+I) - P * Q
H(l,K) = H(I,K) - P
CONTINUE
260 CONTINUE
GO TO 70 ********** ONE ROOT FOUND **********
270 WR(EN) = X + T WI(EN) = 0.0 EN = NA GO TO 60 ********** TWO ROOTS FOUND **********
280 P = (Y - X) / 2.0 Q = P * P + W ZZ = SQRT(ABS(Q))
X = X + T IF (Q .LT. 0.0) GO TO 320 ********** REAL PAIR **********
ZZ = P + SIGN(ZZ,P)
WR(NA) = X + ZZ WR (EN) = WR (NA) IF (ZZ .NE. 0.0) WR(EN) = X - W / ZZ
Wi(NA) = 0.0 WI(EN) = 0.0 GO TO 330
336
7.1-142
C ********** COMPLEX PAIR **********
320 WR(NA) = X + P
WR(EN) = X + P
WI(NA) = ZZ
WI(EN) = -zz
330 EN = ENM2
GO TO 60
C ********** SET ERROR -- NO CONVERGENCE TO AN
C EIGENVALUE AFTER 30 ITERATIONS **********
I000 IERR = EN
i001 RETURN
END
337
7. 1-143
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F287-2 HQR2
A Fortran IV Subroutine to Determine the Eigenvalues and Eigenvectors of a Real Upper Hessenberg Matrix.
May, 1972 July, 1975
i. PURPOSE.
The Fortran IV subroutine HQR2 computes the eigenvalues and eigenvectors of a real upper Hessenberg matrix using the QR methods The eigenvectors of a real general matrix can also be computed if ELMHES (F273) and ELTRAN (F220) or ORTHES (F275) and ORTRAN (F221) have been used to reduce this general matrix to Hessenberg form and to accumulate the transformations,
2. USAGE.
A, Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE HQR2(NM,N,LOW, IGH,H,WR,WI,Z,IERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays H and Z as specified in the DIMENSION statements for H and Z in the calling program.
is an integer input variable set equal to the order of the matrix H. N must be not greater than NM.
LOW, IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F269 for the details. If the matrix is not balanced, set LOW to 1 and IGH to N.
338
7.1-144
H
WR,WI
IERR
is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. On input, it contains the upper Hessenberg matrix. Note: HQR2 destroys this upper Hessenberg matrix.
are working precision real output one- dimensional variables of dimension at least N containing the real and imaginary parts, respectively, of the eigenvalues of the Hessenberg matrix. The eigenvalues are unordered except that complex conjugate pairs of eigenvalues appear consecutively with the eigenvalue having the positive imaginary part first.
is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. If the eigenvectors of the upper Hessenberg matrix are desired, then on input, Z contains the identity matrix of order N, and on output, contains the real and imaginary parts of the eigenvectors of this Hessenberg matrix. If the eigenvectors of a real general matrix are desired, then on input, Z contains the transformation matrix produced in ELTRAN or ORTRAN which reduced the general matrix to Hessenberg form, and on output, contains the real and imaginary parts of the eigenvectors of this real general matrix. If the J-th eigenvalue is real, the J-th column of Z contains its eigenvector. If the J-th ~eigenvalue is complex with positive imaginary part, the J-th and (J+l)-th columns of Z contain the real and imaginary parts of its eigenvector. The conjugate of this vector is the eigenvector for the conjugate eigenvalue. The eigenvectors are not normalized.
is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is ZerO.
339
7.1-145
B. Error Conditions and Returns.
If more than 30 iterations are required to determine an eigenvalue, this subroutine terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues in the WR and WI arrays should be correct for indices IERR+I,IERR+2,...,N, but no eigenvectors are computed.
If all the eigenvalues are determined within 30 iterations, IERR is set to zero.
C. Applicability and Restrictions.
To determine the eigenvalues and eigenvectors of a real general matrix, HQR2 should be preceded by ELMHES (F273) or ORTHES (F275) to provide a suitable upper Hessenberg matrix for HQR2 and by ELTRAN or ORTRAN to accumulate the transformations.
It is recommended in general that BALANC (F269) be used before ELMHES or ORTHES in which case BALBAK (F270) must be used after HQR2.
3. DISCUSSION OF METHOD AND ALGORITHM.
The eigenvalues are determined by the QR method. The essence of this method is a process whereby a sequence of upper Hessenberg matrices, unitarily similar to the original Hessenberg matrix, is formed which converges to a quasi- triangular matrix, that is, an upper Hessenberg matrix whose eigenvalues are the eigenvalues of Ixl or 2x2 principal submatrices. The rate of convergence of this sequence is improved by shifting the origin at each iteration. The arithmetic throughout the process is kept real by combining two iterations into one, using two real origin shifts or a pair of complex conjugate origin shifts. Before each iteration, the last Hessenberg form is checked for a possible splitting into submatrices. If a splitting occurs, only the lower submatrix participates in the next iteration. The similarity transformations used in each iteration are accumulated in the Z array.
The origin shifts at each iteration are the eigenvalues of the lowest 2x2 principal minor. Whenever a lowest ixl or 2x2 principal submatrix finally splits from the rest of the matrix, the eigenvalues of this submatrix are taken to be eigenvalues of the original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of
340
7.1-146
order i or 2. The tolerances in the splitting tests are proportional to the relative machine precision. The eigenvectors of this quasi-triangular matrix are determined by a back substitution process and then transformed to the eigenvectors of the original matrix, using the information in Z.
Some of the eigenvalues may have been isolated on the diagonal by the subroutine BALANC (F269). This information is transmitted to HQR2 through the parameters LOW and IGH. As a result, HQR2 immediately extracts the eigenvalues in rows i to LOW-I and IGH+I to N, and so applies the QR procedure to the submatrix situated in rows and columns LOW through IGH.
This subroutine is a translation of the Algol procedure HQR2 written and discussed in detail by Peters and Wilkinson (i).
4. REFERENCES.
1) Peters, G. and Wilkinson, J.H., Eigenvectors of Real and Complex Matrices by LR and QR Triangularizations, Num. Math. 16,181-204 (1970). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution II/15, 372-395, Springer-Verlag, 1971.)
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for real general matrices.
B. Accuracy.
The subroutine HQR2 is numerically stable (I); that is, each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original upper Hessenberg matrix.
341
7.1-147
SUBROUTINE HQR2(NM~N,LOW,IGH,H,WR,WI,Z,IERR)
INTEGER I,J,K,L,M,N,EN,II,JJ,LL,MM,NA,NM,NN,
X IGH,ITS,LOW,MP2,ENM2,IERR
REAL H(NM,N),WR(N),WI(N),Z(NM,N) REAL P,Q,R,S,T,W,X~Y,RA, SA,VI,VR,ZZ,NORM,MACHEP
REAL SQRT,ABS,SIGN INTEGER MIN0 LOGICAL NOTLAS
COMPLEX Z3
COMPLEX CMPLX REAL REAL,AIMAG
********** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.
MACHEP = ?
IERR = 0
NORM = 0.0 K = 1 ********** STORE ROOTS ISOLATED BY BALANC
AND COMPUTE MATRIX NORM **********
DO 50 I = !, N
40
DO 40 J = K, N NORM = NORM + ABS(H(I,J))
K = I IF (I .GE. LOW .AND. I .LE. IGH) GO TO 50
WR(1) = H(I,I) WI(1) = 0.0
50 CONTINUE
EN = IGH T=0.0 ********** SEARCH FOR NEXT E!GENVALUES **********
60 IF (EN .LT. LOW) GO TO 340
ITS = 0 NA = EN - 1
ENM2 = NA - 1 ********** LOOK FOR SINGLE SMALL SUB-DIAGONAL ELEMENT
FOR L=EN STEP -i UNTIL LOW DO -- **********
70 DO 80 LL = LOW, EN L = EN + LOW - LL IF (L .EQ. LOW) GO TO I00 S = ABS(H(L-I,L-I)) + ABS(H(L,L)) IF (S .EQ. 0.0) S = NORM IF (ABS(H(L,L-I)) .LE. MACHEP * S) GO TO I00
80 CONTINUE
342
7.1-148
********** FORM SHIFT ********** i00 X = H(EN,EN)
IF (L .EQ. EN) GO TO 270
Y = H(NA,NA)
W = H(EN,NA) * H(NA,EN)
IF (L .EQ. NA) GO TO 280 IF (ITS .EQ. 30) GO TO I000
IF (ITS .NE. i0 .AND. ITS .NE. 20) GO TO 130 ********** FORM EXCEPTIONAL SHIFT ********** T = T + X
DO 120 I = LOW, EN 120 H(l,l) = H(I,I) - X
S = ABS(H(EN,NA)) + ABS(H(NA,ENM2)) X= 0.75 * S Y = X
W = -0.4375 * S * S 130 ITS = ITS + i
• ********* LOOK FOR TWO CONSECUTIVE SMALL SUB-DIAGONAL ELEMENTS.
FOR M=EN-2 STEP -i UNTIL L DO -- ********** DO 140 MM = L, ENM2
M = ENM2 + L - MM ZZ = H(M,M) R = X - ZZ
S = Y - ZZ
P = (R * S - W) / H(M+I,M) + H(M,M+I) Q = H(M+I,M+I) - ZZ - R - S R = H(M+2,M+I)
S = ABS(P) + ABS(Q) + ABS(R) F = P / S
Q = Q / S R = R / S
IF (M .EQ. L) GO TO 150
IF (ABS(H(M,M-I)) * (ABS(Q) + ABS(R)) .LE. MACHEP * ABS(P)
X * (ABS(H(M-I,M-I)) + ABS(ZZ) + ABS(H(M+I,M+I)))) GO TO 150 140 CONTINUE
130 MP2 = M + 2
DO 160 I = MP2, EN H(I,I-2) = 0.0
IF (I .EQ. MP2) GO TO 160 H(I,I-3) = 0.0
160 CONTINUE
********** DOUBLE QR STEP INVOLVING ROWS L TO EN AND COLUMNS M TO EN **********
DO 260 K = M, NA NOTLAS = K .NE. NA
IF (K .EQ. M) GO TO 170 P = H(K,K-I)
Q = H(K+I,K-I) R = 0.0
343
7. 1-149
IF (NOTLAS) R = H(K+2,K-I) X = ABS(P) + ABS(Q) + ABS(R)
IF (X .EQ. 0.0) GO TO 260
P = P / X Q = Q / x
R = R / X 170 S = SIGN(SQRT(P*P+Q*Q+R*R),P)
IF (K .EQ. M) GO TO 180 H(K,K-I) = -S * X GO TO 190
180 IF (L .NE. M) H(K,K-I) = -H(K,K-I) 190 P = P + S
x=p/s Y = Q / S
ZZ=R/S e = Q / P R = R / e
• ********* ROW MODIFICATION **********
DO 210 J = K, N P = H(K,J) + Q * H(K+I,J)
IF (°NOT. NOTLAS) GO TO 200 P = P + R * H(K+2,J)
H(K+2,J) = H(K+2,J) - P * ZZ 200 H(K+I,J) = H(K+I,J) - P * Y
H(K,J) = H(K,J) - P * X 210 CONTINUE
J = MiN0(EN,K+3) ********** COLUMN MODIFICATION **********
DO 230 I = i, J
P = X * H(I,K) + Y * H(I,K+I) IF (.NOT. NOTLAS) GO TO 220
P = P + ZZ * H(I,K+2) H(l,K+2) = H(I,K+2) - P * R
220 H(I,K+I) = H(I,K+I) - P * Q H(!~K) = N(l,K) - P
230 CONTINUE ********** ACCUMULATE TRANSFORMATIONS **********
DO 250 I = LOW, IGN e = X * Z(I,K) + Y * Z(I,K+I)
IF (.NOT. NOTLAS) GO TO 240 P = P + ZZ * Z(I,K+2) Z(I,K+2) = Z(I,K+2) - P * R
240 Z(I,K+I) = Z(l,K+l) - P * Q
Z(I,K) = Z(I,K) - e 250 CONTINUE
260 CONTINUE
GO TO 70
344
7. i- 150
C ********** ONE ROOT FOUND **********
270 H(EN,EN) = X + T WR(EN) = H(EN,EN)
WI(EN) = 0.0 EN = NA GO TO 60
C ********** TWO ROOTS FOUND ********** 280 P = (Y - X) / 2.0
Q = P * P + W ZZ = SQRT (ABS (Q))
H(EN,EN) = X + T X = H(EN,EN)
H(NA,NA) = Y + T
IF (Q .LT. 0.0) GO TO 320 C ********** REAL PAIR **********
ZZ = P + SIGN(ZZ,P)
WR(NA) = X + ZZ WR(EN) = WR(NA)
IF (ZZ .NE. 0.0) WR(EN) = X - W / ZZ WI(NA) = 0.0 WI(EN) = 0.0
X = H(EN,NA)
S = ABS(X) + ABS(ZZ) F = X / S Q=ZZ/S R = SQRT (P*P+Q*Q) P = P / R
Q = Q / R
C ********** ROW MODIFICATION ********** DO 290 J = NA, N
ZZ = H(NA,J)
H(NA,J) = Q * ZZ + e * H(EN,J)
H(EN,J) = Q * H(EN,J) - P * ZZ 290 CONTINUE
C ********** COLUMN MODIFICATION ********** DO 300 I = i, EN
ZZ = H(I,NA)
H(I,NA) = Q * zz + P * H(I,EN) H(I,EN) = Q * H(I,EN) - P * ZZ
300 CONTINUE
C ********** ACCUMULATE TRANSFORMATIONS ********** DO 310 I = LOW, IGH
ZZ = Z(I,NA)
Z(I,NA) = Q * ZZ + P * Z(I,EN) Z(I,EN) = Q * Z(I,EN) - P * ZZ
310 CONTINUE
GO TO 330
345
7. 1-151
C ********** COMPLEX PAIR ***~****** 320 WR(NA) = X + P
WR(EN) = X + P WI(~A) = zz
WI(EN) = -ZZ
330 EN = ENM2 GO TO 60
C ********** ALL ROOTS FOUND. BACKSUBSTITUTE TO FIND
C VECTORS OF UPPER TRIANGULAR FORM **********
340 IF (NORM oEQ. 0.0) GO TO i001
C ********** FOR EN=N STEP -i UNTIL 1 DO -- ********** DO 800 NN = i, N
EN = N + I - NN
P = WR(EN) Q = WI(EN)
NA = EN - 1 IF (q) 710, 600, 800
C ********** REAL VECTOR ********** 600 M = EN
H(EN,EN) = 1.0 IF (NA .EQ. 0) GO TO 800
C ********** FOR I=EN-I STEP -I UNTIL i DO -- **********
DO 700 II = i, NA
I = EN - II W = H(I,I) - e
R = H(l,EN)
IF (M .GT. NA) GO TO 620
610 DO 610 J = M, NA R = R + H(I,J) * II(J,EN)
620 IF (WI(I) .GE. 0.0) GO TO 630
ZZ = W S = R
GO TO 700 630 M = I
IF (WI(1) .RE. 0.0) GO TO 640 T = W IF (W .EQ. 0.0) r = MACHEP * NORM
H(I,EN) = -R / T
GO TO 700 C ********** SOLVE REAL EQUATIONS **********
640 X = H(I,I+I) Y = H(I+I,I) Q = (WR(1) -P) * (WR(1) -P)+ WI(1) * WI(1)
T = (X * S - ZZ * R) / Q H(I,EN) = T IF (ABS(X) .LE. ABS(ZZ)) GO TO 650 H(I+I,EN) = (-R - W * T) / X
GO TO 700 650 H(I+I,EN) = (-S - Y * T) / ZZ
700 CONTINUE C ********** END REAL VECTOR **********
GO TO 800
346
7.1-152
C ********** COMPLEX VECTOR ********** 710 M = NA
C *********~ LAST VECTOR COMPONENT CHOSEN IMAGINARY SO THAT C EIGENVECTOR MATRIX IS TRIANGULAR **********
IF (ABS(H(EN,NA)) .LE. ABS(H(NA, EN))) GO TO 720 H(NA,NA) = Q / H(EN,NA) H(NA,EN) = -(H(EN,EN) - P) / H(EN,NA) GO TO 730
720 Z3 = CMPLX(0.0,-H(NA, EN)) / CMPLX(H(NA,NA)-P,Q) H(NA,NA) = REAL(Z3) H(NA,EN) = AIMAG(Z3)
730 H(EN,NA) = 0.0 H(EN,EN) = 1.0 ENM2 = NA - i
IF (ENM2 .EQ. 0) GO TO 800 C ********** FOR I=EN-2 STEP -i UNTIL 1 DO -- **********
DO 790 II = I, ENM2 I = NA - II W = H(I,I) - e RA = 0.0 SA = H(I,EN)
760
770
X
780
DO 760 J = M, NA
RA = RA + H(I,J) * H(J,NA) SA = SA + H(I,J) * H(J,EN)
CONTINUE
IF (WI(I) .GE. 0.0) GO TO 770 ZZ = W R = RA S = SA GO TO 790 M = I
IF (WI(I) .NE. 0.0) GO TO 780 Z3 = CMPLX(-RA,-SA) / CMPLX(W,Q) H(I,NA) = REAL(Z3) H(I,EN) = AIMAG(Z3) GO TO 790
********** SOLVE COMPLEX EQUATIONS ********** X = H(I,I+I) Y = H(I+I,I)
VR = (WR(I) - P) * (WR(I) - P) + WI(I) * WI(I) - Q * q vI = (WR(I) - P) * 2.0 * Q
IF (VR .EQ. 0.0 .AND. VI .EQ. 0.0) VR = MACHEP * NORM * (ABS(W) + ABS(Q) + ABS(X) + ABS(Y) + ABS(ZZ))
Z3 = CMPLX(X*R-ZZ*RA+Q*SA,X*S-ZZ*SA-Q*RA) / CMPLX(VR,Vl) H(I,NA) = REAL(Z3) H(I,EN) = AIMAG(Z3)
IF (ABS(X) .LE. ABS(ZZ) + ABS(Q)) GO TO 785 H(I+I,NA) = (-RA - W * H(I,NA) + Q * H(I,EN)) / X H(I+I,EN) = (-SA - W * H(I,EN) - Q * H(I,NA)) / X GO TO 790
347
7.1-153
785 Z3 = CMPLX(-R-Y*H(I,NA),-S-Y*H(I,EN)) / CMPLX(ZZ,Q)
H(I+!,NA) = REAL(Z3)
H(I+I,EN) = AIMAG(Z3)
790 CONTINUE ********** END COMPLEX VECTOR **********
800 CONTINUE ********** END BACK SUBSTITUTION.
VECTORS OF ISOLATED ROOTS **********
DO 840 1 = i, N IF (I oGE. LOW .AND. I .LE. IGH) GO TO 840
820 DO 820 J = I t N Z(I,J) = H(I,J)
840 CONTINUE ********** MULTIPLY BY TRANSFORMATION MATRIX TO GIVE
VECTORS OF ORIGINAL FULL MATRIX.
FOR J=N STEP -I UNTIL LOW DO -- **********
DO 880 JJ = LOW~ N
J = N + LOW - JJ
M = MIN0(J,IGH)
DO 880 1 = LOW, IGH ZZ = 0.0
860 DO 860 K = LOW, M ZZ = ZZ + Z(I,K) * H(K,J)
Z(l,J) = ZZ
880 CONTINUE
GO TO I001 ********** SET ERROR -- NO CONVERGENCE TO AN
EIGENVALUE AFTER 30 ITERATIONS **********
i000 IERR = EN
i001 RETURN
END
348
7. 1-154
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F285-2 HTRIBK
A Fortran IV Subroutine to Back Transform the Eigenvectors of that Symmetric Tridiagonal Matrix Determined by HTRIDI.
May, 1972 July, 1975
I. PURPOSE.
The Fortran IV subroutine HTRIBK forms the eigenvectors of a complex Hermitian matrix from the eigenvectors of that real symmetric tridiagonal matrix determined by HTRIDI (F284).
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE HTRIBK(NM,N,AR,AI,TAU,M,ZR,ZI)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays AR, AI, ZR, and ZI as specified in the DIMENSION statements for AR, AI, ZR, and ZI in the calling program.
is an integer input variable set equal to the order of the matrix. N must be not greater than NM.
AR,AI are working precision real input two- dimensional variables with row dimension NM and column dimension at least N. The strict lower triangle of AR and the full lower triangle of AI contain some information about the unitary transformations used in the reduction to the tridiagonal form. The remaining upper parts of the matrices are arbitrary. See section 3 of F284 for the details.
349
7.1-155
TAU
M
ZR, ZI
is a working precision real input two- dimensional variable with row dimension 2 and column dimension at least N. TAU contains the remaining information about the unitary transformations. See section 3 of F284 for the details.
is an integer input variable set equal to the number of columns of Z = (ZR,ZI) to be back transformed.
are working precision real two-dimensional variables with row dimension NM and column dimension at least M. On input, the first M columns of ZR contain the real eigenvectors to be back transformed and the contents of ZI are immaterial. On output, these M columns of ZR and ZI contain the real and imaginary parts, respectively, of the transformed eigenvectors. The transformed eigenvectors are orthonormal if the input eigenvectors are orthonormal.
B. Error Conditions and Returns°
None°
Co Applicability and Restrictions.
This subroutine should be used in conjunction with the subroutine HTRIDI (F284).
3. DISCUSSION OF METHOD AND ALGORITHM.
Suppose that the Hermitian matrix C to the tridiagonal symmetric matrix transformation
(say) has been reduced F by the similarity
F = V Q cqv
where Q is a product of the unitary Hermitian matrices encoded in the lower triangles of AR and A!, and V is a unitary diagonal matrix encoded in TAU. Then, given an array Z of column vectors, HTRIBK computes the matrix product QVZ. If the eigenvectors of F are columns of the array Z, then HTRIBK forms the eigenvectors of C in their place. Since QV is unitary, vector Euclidean norms are preserved. Note that the last component of each transformed eigenvector is real.
350
7.1-156
This subroutine is a complex analogue of the subroutine TRBAKI (F279) which is a translation of the Algol procedure TRBAKI written and discussed in detail by Martin, Reinsch, and Wilkinson (i). A similar Algol procedure REVERSE is discussed in detail by Mueller (2).
4. REFERENCES.
1) Martin, R.S., Reinsch, C., and Wilkinson, J.H., Householder's Tridiagonalization of a Symmetric Matrix, Num. Math. 11,181-195 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 1I/2, 212-226, Springer-Verlag, 1971.)
2) Mueller, D.J., Householder's Method for Complex Matrices and Eigensystems of Hermitian Matrices, Num. Math. 8,72-92 (1966).
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for complex Hermitian matrices.
B. Accuracy.
The accuracy of HTRIBK can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of complex Hermitian matrices. In these paths, this subroutine is numerically stable (1,2). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.
351
7.1-157
C
C
C
SUBROUTINE HTRIBK(NM,N,AR,A!,TAU,M,ZR,Z!)
INTEGER !,J,K,L,M~N,NM REAL AR(NM,N),A!(NM,N),TAU(2,N)~ZR(NM,M),ZI(NM,M) REAL H,S,SI
I F (M .EQ. 0) GO TO 200 ********** TRANSFORM THE EIGENVECTORS OF THE REAL SYMMETRIC
TR!DIAGONAL MATRIX TO THOSE OF THE HERMITIAN TRIDIAGONAL MATRIX. **********
DO 50 K = I, N
DO 50 J = i~ M Z!(K,J) = -ZR(K,J) * TAU(e,K) ZR(K,J) = ZR(K,J) * TAU(I,K)
50 CONTINUE
IF (N .EQ. i) GO TO 200 ********** RECOVER AND APPLY THE HOUSEHOLDER MATRICES ********** DO 140 ! = 2, N
L = I - I H = AI(I,I) IF (H .EQ. 0.0) GO TO 140
DO 130 J = i, M
S = 0.0 Sl = 0.0
I i 0
DO Ii0 K = I, L S = S + AR(I,K) * ZR(K,J) - AI(I,K) * ZI(K,J) SI = SI + AR(I,K) * ZI(K,J) + AI(I,K) * ZR(K,J)
CONTINUE • ********* DOUBLE DIVISIONS AVOID POSSIBLE UNDERFLOW **********
S = (S / H) / H SI = (SI / H) / H
120
DO 120 K = i, L ZR(K,J) = ZR(K,J) - S * AR(I,K) - SI * AI(I,K) ZI(K,J) = ZI(K,J) - SI * AR(I,K) + S * AI(I,K)
CONTINUE
130 CONTINUE
140 CONTINUE
200 RETURN END
352
7.1-158
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F243 HTRIB3
A Fortran IV Subroutine to Back Transform the Eigenvectors of that Symmetric Tridiagonal Matrix Determined by HTRID3.
July, 1975
1. PURPOSE.
The Fortran IV subroutine HTRIB3 forms the eigenvectors of a complex Hermitian matrix from the eigenvectors of that real symmetric tridiagonal matrix determined by HTRID3 (F242).
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE HTRIB3(NM,N,A,TAU,M,ZR,ZI)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays A, ZR, and ZI as specified in the DIMENSION statements for A, ZR, and ZI in the calling program.
N is an integer input variable set equal to the order of the matrix. N must be not greater than NM.
A is a working precision real input two- dimensional variable with row dimension NM and column dimension at least N containing some information about the unitary transformations used in the reduction to the tridiagonal form. See section 3 of F242 for the details.
353
7.1-159
TAU
M
ZR, ZI
is a working precision real input two- dimensional variable with row dimension 2 and column dimension at least N. TAU contains the remaining information about the unitary transformations. See section 3 of F242 for the details.
is an integer input variable set equal to the number of columns of Z = (ZR,ZI) to be back transformed.
are working precision real two-dimensional variables with row dimension NM and column dimension at least M. On input, the first M columns of ZR contain the real eigenvectors to be back transformed and the contents of ZI are immaterial. On output, these M columns of ZR and ZI contain the real and imaginary parts, respectively, of the transformed eigenvectors. The transformed eigenvectors are orthonormal if the input eigenvectors are orthonormal.
B. Error Conditions and Returns,
None,
C. Applicability and Restrictions.
This subroutine should be used in conjunction with the subroutine HTRID3 (F242).
3. DISCUSSION OF METHOD AND ALGORITHM.
Suppose that the Hermitian matrix C to the tridiagonal symmetric matrix transformation
(say) has been reduced F by the similarity
F = V Q CQV
where Q is a product of the unitary Hermitian matrices encoded in A, and V is a unitary diagonal matrix encoded in TAU. Then, given an array Z of column vectors, HTRIB3 computes the matrix product QVZ. If the eigenvectors of F are columns of the array Z, then HTRIB3 forms the eigenvectors of C in their place. Since QV is unitary, vector Euclidean norms are preserved. Note that the last component of each transformed eigenvector is real.
354
7.1-160
This subroutine is a complex analogue of the subroutine TRBAK3 (F229) which is a translation of the Algol procedure TRBAK3 written and discussed in detail by Martin, Reinsch, and Wilkinson (i). A similar Algol procedure REVERSE is discussed in detail by Mueller (2).
4. REFERENCES.
I) Martin, R.S., Reinsch, C., and Wilkinson, J.H., Householder's Tridiagonalization of a Symmetric Matrix, Num. Math. 11,181-195 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/2, 212-226, Springer-Verlag, 1971.)
2) Mueller, D.J., Householder's Method for Complex Matrices and Eigensystems of Hermitian Matrices, Num. Math. 8,72-92 (1966).
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for complex Hermitian matrices.
B. Accuracy.
The accuracy of HTRIB3 can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of complex Hermitian matrices. In these paths, this subroutine is numerically stable (1,2). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.
355
7.1-161
C C C
C
C
C
SUBROUTINE HTRIB3(NM,N,A, TAU,M,ZR,ZI)
INTEGER !,J,K,L,M,N,NM REAL A(NM,N),TAU(2,N),ZR(NM,M),ZI(NM,M) REAL H,S,SI
IF (M .EQ. 0) GO TO 200 ********** TRANSFORM THE EIGENVECTORS OF THE REAL SYMMETRIC
TRiDIAGONAL MATRIX TO THOSE OF THE HERMITIAN TRIDIAGONAL MATRIX. **********
DO 50 K = I, N
DO 50 J = I, M
ZI(K,J) = -ZR(K,J) * TAU(2,K) ZR(K,J) = ZR(K,J) * TAU(I,K)
50 CONTINUE
IF (N .EQ. 1) GO TO 200 ********** RECOVER AND APPLY THE HOUSEHOLDER MATRICES ********** DO 140 I = 2, N
L = I - i H = A(I, I) IF (H .EQ. 0.0) GO TO 140
DO 130 J = i, M
S=0.0 Sl = 0.0
Ii0
DO Ii0 K = I, L S = S + A(I,K) * ZR(K,J) - A(K,I) * ZI(K,J) SI = Si + A(I,K) * ZI(K,J) + A(K,I) * ZR(K,J)
CONTINUE • ********* DOUBLE DIVISIONS AVOID POSSIBLE UNDEKFLOW **********
S = (S / H) / H SI = (SI / H) / H
120
DO !20 K = i, L ZR(K,J) = ZR(K,J) - S * A(I,K) - SI * A(K,I) ZI(K,J) = ZI(K,J) - SI * A(I,K) + S * A(K,I)
CONTINUE
130 CONTINUE
140 CONTINUE
200 RETURN END
356
7.1-162
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F284-2 HTRIDI
A Fortran IV Subroutine to Reduce a Complex Hermitian Matrix to a Real Symmetric Tridiagonal Matrix Using
Unitary Transformations.
May, 1972 July, 1975
i. PURPOSE.
The Fortran IV subroutine NTRIDI reduces a complex Hermitian matrix to a real symmetric tridiagonal matrix using unitary similarity transformations. This reduced form is used by other subroutines to find the eigenvalues and/or eigenvectors of the original matrix. See section 2C for the specific routines.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE HTRIDI(NM,N,AR,AI,D,E,E2,TAU)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays AR and AI as specified in the DIMENSION statements for AR and AI in the calling program.
is an integer input variable set equal to the order of the matrix A = (AR,AI). N must be not greater than NM.
357
7. 1-163
AR,AI
E2
TAU
are working precision real two-dimensional variables with row dimension NM and column dimension at least N. On input, AR and AI contain the real and imaginary parts, respectively, of the Hermitian matrix of order N to be reduced to tridiagonal form. Only the full lower triangles of the matrices need be supplied. On output, the strict lower triangle of AR and the full lower triangle of AI contain some information about the unitary transformations used in the reduction. The full upper triangle of AR and the strict upper triangle of AI are unaltered. See section 3 for the details.
is a working precision real output one- dimensional variable of dimension at least N containing the diagonal elements of the real symmetric tridiagonal matrix.
is a working precision real output one- dimensional variable of dimension at least N containing, in its last N-I positions, the subdiagonal elements of the tridiagonal matrix. The element E(1) is set to zero.
is a working precision real output one- dimensional variable of dimension at least N containing, in its last N-I positions, the squares of the subdiagonal elements of the tridiagonal matrix. The element E2(1) is set to zero. E2 need not be distinct from E (non-standard usage acceptable with at least those compilers included in the certification statement), in which case no squares are returned.
is a working precision real output two- dimensional variable with row dimension 2 and column dimension at least N. TAU contains the remaining information about the unitary transformations. See section 3 for
the details.
B. Error Conditions and Returns.
None.
358
7.1-164
C. Applicability and Restrictions.
If all the eigenvalues of the original matrix are desired, this subroutine should be followed by TQLI (F289), IMTQLI (F291), or TQLRAT (F235).
If all the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by TQL2 (F290) or IMTQL2 (F292), and then by HTRIBK (F285).
If some of the eigenvalues of the original matrix are desired, this subroutine should be followed by BISECT (F294) or TRIDIB (F237).
If some of the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by TSTURM (F293), or by BISECT (F294) and TINVIT (F223), or by TRIDIB (F237) and TINVIT, or by IMTQLV (F234) and TINVIT, and then by HTRIBK (F285).
3. DISCUSSION OF METHOD AND ALGORITHM.
The tridiagonal reduction is performed in the following way. Starting with J=N, the elements in the J-th row to the left of the diagonal of (AR,AI) are first scaled, to avoid possible underflow in the transformation that might result in severe departure from orthogonality. The sum of squared magnitudes SIGMA of these scaled elements is next formed. Then, a vector U and a scalar
= u u/2
define an operator
P = I - UU /H
which is unitary and Hermitian and for which the similarity transformation PAP eliminates the elements in the J-th row of A to the left of the subdiagonal and the symmetrical elements in the J-th column.
The non-zero components of U are the elements of the J-th row to the left of the diagonal with the last of them augmented by the square root of SIGMA times the subdiagonal element divided by its magnitude. By storing the transformed subdiagonal element elsewhere and not overwriting the column elements eliminated in the transformation, full information about P is saved for later use in HTRIBK. The transformed subdiagonal element is then rendered real by a diagonal unitary transformation.
359
7.1-165
The above steps are repeated on further rows of the transformed A in reverse order until A is reduced to symmetric tridiagonal form; that is, repeated for J = N-I,N-2,...,3.
The product of the diagonal unitary transformations is accumulated into a unitary diagonal matrix whose diagonal elements are saved in TAU for later use in HTRIBK.
This subroutine is a complex analogue of the subroutine TREDI (F277) which is a translation of the Algol procedure TREDI written and discussed in detail by Martin, Reinsch, and Wilkinson (i). A similar Algol procedure HOUSEHOLDER HERMITIAN is discussed in detail by Mueller (2).
4. REFERENCES.
!)
2)
Martin, R.S., Reinsch, C., and Wilkinson, J.H., Householder's Tridiagonalization of a Symmetric Matrix, Num. Math, 11,181-195 (1968). (Reprinted in Handbook for Automatic Computation, Volume !I, Linear Algebra~ J. H. Wilkinson - C. Reinsch, Contribution 11/2, 212-226, Springer-Verlag, 1971.)
Mueller~ D.J., Householder's Method for Complex Matrices and Eigensystems of Hermitian Matrices, Num. Math. 8,72-92 (1966).
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for complex Hermitian matrices.
B. Accuracy~
The accuracy of HTRIDI can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of complex Hermitian matrices. In these paths, this subroutine is numerically stable (1,2). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenveetors of that matrix~
360
7.1-166
SUBROUTINE HTRIDI(NM,N,AR,Ai,D,E,E2,TAU)
INTEGER I,J,K,L,N,II,NM,JPI
REAL AR(NM,N),AI(NM,N),D(N),E(N),E2(N),TAU(2,N) REAL F,G,H,FI,GI,HH,SI,SCALE REAL SQRT,CABS,ABS COMPLEX CMPLX
TAU(I,N) = 1.0 TAU(2,N) = 0.0
DO I00 I = i, N I00 D(1) = AR(I,!)
C ********** FOR I=N STEP -I UNTIL I DO -- ********** DO 300 II = i, N
I = N + 1 - II L = I - i H= 0.0 SCALE = 0.0
IF (L .LT. i) GO TO 130 C ********** SCALE ROW (ALGOL TOL THEN NOT NEEDED) *~********
DO 120 K = i, L 120 SCALE = SCALE + ABS(AR(!,K)) + ABS(AI(I,K))
130
IF (SCALE .NE. 0.0) GO TO 140 TAU(I,L) = 1.0 TAU(2,L) = 0.0 E(1) = 0.0 E2 (I) = 0.0 GO TO 290
140
150
DO 150 K = i, L AR(I,K) = AR(I,K) / SCALE AI(I,K) = AI(I,K) / SCALE H = N + AR(I,K) * AR(I,K) + AI(I,K) * AI(I,K)
CONTINUE
160
E2(1) = SCALE * SCALE * H G = SQRT (H) E(1) = SCALE * G F = CABS(CMPLX(AR(I,L),AI(I,L)))
• ********* FORM NEXT DIAGONAL ELEMENT OF MATRIX T ********** IF (F .EQ. 0°0) GO TO 160
TAU(I,L) = (AI(I,L) * TAU(2,1) - AR(I,L) * TAU(I,I)) / F SI = (AR(I,L) * TAU(2,1) + AI(I,L) * TAU(I,I)) / F H = H + F * G G = 1.0 + G / F AR(I,L) = G * AR(I,L) AI(I,L) = G * AI(I,L) IF (L .EQ. i) GO TO 270 GO TO 170 TAU(I,L) = -TAU(I,I) SI = TAU(2,!) AR(I,L) = G
361
7.1-167
170
180
F = 0°0
DO 240 J = I, L
g = 0.0
GI = 0.0
********** FORM ELEMENT OF A*U **********
DO 180 K = i, J
G = G + AR(J,K) * AR(I,K) + A!(J,K) * AI(I,K)
GI = GI - AR(J,K) * AI(I,K) + AI(J,K) * AR(I,K)
CONTINUE
JPI = 7 + I
IF (L oLT. JPI) GO TO 220
DO 200 K = JPI, L
G = G + AR(K,J) * AR(I,K) - AI(K,J) * AI(I,K)
GI = GI - AR(K,J) * AI(I,K) - AI(K,J) * AR(I,K)
200 CONTINUE
• ********* FORM ELEMENT OF P **********
220 E(J) = G / H
TAU(2,J) = GI / H
F = F + E(J) * AR(I,J) - TAU(2,J) * AI(I,J)
240 CONTINUE
HH = F / (H + H)
********** FORM REDUCED A **********
DO 260 J = i, L
F = AR(i,J)
G = E(J) - HH * F
E (J) = g
FI = -AI(I,J)
GI = TAU(2,J) - HH * FI
TAU(2,J) = -GI
X
X
260
DO 260 K = I, J
AR(J,K) = AR(J,K) - F * E(K) - G * AR(I,K) + FI * TAU(2,K) + GI * AI(I,K)
AI(J,K) = AI(J,K) - F * TAU(2,K) - G * AI(I,K)
- FI * E(K) - GI * AR(I,K)
CONTINUE
2 7 0
280
DO 280 K = i, L
AR(I,K) = SCALE * AR(I,K)
AI(I,K) = SCALE * AI(I,K)
CONTINUE
TAU(2,L) = -SI
290 HH = D(I)
D(1) = AR(I,I)
AR(I,I) = HH
AI(I,I) = SCALE * SQRT(H)
300 CONTINUE
362
7.1-168
C RETURN END
363
7. i-!69
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F242 HTRID3
A Fortran IV Subroutine to Reduce a Complex Hermitian Matrix, Stored as a Single Square Array, to a Real
Symmetric Tridiagonal Matrix Using Unitary Transformations.
July, 1975
Io PURPOSE°
The Fortran IV subroutine HTRID3 reduces a complex Hermitian matrix, stored as a single square array, to a real symmetric tridiagonal matrix using unitary similarity transformations. This reduced form is used by other subroutines to find the eigenvalues and/or eigenvectors of the original matrix. See section 2C for the specific routines.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE HTRID3(NM,N,A,D,E,E2,TAU)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional array A as specified in the DIMENSION statement for A in the calling program.
is an integer input variable set equal to the order of the matrix. N must be not greater than NM.
is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. On input, A contains the lower triangle of the Hermitian matrix of order N to be reduced to tridiagonal form. If the real part of A
364
7. 1-170
E2
TAU
is denoted by AR and the imaginary part by AI, then the full lower triangle of AR should be stored in the full lower triangle of A and the strict lower triangle of AI should be stored in the transposed positions of the strict upper triangle of A. No storage is required for the zero diagonal elements of AI. For example when N=4, A should contain
(AR(I,I) AI(2,1) AI(3,1) AI(4,1) ) (AR(2,1) AR(2,2) AI(3,2) AI(4,2) ) (AR(3,1) AN(3,2) AR(3,3) AI(4,3) ) (AR(4,1) AR(4,2) AN(4,3) AN(4,4) ).
(If the upper triangle of AI is stored instead, the eigenvalues are not changed but the eigenvectors are conjugated.) On output, A contains some information about the unitary transformations used in the reduction. See section 3 for the details.
is a working precision real output one- dimensional variable of dimension at least N containing the diagonal elements of the real symmetric tridiagonal matrix.
is a working precision real output one- dimensional variable of dimension at least N containing, in its last N-I positions, the subdiagonal elements of the tridiagonal matrix. The element E(1) is set to zero.
is a working precision real output one- dimensional variable of dimension at least N containing, in its last N-I positions, the squares of the subdiagonal elements of the tridiagonal matrix. The element E2(1) is set to zero. E2 need not be distinct from E (non-standard usage acceptable with at least those compilers included in the certification statement), in which case no squares are returned.
is a working precision real output two- dimensional variable with row dimension 2 and column dimension at least N. TAU contains the remaining information about the unitary transformations. See section 3 for the details.
365
7.1-171
B. Error Conditions and Returns.
None.
C. Applicability and Restrictions.
If all the eigenvalues of the original matrix are desired, this subroutine should be followed by TQLI (F289), IMTQLI (F291), or TQLRAT (F235).
If all the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by TQL2 (F290) or IMTQL2 (F292), and then by HTRIB3 (F243) .
If some of the eigenvalues of the original matrix are desired, this subroutine should be followed by BISECT (F294) or TRIDIB (F237).
If some of the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by TSTURM (F293), or by BISECT (F294) and TINVIT (F223), or by TRIDIB (F237) and TINVIT, or by IMTQLV (F234) and TINVIT, and then by HTRIB3 (F243).
3. DISCUSSION OF METHOD AND ALGORITHM.
The tridiagonal reduction is performed in the following way~ Starting with J=N, the elements in the J-th row to the left of the diagonal of A are first scaled, to avoid possible underflow in the transformation that might result in severe departure from orthogonality. The sum of squared magnitudes SIGMA of these scaled elements is next formed. Then, a vector U and a scalar
H = U U/2
define an operator
P = I - UU /H
which is unitary and Hermitian and for which the similarity transformation PAP eliminates the elements in the J-th row of A to the left of the subdiagonal and the symmetrical elements in the J-th column.
366
7.1-172
The non-zero components of U are the elements of the J-th row to the left of the diagonal with the last of them augmented by the square root of SIGMA times the subdiagonal element divided by its magnitude. By storing the transformed subdiagonal element elsewhere and not overwriting the column elements eliminated in the transformation, full information about P is saved for later use in HTRIB3. The transformed subdiagonal element is then rendered real by a diagonal unitary transformation.
The above steps are repeated on further rows of the transformed A in reverse order until A is reduced to symmetric tridiagonal form; that is, repeated for J = N-I,N-2,...,3.
The product of the diagonal unitary transformations is accumulated into a unitary diagonal matrix whose diagonal elements are saved in TAU for later use in HTRIB3.
This subroutine is a complex analogue of the subroutine TRED3 (F228) which is a translation of the Algol procedure TRED3 written and discussed in detail by Martin~ Reinsch, and Wilkinson (I). A similar Algol procedure HOUSEHOLDER HERMITIAN is discussed in detail by Mueller (2).
4. REFERENCES.
i) Martin, R.S., Reinsch, C., and Wilkinson, J.H., Householder's Tridiagonalization of a Symmetric Matrix, Num. Math. 11,181-195 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/2, 212-226, Springer-Verlag, 1971.)
2) Mueller, D.J., Householder's Method for Complex Matrices and Eigensystems of Hermitian Matrices, Num. Math. 8,72-92 (1966).
5. CHECKOUT.
A. Test Cases°
See the section discussing testing of the codes for complex Hermitian matrices.
367
7.1-173
B° Accuracy.
The accuracy of HTRID3 can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of complex Hermitian matrices. In these paths, this subroutine is numerically stable (1,2). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.
368
7.1-174
120
130
140
150
160
170
SUBROUTINE HTRID3(NM,N,A,D,E,E2,TAU)
INTEGER I,J,K,L,N,II,NM,JMI,JPI
REAL A(NM,N),D(N),E(N),E2(N),TAU(2,N) REAL F,G,H,FI,GI,HH,SI,SCALE REAL SQRT,CABS,ABS COMPLEX CMPLX
TAU(I,N) = 1.0 TAU(2,N) = 0.0 ********** FOR I=N STEP -i UNTIL i DO -- ********** DO 300 II = i~ N
I = N + I - II L = I - i H = 0.0 SCALE = 0.0 IF (L .LT. i) GO TO 130
********** SCALE ROW (ALGOL TOL THEN NOT NEEDED) ********** DO 120 K = i, L SCALE = SCALE + ABS(A(I,K)) + ABS(A(K,I))
IF (SCALE .NE. 0.0) GO TO 140 TAU(I,L) = 1.0 TAU(2,L) = 0.0 E(I) = 0.0 E2(1) = 0.0 GO TO 290
DO 150 K = I, L A(I,K) = A(I,K) / SCALE A(K,I) = A(K,I) / SCALE N = H + A(I,K) * A(I,K) + A(K,!) * A(K,I)
CONTINUE
E2(1) = SCALE * SCALE * H G -- SQRT (I{) E(1) = SCALE * G F = CABS(CMPLX(A(I,L),A(L,I)))
• ********* FORM NEXT DIAGONAL ELEMENT OF MATRIX T ********** IF (F .EQ. 0.0) GO TO 160
TAU(I,L) = (A(L,I) * TAU(2,1) - A(I,L) * TAU(I,I)) / F SI = (A(I,L) * TAU(2,1) + A(L,I) * TAU(I,I)) / F H = H + F * G G = 1.0 + G / F
A(I,L) = G * A(I,L) A(L,I) = G * A(L,I) IF (L .EQ. i) GO TO 270 GO TO 170 TAU(I,L) = -TAU(I,I) SI = TAU(2,1) A(I,L) = G F = 0.0
369
o
t~
00
,~l
o'~
o o
o
0 ~
c~
0 0
0
II
11
II
L...;
L-~
t~
o 0 0
~ ¢-
,o I|
tl 11
I I
+ l
H I,o
I
+
C~
~e
h.."
C.+
~
r-4
II
II 0
• :'~
+J
II
(++,
+ P,
~ t',+
:, L"
x'J ~
:"
¢--+
+'+
++++
+
r~
. t+
.+
B+,
~>
c~
t-I
II 0~
+'+~
t";
t'J
H
",~
(~,+
-x
C~
~-'+
'~
~ I
.0
¢~-
¢.-<
r..
.+
+-~
~ -
~"
II I-
o-
l v
~
4"
Ix)
C)
~"
¢7'
~x~
+ H t-t
¢'~
cb
ix0
Ix~
P~
o o
o o
~+.
~e
II
(~I
r..-~
'
~
II
>r'J
~
II
+ r_
.,,
O~
II
• ..
.+"
+~;'+
j I::~
L+
~"J
(~
¢",
II "~
t-'1
4 +
L~
;--+
Bx-J
['x'-J
+w
+.+x ~
I,-.-t
C.
+
I ~t
++ ~
-~
Pe
~ I
.++'+'
x +
t--4
~
¢"b
o o
0 "~
J ~
H 0
l'O
~ II
I--:j
. ~
+
tt
xJ
t.~
o :+
~
+--t
o +-
---+
H Oo
I10~
'J
II 0
I+-1
+ II
L'
~ I
~>
+...-
, L -+
+,,~
+ e..
,+
[-rj
+ '.
~ i.-
+ i..
-..]
.++.
+.
~++'+
H
:g-+
c-x+
i,+4
+ .+
~+
+ + +
~
:e,+
¢+++
.. +
+ x-
-
U
O
I1
0 li
II
r_.+
0
~:~
O"
L~O
0 0 0
¢-,j
'7 +....,
,k.n
7.1-176
TAU(2,L) = -SI 290 D(1) = A(I,I)
A(I,I) = SCALE * SQRT(H) 300 CONTINUE
RETURN END
371
7.1-177
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F234 !MTQLV
A Fortran IV Subroutine to Determine the Eigenvalues of a Symmetric Tridiagonal Matrix.
July, 1975
I. PURPOSE.
The Fortran IV subroutine IMTQLV is a variant of IMTQLI (F291) that determines the eigenvalues of a symmetric tridiagonal matrix using the implicit QL method, and associates with them their corresponding submatrix indices. This feature and the preservation of the input matrix make it possible to later determine the eigenvectors of the matrix.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE IMTQLV(N,D,E,E2,W, IND,IERR,RVI)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
is an integer input variable set equal to the order of the matrix.
is a working precision real input one- dimensional variable of dimension at least N containing the diagonal elements of the symmetric tridiagonal matrix.
is a working precision real input one- dimensional variable of dimension at least N containing, in its last N-I positions, the subdiagonal elements of the symmetric tridiagonal matrix. E(1) is arbitrary.
372
7.1-178
E2
IND
IERR
RVI
is a working precision real one-dimensional variable of dimension at least N. On input, the last N-I positions in this array contain the squares of the subdiagonal elements of the symmetric tridiagonal matrix. E2(1) is arbitrary. On output, E2(1) is set to zero. If any of the elements in E are regarded as negligible, the corresponding elements of E2 are set to zero, indicative of the splitting of the matrix into a direct sum of submatrices.
is a working precision real output one- dimensional variable of dimension at least N containing the eigenvalues of the symmetric tridiagonal matrix. The eigenvalues are in ascending order in W.
is an integer output one-dimensional variable of dimension at least N containing the submatrix indices associated with the corresponding eigenvalues in W. Eigenvalues belonging to the first submatrix have index i, those belonging to the second submatrix have index 2, etc.
is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
is a working precision real temporary one- dimensional variable of dimension at least N used to copy the subdiagonal array E which would otherwise be destroyed.
B. Error Conditions and Returns.
If more than 30 iterations are required to determine an eigenvalue, IMTQLV terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues in the W array should be correct for indices 1,2,...,IERR-I. These eigenvalues are ordered but are not necessarily the smallest IERR-I eigenvalues.
If all the eigenvalues are determined within 30 iterations, IERR is set to zero.
373
7.1-179
C. Applicability and Restrictions.
The subroutine TQLI (F289) can also be used to compute the eigenvalues of a symmetric tridiagonal matrix. (No variant of TQLI is available that associates submatrix indices with the eigenvalues.) Note, however, that TQLI does not perform well on matrices whose successive row sums vary widely in magnitude and are not strictly increasing from the first to the last row. IMTQLV is not sensitive to such row sums and is therefore especially recommended for symmetric tridiagona! matrices whose structure is not known.
To determine the eigenvalues of a full symmetric matrix, IMTQLV should be preceded by TREDI (F277) to provide a suitable symmetric tridiagonal matrix for IMTQLV.
To determine the eigenvalues of a complex Hermitian matrix, IMTQLV should be preceded by HTRIDI (F284) to provide a suitable real symmetric tridiagonal matrix for IMTQLV.
Note, however, that although IMTQLV may perform better on symmetric tridiagonal matrices poorly structured in the above sense, TREDI and HTRIDI may also perform poorly on such full symmetric and complex Hermitian matrices. Hence, any advantage in using IMTQLV over TQLI may be overshadowed by a poor performance in TREDI or HTRIDI.
The eigenvalues of certain non-symmetric tridiagonal matrices can be computed using the combination of FIGI (F280) and IMTQLV. See F280 for the description of this special class of matrices. For such matrices~ IMTQLV should be preceded by FIGI to provide a suitable symmetric matrix for IMTQLV.
To determine eigenvectors associated with the computed eigenvalues, !MTQLV should be followed by TINVIT (F223) and the appropriate back transformation subroutine -- TRBAKI (F279) after TREDI, HTRIBK (F285) after HTRIDI, or BAKVEC (F281) after FIGI.
3. DISCUSSION OF METHOD AND ALGORITHM.
The eigenvalues are determined by the implicit QL method. The essence of this method is a process whereby a sequence of symmetric tridiagonal matrices, unitarily similar to the original symmetric tridiagonal matrix, is formed which converges to a diagonal matrix. The rate of convergence of this sequence is improved by implicitly shifting the origin
374
7.1-180
at each iteration. Before each iteration, the symmetric tridiagonal matrix is checked for a possible splitting into submatrices. If a splitting occurs, only the uppermost submatrix participates in the next iteration. The eigenvalues are ordered in ascending order as they are found.
The origin shift at each iteration is the eigenvalue of the current uppermost 2x2 principal minor closer to the first diagonal element of this minor. Whenever the uppermost ixl principal submatrix finally splits from the rest of the matrix, its element is taken to be an eigenvalue of the original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of order i. The tolerances in the splitting tests are proportional to the relative machine precision.
This subroutine is a modification of the subroutine IMTQLI which is a translation of the Algol procedure IMTQLI written and discussed in detail by Martin and Wilkinson (i) and modified by Dubrulle (2).
4. REFERENCES.
i) Martin, R.S. and Wilkinson, J.H., The Implicit QL Algorithm, Num. Math. 12,377-383 (1968).
2) Dubrulle, A., A Short Note on the Implicit QL Algorithm, Num. Math. 15,450 (1970). (Combined With (i) in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution II/4, 241-248, Springer-Verlag, 1971.)
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for complex Hermitian, real symmetric, real symmetric tridiagonal, and certain real non-symmetric tridiagonal matrices.
B. Accuracy.
The subroutine IMTQLV is numerically stable (1,2); that is, the computed eigenvalues are close to those of the original matrix. In addition, they are the exact eigenvalues of a matrix close to the original real symmetric tridiagonal matrix.
375
7,1-181
SUBROUTINE IMTQLV(N,D,E,E2,W, IND,IERR,RVI)
INTEGER I,J,K,L,M,N,II,MML,TAG,!ERR REAL D(N),E(N),E2(N),W(N),RVI(N) REAL B,C,P,G,P,R,S,MACHEP REAL SQRT,ABS,SIGN INTEGER IND(N)
********** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.
MACHEP = ?
IERR = 0
K = 0 TAG = 0
DO i00 1 = i, N w(1) = D(I) IF (I .NE. i) RVI(I-I) = E(i)
100 CONTINUE
E2(1) = 0.0 RVI(N) = 0.0
DO 290 L = i, N J = 0
C ********** LOOK FOR SMALL SUB-DIAGONAL ELEMENT **********
105 DO ii0 M = L, N IF (M .EQ. N) GO TO 120 IF (ABS(RVI(M)) .LE. MACHEP * (ABS(W(M)) + ABS(W(M+I))))
X GO TO 120 C ********** GUARD AGAINST UNDERFLOWED ELEMENT OF E2 **********
IF (E2(M+I) .EQ. 0.0) GO TO 125
ii0 CONTINUE
C
120
125
130
IF (M .LE. K) GO TO 130 IF (M ,NE. N) E2(M+I) = 0.0
K = M TAG = TAG + I P = W(L) IF (M .EQ. L) GO TO 215 IF (J .EQ. 30) GO TO i000 J = J + i
********** FORM SHIFT ********** G = (W(L+I) - P) / (2.0 * RVI(L)) R = SQRT (G'G+1.0) G = W(M) - P + RVI(L) / (g + SIGN(R,G))
S = 1.0 C = 1,0 P = 0.0 MML = M - L
376
7.1-182
150
160
200
********** FOR I--M-I STEP -i UNTIL L DO -- **********
DO 200 II = i, MML
I = M - II
F = S * RVI(I)
B = C * RVI(I)
IF (ABS(F) .LT. ABS(G)) GO TO 150
C = G / F
R = SQRT(C*C+I.0)
RVI(I+I) = F * R
S = 1 . 0 / R C = C * S
GO TO 160
S = F / G
R = SQRT(S*S+I.0)
RVI(I+I) = G * R
C = 1.0 / R
S = S * C
G = W(I+I) - P
R = (W(1) - G) * S + 2.0 * C * B
P = S * R
W(I+I) = G + P
G = C * R - B
CONTINUE
W(L) = W(L) - P
RVI(L) = G
RVI(M) = 0.0
GO TO 105
********** ORDER EIGENVALUES **********
215 IF (L .EQ. I) GO TO 250
********** FOR I=L STEP -i UNTIL 2 DO -- **********
DO 230 II = 2, L
I = L 4. 2 - II
IF (P .GE. W(I-I)) GO TO 270
w(i) = w(i-1)
IND(I) = IND(I-I)
230 CONTINUE
250 I = 1
270 W(I) = P
IND(I) = TAG
290 CONTINUE
GO TO I001
C ********** SET ERROR -- NO CONVERGENCE TO AN
C EIGENVALUE AFTER 30 ITERATIONS **********
i000 IERR = L
i001 RETURN
END
377
7.1-183
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F291 IMTQLI
A Fortran IV Subroutine to Determine the Eigenvalues of a Symmetric Tridiagonal Matrix.
May, 1972
i. PURPOSE.
The Fortran IV subroutine IMTQLI determines the eigenvalues of a symmetric tridiagonal matrix using the implicit QL method.
2. USAGE.
A~ Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE IMTQLI(N,D,E,IERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
is an integer input variable set equal to the order of the matrix.
is a working precision real one-dimensional variable of dimension at least N. On input, it contains the diagonal elements of the symmetric tridiagonal matrix. On output, it contains the eigenvalues of this matrix in ascending order.
is a working precision real one-dimensional variable of dimension at least N. On input, the last N-I positions in this array contain the subdiagonal elements of the symmetric tridiagonal matrix. E(1) is arbitrary. Note that IMTQLI destroys E.
378
7.1-184
IERR is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
B. Error Conditions and Returns.
If more than 30 iterations are required to determine an eigenvalue, IMTQLI terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues in the D array should be correct for indices 1,2,...,IERR-I. These eigenvalues are ordered but are not necessarily the smallest IERR-I eigenvalues.
If all the eigenvalues are determined within 30 iterations, IERR is set to zero.
C. Applicability and Restrictions.
The subroutine TQLI (F289) can also be used to compute the eigenvalues of a symmetric tridiagonal matrix. Note, however, that TQLI does not perform well on matrices whose successive row sums vary widely in magnitude and are not strictly increasing from the first to the last row. IMTQLI is not sensitive to such row sums and is therefore especially recommended for symmetric tridiagonal matrices whose structure is not known.
To determine the eigenvalues of a full symmetric matrix, IMTQLI should be preceded by TREDI (F277) to provide a suitable symmetric tridiagonal matrix for IMTQLI.
To determine the eigenvalues of a complex Hermitian matrix, IMTQLI should be preceded by HTRIDI (F284) to provide a suitable real symmetric tridiagonal matrix for IMTQLI.
Note, however, that although IMTQLI may perform better on symmetric tridiagonal matrices poorly structured in the above sense, TREDI and HTRIDI may also perform poorly on such full symmetric and complex Hermitian matrices. Hence, any advantage in using IMTQLI over TQLI may be overshadowed by a poor performance in TREDI or HTRIDI.
379
7.1-185
The eigenvalues of certain non-symmetric tridiagonal matrices can be computed using the combination of FIGI (F280) and IMTQLI. See F280 for the description of this special class of matrices. For such matrices, IMTQLI should be preceded by FIGI to provide a suitable symmetric matrix for IMTQLI.
3. DISCUSSION OF METHOD AND ALGORITHM.
The eigenvalues are determined by the implicit QL method. The essence of this method is a process whereby a sequence of symmetric tridiagonal matrices, unitari!y similar to the original symmetric tridiagonal matrix, is formed which converges to a diagonal matrix. The rate of convergence of this sequence is improved by implicitly shifting the origin at each iteration. Before each iteration, the symmetric tridiagona! matrix is checked for a possible splitting into submatrices. If a splitting occurs, only the uppermost submatrix participates in the next iteration. The eigenvalues are ordered in ascending order as they are found.
The origin shift at each iteration is the eigenvalue of the current uppermost 2x2 principal minor closer to the first diagonal element of this minor. Whenever the uppermost ixl principal submatrix finally splits from the rest of the matrix, its element is taken to be an eigenvalue of the original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of order i. The tolerances in the splitting tests are proportional to the relative machine precision.
This subroutine is a translation of the Algol procedure IMTQLI written and discussed in detail by Martin and Wilkinson (I) and modified by Dubrulle (2).
4. REFERENCES.
i) Martin, R.S. and Wilkinson, J.H., The Implicit QL Algorithm, Num. Math. 12,377-383 (1968).
2) Dubrulle, A.~ A Short Note on the Implicit QL Algorithm, Num~ Math. 15,450 (1970). (Combined With (I) in Handbook for Automatic Computation, volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution II/4, 241-248, Springer-Verlag, 1971.)
380
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 non-symmetric tridiagonal matrices.
B. Accuracy.
The subroutine IMTQLI is numerically stable (1,2); that is, the computed eigenvalues are close to those of the original matrix. In addition, they are the exact eigenvalues of a matrix close to the original real symmetric tridiagonal matrix.
381
7. 1-187
C
C C C C
SUBROUTINE IMTQLI(N,D,E,IERR)
INTEGER I,J,L,M,N,!!,MML,IERR REAL D(N),E(N)
REAL B,C,F,G,P,R,S,MACHEP
REAL SQRT,ABS,SIGN
********** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING
THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.
**********
MACHEP = ?
IERR = 0
IF (N .EQ. i) GO TO I001
DO i00 i = 2, N
100 E(I-I) = E(I)
E(N) -- 0.0
DO 290 L = i, N
J = 0 ********** LOOK FOR SMALL SUB-DIAGONAL ELEMENT **********
105 DO Ii0 M = L, N IF (M .EQ. N) GO TO 120 IF (ABS(E(M)) .LE. MACHEP * (ABS(D(M)) + ABS(D(M+I))))
X GO TO 120
i i0 CONTINUE
120 P = D ( L )
IF (M .EQ. L) ~O TO 215 IF (J .EQ. 30) GO TO i000
J = J + i ********** FORM SHIFT **********
G = (D(L+I) - P) / (2.0 * E(L))
R = SQRT(G*G+I.O) G = D(M) - P + E(L) / (G + SIGN(R,G))
S = 1.0
C = 1.0 P = 0.0
MML = M - L ********** FOR I=M-I STEP -I UNTIL L DO -- **********
DO 200 II = I, MML I = M - !I F = s * E ( I )
B = C * E ( I ) IF (ABS(F) .LT. ABS(G)) GO TO 150
C = G / F R = SQRT(C*C+I.O) E(I+I) = F * R s= i.o /R C = C * S GO TO 160
382
7. 1-188
150 S = F / G
R = SQRT(S*S+I.O)
E(I+I) = G * R
c= i.o /R S = S * C
160 G = D(I+I) - e
R = (D(1) - G) * S + 2.0 * C * B
P = S * R
D(I+I) = G + P
G = C * R - B
200 CONTINUE
D(L) = D(L) - P
E(L) = G
E(M) = 0.0
GO TO 105
********** ORDER EIGENVALUES **********
215 IF (L .EQ. i) GO TO 250
********** FOR I=L STEP -i UNTIL 2 DO -- **********
DO 230 II = 2, L
I = L + 2 - II
IF (e .GE. D(I-I)) GO TO 270
D(1) = D(I-I)
230 CONTINUE
250 I = 1
270 D(I) = P
290 CONTINUE
GO TO i001
C ********** SET ERROR -- NO CONVERGENCE TO AN
C EIGENVALUE AFTER 30 ITERATIONS ********** i000 IERR = L
i001 RETURN
END
383
7.1-189
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F292 IMTQL2
A Fortran IV Subroutine to Determine the Eigenvalues and Eigenvectors of a Symmetric Tridiagonal Matrix.
May, 1972
I. PURPOSE.
The Fortran IV subroutine IMTQL2 determines the eigenvalues and eigenvectors of a symmetric tridiagonal matrix. IMTQL2 uses the implicit QL method to compute the eigenvalues and accumulates the QL transformations to compute the eigenvectors. The eigenvectors of a full symmetric matrix can also be computed directly by IMTQL2, if TRED2 (F278) has been used to reduce this matrix to tridiagonal form.
2. USAGE.
A. Calling Sequence°
The SUBROUTINE statement is
SUBROUTINE IMTQL2(NM,N,D,E,Z,IERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional array Z as specified in the DIMENSION statement for Z in the calling program.
N is an integer input variable set equal to the order of the matrix. N must be not greater than NM.
is a working precision real one-dimensional variable of dimension at least N. On input, it contains the diagonal elements of the symmetric tridiagonal matrix. On output, it contains the eigenvalues of this matrix in ascending order.
384
7.1-190
IERR
is a working precision real one-dimensional variable of dimension at least N. On input, the last N-I positions in this array contain the subdiagonal elements of the symmetric tridiagonal matrix. E(1) is arbitrary. Note that IMTQL2 destroys E.
is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. If the eigenvectors of the symmetric tridiagonal matrix are desired, then on input, Z contains the identity matrix of order N, and on output, contains the orthonormal eigenvectors of this tridiagonal matrix. If the eigenvectors of a full symmetric matrix are desired, then on input, Z contains the transformation matrix produced in TRED2 which reduced the full matrix to tridiagonal form, and on output, contains the orthonormal eigenvectors of this full symmetric matrix.
is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
B. Error Conditions and Returns.
If more than 30 iterations are required to determine an eigenvalue, IMTQL2 terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues and eigenvectors in the D and Z arrays should be correct for indices 1,2,...,IERR-I, but the eigenvalues are unordered.
If all the eigenvalues are determined within 30 iterations, IERR is set to zero.
C. Applicability and Restrictions.
The subroutine TQL2 (F290) can also be used to compute the eigenvalues and eigenvectors of a symmetric tridiagonal matrix. Note, however, that TQL2 does not perform well on matrices whose successive row sums vary widely in magnitude and are not strictly increasing from the first to the last row. IMTQL2 is not sensitive to such row sums and is therefore especially recommended for symmetric tridiagonal matrices whose structure is not known.
385
7.1-191
To determine the eigenvalues and eigenvectors of a full symmetric matrix, IMTQL2 should be preceded by TRED2 (F278) to provide a suitable symmetric tridiagonal matrix for IMTQL2.
To determine the eigenvalues and eigenvectors of a complex Hermitian matrix, IMTQL2 should be preceded by HTR!DI (F284) to provide a suitable real symmetric tridiagonal matrix for IMTQL2, and the input array Z to IMTQL2 should be initialized to the identity matrix. IMTQL2 should then be followed by HTRIBK (F285) to back transform the eigenvectors from IMTQL2 into those of the original matrix.
Note~ however, that although !MTQL2 may perform better on symmetric tridiagonal matrices poorly structured in the above sense, TRED2 and HTRIDI may also perform poorly on such full symmetric and complex Hermitian matrices. Hence, any advantage in using IMTQL2 over TQL2 may be overshadowed by a poor performance in TRED2 or HTRIDI.
The eigenvalues and eigenvectors of certain non- symmetric tridiagonal matrices can be computed using the combination of FIGI2 (F222) and IMTQL2. See F222 for the description of this special class of matrices. For such matrices, IMTQL2 should be preceded by FIGI2 to provide a suitable symmetric matrix for IMTQL2.
3. DISCUSSION OF METHOD AND ALGORITHM.
The eigenva!ues are determined by the implicit QL method. The essence of this method is a process whereby a sequence of symmetric tridiagonal matrices, unitarily similar to the original symmetric tridiagonal matrix, is formed which converges to a diagonal matrix. The rate of convergence of this sequence is improved by implicitly shifting the origin at each iteration~ Before each iteration, the symmetric tridiagonal matrix is checked for a possible splitting into submatrices. If a splitting occurs, only the uppermost submatrix participates in the next iteration. The similarity transformations used in each iteration are accumulated in the Z array, producing the orthonormal eigenvectors for the original matrix. Finally, the eigenvalues are ordered in ascending order and the eigenveetors are ordered consistently.
The origin shift at each iteration is the eigenvalue of the current uppermost 2x2 principal minor closer to the first diagonal element of this minor. Whenever the uppermost ixl principal submatrix finally splits from the rest of the matrix, its element is taken to be an eigenvalue of the
386
7.1-192
original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of order i. The tolerances in the splitting tests are proportional to the relative machine precision.
This subroutine is a translation of the Algol procedure IMTQL2 written and discussed in detail by Martin and Wilkinson (i) and modified by Dubrulle (2).
4. REFERENCES.
i) Martin, R.S. and Wilkinson, J.H., The Implicit QL Algorithm, Num. Math. 12,377-383 (1968).
2) Dubrulle, A., A Short Note on the Implicit QL Algorithm, Num. Math. 15,450 (1970). (Combined With (i) in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/4, 241-248, Springer-Verlag, 1971.)
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for complex Hermitian, real symmetric, real symmetric tridiagonal, and certain real non-symmetric tridiagonal matrices.
B. Accuracy.
The subroutine IMTQL2 is numerically stable (1,2); that is, the computed eigenvalues are close to those of the original matrix. In addition, they are the exact eigenvalues of a matrix close to the original real symmetric tridiagonal matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.
387
7.1-193
C C
C C
C
SUBROUTINE IMTQL2(NM,N,D,E,Z,IERR)
INTEGER I,J,K,L,M,N, II,NM,MML,IERR
REAL D (N) ,E(N), Z (NM,N) REAL B,C,F,G,P,R,S,MACHEP
REAL SQRT,ABS,SiGN
********** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.
MACHEP = ?
IERR = 0
IF (N .EQ. i) GO TO I001
DO i00 I = 2, N i00 E(I-I) = E(1)
E(N) = 0.0
DO 240 L = I, N
J = 0 ********** LOOK FOR SMALL SUB-DIAGONAL ELEMENT **********
105 DO ii0 M = L, N IF (M .EQ. N) GO TO 120 IF (ABS(E(M)) oLE. MACHEP * (ABS(D(M)) + ABS(D(M+I))))
X GO TO 120
Ii0 CONTINUE
120 P = D (L) IF (M .EQ. L) GO TO 240 IF (J .EQ. 30) GO TO I000
J = J + 1 ********** FORM SHIFT **********
G = (D(L+I) - P) / (2.0 * E(L))
R = SQRT (G*G+I. 0) G = D(M) - P + E(L) / (G + SIGN(R,G))
S = 1.0 C = 1.0
P = 0.0 MML = M - L
********** FOR I=M-I STEP -I UNTIL L DO -- **********
DO 200 II = I, MML
I = M - I! F = S * E(1) B = C * E(1) IF (ABS(F) .LT. ABS(G)) GO TO 150
C = G / F R = SQRT(C*C+I.O) E(I+I) = F * R S = 1.0 / R C = C * S GO TO 160
388
7.1-194
150 S = F / G
R = SQRT(S*S+I.0)
E(I+I) = G * R
C= 1.0 /R
S = S * C
160 G = D(I+I) - P
R = (D(1) - G) * S + 2.0 * C * B
P = S * R
D(I+I) = G + P
G = C * R - B
• ********* FORM VECTOR **********
DO 180 K = I, N
F = Z(K,I+I)
Z(K,I+I) = S * Z(K,I) + C * F
Z(K,I) = C * Z(K,I) - S * F
180 CONTINUE
200 CONTINUE
D(L) = D(L) - P
E(L) = G
E(M) = 0.0
GO TO 105
240 CONTINUE
********** ORDER EIGENVALUES AND EIGENVECTORS **********
DO 300 II = 2, N
I = II - i
K = I
e = D(1)
260
DO 260 J = II, N
IF (D(J) .GE. P) GO TO 260
K = J
P = D(J)
CONTINUE
IF (K .EQ. I) GO TO 300
D(K) = D(1)
D(1) = P
280
DO 280 J = I, N
P = Z(J,l)
Z(J,I) = Z(J,K)
Z(J,K) = P
CONTINUE
300 CONTINUE
GO TO i001
C ********** SET ERROR -- NO CONVERGENCE TO AN
C EIGENVALUE AFTER 30 ITERATIONS **********
i000 IERR = L
i001 RETURN
END
389
7.1-195
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F288-2 iNVIT
A Fortran IV Subroutine to Determine Those Eigenvectors of a Real Upper Hessenberg Matrix Corresponding to Specified Eigenvalues.
May, 1972 July, 1975
1. PURPOSE.
The Fortran IV subroutine INVIT computes the eigenvectors of a real upper Hessenberg matrix corresponding to specified eigenvalues using inverse iteration.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE INVlT(NM,NgA,WR,WI,SELECT,MM,M,Z~ IERR,RMI,RVI,RV2)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays A and Z as specified in the DIMENSION statements for A and Z in the calling program.
is an integer input variable set equal to the order of the matrix A. N must be not greater than NM.
is a working precision real input two- dimensional variable with row dimension NM and column dimension at least N containing the upper Hessenberg matrix.
390
7.1-196
WR,WI
SELECT
MM
are working precision real one-dimensional variables of dimension at least N. On input, they contain the real and imaginary parts, respectively, of the eigenvalues of the Hessenberg matrix. The eigenvalues need not be ordered, except that complex conjugate eigenvalues must appear consecutively and eigenvalues of any submatrix of the input Hessenberg matrix must have indices in WR,WI which lie between the boundary indices for that submatrix. These ordering constraints are satisfied by the output eigenvalues from HQR (F286). On output, the eigenvalues are unaltered, except that the real parts of close eigenvalues may be perturbed slightly in an attempt to obtain independent eigenvectors.
is a logical one-dimensional variable of dimension at least N. On input, the true elements flag those eigenvalues whose eigenvectors are desired. If both of a pair of complex conjugate eigenvalues are flagged, the second flag is set false and only the eigenvector corresponding to the first of these is computed.
is an integer input variable set equal to an upper bound for the number of columns required to store the real and imaginary parts of the requested eigenvectors. The eigenvector corresponding to a real (complex) eigenvalue requires one (two) column(s).
is an integer output variable set equal to the number of columns actually used to store the eigenvectors.
is a working precision real output two- dimensional variable with row dimension NM and column dimension at least MM containing the eigenvectors corresponding to the flagged eigenvalues. The real and imaginary parts of complex eigenvectors are stored in consecutive columns with the real part first. The eigenvectors are packed into the columns of Z starting at the first column.
391
7.1-197
IERR is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
RM 1 is a working precision real temporary array variable of dimension at least N*N. This array holds the triangularized form of the upper Hessenberg matrix used in the inverse iteration process.
RVI,RV2 are working precision real temporary one- dimensional variables of dimension at least N. They hold the approximate eigenvectors during the inverse iteration process.
B. Error Conditions and Returns.
If more than MM columns of Z are necessary to store the eigenvectors corresponding to the flagged eigenvalues, INVIT terminates with IERR set to -(2*N+I). In this case, M is either MM or MM-I and is the number of columns of Z containing eigenvectors already computed.
If none of the initial vectors for the inverse iteration process produces an acceptable approximation to an eigenvector, INVIT terminates the computation for that eigenvector and sets IERR to -K where K is the index of the associated eigenvalue. If this failure occurs for more than one eigenvalue, the last occurrence is recorded in IERR. The columns of Z corresponding to failures of the above sort are set to zero vectors.
If both of the above error conditions occur, INVIT terminates with IERR set to -(N+K) where K is the index of the last eigenvalue whose inverse iteration process failed. The columns of Z corresponding to failures in the inverse iteration process are set to zero vectors, and in this case, M is the number of columns of Z containing eigenvectors already computed.
If neither of the above error conditions occurs, INVIT sets IERR to zero.
392
7.1-198
C. Applicability and Restrictions.
To determine eigenvectors corresponding to some of the eigenvalues of a real general matrix, INVIT should be preceded by ELMHES (F273) or ORTHES (F275) and HQR (F286). ELMHES or ORTHES provides a suitable upper Hessenberg matrix for INVIT and HQR determines the eigenvalues of this Hessenberg matrix. INVIT should then be followed by ELMBAK (F274) or ORTBAK (F276) to back transform the eigenvectors from INVIT into those of the original matrix. Note: the upper Hessenberg matrix and the two adjacent subdiagonals must be saved before HQR, since HQR destroys this part of A.
It is recommended in general that BALANC (F269) be used before ELMHES or ORTHES in which case BALBAK (F270) must be used after ELMBAK or ORTBAK.
In this implementation, the arithmetic is real throughout except for complex division and complex absolute value.
3. DISCUSSION OF METHOD AND ALGORITHM.
The eigenvectors are determined by inverse iteration. In INVIT, this is a process whereby a vector X1 satisfying the matrix linear equation U'X1 = X0 is computed, where X0 is an initial vector and U is the upper triangular factor in the LU decomposition of the matrix B-W*I with partial pivoting. W is an approximate eigenvalue of a leading submatrix B of the Hessenberg matrix in A. The vector X1 is accepted as an eigenvector of B if the norm of X1 is sufficiently larger than the norm of X0. This eigenvector of B is transformed to an eigenvector of A by simply appending zero components to it.
The computations for the real and complex eigenvectors are separate. In the real case, the factor U in the LU decomposition is stored in the full lower triangle of the array RMI, and in the complex case, the real part of U is stored in the full lower triangle of RMI and the imaginary part of U is stored in the upper triangle of RMI above the superdiagonal augmented by the two columns of Z that will later store the complex eigenvector. (Internally, RMI is treated as a two-dimensional NxN array.)
The acceptance criterion for X1 is a growth test of its norm. If MACHEP denotes the relative machine precision, then currently, X1 is rejected as an eigenveetor if
SQRT(UK)*!!B!!*MACHEP*!!XI!! .LT. !!X0!!/10.0
393
7.1-199
where UK is the order of the submatrix B whose eigenvector is being computed and the norm !! !! is the infinity norm. At most UK orthogonal initial vectors X0 are tried to obtain the required growth. If no vector is accepted, the parameter !ERR is set to indicate this failure and !NVIT proceeds to compute the next eigenvector.
The real parts of close or identical eigenvalues whose eigenvectors are desired may be perturbed slightly in an attempt to obtain independent eigenvectors (if they exist). If required, such perturbations are positive and small multiples of MACHEP*Z!B!!.
This subroutine is a translation of the Algol procedure INVIT written and discussed in detail by Peters and Wilkinson (i)°
4o REFERENCES.
i) Peters, G. and Wilkinson, J.H., The Calculation of Specified Eigenvectors by Inverse Iteration, Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C, Reinsch, Contribution II/18, 418-439, Springer-Verlag, 1971.
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for real general matrices.
B° Accuracy.
The accuracy of INVIT can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real upper Hessenberg matrices. In these paths, this subroutine is numerically stable (i)o This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original upper Hessenberg matrix.
394
7.1-200
C C C
SUBROUTINE INVlT(NM,N,A,WR,WI,SELECT,MM,M,Z,IERR,RMI,RVI,RV2)
INTEGER I,J,K,L,M,N,S,II,IP,MM,MP,NM,NS,NI,UK, IPI,ITS,KMI,IERR REAL A(NM,N),WR(N),WI(N),Z(NM,MM),RMI(N,N),RVI(N),RV2(N) REAL T,W,X,Y,EPS3,NORM,NORMV,GROWTO,ILAMBD,MACHEP,RLAMBD,UKROOT REAL SQRT,CABS~ABS,FLOAT INTEGER lABS LOGICAL SELECT(N) COMPLEX Z3 COMPLEX CMPLX REAL REAL,AIMAG
********** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.
MACHEP = ?
IERR = 0 UK = 0 S = i
********** IP = 0, REAL EIGENVALUE
i, FIRST OF CONJUGATE COMPLEX PAIR -i, SECOND OF CONJUGATE COMPLEX PAIR **********
IP = 0 N1 = N - 1
DO 980 K : i, N
IF (WI(K) .EQ. 0.0 .OR. IP .LT. 0) GO TO i00 IP = i
IF (SELECT(K) .AND. SELECT(K+I)) SELECT(K+1) = .FALSE. i00 IF (.NOT. SELECT(K)) GO TO 960
IF (WI(K) .RE. 0.0) S = S + I IF (S .GT. MM) GO TO i000 IF (UK .GE. K) GO TO 200
********** CHECK FOR POSSIBLE SPLITTING ********** DO 120 UK = K, N
IF (UK .EQ. N) GO TO 140 IF (A(UK+I,UK) .EQ. 0.0) GO TO 140
120 CONTINUE
********** COMPUTE INFINITY NORM OF LEADING UK BY UK [HESSENBERG) MATRIX **********
140 NORM = 0.0 MP = 1
160
180
DO 180 1 = i, UK X=0.0
DO 160 J = MP, UK X = X + ABS(A(I,J))
IF (X .GT. NORM) NORM = X MP = I
CONTINUE
395
7.1-201
C C
C
C
C
C
C
C
200
220
240
X 260
280
300
320
********** EPS3 REPLACES ZERO PIVOT IN DECOMPOSITION
AND CLOSE ROOTS ARE MODIFIED BY EPS3 ********** IF (NORM .EQ. 0.0) NORM = i°0
EPS3 = MACHEP * NORM ********** GROWTO IS THE CRITERION FOR THE GROWTH **********
UKROOT = SQRT(FLOAT(UK))
GROWTO = 1.0E-I / UKROOT
RLAMBD = WR(K)
ILAMBD = WI(K) IF (K .EQ. i) GO TO 280 KMI = K - I
GO TO 240 ********** PERTURB EIGENVALUE IF IT IS CLOSE
TO ANY PREVIOUS EIGENVALUE ********** RLAMBD = RLAMBD + EPS3
********** FOR I=K-I STEP -i UNTIL 1 DO -- **********
DO 260 II = i, KMI I = K - II IF (SELECT(l) .AND. ABS(WR(1)-RLAMBD) .LT. EPS3 .AND.
ABS(WI(1)-ILAMBD) .LT. EPS3) GO TO 220
CONTINUE
WR(K) = RLAMBD ********** PERTURB CONJUGATE EIGENVALUE TO MATCH **********
IPI = K + IP
WR(IPI) = RLAMBD ********** FORM UPPER HESSENBERG A-RLAMBD*I (TRANSPOSED)
AND INITIAL REAL VECTOR ********** MP = !
DO 320 I = I, UK
DO 300 J = MP, UK RMI(J,I) = A(I,J)
RMI(I,I) = RMI(I,I) - RLAMBD
MP = I RVI(1) = EPS3
CONTINUE
ITS = 0 IF (ILAMBD .NE. 0.0) GO TO 520
********** REAL EIGENVALUE. TRIANGULAR DECOMPOSITION WITH INTERCHANGES, REPLACING ZERO PIVOTS BY EPS3 **********
IF (UK ~EQ. i) GO TO 420
DO 400 I = 2, UK MP = I m 1 IF (ABS(RMI(MP, I)) .LE. ABS(RMI(MP,MP))) GO TO 360
396
7.1-202
340
360
380
400
420
440
460
480 500
520
540
550
DO 340 J = MP, UK
Y = RMI(J,I) RMI(J,I) = RMI(J,MP) RMI(J,MP) = Y
CONTINUE
IF (RMI(MP,MP) .EQ. 0.0) RMI(MP,MP) = EPS3 X = RMI(MP,I) / RMI(MP,MP) IF (X .EQ. 0.0) GO TO 400
DO 380 J = I, UK
RMI(J,I) = RMI(J,I) - X * RMI(J,MP)
CONTINUE
IF (RMI(UK,UK) .EQ. 0.0) RMI(UK,UK) = EPS3
********** BACK SUBSTITUTION FOR REAL VECTOR FOR I=UK STEP -i UNTIL 1 DO -- **********
DO 500 II = i, UK I = UK + 1 - II Y = RVI (I)
IF (I .EQ. UK) GO TO 480 IPI = I + 1
DO 460 J = IPI, UK Y = Y - RMI(J,I) * RVI(J)
RVI(1) = Y / RMI(I,I) CONTINUE
GO TO 740
********** COMPLEX EIGENVALUE.
TRIANGULAR DECOMPOSITION WITH INTERCHANGES, REPLACING ZERO PIVOTS BY EPS3. STORE IMAGINARY PARTS IN UPPER TRIANGLE STARTING AT (1,3) **********
NS = N - S Z(I,S-I) = -ILAMBD Z(I,S) = 0.0
IF (N .EQ. 2) GO TO 550 RMI(I,3) = -ILAMBD Z(I,S-I) = 0.0
IF (N .EQ. 3) GO TO 550
DO 540 I = 4, N RMI(I,I) = 0.0
DO 640 I = 2, UK MP = I - I W = RMI(MP,I) IF (I .LT. N) T = RMI(MP, I+I) IF (I .EQ. N) T = E(MP,S-I) X = RMI(MP,MP) * RMI(MP,MP) + T * T IF (W * W .LE. X) GO TO 580
397
7. 1-203
555
560
570
580
600
610
615 620
X = RMI(MP,MP) / W Y = T / W RMI(MP,MP) = W
IF (I .LT. N) RMI(MP,I+I) = 0.0 IF (I .EQ. N) Z(MP,S-I) = 0.0
DO 560 J = !, UK W = RMI(J,I)
RMI(J,I) = RMI(J,MP) - X * W
RMI(J,MP) = W IF (J .LT. NI) GO TO 555
L = J - NS Z(!,L) = Z(MP,L) - Y * W
Z(MP,L) = 0.0
GO TO 560 RMI(I,J+2) = RMI(MP,J+2) - Y * W
RMI(MP,J+2) = 0.0
CONTINUE
RMI(I,!) = RMI(I,I) - Y * ILAMBD
IF (I oLT. NI) GO TO 570
L = I - NS
Z(MP,L) = -ILAMBD Z(I,L) = Z(I,L) + X * ILAMBD
GO TO 640 RMI(MP,I+2) = -ILAMBD RMI(I,I+2) = RMI(I,I+2) + X * ILAMBD
GO TO 640 IF (X .NE. 0.0) GO TO 600
RMI(MP,MP) = EPS3 IF (I .LT. N) RMI(MP,I+I) = 0.0
IF (I .EQ. N) Z(MP,S-I) = 0.0
T = 0.0 X = EPS3 * EPS3
w = w / x X = RMI(MP,MP) * W
Y = -T * W
DO 620 J = I, UK IF (J .LT. NI) GO TO 610
L = J - NS T = Z(MP,L) Z(I,L) = -X * T - Y * RMI(J,MP)
GO TO 615 T = RMI(MP,J+2) RMI(I,J+2) = -X * T - Y * RMI(J,MP) RMI(J,I) = RMI(J,I) - X * RMI(J,MP) + Y * T
CONTINUE
398
7.1-204
C
C
630 640
650
655
660
670
675
680
700
IF (I .LT. NI) GO TO 630
L = I - NS
Z(I,L) = Z(I,L) - ILAMBD GO TO 640 RMI(I,I+2) = RMI(I,I+2) - ILAMBD
CONTINUE
IF (UK .LT. NI) GO TO 650 L = UK - NS T = Z (UK, L) GO TO 655
T = RMI(UK,UK+2)
IF (RMI(UK,UK) .EQ. 0.0 .AND. T .EQ. 0.0) RMI(UK,UK) = EPS3
********** BACK SUBSTITUTION FOR COMPLEX VECTOR FOR I=UK STEP -I UNTIL 1 DO -- **********
DO 720 II = i, UK
I = UK + i - II
X = RVI (I) Y = 0.0
IF (I .EQ. UK) GO TO 700 IPI = I + i
DO 680 J = IPI, UK
IF (J .LT. NI) GO TO 670 L = J - NS T = Z(I,L)
GO TO 675
T = RMI(I,J+2)
X = X - RMI(J,I) * RVI(J) + T * RV2(J)
Y = Y - RMI(J,I) * RV2(J) - T * RVI(J) CONTINUE
IF (I .LT. Nt) GO TO 710 L = I - NS T = Z(I,L) GO TO 715
710 T = RMI(I,I+2)
715 z3 = CMPLX(X,Y) / CMPLX(RMI(I,I),T) RVI(I) = REAL(Z3)
RV2(I) = AIMAG(Z3) 720 CONTINUE
********** ACCEPTANCE TEST FOR REAL OR COMPLEX EIGENVECTOR AND NORMALIZATION **********
740 ITS = ITS + 1
NORM = 0.0
NORMV = 0.0
DO 78O I = i, UK
IF (ILAMBD .EQo 0.0)X = ABS(RVI(I))
IF (ILAMBD .NE. 0.0) X = CABS(CMPLX(RVI(I),RV2(I))) IF (NORMV .GE. X) GO TO 760 NORMV -- X J = I
399
7.1-205
C
C
760
780 NORM = NORM + X
CONTINUE
IF (NORM ,LT. GROWTO) GO TO 840
********** ACCEPT VECTOR ********** X = RVI(J) IF (ILAMBD .EQ. 0.0) X = 1.0 / X IF (ILAMBD .NE. 0.0) Y = RV2(J)
800
820
DO 820 ! = I~ UK
IF (ILAMBD .NE. 0.0) GO TO 800 z(i,s) = RVI(I) * X
GO TO 820 Z3 = CMPLX(RVI(1),RV2(1)) / CMPLX(X,Y)
Z(I,S-I) = REAL(Z3) Z(I,S) = AIMAG(Z3)
CONTINUE
840
IF (UK .EQ° N) GO TO 940 J = UK + I
GO TO 900 ********** IN-LINE PROCEDURE FOR CHOOSING
A NEW STARTING VECTOR ********** IF (ITS .GE. UK) GO TO 880
X = UKROOT Y = EPS3 1 (X + 1.0)
RVI(1) = EPS3
DO 860 1 = 2, UK
860 RVI(1) = Y
J = UK - ITS + i RVI(J) = RVI(J) - EPS3 * X IF (!LAMBD .EQ. 0.0) GO TO 440
GO TO 660 • ********* SET ERROR -- UNACCEPTED EIGENVECTOR **********
880 J = ! IERR = -K
• ********* SET REMAINING VECTOR COMPONENTS TO ZERO **********
900 DO 920 1 = J, N z(i,s) = o.o IF (!LAMBD .NE. 0.0) Z(I,S-I) = 0.0
920 CONTINUE
940 S = S + 1 960 IF (ie .EQ. (-i)) Ie = 0
IF (IP ,EQ. i) IP = -i
980 CONTINUE
GO TO i001
400
7.1-206
C ********** SET ERROR -- UNDERESTIMATE OF EIGENVECTOR
C SPACE REQUIRED **********
i000 IF (IERR .NE. 0) IERR = IERR - N
IF (IERR .EQ. 0) IERR = -(2 * N + i)
i001M = S - 1 - IABS(IP)
RETURN
END
401
7.1-207
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F276-2 ORTBAK
A Fortran IV Subroutine to Back Transform the Eigenvectors of that Upper Hessenberg Matrix Determined by ORTHES.
May, 1972 July, 1975
I. PURPOSE°
The Fortran IV subroutine ORTBAK forms the eigenvectors of a real general matrix from the eigenvectors of that upper Hessenberg matrix determined by ORTHES (F275).
2. USAGE.
A. Calling Sequence°
The SUBROUTINE statement is
SUBROUTINE ORTBAK(NM, LOW, IGN,A,ORT,M,Z)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays A and Z as specified in the DIMENSION statements for A and Z in the calling program.
LOW,IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F269 for the details. If the matrix is not balanced, set LOW to 1 and IGH to the order of the matrix.
A is a working precision real input two- dimensional variable with row dimension NM and column dimension at least IGH. The strict lower triangle of A contains some information about the orthogona!
402
7.1-208
ORT
M
transformations used in the reduction to the Hessenberg form. The remaining upper part of the matrix is arbitrary. See section 3 of F275 for the details.
is a working precision real one-dimensional variable of dimension at least IGH. On input, ORT contains further information about the orthogonal transformations used in the reduction by ORTHES. See section 3 of F275 for the details. ORT is used for temporary storage within ORTBAK and is not restored.
is an integer input variable set equal to the number of columns of Z to be back transformed.
is a working precision real two-dimensional variable with row dimension NM and column dimension at least M. On input, the first M columns of Z contain the real and imaginary parts of the eigenvectors to be back transformed. On output, these M columns of Z contain the real and imaginary parts of the transformed eigenvectors.
B. Error Conditions and Returns.
None.
C. Applicability and Restrictions.
This subroutine should be used in conjunction with the subroutine ORTHES (F275).
The real and imaginary parts of an eigenvector need not be stored in consecutive columns of Z.
3. DISCUSSION OF METHOD AND ALGORITHM.
Suppose that the matrix upper Hessenberg form F transformation
C (say) has been reduced to the stored in A by the similarity
F = Q CQ
403
7.1-209
where Q is a product of the orthogonal matrices encoded in ORT and in a lower triangle of A under F. Then, given an array Z of column vectors, ORTBAK computes the matrix product QZ. If the real and imaginary parts of the eigenvectors of F are columns of the array Z, then ORTBAK forms the eigenvectors of C in their place.
This subroutine is a translation of the Algol procedure ORTBAK written and discussed in detail by Martin and Wilkinson (I).
4. REFERENCES°
i) Martin, R.S. and Wilkinson, J.H., Similarity Reduction of a General Matrix to Hessenberg Form, Num. Math. 12,349-368 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/13, 339-358, Springer-Verlag, 1971.)
5. CHECKOUT.
Ao Test Cases.
See the section discussing testing of the codes for real general matrices.
Bo Accuracy~
The accuracy of ORTBAK can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real general matrices. In these paths, this subroutine is numerically stable (I). This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original matrix.
404
7. 1-210
SUBROUTINE ORTBAK(NM,LOW, IGH,A, ORT,M,Z)
INTEGER I,J,M,LA,MM,MP,NM,IGH,KPI,LOW,MPI
REAL A(NM,IGH),ORT(IGH),Z(NM,M) REAL G
IF (M .EQ. 0) GO TO 200 LA = IGH - 1 KPI = LOW + 1
IF (LA .LT. KPI) GO TO 200
********** FOR MP=IGH-I STEP -I UNTIL LOW+I DO -- ********** DO 140 MM = KPI, LA
MP = LOW + IGH - MM IF (A(MP,MP-I) .EQ. 0.0) GO TO 140 MPI = MP + 1
i00 DO i00 1 = MPI, IGH ORT(1) = A(I,MP-I)
DO 130 J = i , M
G=O.0
i i 0 DO ii0 1 = MP, IGH G = G + ORT(1) * Z(I,J)
• ********* DIVISOR BELOW IS NEGATIVE OF H FORMED IN ORTHES. DOUBLE DIVISION AVOIDS POSSIBLE UNDERFLOW **********
G = (G / ORT(MP)) / A(MP,MP-I)
120
130
DO 120 I = MP, IGH
Z(l,J) = Z(l,J) + G * ORT(1)
CONTINUE
140 CONTINUE
200 RETURN END
405
7.1-2!1
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F275 ORTHES
A Fortran IV Subroutine to Reduce a Real General Matrix to Upper Hessenberg Form Using Orthogonal Transformations.
May, 1972
!. PURPOSE.
The Fortran IV subroutine ORTHES reduces a real general matrix to upper Hessenberg form using orthogonal similarity transformations. This reduced form is used by other subroutines to find the eigenvalues and/or eigenvectors of the original matrix. See section 2C for the specific routines,
2. USAGE.
A, Calling Sequence,
The SUBROUTINE statement is
SUBROUTINE ORTHES(NM,N,LOW, IGH,A,ORT)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional array A as specified in the DIMENSION statement for A in the calling program.
N is an integer input variable set equal to the order of the matrix A. N must be not greater than NM.
LOW~IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F269 for the details. If the matrix is not balanced, set LOW to 1 and !GH to N.
406
7.1-212
A
0RT
is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. On input, A contains the matrix of order N to be reduced to Hessenberg form. On output, A contains the upper Hessenberg matrix as well as some information about the orthogonal transformations used in the reduction. See section 3 for the details.
is a working precision real output one- dimensional variable of dimension at least IGH containing the remaining information about the orthogonal transformations. See section 3 for the details. Only components LOW+I through IGH are actually used by ORTHES.
B. Error Conditions and Returns.
None.
C. Applicability and Restrictions.
If all the eigenvalues of the original matrix are desired, this subroutine should be followed by HQR (F286).
If all the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by ORTRAN (F221) and HQR2 (F287).
If some of the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by HQR (F286), INVIT (F288), and ORTBAK (F276) .
The subroutine ORTHES executes slower than its counterpart ELMHES (F273), which uses elementary similarity transformations. ORTHES is, however, more accurate in some cases. It is recommended that ELMHES be used in general.
If the matrix has elements of widely varying magnitudes, the larger ones should be in the top left-hand corner.
407
7.1-213
3. DISCUSSION OF METHOD AND ALGORITHM.
Suppose that the matrix A has the form
A ( T X Y )
= (0 B Z) (0 0 R)
where T and R are upper triangular matrices, B is a square matrix situated in rows and columns LOW through IGH, and X, Y, and Z are rectangular matrices of the appropriate dimensions. Then the subroutine ORTHES performs orthogonal similarity transformations to reduce to Hessenberg form.
The Hessenberg reduction is performed in the following way. Starting with J=LOW, the elements in the J-th column below the diagonal are first scaled, to avoid possible underflow in the transformation that might result in severe departure from orthogonality. The sum of squares SIGMA of these scaled elements is next formed. Then, a vector U and a scalar
T H = U U / 2
define an operator
T p = i - u u / H
which is orthogonal and symmetric and for which the similarity transformation PAP eliminates the elements in the J-th column of A below the subdiagonal.
The non-zero components of U are the elements of the J-th column below the diagonal with the first of them augmented by the square root of SIGMA prefixed by the sign of the subdiagonal element. By saving this component in the array ORT and not overwriting the column elements eliminated in the transformation, full information on ~ is saved for later use in ORTRAN and ORTBAK.
The transformation replaces the subdiagonal element with the square root of SIGMA prefixed by sign opposite to that of the replaced element.
The above steps are repeated on further columns of the transformed A until B is reduced to Hessenberg form; that is, repeated for J = LOW+I,LOW+2,...,IGH-2.
This subroutine is a translation of the Algol procedure ORTHES written and discussed in detail by Martin and Wilkinson (i).
408
7. 1-214
4. REFERENCES.
l) Martin, R.S. and Wilkinson, J.H., Similarity Reduction of a General Matrix to Hessenberg Form, Num. Math. 12,349-368 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/13, 339-358, Springer-Verlag, 1971.)
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for real general matrices.
B. Accuracy.
The accuracy of ORTHES can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real general matrices. In these paths, this subroutine is numerically stable (I). This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix hlose to the original matrix.
409
7.1-215
C
C
90
I00
ii0
120
130
140
SUBROUTINE ORTHES(NM,N,LOW, IGH,A,ORT)
INTEGER I,J,M,N,I!,JJ,LA,MP,NM,IGH,KPI,LOW
REAL A(NM,N)~ORT(IGH)
REAL F,G,H,SCALE
REAL SQRT,ABS,SIGN
LA = !GH - I
KPI = LOW + i
IF (LA oLT. KPI) GO TO 200
DO 180 M = KPI, LA
H = 0.0
ORT(M) = 0.0
SCALE = 0.0
********** SCALE COLUMN (ALGOL TOL THEN NOT NEEDED) **********
DO 90 I = M, IGH
SCALE = SCALE + ABS(A(I,M-I))
IF (SCALE .EQ. 0.0) GO TO 180
MP = M + IGH
********** FOR I=IGH STEP -i UNTIL M DO -- **********
DO i00 II = M, IGH
! = MP - II
ORT(1) = A(I,M-I) / SCALE
H = H + ORT(1) * ORT(1)
CONTINUE
G = -SIGN(SQRT(H),ORT(M))
H = H - ORT(M) * G
ORr (M) = ORT (M) - G
• ********* FORM (I-(U*UT)/H) * A **********
DO 130 J = M, N
F = 0.0
• ********* FOR I=IGH STEP -I UNTIL M DO -- **********
DO Ii0 II = M~ IGH
I = MP - II
F = F + ORr(1) * A(I,J)
CONTINUE
F = F / H
DO 120 ! = M, IGH
A(I,J) = A(I,J) - F * ORT(1)
CONTINUE ********** FORM (I-(U*UT)/H)*A*(I-(U*UT)/H) **********
DO 160 I = I, IGH
F=0.0
********** FOR J=IGH STEP -I UNTIL M DO -- **********
DO 140 JJ = M, IGH
J = MP - JJ F = F + ORT(J) * A(I,J)
CONTINUE
410
7.1-216
F = F / H
150
DO 150 J = M, IGH
A(I,J) = A(I,J) - F * ORT(J)
160 CONTINUE
O R T ( M ) = SCALE * O R T ( M ) A(M,M-I) = SCALE * G
180 CONTINUE
200 RETURN
END
411
7.1-217
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F221-2 ORTRAN
A Fortran IV Subroutine to Accumulate the Transformations in the Reduction of a Real General Matrix by ORTHES.
May, 1972 July, 1975
I. PURPOSE.
The Fortran IV subroutine ORTRAN accumulates the orthogonal similarity transformations used in the reduction of a real general matrix to upper Hessenberg form by ORTHES (F275).
2. USAGE.
A. Calling Sequence°
The SUBROUTINE statement is
SUBROUTINE ORTRAN(NM,N,LOW, IGH,A,ORT,Z)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays A and Z as specified in the DIMENSION statements for A and Z in the calling program.
is an integer input variable set equal to the order of the matrix A. N must be not greater than NM.
LOW, IGH are integer input variables indicating the boundary indices for the balanced matrix. See section 3 of F269 for the details. If the matrix is not balanced, set LOW to 1 and IGH to N.
412
7.1-218
A
ORT
is a working precision real input two- dimensional variable with row dimension NM and column dimension at least IGH. The strict lower triangle of A contains some information about the orthogonal transformations used in the reduction to the Hessenberg form. The remaining upper part of the matrix is arbitrary. See section 3 of F275 for the details.
is a working precision real one-dimensional variable of dimension at least IGH. On input, ORT contains further information about the orthogonal transformations used in the reduction by ORTHES. See section 3 of F275 for the details. ORT is used for temporary storage within ORTRAN and is not restored.
is a working precision real output two- dimensional variable with row dimension NM and column dimension at least N. It contains the transformation matrix produced in the reduction by ORTHES to the upper Hessenberg form.
B. Error Conditions and Returns.
None.
C. Applicability and Restrictions.
If all the eigenvalues and eigenvectors of the original matrix are desired, this subroutine follows ORTHES (F275) and should be followed by HQR2 (F287). Otherwise, this subroutine will not ordinarily be used.
3. DISCUSSION OF METHOD AND ALGORITHM.
Suppose that the matrix upper Hessenberg form F transformation
C (say) has been reduced to the stored in A by the similarity
T F = Q CQ
where Q is a product of the orthogonal matrices encoded in ORT and in a lower triangle of A under F. Then, ORTRAN accumulates Q into the array Z.
413
7.1-219
This subroutine is a translation of the Algol procedure ORTRANS written and discussed in detail by Peters and Wilkinson (i).
4. REFERENCES.
l) Peters~ G. and Wilkinson, J.H., Eigenvectors of Real and Complex Matrices by LR and QR Triangularizations, Numo Math. 16,181-204 (1970). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/15, 372-395, Springer-Verlag, 1971.)
5. CHECKOUT.
A. Test Cases~
See the section discussing testing of the codes for real general matrices.
B. Accuracy.
The accuracy of ORTRAN can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real general matrices. In these paths, this subroutine is numerically stable (i). This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original matrix.
414
7 . 1 - 2 2 0
SUBROUTINE ORTRAN(NM~N,LOW,IGH,A~ORT~Z)
INTEGER I,J,N~KL,MM,MP,NM,IGH~LOW~MPI REAL A(NM,IGH),ORT(IGH),Z(NM,N) REAL G
**~******* INITIALIZE Z TO IDENTITY MATRIX ***~****** DO 80 I = i~ N
DO 60 J = i, N 60 Z(l,J) = 0.0
z(I,I) : 1.0 80 CONTINUE
KL = IGH - LOW - 1 IF (EL .LT. I) GO TO 200
***me***** FOR MP=IGH-I STEP -i UNTIL LOW+I DO -- ********** DO 140 MM = i, KL
MP = IGH - MM
IF (A(MP,MP-I) .EQ. 0.0) GO TO 140 MPI = MP + i
I00 DO i00 I = MPI, IGH ORT(1) = A(I,MP-I)
DO 130 J = MP, IGH G=0.0
ii0 DO II0 I = MP, IGH G = G + ORT(1) * Z(I,J)
• ********* DIVISOR BELOW IS NEGATIVE OF H FORMED IN ORTHES. DOUBLE DIVISION AVOIDS POSSIBLE UNDERFLOW *********~
g = (G / ORT(MP)) / A(MP,MP-I)
120 DO 120 I = MP, IGH Z(I,J) = Z(l,J) + G * ORT(1)
130 CONTINUE
140 CONTINUE
200 RETURN END
415
7. 1-221
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F298-2 RATQR
A Fortran IV Subroutine to Determine Some Extreme Eigenvaiues of a Symmetric Tridiagonal Matrix.
May, 1972 July, 1975
i. PURPOSE.
The Fortran IV subroutine RATQR determines the algebraically smallest or largest eigenvalues of a symmetric tridiagonal matrix using the rational QR method with Newton corrections.
2. USAGE.
Ao Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE RATQR(N~EPSI,D,E,E2, M,W, IND,BD,TYPE, IDEF,IERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
is an integer input variable set equal to the order of the matrix,
EPSI is a working precision real variable. On input, EPSI specifies a tolerance for the theoretical absolute error of the computed eigenva!ues. If MACHEP denotes the relative machine precision, then if the input EPSI is less than MACHEP times the magnitude of any of the computed eigenvalues, it is reset to a default value described in section 3. The theoretical absolute error in the K-th eigenvalue is usually not greater than K times the output EPSI.
416
7.1-222
E2
M
W
IND
BD
is a working precision real input one- dimensional variable of dimension at least N containing the diagonal elements of the symmetric tridiagonal matrix.
is a working precision real input one- dimensional variable of dimension at least N containing, in its last N-I positions, the subdiagonal elements of the symmetric tridiagonal matrix. E(1) is arbitrary.
is a working precision real one-dimensional variable of dimension at least N. On input, the last N-I positions in this array contain the squares of the subdiagonal elements of the symmetric tridiagonal matrix. E2(1) is arbitrary. On output, E2(1) is set to 0.0 if the smallest eigenvalues are found and to 2.0 if the largest eigenvalues are found. If any of the elements in E are regarded as negligible, the corresponding elements of E2 are set to zero, and so the matrix splits into a direct sum of submatrices.
is an integer input variable set equal to the number of extreme eigenvalues desired.
is a working precision real output one- dimensional variable of dimension at least N containing the M extreme eigenvalues of the symmetric tridiagonal matrix. If the smallest eigenvalues have been found, they are in ascending order in W. If the largest eigenvalues have been found, they are in descending order in W. W need not be distinct from D.
is an integer output one-dimensional variable of dimension at least N containing the submatrix indices associated with the corresponding M eigenvalues in W. Eigenvalues belonging to the first submatrix have index I, those belonging to the second submatrix have index 2, etc.
is a working precision real output one- dimensional variable of dimension at least N. BD(K) is a tighter bound than K*EPSI for the theoretical error of the K-th eigenvalue W(K), K = 1,2,...,M. BD need not be distinct from E2.
417
7.1-223
TYPE
IDEF
IERR
is a logical input variable set true if the smallest eigenvalues are to be found and set false if the largest eigenvalues are to be found.
is an integer input variable set to 1 if the symmetric tridiagonal matrix is known to be positive definite, set to -i if the matrix is known to be negative definite, and set to 0 otherwise.
is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
B. Error Conditions and Returns.
If IDEF is set to 1 and TYPE is set true when the input matrix is not positive definite, or if IDEF is set to -i and TYPE is set false when the matrix is not negative definite, RATQR terminates with IERR set to 6*N+I. No eigenvalues are computed. Note: this error return may also be made if M has been inadvertently specified greater than N.
If successive iterates to the K-th eigenvalue are not strictly monotone increasing, RATQR terminates the calculation for that eigenvalue with IERR set to 5*N+K. The sum of all the shifts up to this point is taken as the eigenvalue and the program proceeds to the next eigenvalue calculation. If this failure occurs for more than one eigenvalue, the last occurrence is
recorded in IERR.
If neither of the above error conditions occurs, IERR is set to zero.
C. Applicability and Restrictions.
To determine extreme eigenvalues of a full symmetric matrix, RATQR should be preceded by TREDI (F277) provide a suitable symmetric tridiagonal matrix for
RATQR.
to
To determine extreme eigenvalues of a complex Hermitian matrix, RATQR should be preceded by HTRIDI (F284) to provide a suitable real symmetric tridiagonal matrix for
RATQR.
418
7.1-224
To determine extreme eigenvalues of certain non- symmetric tridiagonal matrices, RATQR should be preceded by FIGI (F280) to provide a suitable symmetric tridiagonal matrix for RATQR. See F280 a description of this special class of matrices.
for
To determine eigenvectors associated with the computed eigenvalues, RATQR should be followed by TINVlT (F223) and the appropriate back transformation subroutine -- TRBAKI (F279) after TREDI, HTRIBK (F285) after HTRIDI, or BAKVEC (F281) after FIGI.
The subroutine TRIDIB (F237) is generally faster and more accurate than RATQR if the eigenvalues are clustered.
3. DISCUSSION OF METHOD AND ALGORITHM.
The eigenvalues are determined by the rational QR method with Newton corrections. The essence of this method is a process whereby a sequence of symmetric tridiagonal matrices, unitarily similar to the original symmetric tridiagonal matrix with shifted origin, is formed which converges to a matrix with zero diagonal elements. The origin shifts using the Newton step improve the convergence rate of the sequence.
The algorithm applies to the determination of the algebraically smallest eigenvalues. D is first copied into W and IDEF into variable JDEF. If TYPE is false, RATQR then reverses the signs of the elements of W and negates JDEF.
Next, the subdiagonal elements are tested for negligibility. If an element is considered negligible, its square is set to zero, and so the matrix splits into a direct sum of submatrices. Then if JDEF is not i or if JDEF is 1 and the Gerschgorin lower bound for the smallest eigenvalue is positive, the origin is first shifted so that the Gerschgorin lower bound for the translated matrix is zero.
Starting from the new origin, two QR decompositions are performed providing with additional calculations the Newton step by which the origin is again shifted. This process is repeated until a diagonal element of one of the intermediate matrices becomes negligible. Then the sum of the origin shifts is taken as an eigenvalue, the matrix is deflated by deleting the row and column with the negligible diagonal element (the location of this row serves to identify the submatrix to which the eigenvalue belongs), and the complete process is repeated on the deflated matrix.
419
7.1-225
If at any stage MACHEP times the absolute sum of the origin shifts exceeds EPSI, EPSI is reset to this quantity. A diagonal element is considered negligible if it is no greater than the current EPSI. At each iteration, negligible squared subdiagonal elements (earlier copied into BD) are set to zero to avoid underflows which would otherwise occur.
The algorithm assumes after the initial origin shift that the matrix is positive definite, and so can expect diagonal elements of certain intermediate matrices to be positive. If any of these are negative, then !ERR is flagged indicating that !DEF was set erroneously. Also, because the matrix is positive definite, the sum of the origin shifts must increase. If the sum does not increase, this is considered an irregular end of iteration and IERR is flagged. In this case, the current sum of the origin shifts is taken as an eigenvalue, and the matrix is deflated by deleting the row and column corresponding to the smallest diagonal element.
Finally, if TYPE is false, RATQR again reverses the signs of the elements of W.
This subroutine is a translation of the Algol procedure RATQR written and discussed in detail by Reinsch and Bauer (i).
4. REFERENCES°
i) Reinsch, C. and Bauer, F.L., Rational QR Transformation With Newton Shift for Symmetric Tridiagonal Matrices, Num. Math. 11,264-272 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/6, 257-265, Springer-Verlag, 1971.)
5. CHECKOUT.
A~ Test Cases~
See the section discussing testing of the codes for complex Hermitian, real symmetric, real symmetric tridiagonal, and certain real non-symmetric tridiagonal matrices.
420
7.1-226
B. Accuracy.
The subroutine RATQR is numerically stable when limited to the computation of a few eigenvalues that are not tightly clustered (i); that is, the computed eigenvalues are close to those of the original matrix. In addition, they are the exact eigenvalues of a matrix close to the original real symmetric tridiagonal matrix.
421
7.1-227
SUBROUTINE RATQR(N,EPSI,D,E,E2,M,W, IND,BD,TYPE,IDEF,IERR)
INTEGER I,J,K,M,N,II,JJ,KI,!DEF,IERR,JDEF REAL D (N), E (N), E2 (N), W(N), BD (N) REAL F,P,Q,R,S,EP,QP,ERR,TOT,EPSI,DELTA,MACHEP REAL ABS,AM!NI INTEGER IND(N) LOGICAL TYPE
********** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.
MACHEP = ?
IERR = 0
JDEF = IDEF ********** COPY D ARRAY INTO W ********** DO 20 I = I, N
2O W(I) = D(I)
IF (TYPE) GO TO 40 J = ! GO TO 400
40 ERR = 0.0 s = o.o
********** LOOK FOR SMALL SUB-DIAGONAL ENTRIES AND DEFINE INITIAL SHIFT FROM LOWER GERSCHGORIN BOUND. COPY E2 ARRAY INTO BD **********
TOT = W(1) Q = 0.0 J = 0
DO i00 1 = I, N
P = Q IF (I .EQ. i) GO TO 60 IF (P °gr. MACHEP * (ABS(D(1)) + ABS(D(I-I)))) GO TO 80
60 E2(1) = 0.0 80 BD(1) = E2(1)
• ********* COUNT ALSO IF ELEMENT OF E2 HAS UNDERFLOWED **********
IF (E2(1) .EQ. 0.0) J = J + I lED(l) = J Q= 0,0 IF (I .RE. N) Q = ABS(E(I+I)) TOT = AMINI (W(1)-P-Q,TOT)
I00 CONTINUE
IF (JDEF .EQ° I .AND. TOT .LT. 0.0) GO TO 140
DO Ii0 1 = I, N
II0 W(1) = W(1) - TOT
GO TO 160 140 TOT = 0.0
422
7.1-228
160 DO 360 K = i, M
********** NEXT QR TRANSFORMATION **********
180 TOT = TOT + S
DELTA = W(N) - S
I = N
F = ABS(MACHEP*TOT)
IF (EPSI .LT. F) EPSI = F
IF (DELTA .GT. EPSI) GO TO 190
IF (DELTA .LT. (-EPSI)) GO TO i000
GO TO 300
*~******** REPLACE SMALL SUB-DIAGONAL SQUARES BY ZERO
TO REDUCE THE INCIDENCE OF UNDERFLOWS *********e
190 IF (K .EQ. N) GO TO 210
K1 = K + 1
DO 200 J = KI, N
IF (BD(J) .LE. (MACHEP*(W(J)+W(J-I))) ** 2) BD(J) = 0.0
200 CONTINUE
210 F = BD(N) / DELTA
QP = DELTA + F
P = 1.0
IF (K .EQ. N) GO TO 260
K1 = N - K
~********~ FOR I=N-I STEP -I UNTIL K DO -- **********
DO 240 II = i, KI
I = N - II
Q = W(!) - S - F
R = Q / QP
P = P * R + 1.0
EP = F * R
W(I+I) = QP + EP
DELTA = Q - EP
IF (DELTA .GT. EPSI) GO TO 220
IF (DELTA .LT. (-EPSI)) GO TO i000
GO TO 300
220 F = BD(1) / Q
QP = DELTA + F
BD(I+I) = QP * EP
240 CONTINUE
260 W(K) = QP
S = QP / P
IF (TOT + S .GT. TOT) GO TO 180
**~******* SET ERROR -- IRREGULAR END OF ITERATION.
DEFLATE MINIMUM DIAGONAL ELEMENT ********** IERR = 5 * N + K
S=0.0
DELTA = QP
423
7.1-229
DO 280 J = K, N
IF (W(J) ~GT. DELTA) GO TO 280
I = J
DELTA = W(J)
280 CONTINUE
********** CONVERGENCE **********
300 IF (I .LT. N) BD(I+I) = BD(1) * F / QP
II = IND(1)
IF (I oEQ. K) GO TO 340
KI = I - K
**~******* FOR J=I-i STEP -i UNTIL K DO -- **********
DO 320 JJ = I, K1
J = I - JJ
W(J+I) = W(J) - S
BD(J+I) = BD(J)
IND(J+I) = IND(J)
320 CONTINUE
340 W(K) = TOT
ERR = ERR + ABS(DELTA)
BD(K) = ERR
IND(K) = II
360 CONTINUE
IF (TYPE) GO TO I001
F = BD(1)
E2(1) = 2.0
BD(1) = F
J = 2
********** NEGATE ELEMENTS OF W FOR LARGEST VALUES **********
400 DO 500 1 = i, N
5O0 W(1) : -W(1)
JDEF = -JDEF
GO TO (40,1001), J
********** SET ERROR -- IDEF SPECIFIED INCORRECTLY ***~******
i000 IERR = 6 * N + 1
i001 RETURN
END
424
7.1-230
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F303 RG
A Fortran IV Driver Subroutine to Determine the Eigenvalues and Eigenvectors of a Real General Matrix.
July, 1975
I. PURPOSE.
The Fortran IV subroutine RG calls the recommended sequence of subroutines from the eigensystem subroutine package EISPACK to determine the eigenvalues and eigenvectors (if desired) of a real general matrix.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE RG(NM,N,A,WR,W!,MATZ,Z,IVI,FVI,IERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays A and Z as specified in the DIMENSION statements for A and Z in the calling program.
N is an integer input variable set equal to the order of the matrix A. N must not be greater than NM.
A is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. On input, A contains the real general matrix of order N whose eigenvalues and eigenvectors are to be found. On output, A has been destroyed.
425
7.1-231
WR,WI
MATZ
IVl
FVI
IERR
are working precision real output one- dimensional variables of dimension at least N containing the real and imaginary parts, respectively, of the eigenvalues of the real general matrix. The eigenvalues are unordered except that complex conjugate pairs of eigenvalues appear consecutively with the eigenvalue having the positive imaginary part first.
is an integer input variable set equal to zero if only eigenvalues are desired; otherwise it is set to any non-zero integer for both eigenvalues and eigenvectors.
is, if MATZ is non-zero, a working precision real output two-dimensional variable with row dimension NM and column dimension at least N containing the real and imaginary parts of the eigenveetors. If the J-th eigenvalue is real, the J-th column of Z contains its eigenvector. If the J-th eigenvalue is complex with positive imaginary part, the J-th and (J+l)-th columns of Z contain the real and imaginary parts of its eigenvector. The conjugate of this vector is the eigenvector for the conjugate eigenvalue. The eigenvectors are not normalized. If MATZ is zero, Z is not referenced and can be a dummy variable.
is an integer temporary one-dimensional variable of dimension at least N.
is a working precision temporary one- dimensional variable of dimension at least N.
is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
426
7.1-232
B. Error Conditions and Returns.
If N is greater than NM, the subroutine terminates with IERR set equal to IO*N.
If more than 30 iterations are required to determine an eigenvalue, the subroutine terminates with IERR set equal to the index of the eigenvalue for which the failure occurs. The eigenvalues in the WR and WI arrays should be correct for indices IERR+I,IERR+2,...,N, but no eigenvectors are computed.
If all the eigenvalues are determined within 30 iterations, IERR is set to zero.
C. Applicability and Restrictions.
This subroutine can be used to find all the eigenvalues and all the eigenvectors (if desired) of a real general matrix.
3. DISCUSSION OF METHOD AND ALGORITHM.
This subroutine calls the recommended sequence of subroutines from EISPACK to find the eigenvalues and eigenvectors of a real general matrix.
To find eigenvalues only, the sequence is the following. BALANC - to balance a real general matrix. ELMHES - to reduce the balanced matrix to an upper
Hessenberg matrix using elementary transformations.
HQR - to determine the eigenvalues of the original matrix from the Hessenberg matrix.
To find eigenvalues and eigenvectors, the sequence is the following.
BALANC - to balance a real general matrix. ELMHES - to reduce the balanced matrix to an upper
Hessenberg matrix using elementary transformations.
ELTRAN - to accumulate the transformations from the Hessenberg reduction.
HQR2 - to determine the eigenvalues and eigenvectors of the balanced matrix from the Hessenberg matrix.
BALBAK - to backtransform the eigenvectors to those of the original matrix.
427
7. 1-233
4. REFERENCES~
I) Garbow, B.S. and Dongarra, J.J., April, 1974.
EISPACK Path Chart,
5. CHECKOUT~
A. Test Cases~
See the section discussing testing of the codes for real general matrices.
B. Accuracy.
The accuracy of RG can be best described in terms of its role in those paths of EISPACK (I) which find eigenvalues and eigenvectors of real general matrices. In these paths, this subroutine is, in practice, numerically stable. This stability contributes to the property of these paths that each computed eigenvalue and its corresponding eigenvector are exact for a matrix close to the original matrix.
428
7.1-234
SUBROUTINE RG(NM,N,A,WR,WI,MATZ,Z,IVI,FVI,IERR)
INTEGER N,NM,ISI,IS2,1ERR,MATZ REAL A(NM,N),WR(N),WI(N),Z(NM,N),FVI(N) INTEGER IVI(N)
IF (N .LE. NM) IERR = I0 * N GO TO 50
GO TO I0
i0 CALL BALANC(NM,N,A, ISI,IS2,FVI) CALL ELMHES(NM,N,ISI,IS2,A, IVI) IF (MATZ .RE. 0) GO TO 20 ********** FIND EIGENVALUES ONLY ********** CALL HQR(NM,N, ISI,IS2,A,WR,WI,IERR) GO TO 50 ********** FIND BOTH EIGENVALUES AND EIGENVECTORS
20 CALL ELTRAN(NM,N,ISI,IS2,A,IVI,Z) CALL HQR2(NM,N,ISI,IS2,A,WR,WI,Z,IERR) IF (IERR .NE. 0) GO TO 50 CALL BALBAK(NM,N,ISI,IS2,FVI,N,Z)
50 RETURN END
429
7.1-235
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F304 RS
A Fortran IV Driver Subroutine to Determine the Eigenvalues and Eigenvectors of a Real Symmetric Matrix.
July, 1975
i. PURPOSE.
The Fortran IV subroutine RS calls the recommended sequence of subroutines from the eigensystem subroutine package EISPACK to determine the eigenvalues and eigenvectors (if desired) of a real symmetric matrix.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE RS(NM,N,A,W,MATZ,Z,FVI,FV2,1ERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays A and Z as specified in the DIMENSION statements for A and Z in the calling program.
N is an integer input variable set equal to the order of the matrix A. N must not be greater than NM.
A is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. On input, A contains the real symmetric matrix of order N whose eigenvalues and eigenvectors are to be found. Only the full lower triangle of A need be supplied. On output, the full upper triangle of A is unaltered.
430
7.1-236
W is a working precision real output one- dimensional variable of dimension at least N containing the eigenvalues of the real symmetric matrix in ascending order.
MATZ is an integer input variable set equal to zero if only eigenvalues are desired; otherwise it is set to any non-zero integer for both eigenvalues and eigenvectors.
is, if MATZ is non-zero, a working precision real output two-dimensional variable with row dimension NM and column dimension at least N containing the eigenvectors. The eigenvectors are orthonormal. If MATZ is zero, Z is not referenced and can be a dummy variable.
FVI,FV2 are working precision temporary one- dimensional variables of dimension at least N.
IERR is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
B. Error Conditions and Returns.
If N is greater than NM, the subroutine terminates with IERR set equal to 10*N.
If more than 30 iterations are required to determine an eigenvalue, the subroutine terminates with IERR set equal to the index of the eigenvalue for which the failure occurs. The eigenvalues and eigenvectors in the W and Z arrays should be correct for indices 1,2,...,IERR-I.
If all the eigenvalues are determined within 30 iterations, IERR is set to zero.
C. Applicability and Restrictions.
This subroutine can be used to find all the eigenvalues and all the eigenvectors (if desired) of a real symmetric matrix.
4,31
7.1-237
3. DISCUSSION OF METHOD AND ALGORITHM.
This subroutine calls the recommended sequence of subroutines from EISPACK to find the eigenvalues and eigenvectors of a real symmetric matrix.
To find eigenvalues only, the sequence is the following. TREDI - to reduce a real symmetric matrix to a
symmetric tridiagonal matrix using orthogonal transformations.
TQLRAT - to determine the eigenvalues of the original matrix from the symmetric tridiagonal matrix.
To find eigenvalues and eigenvectors, the sequence is the following.
TRED2 - to reduce a real symmetric matrix to a symmetric tridiagonal matrix using and accumulating orthogonal transformations.
TQL2 - to determine the eigenvalues and eigenvectors of the original matrix from the symmetric tridiagonal matrix.
4, REFERENCES.
i) Garbow, B.S. and Dongarra~ J.J., April, 1974.
EISPACK Path Chart,
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for real symmetric matrices.
B. Accuracy°
The accuracy of RS can best be described in terms of its role in those paths of EISPACK (i) which find eigenvalues and eigenvectors of real symmetric matrices. In these paths, this subroutine is numerically stable. This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.
432
7.1-238
SUBROUTINE RS(NM,N,A,W,MATZ,Z,FVI,FV2,1ERR)
INTEGER N,NM,IERR,MATZ REAL A(NM,N),W(N),Z(NM,N),FVI(N),FV2(N)
IF (N .LE. NM) IERR = i0 * N GO TO 50
GO TO I0
I0 IF (MATZ .NE. 0) GO TO 20 ********** FIND EIGENVALUES ONLY ********** CALL TREDI(NM~N,A,W,FVI,FV2) CALL TQLRAT(N~W,FV2,1ERR) GO TO 50 ********** FIND BOTH EIGENVALUES AND EIGENVECTORS
20 CALL TRED2(NM,N,A,W,FVI,Z) CALL TQL2(NM,N,W, FVI,Z,IERR)
50 RETURN END
433
7.1-239
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F307 RSP
A Fortran IV Driver Subroutine to Determine the Eigenvalues and Eigenvectors of a Real Symmetric Packed Matrix.
July, 1975
I. PURPOSE.
The Fortran IV subroutine RSP calls the recommended sequence of subroutines from the eigensystem subroutine package EISPACK to determine the eigenvalues and eigenvectors (if desired) of a real symmetric packed matrix.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE RSP(NM,N,NV,A,W,MATZ,Z,FVI,FV2,IERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM
N
NV
is an integer input variable set equal to the row dimension of the two-dimensional array Z as specified in the DIMENSION statement for Z in the calling program.
is an integer input variable set equal to the order of the matrix A. N must not be greater than NM.
is an integer input variable set equal to the dimension of the array A as specified in the DIMENSION statement for A in the calling program. NV must not be less than N*(N+I)/2.
434
7.1-240
A is a working precision real one-dimensional variable of dimension at least NV. On input, A contains the lower triangle, stored row-wise, of the real symmetric packed matrix of order N whose eigenvalues and eigenvectors are to be found. For example if N=3, A should contain
(A(I,I),A(2,1),A(2,2),A(3,1),A(3,2),A(3,3))
where the subscripts for each element refer to the row and column of the element in the standard two-dimensional representation. On output, A has been destroyed.
W is a working precision real output one- dimensional variable of dimension at least N containing the eigenvalues of the real symmetric packed matrix in ascending order.
MATZ is an integer input variable set equal to zero if only eigenvalues are desired; otherwise it is set to any non-zero integer for both eigenvalues and eigenvectors.
is, if MATZ is non-zero, a working precision real output two-dimensional variable with row dimension NM and column dimension at least N containing the eigenvectors. The eigenvectors are orthonormal. If MATZ is zero, Z is not referenced and can be a dummy variable.
FVI,FV2 are working precision temporary one- dimensional variables of dimension at least N.
IERR is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
B. Error Conditions and Returns.
If N is greater than NM, the subroutine terminates with IERR set equal to 10*N.
If NV is less than N*(N+I)/2, the subroutine terminates with IERR set equal to 20*N.
435
7.1-241
If more than 30 iterations are required to determine an eigenvalue, the subroutine terminates with IERR set equal to the index of the eigenvalue for which the failure occurs. The eigenvalues and eigenvectors in the W and Z arrays should be correct for indices 1,2,...,IERR-Io
If all the eigenvalues are determined within 30 iterations, IERR is set to zero.
C. Applicability and Restrictions.
This subroutine can be used to find all the eigenvalues and all the eigenvectors (if desired) of a real symmetric packed matrix.
3. DISCUSSION OF METHOD AND ALGORITHM.
This subroutine calls the recommended sequence of subroutines from EISPACK to find the eigenvalues and eigenvectors of a real symmetric packed matrix.
To find eigenva!ues only, the sequence is the following. TRED3 - to reduce a real symmetric packed matrix to a
symmetric tridiagonal matrix using orthogonal transformations.
TQLRAT - to determine the eigenvalues of the original matrix from the symmetric tridiagonal matrix.
To find eigenva!ues and eigenvectors, the sequence is the following.
TRED3 - to reduce a real symmetric packed matrix to a symmetric tridiagonal matrix using orthogonal transformations.
TQL2 - to determine the eigenvalues and eigenvectors of the symmetric tridiagonal matrix.
TRBAK3 - to backtransform the eigenvectors to those of the original matrix.
4. REFERENCES.
I) Garbow~ B.S. and Dongarra, J.J., April, 1974.
EISPACK Path Chart,
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for real symmetric packed matrices.
436
7.1-242
B. Accuracy.
The accuracy of RSP can best be described in terms of its role in those paths of EISPACK (i) which find eigenvalues and eigenvectors of real symmetric packed matrices. In these paths, this subroutine is numerically stable. This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.
437
7.1-243
SUBROUTINE RSP(NM,N,NV,A,W,MATZ,Z,FVI,FV2~IERR)
INTEGER !,J~N,NM,NV,IERR,MATZ REAL A(NV),W(N),Z(NM,N),FVI(N),FV2(N)
IF (N .LE. NM) GO TO 5 !ERR = i0 * N GO TO 50
5 IF (NV .GE. (N * (N + i)) / 2) GO TO i0 IERR = 20 * N GO TO 50
I0 CALL TRED3(N,NV,A,W, FVI,FV2) IF (MATZ .NE. O) GO TO 20 ********** FIND EIGENVALUES ONLY ********** CALL TQLRAT(N,W,FV2,1ERR) GO TO 50 ********** FIND BOTH EIGENVALUES AND EIGENVECTORS **********
20 DO 40 I = i, N
30
DO 30 J = i, N Z(J,I) = 0.0
CONTINUE
Z(I,I) = 1.0 40 CONTINUE
CALL TQL2(NM,N,W, FVI,Z,IERR) IF (IERR .NE. 0) GO TO 50 CALL TRBAK3(NM,N,NV,A,N,Z)
50 RETURN END
438
7.1-244
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F305 RST
A Fortran IV Driver Subroutine to Determine the Eigenvalues and Eigenvectors of a Real Symmetric Tridiagonal Matrix.
July, 1975
I. PURPOSE.
The Fortran IV subroutine RST calls the recommended sequence of subroutines from the eigensystem subroutine package EISPACK to determine the eigenvalues and eigenvectors (if desired) of a real symmetric tridiagonal matrix.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE RST(NM,N,W,E,MATZ,Z,IERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional array Z as specified in the DIMENSION statement for Z in the calling program.
N is an integer input variable set equal to the order of the matrix. N must not be greater than NM.
W is a working precision real one-dimensional variable of dimension at least N. On input, it contains the diagonal elements of the real symmetric tridiagonal matrix. On output, it contains the eigenvalues of the matrix in ascending order.
439
7.1-245
MATZ
!ERR
is a working precision real one-dimensional variable of dimension at least N. On input~ it contains the subdiagonal elements of the matrix in its last N-I positions. E(1) is arbitrary. On output, E has been destroyed.
is an integer input variable set equal to zero if only eigenvalues are desired; otherwise it is set to any non-zero integer for both eigenvalues and eigenvectors.
is, if MATZ is non-zero, a working precision real output two-dimensional variable with row dimension NM and column dimension at least N containing the eigenvectors. The eigenvectors are orthonormal. If MATZ is zero, Z is not referenced and can be a dummy variable.
is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
B. Error Conditions and Returns°
If N is greater than NM, the subroutine terminates with IERR set equal to IO*N.
If more than 30 iterations are required to determine an eigenvalue, the subroutine terminates with !ERR set equal to the index of the eigenvalue for which the failure occurs. The eigenvalues and eigenvectors in the W and Z arrays should be correct for indices 1,2,o~.,IERR-I.
If all the eigenvalues are determined within 30 iterations~ IERR is set to zero.
C, Applicability and Restrictions°
This subroutine can be used to find all the eigenvalues and all the eigenvectors (if desired) of a real symmetric tridiagonal matrix.
440
7.1-246
3. DISCUSSION OF METHOD AND ALGORITHM.
This subroutine calls the recommended sequence of subroutines from EISPACK to find the eigenvalues and eigenvectors of a real symmetric tridiagona! matrix.
To find eigenvalues only, the sequence is the following. IMTQLI - to determine the eigenvalues of a real
symmetric tridiagonal matrix.
To find eigenvalues and eigenvectors, the sequence is the following.
IMTQL2 - to determine the eigenvalues and eigenvectors of a real symmetric tridiagonal matrix.
4. REFERENCES.
i) Garbow, B.S. and Dongarra, J°J., April, 1974.
EISPACK Path Chart,
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for real symmetric tridiagonal matrices.
B. Accuracy.
The subroutine RST is numerically stable; that is, the computed eigenvalues are close to those of the original matrix. In addition, they are the exact eigenvalues of a matrix close to the original real symmetric tridiagonal matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.
441
7.1-247
SUBROUTINE RST(NM,N,W,E,MATZ,Z,IERR)
INTEGER I,J,N,NM, IERR,MATZ REAL W(N),E(N),Z(NM,N)
IF (N .LE. NM) GO TO i0 IERR = i0 * N GO TO 50
i0 IF (MATZ .NE. 0) GO TO 20 ********** FIND EIGENVALUES ONLY ********** CALL IMTQLI(N~W,E,IERR) GO TO 50 ********** FIND BOTH EIGENVALUES AND EIGENVECTORS **********
20 DO 40 I = I, N
30
DO 30 J = i, N z(J,I) = 0o0
CONTINUE
z(~,i) = i.o
40 CONTINUE
CALL IMTQL2(NM,N,W,E,Z,IERR)
50 RETURN END
442
7.1-248
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F306 RT
A Fortran IV Driver Subroutine to Determine the Eigenvalues and Eigenvectors of a Certain Real Tridiagonal Matrix.
July, 1975
i. PURPOSE.
The Fortran IV subroutine RT calls the recommended sequence of subroutines from the eigensystem subroutine package EISPACK to determine the eigenvalues and eigenvectors (if desired) of a certain real tridiagonal matrix. The property of the matrix required for use of this subroutine is that the products of pairs of corresponding off-diagonal elements be all non-negative, and further if eigenvectors are desired, no product be zero unless both factors are zero.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE RT(NM~N~A,W,MATZ,Z~FVI,IERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays A and Z as specified in the DIMENSION statements for A and Z in the calling program.
is an integer input variable set equal to the order of the matrix A. N must not be greater than NM.
443
7.1-249
MATZ
FVI
!ERR
is a working precision real input two- dimensional variable with row dimension NM and column dimension at least 3 containing the real tridiagonal matrix of order N whose eigenvalues and eigenvectors are to be found. Its subdiagonal elements are stored in the last N-I positions of the first column, its diagonal elements are stored in the second column, and its superdiagonal elements are stored in the first N-I positions of the third column. Elements A(I,I) and A(N,3) are arbitrary.
is a working precision real output one- dimensional variable of dimension at least N containing the eigenvalues of the real tridiagonal matrix in ascending order.
is an integer input variable set equal to zero if only eigenvalues are desired; otherwise it is set to any non-zero integer for both eigenvalues and eigenvectors.
is, if MATZ is non-zero, a working precision real output two-dimensional variable with row dimension NM and column dimension at least N containing the eigenvectors. The eigenvectors are not normalized. If MATZ is zero, Z is not referenced and can be a dummy variable.
is a working precision temporary one- dimensional variable of dimension at least N.
is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
B. Error Conditions and Returns.
If N is greater than NM, the subroutine terminates with IERR set equal to 10*N.
If the product of A(I,I) and the subroutine terminates with and no results computed.
A(I-I,3) is negative, IERR set equal to N+I
If the product is zero with one factor non-zero, and MATZ is non-zero, the subroutine terminates with IERR set equal to 2*N+I and no results computed.
444
7.1-250
If more than 30 iterations are required to determine an eigenvalue, the subroutine terminates with IERR set equal to the index of the eigenvalue for which the failure occurs. The eigenvalues and eigenvectors in the W and Z arrays should be correct for indices 1,2,...,IERR-I.
If all the eigenvalues are determined within 30 iterations, IERR is set to zero.
C. Applicability and Restrictions.
This subroutine can be used to find all the eigenvalues and all the eigenvectors (if desired) of a certain real tridiagonal matrix.
3. DISCUSSION OF METHOD AND ALGORITHM.
This subroutine calls the recommended sequence of subroutines from EISPACK to find the eigenvalues and eigenvectors of a certain real tridiagonal matrix.
To find eigenvalues only, the sequence is the following. FIGI - to transform a certain real tridiagonal matrix
into a symmetric tridiagonal matrix. IMTQLI - to determine the eigenvalues of the original
matrix from the symmetric tridiagonal matrix.
To find eigenvalues and eigenvectors, the sequence is the following.
FIGI2 - to transform a certain real tridiagonal matrix into a symmetric tridiagonal matrix, accumulating the transformations.
IMTQL2 - to determine the eigenvalues and eigenvectors of the original matrix from the symmetric tridiagonal matrix.
4. REFERENCES.
i) Garbow, B.S. and Dongarra, J.J., April, 1974.
EISPACK Path Chart,
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for certain real non-symmetric tridiagonal matrices.
B. Accuracy.
445
7,1-251
The accuracy of RT can best be described in terms of its role in those paths of EISPACK (i) which find eigenvalues and eigenvectors of certain real non- symmetric tridiagonal matrices. In these paths, this subroutine is numerically stable. This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.
446
7.1-252
SUBROUTINE RT(NM,N,A,W,MATZ,Z,FVl,IERR)
INTEGER N,NM,IERR,MATZ REAL A(NM,3),W(N),Z(NM,N),FVI(N)
IF (N .LE. NM) GO TO I0 IERR = i0 * N GO TO 50
I0 IF (MATZ .NE. 0) GO TO 20 ********** FIND EIGENVALUES ONLY ********** CALL FIGI(NM,N,A,W,FVI,FVI,IERR) IF (IERR .GT. 0) GO TO 50 CALL IMTQLI(N,W,FVI,IERR) GO TO 50 ********** FIND BOTH EIGENVALUES AND EIGENVECTORS **********
20 CALL FIGI2(NM,N,A,W, FVI,Z,IERR) IF (IERR .NE. O) GO TO 50 CALL IMTQL2(NM,N,W,FVI,Z,IERR)
50 RETURN END
447
7. 1-253
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F223-2 TINVIT
A Fortran IV Subroutine to Determine Some Eigenvectors of a Symmetric Tridiagonal Matrix.
May, 1972 July, 1975
io PURPOSE°
The Fortran IV subroutine TINVIT determines those eigenvectors of a symmetric tridiagonal matrix corresponding to a set of ordered approximate eigenvalues~ using inverse
iteration.
2. USAGE.
A. Calling Sequence°
The SUBROUTINE statement is
SUBROUTINE TINVIT(NM,N,D,E,E2,M,W, IND,Z, IERR,RVI,RV2,RV3,RV4,RV6)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM
N
D
is an integer input variable set equal to the row dimension of the two-dimensional array Z as specified in the DIMENSION statement for Z in the calling program.
is an integer input variable set equal to the order of the matrix. N must be not greater than NM.
is a working precision real input one- dimensional variable of dimension at least N containing the diagonal elements of the symmetric tridiagonal matrix.
448
7.1-254
E2
M
W
IND
is a working precision real input one- dimensional variable of dimension at least N containing, in its last N-I positions, the subdiagonal elements of the symmetric tridiagonal matrix. E(1) is arbitrary.
is a working precision real input one- dimensional variable of dimension at least N containing, in its last N-I positions, the squares of the corresponding elements of E with zeros corresponding to negligible elements of E, (The successive submatrices are located from the zeros of E2.) If MACHEP denotes the relative machine precision, then E(I) is considered negligible if it is not larger than the product of MACHEP and the sum of the magnitudes of D(I) and D(I-I). E2(1) should contain 0.0 if the eigenvalues are in ascending order and 2.0 if the eigenvalues are in descending order. If subroutine BISECT (F294) or TRIDIB (F237) has been used to determine the eigenvalues, their output E2 array is suitable for input to TINVIT.
is an integer input variable set equal to the number of specified eigenvalues for which the corresponding eigenvectors are to be determined.
is a working precision real input one- dimensional variable of dimension at least M containing the M specified eigenvalues of the symmetric tridiagonal matrix. The eigenvalues must be in either ascending or descending order in W. The ordering is required to insure the determination of independent orthogonal eigenvectors associated with close eigenvalues.
is an integer input one-dimensional variable of dimension at least M containing the submatrix indices associated with the corresponding M eigenvalues in W. Eigenvalues belonging to the first submatrix have index i, those belonging to the second submatrix have index 2, etc. If BISECT or TRIDIB has been used to determine the eigenvalues, their output IND array is suitable for input to TINVIT.
449
7.1-255
is a working precision real output two- dimensional variable with row dimension NM and column dimension at least M. It contains M orthonormal eigenvectors of the symmetric tridiagonal matrix corresponding to the M eigenvalues in W.
!ERR is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
RVI,RV2,RV3
are working precision real temporary one- dimensional variables of dimension at least N used to store the main diagonal and the two adjacent diagonals of the triangular matrix produced in the inverse iteration process.
RV4,RV6 are working precision real temporary one- dimensional variables of dimension at least N. RV4 holds the multipliers of the Gaussian elimination step in the inverse iteration process. RV6 holds the approximate eigenvectors in this process.
B. Error Conditions and Returns~
If more than 5 iterations are required to determine an eigenvector, TINVIT terminates the computation for that eigenvector and sets IERR to -R where R is the index of the eigenvector. If this failure occurs for more than one eigenvector, the last occurrence is recorded in IERR. The columns of Z corresponding to failures of the above sort are set to zero vectors.
If all the eigenvectors are determined within 5 iterations, IERR is set to zero.
C. Applicability and Restrictions.
To determine some of the eigenva!ues and eigenvectors of a full symmetric matrix, TINVIT should be preceded by TREDI (F277) to provide a suitable symmetric tridiagonal matrix for BISECT (F294), TRIDIB (F237), or !MTQLV (F234) which can then be used to determine the eigenvalues. It should be followed by TRBAKI (F279) to back transform the eigenvectors from TINVIT into those of the original matrix.
450
7.1-256
To determine some of the eigenvalues and eigenvectors of a complex Hermitian matrix, TINVlT should be preceded by HTRIDI (F284) to provide a suitable real symmetric tridiagonal matrix for BISECT (F294), TRIDIB (F237), or IMTQLV (F234). It should then be followed by HTRIBK (F285) to back transform the eigenvectors from TINVIT into those of the original matrix.
Some of the eigenvalues and eigenvectors of certain non- symmetric tridiagonal matrices can be computed using the combination of FIGI (F280), BISECT (F294) or TRIDIB (F237), TINVlT, and BAKVEC (F281). See F280 for the description of this special class of matrices. For these matrices, TINVIT should be preceded by FIGI to provide a suitable symmetric matrix for BISECT or TRIDIB. It should then be followed by BAKVEC to back transform the eigenvectors from TINVIT into those of the original matrix.
The computation of the eigenvectors by inverse iteration requires that the precision of the eigenvalues be commensurate with small relative perturbations of the order of MACHEP in the matrix elements. For most symmetric tridiagonal matrices, it is enough that the absolute error in the eigenvalues for which eigenvectors are desired be approximately MACHEP times a norm of the matrix. But some matrices require a smaller absolute error, perhaps as small as MACHEP times the eigenvalue of smallest magnitude.
3. DISCUSSION OF METHOD AND ALGORITHM.
The calculations proceed as follows. First, the E2 array is inspected for the presence of a zero element defining a submatrix. The eigenvalues belonging to this submatrix are identified by their common submatrix index in IND.
The eigenvectors of the submatrix are then computed by inverse iteration. First, the LU decomposition of the submatrix with an approximate eigenvalue subtracted from its diagonal elements is achieved by Gaussian elimination using partial pivoting. The multipliers defining the lower triangular matrix L are stored in the temporary array RV4 and the upper triangular matrix U is stored in the three temporary arrays RVI, RV2, and RV3. Saving these quantities in RVl, RV2, RV3, and RV4 avoids repeating the LU decomposition if further iterations are required. An approximate vector, stored in RV6, is computed starting from an initial vector, and the norm of the approximate vector is compared with a norm of the submatrix to determine whether the growth is sufficient to accept it as an eigenvector. If this vector is accepted, its Euclidean norm
451
7.1-257
is made I, If the growth is not sufficient, this vector is used as the initial vector in computing thenext approximate vector, This iteration process is repeated at most 5 times.
Eigenvectors computed in the above way corresponding to well- separated eigenvalues of this submatrix will be orthogonal. However, eigenvectors corresponding to close eigenvalues of this submatrix may not be satisfactorily orthogonal. Hence, to insure orthogonal eigenvectors~ each approximate vector is made orthogonal to those previously computed eigenvectors whose eigenvalues are close to the current eigenvalue. If the orthogonalization process produces a zero vector, a column of the identity matrix is used as an initial vector for the next iteration.
Identical eigenvalues are perturbed slightly in an attempt to obtain independent eigenvectors. These perturbations are not recorded in the eigenvalue array W.
The above steps are repeated on each submatrix until all the eigenvectors are computed.
This subroutine is a subset (except for the resolution of non-convergent eigenvectors) of the Fortran subroutine TSTUKM (F293), which is a translation of the Algol procedure TR!STURM written and discussed in detail by Peters and Wilkinson (I)°
4. REFERENCES.
i) Peters, Go and Wilkinson, J.H., The Calculation of Specified Eigenvectors by Inverse Iteration, Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/18, 418-439, Springer-Verlag, 1971.
5. CHECKOUT.
A. Test Cases°
See the section discussing testing of the codes for complex Hermitian, real symmetric, real symmetric tridiagonal, and certain real non-symmetric tridiagonal matrices.
452
7.1-258
B. Accuracy.
The accuracy of TINVIT can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real symmetric matrices and matrix systems. In these paths, this subroutine is numerically stable (i). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix or system close to the original matrix or system and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix or system.
453
7.1-259
C
C
C C
C C
C
C
C C C C
SUBROUTINE TINVIT(NM,N,D,E,E2,M,W,IND,Z, X IERR,RVI,RV2,RV3,RV4,RV6)
INTEGER I,J,M,N,P,Q,R~S,II,IP,JJ,NM,ITS,TAG, IERR,GROUP
REAL D(N),E(N),E2(N),W(M),Z(NM,M),
X RVI(N),RV2(N),RVB(N),RV4(N),RV6(N) REAL U,V,UK,XU,XO,XI,EPS2,EPS3,EPS4,NORM,ORDER,MACHEP
REAL SQRT,ABS,FLOAT INTEGER IND(M)
********** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING
THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.
MACHEP = ?
IERR = 0 IF (M .EQ. 0) GO TO I001
TAG = 0 ORDER = 1.0 - E2(1)
Q = 0 ********** ESTABLISH AND PROCESS NEXT SUBMATRIX **********
I00 P = Q + I
DO 120 Q = P, N IF (Q .EQ. N) GO TO 140 IF (E2(Q+I) .EQ. 0.0) GO TO 140
120 CONTINUE ********** FIND VECTORS BY INVERSE ITERATION ~*********
140 TAG = TAG + 1
S = 0
490
DO 920 R = i, M IF (!ND(R) .NEo TAG) GO TO 920
ITS = 1
Xl = W(R) IF (S .ME. 0) GO TO 510
********** CHECK FOR ISOLATED ROOT **********
XU = 1.0 IF (P .ME. Q) GO TO 490
RV6(P) = 1.0 GO TO 870 NORM = ABS(D(P)) IP = P + i
500 DO 500 I = IP, Q NORM = NORM + ABS(D(1)) + ABS(E(1))
********** EPS2 IS THE CRITERION FOR GROUPING, EPS3 REPLACES ZERO PIVOTS AND EQUAL
ROOTS ARE MODIFIED BY EPS3, EPS4 IS TAKEN VERY SMALL TO AVOID OVERFLOW **********
EPS2 = 1.0E-3 * NORM EPS3 = MACHEP * NORM UK = FLOAT(Q-P+I)
454
7.1-260
C
C
EPS4 = UK * EPS3
UK = EPS4 / SQRT(UK)
S = P
505 GROUP = 0 GO TO 520
• ********* LOOK FOR CLOSE OR COINCIDENT ROOTS ********** 510 IF (ABS(XI-X0) .GE. EPS2) GO TO 505
GROUP = GROUP + I
IF (ORDER * (XI - X0) .LE. 0.0) XI = X0 + ORDER * EPS3
• ********* ELIMINATION WITH INTERCHANGES AND INITIALIZATION OF VECTOR **********
520 V = 0.0
540
560
580
600
620
DO 580 1 = P, Q
RV6 (I) = UK IF (I .EQ. P) GO TO 560
IF (ABS(E(1)) .LT. ABS(U)) GO TO 540 ********** WARNING -- A DIVIDE CHECK MAY OCCUR HERE IF
E2 ARRAY HAS NOT BEEN SPECIFIED CORRECTLY ********** XU = U / E(1)
RV4(I) = XU RVt(I-l) = E(I)
RV2(I-I) = D(1) - El
RV3(I-I) = 0.0
IF (I .NE. Q) RV3(I-I) = E(I+I) U = V - XU * RV2(I-I) V = -XU * RV3(I-I)
GO TO 580 xu = E(I) / U RV4(1) = XU RVI(I-I) = u
RV2(I-I) = V RV3(I-I) = 0.0 U = D(I) - X1 - XU * V
IF (I .NE. Q) V = E(I+I) CONTINUE
IF (U .EQ. 0.0) U = EPS3 RVI(Q) = u
RV2(Q) = 0.0
RV3(Q) = 0.0
********** BACK SUBSTITUTION FOR I=Q STEP -I UNTIL P DO -- **********
DO 620 II = P, Q
I = P + Q - II
RV6(I) = (RV6(I) - U * RV2(I) - V * RV3(I)) / RVI(I) V = U U = RV6 (I)
CONTINUE
********** ORTHOGONALIZE WITH RESPECT TO PREVIOUS MEMBERS OF GROUP **********
IF (GROUP .EQ. O) GO TO 700 J = R
455
7.1-261
C
C
C
C C
C
630
640
660
680
700
720
740
DO 680 JJ = I, GROUP
J = J - 1
IF (IND(J) oNE. TAG) GO TO 630
XU = 0.0
DO 640 1 = P, Q
xu = xu + RV6(!) * Z(I,J)
DO 660 I = P, Q RV6(1) = RV6(1) - XU * Z(I,J)
CONTINUE
NORM = 0.0
DO 720 I = P, Q
NORM = NORM + ABS(RV6(I))
IF (NORM .GE. !.0) GO TO 840 ******~*** FORWARD SUBSTITUTION **********
IF (ITS .EQ. 5) GO TO 830 IF (NORM .NE. 0.0) GO TO 740
RV6(S) = EPS4 S = S + I IF (S .GT. Q) S = P
GO TO 780 XU = EPS4 / NORM
DO 760 1 = P, Q
760 RV6(I) = RV6(I) * XU • ********* ELIMINATION OPERATIONS ON NEXT VECTOR
ITERATE **********
780 DO 820 I = IP, Q
U = RV6 (I) • ********* IF RVI(I-I) .EQ. E(1), A ROW INTERCHANGE
WAS PERFORMED EARLIER IN THE TRIANGULARIZATION PROCESS **********
IF (RVI(I-I) .NE. E(I)) GO TO 800
u = ~v6(i-1)
RV6(I-I) = RV6(I)
800 RV6(1) = U - RV4(1) * RV6(I-I) 820 CONTINUE
ITS = ITS + ! GO TO 600
C ********** SET ERROR -- NON-CONVERGED EIGENVECTOR **********
830 IERR = -R XU = 0.0 GO TO 870
C ********** NORMALIZE SO THAT SUM OF SQUARES IS C 1 AND EXPAND TO FULL ORDER **********
840 U = 0.0
456
7 .1 -262
DO 860 I = P, Q 860 u = u + RV6(1)**2
C
XU = 1.0 / SQRT(U) C
870 DO 880 I = i, N 880 Z(I,R) = 0.0
C DO 900 I = P, Q
900 Z(I,R) = RV6(I) * XU C
X0 = X1 920 CONTINUE
C
IF (Q .LT. N) GO TO I00 I001 RETURN
END
457
7.!-263
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F235 TQLRAT
A Fortran IV Subroutine to Determine the Eigenvalues of a Symmetric Tridiagonal Matrix.
July, 1975
I. PURPOSE.
The Fortran IV subroutine TQLRAT determines the eigenvalues of a symmetric tridiagonal matrix using a rational variant of the QL method.
2. USAGE.
A. Calling Sequences
The SUBROUTINE statement is
SUBROUTINE TQLRAT(N,D,E2,1ERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
N is an integer input variable set equal to the order of the matrix.
is a working precision real one-dimensional variable of dimension at least N. On input, it contains the diagonal elements of the symmetric tridiagonal matrix. On output, it contains the eigenvalues of this matrix in ascending order.
E2 is a working precision real one-dimensional variable of dimension at least N. On input, the last N-I positions in this array contain the squares of the subdiagonal elements of the symmetric tridiagonal matrix. E2(1) is arbitrary. Note that TQLRAT destroys E2.
458
7.1-264
IERR is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
B. Error Conditions and Returns.
If more than 30 iterations are required to determine an eigenvalue, TQLRAT terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues in the D array should be correct for indices 1,2,...,IERR-I. These eigenvalues are ordered but are not necessarily the smallest IERR-I eigenvalues.
If all the eigenva!ues are determined within 30 iterations, IERR is set to zero.
C. Applicability and Restrictions.
To determine the eigenvalues of a full symmetric matrix, TQLRAT should be preceded by TREDI (F277) to provide a suitable symmetric tridiagonal matrix for TQLRAT.
To determine the eigenvalues of a complex Hermitian matrix, TQLRAT should be preceded by HTRIDI (F284) to provide a suitable real symmetric tridiagonal matrix for TQLRAT.
TQLRAT does not perform well on matrices whose successive row sums vary widely in magnitude and are not strictly increasing from the first to the last row. The subroutine IMTQLI (F291) is not sensitive to such row sums and is therefore recommended for symmetric tridiagonal matrices whose structure is not known.
3. DISCUSSION OF METHOD AND ALGORITHM.
The eigenvalues are determined by a rational variant of the QL method. The essence of this method is a process whereby a sequence of symmetric tridiagonal matrices, unitarily similar to the original symmetric tridiagonal matrix, is formed which converges to a diagonal matrix. The rate of convergence of this sequence is improved by shifting the origin at each iteration. Before the iterations for each eigenvalue, the symmetric tridiagonal matrix is checked for a possible splitting into submatrices. If a splitting occurs, only the uppermost submatrix participates in the next iteration. The eigenvalues are ordered in ascending order as they are found.
459
7.1-265
The origin shift at each iteration is the eigenvalue of the current uppermost 2x2 principal minor closer to the first diagonal element of this minor. Whenever the uppermost Ixl principal submatrix finally splits from the rest of the matrix, its element is taken to be an eigenvalue of the original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of order i. The tolerances in the splitting tests are proportional to the relative machine precision.
This subroutine is a translation of the Algol procedure TQLRAT written and discussed in detail by Reinsch (I). It is a rational variant of the subroutine TQLI which is a translation of the Algol procedure TQLI written and discussed in detail by Bowdler, Martin, Reinsch, and Wilkinson (2).
4. REFERENCES.
1) Reinsch, C.H.~ A Stable Rational QR Algorithm for the Computation of the Eigenvalues of an Hermitian, Tridiagonal Matrix, Math. Comp. 25,591-597 (1971). (Algorithm 464, Comm, ACM 16,689 (1973).)
2) Bowdler, Ho, Martin, R.S.~ Reinsch, C., and Wilkinson, J.H., The QR and QL Algorithms for Symmetric Matrices, Num. Math. 11,293-306 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - Co Reinsch, Contribution 11/3, 227-240, Springer-Verlag, 1971.)
5. CHECKOUT.
A, Test Cases.
See the section discussing testing of the codes for complex Hermitian, real symmetric, real symmetric tridiagonal, and certain real non-symmetric tridiagonal matrices.
Bo Accuracy,
The subroutine TQLRAT is numerically stable (1,2); that is, the computed eigenvalues are close to those of the original matrix. In addition, they are the exact eigenvalues of a matrix close to the original real symmetric tridiagonal matrix.
460
7.1-266
SUBROUTINE TQLRAT(N,D,E2,1ERR)
INTEGER I,J,L,M,N,II,LI,MML,IERR
REAL D(N),E2(N) REAL B,C,F,G,H,P,R,S,MACHEP
REAL SQRT,ABS,SIGN
********** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING
THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.
**********
MACHEP = ?
IERR = 0 IF (N .EQ. i) GO TO I001
DO i00 1 = 2, N i00 E2(I-I) = E2(1)
F = 0.0
B = 0.0 E2 (N) = 0.0
105
i i 0
DO 290 L = I, N J = 0 H = MACHEP * (ABS(D(L)) + SQRT(E2(L)))
IF (B .GT. H) GO TO 105 B = H
C = B * B
• ********* LOOK FOR SMALL SQUARED SUB-DIAGONAL ELEMENT ********** DO II0 M = L, N
IF (E2(M) .LE. C) GO TO 120 • ********* E2(N) IS ALWAYS ZERO, SO THERE IS NO EXIT
THROUGH THE BOTTOM OF THE LOOP ********** CONTINUE
120
130 IF (M .EQo L) GO TO 210 IF (J .EQ. 30) GO TO i000 J = J + I
********** FORM SHIFT ********** LI = L + I S = SQRT(E2(L))
G = D(L)
P = (D(LI) - G) / (2.0 * S) R = SQRT(P*P+I.0)
D(L) = S / (e + SIGN(R,P))
H = G - D(L)
140 DO 140 1 = LI, N D(I) = D(I) - H
F = F + H
461
7.1-267
200
********** RATIONAL QL TRANSFORMATION **********
G = D (M)
IF (G ,EQ, 0.0) G = B
H = G
S = 0 , 0
M M L = M - L
********** FOR !=M-I STEP -I UNTIL L DO -- **********
DO 200 II = I, MML
I = M - II
P = G * H
R = P + E2(1)
E2(I+I) = S * R
S = E2(1) / R
o(I+i) = H + s * (~ + D(I))
G = D(1) - E2(1) / g
IF (G .EQ. 0.0) G = B
H = G * P / R
CONTINUE
E2(L) = S * G
D(L) = H
C ********** GUARD AGAINST UNDERFLOW IN CONVERGENCE TEST **********
IF (H .EQ. 0.0) GO TO 210
IF (ABS(E2(L)) .LE. ABS(C/H)) GO TO 210
E2(L) = H * E2(L)
IF (E2(L) .NE. 0.0) GO TO 130
210 P = D(L) + F
C ********** ORDER EIGENVALUES **********
IF (L ,EQ. i) GO TO 250
C ********** FOR I=L STEP -i UNTIL 2 DO -- **********
DO 230 II = 2, L
I = L + 2 - II
IF (P .GE. D(I-I)) GO TO 270
D(!) = D (I-I)
230 CONTINUE
250 I = 1
270 D(1) = P
290 CONTINUE
GO TO I001 ********** SET ERROR -- NO CONVERGENCE TO AN
EIGENVALUE AFTER 30 ITERATIONS **********
I000 IERR = L
i001 RETURN
END
462
7.1-268
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F289-2 TQLI
A Fortran IV Subroutine to Determine the Eigenvalues of a Symmetric Tridiagonal Matrix.
May, 1972 July, 1975
i. PURPOSE.
The Fortran IV subroutine TQLI determines the eigenvalues of a symmetric tridiagonal matrix using the QL method.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE TQLI(N,D,E,IERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
is an integer input variable set equal to the order of the matrix.
is a working precision real one-dimensional variable of dimension at least N. On input, it contains the diagonal elements of the symmetric tridiagonal matrix. On output, it contains the eigenva!ues of this matrix in ascending order.
is a working precision real one-dimensional variable of dimension at least N. On input, the last N-I positions in this array contain the subdiagonal elements of the symmetric tridiagona! matrix. E(1) is arbitrary. Note that TQLI destroys E.
463
7.1-269
IERR is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
B. Error Conditions and Returns°
If more than 30 iterations are required to determine an eigenvalue, TQLI terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues in the D array should be correct for indices 1,2,o..,IERR-I. These eigenvalues are ordered but are not necessarily the smallest IERR-I eigenvalues.
If all the eigenvalues are determined within 30 iterations, IERR is set to zero.
C. Applicability and Restrictions.
To determine the eigenvalues of a full symmetric matrix, TQLI should be preceded by TREDI (F277) to provide a suitable symmetric tridiagonal matrix for TQLI.
To determine the eigenvalues of a complex Hermitian matrix, TQLI should be preceded by HTRIDI (F284) to provide a suitable real symmetric tridiagonal matrix for TQLI.
TQLI does not perform well on matrices whose successive row sums vary widely in magnitude and are not strictly increasing from the first to the last row. The subroutine IMTQL! (F291) is not sensitive to such row sums and is therefore recommended for symmetric tridiagonal matrices whose structure is not known.
3. DISCUSSION OF METHOD AND ALGORITHM.
The eigenvalues are determined by the QL method. The essence of this method is a process whereby a sequence of symmetric tridiagonal matrices, unitarily similar to the original symmetric tridiagonal matrix, is formed which converges to a diagonal matrix. The rate of convergence of this sequence is improved by shifting the origin at each iteration° Before the iterations for each eigenvalue, the symmetric tridiagonal matrix is checked for a possible splitting into submatrices. If a splitting occurs, only the uppermost submatrix participates in the next iteration. The eigenvalues are ordered in ascending order as they are found.
464
7.1-270
The origin shift at each iteration is the eigenvaiue of the current uppermost 2x2 principal minor closer to the first diagonal element of this minor. Whenever the uppermost ixl principal submatrix finally splits from the rest of the matrix, its element is taken to be an eigenvalue of the original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of order I. The tolerances in the splitting tests are proportional to the relative machine precision.
This subroutine is a translation of the Algol procedure TQLI written and discussed in detail by Bowdler, Martin, Reinsch, and Wilkinson (I).
4. REFERENCES.
i) Bowdler, H., Martin, R.S., Reinsch, C., and Wilkinson, J.H., The QR and QL Algorithms for Symmetric Matrices, Num. Math. 11,293-306 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/3, 227-240, Springer-Verlag, 1971.)
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for complex Hermitian, real symmetric, real symmetric tridiagonal, and certain real non-symmetric tridiagonal matrices.
B. Accuracy.
The subroutine TQLI is numerically stable (i); that is, the computed eigenvalues are close to those of the original matrix. In addition, they are the exact eigenvalues of a matrix close to the original real symmetric tridiagonal matrix.
465
7.1-271
C
SUBROUTINE TQLI(N,D,E,IERR)
INTEGER !,J,L,M,N,II,LI,MML,IERR
REAL D(N),E(N) REAL B,C,F,G,H,P,R,S,MACHEP
REAL SQRT,ABS,SIGN
********** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING
THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.
**********
MACHEP = ?
IERR = 0
IF (N .EQ. i) GO TO I001
DO i00 I = 2, N
100 E(I-I) = E(1)
F = 0.0
B = 0.0 E(N) = 0.0
ii0
DO 290 L = i, N
J=0 H = MACHEP * (ABS(D(L)) + ABS(E(L))) IF (B .er. H) B = H
• ********* LOOK FOR SMALL SUB-DIAGONAL ELEMENT **********
DO Ii0 M = L, N IF (ABS(E(M)) .LE. B) GO TO 120
• ********* E(N) IS ALWAYS ZERO, SO THERE IS NO EXIT
THROUGH THE BOTTOM OF THE LOOP **********
CONTINUE
120 130
IF (M °EQ. L) GO TO 210
IF (J ,EQ. 30) GO TO I000
J = J + 1 ********** FORM SHIFT **********
L1 = L + 1 G = D (L) e = (D(LI) - G) / (2.0 * E(L))
R = SQRT(P*P+I.0) D(L) = E(L) / (e + SIGN(R,P))
H = G - D(L)
140
DO 140 I = LI, N
D(1) = D(i) - H
F = F + H
********** QL TRANSFORMATION **********
P = D (M)
C = i°0 S = 0 . 0
MML = M - L
466
7.1-272
150
160
200
********** FOR I--M-I STEP -I UNTIL L DO -- **********
DO 200 II = i, MML
I = M- II
G = C * E(I)
H = C * P
IF (ABS(P) .LT. ABS(E(1))) GO TO 150
C = E(1) / P
R = SQRT(C*C+I.0)
E(I+I) = S * P * R
S=C/R C = 1.0 / R
GO TO 160
C = P / E(1)
R = SQRT(C*C+I.0)
E(I+I) = S * E(1) * R
S = 1,0 1 R
C = C * S
P = C * D(1) - S * G
D(I+I) = II + S * (C * g + S * D(1))
CONTINUE
E(L) = S * P
D(L) = C * P
IF (ABS(E(L)) .GT. B) GO TO 130
210 P = D(L) + F
• ********* ORDER EIGENVALUES **********
IF (L .EQ. I) GO TO 250
• ********* FOR I=L STEP -i UNTIL 2 DO -- **********
DO 230 II = 2, L
I = L + 2 - II
IF (P oGE. D(I-I)) GO TO 270
D(1) = D(I-I)
230 CONTINUE
250 I = 1
270 D(I) = P
290 CONTINUE
GO TO I001
********** SET ERROR -- NO CONVERGENCE TO AN
EIGENVALUE AFTER 30 ITERATIONS ********** i000 IERR = L
i001 RETURN
END
467
7.1-273
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F290-2 TQL2
A Fortran IV Subroutine to Determine the Eigenvalues and Eigenvectors of a Symmetric Tridiagonal Matrix.
May, 1972 July, 1975
1, PURPOSE.
The Fortran IV subroutine TQL2 determines the eigenvalues and eigenvectors of a symmetric tridiagonal matrix. TQL2 uses the QL method to compute the eigenvalues and accumulates the QL transformations to compute the eigenvectors. The eigenvectors of a full symmetric matrix can also be computed directly by TQL2, if TRED2 (F278) has been used to reduce this matrix to tridiagonal form.
2. USAGE.
A. Calling Sequence~
The SUBROUTINE statement is
SUBROUTINE TQL2(NM,N,D,E,Z,IERR)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional array Z as specified in the DIMENSION statement for Z in the calling program.
is an integer input variable set equal to the order of the matrix. N must be not greater than NM.
is a working precision real one-dimensional variable of dimension at least N. On input, it contains the diagonal elements of the symmetric tridiagonal matrix. On output, it contains the eigenvalues of this matrix in ascending order.
468
7. 1-274
IERR
is a working precision real one-dimensional variable of dimension at least N. On input, the last N-I positions in this array contain the subdiagonal elements of the symmetric tridiagonal matrix. E(1) is arbitrary. Note that TQL2 destroys E.
is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. If the eigenvectors of the symmetric tridiagonal matrix are desired, then on input, Z contains the identity matrix of order N, and on output, contains the orthonormal eigenvectors of this tridiagonal matrix. If the eigenvectors of a full symmetric matrix are desired, then on input, Z contains the transformation matrix produced in TRED2 which reduced the full matrix to tridiagonal form, and on output, contains the orthonormal eigenveetors of this full symmetric matrix.
is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
B. Error Conditions and Returns.
If more than 30 iterations are required to determine an eigenvalue, TQL2 terminates with IERR set to the index of the eigenvalue for which the failure occurs. The eigenvalues and eigenvectors in the D and Z arrays should be correct for indices 1,2,...,IERR-I, but the eigenvalues are unordered.
If all the eigenvalues are determined within 30 iterations, IERR is set to zero.
C. Applicability and Restrictions.
To determine the eigenvalues and eigenvectors of a full symmetric matrix, TQL2 should be preceded by TRED2 (F278) to provide a suitable symmetric tridiagonal matrix for TQL2.
469
7ol-275
To determine the eigenvalues and eigenvectors of a complex Hermitian matrix, TQL2 should be preceded by HTRIDI (F284) to provide a suitable real symmetric tridiagonal matrix for TQL2, and the input array Z to TQL2 should be initialized to the identity matrix. TQL2 should then be followed by HTRIBK (F285) to back transform the eigenvectors from TQL2 into those of the original matrix.
TQL2 does not perform well on matrices whose successive row sums vary widely in magnitude and are not strictly increasing from the first to the last row. The subroutine IMTQL2 (F292) is not sensitive to such row sums and is therefore recommended for symmetric tridiagonal matrices whose structure is not known.
3. DISCUSSION OF METHOD AND ALGORITHM.
The eigenvalues are determined by the QL method. The essence of this method is a process whereby a sequence of symmetric tridiagonal matrices, unitarily similar to the original symmetric tridiagona! matrix, is formed which converges to a diagonal matrix. The rate of convergence of this sequence is improved by shifting the origin at each iteration. Before the iterations for each eigenvalue, the symmetric tridiagonal matrix is checked for a possible splitting into submatrices. If a splitting occurs, only the uppermost submatrix participates in the next iteration. The similarity transformations used in each iteration are accumulated in the Z array, producing the orthonormal eigenvectors for the original matrix. Finally, the eigenvalues are ordered in ascending order and the eigenvectors are ordered consistently.
The origin shift at each iteration is the eigenvalue of the current uppermost 2x2 principal minor closer to the first diagonal element of this minor. Whenever the uppermost Ixl principal submatrix finally splits from the rest of the matrix, its element is taken to be an eigenvalue of the original matrix and the algorithm proceeds with the remaining submatrix. This process is continued until the matrix has split completely into submatrices of order I. The tolerances in the splitting tests are proportional to the relative machine precision.
This subroutine is a translation of the Algol procedure TQL2 written and discussed in detail by Bowdler, Martin, Reinsch, and Wilkinson (I).
470
7.1-276
4. REFERENCES.
i) Bowdler, H., Martin, R.S., Reinsch, C., and Wilkinson, J.H., The QR and QL Algorithms for Symmetric Matrices, Num. Math. 11,293-306 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution II/3, 227-240, Springer-Verlag, 1971.)
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for complex Hermitian, real symmetric, real symmetric tridiagonal, and certain real non-symmetric tridiagonal matrices.
B. Accuracy.
The subroutine TQL2 is numerically stable (i); that is, the computed eigenvalues are close to those of the original matrix. In addition, they are the exact eigenvalues of a matrix close to the original real symmetric tridiagonal matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.
471
7.1-277
C
C
C
SUBROUTINE TQL2(NM,N,D,E,Z,IERR)
INTEGER I,J,K,L,M,N, II,LI,NM,MML,IERR
REAL D(N),E(N),Z(NM,N)
REAL B,C,F,G,H,P,R,S,MACHEP REAL SQRT,ABS,SIGN
********** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING
THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.
**********
MACHEP = ?
IERR = 0
IF (N .EQ. I) GO TO i001
DO I00 1 = 2, N 100 E(I-t) = E(I)
F = 0.0 B = 0.0
E(N) = 0.0
ii0
DO 240 L = I, N
J = 0
H = MACHEP * (ABS(D(L)) + ABS(E(L))) IF (B .LT. H) B = H
• ********* LOOK FOR SMALL SUB-DIAGONAL ELEMENT **********
DO Ii0 M = L, N
IF (ABS(E(M)) .LE. B) GO TO 120 • ********* E(N) IS ALWAYS ZERO, SO THERE IS NO EXIT
THROUGH THE BOTTOM OF THE LOOP **********
CONTINUE
120 130
IF (M .EQ. L) GO TO 220
IF (J .EQ. 30) GO TO i000
J = J + i ********** FORM SHIFT **********
L1 = L + i G = D (L) P = (D(LI) -G) / (2.0 * E(L))
R = SQRT(P*P+I.0) D(L) = E(L) / (P + SIGN(R,P))
H = G - D(L)
140 DO 140 I = LI, N O(1) = D(1) - H
F = F + H ********** QL TRANSFORMATION **********
P = D (M)
C : 1.0 S = 0 . 0
MML = M - L
472
O3
I'o
O0
0 ff'~
t~
t~
~ ~.
.~
0 0
.-~
.-
"~
~.'~
~ ~
II o
tl I!
~ II
H
•
II
II -
w
I-4
~--.
~'
0 0 0
OX
0
0
0 0
0 II
II II
0
II 11
0
~ M
H
~;I
tZl
c~
t:~
~..~
~ I
II
2 ""
O
~ f'
~ c3
.~
I..o
o 00
o
o o
o
~,'
0
~ H
,-',
~'
J ,"
,, •
--- -
0
0"~
C~
0 .,-
-.
I~
L'~
"..-
/ h~
i >d
-I
- "-
-"
;'l-J
• H C
~
I--I
C~
0 r,~
0 0 0 LO
O
0 0
x-.
0 0
x..
~.~
x..H
~ ~
~::;q
II
o~i
",..~
~
- 0
~'-~
[;~
n
l:~
. ~
, ii
v~
<:~
i---i
~'~
~ I
L'q
~-
I ~-"
It It
II t-
-I
II II
il I|
H II
II
r.~
c~
,.-.~
0~
~s
'~ "
.-~
~... ~
"~'o
~
o
" i-I
0 0 0
0 o II
I! II
o
c~
~ :~
I
II
H
X-,
0 tl ! I t~
0 I !
? ..j
00
7.1-279
C
300 CONTINUE
C
GO TO i001
C ********** SET ERROR -- NO CONVERGENCE TO AN
C EIGENVALUE AFTER 30 ITERATIONS **********
i000 IERR = L
i001 RETURN
END
474
7. 1-280
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F279-2 TRBAKI
A Fortran IV Subroutine to Back Transform the Eigenvectors of that Symmetric Tridiagonal Matrix Determined by TREDI.
May, 1972 July, 1975
i. PURPOSE.
The Fortran IV subroutine TRBAKI forms the eigenvectors of a real symmetric matrix from the eigenvectors of that symmetric tridiagonal matrix determined by TREDI (F277).
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE TRBAKI(NM,N,A,E,M,Z)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays A and Z as specified in the DIMENSION statements for A and Z in the calling program.
is an integer input variable set equal to the order of the matrix. N must be not greater than NM.
is a working precision real input two- dimensional variable with row dimension NM and column dimension at least N. The strict lower triangle of A contains some information about the orthogonal transformations used in the reduction to the tridiagonal form. The remaining upper part of the matrix is arbitrary. See section 3 of F277 for the details.
475
7.1-281
is a working precision real input one- dimensional variable of dimension at least N containing, in its last N-I positions, the subdiagonal elements of the tridiagonal matrix. The element E(1) is arbitrary. These elements serve to provide the remaining information about the orthogonal transformations.
is an integer input variable set equal to the number of columns of Z to be back transformed.
is a working precision real two-dimensional variable with row dimension NM and column dimension at least M. On input, the first M columns of Z contain the eigenvectors to be back transformed. On output, these columns of Z contain the transformed eigenvectors. The transformed eigenvectors are orthonormal if the input eigenvectors are orthonormal.
B. Error Conditions and Returns~
None~
C. Applicability and Restrictions~
This subroutine should be used in conjunction with the subroutine TREDI (F277).
3. DISCUSSION OF METHOD AND ALGORITHM.
Suppose that the symmetric matrix C to the tridiagonal symmetric matrix transformation
(say) has been reduced F by the similarity
T F = Q CQ
where Q is a product of the orthogonal symmetric matrices encoded in E and in the strict lower triangle of A. Then, given an array Z of column vectors, TRBAKI computes the matrix product QZ. If the eigenvectors of F are columns of the array Z, then TRBAKI forms the eigenvectors of C in their place. Since Q is orthogonal, vector Euclidean norms are preserved.
476
7.1-282
This subroutine is a translation of the Algol procedure TRBAKI written and discussed in detail by Martin, Reinsch, and Wilkinson (I).
4. REFERENCES.
l) Martin, R.S., Reinsch, C., and Wilkinson, J.H., Householder's Tridiagonalization of a Symmetric Matrix, Num. Math. 11,181-195 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution II/2, 212-226, Springer-Verlag, 1971.)
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for real symmetric matrices.
B. Accuracy.
The accuracy of TRBAKI can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real symmetric matrices and matrix systems. In these paths, this subroutine is numerically stable (I). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix or system close to the original matrix or system and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix or system.
477
7.1-283
SUBROUTINE TRBAKI(NM,N,A,E,M,Z)
INTEGER I,J,K,L,M,N,NM REAL A(NM,N), E (N), Z (NM,M) REAL S
IF (M .EQ. 0) GO TO 200 IF (N .EQ. i) GO TO 200
DO 140 I = 2~ N L = I - 1 IF (E(I) .EQ. 0.0) GO TO 140
DO 130 J = I, M S=Oo0
Ii0 DO Ii0 K = i, L
s = s + A(I~K) * Z(K,J) • ********* DIVISOR BELOW IS NEGATIVE OF H FORMED IN TREDI.
DOUBLE DIVISION AVOIDS POSSIBLE UNDERFLOW **********
S = (S / A ( i , L ) ) / E ( I )
120 DO 120 K = i, L Z(K,J) = Z(K,J) + S * A(I,K)
130 CONTINUE
140 CONTINUE
200 RETURN
END
478
7.1-284
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F229 TRBAK3
A Fortran IV Subroutine to Back Transform the Eigenvectors of that Symmetric Tridiagonal Matrix Determined by TRED3.
July, 1975
i. PURPOSE.
The Fortran IV subroutine TRBAK3 forms the eigenvectors of a real symmetric matrix from the eigenvectors of that symmetric tridiagonal matrix determined by TRED3 (F228).
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE TRBAK3(NM,N,NV,A,M,Z)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional array Z as specified in the DIMENSION statement for Z in the calling program.
N is an integer input variable set equal to the order of the matrix. N must be not greater than NM.
NV is an integer input variable set equal to the dimension of the array A as specified in the DIMENSION statement for A in the calling program. NV must be not less than N* (N+I) 12.
A is a working precision real input one- dimensional variable of dimension at least N*(N+I)/2 containing information about the orthogonal transformations used in the reduction to the tridiagonal form. See section 3 of F228 for the details.
479
7.1-285
M is an integer input variable set equal to the number of columns of Z to be back transformed.
is a working precision real two-dimensional variable with row dimension NM and column dimension at least M. On input, the first M columns of Z contain the eigenvectors to be back transformed. On output, these columns of Z contain the transformed eigenvectors. The transformed eigenvectors are orthonormal if the input eigenvectors are orthonormal.
B. Error Conditions and Returns~
None.
C. Applicability and Restrictions.
This subroutine should be used in conjunction with the subroutine TRED3 (F228).
3~ DISCUSSION OF METHOD AND ALGORITHM.
Suppose that the symmetric matrix C to the tridiagonal symmetric matrix transformation
(say) has been reduced F by the similarity
T F = Q CQ
where Q is a product of the orthogonal symmetric matrices encoded in A. Then, given an array Z of column vectors, TRBAK3 computes the matrix product Qz. If the eigenvectors of F are columns of the array Z, then TRBAK3 forms the eigenvectors of C in their place. Since Q is orthogonal, vector Euclidean norms are preserved.
This subroutine is a translation of the Algol procedure TRBAK3 written and discussed in detail by Martin, Reinsch, and Wilkinson (I).
480
7.1-286
4. REFERENCES.
1) Martin, R.S., Reinsch, C., and Wilkinson, J.H., Householder's Tridiagonalization of a Symmetric Matrix, Num. Math. 11,181-195 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/2, 212-226, Springer-Verlag, 1971.)
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for real symmetric packed matrices.
B. Accuracy.
The accuracy of TRBAK3 can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real symmetric packed matrices. In these paths, this subroutine is numerically stable (i). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.
481
41
O0
I'O
0 0 0 0
0 0
bo
0 C
) 0
0
.,-~
~:~
~ 0
II ! N..
H
C~
II
~a
C~
0
~'- C')
~'0
~
.~
tJ
0 t~
0~
0 t~
D~
0
C~
0
0 ~
II 0
I---I ~
II
C~
~"~°
~I
II
t,~
C~
H
H
II 11
0
U II
" °
Hk
.~
b~
0 0
0 0
O0
O0
O
0
~t
n
v~
H
ba
Z
C3
c~
t~
0 t"z~
t~
N
'7
7.1-288
NATS' PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F277-2 TREDI
A Fortran IV Subroutine to Reduce a Real Symmetric Matrix to a Symmetric Tridiagonal Matrix Using
Orthogonal Transformations.
May, 1972 July, 1975
i. PURPOSE.
The Fortran IV subroutine TREDI reduces a real symmetric matrix to a symmetric tridiagonal matrix using orthogonal similarity transformations. This reduced form is used by other subroutines to find the eigenvalues and/or eigenvectors of the original matrix. See section 2C for the specific routines.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE TREDI(NM,N,A,D,E,E2)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional array A as specified in the DIMENSION statement for A in the calling program.
N is an integer input variable set equal to the order of the matrix A. N must be not greater than NM.
A is a working precision real two-dimensional variable with row dimension NM and column dimension at least N. On input, A contains the symmetric matrix of order N to be reduced to tridiagonal form. Only the full lower triangle of the matrix need be
483
7. 1 -289
E2
supplied. On output, the strict lower triangle of A contains information about the orthogona! transformations used in the reduction. The full upper triangle of A is unaltered. See section 3 for the details.
is a working precision real output one- dimensional variable of dimension at least N containing the diagonal elements of the tridiagonal matrix.
is a working precision real output one- dimensional variable of dimension at least N containing, in its last N-I positions, the subdiagonal elements of the tridiagonal matrix. The element E(1) is set to zero.
is a working precision real output one- dimensional variable of dimension at least N containing, in its last N-I positions, the squares of the subdiagonal elements of the tridiagonal matrix. The element E2(1) is set to zero. E2 need not be distinct from E (non-standard usage acceptable with at least those compilers included in the certification statement), in which case no squares are returned.
Bo Error Conditions and Returns.
None.
C. Applicability and Restrictions.
If all the eigenvalues of the original matrix are desired, this subroutine should be followed by TQLI (F289), IMTQLI (F291), or TQLRAT (F235).
If some of the eigenvalues of the original matrix are desired, this subroutine should be followed by BISECT (F294) or TRIDIB (F237).
If some of the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by TSTURM (F293), or by BISECT (F294) and TINVIT (F223), or by TRIDIB (F237) and TINVIT, or by IMTQLV (F234) and TINVIT, and then by TRBAKI (F279).
484
7.1-290
If all the eigenvalues and eigenvectors of the original matrix are desired, subroutine TRED2 (F278) should be used rather than TREDI to perform the tridiagonal reduction, and should be followed by TQL2 (F290) or IMTQL2 (F292).
If the matrix has elements of widely varying magnitudes, the smaller ones should be in the top left-hand corner.
3. DISCUSSION OF METHOD AND ALGORITHM.
The tridiagonal reduction is performed in the following way. Starting with J=N, the elements in the J-th row to the left of the diagonal are first scaled, to avoid possible underflow in the transformation that might result in severe departure from orthogonality. The sum of squares SIGMA of these scaled elements is next formed. Then, a vector U and a scalar
T H -- U U/2
define an operator
T P = I - UU /H
which is orthogonal and symmetric and for which the similarity transformation PAP eliminates the elements in the J-th row of A to the left of the subdiagonal and the symmetrical elements in the J-th column.
The non-zero components of U are the elements of the J-th row to the left of the diagonal with the last of them augmented by the square root of SIGMA prefixed by the sign of ~ the subdiagonal element. By storing the transformed subdiagonal element in E(J) and not overwriting the row elements eliminated in the transformation, full information about P is saved for later u~e in YRBAKI.
The transformation sets E2(J) equal to SIGMA and E(J) equal to the square root of SIGMA prefixed by sign opposite to that of the replaced subdiagonal element.
The above steps are repeated on further rows of the transformed A in reverse order until A is reduced to tridiagonal form; that is, repeated for J = N-I,N-2,...,3.
Only the elements in the lower triangle of A are accessed, and although the diagonal elements are modified in the algorithm, they are restored to their original contents by the end of the subroutine, thus preserving the full upper triangle of A.
4 8 5
7.1-291
This subroutine is a translation of the Algol procedure TREDI written and discussed in detail by Martin~ Reinsch, and Wilkinson (I).
4. REFERENCES°
I) Martin, R~S°~ Reinsch, C.~ and Wilkinson~ J.H., Householder's Tridiagonalization of a Symmetric Matrix, Num. Math. 11,181-195 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, Jo H. Wilkinson - C. Reinsch, Contribution II/2, 212-226, Springer-Verlag~ 1971.)
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for real symmetric matrices.
B. Accu~acyo
The accuracy of TREDI can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real symmetric matrices and matrix systems. In these paths, this subroutine is numerically stable (I). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix or system close to the original matrix or system and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix or system.
486
7.1-292
SUBROUTINE TREDI(NM,N,A,D,E,E2)
INTEGER I,J,K,L,N,II,NM,JPI
REAL A(NM,N),D(N),E(N),E2(N)
REAL F,G,H,SCALE
REAL SQRT,ABS,SIGN
DO i00 1 = i, N
I00 D(I) = A(I,I)
C ********** FOR I=N STEP -i UNTIL 1 DO -- ********** DO 300 II = i, N
I = N + 1 - II
L = I - i
H=0.0
SCALE = 0.0
IF (L .LT. i) GO TO 130
C ********** SCALE ROW (ALGOL TOL THEN NOT NEEDED) ********** DO 120 K = i, L
120 SCALE = SCALE + ABS(A(I,K))
130 IF (SCALE .NE. 0.0) GO TO 140 E(I) -- 0.0
E2(1) = 0.0
GO TO 290
140
150
DO 150 K = i, L
A(!,K) = A(I,K) / SCALE
H = H + A(I,K) * A(I,K) CONTINUE
E2(I) = SCALE * SCALE * H
F = A(I,L)
G = -SIGN(SQRT(H),F)
E(1) = SCALE * G
H = H - F * G
A(I,L) = F - G
IF (n .EQ. I) GO TO 270
F = 0.0
180
DO 240 J = i, L
G = 0.0
********** FORM ELEMENT OF A*U **********
DO 180 K = I, J
C = C + A(J,K) * A(I,K)
JPI = J + i
IF (L .LT. JPI) GO TO 220
DO 200 K = JPI, L
200 G = G + A(K,J) * A(I,K)
• ********* FORM ELEMENT OF P ********** 220 E(J) = G / H
F = F + E(J) * A(I,J) 240 CONTINUE
487
7.1-293
C
C
H = F / (~ + H)
********** FORM REDUCED A **********
DO 260 J = I, L
F = A(I,J)
G = E(J) - H * F
E(J) = G
260
DO 260 K = i, J
A(J,K) = A(J,K) - F * E(K) - G * A(I,K)
CONTINUE
270
280
DO 280 K = I, L
A(I,K) = SCALE * A(I,K)
290 H = D(i)
D(I) = A(I,I)
A(I,I) =
300 CONTINUE
RETURN
END
488
7.1-294
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F278-2 TRED2
A Fortran IV Subroutine to Reduce a Real Symmetric Matrix to a Symmetric Tridiagonal Matrix Accumulating the
Orthogonal Transformations.
May, 1972 July, 1975
i. PURPOSE.
The Fortran IV subroutine TRED2 reduces a real symmetric matrix to a symmetric tridiagonal matrix using and accumulating orthogonal similarity transformations. This reduced form and the transformation matrix are used by subroutine TQL2 (F290) or IMTQL2 (F292) to find the eigenvalues and eigenvectors of the original matrix.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE TRED2(NM,N,A,D,E,Z)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional arrays A and Z as specified in the DIMENSION statements for A and Z in the calling program.
is an integer input variable set equal to the order of the matrix A. N must be not greater than NM.
489
7.1-295
is a working precision real input two- dimensional variable with row dimension NM and column dimension at least N. A contains the symmetric matrix of order N to be reduced to tridiagonal form. Only the full lower triangle of the matrix need be supplied.
is a working precision real output one- dimensional variable of dimension at least N containing the diagonal elements of the tridiagonal matrix.
is a working precision real output one- dimensional variable of dimension at least N containing~ in its last N-I positions, the subdiagonal elements of the tridiagonal matrix. The element E(1) is set to zero.
is a working precision real output two- dimensional variable with row dimension and column dimension at least N. It contains the orthogonal transformation matrix produced in the reduction to the tridiagonal form.
NM
Be Error Conditions and Returns°
None.
C. Applicability and Restrictions.
If all the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by TQL2 (F290) or IMTQL2 (F292).
If some other combination of eigenvalues and eigenvectors is desired, subroutine TREDI (F277) should be used rather than TRED2 to perform the tridiagonal reduction.
If the matrix has elements of widely varying magnitudes, the smaller ones should be in the top left-hand corner.
Parameters A and Z need not be distinct.
490
7.1-296
3. DISCUSSION OF METHOD AND ALGORITHM.
The lower triangle of A is initially copied into Z and all subsequent operations are performed on Z.
The tridiagonal reduction is performed in the following way. Starting with J=N, the elements in the J-th row to the left of the diagonal are first scaled, to avoid possible underflow in the transformation that might result in severe departure from orthogonality. The sum of squares SIGMA of these scaled elements is next formed. Then, a vector U and a scalar
T H = U U/2
define an operator
T P = I - UU /H
which is orthogonal and symmetric and for which the ° °
slmllarmty transformation PAP eliminates the elements in the J-th row of A to the left of the subdiagonal and the symmetrical elements in the J-th column.
The non-zero components of U are the elements of the J-th row to the left of the diagonal with the last of them augmented by the square root of SIGMA prefixed by the sign of the subdiagonal element. By storing the transformed subdiagonal element in E(J) and not overwriting the row elements eliminated in the transformation, full information about P is saved for later accumulation of transformations.
The transformation sets E(J) equal to the square root of SIGMA prefixed by sign opposite to that of the replaced subdiagonal element.
The above steps are repeated on further rows of the transformed A in reverse order until A is reduced to tridiagonal form; that is, repeated for J = N-I,N-2,...,3.
Finally, the orthogonal transformation matrix is accumulated in Z as the product of the N-2 operators defined in the tridiagonal reduction.
This subroutine is a translation of the Algol procedure TRED2 written and discussed in detail by Martin, Reinsch, and Wilkinson (I).
491
7 . 1 - 2 9 7
4. REFERENCES.
1) Martin, R.S., Reinsch, C., and Wilkinson, J.H., Householder's Tridiagonalization of a Symmetric Matrix, Num. Math. 11,181-195 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/2, 212-226, Springer-Verlag, 1971.)
5~ CHECKOUT.
A. Test Cases~
See the section discussing testing of the codes for real symmetric matrices.
B. Accuracy.
The accuracy of TRED2 can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real symmetric matrices and matrix systems. In these paths, this subroutine is numerically stable (i). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix or system close to the original matrix or system and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix or system.
492
7.1-298
C
SUBROUTINE TRED2(NM,N,A,D,E,Z)
INTEGER I,J,K,L,N, II,NM,JPI
REAL A(NM,N),D(N),E(N),Z(NM,N) REAL F,G,H,HH,SCALE REAL SQRT,ABS,SIGN
DO I00 1 = i, N
DO I00 J = I, I Z(l,J) = A(I,J)
i00 CONTINUE
120
IF (N .EQ. I) GO TO 320
********** FOR I=N STEP -i UNTIL 2 DO -- ********** DO 300 II = 2, N
I = N + 2 - II
L = I - 1 H = 0.0 SCALE = 0.0
IF (L ,LT. 2) GO TO 130
********** SCALE ROW (ALGOL TOL THEN NOT NEEDED) ********** DO 120 K = I, L
SCALE = SCALE + ABS(Z(I,K))
130 IF (SCALE .NE. 0.0) GO TO 140 E(1) = Z(l,L) GO TO 290
140
150
DO 150 K = i, L
Z(I,K) = Z(I,K) / SCALE H = H + Z(I,K) * Z(l,K)
CONTINUE
F = Z(I,L)
G = -SIGN(SQRT(H),F) E(1) = SCALE * G H = H - F * G Z(I,L) = F - G
F = 0.0
180
DO 240 J = I, L Z(J,Z) = Z(I,J) / i
G = 0.0 ********** FORM ELEMENT OF A*U **********
DO 180 K = i, J
G = G + Z(J,K) * Z(I,K)
JPI = J + 1
IF (L .LT. JPI) GO TO 220
200 DO 200 K = JPI, L
G = g + Z(K,J) * Z(I,K)
493
7.1-299
********** FORM ELEMENT OF P **********
220 E(J) = G / H
F = F + E(J) * Z(l,J)
240 CONTINUE
HH = F / (H + H) ********** FORM REDUCED A **********
DO 260 J = I, L
F = Z(I,J)
G = E(J) - HH * F
E(J) = G
260
DO 260 K = i, J
Z(J,K) = Z(J,K) - F * E(K) - G * Z(I,K)
CONTINUE
290 D(1) = H
300 CONTINUE
320 D(1) = 0.0
~(I) = o.o ********** ACCUMULATION OF TRANSFORMATION MATRICES **********
DO 500 I = I, N
L = I - i
IF (D(I) oEQ. 0.0) GO TO 380
DO 360 J = I, L
G=0~0
340
DO 340 K = i, L
G = G + Z(I,K) * Z(K,J)
360
DO 360 K = i, L
Z(K,J) = Z(K,J) - G * Z(K,I)
CONTINUE
380 D(I) = Z(I,I)
Z(I,i) = 1.0 IF (L .LT. I) GO TO 500
400
DO 400 J = I, L
Z(I,J) = 0.0 Z(J,I) = 0.0
CONTINUE
500 CONTINUE
RETURN
END
494
7.1-300
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F228 TRED3
A Fortran IV Subroutine to Reduce a Real Symmetric Matrix, Stored as a One-Dimensional Array, to a Symmetric
Tridiagonal Matrix Using Orthogonal Transformations.
July, 1975
i. PURPOSE.
The Fortran IV subroutine TRED3 reduces a real symmetric matrix, stored as a one-dimensional array, to a symmetric tridiagonal matrix using orthogonal similarity transformations. This reduced form is used by other subroutines to find the eigenvalues and/or eigenvectors of the original matrix. See section 2C for the specific routines.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE TRED3(N,NV,A,D,E,E2)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
N is an integer input variable set equal to the order of the matrix A.
NV is an integer input variable set equal to the dimension of the array A as specified in the DIMENSION statement for A in the calling program. NV must be not less than N* (N+I) 12.
A is a working precision real one-dimensional variable of dimension at least N*(N+I)/2. On input, A contains the lower triangle of the symmetric matrix of order N to be reduced to tridiagonal form, packed row- wise. For example if N=3, A should contain
495
7.1-301
E2
(A(i, I),A(2, i) ,A(2,2) ,A(3, I),A(3,2) ,A(3,3))
where the subscripts for each element refer to the row and column of the element in the standard two-dimensional representation. On output, A contains information about the orthogonal transformations used in the reduction. See section 3 for the details.
is a working precision real output one- dimensional variable of dimension at least N containing the diagonal elements of the tridiagonal matrix.
is a working precision real output one- dimensional variable of dimension at least N containing, in its last N-I positions, the subdiagonal elements of the tridiagonal matrix. The element E(1) is set to zero.
is a working precision real output one- dimensional variable of dimension at least N containing, in its last N-I positions, the squares of the subdiagonal elements of the tridiagonal matrix. The element E2(1) is set to zero. E2 need not be distinct from E (non-standard usage acceptable with at least those compilers included in the certification statement), in which case no squares are returned.
B. Error Conditions and Returns.
None°
C. Applicability and Restrictions.
If all the eigenvalues of the original matrix are desired, this subroutine should be followed by TQLI (F289), IMTQLI (F291), or TQLRAT (F235).
If some of the eigenvalues of the original matrix are desired, this subroutine should be followed by BISECT (F294) or TR!DIB (F237).
If some of the eigenvalues and eigenvectors of the original matrix are desired, this subroutine should be followed by TSTURM (F293), or by BISECT (F294) and TINVIT (F223), or by TRIDIB (F237) and TINVIT, or by IMTQLV (F234) and TINVIT, and then by TRBAK3 (F229).
496
7.1-302
If all the eigenvalues and eigenvectors of the original matrix are desired, subroutine TRED2 (F278) should be used rather than TRED3 to perform the tridiagonal reduction, and should be followed by TQL2 (F290) or IMTQL2 (F292). In this case, the packed form of the matrix cannot be used, but the eigenvectors can share the space required for the matrix.
If the matrix has elements of widely varying magnitudes, the smaller ones should be at the top.
3. DISCUSSION OF METHOD AND ALGORITHM.
Discussion of the algorithm is facilitated if the matrix is considered square. The implementation, however, achieves significant storage economy by specifying only the lower triangle to be stored and packed one-dimensionally.
The tridiagonal reduction is performed in the following way. Starting with J=N, the elements in the J-th row to the left of the diagonal are first scaled, to avoid possible underflow in the transformation that might result in severe departure from orthogonality. The sum of squares SIGMA of these scaled elements is next formed. Then, a vector U and a scalar
T H = u u/2
define an operator
T P = I -UU /H
which is orthogonal and symmetric and for which the similarity transformation PAP eliminates the elements in the J-th row of A to the left of the subdiagonal and the symmetrical elements in the J-th column.
The non-zero components of U are the elements of the J-th row to the left of the diagonal with the last of them augmented by the square root of SIGMA prefixed by the sign of the subdiagonal element. By storing the transformed subdiagonal element in E(J) and not overwriting the row elements eliminated in the transformation, full information about P is saved for later use in TRBAK3.
The transformation sets E2(J) equal to SIGMA and E(J) equal to the square root of SIGMA prefixed by sign opposite to that of the replaced subdiagonal element.
497
7.1-303
The above steps are repeated on further rows of the transformed A in reverse order until A is reduced to tridiagonal form~ that is, repeated for J = N-I,N-2,...,3o
This s~broutine is a translation of the Algol procedure TRED3 written and discussed in detail by Martin, Reinsch, and Wilkinson (i).
4. REFERENCES°
i) Martin~ R~So, Reinsch, C.~ and Wilkinson, J.H., Householder's Tridiagonalization of a Symmetric Matrix, Num. Math. 11,181-195 (1968). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, Jo H~ Wilkinson - C. Reinsch, Contribution 11/2, 212-226, Springer-Verlag, 1971.)
5. CHECKOUT~
A. Test Cases~
See the section discussing testing of the codes for real symmetric packed matrices.
B. Accuracy°
The accuracy of TRED3 can best be described in terms of its role in those paths of EISPACK which find eigenvalues and eigenvectors of real symmetric packed matrices. In these paths, this subroutine is numerically stable (I). This stability contributes to the property of these paths that the computed eigenvalues are the exact eigenvalues of a matrix close to the original matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.
498
7.1-304
C
120
130
140
150
180
SUBROUTINE TRED3(N,NV,A,D,E,E2)
INTEGER I,J,K,L,N,II,IZ,JK,NV
REAL A(NV), D (N), E (N), E2 (N) REAL F,G,H,HH,SCALE
REAL SQRT,ABS,SIGN
********** FOR I=N STEP -I UNTIL 1 DO -- ********** DO 300 II = i, N
I = N + i - II L = I - 1 I Z = ( I * L ) / 2 H = 0.0 SCALE = 0.0
IF (L .LT. i) GO TO 130
********** SCALE ROW (ALGOL TOL THEN NOT NEEDED) ********** DO 120 K = I, L
IZ = IZ + 1 D(K) = A(IZ)
SCALE = SCALE + ABS(D(K)) CONTINUE
IF (SCALE .NE. 0.0) GO TO 140 E(I) = 0.0
E2(1) = 0.0 GO TO 290
DO 150 K = I, L
D(K) = D(K) / SCALE H = H + D(K) * D(K)
CONTINUE
E2(1) = SCALE * SCALE * H F = D (L) G = -SIGN (SQRT (H), F)
E(1) = SCALE * G H = H - F * G D(L) = F - g A(IZ) = SCALE * D(L)
IF (L .EQ. i) GO TO 290 F = 0.0
DO 240 J = i, L G = 0.0
JK = (J * (J-l)) / 2
• ********* FORM ELEMENT OF A*U ********** DO 180 K = i, L
JK = JK + 1
IF (K .GT. J) JK = JK + K - 2 G = G + A(JK) * D(K)
CONTINUE
499
7.1-305
240
********** FORM ELEMENT OF P **********
E(J) = G / H F = F + E(J) * D(J)
CONTINUE
HH = F / (H + H) JK = 0
********** FORM REDUCED A **********
DO 260 J = I, L
F = D(J)
G = E(J) - HH * F
E(J) = G
260
DO 260 K = i, J
JK = JK + 1
A(JK) = A(JK) - F * E(K) - G * D(K)
CONTINUE
290 D(1) = A(IZ+I)
A(IZ+!) = SCALE * SQRT(H)
300 CONTINUE
RETURN
END
500
7.1-306
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F237 TRIDIB
A Fortran IV Subroutine to Determine Some Eigenvalues of a Symmetric Tridiagonal Matrix.
July, 1975
i. PURPOSE.
The Fortran IV subroutine TRIDIB determines those eigenvalues of a symmetric tridiagonal matrix between specified boundary indices using Sturm sequencing.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE TRIDIB(N,EPSI,D,E,E2,LB,UB, MII,M,W, IND,IERR,RV4,RV5)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
is an integer input variable set equal to the order of the matrix.
EPSI is a working precision real variable. On input, it specifies an absolute error tolerance for the computed eigenvalues. If the input EPSI is non-positive, it is reset to a default value described in section 2C.
D is a working precision real input one- dimensional variable of dimension at least N containing the diagonal elements of the symmetric tridiagonal matrix.
is a working precision real input one- dimensional variable of dimension at least N containing, in its last N-I positions, the subdiagonal elements of the symmetric tridiagonal matrix. E(1) is arbitrary.
501
7,1-307
E2 is a working precision real one-dimensional variable of dimension at least N. On input, the last N-I positions in this array contain the squares of the subdiagonal elements of the symmetric tridiagonal matrix. E2(1) is arbitrary. On output, E2(1) is set to zero. If any of the elements in E are regarded as negligible, the corresponding elements of E2 are set to zero, and so the matrix splits into a direct sum of submatriceso
LB,UB are working precision real output variables set to the lower and upper endpoints, respectively, of an interval containing exactly the desired eigenvalues. See section 2C for further details.
MII is an integer input variable specifying the lower index of the set of desired (smallest) eigenvalues.
M is an integer input variable specifying the number of eigenvalues desired. The upper index, M22, of the set is then obtained internally as M22=MII+M-I.
W is a working precision real output one- dimensional variable of dimension at least M containing the M eigenvalues of the symmetric tridiagonal matrix between boundary indices MII and M22. The eigenvalues are in ascending order in W.
IND is an integer output one-dimensional variable of dimension at least M containing the submatrix indices associated with the corresponding M eigenvalues in W. Eigenvalues belonging to the first submatrix have index i, those belonging to the second submatrix have index 2, etc.
IERR is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
RV4,RV5 are working precision real temporary one- dimensional variables of dimension at least N used to hold the lower and upper bounds for the eigenvalues in the bisection process.
502
7.1-308
B. Error Conditions and Returns.
If exactly multiple eigenvalues prevent the determination of an appropriate LB, TRIDIB terminates with no eigenvalues computed, and IERR is set to 3*N+I. In this case, the returned values of LB and UB define the Gerschgorin interval containing all the eigenvalues of the matrix.
If, after determining LB, exactly multiple eigenvalues prevent the determination of an appropriate UB, TRIDIB terminates with no eigenvalues computed, and IERR is set to 3"N+2. In this case, the returned value of UB is the upper bound for the Gerschgorin interval containing all the eigenvalues of the matrix.
If neither of the above error conditions occurs, IERR is set to zero.
C. Applicability and Restrictions.
To determine some of the eigenvalues of a full symmetric matrix, TRIDIB should be preceded by TREDI (F277) to provide a suitable symmetric tridiagonal matrix for TRIDIB.
To determine some of the eigenvalues of a complex Hermitian matrix, TRIDIB should be preceded by HTRIDI (F284) to provide a suitable real symmetric tridiagonal matrix for TRIDIBo
Some of the eigenvalues of certain non-symmetric tridiagonal matrices can be computed using the combination of FIGI (F280) and TRIDIB. See F280 for the description of this special class of matrices. For these matrices, TRIDIB should be preceded by FIGI to provide a suitable symmetric matrix for TRIDIB.
To determine eigenvectors associated with the computed eigenvalues, TRIDIB should be followed by TINVIT (F223) and the appropriate back transformation subroutine -- TRBAKI (F279) after TREDI, HTRIBK (F285) after HTRIDI, or BAKVEC (F281) after FIGI.
The subroutines TQLI (F289), IMTQLI (F291), and TQLRAT (F235) determine all the eigenvalues of a symmetric tridiagonal matrix faster than TRIDIB determines 25 percent of them. Hence~ if more than 25 percent of them are desired, it is recommended that TQLI, IMTQLI, or TQLRAT be used.
503
7 . 1 - 3 0 9
If it is preferred to specify the interval (LB,UB) be searched for eigenvalues rather than the boundary indices MII and M22, use subroutine BISECT (F294) instead.
to
The precision of the computed eigenvalues is controlled through the parameter EPSI. To obtain eigenvalues accurate to within a certain absolute error, EPSI should be set to that error. In particular, if MACHEP denotes the relative machine precision~ then to obtain the eigenvalues to an accuracy commensurate with small relative perturbations of the order of MACHEP in the matrix elements, it is enough for most tridiagonal matrices that EPSI be approximately MACHEP times a norm of the matrix. But some matrices require a smaller EPSI for this accuracy, perhaps as small as MACHEP times the eigenvalue of smallest magnitude in (LB,UB). Note, however, that if EPSI is smaller than required, TRIDIB will perform unnecessary bisection steps to determine the eigenvalues. For further discussion of EPSI, see reference (i).
If the input EPSI is non-positive, TRIDIB resets it, for each submatrix, to -MACHEP times the l-norm of the submatrix and uses its magnitude. This value is tentatively considered adequate for computing the eigenvalues to an accuracy commensurate with small relative perturbations of the order of MACHEP in the matrix elements.
3. DISCUSSION OF METHOD AND ALGORITHM.
The eigenva!ues are determined by the method of bisection applied to the Sturm sequence.
The calculations proceed as follows. First, the subdiagonal elements are tested for negligibility. If an element is considered negligible, its square is set to zero, and so the matrix splits into a direct sum of submatrices. At the same time, the Gerschgorin interval known to contain all the eigenvalues of the matrix is determined. Then, an interval (LB,UB) is determined, using a bisection process proceeding from the Gerschgorin bounds, that contains exactly eigenvalues MII through M22.
Next, a submatrix is examined for its eigenvalues in the interval (LB,UB). Its Gerschgorin interval is determined and used to refine the interval (LB,UB). If the input EPSI is non-positive, it is reset to the default value described in section 2C. Then, subintervals, each enclosing an eigenvalue in (LB,UB), are shrunk using a bisection process
504
7.1-310
until the endpoints of each subinterval are close enough to be accepted as an eigenvalue of the submatrix. Here the endpoints of each subinterval are close enough when they differ by less than MACHEP times twice the sum of the magnitudes of the endpoints plus the absolute error tolerance EPSI.
The submatrix eigenvalues are then merged with previously found eigenvalues into an ordered set.
The above steps are repeated on each submatrix until all the eigenvalues between boundary indices MII and M22 are computed.
This subroutine is a translation of the Algol procedure BISECT written and discussed in detail by Barth, Martin, and Wilkinson (I). A similar Algol procedure TRISTURM is discussed in detail by Peters and Wilkinson (2); a subset of it has been translated as subroutine BISECT (F294).
4. REFERENCES.
i) Barth, W., Martin, R.S., and Wilkinson, J.H., Calculation of the Eigenvalues of a Symmetric Tridiagonal Matrix by the Method of Bisection, Num. Math. 9,386-393 (1967). (Reprinted in Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/5, 249-256, Springer-Verlag, 1971.)
2) Peters, G. and Wilkinson, J.H., The Calculation of Specified Eigenvectors by Inverse Iteration, Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/18, 418-439, Springer-Verlag, 1971.
5. CHECKOUT.
A. Test Cases.
See the section discussing testing of the codes for complex Hermitian, real symmetric, real symmetric tridiagonal, and certain real non-symmetric tridiagonal matrices.
505
7.1-311
B. Accuracy~
The subroutine TRIDIB is numerically stable (1,2); that is, the computed eigenvalues are close to those of the original matrix. In addition, they are the exact eigenvalues of a matrix close to the original real symmetric tridiagonal matrix.
506
7.1-312
SUBROUTINE TRIDIB(N,EPSI,D,E,E2,LB,UB,MII,M,W,IND,IERR,RV4,RV5)
INTEGER I,J,K,L,M,N,P,Q,R,S,II,MI,M2,MII,M22,TAG,IERR,ISTURM
REAL D(N),E(N),E2(N),W(M),RV4(N),RV5 (N)
REAL U,V,LB,TI~T2,UB,XU,X0,XI,EPSI,MACHEP
REAL ABS,AMAXI,AMINI,FLOAT
INTEGER lED(M)
********** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING
THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.
MACHEP = ?
IERR = 0
TAG = 0
XU = D(1)
X0 = D(i)
U = 0.0
********** LOOK FOR SMALL SUB-DIAGONAL ENTRIES AND DETERMINE AN
INTERVAL CONTAINING ALL THE EIGENVALUES ********** DO 40 I = I, N
XI = U
U = 0.0
IF (I .NE. N) U = ABS(E(I+I))
XU = AMINI(D(1)-(XI+U),XU)
X0 = AMAXI(D(1)+(XI+U),X0)
IF (I .EQ. I) GO TO 20
IF (ABS(E(1)) .GT. MACHEP * (ABS(D(1)) + ABS(D(I-I))))
X GO TO 40
20 E2(1) = 0.0
40 CONTINUE
XI = AMAXI(ABS(XU),ABS(X0)) * MACHEP * FLOAT(N)
XU = XU - XI
TI = XU
X0 = X0 + X1
T2 = X0
• ********* DETERMINE AN INTERVAL CONTAINING EXACTLY
THE DESIRED EIGENVALUES ********** P = i
Q = N
M1 = MII - i
IF (MI .EQ. 0) GO TO 75
ISTURM = i
50 V = XI
Xl = (XU + X0) * 0.5
IF (XI .EQ. V) GO TO 980
GO TO 320
60 IF (S - MI) 65, 73, 70
65 XU = XI
GO TO 50
70 X0 = X1
GO TO 50
507
7. 1-313
73 XU = X1
T1 = X1 75 M22 = M1 + M
IF (M22 .EQo N) GO TO 90
X0 = T2
ISTURM = 2 GO TO 50
80 IF (S - M22) 65, 85, 70
85 T2 = XI
90 Q = 0 R = 0 ********** ESTABLISH AND PROCESS NEXT SUBMATRIX, REFINING
INTERVAL BY THE GERSCHGORIN BOUNDS **********
i00 IF (R .EQ, M) GO TO i001 TAG = TAG + i
P = Q + i xu = D(P)
XO = D(P)
U = 0o0
DO 120 Q = P, N
X1 = U U = 0.0
V = 0.0 IF (Q .EQ. N) GO TO ii0
U = ABS(E(Q+I)) V = E2(Q+I)
Ii0 XU = AMINI (D (Q) - (Xl+U), xu) x0 = AMAXI(D(Q)+(XI+U),X0) IF (V .EQo 0,0) GO TO 140
120 CONTINUE
140 XI = AMAXI(ABS(XU),ABS(X0)) * MACHEP
IF (EPSI ,LE. 0.0) EPSI = -XI
IF (P .NE. Q) GO TO iS0 • ********* CHECK FOR ISOLATED ROOT WITHIN INTERVAL **********
IF (TI ,GT. D(P) .OR. D(P) .GE. T2) GO TO 940
MI = P M2 = P
RV5 (e) = D(P) GO TO 900
180 XI = XI * FLOAT(Q-P+I)
LB = AMAXI (TI ,XU-XI) UB = AMINI(T2,X0+XI) XI = LB ISTURM = 3 GO TO 320
200 MI = S + 1 X1 = UB I STURM = 4 GO TO 320
220 M2 = S IF (MI .GT. M2) GO TO 940
508
7.1-314
C
C C
C
C
C
********** FIND ROOTS BY BISECTION **********
X0 = UB
ISTURM = 5
DO 240 I = MI, M2 RV5(1) = UB
RV4(1) = LB
240 CONTINUE ********** LOOP FOR K-TH EIGENVALUE
FOR K=M2 STEP -i UNTIL M1 DO -- (-DO- NOT USED TO LEGALIZE COMPUTEE-GO-TO) **********
K = M2 250 XU = LB
********** FOR I=K STEP -i UNTIL MI DO -- **********
DO 260 II = MI, K I = MI + K - II
IF (XU .GE. RV4(1)) GO TO 260
XU = RV4 (I)
GO TO 280
260 CONTINUE
280 IF (XO .GT. RV5(K)) X0 = RV5(K) ********** NEXT BISECTION STEP **********
300 Xl = (XU + X0) * 0.5 IF ((X0 - XU) .LE. (2.0 * MACHEP *
X (ABS(XU) + ABS(X0)) + ABS(EPSI))) GO TO 420
********** IN-LINE PROCEDURE FOR STURM SEQUENCE ********** 320 S = P - 1
U:I.0
325
330
340
DO 340 1 = P, Q
IF (U .NE. 0.0) GO TO 325
V = ABS(E(1)) / MACHEP GO TO 330 V = E2(1) / U
u = D(I) - El - V
IF (U .LT. 0.0) S = S + I CONTINUE
GO TO (60,80,200,220,360), ISTURM ********** REFINE INTERVALS **********
360 IF (S .GE. K) GO TO 400 XU = Xl IF (S .GE. MI) GO TO 380
RV4(MI) = El
GO TO 300 380 RV4(S+I) = XI
IF (RVS(S) .GT. XI) RVS(S) = El
GO TO 300 400 XO = X1
GO TO 300
509
7.1-315
C ********** K-TH EIGENVALUE FOUND **********
420 RV5(K) = X1
K = K - I
IF (K .GE. MI) GO TO 250
C ********** ORDER EIGENVALUES TAGGED WITH THEIR
C SUBMATRIX ASSOCIATIONS **********
900 S = R
R = R + M2 - M1 + 1
J = 1
K = M1
DO 920 L = i, R
IF (J .GT. S) GO TO 910
IF (K .GT. M2) GO TO 940
IF (RV5(K) .GE. W(L)) GO TO 915
905
DO 905 II = J, S
I = L + S - II
W(I+t) = W(I)
!ND(I+I) = IND(1)
CONTINUE
910 W(L) = RV5(K)
IND(L) = TAG
K = K + i
GO TO 920
915 7 = J + I
920 CONTINUE
940 IF (q ~LT. N) GO TO I00
GO TO i001 ********** SET ERROR -- INTERVAL CANNOT BE FOUND CONTAINING
EXACTLY THE DESIRED EIGENVALUES **********
980 IERR = 3 * N + ISTURM
i001LB = TI
UB = T2
RETURN
END
510
7.1-316
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F293-2 TSTURM
A Fortran IV Subroutine to Determine Some Eigenvalues and Eigenvectors of a Symmetric Tridiagonal Matrix.
May, 1972 July, 1975
i. PURPOSE.
The Fortran IV subroutine TSTURM determines those eigenvalues of a symmetric tridiagonal matrix in a specified interval and their corresponding eigenvectors, using Sturm sequencing and inverse iteration.
2. USAGE.
A. Calling Sequence.
The SUBROUTINE statement is
SUBROUTINE TSTURM(NM,N,EPSI,D,E,E2,LB,UB, MM,M,W,Z,IERR,RVI,RV2,RV3, RV4,RV5,RV6)
The parameters are discussed below and the interpretation of working precision for various machines is given in the section discussing certification.
NM is an integer input variable set equal to the row dimension of the two-dimensional array Z as specified in the DIMENSION statement for Z in the calling program.
is an integer input variable set equal to the order of the matrix. N must be not greater than NM.
EPS 1 is a working precision real variable. On input, it specifies an absolute error tolerance for the computed eigenvalues. If MACHEP denotes the relative machine precision, then EPSI should be chosen so that the accuracy of these eigenvalues is
511
7.1-317
E2
LB,UB
MM
commensurate with relative perturbations of the order of MACHEP in the matrix elements. If the input EPSI is non- positive, it is reset to a default value described in section 2C.
is a working precision real input one- dimensional variable of dimension at least N containing the diagonal elements of the symmetric tridiagonal matrix.
is a working precision real input one- dimensional variable of dimension at least N containing, in its last N-I positions, the subdiagonal elements of the symmetric tridiagonal matrix. E(1) is arbitrary.
is a working precision real one-dimensional variable of dimension at least N. On input, the last N-I positions in this array contain the squares of the subdiagonal elements of the symmetric tridiagonal matrix. E2(1) is arbitrary. On output, E2(1) is set to zero. If any of the elements in E are regarded as negligible, the corresponding elements of E2 are set to zero, and so the matrix splits into a direct sum of submatrices.
are working precision real input variables specifying the lower and upper endpoints, respectively, of the interval to be searched for the eigenvalues. If LB is not less than UB, TSTURM computes no eigenvalues or eigenvectors. See section 2C for further details.
is an integer input variable set equal to an upper bound for the number of eigenvalues in the interval (LB,UB).
is an integer output variable set equal to the number of eigenvalues found to lie in the interval (LB,UB).
is a working precision real output one- dimensional variable of dimension at least MM containing the M eigenvalues of the symmetric tridiagonal matrix in the interval (LB,UB). If the matrix does not split into submatrices, the eigenvalues are in ascending order in W. If the matrix does split, the eigenvalues for each submatrix are in ascending order in W.
512
7 .1 -318
is a working precision real output two- dimensional variable with row dimension NM and column dimension at least MM. It contains M orthonormal eigenvectors of the symmetric tridiagonal matrix corresponding to the M eigenvalues in W.
IERR is an integer output variable set equal to an error completion code described in section 2B. The normal completion code is zero.
RVI,RV2,RV3
are working precision real temporary one- dimensional variables of dimension at least N used to store the main diagonal and the two adjacent diagonals of the triangular matrix produced in the inverse iteration process.
RV4,RVS,RV6 are working precision real temporary one- dimensional variables of dimension at least N. RV4 and RV5 hold the lower and upper bounds for the eigenvalues in the bisection process. In addition, RV4 holds the multipliers of the Gaussian elimination step in the inverse iteration process. RV6 holds the approximate eigenvectors in this process.
B. Error Conditions and Returns.
If M exceeds MM, TSTURM terminates with no eigenvalues or eigenvectors computed, and IERR is set to 3*N+I. In this case, the output parameter M is the number of eigenvalues found to lie in (LB,UB).
If more than 5 iterations are required to determine an eigenvector, TSTURM terminates with IERR set to 4*N+R, where R is the index of the eigenvector for which the failure occurs. The eigenvalues and eigenvectors in the W and Z arrays should be correct for indices 1,2,...~R-I.
If M does not exceed MM and all the eigenvectors are determined within 5 iterations, IERR is set to zero.
513
7. 1-319
C. Applicability and Restrictions.
To determine some of the eigenvalues and eigenvectors of a full symmetric matrix, TSTURM should be preceded by TREDI (F277) to provide a suitable symmetric tridiagonal matrix for TSTURM. It should then be followed by TRBAKI (F279) to back transform the eigenvectors from TSTURM into those of the original matrix.
To determine some of the eigenvalues and eigenvectors of a complex Hermitian matrix, TSTURM should be preceded by HTRIDI (F284) to provide a suitable real symmetric tridiagonal matrix for TSTURM. It should then be followed by HTRIBK (F285) to back transform the eigenvectors from TSTURM into those of the original matrix.
Some of the eigenvalues and eigenvectors of certain non- symmetric tridiagonal matrices can be computed using the combination of FIGI (F280), TSTURM, and BAKVEC (F281). See F280 for the description of this special class of matrices. For these matrices, TSTURM should be preceded by FIGI to provide a suitable symmetric matrix for TSTURM. It should then be followed by BAKVEC to back transform the eigenvectors from TSTURM into those of the original matrix.
The interval (LB,UB) is formally half-open, not including the upper endpoint UB. However, because of rounding errors, the true eigenvalues very close to the endpoints of the interval may be erroneously counted or missed.
The input interval (LB,UB) may be refined internally to a smaller interval known to contain all the eigenvalues in (LB,UB). This insures that TSTURM will not perform unnecessary bisection steps to determine the eigenvalues in (LB,UB).
The computation of the eigenvectors by inverse iteration requires that the precision of the eigenvalues be commensurate with small relative perturbations of the order of MACHEP in the matrix elements. For most symmetric tridiagonal matrices, it is enough that the absolute error EPSI in the eigenvalues for which eigenvectors are desired be approximately MACHEP times a norm of the matrix. But some matrices require a smaller EPSI, perhaps as small as MACHEP times the eigenvalue of smallest magnitude in the interval (LB,UB). Note, however, that if EPSI is smaller than necessary, TSTURM will perform unnecessary bisection steps to determine the eigenvalues. For further discussion of EPSI, see reference (2).
514
7.1-320
If the input EPSI is non-positive, TSTURM resets it, for each submatrix, to -MACHEP times the 1-norm of the submatrix and uses its magnitude. This value is considered adequate for most symmetric tridiagonal matrices and is recommended for use generally. If TSTURM terminates with a vector error exit, a smaller EPSI may be more successful.
3. DISCUSSION OF METHOD AND ALGORITHM.
The eigenvalues are determined by the method of bisection applied to the Sturm sequence and the eigenvectors are determined by inverse iteration.
The calculations proceed as follows. First, the subdiagonal elements are tested for negligibility. If an element is considered negligible, its square is set to zero, and so the matrix splits into a direct sum of submatrices. Then, the Sturm sequence for the entire matrix is evaluated at UB and LB giving the number of eigenvalues of the matrix less than UB and LB respectively. The difference is the number of eigenvalues in (LB,UB).
Next, a submatrix is examined for its eigenvalues in the interval (LB,UB). The Gerschgorin interval, known to contain all the eigenvalues, is determined and used to refine the input interval (LB,UB). If the input EPSI is non- positive, it is reset to the default value described in section 2C. Then, subintervals, each enclosing an eigenvalue in (LB,UB), are shrunk using a bisection process until the endpoints of each subinterval are close enough to be accepted as an eigenvalue of the submatrix. Here the endpoints of each subinterval are close enough when they differ by less than MACHEP times twice the sum of the magnitudes of the endpoints plus the absolute error tolerance EPSI.
The eigenvectors of the same submatrix are then computed by inverse iteration. First, the LU decomposition of the submatrix with an approximate eigenvalue subtracted from its diagonal elements is achieved by Gaussian elimination using partial pivoting. The multipliers defining the lower triangular matrix L are stored in the temporary array RV4 and the upper triangular matrix U is stored in the three temporary arrays RVl, RV2, and RV3. Saving these quantities in RVI, RV2, RV3, and RV4 avoids repeating the LU decomposition if further iterations are required. An approximate vector, stored in RV6, is computed starting from an initial vector, and the norm of the approximate vector is compared with a norm of the submatrix to determine whether the growth is sufficient to accept it as an eigenveetor. If this vector is accepted, its Euclidean norm
515
7.1-321
is made I~ If the growth is not sufficient, this vector is used as the initial vector in computing the next approximate vector. This iteration process is repeated at most 5 times.
Eigenvectors computed in the above way corresponding to well- separated eigenvalues of this submatrix will be orthogonal. However, eigenvectors corresponding to close eigenvalues of this submatrix may not be satisfactorily orthogonal. Hence, to insure orthogonal eigenvectors, each approximate vector is made orthogona! to those previously computed eigenvectors whose eigenvalues are close to the current eigenvalue. If the orthogonalization process produces a zero vector, a column of the identity matrix is used as an initial vector for the next iteration.
Identical eigenvalues are perturbed slightly in an attempt to obtain independent eigenvectors. These perturbations are not recorded in the output eigenvalue array W.
The above steps are repeated on each submatrix until all the eigenvalues in the interval (LB,UB) and their corresponding eigenvectors are computed.
This subroutine is a translation of the Algol procedure TRISTURM written and discussed in detail by Peters and Wilkinson (I).
4. REFERENCES.
i) Peters, G. and Wilkinson, J.H., The Calculation of Specified Eigenvectors by Inverse Iteration, Handbook for Automatic Computation, Volume II, Linear Algebra, J. H. Wilkinson - C. Reinsch, Contribution 11/18, 418-439, Springer-Verlag, 1971.
z) Barth, W., Martin, R.S., and Wilkinson, J.H., Calculation of the Eigenvalues of a Symmetric Tridiagonal Matrix by the Method of Bisection, Num. Math. 9,386-393 (1967).
5 . CHECKOUT°
A. Test Cases~
See the section discussing testing of the codes for complex Hermitian, real symmetric, real symmetric tridiagonal, and certain real non-symmetric tridiagonal matrices.
B. Accuracy.
516
7.1-322
The subroutine TSTURM is numerically stable (1,2); that is, the computed eigenvalues are close to those of the original matrix. In addition, they are the exact eigenvalues of a matrix close to the original real symmetric tridiagonal matrix and the computed eigenvectors are close (but not necessarily equal) to the eigenvectors of that matrix.
517
7.1-323
SUBROUTINE TSTURM(NM,N,EPSI,D,E,E2,LB,UB,MM,M,W,Z,
X IERR,RVI,RV2,RV3,RV4,RVS,RV6)
INTEGER I,J,K,M,N,P,Q,R,S,II,IP,JJ,MM,MI,M2,NM,ITS, X !ERK,GROUP,ISTURM REAL D(N),E(N),E2(N),W(MM),Z(NM,MM),
X RVI (N),RV2(N),RV3(N),RV4(N),RV5(N),RV6(N) REAL U,V,LB,TI,T2,UB,UK,XU,X0,XI,EPSI,EPS2,EPS3,EPS4,
X NORM,MACHEP REAL SQRT,ABS,AMAXI,AMINI,FLOAT
********** MACHEP IS A MACHINE DEPENDENT PARAMETER SPECIFYING
THE RELATIVE PRECISION OF FLOATING POINT ARITHMETIC.
**********
MACHEP = ?
IERR = 0
TI = LB
T2 = UB C ********** LOOK FOR SMALL SUB-DIAGONAL ENTRIES **********
DO 40 I = i, N IF (I .EQ. I) GO TO 20 IF (ABS(E(1)) .GT. MACHEP * (ABS(D(1)) + ABS(D(I-I))))
X GO TO 40
20 E2(1) = 0.0 40 CONTINUE
C ********** DETERMINE THE NUMBER OF EIGENVALUES
C IN THE INTERVAL **********
P=I Q = N
XI = UB ISTURM = 1
GO TO 320 60 M = S
XI = LB ISTURM = 2 GO TO 320
80 M = M - S IF (M .GT. MM) GO TO 980
Q = 0
R = 0 C ********** ESTABLISH AND PROCESS NEXT SUBMATRIX, REFINING
C INTERVAL BY THE GERSCHGORIN BOUNDS *****~****
i00 IF (R .EQ. M) GO TO I001 P = Q + I
XU = D ( P )
X0 = D(P) U=O.O
518
7.1-324
C
DO 120 Q = P, N
X1 = U
U = 0.0 V = 0.0 IF (Q .EQ. N) GO TO Ii0
U = ABS (E (Q+I))
v = E2(Q+I) ii0 XU = AMINI(D(Q)-(XI+U),XU)
X0 = AMAXI(D(Q)+(XI+U),X0)
IF (V .EQ. 0.0) GO TO 140 120 CONTINUE
140 Xl = AMAXI(ABS(XU),ABS(XO)) * MACHEP IF (EPSI .LE. 0.0) EPSI =-XI
IF (P .NE. Q) GO TO 180
• ********* CHECK FOR ISOLATED ROOT WITHIN INTERVAL ********** IF (TI .GT. D(P) .OR. D(P) .GE. T2) GO TO 940 R = R + 1
DO 160 I = I, N 160 Z(I,R) = 0.0
W(R) = D(P) Z(P,R) = 1.0
GO TO 940
180 X1 = X1 * FLOAT(Q-P+I) LB = AMAXI(TI,XU-XI)
UB = AMINI(T2,X0+XI) X1 = LB ISTURM = 3
GO TO 320 200 MI = S + i
Xl = UB ISTURM = 4
GO TO 320 220 M2 = S
IF (MI .GT. M2) GO TO 940
• ********* FIND ROOTS BY BISECTION ********** X0 = UB ISTURM = 5
DO 240 I = MI, M2
RV5 (I) = UB RV4(I) = LB
240 CONTINUE
********** LOOP FOR K-TH EIGENVALUE FOR K=M2 STEP -i UNTIL M1 DO --
(-DO- NOT USED TO LEGALIZE COMPUTEE-GO-TO) ********** K = M2
250 XU = LB
519
7.1-325
C
C
C
260
********** FOR I=K STEP -i UNTIL M1 DO -- ********** DO 260 II = M!, K
I = M1 + K - II
IF (XU .GE. RV4(I)) GO TO 260
XU = RV4(1) GO TO 280
CONTINUE
280 IF (XO .GT. RV5(K)) X0 = RV5(K)
********** NEXT BISECTION STEP **********
300 X1 = (XU + X0) * 0.5 IF ((X0 - XU) .LE. (2.0 * MACHEP *
X (ABS(XU) + ABS(X0)) + ABS(EPSI))) GO TO 420
********** IN-LINE PROCEDURE FOR STURM SEQUENCE **********
320 S = P - 1 U=I.0
325
330
340
DO 340 1 = P, Q
IF (U .NE. 0.0) GO TO 325 V = ABS(E(1)) / MACHEP
GO TO 330 V = E2(I) / U U = D(1) - El - V IF (U .LT. 0.0) S = S + i
CONTINUE
GO TO (60,80,200,220,360), !STURM ********** REFINE INTERVALS **********
360 IF (S .GE. K) GO TO 400
XU = X1 IF (S aGE. MI) GO TO 380
RV4(MI) = XI
GO TO 300
380 RV4 (S+I) = X1 IF (RV5(S) .GT. XI) RV5(S) = X1
GO TO 300
400 X0 = X1 GO TO 300
********** K-TH EIGENVALUE FOUND **********
420 RV5 (K) = X1
K = K - 1 IF (K .GE. MI) GO TO 250 ***~****** FIND VECTORS BY INVERSE ITERATION **********
NORM = ABS(D(P)) IP = P + i
DO 500 I = IP, Q 500 NORM = NORM + ABS(D(1)) + ABS(E(1))
520
7.1-326
520
540
560
580
********** EPS2 IS THE CRITERION FOR GROUPING,
EPS3 REPLACES ZERO PIVOTS AND EQUAL
ROOTS ARE MODIFIED BY EPS3,
EPS4 IS TAKEN VERY SMALL TO AVOID OVERFLOW ********** EPS2 = 1.0E-3 * NORM EPS3 = MACHEP * NORM UK = FLOAT (Q-P+I)
EPS4 = UK * EPS3 UK = EPS4 / SQRT(UK)
GROUP = 0 S = P
DO 920 K = MI, M2 R = R + I
ITS = 1 W(R) = RV5(K)
Xl = RV5 (K)
********** LOOK FOR CLOSE OR COINCIDENT ROOTS ********** IF (K .EQ. MI) GO TO 520
IF (XI - X0 .GE. EPS2) GROUP = -i GROUP = GROUP + 1
IF (XI .LE. X0) Xl = X0 + EPS3
********** ELIMINATION WITH INTERCHANGES AND
INITIALIZATION OF VECTOR ********** v=o.o
DO 580 I = P, Q
RV6 (I) = UK
IF (I .EQ. P) GO TO 560
IF (ABS(E(1)) .LT. ABS(U)) GO TO 540 XU = U / E(1) RV4(1) = XU RVI(I-I) = E(I)
RV2(I-I) = D(1) - XI
RV3(I-I) = 0.0
IF (I .NE. Q) RV3(I-I) -- E(I+I) U = V - XU * RV2(I-I) V = -XU * RV3(I-I)
GO TO 580 XU = E(1) / U RV4(1) = XU
RVI(I-I) = U
RV2(I-I) = V
RV3(I-I) = 0.0
u = D(I) - Xl - XU * V
IF (I .NE. Q)V = E(I+I) CONTINUE
IF (U .EQ. 0.0) U = EPS3 RVI (Q) = U
RV2(Q) = 0.0 RV3(Q) = 0.0
521
7.1-327
C ********** BACK SUBSTITUTION
C FOR I=Q STEP -I UNTIL P DO -- ********** 600 DO 620 II = P, Q
I = P + Q - II RV6(1) = (RV6(1) - U * RV2(1) - V * RV3(1)) / RVI(1)
V = U
U = RV6 (I) 620 CONTINUE
C ********** ORTHOGONALIZE WITH RESPECT TO PREVIOUS
C MEMBERS OF GROUP **********
IF (GROUP .EQ. 0) GO TO 700
640
660
C 680
C 700
C
720
740
C C
C
DO 680 JJ = I, GROUP J = R - GROUP - 1 + JJ
XU = 0.0
DO 640 ! = P, Q XU = XU + RV6(1) * Z(I,J)
DO 660 1 = P, Q RV6(1) = RV6(1) - XU * Z(I,J)
CONTINUE
NORM = 0.0
DO 720 1 = P, Q NORM = NORM + ABS(RV6(I))
IF (NORM oGE. 1.0) GO TO 840
********** FORWARD SUBSTITUTION ********** IF (ITS .EQ. 5) GO TO 960
IF (NORM .NE. 0.0) GO TO 740
RV6(S) = EPS4
S = S + 1 IF (S .GT. Q) S = P
GO TO 780 XU = EPS4 / NORM
DO 760 I = P, Q 760 l{V6(I) = RV6(I) * XU
• ********* ELIMINATION OPERATIONS ON NEXT VECTOR
ITERATE **********
780 DO 820 I = IP, Q U = RV6 (I)
• ********* IF RVI(I-I) .EQ. E(1), A ROW INTERCHANGE
WAS PERFORMED EARLIER IN THE
TRIANGULARIZATION PROCESS ********** IF (RVI(I-I) .NE. E(1)) GO TO 800
U = RV6 (I-I) RV6(I-I) = RV6(1)
800 RV6(1) = U - RV4(1) * RV6(I-I) 820 CONTINUE
522
7.1-328
840
ITS = ITS + 1
GO TO 600
********** NORMALIZE SO THAT SUM OF SQUARES IS
i AND EXPAND TO FULL ORDER **********
U = 0.0
860
DO 860 1 = P, q U = U + RV6(1)**2
XU = 1.0 / SQRT(U)
880 DO 880 1 = I, N
Z(I,R) = 0.0
900
DO 900 1 = P, Q
Z(I,R) = RV6(1) * XU
X0 = XI
920 CONTINUE
940 IF (Q .LT. N) GO TO i00
GO TO i001
********** SET ERROR -- NON-CONVERGED EIGENVECTOR ********** 960 IERR = 4 * N + R
GO TO i001
********** SET ERROR -- UNDERESTIMATE OF NUMBER OF
EIGENVALUES IN INTERVAL **********
980 IERR = 3 * N + I
i001LB = TI
UB = T2
RETURN
END
523
7.2-I
NATS PROJECT
EIGENSYSTEM SUBROUTINE PACKAGE (EISPACK)
F299-2 EISPAC
A Control Program for the Eigensystem Package (F269 to F298 and F220 to F247).
May, 1972 July, 1975
i. PURPOSE~
The Fortran IV and 0S/360-370 assembly language subroutine EISPAC (together with its associated "keyword" entry points) is designed to simplify the solution of the standard and generalized matrix eigenproblems using the subroutines in the eigensystem package (F269-F298, F220-F247). It thus may be used to compute some or all of the eigenvalues, with or without eigenvectors, of complex general, complex Hermitian, real general, real symmetric, real symmetric tridiagonal, certain real non-symmetric tridiagonal, and real symmetric band matrices; and it may also be used to compute some or all of the eigenvalues, with or without eigenvectors, for the real symmetric generalized eigenproblem, or all of the eigenvalues, with or without eigenvectors, for the real non- symmetric generalized eigenproblem. EISPAC offers the following advantages if you wish to solve an eigenproblem:
!o You describe the problem to EISPAC in simple, familiar terms°
2~ Using your description, EISPAC automatically selects subroutines to solve your problem and executes them in the proper order and with parameters passed from one to another in the proper way. In general, EISPAC selects the sequence of subroutines in the eigensystem package which will solve your problem as rapidly as possible with reasonable assurance of stability in the calculations.
3~ EISPAC loads each selected subroutine only as it is required, thus making available for data storage as much memory as possible. On the other hand, if sufficient memory is available, the subroutines used are retained in memory and are not reloaded when you repeatedly call EISPAC to solve the same problem. (See section 3 below.)
4. EISPAC allocates and frees any necessary auxiliary storage automatically.
524
7.2-2
5. Use of EISPAC minimizes the number of changes you must make to your program if you wish to solve a slight variation of your original problem or if you wish to take advantage of new methods when they are introduced.
6. EISPAC is called as a subroutine from your own driver program. Thus the matrix whose eigensystem is being computed may itself be the result of other computations in your program, and the computed eigensystem may conveniently be used in further calculations.
Thus EISPAC relieves you of having to develop a detailed knowledge of the applicability, efficiency, and calling sequences of the individual EISPACK subroutines.
2. USAGE.
A. Calling Sequence.
EISPAC employs variable length parameter lists and "keyword" parameters to simplify specification of your problem and to group related subparameters. An overview of the calls to EISPAC is given by the prototype calls below; specific calls for different classes of matrices are discussed in section 2.B.
The prototype call to EISPAC for the standard eigenproblem is:
CALL EISPAC (NM, N, MATRIX (...), BAND (...), VALUES (.0.), VECTOR (...), METHOD (...), ERROR (...), SU~R ( . . . ) )
where
NM is an integer variable which supplies the row (first) dimension of any two- dimensional arrays appearing in the call to EISPAC (as that dimension is specified in the DIMENSION statements for them in the calling program). For example, if your program contains arrays dimensioned: A(50,50), Z(50,50) which appear in the call to EISPAC, and the order of the eigenproblem being solved is 25, then NM = 50 and N = 25.
525
7 . 2 - 3
is an integer variable which supplies the order of the input matrix. N is checked to verify that it is neither greater than NM nor less than i.
MATRIX, BAND, VALUES, VECTOR, METHOD, ERROR, SUBR are keyword parameters. They accept sets of subparameters which define the eigenproblem being solved. (These subparameters are discussed in detail in section 2.C below.) Keyword parameters not needed to specify a particular problem are omitted from the call to EISPAC; those appearing may appear in any order.
The prototype call to EISPAC for the generalized eigenproblem is:
CALL EISPAC (NM, N, MATA (..o), MATB (...), VALUES (...), VECTOR (...), ERROR (...), SUBR (.o.))
where MATA and MATB replace MATRIX as keyword parameters. Note: MATRIX and MATA are alternate forms of the same keyword and can be used interchangeably.
To use EISPAC, you must include a private library DD card for EISPACLB (the dynamic load library, see section 3 below) in the GO-step of your job. This card associates EISPACLB with the dataset where the load modules for EISPAC and the eigensystem package subroutines reside. If you are using a typical Fortran cataloged procedure, this card is:
//GO.EISPACLB DD DISP=SHR,DSNAME=...
Similarly, if you are using the TSO time sharing system~ you should execute the command:
ALLOC FiLE(EISPACLB) DATASET(...) SHR
before executing your program.
Finally, if you wish to use EISPAC from a PL/I (Checkout or Optimizer) program by means of the interlanguage communication facility, you should write a simple Fortran subroutine which is called from your PL/I program and which in turn calls E!SPAC as described below. This is necessary because EISPAC makes certain (non-standard) assumptions about the Fortran environment of the program calling it which may not be satisfied
526
7.2-4
when the program is written in PL/I. The Fortran program calling EISPAC should have as parameters the variables to be passed to EISPAC; you should take care that the vectors and arrays appear in DIMENSION statements in it. Thus for the example concluding the section on real symmetric matrices in section 2.B below, the Fortran subroutine called by your PL/I program should look like:
SUBROUTINE EISCAL (N, A, W, Z) INTEGER N REAL*8 A(N,N), W(N), Z(N,N) CALL EISPAC (N, N, MATRIX ('REAL, A, 'SYMMETRIC'),
VALUES (W), VECTOR (Z)) RETURN END
This example assumes that the PL/I arrays corresponding to the matrices A and Z are dimensioned exactly NxN, and hence that the parameter NM can be replaced by N. In the PL/I calling program, EISCAL would be declared:
DCL EISCAL ENTRY (FIXED BINARY(31,0), (*,*) FLOAT DECIMAL(16), (*) FLOAT DECIMAL(16), (*,*) FLOAT DECIMAL(16)) OPTIONS (FORTRAN) EXTERNAL;
You must provide a DD card or allocation for FT06F001, the standard Fortran output file, because Fortran automatically tries to open it. This file should be associated with the same dataset as the output from the PL/I program, so that EISPAC error messages, if any, appear with it. Finally, if you are using the PL/I Checkout compiler, you need to specify the option SIZE(-nK) to the execution step to reserve dynamic storage for EISPAC; at a minimum n=14, and it must be large enough to accommodate any temporary arrays that are allocated. (An insufficiently large value of n will result in either of the system completion codes 804 or 80A (see section 2.D).)
The use of EISPAC to solve various kinds of eigenproblems is illustrated in the following section. You may wish to read first the examples for the type of matrix you have and then consult section 2.C for further details about the keyword subparameters. (Note that in these examples the continuation symbol which must appear in column 6 of a Fortran continuation card has been omitted.)
527
7.2-5
B. EISPAC Examples for Different Classes of Matrices.
Complex General Matrix
The basic call, which finds all of the eigenvalues (WR, WI) of the complex general matrix (AR, AI), is:
CALL EISPAC (NM, N, MATRIX ('C0MPLSX', AR, A!), VALUES (WR, WZ))
If you wish to find all of the eigenvectors (ZR, ZI), add: VECTOR (ZR, ZI).
If you wish to find all of the eigenvalues and only selected eigenvectors~ add: VECTOR (ZR, ZI, MM, M, SELECT).
If you prefer not to balance the matrix, add: METHOD ('NO', 'BALANCE').
If you wish to use elementary instead of unitary similarities, add: METHOD ('ELEMENTARY')~
Thus a call to find all of the eigenvalues and some of the eigenvectors of a complex general matrix is:
CALL EISPAC (NM, N, MATRIX ('COMPLEX', AR, AI), VALUES (WR, WI), VECTOR (ZR, ZI, MM, M, SELECT))
Complex Hermitian Matrix
Recall that a complex Hermitian matrix is a matrix which is equal to its complex conjugate transpose. If you wish to solve an eigenproblem for a complex symmetric matrix (a matrix which is equal to its transpose without conjugation), you must follow the complex general matrix examples.
The basic call, which finds all of the eigenvalues W of the complex Hermitian matrix (AR, AI), is:
CALL EISPAC (NM, N, MATRIX ('COMPLEX', AR, AI, 'HERMITIAN'), VALUES (W))
528
7.2-6
If the complex Hermitian matrix is packed into a single two-dimensional array, HP, substitute for MATRIX ('COMPLEX', AR, AI, 'HERMITIAN'): MATRIX ('COMPLEX', HP, HP, 'HERMITIAN', 'PACKED').
If you wish to find only the eigenvalues in the interval (RLB,RUB), substitute for VALUES (W) (see note 3): VALUES (W, MM, M, RLB, RUB).
Alternatively, if you wish to find exactly M eigenvalues, starting from the Mll-th smallest one, substitute for VALUES (W): VALUES (W, MII, M). (See notes i and 3.)
If you wish to find the eigenvectors (ZR, ZI) corresponding to the eigenvalues found, add: VECTOR (ZR, ZI).
Thus a call to find a few eigenvalues and their corresponding eigenvectors of a complex Hermitian matrix is:
CALL EISPAC (NM, N, MATRIX ('COMPLEX', AR, AI, 'HERMITIAN'), VALUES (W, MM, M, RLB, RUB), VECTOR (ZR, ZI))
Real General Matrix
The basic call, which finds all of the eigenvalues (WR, WI) of the real general matrix A, is:
CALL EISPAC (NM, N, MATRIX ('REAL', A), VALUES (WR, WI))
If you wish to find all of the eigenvectors ZP, add: VECTOR (ZP).
If you wish to find all of the eigenvalues and only selected eigenvectors, add: VECTOR (ZP, MM, M, SELECT).
If you prefer not to balance the matrix, add: METHOD ('NO', 'BALANCE').
If you wish to use orthogonal instead of elementary similarities for the reduction to upper Hessenberg form, add (see note 5): METHOD ('ORTHOGONAL').
529
7.2-7
Thus a call to find all of the eigenva!ues of a real general matrix without balancing and using orthogonal similarities is:
CALL EiSPAC (NM, N, MATRIX ('REAL', A), VALUES (WR, WI), METHOD ('NO', 'BALANCE', 'ORTHOGONAL'))
Real Non-Symmetric Tridiagonal Matrix
The following examples apply only if the products of corresponding off-diagonal elements of the tridiagonal matrix all are non-negative. (Read note 4 below for an additional restriction if you wish to compute eigenvectors.) Otherwise the real general matrix examples must be followed.
The basic call, which finds all of the eigenvalues W of the real tridiagonal matrix UST, is:
CALL EISPAC (NM, N, MATRIX ('REAL', UST, 'TRIDIAGONAL'), VALUES (W))
If you wish to find only the eigenva!ues in the interval (RLB,RUB), substitute for VALUES (W) (see note 3): VALUES (W, MM, M, RLB, RUB).
Alternatively, if you wish to find exactly M eigenvalues, starting from the Mll-th smallest one, substitute for VALUES (W): VALUES (W, MII, M). (See notes 1 and 3.)
If you wish to find the eigenvectors Z corresponding to the eigenvalues found, add: VECTOR (Z).
Thus a call to find exactly M eigenvalues, starting from the Mll-th smallest one, of a real non-symmetric tridiagonal matrix is:
CALL EISPAC (NM, N, MATRIX ('REAL', UST, 'TRIDIAGONAL'), VALUES (W, MII, M))
Real Symmetric Matrix
The basic call, which finds all of the eigenvalues W of the real symmetric matrix A, is (see note 2):
530
7 . 2 - 8
CALL EISPAC (NM, N, MATRIX ('REAL', A, 'SYMMETRIC'), VALUES (W))
If the real symmetric matrix is packed into a single one-dimensional array, SP, substitute for MATRIX ('REAL', A, 'SYMMETRIC'): MATRIX ('REAL', SP, 'SYMMETRIC', 'PACKED').
If you wish to find only the eigenvalues in the interval (RLB,RUB), substitute for VALUES (W) (see note 3): VALUES (W, MM, M, RLB, RUB).
Alternatively, if you wish to find exactly M eigenvalues, starting from the Mll-th smallest one, substitute for VALUES (W): VALUES (W, MII, M). (See notes I and 3.)
If you wish to find the eigenvectors Z corresponding to the eigenvalues found, add: VECTOR (Z).
Thus a call to find all of the eigenvalues and eigenvectors of a real symmetric matrix is:
CALL EISPAC (NM, N, MATRIX ('REAL', A, 'SYMMETRIC'), VALUES (W), VECTOR (Z))
Real Symmetric Tridiagonal Matrix
The basic call, which finds all of the eigenvalues W of the real symmetric tridiagonal matrix ST, is (see note 2):
CALL EISPAC (NM, N, MATRIX ('REAL', ST, 'SYMMETRIC', 'TRIDIAGONAL'), VALUES (W))
If you wish to find only the eigenvalues in the interval (RLB,RUB), substitute for VALUES (W) (see note 3): VALUES (W, MM, M, RLB, RUB).
Alternatively, if you wish to find exactly M eigenvalues, starting from the Mll-th smallest one, substitute for VALUES (W): VALUES (W, MII, M). (See notes i and 3.)
If you wish to find the eigenvectors Z corresponding to the eigenvalues found, add: VECTOR (Z).
531
7.2-9
Thus a call to find some of the eigenvalues of a real symmetric tridiagonal matrix is:
CALL EISPAC (NM, N, MATRIX ('REAL', ST, 'SYMMETRIC', 'TRIDIAGONAL'), VALUES (W, MM, M, RLB, RUB))
Real Symmetric Band Matrix . . . . . . . . . . . . . . . . . . . . . . .
The basic call, which finds all of the eigenvalues W of the real symmetric band matrix SB, is (see notes 2 and 6):
CALL EISPAC (NM, N, MATRIX ('REAL', SB, 'SYMMETRIC'), BAND (MB), VALUES (W))
If you wish to find only the eigenvalues in the interval (RLB,RUB), substitute for VALUES (W) (see note 3): VALUES (W, MM, M, RLB, RUB).
Alternatively, if you wish to find exactly M eigenvalues, starting from the Mll-th smallest one, substitute for VALUES (W): VALUES (W, MII, M). (See notes 1 and 3.)
If you wish to find the eigenvectors Z corresponding to the eigenvalues found, add: VECTOR (Z).
Thus a call to find some of the eigenvalues of a real symmetric band matrix is:
CALL EISPAC (NM, N, MATRIX ('REAL', SB, 'SYMMETRIC'), BAND (MB), VALUES (W, MM, M, RLB, RUB))
Generalized Real Symmetric Matrix Systems
There are three forms of the real symmetric generalized eigenproblem that can be solved with EISPAC: namely, the forms Ax = (lambda)Bx, ABx = (lambda)x, and BAx = (lambda)x, where A and B are both symmetric and B is positive definite.
532
7.2-10
The basic call, which finds all of the eigenvalues W of the real symmetric generalized system Ax = (lambda)Bx, is (see notes 2 and 7):
CALL EISPAC (NM, N, MATA ('REAL', A, 'SYMMETRIC'), MATB ('REAL', B, 'SYMMETRIC', 'POSITIVE DEFINITE'), VALUES (W))
If you wish to find only the eigenvalues in the interval (RLB,RUB), substitute for VALUES (W) (see note 3): VALUES (W, MM, M, RLB, RUB).
Alternatively, if you wish to find exactly M eigenvalues, starting from the Mll-th smallest one, substitute for VALUES (W): VALUES (W, MII, M). (See notes i and 3.)
If you wish to find the eigenvectors Z corresponding to the eigenvalues found, add: VECTOR (Z).
If the problem is of the form ABx = (lambda)x or BAx = (lambda)x, supply 'ABX=LX' or 'BAX=LX', respectively, to MATB (in a position after the B parameter).
Thus a call to find exactly M eigenvalues, starting from the Mll-th smallest one, and the corresponding eigenveetors of the real symmetric generalized system ABx = (lambda)x, is:
CALL EISPAC (NM, N, MATA ('REAL', A, 'SYMMETRIC'), MATB ('REAL', B, 'SYMMETRIC', 'POSITIVE DEFINITE', 'ABX=LX'), VALUES (W, MII, M), VECTOR (Z))
Generalized Real Non-Symmetric Matrix System
The basic call, which finds all of the eigenvalues (ALPHAR/BETA, ALPHAI/BETA) for the real non~ symmetric generalized eigenproblem Ax = (lambda)Bx, is (see note 8):
CALL EISPAC (NM, N, MATA ('REAL', A), MATB ('REAL', B), VALUES (ALPHAR, ALPHAI, BETA))
If you wish to find all of the eigenvectors, ZP, of the system, add: VECTOR (ZP).
533
7.2-11
Thus a call to find all of the eigenvalues and eigenvectors of a real non-symmetric generalized system is:
CALL EISPAC (NM, N, MATA ('REAL ~ , A), MATB ('REAL', B), VALUES (ALPHAR, ALPHAI, BETA), VECTOR (ZP))
C~ Meanings of Keyword Subparameters.
Subparameters for MATRIX, MATA, and MATB:
'REAL' specifies that the matrix whose eigensystem is to be computed is real. (See note 9.)
'COMPLEX' specifies that the matrix whose eigensystem is to be computed is complex. (See note 9.)
AR, AI are long precision real two-dimensional variables with row dimension NM and column dimension at least N. They supply, respectively, the real and imaginary parts of the complex matrix whose eigensystem is to be computed. In the non-Hermitian case, the information in the full AR and AI arrays specifies the matrix, and all of it is destroyed. In the Hermitian case, the information in the full lower triangle of AR and the strict lower triangle of AI specifies the matrix, and is destroyed as well as the diagonal of AI; the full upper triangle of AR and the strict upper triangle of AI are left unaltered.
A~ B are long precision real two-dimensional variables with row dimension NM and column dimension at least N. They supply the real matrices whose eigensystem is to be computed. (For the standard eigenproblem, only A is supplied.) In the non-symmetric case, the information in the full A and B arrays specifies the matrices, and all of it is destroyed. In the symmetric standard case~ the information in the full lower triangle of A specifies the matrix; that in the strict lower triangle may be destroyed, and that in the full upper triangle is left
534
7.2-12
UST
ST
HP
unaltered. In the symmetric generalized case, the information in the full upper triangles of A and B specifies the matrices; the full lower triangle of A and the strict lower triangle of B are destroyed, and the strict upper triangle of A and the full upper triangle of B are left unaltered.
is a long precision real two-dimensional variable with row dimension NM and column dimension at least 3. It supplies a real non-symmetric tridiagonal matrix whose subdiagonal elements are stored in the last N-I positions of the first column, whose diagonal elements are stored in the second column, and whose superdiagonal elements are stored in the first N-I positions of the third column. UST(I,I) and UST(N,3) are arbitrary. None of the information in UST is destroyed. The non-symmetric tridiagonal matrix supplied by UST must have the additional special property that the products of corresponding off-diagonal elements all are non-negative. (Read note 4 for an additional restriction on UST if eigenvectors are being computed.) Violation of these restrictions on UST causes an EISPAC execution phase error (see section 2.D below).
is a long precision real two-dimensional variable with row dimension NM and column dimension at least 2. It supplies a real symmetric tridiagonal matrix whose subdiagonal elements are stored in the last N-I positions of the first column and whose diagonal elements are stored in the second column. ST(I,1) is arbitrary. The information in the subdiagonal (first column) only is destroyed.
is a long precision real two-dimensional variable with row dimension NM and column dimension at least N. On input, HP contains the lower triangle of a packed complex Hermitian matrix of order N whose eigensystem is to be computed. If the real part of the matrix is denoted by AR and the imaginary part by AI, then the full
535
7.2-13
SP
SB
lower triangle of AR should be stored in the full lower triangle of HP, and the strict lower triangle of AI should be stored in the strict upper triangle of HP in transposed form. For example when N=4, HP should contain
(AR(I,I) AI(2,1) AI(3,1) A!(4,1) ) (AR(2,1) AR(2,2) AI(3,2) AI(4,2) ) (AR(3,1) AR(3,2) AR(3,3) AI(4,3) ) (AR(4,1) AR(4,2) AR(4,3) AR(4,4) ).
All of the information in HP is destroyed.
is a long precision real one-dimensional variable with dimension at least N*(N+I)/2. It supplies the lower triangle of a real symmetric matrix A of order N, packed row-wise. For example when N=3, SP should contain
(A(I,I),A(2,1),A(2,2),A(3,1),A(3,2),A(3,3))
where the subscripts of each element refer to the row and column of the element in the standard two-dimensional representation. All of the information in SP is destroyed.
is a long precision real two-dimensional variable with row dimension NM and column dimension at least MB. It supplies the lower triangle of a real symmetric matrix A of order N in band form with half bandwidth MB. The lowest subdiagonal of the matrix is stored in the last N+I-MB positions of the first column of SB, the next subdiagonal in the last N+2-MB positions of the second column, further diagonals similarly, and finally the principal diagonal in the N positions of the last column. Contents of storage locations not part of the matrix are arbitrary. For example, when N=5 and MB=3, SB should contain
( * * A(I,I) ) ( * A(2,1) A(2,2) ) (A(3,1) A(3,2) A(3,3) ) (A(4,2) A(4,3) A(4,4) ) (A(5,3) A(5,4) A(5,5) ).
536
7.2-14
All of the information in SB is destroyed.
'HERMITIAN', 'SYMMETRIC', 'TRIDIAGONAL' 'POSITIVE DEFINITE' , 'NEGATIVE DEFINITE', 'PACKED I
specify that the matrix whose eigensystem is to be found has the stated special property. (See also notes I, 2, and 9.)
'ABX=LX', 'BAX=LX' (as subparameters for MATB) specify the corresponding variant of the real symmetric generalized eigenproblem.
Subparameter for BAND:
MB is an integer variable which supplies the half bandwidth of a real symmetric band matrix. It is defined as the number .of adjacent diagonals, including the principal diagonal, required to specify the non-zero portion of the lower triangle of the matrix.
Subparameters for VALUES:
WR, WI are long precision real one-dimensional variables of dimension at least N. They receive, respectively, the real and imaginary parts of the N complex eigenvalues computed.
W is a long precision real one-dimensional variable of dimension at least sufficient (N, MM, or M) to hold the eigenvalues. It receives the N (M) eigenvalues computed.
MM is an integer variable which, when it is a subparameter to VALUES, supplies a maximum for the number of eigenvalues expected in the interval (RLB,RUB); more than MM eigenvalues in (RLB,RUB) is an error. The dimension of W, and the column dimension of ZR and ZI or Z if used, must be at least MM.
M is an integer variable which, when it is a subparameter to VALUES, denotes the number of eigenvalues actually stored in W. It is supplied (in conjunction with MII) by the user if a specified number of eigenvalues is to be computed. It is set by the program, if an interval (RLB,RUB) has been specified, to the number of eigenvalues actually found.
537
7.2-15
RLB, RUB are long precision real variables which define an interval to be searched for eigenvalues. The eigenvalues found lie in the interval (RLB,RUB), which is closed on the left and open on the right; if RLB is not less than RUB, no eigenvalues are found. (RLB,RUB) must not contain more than MM eigenvalueso
MII is an integer variable which, when it is a subparameter to VALUES, supplies the index of the smallest eigenvalue to be computed.
EPS 1 is a long precision real variable which supplies an absolute error tolerance for the computed eigenvalues; if the input value of EPSI is non-positive, a default value will be used. (See note 3.)
ALPHAR, ALPHAI, BETA are long precision real one-dimensional variables with dimension at least N which receive the complex eigenvalues for a real non-symmetric generalized eigenproblem. The real part of each eigenvalue is given by ALPHAR(I)/BETA(I) and the imaginary part by ALPHAI(I)/BETA(1). (See note 8.)
'LARGEST', 'SMALLEST' specify that the M largest or smallest eigenvalues are to be computed if the rational QR method has been selected° In this case substitute for VALUES(W): VALUES (W, M, 'LARGEST') or VALUES (W, M, 'SMALLEST'), respectively° (See notes i and 9.)
Subparameters for VECTOR:
ZR, ZI are long precision real two-dimensional variables with row dimension NM and column dimension at least sufficient (N, MM, or M) to hold the eigenvectors. They receive, respectively, the real and imaginary parts of the N (M) eigenvectors computed.
ZP is a long precision real two-dimensional variable with row and column dimensions as described for ZR and ZI. It receives N (M) columns which represent eigenvectors of a real general matrix or matrix system. To conserve storages these eigenvectors are stored in ZP in packed form:
538
7.2-16
MM
M
SELECT
corresponding to a real eigenvalue, one column representing the real eigenvector is stored; corresponding to a complex conjugate pair of eigenvalues, two consecutive columns representing the real and imaginary parts of the eigenvector corresponding to the first, or first flagged (see SELECT below), of the pair are stored. For example, suppose all of the eigenvectors of a real general matrix are being computed. If the K-th eigenvalue is real (WI(K) = 0) then ZP(K) is the corresponding eigenvector. If the K-th and (K+l)-th eigenvalues are a complex conjugate pair (with WI(K) .GT. 0) then ZP(K) is the real part and ZP(K+I) is the imaginary part of the eigenvector corresponding to the K-th eigenvalue. The conjugate of this vector is the eigenvector for the conjugate eigenvalue. (Example Fortran statements for unpacking the eigenvectors may be found in section 2.3.2 of (6).)
is a long precision real two-dimensional variable with row and column dimensions as described for ZR and ZI. It receives the N (M) eigenvectors computed. When all of the eigenvectors of a real symmetric (full) matrix or generalized matrix system are being computed, the array A which supplies the input matrix may be used for Z; the eigenvectors then overwrite the input matrix.
is an integer variable which, when it is a subparameter to VECTOR, supplies the maximum number of columns of ZR and ZI or ZP which will be used. The column dimension of ZR and ZI or ZP must be at least MM.
is an integer variable which, when it is a subparameter to VECTOR, receives the number of columns used to store eigenvectors in ZR and ZI or ZP.
is a logical one-dimensional variable of dimension at least N whose true elements flag those eigenvalues of a real or complex general matrix whose eigenvectors are to be computed. If eigenvectors of a real general matrix are being computed and both of a pair of complex conjugate eigenvalues
539
7.2-17
are flagged, the second flag is set false and only the eigenveetor corresponding to the first of the pair is computed. An error results if MM is smaller than the number of columns required to hold the selected eigenvectors.
Subparameters for METHOD:
(See note 9 concerning alphanumeric parameters.)
'ORTHOGONAL' specifies that orthogonal similarities (instead of elementary similarities) are to be used to reduce a real general matrix to upper Hessenberg form. Reduction by orthogonal similarities is somewhat slower than that by elementary similarities~ but in some cases it may improve the accuracy of the computed eigensystem. In particular, if you wish to calculate the condition numbers for the computation of the eigensystem of a matrix (see (3), po 199 and (4), pp. 86-89), you should use the condition-number-preserving orthogonal transformations.
'ELEMENTARY' specifies that elementary similarities (instead of unitary similarities) are to be used on a complex general matrix (the LR rather than the QR transformation). Elementary similarities are somewhat faster than unitary similarities, but in some cases diminish the accuracy of the computed (complex general) eigensystem.
~NO', 'BALANCE' specifies that a real or complex general matrix is not to be balanced before its eigensystem is computed. In general, balancing improves the accuracy of the computed eigensystem and requires very little additional computation time.
'RATQR T specifies that the rational QR method is to be used to compute a few of the largest or smallest eigenvalues. (See note i.)
540
7.2-18
Subparameter for ERROR:
IERROR is an integer variable which receives a value indicating whether certain errors occurred during the solution of the eigensystem. See section 2.D below.
Subparameter for SUBR:
USUB is a user-supplied subroutine with the following parameter list:
USUB (SUBRNO, NM, N, AR, AI, WR, Wl, ZR, ZI, MM, M, RLB, RUB, EPSI, SELECT, IDEF, SMLSTV, IERROR, LOW, UPP, BND, D, E, E2, IND, INT, ORTR, SCALE, TAU, ORTI, MII, NV, MB, BR, DL, ALPHAR, ALPHAI, BETA).
The keyword parameter SUBR (USUB) may be added to any EISPAC call. (Note that USUB must be mentioned in an EXTERNAL statement in the calling program.) USUB will be called before execution begins and after execution of each numbered routine in the path determined by the parameters to EISPAC and defined in the "EISPAC Eigensystem Path Chart" (i); the number of the routine (zero before execution begins) is passed by the integer variable SUBRNO. USUB may be used to examine intermediate results, to obtain timing information, etc.; its use is quite analogous to that of the procedure "INFORM" described by Rutishauser ~5). For the meanings of the parameters it receives, and appropriate dimensions for those requiring them, see (i), (2), and section 2.3.7 of (6).
Note I: Computing a Few of the Largest or Smallest Eigenvalues.
The recommended procedure for computing a few of the extreme eigenvalues of a real symmetric or complex Hermitian matrix is by appropriate specification of the subparameters MII and M to VALUES. Alternatively, the rational QR method may be employed, although it has proven less stable numerically. If the rational QR method is selected and you know that the matrix is positive (negative) definite, you may indicate so by adding the subparameter 'POSITIVE DEFINITE' ('NEGATIVE DEFINITE') to MATRIX, e.g.,
541
7.2-19
MATRIX ('REAL', ST, ~SYMMETRIC', 'TR!DIAGONAL' 'POSITIVE DEFINITE'), METHOD ('RATQR'), VALUES (W, M, 'SMALLEST').
Computational economy results only when the largest (smallest) eigenvalues of a negative (positive) definite matrix are sought.
Note that subparameter W to VALUES must be of dimension at least N, if the rational QR method is used, even though only M eigenvalues are requested.
Note 2: ~HERM!TIAN' for Real Matrices.
For a real matrix, are synonymous.
~HERMiTIAN' and 'SYMMETRIC'
Note 3: EPSI as a Subparameter to VALUES.
EPSI is a long precision real variable which supplies an absolute error tolerance for the computed eigenvalues when only a few eigenvalues (or a few eigenvalues and their corresponding eigenvectors) are being calculated for the standard or generalized real symmetric problems; or for the non-symmetric generalized problem where all eigenvalues and possibly eigenvectors are being found. If the input value of EPSI is non- positive, a suitable default value, which is related to the machine precision and the norm of the matrix, is used in place of EPSI; this same default is used if EPSI is not supplied to EiSPAC. The input value, if any, of EPSI is not altered when the default value is employed; however, for the standard problem only, the (last) default value used may be examined by means of a user subroutine supplied as the subparameter to SUBR (see above). To supply EPSI to E!SPAC, substitute for the recommended call to VALUES: VALUES (W, MM, M, RLB, RUB, EPSI) or VALUES (ALPHAR, ALPHAI, BETA, EPSI) as appropriate.
If eigenvalues only (no eigenvectors) are being computed, EPSI may be used to control the trade- off between computation time and absolute accuracy of the computed eigenvalues, if less (or more) accuracy than that given by the default value of EPSI is required.
542
7.2-20
If eigenvalues and their corresponding eigenvectors are being computed, extreme care must be taken in choosing a value for EPSI other than the default, since if EPSI is too large, the eigenvectors may be poor because the eigenvalues are not sufficiently accurate; whereas if EPSI is smaller than necessary for convergence, the additional accuracy of the computed eigenvalues will not increase the accuracy of the eigenvectors. For further discussion, or in case of difficulty, see section 2.3.3 of (6), and also the NATS subroutine documents for F223 TINVIT, F294 BISECT, F237 TRIDIB, and F239 QZIT (2).
Note 4: Class of Non-Symmetric Tridiagonal Matrices for which Eigenvectors may be Found.
The class of real non-symmetric tridiagonal matrices for which eigenvectors can be computed is somewhat more restricted than that for which eigenvalues can be found. For the eigenvector computation to be successful, not only must the products of corresponding off-diagonal elements all be non-negative, but also when such a product is zero~ the corresponding off-diagonal elements must both be zero.
Note 5: 'UNITARY' for Real Matrices.
For a real matrix, 'UNITARY' and 'ORTHOGONAL' are synonymous.
Note 6: Symmetric Band Matrices of Half Bandwidth 2.
If MB is specified as 2 for a real symmetric band matrix, EISPAC selects the same subroutines as if 'TRIDIAGONAL' had been specified as a subparameter to MATRIX.
Note 7: Generalized Problem Matrix Subparameters.
As discussed earlier, for a problem to be classified "Real Symmetric Generalized", the A and B input matrices must each be symmetric with B positive definite. Unless 'SYMMETRIC' is specified as a subparameter to MATA and both 'SYMMETRIC' and 'POSITIVE DEFINITE' are specified as subparameters to MATB, EISPAC will select a path corresponding to the real non-symmetric generalized case instead (and assume storage of the full A and B matrices).
543
7.2-21
Note 8: Eigenvalues for the Non-Symmetric Generalized Problem.
The divisions ALPHAR(1)/BETA(1) and ALPHAI(1)/BETA(1) to obtain the real and imaginary parts of the eigenvalues for the real non-symmetric generalized problem are left to the user. The arrays ALPHAR, ALPHAI, and BETA themselves are returned instead, because they have more information than the quotients when B (or both A and B) is nearly singular. Indeed, if B is singular, at least one element of BETA will be zero and division dare not be attempted.
Note 9: Negation and Abbreviation of Alphanumeric Subparameters.
Any alphanumeric subparameter (e.g., 'BALANCE') is negated if its immediately preceding subparameter is 'NO', 'NON', or 'NOT' Similarly, the subparameters 'YES', 'IS', 'USE', and 'DO' act as identity alphanumeric subparameters. These conventions are useful when you desire to use a single EISPAC call to compute the eigensystem of a matrix which sometimes is to be balanced and sometimes not, say, since the subparameter 'NO' or 'YES' may be an alphanumeric variable.
Any alphanumeric subparameter may be abbreviated by enough of its initial letters to unambiguously distinguish it from all other alphanumeric subparameters. For protection against ambiguities arising from the future introduction of new alphanumeric subparameters, you should use at least three (perhaps four) letter abbreviations when they exist. The alphanumeric subparameters currently in use are listed below (synonyms are separated by commas, antonyms by hyphens):
DO', 'IS', 'USE ~, 'YES' NO', 'NON', 'NOT' REAL ~ - 'COMPLEX' HERMITIAN' - 'GENERAL' (see note 2) SYMMETRIC' - 'GENERAL' TRIDIAGONAL' - 'FULL' POSITIVE DEFINITE' NEGATIVE DEFINITE' BALANCE' ORTHOGONAL' - 'ELEMENTARY'
~UNITARY' - 'ELEMENTARY' (see note 5) ~AX=LBX', 'AZ=WBZ' 'ABX=LX', 'ABZ=WZ' 'BAX=LX' 'BAZ=WZ' 'LARGEST ~ - 'SMALLEST'
544
7.2-22
As a final example illustrating these concepts, suppose you wish to compute the eigenvalues and eigenvectors of an order N real general matrix without balancing and using orthogonal transformations, with retrieval of the error indicator and calls to a user subroutine, in a program with variables dimensioned: A(100,100), WR(100), WI(100), Z(100,100). Then two of several possible calls are:
CALL EISPAC (i00, N, MATRIX ('REAL', A), VALUES (WR, WI), VECTOR (Z), METHOD ('ORTHOGONAL', 'NO', 'BALANCE'), ERROR (IERROR), SUBR (USUB))
CALL EISPAC (i00, N, MATRIX ('NOT', 'COMPLEX', A), METHOD ('USE', 'ORTHOG', 'NO' 'NO' 'NO', 'BALAN'), VALUES (WR, WI), VECTOR (Z), SUBR (USUB), ERROR (IERROR))
(Recall in the last example that keyword parameters can appear in any order in the third parameter position and beyond.)
D. Error Conditions and Returns.
Three types of errors can occur in EISPAC: "decision phase" errors, "execution phase" errors, and "linkage" errors. (See section 3 below.) Decision phase errors arise when EISPAC detects a mistake or inconsistency in the form of the parameters it receives. Execution phase errors are those which it detects during the execution of the eigensystem-package subroutines themselves. Decision phase errors always result in a message describing the error and the further message "EXECUTION CONTINUING" or "EXECUTION TERMINATED" and the appropriate action. Execution phase errors always result in a message describing the error and termination of execution, unless the ERROR keyword was supplied (see below).
Linkage errors may occur either during the decision or execution phases and always cause termination of execution. Linkage error 00 arises when the internal file name EISPACLB has not been associated with a dataset via a DD card or ALLOC command. Linkage error 01 arises when such an association has been made but a requested subroutine or phase of EISPAC cannot be found in the associated dataset. In this case, check that it contains the required eigensystem-package subroutines and the phases of EISPAC. (See sections 3 and 5 below.)
545
7.2-23
You may modify the behavior of EiSPAC when an execution phase error is detected by supplying the ERROR keyword. When it is supplied, its subparameter IERROR is set to a value characterizing the error and return is made to the calling program (i.e., execution is not terminated). Furthermore, you may suppress the printing of the error message by setting IERROR to the value -755 870 989 before calling EISPAC.
A non-zero value of IERROR on return from EISPAC indicates that an execution phase error has occurred. If IERROR is positive, the computation has been abandoned, and few, if any, useful results have been produced. However, if IERROR is negative, the computation has been continued despite the error(s) and some meaningful results have been produced; use of the ERROR keyword thus permits you to recover these results. The values IERROR may assume and their significance are discussed below. (See also (2) and (6) . )
Value of Error iERROR Msg. No. Significance
None No execution phase errors occurred.
I O0 The calculation of the l-th eigenvalue failed to converge. If the eigensystem of a real or complex general matrix or for a non-symmetric generalized problem was being computed, eigenvalues I+I,I+2,...,N should be correct; otherwise, eigenvalues 1,2,...,I-I should be correct.
N+I 0i For a real non-symmetric tridiagonal matrix, A(I,I)*A(I-I,3) .LT. 0, violating the restriction discussed above. No useful results are produced.
2*N+I 02 For the eigenvectors of a real non-
symmetric tridiagonal matrix, A(I,I) and A(I-I,3) violated the restriction of note 4, above. All eigenvalues, but no eigenvectors, are correct.
546
7.2-24
3*N+I
3"N+2
4*N+I
5*N+I
6*N+I
7*N+I
-I
03
04
None
05
06
07
50
Either: (i) Parameter MM specified insufficient storage to hold all of the eigenvalues in the interval (RLB,RUB). The only useful result is M, which contains the number of eigenvalues which lie in the interval.
multiplicity at index MII. useful results are produced.
Or: (2) It is not possible to compute exactly M eigenvalues (starting from the Mll-th) because of exact
No
It is not possible to compute exactly M eigenvalues (starting from the Mll-th) because of exact multiplicity at index MII+M-I. No useful results are produced.
Not used in EISPAC.
The M largest or smallest eigenvalues were being computed by the rational QR method and the I-th eigenvalue failed to converge. All eigenvalues probably have some accuracy, but no stronger statement can be made.
The M largest or smallest eigenvalues were being computed by the rational QR method, the matrix was specified negative or positive definite, but the computation suggests it may not be; try again omitting the definiteness specification. No useful results are produced.
The eigensystem for a real symmetric generalized problem was being computed and the matrix supplied to MATB was not positive definite. No useful results are produced.
The calculation of one or more eigenvectors including the l-th failed to converge. All eigenvalues and the non-zero eigenvectors are correct.
547
7.2-25
-(N+I) None Both error 50 above and error 52 below occurred.
2*N+I) 52 Parameter MM specified insufficient columns to hold the selected eigenvectors. All eigenvalues and the first MM columns of (ZR, ZI) or Z are correct.
3*N+I) None This error predicts that error 02 above will occur. It will not normally be returned from EISPAC but may be observed when the user subroutine is emp!oyed.
In addition to the above errors which are diagnosed by EISPAC, other errors may produce System/360-370 completion codes (SCC). The most commonly produced completion codes and their meanings in conjunction with EISPAC are the following:
804 There was not enough storage to dynamically load a requested subroutine. Provide more storage (region), reduce the size of the eigenproblem being solved, or choose a path which requires less temporary storage (see (I) and (6)). The minimum storage requirement for EISPAC is approximately 22,000 (decimal) bytes on System/360-370.
606 Same as SCC804 above.
80A There was not enough storage to allocate a temporary vector or matrix~ See suggestions under SCC804 above.
E. Applicability and Restrictions°
EiSPAC is applicable to the solution of the standard and generalized eigensystem problems for the classes of matrices for which examples are given above. For further details on applicability, see (6), or consult the "EISPAC Eigensystem Path Chart" (I) to determine which subroutines are used in the path of interest and then the NATS subroutine documents (2) for those subroutines.
548
7.2-26
3. DISCUSSION OF METHOD AND ALGORITHM.
EISPAC consists of three major parts, the parameter- interpreter phase, the decision phase, and the execution phase, which are co-ordinated by a supervisor. The supervisor employs brief assembly language routines to count the number of subparameters supplied to each of the keywords and the number of parameters supplied to EISPAC itself. It then loads the parameter-interpreter phase dynamically and passes the parameter information to it.
The parameter-interpreter phase analyzes the parameters, checks them for consistency, supplies defaults for omitted optional parameters, and produces a characterization of the problem they specify. It returns this characterization and a standardized list of parameters to the supervisor.
If errors have been detected in the parameter-interpreter phase, the supervisor loads an error message module dynamically which prints error messages and which may terminate execution. Otherwise, the supervisor loads a decision phase appropriate to the problem being solved and passes the characterization to it. The decision phase determines the "path", or sequence, of eigensystem-package subroutines and auxiliary actions (e.g., temporary storage allocations) needed to solve the specified eigenproblem. It then returns a representation of this path to the supervisor.
The supervisor then calls the execution phase, which interprets the representation of the path (and information about order of execution) to load dynamically the required eigensystem subroutines and to allocate and free needed temporary storage. (Loading, allocating, and freeing are performed by operating system requests contained in brief assembly language routines.) When execution is complete, or as soon as a fatal error occurs, the execution phase returns to the supervisor. If execution phase errors have occurred and error messages are to be printed (see section 2.D above), the supervisor loads the error message module dynamically and prints them; execution terminates or continues as described above. When execution continues, the supervisor returns the results of the computation to the calling program.
Certain economies of execution are possible when EISPAC is called repeatedly to solve the same eigenproblem. After the first execution of the path for the problem, usable copies of the eigensystem-package subroutines for it may remain in memory (if sufficient storage is available), and if so they are reused without being reloaded on subsequent executions of the path.
549
7.2-27
The design and implementation of EISPAC are highly modular, so that additional subroutines and paths can be added relatively easily and with only a minimum of disturbance to existing paths. This modular design of EISPAC and the philosophy behind it are discussed in detail in (7).
4. REFERENCES~
i)
2)
Boyle, J~M., Hauser, C.H., and Rothaar, H.R., EISPAC Eigensystem Package Path Chart, Release 2, Argonne National Laboratory, Applied Mathematics Division, February, 1975.
NATS Project, Eigensystem Subroutine Package (EISPACK), Subroutines F269 to F298 and F220 to F247.
3) Wilkinson, J.H. and Reinsch, C., Handbook for Automatic Computation, Volume II, Linear Algebra, Springer-Verlag, (i97i).
4) Wilkinson, J.H., The Algebraic Eigenvalue Problem, Oxford, Clarendon Press (1965).
5) Rutishauser, H., Interference With an Algol-Procedure, Annual Review in Automatic Programming, Vol. 2 (R. Goodman, Ed.), Pergamon Press, (1961).
6) This publication. (Reference retained to resolve User Guide pointers, thus enabling compatibility with distributed documentation.)
7) Boyle, J.M. and Grau, A.Ao, Modular Design of a User- Oriented Control Program for EISPACK, Applied Mathematics Division Technical Memorandum No. 242, Argonne National Laboratory, Argonne, Illinois 60439, November 1973.
5. PROGRAM STATISTICS.
A. Additional Entry Point Names in EISPAC.
The entry point names listed below are entry point names in the part of EISPAC loaded with your program. Your program must not include other subroutines or functions having any of these names:
BAND, COREEP, EERMEP, EIDFEP, EISPAC, ERROR, FIDFEP, LINKEP, MATA, MATB, MATRIX, METHOD, SUBR, SUPVEP, VALUES, VECTOR.
550
7.2-28
In addition, the other phases of EISPAC contain entry points with the names DGNHEP, DGSHEP, DIDFEP, DSNHEP, EGNHEP, EGSHEP, ERMSEP, ERSEP, ESNHEP, FIDFEP, IBCMEP, IBCOM#, ICHREP, INTREP, and LKUPEP. These entry points will not, however, conflict with those in your program, since these phases are loaded dynamically.
B. Common Storage.
None.
C. Space Requirements.
The parts of EISPAC loaded with your program (subroutine EISPAC and the supervisor) require 2738 (HEX) = 10040 (DECIMAL) bytes under FORTRAN H, OPT=2, Release 21.7 of 0S/360. However, EISPAC requires an additional amount of storage for the dynamically loaded subroutines and the temporary arrays some of them require. At a minimum, this requirement is 2EA0 (HEX) = 11936 (DECIMAL) bytes for the parameter- interpreter phase of EISPAC. During execution, up to 3100 (HEX) = 12544 (DECIMAL) bytes are required for the appropriate execution phase of EISPAC and a typical EISPACK subroutine, plus whatever additional storage is needed for dynamically allocated temporary arrays. See (I) and (2) for further information for estimating this dynamically-determined amount of storage.
6. CHECKOUT.
A. Test Cases.
EISPAC has been tested on the same matrices as have the separate EISPACK subroutines. See Section 3 -- "VALIDATION OF EISPACK".
B. Accuracy.
The accuracy of EISPAC depends directly upon the subroutines used from the EISPACK package (2). Consult the path chart (i) to learn which subroutines have been selected, and then reference the separate accuracy statements that apply to these subroutines.
551