LAPACK95 Users' Guide (Software, Environments and Tools)

LAPACK95 USERS' GUIDE

SOFTWARE.ENVIRONMENTS.TOOLS The series includes handbooks and software guides as well as monographs on practical implementation of computational methods, environments, and tools. The focus is on making recent developments available in a practical format to researchers and other users of these methods and tools.

Editor-in-Chief Jack J. Dongarra University of Tennessee and Oak Ridge National Laboratory

Editorial Board James W. Demmel, University of California, Berkeley Dennis Gannon, Indiana University Eric Grosse, AT&T Bell Laboratories Ken Kennedy, Rice University Jorge J. Moré, Argonne National Laboratory

Software, Environments, and Tools V. A. Barker, L. S. Blackford, J. Dongarra, J. Du Croz, S. Hammarling, M. Marinova, J. Wasniewski, and P. Yalamov, LAPACK95 Users' Guide Stefan Goedecker and Adolfy Hoisie, Performance Optimization of Numerically Intensive Codes Zhaojun Bai, James Demmel, Jack Dongarra, Axel Ruhe, and Henk van der Vorst, Templates for the Solution of Algebraic Eigenvalue Problems: A Practical Guide Lloyd N. Trefethen, Spectral Methods in MATLAB E. Anderson, Z. Bai, C. Bischof, S. Blackford, J. Demmel, J. Dongarra, J. Du Croz, A. Greenbaum, S. Hammarling, A. McKenney, and D. Sorensen, LAPACK Users' Guide, Third Edition Michael W. Berry and Murray Browne, Understanding Search Engines: Mathematical Modeling and Text Retrieval Jack J. Dongarra, lain S. Duff, Danny C. Sorensen, and Henk A. van der Vorst, Numerical Linear Algebra for High-Performance Computers R. B. Lehoucq, D. C. Sorensen, and C. Yang, ARPACK Users' Guide: Solution of Large-Scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods Randolph E. Bank, PLTMG: A Software Package for Solving Elliptic Partial Differential Equations, Users' Guide 8.0 L. S. Blackford, J. Choi, A. Cleary, E. D'Azevedo, J. Demmel, I. Dhillon, J. Dongarra, S. Hammarling, G. Henry, A. Petitet, K. Stanley, D. Walker, and R. C. Whaley, ScaLAPACK Users' Guide Greg Astfalk, editor, Applications on Advanced Architecture Computers Françoise Chaitin-Chatelin and Valerie Frayssé, Lectures on Finite Precision Computations Roger W. Hockney, The Science of Computer Benchmarking Richard Barrett, Michael Berry, Tony F. Chan, James Demmel, June Donato, Jack Dongarra, Victor Eijkhout, Roldan Pozo, Charles Romine, and Henk van der Vorst, Templates for the Solution of Linear Systems: Building Blocks for Iterative Methods E. Anderson, Z. Bai, C. Bischof, J. Demmel, J. Dongarra, J. Du Croz, A. Greenbaum, S. Hammarling, A. McKenney, S. Ostrouchov, and D. Sorensen, LAPACK Users' Guide, Second Edition Jack J. Dongarra, lain S. Duff, Danny C. Sorensen, and Henk van der Vorst, Solving Linear Systems on Vector and Shared Memory Computers J. J. Dongarra, J. R. Bunch, C. B. Moler, and G. W. Stewart, Unpack Users' Guide

LAPACK95 USERS' GUIDE V. A. BARKER L. S. BLACKFORD J. DONGARRA J. Du CROZ S. HAMMARLING M. MARINOVA J. WASNIEWSKI P. YALAMOV

SOCIETY FOR INDUSTRIAL AND APPLIED MATHEMATICS PHILADELPHIA

Copyright © 2001 by the Society for Industrial and Applied Mathematics. 10987654321 All rights reserved. Printed in the United States of America. No part of this book may be reproduced, stored, or transmitted in any manner without the written permission of the publisher. For information, write to the Society for Industrial and Applied Mathematics, 3600 University City Science Center, Philadelphia, PA 19104-2688. No warranties, express or implied, are made by the publisher, authors, and their employers that the programs contained in this volume are free of error. They should not be relied on as the sole basis to solve a problem whose incorrect solution could result in injury to person or property. If the programs are employed in such a manner, it is at the user's own risk and the publisher, authors, and their employers disclaim all liability for such misuse. Library of Congress Cataloging-in-Publication Data LAPACK95 users' guide / V. A. Barker... [et al.]. p. cm. - (Software, environments, and tools) Includes bibliographical references and index. ISBN 0-89871-504-0 (pbk.) 1. FORTRAN (Computer program language) 2. Subroutines (Computer programs) 3. LAPACK I. Barker, V. A. (Vincent Allan), 1934- II. Software, environments, tools QA76.73.F25 L36 2001 512'.5'02855369--dc21

2001042995 This book is also available in html form over the Internet. To view the html file use the following URL: http://www.netlib.org/lapack95/lug95/

Royalties from the sale of this book are placed in a fund to help students attend SIAM meetings and other SIAM-related activities. This fund is administered by SIAM, and qualified individuals are encouraged to write directly to SIAM for guidelines.

is a registered trademark.

Authors' Affiliations: V.A. Barker Technical University of Denmark, Lyngby, Denmark L.S. Blackford University of Tennessee, USA J. Dongarra University of Tennessee, USA J. Du Croz Numerical Algorithms Group Ltd., Oxford, UK (retired) S. Hammarling Numerical Algorithms Group Ltd., Oxford, UK M. Marinova Danish Computing Center for Research and Education UNI • C, Lyngby, Denmark J. Wasniewski Danish Computing Center for Research and Education UNI • C, Lyngby, Denmark P. Yalamov University of Rousse, Bulgaria

This page intentionally left blank

Contents xvii

Preface

I

GENERAL INFORMATION

1

1 Essentials

3

1.1 LAPACK95

3

1.2

3

Problems that LAPACK95 can Solve

1.3 Computers for which LAPACK95 is Suitable

4

1.4

4

LAPACK and the BLAS

1.5 Availability and Installation of Software 1.5.1

4

LAPACK95

4

1.5.1.1

5

Incorporating Machine Dependencies

1.5.2

LAPACK

6

1.5.3

BLAS

7

1.5.4

Installation Debugging Hints

8

1.5.5

Mirror Repositories of netlib

8

1.5.6

Availability of Software via CD-ROM

8

1.6

Support

9

1.7

Commercial Use

9

2 Contents of LAPACK95 2.1

11

Structure of LAPACK95

11

2.1.1

11

Levels of Routines vii

viii

Contents

2.2

2.1.2

Data Types and Precision

11

2.1.3

Naming Scheme

12

Driver Routines

13

2.2.1

Linear Equations

13

2.2.2

Linear Least Squares (LLS) Problems

13

2.2.3

Generalized Linear Least Squares (LSE and GLM) Problems

15

2.2.4

Standard Eigenvalue and Singular Value Problems

16

2.2.4.1

Symmetric Eigenproblems (SEP)

16

2.2.4.2

Nonsymmetric Eigenproblems (NEP)

17

2.2.4.3

Singular Value Decomposition (SVD)

18

2.2.5

Generalized Eigenvalue and Singular Value Problems

18

2.2.5.1

Generalized Symmetric Definite Eigenproblems (GSEP)

18

2.2.5.2

Generalized Nonsymmetric Eigenproblems (GNEP)

20

2.2.5.3

Generalized Singular Value Decomposition (GSVD)

21

3 Documentation Design and Program Examples

25

3.1 Design of the LAPACK95 Driver Interface

25

3.2 Design and Documentation of Driver Argument Lists

26

3.2.1

Structure of the Documentation

26

3.2.2

Order of Arguments

27

3.2.3

Argument Descriptions

27

3.2.4

Optional Arguments

28

3.2.5

Array Arguments

28

3.3 Error Handling

28

3.4

30

Matrix Storage Schemes

3.5 Design of Interfaces for Computational Routines

30

3.6 How to call an LAPACK95 Routine

31

3.7

33

Code for One Version of LA_SYEV

3.8 LAPACK and LAPACK95 Interface Module Blocks 3.8.1

F77-LAPACK Generic Interface Blocks

35 35

ix

Contents

3.8.2

3.8.3

3.8.1.1

LA_SYEV/LA_HEEV

35

3.8.1.2

LA_GESV Multiple RHS Case

37

3.8.1.3

LA.GESV Single RHS Case

37

F95_LAPACK Generic Interface Blocks

38

3.8.2.1

LA_SYEV/LA_HEEV

38

3.8.2.2

LA_GESV

39

LA_LAMCH Interfaces

4 Performance and Troubleshooting 4.1 Performance of LAPACK95

4.2

41 41

4.1.1

Performance Issues

41

4.1.2

Performance Tables

41

Accuracy and Stability

4.3 Errors and Poor Performance

II

40

DRIVER ROUTINES

5 Driver Routines for Linear Systems 5.1 General Linear Systems

. 47 47

49 51 51

5.1.1

LA_GESV

51

5.1.2

LA_GESVX

54

5.1.3

LA_GBSV

57

5.1.4

LA_GBSVX

61

5.1.5

LA_GTSV

65

5.1.6

LA.GTSVX

67

5.2 Symmetric/Hermitian Positive Definite Linear Systems

70

5.2.1

LA_POSV

70

5.2.2

LA_POSVX

73

5.2.3

LA_PPSV

77

5.2.4

LA_PPSVX

79

x

Contents 5.2.5

LA-PBSV

82

5.2.6

LA-PBSVX

85

5.2.7

LA–PTSV

89

5.2.8

LA-PTSVX

91

5.3 Symmetric Indefinite Linear Systems

93

5.3.1

LA_SYSV / LA-HESV

93

5.3.2

LA_SYSVX / LA_HESVX

98

5.3.3

LA_SPSV / LA_HPSV

101

5.3.4

LA_SPSVX / LA_HPSVX

104

6 Driver Routines for Least Squares Problems 6.1 Linear Least Squares Problems

107 107

6.1.1

LA_GELS

107

6.1.2

LA_GELSY

110

6.1.3

LA_GELSS / LA_GELSD

112

6.2 Generalized Linear Least Squares Problems

114

6.2.1

LA_GGLSE

114

6.2.2

LA_GGGLM

116

7 Driver Routines for Standard Eigenvalue Problems 7.1 Standard Symmetric Eigenvalue Problems

119 119

7.1.1

LA_SYEV / LA_HEEV / LA_SYEVD / LA_HEEVD

119

7.1.2

LA_SYEVX / LA_HEEVX

122

7.1.3

LA_SYEVR / LA_HEEVR

124

7.1.4 LA_SPEV / LA_HPEV / LA_SPEVD / LA_HPEVD . .

126

7.1.5

LA_SPEVX / LA_HPEVX

130

7.1.6

LA_SBEV / LA_HBEV / LA_SBEVD / LA_HBEVD

132

7.1.7 LA_SBEVX / LA_HBEVX

135

7.1.8 LA_STEV / LA_STEVD

138

7.1.9

140

LA_STEVX

xi

Contents

7.2

7.1.10 LA-STEVR

142

Standard Nonsymmetric Eigenvalue Problems

145

7.2.1

LA-GEES

145

7.2.2

LA_GEESX

149

7.2.3

LA_GEEV

152

7.2.4

LA_GEEVX

156

8 Driver Routines for Generalized Eigenvalue Problems 8.1 Generalized Symmetric Eigenvalue Problems

8.2

LA_SYGV /LA_SYGVD / LA-HEGV / LA_HEGVD

159

8.1.2

LA-SYGVX / LA-HEGVX

163

8.1.3

LA_SPGV / LA_SPGVD / LA-HPGV / LA_HPGVD

166

8.1.4

LA_SPGVX / LA_HPGVX

171

8.1.5

LA_SBGV / LA_SBGVD / LA-HBGV / LA_HBGVD

174

8.1.6

LA_SBGVX / LA_HBGVX

178

Generalized Nonsymmetric Eigenvalue Problems

181

8.2.1

LA-GGES

181

8.2.2

LA_GGESX

187

8.2.3

LA_GGEV

190

8.2.4

LA_GGEVX

195

9.1 Standard Singular Value Problems 9.1.1

III

159

8.1.1

9 Driver Routines for Singular Value Problems

9.2

159

LA_GESVD / LA_GESDD

201 201 201

Generalized Singular Value Problems

204

9.2.1

204

LA_GGSVD

COMPUTATIONAL ROUTINES

10 Computational Routines 10.1 Computational Routines for Linear Equations

211 213 213

xii

Contents 10.1.1 General Linear Systems

213

10.1.2 Symmetric/Hermitian Positive Definite Linear Systems

216

10.1.3 Symmetric Indefinite Linear Systems

221

10.1.4 Triangular Linear Systems

223

10.2 Computational Routines for Orthogonal Factorizations

226

10.3 Computational Routines for the Symmetric Eigenproblem

229

10.4 Computational Routines for the Nonsymmetric eigenproblem

231

10.5 Computational Routines for the Singular Value Decomposition

234

10.6 Computational Routines for the Generalized Symmetric Definite Eigenproblem . . . 236 10.7 Computational Routines for the Generalized Nonsymmetric Eigenproblem

237

10.8 Computational Routines for the Generalized Singular Value Decomposition

239

Bibliography

239

Index by Keyword

245

Index by Routine Name

256

List of Tables 1.1 Machine constants returned by LA_LAMCH

6

2.1 Matrix types in the LAPACK naming scheme

12

2.2

14

Driver routines for linear equations

2.3 Driver routines for linear least squares problems

15

2.4

16

Driver routines for generalized linear least squares problems

2.5 Driver routines for standard eigenvalue and singular value problems

19

2.6 Driver routines for generalized eigenvalue and singular value problems

23

4.1 Computer used for running the performance timing

42

4.2

Floating point coefficient of operation counts for LAPACK drivers for n x n matrices (see also Table 3.13 of [1]). The number of operations is a x n3

43

4.3

Performance of LA-GESV in megaflops; n = 100 and 1000

43

4.4

Performance of LA-GEEV in megaflops (eigenvalues only); n = 100 and 1000

44

4.5

Performance of LA_GEEV in megaflops (eigenvalues and right eigenvectors); n = 100 and 1000

44

Performance of LA-GESVD in megaflops (singular values and left and right singular vectors); n = 100 and 1000

45

4.7

Performance of LA_GESDD in megaflops (singular values only); n = 100 and 1000

45

4.8

Performance of LA_GESDD in megaflops (singular values and left and right singular vectors); n = 100 and 1000

46

4.6

xm

This page intentionally left blank

List of Figures 3.1 Example program calling an LAPACK95 driver routine

32

3.2

33

Example program calling an LAPACK95 computational routine

xv

This page intentionally left blank

Preface Fortran has always been a principal language in the fields of scientific, numerical, and engineering computing. A series of revisions to the standard defining successive versions of the language has progressively enhanced its power and kept it competitive with several generations of rivals. The present Fortran standard is Fortran 95. The new features contained in Fortran 95 ensure that the Fortran language will continue to be used successfully for a long time to come. The fact that it contains the whole of Fortran 77 as a subset means that conversion to Fortran 95 is as simple as conversion to another Fortran 77 compiler. For more information on Fortran 95, see [31]. The development of LAPACK was a natural step after specifications of the Level 2 and 3 BLAS were drawn up in 1984-86 and 1987-88. Research on block algorithms had been ongoing for several years, but agreement on the BLAS made it possible to construct a new software package, to take the place of LINPACK and EISPACK, which would achieve much greater efficiency on modern high-performance computers. The new package, LAPACK, written in Fortran 77, also contained a number of algorithmic advances that had been made since LINPACK and EISPACK were written in the 1970's. The proposal for LAPACK was submitted while the Level 3 BLAS were still being developed, and funding was obtained from the National Science Foundation (NSF) beginning in 1987. Since its completion, four follow-up projects, LAPACK 2, ScaLAPACK, ScaLAPACK 2 and LAPACK 3 have been funded in the U.S. by the NSF and ARPA in 1990-1994, 1991-1995, 1995-1998, and 1998-2001, respectively. This book describes LAPACK95 [12, 6, 14], yet another step in the development of LAPACK. LAPACK95 is a Fortran 95 interface to the Fortran 77 LAPACK library. It is relevant for anyone who writes in the Fortran 95 language and needs reliable software for basic numerical linear algebra. It may be regarded as a sequel to [1], the official reference for LAPACK, and as such, it assumes a basic knowledge of LAPACK and frequently refers to the LAPACK Users' Guide [1] for specific details. This book is divided into three parts. Part I: GENERAL INFORMATION contains chapters providing a thorough explanation of the design and functionality of the LAPACK95 library. Part II: DRIVER ROUTINES contains detailed specifications of the driver routines, including numerical examples. Part III: COMPUTATIONAL ROUTINES contains brief specifications of the computational routines. A Bibliography is also provided, as well as two indexes- Index by Keyword and Index by Routine Name. A number of technical reports were written during the development of LAPACK95 and published as technical reports at UNI«C, Denmark, and as LAPACK Working Notes by the University of Tennessee. These reports are available in postscript and pdf format. http://www.netlib.org/lapack/lawns/ xvii

xviii

Preface

The performance results presented in this book were obtained using computer resources at the Danish Computing Center for Research and Education, UNI«C. This work was supported by the Danish Natural Science Research Council through a grant for the EPOS project (Efficient Parallel Algorithms for Optimization and Simulation) and by the Oak Ridge National Laboratory, managed by UT/Battelle, LLC for the U.S. Department of Energy, under contract number DE-AC05-96OR22464. The cover was designed by David Rogers at the Innovative Computing Laboratory, Department of Computer Science, University of Tennessee. Finally, we would like to thank all those who have contributed code, criticism, ideas and encouragement. We wish especially to express our gratitude to the LAPACK authors, Bjarne Stig Andersen, Zohair Maany, Antoine Petitet, John Reid, Clint Whaley, and Adam Zemla. The basefiles for the LAPACK95 library are kept in the extract system developed by Clint Whaley. The royalties from the sales of this book are being placed in a fund to help students attend SIAM meetings and other SIAM related activities. This fund is administered by SIAM and qualified individuals are encouraged to write directly to SIAM for guidelines.

Part I

GENERAL INFORMATION

This page intentionally left blank

Chapter 1

Essentials 1.1

LAPACK95

LAPACK95 [6, 14] is a Fortran 95 [31] interface to the Fortran 77 LAPACK library [1]. It improves upon the original user-interface to the LAPACK package, taking advantage of the considerable simplifications which Fortran 95 allows. The design of LAPACK95 exploits assumed-shape arrays, optional arguments, and generic interfaces. The Fortran 95 interface has been implemented by writing Fortran 95 "wrappers" to call existing routines from the LAPACK package. This interface can persist unchanged even if the underlying Fortran 77 LAPACK code is rewritten to take advantage of the new features of Fortran 95. The LAPACK95 home page, which is maintained at netlib [18], is http://www.netlib.org/lapack95/ A list of LAPACK95 Frequently Asked Questions (FAQ) can be found at http://www.netlib.org/lapack95/faq.html

1.2

Problems that LAPACK95 can Solve

LAPACK95 provides interfaces to all LAPACK driver and computational routines. Driver routines are for the major tasks of solving systems of linear equations, linear least squares problems, eigenvalue problems and singular value problems. For details see Chapter 2 and Part II. Computational routines are for smaller computational tasks; each driver typically calls a sequence of computational routines. The computational routines are documented briefly in Part III. As with LAPACK, dense and band matrices are provided for but not general sparse matrices. In all areas, similar functionality is provided for real and complex matrices and single and double precision. 3

4

Chapter 1. Essentials

1.3

Computers for which LAPACK95 is Suitable

Since LAPACK95 is an interface to LAPACK, its efficiency is closely related to that of LAPACK. LAPACK is designed to give high efficiency on vector processors, high-performance "super-scalar" workstations, and shared memory multiprocessors. It can also be used satisfactorily on all types of scalar machines (PC's, workstations, mainframes). Section 4.1.2 gives some examples of the performance achieved by LAPACK with the LAPACK95 interface routines.

1.4

LAPACK and the BLAS

LAPACK routines are written so that as much as possible of the computation is performed by calls to the Basic Linear Algebra Subprograms (BLAS) [30, 16, 15] . Highly efficient machine-specific implementations of the BLAS are available for many modern high-performance computers. Alternatively, machine-specific implementations can be generated using the ATLAS system mentioned in Section 1.5.3 below. The BLAS enable LAPACK routines to achieve high performance with portable code. The methodology for constructing LAPACK routines in terms of calls to the BLAS is described in Chapter 3 of the LAPACK Users' Guide [1].

1.5

Availability and Installation of Software

1.5.1 LAPACK95 The LAPACK95 software can be downloaded from the LAPACK95 home page http://www.netlib.org/lapack95/lapack95.tgz and is also available via ftp as follows: anon ftp to www.netlib.org cd Iapack95 binary get Iapack95.tgz This distribution tar file does NOT contain an LAPACK library or a BLAS library. Note that LAPACK, version 3.0 or later, is required for the installation of LAPACK95. LAPACK95 assumes that an LAPACK library and a BLAS library are installed on the machine to which the user is installing LAPACK95. If either of these libraries is not already installed, refer to the downloading and installation instructions in sections 1.5.2 and 1.5.3, respectively. After downloading the software, the user enters the following command to extract the files: gunzip -c Iapack95.tgz | tar xvf -

1.5. Availability and Installation of Software

5

This will create a top-level directory called LAPACK95 with the following contents: README (file): Contains a description of the LAPACK95 installation procedure. make.inc files for different systems. SRC (directory): Source code for all LAPACK95 routines. TESTING (directory): Procedures for testing the entire LAPACK95 package or individual routines. TIMING (directory): The timing routines that produced the performance results in Chapter 4. EXAMPLESl (directory): Simple program examples for all LAPACK95 driver routines. These programs have been used for the numerical examples in Part II of this Users' Guide. EXAMPLES2 (directory): More program examples; see the README file of this directory for details. To install LAPACK95, the user should proceed as instructed in the README file in the top-level directory. A comprehensive test suite for LAPACK95 is provided, and it is highly recommended that this be run to ensure proper installation of the package. (Refer to the subdirectory TESTING and [13]). The procedure for calling LAPACK95 routines from the user's Fortran 95 program is described in Section 3.6. 1.5.1.1

Incorporating Machine Dependencies

Optimal Value of the Block Size (Function ILAENV) LAPACK95 routines that implement block algorithms rely on the block size specified in the auxiliary enquiry LAPACK function ILAENV. The setting of the parameters in ILAENV is part of the LAPACK installation process, and detailed in the LAPACK Installation Guide [4, 5]. Machine Dependent Constants (Function LA_LAMCH) LAPACK95 provides a function, LAJLAMCH, that returns the values of the machine constants listed in Table 1.1. LA.LAMCH computes these constants the first time it is called in a run. For performance testing, this initial cost can be hidden by including a call to LA_LAMCH in the main program before any calls to the routines that are to be timed. A cleaner, but less portable, alternative is for the installer to save the values computed by LAJLAMCH for a specific machine and create a new version of LA_LAMCH with these constants set in DATA statements, taking care that no accuracy is lost in the translation. The code of LA.LAMCH is listed in Section 3.8.3.

Chapter 1. Essentials

6

Table 1.1: Machine constants returned by LA_LAMCH Argument Constant returned 'E' or V eps: relative machine precision sfmin: safe minimum, such that 1/sfmin does not overflow 'S' or V 'B' or V base: base of the machine 'P' or 'p' prec: eps x base 'N' or V t: number of (base) digits in the mantissa 'R' or V rnd: 1.0 when rounding occurs in addition, 0.0 otherwise 'M' or 'm' emin: minimum exponent before (gradual) underflow 'U' or V rmin: underflow threshold - base6""""1 emax: largest exponent before overflow 'L' or T 'O' or V rmax: overflow threshold - baseemaix(l-eps)

1.5.2 LAPACK The Fortran 77 source code of LAPACK is available at the LAPACK home page http://www.netlib.org/lapack/lapack.tgz http://www.netlib.org/lapack/lapack-pc.zip

- Unix / Linux - PC / Windows

Alternatively, prebuilt LAPACK libraries (in object code) are available from the LAPACK home page for a variety of architectures. http://www.netlib.org/lapack/archives/ LAPACK is available via ftp as follows: • LAPACK (Source code) anon ftp to www.netlib.org cd lapack binary get lapack.tgz

LAPACK archives (Prebuilt libraries) anon ftp to www.netlib.org cd lapack/archives binary Is get the proper lapack-file

Note: LAPACK, version 3.0 or later, is required to install LAPACK95. Installation instructions for LAPACK can be found in the LAPACK Installation Guide[4, 5]. Information on machine-specific installations is contained in the release_notes file, http: //www. netlib. org/lapack/release jaotes. html A comprehensive test suite for LAPACK is provided in the LAPACK distribution. It is highly recommended that this test suite be run to ensure proper installation of the package.

1.5. Availability and Installation of Software

1.5.3

7

BLAS

The BLAS home page is http://www.netlib.org/blas/ There are three sources for the BLAS, as detailed below. Regardless of the origin of the BLAS library selected, the BLAS test suite (available on the BLAS webpage) should be run to ensure proper installation. 1. Vendor or ISV (Independent Software Vendor) BLAS. These can be supplied by default with the computer, or can be available as a separate software package. An optimized BLAS library gives much better performance than the model implementation. For a list of vendor- and ISV-supplied BLAS see http://www.netlib.org/blas/faq.html

2. Automatically Tuned Linear Algebra Software (ATLAS). The ATLAS project uses empirical techniques to automatically optimize software for unknown architectures. The software produced by the ATLAS project provides a complete, highly optimized BLAS for almost all cache-based architectures, and includes standard Fortran 77 and ANSI C APIs for all routines. For installation, ATLAS requires an ANSI C compiler, and access to Unix-like build tools such as make. ATLAS runs on all versions of Unix and Windows. The performance of ATLAS is on par with the best hand-coded implementations on all known architectures. See [43], and the links given below, for further details. http://www.netlib.org/atlas/ Prebuilt ATLAS libraries are available for a variety of architectures. http://www.netlib.org/atlas/archives/ ATLAS is available via ftp as follows: ATLAS (Source code and documentation) anon ftp to www.netlib.org cd atlas binary get atlas_.tgz

ATLAS archives (Prebuilt libraries) anon ftp to www.netlib.org cd atlas/archives binary Is

get the proper atlas-file

where denotes the current version of the software. 3. The model implementation. This package is available at http://www.netlib.org/blas/bias.tgz

8

Chapter 1. Essentials and is available via ftp as follows: anon ftp to www.netlib.org cd bias binary get blas.tgz This file contains the Fortran 77 reference implementation of the Level 1, Level 2 and Level 3 BLAS routines in all precisions. The routines must be compiled by the local Fortran compiler, and archived into a library, e.g., libblas.a. It should be emphasized that the performance achieved using this version of the BLAS will not be as high as could be obtained with a machine-specific implementation. N.B. The model implementation is also included in the LAPACK distribution file.

1.5.4

Installation Debugging Hints

If the user encounters difficulty in the installation process then he should: Consult the FAQ lists at the home pages of the BLAS, LAPACK and LAPACK95. Consult the release-notes files at the same home pages. These files contain lists of known difficulties that have been diagnosed and corrected (or will be corrected in the next release), or reported to the vendor in the case of machine-specific BLAS. Check the installation of machine dependencies. Try the model implementation BLAS (Section 1.5.3) if he is using machine-specific BLAS. Discuss the problem with the system administrator (if there is one). Contact the developers of LAPACK95 at the Email address in Section 1.6. 1.5.5

Mirror Repositories of netlib

There are a number of mirror repositories of netlib located around the world. A list of these sites is maintained at http://www.netlib.org/bib/mirrors.html LAPACK95, LAPACK, and the BLAS (model implementation and ATLAS), can be obtained from any of these websites. 1.5.6

Availability of Software via CD-ROM

A subset of netlib software, including LAPACK95, LAPACK, and the BLAS (model implementation and ATLAS), is available on CD-ROM from

9

1.6. Support Prime Time Free-ware 370 Altair Way, Suite 150 Sunnyvale, CA 94086, USA http://www.ptf.com/ [email protected] Tel: +1 408-433-9662 Fax: +1 408-433-0727

1.6

Support

LAPACK95 has been tested on many types of computers. The LAPACK95 project supports the package in the sense that reports of errors or poor performance will gain the attention of the developers, as will questions regarding any aspect of the package. All correspondence should be directed by Email to [email protected] Naturally, the developers cannot support modifications to the software made by others.

1.7

Commercial Use

Since LAPACK95 is freely available, it can be included in commercial packages. It is requested only that proper credit be given to the authors by citing this Users' Guide as the official reference for LAPACK95. Like all software, this package is copyrighted. It is not trademarked; however, if modifications are made that affect the interface, functionality, or accuracy of the resulting software, the name of the routine should be changed. Any modification to the software should be noted in the modifier's documentation.

This page intentionally left blank

Chapter 2

Contents of LAPACK95 Structure of LAPACK95

2.1

LAPACK95 provides a Fortran 95 interface to LAPACK drivers and generic interfaces to LAPACK computational routines. Descriptions of the two types of interfaces are documented in Parts II and III, respectively.

2.1.1

Levels of Routines

The subroutines are classified as follows: driver routines, each of which solves a complete problem, for example solving a system of linear equations, or computing the eigenvalues of a real symmetric matrix. Users are recommended to use a driver routine if there is one that meets their requirements. The driver routines are listed in Section 2.2 and documented in Part II. computational routines, each of which performs a distinct computational task, for example an LU factorization, or the reduction of a real symmetric matrix to tridiagonal form. Each driver routine calls a sequence of computational routines. Users (especially software developers) may need to call computational routines directly to perform tasks, or sequences of tasks, that cannot conveniently be performed by the driver routines. The computational routines are documented in Part III. auxiliary routines, which are primarily for internal use. These are not documented in this book.

2.1.2

Data Types and Precision

LAPACK95 driver and computational routines do not distinguish between real and complex data types or between single and double precision. To handle different precisions, a module block, 11

12

Chapter 2. Contents of LAPACK95

la-precision.mod, is used to define named constants SP and DP for the KIND values of single and double precision, respectively: MODULE LA .PRECISION INTEGER, PARAMETER :: SP=KIND(1.0), DP=KIND(1.0DO) END MODULE LA .PRECISION In LAPACK95, all real and complex constructs are expressed in terms of a symbolic KIND value WP, which is defined by reference to the module la-precision.mod as follows: USE LAJPRECISION :: WP ==> SP

- single precision

USE LAJPRECISION :: WP => DP

- double precision

For examples of use see Section 3.6.

2.1.3 Naming Scheme The name of each LAPACK95 routine has been made as similar as possible to its name in LAPACK. All driver and computational routines have names of the form LA.YYZZZ, where for some routines the 8th character is blank. The two letters YY indicate the type of matrix (or of the most significant matrix). Most of these two-letter codes apply to both real and complex matrices; a few apply specifically to one or the other, as indicated in Table 2.1. Table 2.1: Matrix types in the LAPACK naming scheme GB GE GG GT HB HE HP PB PO PP PT SB SP ST SY

general band general (i.e., unsymmetric, in some cases rectangular) general matrices, generalized problem (i.e., a pair of general matrices) general tridiagonal (complex) Hermitian band (complex) Hermitian (complex) Hermitian, packed storage symmetric or Hermitian positive definite band symmetric or Hermitian positive definite symmetric or Hermitian positive definite, packed storage symmetric or Hermitian positive definite tridiagonal (real) symmetric band symmetric, packed storage (real) symmetric tridiagonal symmetric

When we wish to refer to a class of routines that perform the same function on different types of

2.2. Driver Routines

13

matrices, we replace the two letters by "yy". Thus LA_yySV refers to all the simple driver routines for systems of linear equations that are listed in Table 2.2. The last three letters ZZZ indicate the computation performed.

2.2

Driver Routines

This section describes the driver routines in LAPACK95.

2.2.1

Linear Equations

Two types of driver routines are provided for solving systems of linear equations: the simple driver (name ending -SV) solves the system AX — B by factorizing A and overwriting B with the solution X; the exoert driver (name endine -SVX) can also oerform the following functions: — solve ATX — B or AHX — B (unless A is symmetric or Hermitian); — estimate the condition number of A, check for near-singularity, and check for pivot growth; — refine the solution and compute forward and backward error bounds; — equilibrate the system if A is poorly scaled. The expert driver requires roughly twice as much storage as the simple driver. Both types of driver routines handle single or multiple right hand sides by allowing B to be a vector or matrix, respectively. Different driver routines are provided to take advantage of special properties or storage schemes of the matrix A, as shown in Table 2.2.

2.2.2

Linear Least Squares (LLS) Problems

The linear least squares problem is:

where A is an m x n matrix, b is a given m element vector and x is the n element solution vector. In the most usual case m > n and rank(A) = n, and in this case the solution to problem (2.1) is unique, and the problem is also referred to as finding a least squares solution to an overdetermined system of linear equations. When m < n and rank(A) = m, there are an infinite number of solutions x which exactly satisfy 6 — Ax = 0. In this case it is often useful to find the unique solution x which minimizes ||x||2, and the problem is referred to as finding a minimum norm solution to an underdetermined system of linear equations. The driver routine LA_GELS solves problem (2.1) on the assumption that rank(A) = min(ra,n)

14

Chapter 2. Contents of LAPACK95 Table 2.2: Driver routines for linear equations Type of matrix and storage scheme General dense Real / complex General band Real / complex General tridiagonal Real / complex Positive definite full storage Real symmetric / complex Hermitian Positive definite packed storage Real symmetric / complex Hermitian Positive definite band storage Real symmetric / complex Hermitian Positive definite tridiagonal Real symmetric / complex Hermitian Indefinite full storage Real symmetric / complex symmetric / complex Hermitian Indefinite packed storage Real symmetric / complex symmetric / complex Hermitian

Simple driver LA_GESV

Expert driver LA_GESVX

LA_GBSV

LA_GBSVX

LA_GTSV

LA_GTSVX

LA_POSV

LAJPOSVX

LA_PPSV

LA.PPSVX

LA.PBSV

LA_PBSVX

LA_PTSV

LA_PTSVX

LA_SYSV / LA_HESV

LA_SYSVX / LA.HESVX

LA_SPSV / LA_HPSV

LA_SPSVX / LA_HPSVX

— in other words, A has full rank — finding a least squares solution of an overdetermined system when m > n, and a minimum norm solution of an underdetermined system when m < n. LA_GELS uses a QR or LQ factorization of A, and also allows A to be replaced by AT in the statement of the problem (or by AH if A is complex). In the general case when we may have rank(A) < min(ra, n) — in other words, A may be rankdeficient — we seek the minimum norm least squares solution x which minimizes both \\x\\2 and ||6 - Ax\\2The driver routines LA_GELSY, LA.GELSS, and LA_GELSD, solve this general formulation of problem (2.1), allowing for the possibility that A is rank-deficient; LA-GELSY uses a complete orthogonal factorization of A, while LA_GELSS uses the singular value decomposition of A, and LA_GELSD uses the singular value decomposition of A with an algorithm based on divide and conquer. The subroutine LA.GELSD is significantly faster than its older counterpart LA_GELSS, especially for large problems, but may require somewhat more workspace depending on the matrix dimensions. The LLS driver routines are listed in Table 2.3. All four routines allow several right hand side vectors b and corresponding solutions x to be

15

2.2. Driver Routines

handled in a single call, storing these vectors as columns of matrices B and X, respectively. Note however that problem (2.1) is solved for each right hand side vector independently; this is not the same as finding a matrix X which minimizes Table 2.3: Driver routines for linear least squares problems Operation solve LLS using QR or LQ factorization solve LLS using complete orthogonal factorization solve LLS using SVD solve LLS using divide-and-conquer SVD

2.2.3

real/complex LA_GELS LA_GELSY LA_GELSS LA.GELSD

Generalized Linear Least Squares (LSE and GLM) Problems

Driver routines are provided for two types of generalized linear least squares problems. The first is

where A is an m x n matrix and B is a p x n matrix, c is a given ra-vector, and d is a given p-vector, with p < n < m + p. This is called a linear equality-constrained least squares problem (LSE). The routine LA.GGLSE solves this problem using the generalized RQ (GRQ) I A \ factorization, on the assumptions that B has full row rank p and the matrix has full column \B ) rank n. Under these assumptions, the problem LSE has a unique solution. The second generalized linear least squares problem is

where A is an n x m matrix, B is an n x p matrix, and d is a given n-vector, with ra < n < m + p. This is sometimes called a general (Gauss-Markov) linear model problem (GLM). When B = /, the identity matrix, the problem reduces to an ordinary linear least squares problem. When B is square and nonsingular, the GLM problem is equivalent to the weighted linear least squares problem:

The routine LA_GGGLM solves this problem using the generalized QR (GQR) factorization, on the assumptions that A has full column rank m and the matrix (A, B) has full row rank n. Under these assumptions, the problem is always consistent, and there are unique solutions x and y. The driver routines for generalized linear least squares problems are listed in Table 2.4.

16

Chapter 2. Contents of LAPACK95 Table 2.4: Driver routines for generalized linear least squares problems Operation solve LSE problem using GRQ solve GLM problem using GQR

2.2.4

real/complex LA.GGLSE LA.GGGLM

Standard Eigenvalue and Singular Value Problems

2.2.4.1

Symmetric Eigenproblems (SEP)

The symmetric eigenvalue problem is to find the eigenvalues, A, and corresponding eigenvectors, z •£ 0, such that For the Hermitian eigenvalue problem we have

For both problems the eigenvalues A are real. When all eigenvalues and eigenvectors have been computed, we write:

where A is a diagonal matrix whose diagonal elements are the eigenvalues, and Z is an orthogonal (or unitary) matrix whose columns are the eigenvectors. This is the classical spectral factorization of A There are four types of driver routines for symmetric and Hermitian eigenproblems, and these are listed below. Originally LAPACK had just the first two (the simple and expert drivers), and the last two were added after improved algorithms were discovered. Ultimately we expect the algorithm in the most recent driver (called RRR below) to supersede all the others, but in LAPACK 3.0 the other drivers may still be faster on some problems, so we retain them. A simple driver (name ending -EV) computes all the eigenvalues and (optionally) eigenvectors. An expert driver (name ending -EVX) computes all or a selected subset of the eigenvalues and (optionally) eigenvectors. If few enough eigenvalues or eigenvectors are desired, the expert driver is faster than the simple driver. A divide-and-conquer driver (name ending -EVD) solves the same problem as the simple driver. It is much faster than the simple driver for large matrices, but uses more workspace. The name divide-and-conquer refers to the underlying algorithm (see sections 2.4.4 and 3.4.3 in the LAPACK Users' Guide[l]). A relatively robust representation (RRR) driver (name ending -EVR) computes all or (in a later release) a subset of the eigenvalues, and (optionally) eigenvectors. It is the fastest algorithm of all (except for a few cases), and uses the least workspace. The name RRR refers to the underlying algorithm (see sections 2.4.4 and 3.4.3 in the LAPACK Users' Guidefl]).

2.2. Driver Routines

17

Different driver routines are provided to take advantage of special structure or storage of the matrix A, as shown in Table 2.5. 2.2.4.2

Nonsymmetric Eigenproblems (NEP)

The nonsymmetric eigenvalue problem is to find the eigenvalues, A, and corresponding eigenvectors, v ^ 0, such that A real matrix A may have complex eigenvalues, occurring as complex conjugate pairs. More precisely, the vector v is called a right eigenvector of A, and a vector u ^ 0 satisfying

is called a left eigenvector of A. This problem can be solved via the Schur factorization of A, defined in the real case as

where Z is an orthogonal matrix and T is an upper quasi-triangular matrix with 1 x 1 and 2 x 2 diagonal blocks, the 2 x 2 blocks corresponding to complex conjugate pairs of eigenvalues of A. In the complex case the Schur factorization is

where Z is unitary and T is a complex upper triangular matrix. The columns of Z are called the Schur vectors. For each k (I < k < n), the first k columns of Z form an orthonormal basis for the invariant subspace corresponding to the first k eigenvalues on the diagonal of T. Because this basis is orthonormal, it is preferable in many applications to compute Schur vectors rather than eigenvectors. It is possible to order the Schur factorization so that any desired set of k eigenvalues occupy the k leading positions on the diagonal of T. Two pairs of drivers are provided, one pair focusing on the Schur factorization, and the other pair on the eigenvalues and eigenvectors as shown in Table 2.5: LA_GEES: a simple driver that computes all or part of the Schur factorization of A, with optional ordering of the eigenvalues; LA-GEESX: an expert driver that can additionally compute condition numbers for the average of a selected subset of the eigenvalues, and for the corresponding right invariant subspace; LA_GEEV: a simple driver that computes all the eigenvalues of A, and (optionally) the right or left eigenvectors (or both); LA_GEEVX: an expert driver that can additionally balance the matrix to improve the conditioning of the eigenvalues and eigenvectors, and compute condition numbers for the eigenvalues or right eigenvectors (or both).

18

Chapter 2. Contents of LAPACK95

2.2.4.3

Singular Value Decomposition (SVD)

The singular value decomposition of an m x n matrix A is given by

where U and V are orthogonal (unitary) and S is an m x n diagonal matrix with real diagonal elements, <7j, such that The 0{ are the singular values of A and the first min(ra, n) columns of U and V are the left and right singular vectors of A. The singular values and singular vectors satisfy:

where Ui and Vi are the ith columns of U and V respectively. There are two types of driver routines for the SVD. Originally LAPACK had just the simple driver described below, and the other one was added after an improved algorithm was discovered. a simple driver LA_GESVD computes all the singular values and (optionally) left and/or right singular vectors. a divide and conquer driver LA_GESDD solves the same problem as the simple driver. It is much faster than the simple driver for large matrices, but uses more workspace. The name divide-and-conquer refers to the underlying algorithm (see sections 2.4.4 and 3.4.3 in the LAPACK Users' Guidefl]).

2.2.5 2.2.5.1

Generalized Eigenvalue and Singular Value Problems Generalized Symmetric Definite Eigenproblems (GSEP)

Drivers are provided to compute all the eigenvalues and (optionally) the eigenvectors of the following types of problems:

where A and B are symmetric or Hermitian and B is positive definite. For all these problems the eigenvalues A are real. The matrices Z of computed eigenvectors satisfy ZT AZ = A (problem types 1 and 3) or Z~1AZ~T = I (problem type 2), where A is a diagonal matrix with the eigenvalues on the diagonal. Z also satisfies ZTBZ = / (problem types 1 and 2) or ZTB~1Z — I (problem type 3). There are three types of driver routines for generalized symmetric and Hermitian eigenproblems. Originally LAPACK had just the simple and expert drivers described below, and the third driver was added after an improved algorithm was discovered.

2.2. Driver Routines

19

Table 2.5: Driver routines for standard eigenvalue and singular value problems Type of problem SEP

NEP

SVD

Function and storage scheme

Real/complex

simple driver divide and conquer driver expert driver RRR driver simple driver (packed storage) divide and conquer driver (packed storage) expert driver (packed storage) simple driver (band matrix) divide and conquer driver (band matrix) expert driver (band matrix) simple driver (tridiagonal matrix) divide and conquer driver (tridiagonal matrix) expert driver (tridiagonal matrix) RRR driver (tridiagonal matrix) simple driver for Schur factorization expert driver for Schur factorization simple driver for eigenvalues/vectors expert driver for eigenvalues/vectors simple driver divide and conquer driver

LA_SYEV LA_SYEVD LA_SYEVX LA_SYEVR LA_SPEV LA_SPEVD

Complex Hermitian LA_HEEV LA_HEEVD LAJIEEVX LA_HEEVR LA_HPEV LA_HPEVD

LA_SPEVX LA_SBEV LA_SBEVD

LA_HPEVX LA_HBEV LA_HBEVD

LA_SBEVX LA_STEV LA_STEVD (real only) LA_STEVX LA_STEVR LAJ3EES LA_GEESX LA_GEEV LA_GEEVX LA_GESVD LA_GESDD

LA_HBEVX

a simple driver (name ending -GV) computes all the eigenvalues and (optionally) eigenvectors. an expert driver (name ending -GVX) computes all or a selected subset of the eigenvalues and (optionally) eigenvectors. If few enough eigenvalues or eigenvectors are desired, the expert driver is faster than the simple driver. a divide-and-conquer driver (name ending -GVD) solves the same problem as the simple driver. It is much faster than the simple driver for large matrices, but uses more workspace. The name divide-and-conquer refers to the underlying algorithm (see sections 2.4.4 and 3.4.3 in the LAPACK Users' Guidejl]). Different driver routines are provided to take advantage of special structure or storage of the matrices A and J5, as shown in Table 2.6.

Chapter 2. Contents of LAPACK95

20

2.2.5.2

Generalized Nonsymmetric Eigenproblems (GNEP)

Given a matrix pair (A, B), where A and B are square n x n matrices, the generalized nonsymmetric eigenvalue problem is to find the eigenvalues A and corresponding eigenvectors x ^ 0 such that or to find the eigenvalues p, and corresponding eigenvectors y ^ 0 such that

Note that these problems are equivalent with y, — I/A and x = y if neither A nor p. is zero. In order to deal with the case that A or /j, is zero, or nearly so, the LAPACK routines return two values, a and /3, for each eigenvalue, such that A = a//3 and p, = fi/a. More precisely, x and y are called right eigenvectors. Vectors u ^ 0 or v ^ 0 satisfying

are called left eigenvectors. Sometimes the following, equivalent, notation is used to refer to the generalized eigenproblem for the pair (A, B}\ The object A — \B, where A is a complex scalar variable, is called a matrix pencil, or just pencil. So one can also refer to the generalized eigenvalues and eigenvectors of the pencil A — \B. If the determinant of A — \B is identically zero for all values of A, the eigenvalue problem is called singular; otherwise it is regular. Singularity of (A, B] is signaled by some a = /3 = 0 (in the presence of roundoff, a and j3 may be very small). In this case, the eigenvalue problem is very ill-conditioned, and in fact some of the other nonzero values of a and /3 may be indeterminate (see section 4.11.1.4 in the LAPACK Users' Guideflj) for further discussion) [38, 44, 10]. The current routines in LAPACK are intended only for regular matrix pencils. The generalized nonsymmetric eigenvalue problem can be solved via the generalized Schur decomposition of the matrix pair (A, 5), defined in the real case as

where Q and Z are orthogonal matrices, T is upper triangular, and S is an upper quasi-triangular matrix with 1 x 1 and 2 x 2 diagonal blocks, the 2 x 2 blocks corresponding to complex conjugate pairs of eigenvalues of (A, B). In the complex case, the generalized Schur decomposition is

where Q and Z are unitary and S and T are both upper triangular. The columns of Q and Z are called left and right generalized Schur vectors and span pairs of deflating subspaces of A and B [38]. Deflating subspaces are a generalization of invariant subspaces: For each k (1 < k < n), the first k columns of Z span a right deflating subspace mapped by both A and B into a left deflating subspace spanned by the first k columns of Q. More formally, let Q = (Q\, Qz) and Z = (Z\, Z^) be a conformal partitioning with respect to

2.2. Driver Routines

21

the cluster of A: eigenvalues in the (l,l)-block of (5, T), i.e. where Q\ and Z\ both have k columns, and 5>n and Tn below are both k x k.

Then subspaces £ — span(Qi) and 7£ — span(Zi) form a pair of (left and right) deflating subspaces associated with the cluster of (Su,Tu), satisfying C — AR + B'R, and dim(£) = dim(7?.) [39, 40]. It is possible to order the generalized Schur form so that (5n,Tn) has any desired subset of k eigenvalues, taken from the set of n eigenvalues of (S,T). As for the standard nonsymmetric eigenproblem, two pairs of drivers are provided, one pair focusing on the generalized Schur decomposition, and the other pair on the eigenvalues and eigenvectors as shown in Table 2.6: LA_GGES: a simple driver that computes all or part of the generalized Schur decomposition of (A. B), with optional ordering of the eigenvalues: LA-GGESX: an expert driver that can additionally compute condition numbers for the average of a selected subset of eigenvalues, and for the corresponding pair of deflating subspaces of A and B: LA_GGEV: a simple driver that computes all the generalized eigenvalues of (A,B), and optionally the left or right eigenvectors (or both); LA_GGEVX: an expert driver that can additionally balance the matrix pair to improve the conditioning of the eigenvalues and eigenvectors, and compute condition numbers for the eigenvalues and/or left and right eigenvectors (or both). To save space in Table 2.6, the word "generalized" is omitted before Schur decomposition, eigenvalues/vectors and singular values/vectors. 2.2.5.3

Generalized Singular Value Decomposition (GSVD)

The generalized (or quotient) singular value decomposition of an m x n matrix A and a p x n matrix B is given by the pair of factorizations

The matrices in these factorizations have the following properties: U is m x m, V is p x p, Q is n x n, and all three matrices are orthogonal. If A and B are complex, these matrices are unitary instead of orthogonal, and QT should be replaced by QH in the pair of factorizations. R is r x r, upper triangular and nonsingular. [0, R] is r x n (in other words, the 0 is an /A \ r x (n — r) zero matrix). The integer r is the rank of „ I , and satisfies r < n.

\ ' £1 is m x r, £2 is p x r, both are real, nonnegative and diagonal, and £^£1 + £^£2 = ^' Write £f £1 = diag(af,..., 0%) and £^£2 = di a g(/?i,..., /3jr), where ai and /% lie in the interval from 0 to 1. The ratios ai//3i,..., ar/{3T are called the generalized singular values of the pair A, B, If /% = 0, then the generalized singular value at/fa is infinite.

22

Chapter 2. Contents of LAPACK95

EI and £2 have the following detailed structures, depending on whether m — r > 0 or m — r < 0. In the first case, m — r > 0, then

Here / is the rank of 5, k — r — /, C and 5 are diagonal matrices satisfying C2 + S2 = /, and S is nonsingular. We may also identify cti = • • • = a^ = 1, ot^+i = ca for i = 1,..., /, fi\ — • • • = fa — 0, and f3k+i = Sjz for i = 1,..., /. Thus, the first k generalized singular values ai/Pi,..., otk//3k are infinite, and the remaining / generalized singular values are finite. In the second case, when m — r < 0,

and

Again, / is the rank of B, k — r — /, C and S are diagonal matrices satisfying C2 + S2 = /, 5 is nonsingular, and we may identify a\ = • • • = otk = 1, &k+i — ca for i = l , . . . , m — A;, «m+i = • • • = ar = 0, /?! = • • • = ^ = 0, j3k+i = sa for i = 1,..., m - k, and ^m+i = • • • = (3r = 1. Thus, the first A; generalized singular values a\lfi\,... ,&k/l3k are infinite, and the remaining / generalized singular values are finite. Here are some important special cases of the generalized singular value decomposition. First, if B is square and nonsingular, then r — n and the generalized singular value decomposition of A and B is equivalent to the singular value decomposition of AB~l, where the singular values of AB~l are equal to the generalized singular values of the pair A, B:

Second, if the columns of (AT BT}T are orthonormal, then r = n, R — I and the generalized singular value decomposition of A and B is equivalent to the CS (Cosine-Sine) decomposition of (AT BT}T [20]:

Third, the generalized eigenvalues and eigenvectors of A A — \B B can be expressed in terms of the generalized singular value decomposition: Let

2.2. Driver Routines

23

Table 2.6: Driver routines for generalized eigenvalue and singular value problems Type of problem GSEP

GNEP

|| GSVD

Function and storage scheme

Real/complex

simple driver divide and conquer driver expert driver simple driver (packed storage) divide and conquer driver expert driver simple driver (band matrices) divide and conquer driver expert driver simple driver for Schur factorization expert driver for Schur factorization simple driver for eigenvalues/vectors expert driver for eigenvalues/vectors singular values/ vectors ||

LA_SYGV (real only) LA_SYGVD (real only) LA_SYGVX (real only) LA.SPGV (real only) LA_SPGVD (real only) LA_SPGVX (real only) LA.SBGV (real only) LA_SBGVD (real only) LA_SBGVX (real only) LA.GGES LA_GGESX LA_GGEV LA.GGEVX LA_GGSVD

Complex Hermitian LA_HEGV LAJHEGVD LA_HEGVX LA_HPGV LA.HPGVD LA_HPGVX LA_HBGV LAJiBGVD LAJiBGVX

Then

Therefore, the columns of X are the eigenvectors of ATA — \BTB, and the "nontrivial" eigenvalues are the squares of the generalized singular values (see also section 2.2.5.1). "Trivial" eigenvalues are those corresponding to the leading n — r columns of X, which span the common null space of ATA and BTB. The "trivial eigenvalues" are not well defined1. A single driver routine LA_GGSVD computes the generalized singular value decomposition of A and B (see Table 2.6). The method is based on the method described in [33, 2, 3].

:

If we tried to compute the trivial eigenvalues in the same way as the nontrivial ones, that is by taking ratios of the leading n — r diagonal entries of XT ATAX and XTBTBX, we would get 0/0. For a detailed mathematical discussion of this decomposition, see the discussion of the Kronecker Canonical Form in [19].

This page intentionally left blank

Chapter 3

Documentation Design and Program Examples 3.1

Design of the LAPACK95 Driver Interface

The design of LAPACK95 [12, 6, 14] exploits the following features of the Fortran 95 language: 1. Assumed-shape arrays: All array arguments to LAPACK95 routines are assumed-shape arrays. Arguments to specify problem dimensions or array dimensions are not used. This implies that the actual arguments supplied to LAPACK95 routines must have the exact shape required by the problem. The most convenient ways to achieve this are: using allocatable arrays. For example, REAL, ALLOCATABLE :: A(:,:), B(:) ALLOCATE( A(N,N), B(N) ) CALL LA_GESV( A, B )

passing array sections. For example, REAL :: A(NMAX,NMAX), B(NMAX) CALL LA_GESV( A(:N,:N), B(:N) ) Zero dimensional (empty) arrays are allowed. There are some grounds for concern about the effect of Fortran 95 assumed-shape arrays on performance because compilers cannot assume that their storage is contiguous. The effect on performance depends on the compiler and may diminish as compilers become more effective in optimizing compiled code. 2. Automatic allocation of work arrays: Workspace arguments and arguments to specify their dimensions are not used. 25

26

Chapter 3. Documentation Design and Program Examples 3. OPTIONAL arguments: In LAPACK, character arguments are frequently used to specify some choice of options. In Fortran 95, a choice of options can sometimes be specified naturally by the presence or absence of optional arguments. For example, options to compute the left or right eigenvectors in LA-GEEV can be specified by the presence of the numerical arguments VL or VR, and the character arguments JOBVL and JOBVR which are required in the LAPACK routine SGEEV are not needed. In other routines, a character argument to specify options may still be required, but it is OPTIONAL in the sense that if it is not specified, then a default value is given. For example, in LA_GESVX the argument TRANS is OPTIONAL, with default value } N 3 . 4. Generic interfaces: The systematic occurrence in LAPACK of analogous routines for real or complex data, and for single or double precision, lends itself well to the definition of generic interfaces, allowing four different LAPACK routines to be accessed through the same LAPACK95 routine name. Generic interfaces can also be used to cover routines whose arguments differ in rank and thus provide an increase in flexibility over LAPACK. For example, in LAPACK, routines for solving a system of linear equations (such as SGESV) allow for multiple right hand sides, and so the arrays which hold the right hand sides and solutions are always of rank 2. In LAPACK95, on the other hand, the arrays holding the right hand sides and solutions may be either of rank 1 (for a single right hand side) or of rank 2 (for several right hand sides). 5. Naming: For all LAPACK95 routine names: the initial letter (S, C, D or Z) is omitted, the letters LA_ are prefixed. The naming scheme is described in detail in Section 2.1.3. 6. Error-handling: All LAPACK95 driver routines have an optional diagnostic output argument INFO. See Section 3.3 for details of its use.

Derived types are not used in this Fortran 95 interface. They could be considered — for example, to hold the details of an LU factorization and equilibration factors. However, since LAPACK routines are so frequently used as building blocks in larger algorithms or applications, it has been decided that the first priority is keeping the interface simple.

3.2

Design and Documentation of Driver Argument Lists

As in LAPACK, the argument lists of all LAPACK95 driver routines conform to a single set of conventions for their design and documentation.

3.2.1

Structure of the Documentation

The documentation of each LAPACK95 driver routine in Part II of this book includes: the SUBROUTINE or FUNCTION statement, consisting of the name and argument list, followed by statements declaring the type and shape of the arguments;

3.2. Design and Documentation of Driver Argument Lists

27

a summary of the Purpose of the routine; a Description (only for some of the expert drivers); descriptions of each of the Arguments in the order of the argument list; the most important References; one or more numerical Examples. The first four of these items are also in the leading comments of the driver source code.

3.2.2

Order of Arguments

Arguments of an LAPACK95 driver routine appear in the following order: array or scalar arguments containing the input data; some of these may also be used for output data. array or scalar arguments used only for output data. optional arguments.

3.2.3

Argument Descriptions

The style of the argument descriptions is illustrated by the following example from LA_GESV: A

(input/output) REAL or COMPLEX square array, shape (:.:). On entry, the matrix A. On exit, the factors L and U from the factorization A = PLU; the unit diagonal elements of L are not stored.

B

(input/output) REAL or COMPLEX array, shape (:.:) with size(B, 1) = szze(A, 1) or shape (:) with size(B) = size(A, I). On entry, the matrix B. On exit, the solution matrix X.

IPIV

Optional (output] INTEGER array, shape (:) with size(IPIV) = size(A, I ) . The pivot indices that define the permutation matrix P: row i of the matrix was interchanged with row IPIVj .

INFO

Optional (output] INTEGER = 0 : successful exit. < 0 : if INFO = —i, the ith argument has an illegal value. > 0 : if INFO = z, then [7^ = 0. The factorization has been completed, but the factor U is singular, so the solution could not be computed. If INFO is not present and an error occurs, then the program is terminated with an error message.

The description of each argument gives:

28

Chapter 3. Documentation Design and Program Examples a classification of the argument as (input), (input/output), (output), (input or output), the type of the argument; (for an array) its shape; the use of the argument on entry and/or on exit; (for a scalar input argument) any constraints that the supplied values must satisfy; (for optional input arguments) a default value.

3.2.4

Optional Arguments

The meaning of each valid value of the argument is given. For example (from LA_POSV): UPLO

Optional (input) CHARACTER(LEN=1) = 'U': Upper triangle of A is stored; = 'L': Lower triangle of A is stored. Default value: 'U'.

The corresponding lower-case characters may be supplied (with the same meaning), but any other value is illegal.

3.2.5

Array Arguments

Each array argument is an assumed-shape array. Some array arguments may have either rank 1 or rank 2. An example from LA_GESV: B

3.3

(input/output) REAL or COMPLEX array, shape (:,:) with szze(B. 1) = size(A, 1) or shape (:) with size(B) = size(A., 1). On entry, the matrix B. On exit, the solution matrix X.

Error Handling

All LAPACK95 driver and computational routines have a diagnostic output argument INFO. In the case of the driver routines, this argument is optional. Three types of exit from a routine are allowed: successful termination: The routine returns to the calling program with INFO set to 0. illegal value of one or more arguments, or error in memory allocation: The routine sets INFO < 0 and calls the error routine ERINFO, which issues an error message identifying the first invalid argument and stops execution. 1

(Input or output) means that the argument may be either an input argument or an output argument, depending on the values of other arguments. For example, in the xyySVX driver routines, some arguments are used either as output arguments to return details of a factorization, or as input arguments to supply details of a previously computed factorization.

3.3.

Error Handling

29

failure in the course of computation: The routine sets INFO > 0 and returns to the calling program without issuing any error message. It is then the responsibility of the user to test INFO on return to the calling program. If INFO is not supplied in the call of a driver routine and an error occurs, then the routine always issues an error message and stops execution, even when INFO > 0 (in which case the error message reports the value of INFO). If a user wishes to continue execution after a failure in computation, then INFO must be supplied and should be tested on return. This behavior simplifies calls to LAPACK95 drivers when there is no need to test INFO on return and makes it less likely that users will forget to test INFO when necessary. If an invalid argument is detected, the routines issue an error message and stop, as in LAPACK. However, in LAPACK95 there can be different reasons for an argument being invalid: illegal value : as in LAPACK. invalid shape (of an assumed-shape array): for example, a two-dimensional array is not square when it is required to be. inconsistent shapes (of two or more assumed-shape arrays): for example, arrays holding the right hand sides and solutions of a system of linear equations must have the same shape. no more core allocation: insufficient memory for LAPACK. The value of INFO is assigned by a call to the routine ERINFO below: SUBROUTINE ERINFO( LINFO, SRNAME, INFO, ISTAT ) .. Scalar Arguments .. CHARACTER( LEN = * ), INTENT(IN) :: SRNAME INTEGER, INTENT( IN ) :: LINFO INTEGER, INTENT( OUT ), OPTIONAL :: INFO INTEGER, INTENT( IN ), OPTIONAL :: ISTAT ! .. Executable Statements .. IF( ( LINFO < 0 .AND. LINFO > -200 ) .OR. & ( LINFO > 0 .AND. .NOT. PRESENT( INFO ) ) )THEN WRITE ( *, * ) 'Program terminated in LAPACK_95 subroutine ', SRNAME WRITE ( *, * ) 'Error indicator, INFO = ', LINFO IF( PRESENT(ISTAT) )THEN IF( ISTAT I- 0 ) THEN IF( LINFO == -100 )THEN WRITE ( *, * ) 'The statement ALLOCATE causes STATUS = ', ISTAT ELSE WRITE ( *, * ) 'LINFO = ', LINFO, ' not expected'

!

END IF END IF END IF STOP

Chapter 3. Documentation Design and Program Examples

30

ELSE IF( LINFO <= -200 )THEN

WRITE(*,*)

WRITE( *, * ) '*** WARNING, INFO - ', LINFO, ' WARNING ***' IF( LINFO == -200 )THEN WRITE( *, * ) 'Could not allocate sufficient workspace for the optimum' WRITE( *, * ) 'blocksize, hence the routine may not have performed as' WRITE( *, * ) 'efficiently as possible' ELSE WRITE( *, * ) 'Unexpected warning'

END IF WRITE(*, *) END IF

IF( PRESENT( INFO ) ) INFO = LINFO END SUBROUTINE ERINFO The use of ERINFO, INFO and LINFO is illustrated in the code in Section 3.7.

3.4

Matrix Storage Schemes

LAPACK95 allows the same matrix storage schemes as LAPACK: conventional storage in a two-dimensional array; packed storage for symmetric, Hermitian or triangular matrices; band storage for band matrices; the use of two or three one-dimensional arrays to store tridiagonal or bidiagonal matrices. The name of a routine identifies the storage scheme used, as explained in Section 2.1.3. For further details see [1] and the numerical examples in Part II.

3.5

Design of Interfaces for Computational Routines

LAPACK95 provides interfaces to all LAPACK computational routines. (See Part III). These interfaces are generic with respect to precision (single or double) and data type (real or complex). In contrast to the driver interfaces, however, they must employ the same argument list as the corresponding LAPACK routines. Thus assumed-shape arrays, automatic allocation of work arrays, and optional arguments are not features of the interfaces to computational routines. For example, the LAPACK95 interface CALL LA_GEQRF( M, N, A, LDA, TAU, WORK, LWORK, INFO ) corresponds to the four LAPACK computational routines

3.6.

31

How to call an LAPACK95 Routine CALL CALL CALL CALL

SGEQRFC DGEQRFC CGEQRFC ZGEQRFC

M, M, M, M,

N, N, N, N,

A, A, A, A,

LDA, TAU, LDA, TAU, LDA, TAU, LDA, TAU,

WORK, WORK, WORK, WORK,

LWORK, LWORK, LWORK, LWORK,

INFO INFO INFO INFO

) ) ) )

There are two advantages to using the LAPACK95 interfaces to LAPACK computational routines rather than calling the latter directly: 1. The generic property can be exploited. 2. The argument correctness of the calling program is checked by the interface.

3.6

How to call an LAPACK95 Routine

Let the object code libraries associated with the BLAS and LAPACK be libblas.a and liblapack.a, respectively. The compilation of the LAPACK95 source code produces a library and four modules. The library, Iiblapack95.a, contains the LAPACK95 driver interface routines described in Part II. The modules are as follows: la,precision, mod: This concerns the use of single or double precision. f95Japack.mod: This contains interfaces between calls to LAPACK95 driver routines and the Iiblapack95. a library. f77Japack.mod: This contains interfaces between calls to LAPACK95 computational routines and the liblapack.a library. la-.auxmod.mod: This contains LAPACK95 auxiliary routines (which are not described in this Users' Guide). The user's program must refer to the appropriate modules via the Fortran 95 USE statement, and it must also link to the appropriate libraries. The appropriate choices are as follows: The user's program calls one or more LAPACK95 driver routines: Modules: la-precision.mod, f95Japack.mod Libraries: Iiblapack95.a, liblapack.a, libblas.a The user's program calls one or more LAPACK95 computational routines: Modules: la.precision.mod, f77Japack.mod Libraries: liblapack.a, libblas.a

Example 1 The program in Fig. 3.1 illustrates the use of an LAPACK95 driver routine, LA.GESV. This routine solves a linear system of equations AX — B, where A is a square matrix and B is a vector or matrix containing the right-hand side vector(s). (See Section 5.1.1). In this application B is a matrix. Remarks:

32

Chapter 3. Documentation Design and Program Examples Statement 2 includes the la-precision.mod module from LAPACK95 and sets the precision to single precision (SP) via the internal parameter WP (working precision). If SP is replaced by DP then the precision is set to double precision. Statement 3 includes the interface block of the driver routine LA_GESV from the f95Japack.mod module of LAPACK95. All driver routine interfaces are contained in this module. Statement 7 defines arguments A and B to be allocatable real single-precision arrays. The program works in complex arithmetic if REAL(WP) is replaced by COMPLEX(WP). Statements 9-11 allocate A and B and assign data to these arrays. Statement 12 calls LA_GESV to solve the system. On exit, the solution matrix X is stored in array B. Q+afomcmf

1 !-\ T-»rinfc Y

1 PROGRAM EXAMPLE 2 USE LA_PRECISION, ONLY: WP => SP 3 USE F95_LAPACK, ONLY: LA_GESV 4 IMPLICIT NONE 5 CHARACTER( LEN = * ), PARAMETER :: FMT = '(7(1X,F9.3))' 6 INTEGER :: J, N, NRHS 7 REAL( WP ), ALLOCATABLE :: A( :, : ), B( :, : ) 8 N = 5; NRHS = 2 9 ALLOCATE( A( N, N ), B( N, NRHS ) ) 10 CALL RANDOM_NUMBER( A ) 11 DO J = 1, NRHS; B( :, J ) = SUM( A, DIM=2 )*J; END DO 12 CALL LA_GESV( A, B ) 14 WRITE( *, * ) 'The solution:' 15 DO J = 1, NRHS; WRITE ( *, FMT ) B( :, J ); END DO 17 END PROGRAM EXAMPLE Figure 3.1: Example program calling an LAPACK95 driver routine.

Example 2 The program in Fig. 3.2 illustrates the use of an LAPACK95 computational routine, LA.GEQRF, which computes the QR factorization of a square matrix A (A = QR). (See LA.GEQRF in Section 10.2). Remarks: Statement 2 includes the la.precision.mod module from LAPACK95 and sets the precision to single precision (SP) via the internal parameter WP (working precision). If SP is replaced by DP then the precision is set to double precision. Statement 3 includes the interface block of the computational routine LA_GEQRF from the f77Japack.mod module of LAPACK95. All computational routine interfaces belong to this module.

3.7. Code for One Version of LA.SYEV

33

Statement 7 defines arguments A, TAU and WORK to be allocatable real single-precision arrays. The program works in complex arithmetic if REAL(WP) is replaced by COMPLEX(WP). Statements 9-10 allocate A, TAU and WORK and assign data to array A. Statements 11-13 calculate the optimal length of the work array WORK and allocate this array. Statement 14 calls LA_GEQRF to compute the QR factorization of the matrix in array A. On exit, details of the factorization are stored in array A. Statement 18 prints the contents of A. 1 PROGRAM EXAMPLE 2 USE LA_PRECISION, ONLY: WP => SP 3 USE F77JLAPACK, ONLY: LA_GEQRF 4 IMPLICIT NONE 5 CHARACTER( LEN = * ), PARAMETER :: FMT = '(7(1X,F9.3))' 6 INTEGER :: I, INFO, LDA, LWORK, M, N 7 REAL( WP ), ALLOCATABLE :: A( :, : ), TAU( : ), WORK( : ) 8 M = 5; N = 6; LDA = M; LWORK = -1 9 ALLOCATE( A( M, N ), TAU(MIN( M, N ) ), WORK(MAX( 1, N ) ) ) 10 CALL RANDOM_NUMBER( A ) 11 CALL LA_GEQRF( M, N, A, LDA, TAU, WORK, LWORK, INFO ) 12 LWORK = INT( WORK( 1 ) ); DEALLOCATE( WORK ) 13 ALLOCATE( WORK( LWORK ) ) 14 CALL LA_GEQRF( M, N, A, LDA, TAU, WORK, LWORK, INFO ) 15 WRITE( *, * ) 'INFO = ', INFO 16 IF( INFO == 0 )THEN 17 WRITE( *, * ) 'Matrix A on exit:' 18 DO I = 1, M; WRITE ( *, FMT ) A( I, : ); END DO 19 END IF 20 END PROGRAM EXAMPLE Figure 3.2: Example program calling an LAPACK95 computational routine.

3.7

Code for One Version of LAJ3YEV

The following code implements one of the Fortran 95 interface driver subroutines. The routine shown is the real single precision version of LA_SYEV. SUBROUTINE SSYEV_F95( A, W, JOBZ, UPLO, INFO ) ! - LAPACK95 interface driver routine (version 2.0) ! UNI-C, Denmark; Univ. of Tennessee, USA; NAG Ltd., UK ! August, 2000

34 I

! ! ! !

Chapter 3. Documentation Design and Program Examples .. Use statements .. USE LAJPRECISION, ONLY: WP => SP USE LA.AUXMOD, ONLY: ERINFO, LSAME USE F77_LAPACK, ONLY: SYEV_F77 => LA_SYEV, & ILAENV_F77 => ILAENV .. Implicit statement .. IMPLICIT NONE .. Character arguments .. CHARACTER( LEN = 1 ), INTENT(IN), OPTIONAL :: JOBZ, UPLO .. Scalar arguments .. INTEGER, INTENT(OUT), OPTIONAL :: INFO .. Array arguments .. REAL( WP ), INTENT(INOUT) :: A( :, : ) REAL( WP ), INTENT(OUT) :: W( : )

! LA_SYEV computes all eigenvalues and, optionally, ! eigenvectors of a real symmetric matrix A. i ! .. Local parameters .. CHARACTER( LEN = 7 ), PARAMETER :: SRNAME = 'LAJ3YEV CHARACTER( LEN = 6 ), PARAMETER :: BSNAME = 'SSYTRD' ! .. Local scalars .. CHARACTER( LEN = 1 ) :: LJOBZ, LUPLO INTEGER :: N, LINFO, LD, ISTAT, ISTAT1, LWORK, NB ! .. Local arrays .. REAL( WP ), POINTER :: WORK( : ) ! .. Intrinsic functions .. INTRINSIC MAX, PRESENT ! .. Executable statements .. N = SIZE( A, 1 ); LINFO = 0; ISTAT = 0; LD = MAX( 1, N ) IF( PRESENT( JOBZ ) ) THEN LJOBZ = JOBZ ELSE LJOBZ = 'N' END IF IF( PRESENT( UPLO ) ) THEN LUPLO = UPLO ELSE LUPLO = 'U' END IF ! .. Test the arguments IF( SIZE( A, 2 ) /= N .OR. N < 0 )THEN LINFO = -1 ELSE IF( SIZE( W ) /= N )THEN LINFO = -2

3.8. LAPACK and LAPACK95 Interface Module Blocks ELSE IF( .NOT. LSAME( LJOBZ, 'N' ) .AND. & .NOT. LSAME( LJOBZ, 'V ) )THEN LINFO = -3 ELSE IF( .NOT. LSAME( LUPLO, 'U' ) .AND. & .NOT. LSAME( LUPLO, 'L' ) )THEN LINFO = -4 ELSE IF( N > 0 )THEN ! .. Determine the workspace NB = ILAENV_F77( 1, BSNAME, LUPLO, N, -1, -1, -1 ) IF( NB <= 1 .OR. NB >= N )THEN NB = 1 END IF LWORK = ( 2 + NB ) * N ALLOCATE( WORK( LWORK ), STAT = ISTAT ) IF( ISTAT /= 0 )THEN LWORK = 3 * N - 1 DEALLOCATE( WORK, STAT = ISTAT1 ) ALLOCATE( WORK( LWORK), STAT = ISTAT ) IF( ISTAT /= 0 ) THEN LINFO = -100 ELSE CALL ERINFO( -200, SRNAME, ISTAT1 ) END IF END IF IF( LINFO == 0 )THEN CALL SYEV_F77( LJOBZ, LUPLO, N, A, LD, W, & WORK, LWORK, LINFO ) END IF DEALLOCATE( WORK, STAT = ISTAT1 ) END IF CALL ERINFO( LINFO, SRNAME, INFO, ISTAT ) END SUBROUTINE SSYEVJF95

3.8 3.8.1 3.8.1.1

LAPACK and LAPACK95 Interface Module Blocks F77_LAPACK Generic Interface Blocks LA_SYEV/LA_HEEV

INTERFACE LA_SYEV SUBROUTINE SSYEV( JOBZ, UPLO, N, A, LDA, W, & WORK, LWORK, INFO ) USE LAJPRECISION, ONLY: WP => SP

35

36

Chapter 3. Documentation Design and Program Examples

CHARACTER^ LEN = 1 ), INTENT( IN ) :: JOBZ, UP INTEGER, INTENT( IN ) :: LDA, LWOR INTEGER, INTENT ( OUT ) :: REAL( WP ), INTENT( INOUT ) :: A( LDA REAL( WP ), INTENT( OUT ) :: W( REAL( WP ), INTENT( OUT ) :: WORK END SUBROUTINE SSYEV SUBROUTINE DSYEV( JOBZ, UPLO, N, A, LDA, W, & WORK, LWORK, INFO ) USE LA_PRECISION, ONLY: WP => DP CHARACTER( LEN = 1 ), INTENT( IN ) :: JOBZ, UPLO INTEGER, INTENT( IN ) :: LDA, LWORK INTEGER, INTENT ( OUT ) :: INFO REAL( WP ), INTENT( INOUT ) :: A( LDA REAL( WP ), INTENT( OUT ) :: W( REAL( WP ), INTENT( OUT ) :: WORK( END SUBROUTINE DSYEV END INTERFACE

INTERFACE LA_HEEV SUBROUTINE CHEEV( JOBZ, UPLO, N, A, LDA, W WORK, LWORK, RWORK, INFO ) USE LA_PRECISION, ONLY: WP => SP CHARACTER( LEN = 1 ), INTENT( IN ) :: JOBZ, UP INTEGER, INTENT( IN ) :: LDA, LWORK INTEGER, INTENT( OUT ) :: INFO COMPLEX( WP ), INTENT( INOUT ) :: A( LDA REAL( WP ), INTENT( OUT ) :: W( * ), RWOR COMPLEX( WP ), INTENT( OUT ) :: WORK END SUBROUTINE CHEEV SUBROUTINE ZHEEV( JOBZ, UPLO, N, A, LDA, W WORK, LWORK, RWORK, INFO ) USE LA_PRECISION, ONLY: WP => DP CHARACTER( LEN = 1 ), INTENT( IN ) :: JOBZ, UP INTEGER, INTENT( IN ) :: LDA, LWORK INTEGER, INTENT ( OUT ) :: I COMPLEX( WP ), INTENT( INOUT ) :: A( LDA REAL( WP ), INTENT( OUT ) :: W( * ), RWOR COMPLEX( WP ), INTENT( OUT ) :: WORK END SUBROUTINE ZHEEV END INTERFACE

3.8. LAPACK and LAPACK95 Interface Module Blocks 3.8.1.2

LA_GESV Multiple RHS Case

INTERFACE LA_GESV SUBROUTINE SGESV( N, NRHS, A, LDA, IPIV, B, LDB, INFO ) USE LA_PRECISION, ONLY: WP => SP INTEGER, INTENT( IN ) :: LDA, LDB, NRHS, N INTEGER, INTENT( OUT ) :: INFO INTEGER, INTENT( OUT ) :: IPIV( * ) REAL(WP), INTENT( INOUT ) :: A( LDA, * ), B( LDB, * ) END SUBROUTINE SGESV SUBROUTINE DGESV( N, NRHS, A, LDA, IPIV, B, LDB, INFO ) USE LAJPRECISION, ONLY: WP => DP INTEGER, INTENT( IN ) :: LDA, LDB, NRHS, N INTEGER, INTENT ( OUT ) :: INFO INTEGER, INTENT( OUT ) :: IPIV( * ) REAL(WP), INTENT( INOUT ) :: A( LDA, * ), B( LDB, * ) END SUBROUTINE DGESV SUBROUTINE CGESV( N, NRHS, A, LDA, IPIV, B, LDB, INFO ) USE LAJPRECISION, ONLY: WP => SP INTEGER, INTENT( IN ) :: LDA, LDB, NRHS, N INTEGER, INTENT ( OUT ) :: INFO INTEGER, INTENT( OUT ) :: IPIV( * ) COMPLEX(WP), INTENT( INOUT ) :: A( LDA, * ), B( LDB, * ) END SUBROUTINE CGESV SUBROUTINE ZGESV( N, NRHS, A, LDA, IPIV, B, LDB, INFO ) USE LA_PRECISION, ONLY: WP => DP INTEGER, INTENT( IN ) :: LDA, LDB, NRHS, N INTEGER, INTENT( OUT ) :: INFO INTEGER, INTENT( OUT ) :: IPIV( * ) COMPLEX( WP ), INTENT( INOUT ) :: A( LDA, * ), B( LDB, * ) END SUBROUTINE ZGESV MODULE PROCEDURE SGESV1, DGESV1, DGESV1, CGESV1, ZGESV1 END INTERFACE 3.8.1.3

LA_GESV Single RHS Case

CONTAINS SUBROUTINE SGESV1( N, NRHS, A, LDA, IPIV, B, LDB, INFO ) USE LAJPRECISION, ONLY: WP => SP INTEGER, INTENT( IN ) :: LDA, LDB, NRHS, N INTEGER, INTENT( OUT ) :: INFO INTEGER, INTENT( OUT ) :: IPIV( * )

37

38

Chapter 3. Documentation Design and Program Examples REAL( WP ), INTENT( INOUT ) :: A( LDA, * ), B( * ) INTERFACE SUBROUTINE SGESV( N, NRHS, A, LDA, IPIV, B, LDB, INFO ) USE LA_PRECISION, ONLY: WP => SP INTEGER, INTENT( IN ) :: LDA, LDB, NRHS, N INTEGER, INTENT( OUT ) :: INFO INTEGER, INTENT( OUT ) :: IPIV( * ) REAL(WP), INTENT( INOUT ) :: A( LDA, * ), B( LDB, * ) END SUBROUTINE SGESV END INTERFACE CALL SGESV( N, NRHS, A, LDA, IPIV, B, LDB, INFO ) END SUBROUTINE SGESV1 SUBROUTINE DGESV1( N, NRHS, A, LDA, IPIV, B, LDB, INFO ) USE LA-PRECISION, ONLY: WP => DP CALL DGESV( N, NRHS, A, LDA, IPIV, B, LDB, INFO ) END SUBROUTINE DGESV1 SUBROUTINE CGESV1( N, NRHS, A, LDA, IPIV, B, LDB, INFO ) USE LA_PRECISION, ONLY: WP => SP CALL CGESV( N, NRHS, A, LDA, IPIV, B, LDB, INFO ) END SUBROUTINE CGESV1 SUBROUTINE ZGESV1( N, NRHS, A, LDA, IPIV, B, LDB, INFO ) USE LA_PRECISION, ONLY: WP => DP CALL ZGESV( N, NRHS, A, LDA, IPIV, B, LDB, INFO ) END SUBROUTINE ZGESV1

3.8.2 3.8.2.1

F95_LAPACK Generic Interface Blocks LA_SYEV/LAJHEEV

INTERFACE LAJSYEV SUBROUTINE SSYEV_F95( A, W, JOBZ, UPLO, INFO ) USE LAJPRECISION, ONLY: WP => SP CHARACTER(LEN=1), INTENT( IN ), OPTIONAL :: JOBZ, UPLO INTEGER, INTENT( OUT ), OPTIONAL :: INFO REAL( WP ), INTENT( INOUT ) :: A( :, : ) REAL( WP ), INTENT( OUT ) :: W( : ) END SUBROUTINE SSYEVJF95 SUBROUTINE DSYEV_F95( A, W, JOBZ, UPLO, INFO ) USE LA_PRECISION, ONLY: WP => DP CHARACTER(LEN=1), INTENT( IN ), OPTIONAL :: JOBZ, UPLO

3.8. LAPACK and LAPACK95 Interface Module Blocks INTEGER, INTENT( OUT ), OPTIONAL :: INFO REAL( WP ), INTENT( INOUT ) :: A( :, : ) REAL( WP ), INTENT( OUT ) :: W( : ) END SUBROUTINE DSYEVJF95 END INTERFACE INTERFACE LA_HEEV SUBROUTINE CHEEV_F95( A, W, JOBZ, UPLO, INFO ) USE LAJPRECISION, ONLY: WP => SP CHARACTER(LEN=1), INTENT( IN ), OPTIONAL :: JOBZ, UPLO INTEGER, INTENT( OUT ), OPTIONAL :: INFO COMPLEX( WP ), INTENT( INOUT ) :: A( :, : ) REAL( WP ), INTENT( OUT ) :: W( : ) END SUBROUTINE CHEEV_F95 SUBROUTINE ZHEEVJF95( A, W, JOBZ, UPLO, INFO ) USE LA_PRECISION, ONLY: WP => DP CHARACTER(LEN=1), INTENT( IN ), OPTIONAL :: JOBZ, UPLO INTEGER, INTENT( OUT ), OPTIONAL :: INFO COMPLEX( WP ), INTENT( INOUT ) :: A( :, : ) REAL( WP ), INTENT( OUT ) :: W( : ) END SUBROUTINE ZHEEV_F95 END INTERFACE

3.8.2.2

LA_GESV

INTERFACE LA_GESV ! Single Precision, Multiple RHS SUBROUTINE SGESV_F95( A, B, IPIV, INFO ) USE LA_PRECISION, ONLY: WP => SP INTEGER, INTENT( OUT ), OPTIONAL :: INFO INTEGER, INTENT( OUT ), OPTIONAL :: IPIV( : ) REAL( WP ), INTENT( INOUT ) :: A( :, : ), B( :, : ) END SUBROUTINE SGESV_F95 ! Single Precision, Single RHS SUBROUTINE SGESV1_F95( A, B, IPIV, INFO ) USE LA_PRECISION, ONLY: WP => SP INTEGER, INTENT( OUT ), OPTIONAL :: INFO INTEGER, INTENT( OUT ), OPTIONAL :: IPIV( : ) REAL( WP ), INTENT( INOUT ) :: A( :, : ), B( : ) END SUBROUTINE SGESV1JF95 ! Double Precision, Multiple RHS SUBROUTINE DGESV_F95( A, B, IPIV, INFO ) USE LA_PRECISION, ONLY: WP => DP

39

Chapter 3. Documentation Design and Program Examples

40

END SUBROUTINE ZGESV_F95 ! Double Complex, Single RHS SUBROUTINE ZGESV1_F95( A, B, IPIV, INFO ) USE LA_PRECISION, ONLY: WP => DP INTEGER, INTENT ( OUT ), OPTIONAL :: INFO INTEGER, INTENT( OUT ), OPTIONAL :: IPIV( : ) COMPLEX( WP ), INTENT( INOUT ) :: A( :, : ), B( : ) END SUBROUTINE ZGESV1JF95 END INTERFACE

3.8.3 LA_LAMCH Interfaces LAPACK95 has two kinds of interface entries for LA-LAMCH. 1. Explicit interface entries:

INTERFACE FUNCTION SLAMCH( CMACH ) USE LA_PRECISION, ONLY: WP => SP REAL(WP) :: SLAMCH

CHARACTER( LEN = 1 ), INTENT( IN ) :: CMACH END FUNCTION SLAMCH FUNCTION DLAMCH( CMACH ) USE LAJPRECISION, ONLY: WP => DP REAL( WP ) :: DLAMCH CHARACTER( LEN = 1 ), INTENT( IN ) :: CMACH END FUNCTION DLAMCH END INTERFACE This is a part of the F77JLAPACK interface module blocks. 2. Generic interface entry:

FUNTION LA_LAMCH( l.O.wp, CMACH, INFO ) CHARACTER(LEN=1), INTENT( IN ) :: CMACH REAL(wp) :: LA_LAMCH INTEGER, INTENT( OUT ), OPTIONAL :: INFO where wp ::= KIND( 1.0 ) | KIND( l.ODO ) This is a part of the F95JLAPACK interface module blocks. For function values of LA_LAMCH (SLAMCH and/or DLAMCH) see Table 1.1.

Chapter 4

Performance and Troubleshooting 4.1 4.1.1

Performance of LAPACK95 Performance Issues

In contrast to Fortran 77 compilers, current Fortran 95 compilers do not assume that array storage is contiguous. When a Fortran 77 routine is called from a Fortran 95 routine, a contiguous copy of arrays is made in temporary storage, an operation that degrades performance. This problem could be alleviated by alternative interfaces to the Fortran 77 routines involving Fortran 77 constructs, but this would violate the goal of having a true Fortran 95 interface to LAPACK. Hence the user should be aware that in some cases LAPACK95 may perform less efficiently than when LAPACK is called directly from a Fortran 77 or Fortran 95 program.

4.1.2

Performance Tables

In this section we give performance results, in megaflops, for some basic computations on a variety of computers. Table 4.1 lists the computers used, processor names, operating system versions, compiler versions and the BLAS library versions. Regarding the latter, ATLAS refers to BLAS obtained from the ATLAS system; see Section 1.5.3. ESSL is the Engineering Scientific Subroutine Library [23, 22] for IBM computers; it also contains the IBM specialized BLAS. SUNPERF is the Sun WorkShop(TM) 6 Performance Library [41]; it also contains the SUN specialized BLAS. CXML is the Compaq Extended Math Library [7]; it also contains the Compaq Alpha specialized BLAS. Each of the performance tables below gives the performance of a specific LAPACK95 driver routine and, in addition, the performance obtained by using LAPACK directly; i.e., without the LAPACK95 interface. A table is arranged as follows: Column 1 identifies the computers and their processors. Column 2 gives the optimal block size (Section 1.5.1.1). Column 3 specifies the type of data: D, real double precision; S, real single precision; Z, complex double precision; C, complex single precision. Columns 4 and 5 give the megaflop counts achieved by LAPACK, without the Fortran 95 interface, for problems of order 100 and 1000, respectively. Columns 6 and 7 give the megaflop counts for the same problems when the LAPACK95 driver routine named in the figure 41

Chapter 4. Performance and Troubleshooting

42

Table 4.1: Computer used for running the performance timing Computer Compiler Processor OS BLAS version & options name version name library COMPAQ

IBM

IBM

SUN

Alpha EV6

OSF1 - Tru64

£90 v. 5.3

CXML

© 500 MHz

v. 4.0

v. 3.5

PowerPC 604e © 332 MHz

AIX v. 4.3.3

Power2

AIX

Compaq Fortran -03 xlf95 v. 6.1 IBM compiler -O3 -qstrict xlf95 v. 6.1

© 67 MHz

v. 4.3.3

UltraSparc II

SUNOS v. 5.7

© 400 MHz

INTEL

Pentium III © 500 MHz

SGI

R12000 © 300 MHz

Linux RedHat v. 6.1 IRIX64 v.6.5

IBM compiler -O3 -qstrict -qarch=pwr2 £90 v. 5.0 Workshop compiler -fast -xtarget— ultra2 -xarch— vSplusa £95 v. 1.0 NAG compiler -O3 £90 v. 7.30 MlPSpro compiler -O3

ESSL v. 3.1.1 ESSL v.3.1.1

SUNPERF v. 2.0

ATLAS v. 3.0 ATLAS v. 3.0

caption is used. Each of the megaflop counts in the tables was obtained as follows: The problem was run 10 times, and each time the elapsed time was measured using the Fortran 95 command CPU-TIME. The megaflop rate was then computed from the formula

where t is the average of the 10 elapsed times and a is given in Table 4.2. The driver routines timed are: LA.GESV (Table 4.3): computes the solution to a system of equations AX = B, where A is an n x n matrix and B (in this computation) is an n x 1 vector (Section 5.1.1). LA_GEEV (Tables 4.4 and 4.5): computes for an n x n matrix A the eigenvalues and, optionally, the left and/or right eigenvectors (Section 7.2.3). LA_GESVD (Table 4.6): computes for an m x n matrix A the singular values and, optionally, the left and/or right singular vectors (Section 9.1.1). In this computation m = n.

43

4.1. Performance of LAPACK95

Table 4.2: Floating point coefficient of operation counts for LAPACK drivers for n x n matrices (see also Table 3.13 of [1]). The number of operations is a x n 3 . Driver LA.GESV LA.GEEV LA_GEEV LA_GES{VD,DD} LA_GES{VD,DD}

Options 1 right hand side eigenvalues only eigenvalues and right eigenvectors singular values only singular values, and left and right singular vectors

Q

0.67 10.00 26.33 2.67 6.67

LA-GESDD (Tables 4.7 and 4.8): solves the same problem as LA_GESVD but uses a divide and conquer method if singular vectors are desired (Section 9.1.1).

Table 4.3: Performance of LA.GESV in megaflops; n = 100 and 1000. Computer / Processor COMPAQ Alpha EV6 @ 500 MHz

Block size 28

Data type D S

z

IBM PowerPC 604e @ 332 MHz

32

IBM Power2 @ 67 MHz

32

SUN UltraSparc II @ 400 MHz

64

INTEL Pentium III @ 500 MHz

40

SGI R12000 @ 300 MHz

64

c

D S

z c

D S Z C D S

z c

D S

z c

D S

z

c

LAPACK 100 1000 402 732 402 789 152 80 174 81 104 271 145 333 243 57 112 67 67 236 67 218 58 33 60 33 109 177 130 247 35 40 46 40 67 251 314 67 34 71 88 66 182 442 242 340 113 59 127 65

LAPACK95 100 1000 679 402 755 402 151 80 171 81 271 101 333 145 226 57 111 67 235 67 218 67 58 33 59 33 172 109 249 155 35 37 46 39 251 67 314 67 71 34 88 66 445 190 344 242 114 60 127 66

Chapter 4. Performance and Troubleshooting

44

Table 4.4: Performance of LA_GEEV in megaflops (eigenvalues only); n — 100 and 1000. Computer / Processor COMPAQ Alpha EV6 @ 500 MHz IBM PowerPC 604e © 332 MHz IBM Power2 © 67 MHz SUN UltraSparc II @ 400 MHz INTEL Pentium III @ 500 MHz SGI R12000 @ 300 MHz

Block Data size L tv P e 28 D S 32 D S 32 D S 64 D S 40 D S 64 D S

LAPACK 100 1000 272 262 300 369 87 109 117 128 76 49 94 51 95 105 152 176 97 95 142 175 171 236 230 407

LAPACK95 100 1000 263 270 372 300 109 99 117 161 50 76 51 98 118 97 171 173 91 93 142 175 177 233 230 411

Table 4.5: Performance of LA-GEEV in megaflops (eigenvalues and right eigenvectors); n — 100 and 1000. Computer Processor COMPAQ Alpha EV6 © 500 MHz IBM PowerPC 604e © 332 MHz IBM Power2 @ 67 MHz SUN UltraSparc II © 400 MHz INTEL Pentium III © 500 MHz SGI R12000 © 300 MHz

Block size 28 32 32 64 40 64

Data type D S D S D S D S D S D S

LAPACK 100 1000 267 268 376 437 141 81 148 138 69 70 95 63 104 92 197 181 112 105 181 201 246 241 325 500

LAPACK95 100 1000 268 267 351 437 141 85 147 171 68 70 63 108 100 99 183 199 112 111 207 181 249 257 325 479

45

4.1. Performance of LAPACK95

Table 4.6: Performance of LA-GESVD in megaflops (singular values and left and right singular vectors); n = 100 and 1000. Computer / Processor

Block size

Data type

COMPAQ Alpha EV6 @ 500 MHz IBM PowerPC 604e @ 332 MHz IBM Power2 @ 67 MHz SUN UltraSparc II @ 400 MHz INTEL Pentium III @ 500 MHz SGI R12000 @ 300 MHz

28

D S D S D S D S D S D S

32 32 64 40 64

LAPACK 100 1000

LAPACK95 1000 100

130 174 43 56 32 32 52 65 49 66 90 129

129 181 43 56 32 32 52 64 49 66 90 129

60 105 22 29 11 17 15 33 31 51 42 100

60 104 22 29 11 16 13 32 31 47 42 97

Table 4.7: Performance of LA_GESDD in megaflops (singular values only); n = 100 and 1000. Computer / Processor

Block size

Data type

COMPAQ Alpha EV6 @ 500 MHz IBM PowerPC 604e @ 332 MHz IBM Power2 @ 67 MHz SUN UltraSparc II @ 400 MHz INTEL Pentium III @ 500 MHz SGI R12000

28

D S D

@ 300 MHz

32 32 64 40 64

L_

S

D S D S D S D S

LAPACK

LAPACK95

100 267 285 78 110 53 56 85 140 89 133 134 201

100 267 236 78 110 53 66 85 119 89 133 134 202

1000 300 459 83 119 136 134 87 150 121 180 280 369

1000 293 456 83 119 136 138 87 144 121 179 280 369

Chapter 4. Performance and Troubleshooting

46

Table 4.8: Performance of LA_GESDD in megaflops (singular values and left and right singular vectors); n = 100 and 1000.

Computer / Processor COMPAQ Alpha EV6 @ 500 MHz

Block size 28

IBM PowerPC 604e © 332 MHz

32

IBM Power2 @ 67 MHz

32

SUN UltraSparc II @ 400 MHz

64

INTEL Pentium III © 500 MHz SGI R12000 © 300 MHz

Data type D S

c z D S

z c D S

z c

D S

z

40

c

D S

z

64

c

D S

z c

LAPACK 100 1000 210 372 285 486 108 88 100 135 74 118 161 96 45 135 91 50 121 41 124 43 23 45 24 47 86 81 112 146 32 18 35 37 78 146 95 191 30 51 39 65 111 272 169 311 50 77 59 110

LAPACK95 100 1000 355 200 485 235 107 88 132 80 74 118 161 96 132 46 92 50 121 41 124 43 45 23 47 24 77 81 112 146 18 30 34 36 74 146 194 95 51 30 65 39 272 111 311 170 52 78 109 59

4.2. Accuracy and Stability

4.2

47

Accuracy and Stability

LAPACK95 is a Fortran 95 interface to LAPACK. As such, it does not alter any of the algorithms of the LAPACK routines, and thus the accuracy and stability issues remain the same as for LAPACK. For details of the accuracy and stability properties of the LAPACK routines, see [1].

4.3

Errors and Poor Performance

If an error occurs, the user's first thought should be that the successful use of LAPACK95 relies heavily on the proper installation of the BLAS, LAPACK, and LAPACK95 packages. As mentioned earlier, each of these includes a test suite that should be run as part of the installation process. If the error occurs during the installation process, the user should follow the advice given in Section 1.5.4. Henceforth it will be assumed that the installation process (including the running of the three test suites) was successful and that the error first occurs in an application. Here the user should: Reread the documentation of the driver and computational routines being used, paying particular attention to the description of the argument INFO. Check the installation of machine dependencies (Section 1.5.1.1). In the case of an LAPACK95 driver routine, try to reproduce the results of the numerical example(s) given for that routine in Part II. The user can write his own main program for this purpose or use the one provided in the EXAMPLEl directory of the LAPACK95 distribution file. (See Section 1.5.1). Consult the FAQ lists at the home pages of the BLAS, LAPACK and LAPACK95. Consult the release-notes files at the same home pages. These files contain lists of known difficulties that have been diagnosed and corrected (or will be corrected in the next release), or reported to the vendor in the case of machine-specific BLAS. Report the error to the Email address in Section 1.6 with the following information, if possible: A test case, a description of the problem and expected results, and the actions, if any, that the user has already taken to fix the error. With regard to poor performance, two possible causes are an inefficient version of the BLAS for the given computer and an incorrect installation of machine dependencies.

This page intentionally left blank

Part II

DRIVER ROUTINES

This page intentionally left blank

Chapter 5

Driver Routines for Linear Systems 5.1

General Linear Systems

5.1.1 LA_GESV SUBROUTINE LA_GESV( A, B, IPIV=ipiv, INFO=info ) type(wp), INTENT(INOUT) :: A(:,:), rhs INTEGER, INTENT(OUT), OPTIONAL :: IPIV(:) INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(:,:) | B(:)

Purpose LA_GESV computes the solution to a real or complex linear system of equations AX = B. where A is a square matrix and X and B are rectangular matrices or vectors. Gaussian elimination with row interchanges is used to factor A as A = PL U. where P is a permutation matrix. L is unit lower triangular, arid U is upper triangular. The factored form of A is then used to solve the above system.

Arguments A

B

IPIV

(input/output) REAL or COMPLEX square array, shape (:,:). On entry, the matrix A. On exit, the factors L and U from the factorization A = PLU; the unit diagonal elements of L are not stored. (input/output) REAL or COMPLEX array, shape (:,:) with size(B, 1) = size(A. 1) or shape (:) with size(B) = size(A. I). On entry, the matrix B. On exit, the solution matrix X. Optional (output) INTEGER array, shape (:) with szze(IPIV) = szze(A, 1). The pivot indices that define the permutation matrix F; row i of the matrix was interchanged with row IPIVj . 51

52 INFO

General Linear Systems Optional (output) INTEGER = 0 : successful exit. < 0 : if INFO = — i, the ith argument has an illegal value. > 0 : if INFO = i, then £7^ = 0. The factorization has been completed, but the factor U is singular, so the solution could not be computed. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20]. Examples The results below are computed with e = 1.19209 x 10~7. Example 1 (from Program LA_GESV_EXAMPLE)

Arrays A and B on entry:

The call: CALL LA_GESV( A, B ) B on exit:

The solution of the system A X = B is:

53

LA_GESV

Example 2 (from Program LA_GESV_EXAMPLE) A on entry: As in Example 1. B on entry: J? :) i, where B is the input matrix in Example 1. The call: CALL LA_GESV( A, B(:,l), IPIV, INFO ) A, B(:, 1), IPIV and INFO on exit:

INFO = 0

Matrices L, U, P and x, where x is the solution of the system Ax = b:

54

General Linear Systems

5.1.2

LA_GESVX

SUBROUTINE LA_GESVX ( A, B, X, AF=af, IPIV=ipiv, FACT=fact, & TRANS=trans, EQUED=equed, R=r, C=c, FERR=ferr, & BERR=berr, RCOND=rcond, RPVGRW=rpvgrw, & INFO=info ) type(wp), INTENT(INOUT) :: A(:,:), rhs type(wp), INTENT(OUT) :: sol type(wp), INTENT(INOUT), OPTIONAL :: AF(:,:) INTEGER, INTENT(INOUT), OPTIONAL :: IPIV(:) CHARACTER(LEN^l), INTENT(IN), OPTIONAL :: FACT, & TRANS CHARACTER(LEN=1), INTENT(INOUT), OPTIONAL :: EQUED REAL(wp), INTENT(INOUT), OPTIONAL :: R(:), C(:) REAL(wp), INTENT(OUT), OPTIONAL :: err, RCOND, RPVGRW INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(:,:) | B(:) sol ::= X(:,:) | X(:) err ::- FERR(:), BERR(:) | FERR, BERR

Purpose LA.GESVX computes the solution to a real or complex linear system of equations of the form AX — B, ATX = B or AHX = B, where A is a square matrix and X and B are rectangular matrices or vectors. LA.GESVX can also optionally equilibrate the system if A is poorly scaled, estimate the condition number of (the equilibrated) ^4, return the pivot growth factor, and compute error bounds.

Description 1. If FACT = 'E', then real row scaling factors Ri and/or real column scaling factors d are computed to equilibrate the system. The form of the equilibrated system depends on the value of TRANS: TRANS 'N! 5rru

'C'

The equilibrated system [diag(R) A diag(C}\ [diag(C)~lX] = diag(R] B [(diag(R) A diag(C)}T] [diag(R)-lX] = diag(C) B [(diag(R) A diag(C}}H] [diag(R)-lX] = diag(C) B

Depending on the value of EQUED determined during the equilibration, the matrices diag(R) and/or diag(C) may be implicitly the identity matrix: EQUED 'N'

'R' 'C' 'B'

diag(R) Identity diag(R) Identity diag(R)

diag(C) Identity Identity diag(C) diag(C)

LA.GESVX

55

2. If FACT = 'N', matrix A is factored as A ~ PLU, where P is a permutation matrix. L is unit lower triangular, and U is upper triangular. If FACT = 'E', the equilibrated matrix is factored as PLU. 3. If some Ui^ = 0, so that U is singular, then the routine returns with INFO = i. Otherwise, an estimate of the condition number of (the equilibrated) A is found using the above factorization. If the reciprocal of the condition number is less than machine precision, INFO = n + 1, where n is the order of A. is returned as a warning. However, the routine still goes on to solve for X. Iterative refinement is applied to improve the computed solution. 4. LA-GESVX also optionally computes the reciprocal pivot growth factor and. for each solution vector X j , the estimated forward error bound and the componentwise relative backward error.

Arguments A

(input/output] REAL or COMPLEX square array, shape (:,:). On entry, the matrix A or its equilibration: If FACT = T' and EQUED ^ 'N' then A has been equilibrated by the scaling factors in R and/or C during a previous call to LA_GESVX. On exit, if FACT = 'E!, then the equilibrated version of A is stored in A; otherwise. A is unchanged.

B

(input/output) REAL or COMPLEX array, shape (:,:) with size(B. 1) = size(A, 1) or shape (:) with size(B) = size(A,l). On entry, the matrix B. On exit, the scaled version of B if the system has been equilibrated; otherwise. B is unchanged.

X

(output) REAL or COMPLEX array, shape (:,:) with size(X, 1) = size(A, 1) and size(X, 2) = szze(B,2), or shape (:) with sz'ze(X) — size(A, I ) . The solution matrix X.

AF

Optional (input or output] REAL or COMPLEX square array, shape (:,:) with the same size as A. If FACT = 'F' then AF is an input argument that contains the factors L and U of (the equilibrated) A returned by a previous call to LA_GESVX. If FACT ^ 'F' then AF is an output argument that contains the factors L and U of (the equilibrated) A.

IPIV

Optional (input or output) INTEGER array, shape (:) with size(IPYV) = size(A, I). If FACT = 'F' then IPIV is an input argument that contains the pivot indices from the factorization of (the equilibrated) A, returned by a previous call to LA_GESVX. If FACT ^ 'F' then IPIV is an output argument that contains the pivot indices from the factorization of (the equilibrated) A. Optional (input) CHARACTER(LEN=1). Specifies whether the factored form of the matrix A is supplied on entry, and. if not, whether the matrix A should be equilibrated before it is factored. = 'N': The matrix A will be copied to AF and factored (no equilibration). = 'E': The matrix A will be equilibrated, then copied to AF and factored. = 'F': AF and IPIV contain the factored form of (the equilibrated) A. Default value: 'N'.

FACT

TRANS

Optional (input) CHARACTER(LEN=1). Specifies the form of the system of equations: = 'N': AX = B (No transpose) = 'T': ATX = B (Transpose) = 'C': AHX = B (Conjugate transpose)

General Linear Systems

56 Default value: 'N'. EQUED

Optional (input or output) CHARACTER(LEN=1). Specifies the form of equilibration that was done. EQUED is an input argument if FACT = 'F', otherwise it is an output argument: = 'N': No equilibration (always true if FACT = 'N'). = 'R': Row equilibration, i.e., A has been premultiplied by diag(R). = 'C': Column equilibration, i.e., A has been postmultiplied by diag(C). = 'B': Both row and column equilibration. Default value: 'N'.

R

Optional (input or output) REAL array, shape (:) with size(R) = size(A, I ) . The row scale factors for A. R is an input argument if FACT = 'F' and EQUED = 'R' or 'B'. R is an output argument if FACT = 'E' and EQUED = 'R' or 'B'.

C

Optional (input or output) REAL array, shape (:) with size(C) = size(A, 1). The column scale factors for A. C is an input argument if FACT = 'F' and EQUED = 'C' or 'B'. C is an output argument if FACT = 'E' and EQUED = 'C' or 'B'.

FERR

Optional (output) REAL array of shape (:), with szze(FERR) = size(X,2), or REAL scalar. The estimated forward error bound for each solution vector Xj (the j-th column of the solution matrix X). If XTRUE is the true solution corresponding to X j , FERRj is an estimated upper bound for the magnitude of the largest element in (Xj — XTRUE) divided by the magnitude of the largest element in Xr The estimate is as reliable as the estimate for RCOND and is almost always a slight overestimate of the true error.

BERR

Optional (output] REAL array of shape (:), with sz,ze(BERR) = size(K, 2), or REAL scalar. The componentwise relative backward error of each solution vector Xj (i.e., the smallest relative change in any element of A or B that makes Xj an exact solution).

RCOND

Optional (output) REAL. The estimate of the reciprocal condition number of (the equilibrated) A. If RCOND is less than the machine precision, the matrix is singular to working precision. This condition is indicated by a return code of INFO > 0.

RPVGRW Optional (output) REAL. The reciprocal pivot growth factor ||A||oo/||?7||oo- If RPVGRW is much less than 1, then the stability of the LU factorization of the (equilibrated) matrix A could be poor. This also means that the solution X, condition estimator RCOND, and forward error bound FERR could be unreliable. If the factorization fails with 0 < INFO < size(A, 1), then RPVGRW contains the reciprocal pivot growth factor for the leading INFO columns of A.

INFO

Optional (output) INTEGER = 0: successful exit. < 0: if INFO = —z, the ith argument had an illegal value. > 0: if INFO = t, and » is < n: Ui,i = 0. The factorization has been completed, but the factor U is singular, so the solution could not be computed. = n-fl: U is nonsingular, but RCOND is less than machine precision, so the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because the computed solution can be more accurate than the value of RCOND would suggest. If INFO is not present and an error occurs, then the program is terminated with an error message.

LA_GESVX

57

References: [1] and [17, 9, 20, 21]. Example (from Program LA_GESVX_EXAMPLE) The results below are computed with e = 1.19209 x 10~7. A and B are the same as in Example 1 for LA_GESV. The call:

CALL LA_GESVX(A, B, X, FERR=FERR, BERR=BERR, & RCOND=RCOND, RPVGRW=RPVGRW ) FERR, BERR, RCOND and RPVGRW on exit: FERR BERR

The forward and backward errors of the three solution vectors are:

The estimate of the reciprocal condition number of A is 1.14296 x 10~2. The reciprocal pivot growth factor is 1.12500. The solution of the system A X = B is:

5.1.3

LA_GBSV

SUBROUTINE LA_GBSV( AB, B, KL=kl, IPIV=ipiv, INFO=info ) type(wp), INTENT(INOUT) :: AB(:,:), rhs INTEGER, INTENT(IN), OPTIONAL :: KL INTEGER, INTENT(OUT), OPTIONAL :: IPIV(:) INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(:,:) | B(:)

58

General Linear Systems

Purpose LA_GBSV computes the solution to a real or complex linear system of equations AX = B, where A is a square band matrix and X and B are rectangular matrices or vectors. The L U decomposition with row interchanges is used to factor A as A = L U, where L is a. product of permutation and unit lower triangular matrices with kl subdiagonals, and U is upper triangular with kl + ku superdiagonals. The factored form of A is then used to solve the above system.

Arguments AB

(input/output) REAL or COMPLEX rectangular array, shape (:,:) with size(AB, 1) — 2kl + ku + 1 and size(AB, 2) = n, where kl and ku are, respectively, the numbers of subdiagonals and superdiagonals in the band of A, and n is the order of A. On entry, the matrix A in band storage. The (kl + ku + 1) diagonals of A are stored in rows (kl + 1) to (2kl + ku + 1) of AB, so that the jth column of A is stored in the jth column of AB as follows:

The remaining elements in AB need not be set. On exit, details of the factorization. U is an upper triangular band matrix with (kl + ku+l) diagonals. These are stored in the first (kl + ku + 1) rows of AB. The multipliers that arise during the factorization are stored in the remaining rows. B

(input/output) REAL or COMPLEX array, shape (:,:) with size(B, 1) = n or shape (:) with size(B) = n. On entry, the matrix B. On exit, the solution matrix X.

KL

Optional (input) INTEGER. The number of subdiagonals in the band of A (KL = kl). The number of superdiagonals in the band is given by ku — size(AB, 1) — 2 kl — 1. Default value: (size(AB, 1) - l)/3.

IPIV

Optional (output) INTEGER array, shape (:) with size(IPlV) = n. The pivot indices that define the row interchanges; row i of the matrix was interchanged with row IPIVi .

INFO

Optional (output) INTEGER — 0: successful exit. < 0: if INFO = —i, the iih argument had an illegal value. > 0: if INFO = i, U(i, i) = 0. The factorization has been completed, but the factor U is singular, so the solution could not be computed. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20].

59

LA_GBSV

Examples Example 1 The band storage scheme is illustrated by the following example, where n = 9, kl = 2 and ku — 1, making size(AB, 1) = 6 and size(AB,2) = 9.

AB on entry

AB on exit

Elements marked * are not referenced by the routine. Elements marked o need not be set on entry. This extra space is needed for U because of the row interchanges.

Example 2 (from Program LA_GBSV_EXAMPLE) The results below are computed with

60

Arrays AB and B on entry:

The call: CALL LA_GBSV( AB, B, 2, IPIV, INFO ) AB. B. IPIV and INFO on exit:

M - Multipliers

Matrices U and X, where X is the solution of the system AX = B:

General Linear Systems

61

LA_GBSVX

5.1.4

LA_GBSVX

SUBROUTINE LA_GBSVX( AB, B, X, KL=kl, AFB=afb, IPIV=ipiv, & FACT=fact, TRANS=trans, EQUED=equed, R=r, C=c, & FERR^ferr, BERR=berr, RCOND=rcond, & RPVGRW=rpvgrw, INFO^info ) type(wp), INTENT(INOUT) :: AB(:,:), rhs type(wp), INTENT (OUT) :: sol INTEGER, INTENT(IN), OPTIONAL :: KL type(wp), INTENT(INOUT), OPTIONAL :: AFB(:,:) INTEGER, INTENT(INOUT), OPTIONAL :: IPIV(:) CHARACTER(LEN=:1), INTENT(IN), OPTIONAL :: TRANS, FACT CHARACTER(LEN=1), INTENT(INOUT), OPTIONAL :: EQUED REAL(iup), INTENT(INOUT), OPTIONAL :: C(:), R(:) REAL (tup), INTENT (OUT), OPTIONAL :: err, RCOND, RPVGRW INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(:,:) | B(:) sol ::= X(:,:) | X(:)

err ::= FERR(:), BERR(:) | FERR, BERR

Purpose LA_GBSVX computes the solution to a real or complex linear system of equations of the form AX — B: ATX = B or AHX — B, where A is a square band matrix and X and B are rectangular matrices or vectors. LA_GBSVX can also optionally equilibrate the system if A is poorly scaled, estimate the condition number of (the equilibrated) A, return the pivot growth factor, and compute error bounds.

Description 1. If FACT — 'E'. then real row scaling factors Rx and/or real column scaling factors d are computed to equilibrate the system. The form of the equilibrated system depends on the value of TRANS: TRANS 'N' T' ,c,

The equilibrated system [diag(R) A diag(C}} [diag(C)-lX] = diag(R) B [(diag(R}Adiag(C))T] [diag(R)~lX] = diag(C) B [ ( d i a g ( R ) A d i a g ( C ) ) H ] [diag(R)-1 X] = diag(C) B

Depending on the value of EQUED determined during the equilibration, the matrices diag(R) and/or diag(C) may be implicitly the identity matrix:

EQUED 'N' 'R' 'C' 'B'

diag(R) Identity diag(R) Identity diag(R)

diag(C) Identity Identity diag(C) diag(C)

2. If FACT = 'N'. the LU decomposition with row interchanges is used to factor A as A — LU, where L is a product of permutation and unit lower triangular matrices with kl subdiagonals, and U is upper triangular with kl + ku superdiagonals. If FACT = 'E', the equilibrated matrix is factored as LU.

62

General Linear Systems

3. If some £7^ = 0, so that U is singular, then the routine returns with INFO = i. Otherwise, an estimate of the condition number of (the equilibrated) A is found using the above factorization. If the reciprocal of the condition number is less than machine precision, INFO = n + 1, where n is the order of A, is returned as a warning. However, the routine still goes on to solve for X. Iterative refinement is applied to improve the computed solution. 4. LA_GBSVX also optionally computes the reciprocal pivot growth factor and, for each solution vector X j , the estimated forward error bound and the componentwise relative backward error.

Arguments AB

B

X

KL

AFB

IPIV

(input/output] REAL or COMPLEX rectangular array, shape (:,:) with size(AB, 1) = kl + ku -f 1 and szze(AB, 2) = n, where kl and ku are, respectively, the numbers of subdiagonals and superdiagonals in the band of A, and n is the order of A. On entry, the matrix A or its equilibration in band storage. The (kl + ku + 1) diagonals of A are stored in rows 1 to (kl + ku + 1) of AB, so that the jih column of A is stored in the jth column of AB as follows:

The remaining elements in AB need not be set. If FACT = 'F' and EQUED ^ 'N' then A has been equilibrated by the scaling factors in R and/or C during the previous call to LA_GBSVX. On exit, if FACT = 'E', the equilibrated version of A is stored in AB; otherwise. AB is unchanged. (input/output) REAL or COMPLEX array, shape (:,:) with size(B, 1) = n or shape (:) with size(B) = n. On entry, the matrix B. On exit, the scaled version of B if the system has been equilibrated; otherwise, B is unchanged. (output) REAL or COMPLEX array, shape (:,:) with size(X, 1) — n and size(X,2) = size(B,2), or shape (:) with size(X.) = n. The solution matrix X. Optional (input) INTEGER. The number of subdiagonals in the band of A (KL = kl). The number of superdiagonals in the band is given by ku = size(AB, 1) — kl — 1. Default value: (size(AB, 1) - l)/2. Optional (input or output) REAL or COMPLEX rectangular array, shape (:,:) with s«'ze(AFB, 1) 2kl + ku + 1 and size(AFB, 2) = n If FACT = 'F' then AFB is an input argument that contains the details of the factorization of (the equilibrated) A returned by a previous call to LA_GBSVX. If FACT 7^ 'F' then AFB is an output argument that contains the details of the factorization of (the equilibrated) A. U is an upper triangular band matrix with (kl + ku + 1) diagonals. These are stored in the first (kl + ku + 1) rows of AFB. The multipliers that arise during the factorization are stored in the remaining rows. Optional (input or output) INTEGER array, shape (:) with size(lPIV) = n. If FACT = 'F' then IPIV is an input argument that contains the pivot indices from the factorization of (the equilibrated) A, returned by a previous call to LA_GBSVX. If FACT 7^ 'F' then IPIV is an output argument that contains the pivot indices from the factorization of (the equilibrated) A.

LA.GBSVX FACT

63

Optional (input) CHARACTER(LEN=1). Specifies whether the factored form of the matrix A is supplied on entry, and, if not. whether the matrix A should be equilibrated before it is factored. = 'N': The matrix A will be copied to AFB and factored (no equilibration). = 'E': The matrix A will be equilibrated, then copied to AFB and factored. = 'F': AFB and IPIV contain the factored form of (the equilibrated) A. Default value: 'N'.

TRANS

Optional (input) CHARACTER(LEN=1). Specifies the form of the system of equations: = 'N': AX = B (No transpose) = T: ATX = B (Transpose) = 'C': AHX = B (Conjugate transpose) Default value: 'N'.

EQUED

Optional (input or output) CHARACTER(LEN=1). Specifies the form of equilibration that was done. EQUED is an input argument if FACT = 'F'. otherwise it is an output argument: = 'N': No equilibration (always true if FACT = 'N'). = 'R': Row equilibration, i.e., A has been premultiplied by diag(R). — 'C': Column equilibration, i.e.. A has been postmultiplied by diag(C). = 'B:: Both row and column equilibration. Default value: 'N'.

R

Optional (input or output) REAL array, shape (:) with size(R) — size(A. I ) . The row scale factors for A. R is an input argument if FACT = 'F' and EQUED = 'R' or 'B'. R is an output argument if FACT = 'E' and EQUED = 'R' or 'B'.

C

Optional (input or output) REAL array, shape (:) with size(C) — size(A, I). The column scale factors for A. C is an input argument if FACT = 'F; and EQUED = 'C' or 'B'. C is an output argument if FACT = 'E' and EQUED = 'C' or 'B'.

FERR

Optional (output) REAL array of shape (:). with size(FERR) = size(X., 2), or REAL scalar. The estimated forward error bound for each solution vector Xj (the j'-th column of the solution matrix X). If XT RUE is the true solution corresponding to Xj, FERRj is an estimated upper bound for the magnitude of the largest element in (Xj — XTRUE) divided by the magnitude of the largest element in Xj. The estimate is as reliable as the estimate for RCOND and is almost always a slight overestimate of the true error.

BERR

Optional (output) REAL array of shape (:), with size(BERR) — size(X, 2), or REAL scalar. The componentwise relative backward error of each solution vector Xj (i.e., the smallest relative change in any element of A or B that makes Xj an exact solution).

RCOND

Optional (output) REAL. The estimate of the reciprocal condition number of (the equilibrated) A. If RCOND is less than the machine precision, the matrix is singular to working precision. This condition is indicated by a return code of INFO > 0.

RPVGRW Optional (output) REAL. The reciprocal pivot growth factor IIAHoo/IJC/Uoo- If RPVGRW is much less than 1, then the stability of the LU factorization of the (equilibrated) matrix A could be poor. This also means that the solution X. condition estimator RCOND, and forward error bound FERR could be unreliable. If the factorization fails with 0 < INFO < size(A, 1), then RPVGRW contains the reciprocal pivot growth factor for the leading INFO columns of A.

General Linear Systems

64

INFO

Optional (output) INTEGER = 0: successful exit. < 0: if INFO = — i, the ith argument had an illegal value. > 0: if INFO = i, and i is < n: Uiti = 0. The factorization has been completed, but the factor U is singular, so the solution could not be computed. = n+1: U is nonsingular, but RCOND is less than machine precision, so the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because the computed solution can be more accurate than the value of RCOND would suggest. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20, 21].

Example (from Program LA.GBSVXJEXAMPLE) The results below are computed with e = 1.19209 x 10~7. A and B are the same as in Example 2 for LA_GBSV. except that the first column of A is multiplied by 6

io- .

Arrays AB and B on entry:

Elements marked * are not referenced by the routine. The call: CALL LA_GBSVX( AB, B, X, 2, FACT='E', TRANSIT', EQUED=EQUED, & R=R, C—C, FERR=^FERR, BERR—BERR ) X, EQUED, R, C, FERR and BERR on exit:

EQUED = 'C'

65

LA_GBSVX FERR

BERR

The solution of the system

The columns of matrix A were equilibrated by multiplication from the right with the matrix

The forward and backward errors of the two solution vectors are:

5.1.5

LA_GTSV

SUBROUTINE LA_GTSV( DL, D, DU, B, INFO=info ) type(wp), INTENT(INOUT) :: DL(:), D(:), DU(:), rhs INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(:,:) | B(:)

Purpose LA_GTSV computes the solution to a real or complex linear system of equations AX = B, where A is a square tridiagonal matrix and X and B are rectangular matrices or vectors. The LU decomposition is used to factor the matrix A as A = LU, where L is a product of permutation and unit lower bidiagonal matrices and U is upper triangular with nonzeros in only the main diagonal and first two superdiagonals. The factored form of A is then used to solve the above system. Note: The system ATX = B may be solved by interchanging the order of the arguments DU and DL.

Arguments DL

(input/output) REAL or COMPLEX array, shape (:) with size(DL) •= n — 1, where n is the order of A. On entry, the subdiagonal of A. On exit, the n — 2 elements of the second superdiagonal of U in DLi, • • • , DL n _2-

66

General Linear Systems

D

(input/output) REAL or COMPLEX array, shape (:) with size(D) = n. On entry, the diagonal of A. On exit, the diagonal of U.

DU

(input/output) REAL or COMPLEX array, shape (:) with size(DL) = n — I. On entry, the superdiagonal of A. On exit, the first superdiagonal of U.

B

(input/output) REAL or COMPLEX array, shape (:,:) with size(B: 1) = n or shape (:) with size(B) = n. On entry, the matrix B. On exit, the solution matrix X.

INFO

Optional (output) INTEGER = 0: successful exit. < 0: if INFO = —z, the ith argument had an illegal value. > 0: if INFO = i, then U^i = 0. The factorization has not been completed unless i = n. The factor U is singular, so the solution could not be computed. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20].

Example (from Program LA_GTSVJBXAMPLE) The results below are computed with

Arrays DL, D, DU and B on entry:

DL 1 4 6 6 4

D 2 5 8 8 4 9

The call: CALL LA_GTSV( DL, D, DU, B, INFO )

DU 2 4 4 6 3

4 10 16 20 13 13

B 8 20 32 40 26 26

12 30 48 60 39 39

67

LA.GTSV DL, D, DU, B and INFO on exit: DL 0 0 6 3 o

D 2 4 6 6 4 7.66667

DU

2 4 8 4 _9_

B

1.00000 1.00000 1.00000 1.00000 1.00000 1.00000

2.00000 2.00000 2.00000 2.00000 2.00000 2.00000

3.00000 3.00000 3.00000 3.00000 3.00000 3.00000

INFO = 0

Element marked o is not used on exit. Matrix U and the solution of the system A X = B are:

5.1.6

LA_GTSVX

SUBROUTINE LA_GTSVX( DL, D, DU, B, X, DLF=dlf, DF=df, DUF=duf, & DU2=du2, IPIV=ipiv, FACT=fact, TRANS=trans, FERR=ferr, & BERR=berr, RCOND=rcond, INFO=info ) type(wp), INTENT(IN) :: DL(:), D(:), DU(:), rhs type(wp), INTENT(OUT) :: sol type(wp), INTENT(INOUT), OPTIONAL :: DLF(:), DF(:), DUF(:), DU2(:) INTEGER, INTENT(INOUT), OPTIONAL :: IPIV(:) CHARACTER(LEN=1), INTENT (IN), OPTIONAL :: FACT, TRANS REAL(wp), INTENT (OUT), OPTIONAL :: err REAL(twp), INTENT (OUT), OPTIONAL :: RCOND INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(:,:) | B(:) sol ::= X(:,:) | X(:)

err ::= FERR(:), BERR(:) | FERR, BERR

Purpose LA_GTSVX computes the solution to a real or complex linear system of equations of the form AX — B, ATX = B or AHX = B. where A is a square tridiagonal matrix arid X and B are rectangular matrices or vectors. LA_GTSVX can also optionally estimate the condition number of A and compute error bounds.

Description 1. If FACT = 'N', the LU decomposition is used to factor the matrix A as A — LU, where L is a product of permutation and unit lower bidiagonal matrices and U is upper triangular with nonzeros in only the

General Linear Systems

68

main diagonal and first two superdiagonals. 2. If some U^i = 0, so that U is singular, then the routine returns with INFO = i. Otherwise, the factored form of A is used to estimate the condition number of A. If the reciprocal of the condition number is less than machine precision, INFO = n + 1, where n is the order of A, is returned as a warning. However, the routine still goes on to solve for X. Iterative refinement is applied to improve the computed solution. 3. LA_GTSVX also optionally computes, for each solution vector Xj the estimated forward error bound and the componentwise backward error.

Arguments DL (input) D DU

B

DLF

DF

DUF DU2

IPIV

FACT

REAL or COMPLEX array, shape (:) with size(DL) = n - I. The subdiagonal of A. (input) REAL or COMPLEX array, shape (:) with size(D) = n. The diagonal of A. (input) REAL or COMPLEX array, shape (:) with s-ize(DU) - n - I. The superdiagonal of A. (input/output) REAL or COMPLEX array, shape (:,:) with size(B, 1) = n or shape (:) with size(B) — n. The matrix B. (output] REAL or COMPLEX array, shape (:,:) with size(X., 1) = n and size(K,2) = size(B, 2), or shape (:) with size(X.) = n. The solution matrix X. Optional (input or output) REAL or COMPLEX array, shape (:) with size(DLF) = n — 1. If FACT = 'F' then DLF is an input argument that contains the multipliers that define the matrix L from the LU factorization of A. If FACT = 'N' then DLF is an output argument that contains the multipliers that define the matrix L from the LU factorization of A. Optional (input or output) REAL or COMPLEX array, shape (:) with size(DF)= n. If FACT = 'F' then DF is an input argument that contains the diagonal of the matrix U. If FACT = 'N' then DF is an output argument that contains the diagonal of the matrix U. Optional (input or output) REAL or COMPLEX array, shape (:) with size(DUF) = n — 1. If FACT = 'F' then DUF is an input argument that contains the first superdiagonal of U. If FACT = 'N' then DUF is an output argument that contains the first superdiagonal of U. Optional (input or output) REAL or COMPLEX array, shape (:) with size(DV2) = n — 2. If FACT = 'F', then DU2 is an input argument that contains the second superdiagonal of U. If FACT = 'N', then DU2 is an output argument that contains the second superdiagonal of U. Optional (input or output) INTEGER array, shape (:) with size(IPIV) = n. If FACT = 'F' then IPIV is an input argument that contains the pivot indices from the L U factorization of A. If FACT = 'N', then IPIV is an output argument that contains the pivot indices from the LU factorization of A; row i of the matrix was interchanged with row IPIVj. IPIVj will always be either i or i + 1; IPIVj = i indicates a row interchange was not required.

Optional (input) CHARACTER(LEN=1).

Specifies whether the factored form of A is supplied on entry. = 'N': The matrix will be copied to DLF, DF and DUF and factored. = 'F': DLF, DF, DUF, DU2 and IPIV contain the factored form of A.

69

LA_GTSVX

TRANS

FERR

BERR RCOND

INFO

Default value: 'N'. Optional ('input) CHARACTER(LEN=1). Specifies the form of the system of equations: = 'N': AX - B (No transpose) = "T: ATX = B (Transpose) = 'C': AHX = B (Conjugate transpose) Default value: 'N'. Optional (output) REAL array of shape (:), with size(FERR) = size(X,2). or REAL scalar. The estimated forward error bound for each solution vector Xj (the j-th column of the solution matrix X). If XT RUE is the true solution corresponding to X j , FERRj is an estimated upper bound for the magnitude of the largest element in (Xj — XT RUE) divided by the magnitude of the largest element in Xj. The estimate is as reliable as the estimate for RCOND and is almost always a slight overestimate of the true error. Optional (output) REAL array of shape (:), with size(BERR) = size(X.2). or REAL scalar. The componentwise relative backward error of each solution vector Xj (i.e.. the smallest relative change in any element of A or B that makes Xj an exact solution). Optional (output) REAL. The estimate of the reciprocal condition number of the matrix A. If RCOND is less than the machine precision, the matrix is singular to working precision. This condition is indicated by a return code of INFO > 0. Optional (output) INTEGER = 0: successful exit. th < 0: if INFO — —i, the i argument had an illegal value. > 0: if INFO = i, and i is < n: U^i = 0. The factorization has not been completed unless i = n. The factor U is singular, so the solution could not be computed. — n+1: U is nonsingular. but RCOND is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because the computed solution can be more accurate than the value of RCOND would suggest. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20, 21].

Example (from Program LA_GTSVXJEXAMPLE) The results below are computed with e = 1.19209 x 10 7. A is the same as in the example for LA_GTSV.

The call:

Symmetric/Hermitian Positive Definite Linear Systems

70

CALL LA_GTSVX(DL, D, DU, B, X, DLF, DF, DUF, DU2, TRANS=T' ) X, DLF, DF, DUF, DU2 and IPIV on exit: X

DLF

DF

DUF

DU2

IPIV

Matrix U and the solution of the system AT X = B are:

5.2

Symmetric/Hermitian Positive Definite Linear Systems

5.2.1

LAJPOSV

SUBROUTINE LA_POSV( A, B, UPLO=uplo, INFO=info ) type(wp), INTENT(INOUT) :: A(:,:), rhs CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: UPLO INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(:,:) | B(:)

Purpose LAJPOSV computes the solution to a linear system of equations AX = B, where A is real symmetric or complex Hermitian and, in either case, positive definite, and where X and B are rectangular matrices or vectors. The Cholesky decomposition is used to factor A as

71

LA_POSV

where U is an upper triangular matrix and L is a lower triangular matrix (L — U H ) . The factored form of A is then used to solve the above system.

Arguments A

(input/output) REAL or COMPLEX square array, shape (:,:). On entry, the matrix A. If UPLO = 'U', the upper triangular part of A contains the upper triangular part of the matrix A, and the strictly lower triangular part of A is not referenced. If UPLO = 'L'. the lower triangular part of A contains the lower triangular part of the matrix A, and the strictly upper triangular part of A is riot referenced. On exit, the factor U or L from the Cholesky factorization

B

(input/output) REAL or COMPLEX array, shape (:,:) with size(B, 1) = size(A, I) or shape (:) with size(H) = size(A,l). On entry, the matrix B. On exit, the solution matrix X.

UPLO

Optional (input) CHARACTER(LEN=1) = 'U': Upper triangle of A is stored; = 'L': Lower triangle of A is stored. Default value: 'U'.

INFO

Optional (output) INTEGER = 0: successful exit. < 0: if INFO = —i, the iih argument had an illegal value. > 0: if INFO = i, the leading minor of order i of A is not positive definite, so the factorization could not be completed and the solution could not be computed. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20].

Examples The results below are computed with e = 1.19209 x 10~7.

Example 1 (from Program LA_POSV_EXAMPLE)

72

Symmetric/Hermitian Positive Definite Linear Systems

Arrays A and B on entry:

Elements marked * are not used by the routine. The call: CALL LA_POSV( A, B ) Arrays A and B on exit:

1.00000 1.00000 1.00000 1.00000 1.00000

B 2.00000 2.00000 2.00000 2.00000 2.00000

3.00000 3.00000 3.00000 3.00000 3.00000

Matrices U and X, where A = UTU and X is the solution of the system AX = B:

Example 2 (from Program LA_POSV_EXAMPLE) A on entry: As in Example 1. B on entry: J5:>i, where B is the input matrix in Example 1.

38 * 3 48 4 6 6 7 5 7

A * * * * * * 52 * * 1 56 * 6 10 74

B(:,l) 56 71 69 80 102

LA_POSV Elements marked * are not used by the routine. The call: CALL LA_POSV( A, B(:,l), = 'L' A and B(:, 1) on exit:

L and x. where A — L L and x is the solution of the system

5.2.2

LA_POSVX

SUBROUTINE LA_POSVX( A, B, X, UPLO^uplo, AF=a£, FACT=fact, & EQUED=equed, S=s, FERR=ferr, BERR=berr, & RCOND=rcond, INFO=info ) type(wp), INTENT(INOUT) :: A(:,:), rhs type(wp), INTENT(OUT) :: sol CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: UPLO type(wp), INTENT(INOUT), OPTIONAL :: AF(:,:) CHARACTER(LEN=1), INTENT (IN), OPTIONAL :: FACT CHARACTER(LEN-l), INTENT(INOUT), OPTIONAL :: EQUED REAL(wp), INTENT (INOUT), OPTIONAL :: S(:) REAL(wp), INTENT(OUT), OPTIONAL :: err REAL (tup), INTENT (OUT), OPTIONAL :: RCOND INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(:,:) | B(:) sol ::= X(:,:) | X(:) err ::= FERR(:), BERR(:) | FERR, BERR

73

74

Symmetric/Hermitian Positive Definite Linear Systems

Purpose LA-POSVX computes the solution to a linear system of equations AX = B, where A is real symmetric or complex Hermitian and, in either case, positive definite, and where X and B are rectangular matrices or vectors. LA_POSVX can also optionally equilibrate the system if A is poorly scaled, estimate the condition number of (the equilibrated) A, and compute error bounds.

Description 1. If FACT = 'E', then real scaling factors Si are computed to equilibrate the system:

[diag(S)Adiag(S)][diag(SrlX] X] = diag(S)B Depending on the value of EQUED determined during the equilibration, the matrix diag(S) may be implicitly the identity matrix: EQUED diag(S) 'N' Identity 'Y' diag(S) 2. If FACT = 'N', the Cholesky decomposition is used to factor the matrix A as A = UHU if UPLO = 'U', or A = L LH if UPLO = 'L' where U is an upper triangular matrix and L is a lower triangular matrix (L = UH). If FACT = 'E', the equilibrated matrix is factored as UHU or LLH. 3. If the leading minor of order i of (the equilibrated) A is not positive definite, then the routine returns with INFO — i. Otherwise, an estimate of the condition number of (the equilibrated) A is found using the above factorization. If the reciprocal of the condition number is less than machine precision, INFO = n + 1, where n is the order of A, is returned as a warning. However, the routine still goes on to solve for X. Iterative refinement is applied to improve the computed solution. 4. LAJPOSVX also optionally computes, for each solution vector X j , the estimated forward error bound and the componentwise relative backward error.

Arguments A

(input/output) REAL or COMPLEX square array, shape (:,:). On entry, the matrix A or its equilibration: If UPLO = 'U', then the upper triangular part of A contains the upper triangular part of (the equilibrated) A, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', then the lower triangular part of A contains the lower triangular part of (the equilibrated) A, and the strictly upper triangular part of A is not referenced. If FACT = 'F' and EQUED = 'Y', then A has been equilibrated by the scaling factors in S during a previous call to LA_POSVX. On exit, if FACT = 'E', then the equilibrated version of A is stored in A; otherwise, A is unchanged.

B

(input/output) REAL or COMPLEX array, shape (:,:) with size(B, 1) = size(A, 1) or shape (:) with size(B) = size(A, 1). On entry, the matrix B. On exit, the scaled version of B if the system has been equilibrated; otherwise, B is unchanged.

LA.POSVX X

UPLO

AF

FACT

EQUED

S

FERR

BERR

RCOND

INFO

75

(output) REAL or COMPLEX array, shape (:.:) with size(K, 1) = size(A, 1) and size(X. 2) = size(B,2), or shape (:) with szze(X) = size(A, 1). The solution matrix X. Optional (input) CHARACTER(LEN=1). = 'U': Upper triangle of A is stored; = 'L': Lower triangle of A is stored. Default value: 'U'. Optional (input or output) REAL or COMPLEX array, shape (:,:) with the same size as A. If FACT = 'F' then AF is an input argument that contains the factor U or L from the Cholesky factorization of (the equilibrated) A, in the same storage format as A. returned by a previous call to LA_POSVX If FACT 7^ 'F' then AF is an output argument that contains the factor U or L from the Cholesky factorization of (the equilibrated) A in the same storage format as A. Optional (input) CHARACTER(LEN=1). Specifies whether the factored form of the matrix A is supplied on entry, arid, if not. whether A should be equilibrated before it is factored. = 'N': The matrix A will be copied to AF and factored (no equilibration). = 'E': The matrix A will be equilibrated, then copied to AF and factored. = 'F': AF contains the factored form of (the equilibrated) A. Default value: 'N'. Optional (input or output) CHARACTER(LEN=1). Specifies the form of equilibration that was done. EQUED is an input argument if FACT — 'F', otherwise it is an output argument: = 'N': No equilibration (always true if FACT = 'N'). = 'Y': Equilibration, i.e.. A has been premultiplied and postmultiplied by diag(S). Default value: 'N'. Optional (input or output) REAL array, shape (:) with size(S) = 6"ize(A, 1). The scaling factors for A. S is an input argument if FACT = 'F' and EQUED = 'Y'. S is an output argument if FACT = 'E: and EQUED = 'Y'. Optional (output) REAL array of shape (:). with size(FERR) = size(X. 2), or REAL scalar. The estimated forward error bound for each solution vector Xj (the jih column of the solution matrix X). If XT RUE is the true solution corresponding to X j , FERRj is an estimated upper bound for the magnitude of the largest element in (Xj — XT RUE) divided by the magnitude of the largest element in Xj. The estimate is as reliable as the estimate for RCOND. and is almost always a slight overestimate of the true error. Optional (output) REAL array of shape (:), with size(BERR) = size(X. 2), or REAL scalar. The componentwise relative backward error of each solution vector Xj (i.e., the smallest relative change in any element of A or B that makes Xj an exact solution). Optional (output) REAL The estimate of the reciprocal condition number of (the equilibrated) A. If RCOND is less than the machine precision, the matrix is singular to working precision. This condition is indicated by a return code of INFO > 0. Optional (output) INTEGER = 0: successful exit. < 0: if INFO = — i. the ith argument had an illegal value. > 0: if INFO = i, and i is

76

Symmetric/Hermitian Positive Definite Linear Systems < n: the leading minor of order i of (the equilibrated) A is not positive definite, so the factorization could not be completed and the solution and error bounds could not be computed. RCOND— 0 is returned. = n+1: U or L is nonsingular, but RCOND is less than machine precision, so the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because the computed solution can be more accurate than the value of RCOND would suggest. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9; 20, 21].

Example (from Program LAJPOSVX_EXAMPLE) The results below are computed with e = 1.19209 x 10~7. A and B. are the same as in Example 1 for LA JPOSV, except that the first column of A is multiplied by 10~6. The call: CALL LA_POSVX( A, B, X, FACT^'E', EQUED=EQUED, S=S ) EQUED, S, FERR and BERR on exit:

EQUED = 'Y',

FERR

BERR

Equilibration was done. The scale factors and the error bounds are:

The solution of the system A X = B is:

LA_PPSV

5.2.3

77

LA_PPSV

SUBROUTINE LA_PPSV( AP, B, UPLO=uplo, INFO=info ) type(wp), INTENT(INOUT) :: AP(:), rhs CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: UPLO INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(:,:) | B(:)

Purpose LA-PPSV computes the solution to a linear system of equations AX = B, where A is real symmetric or complex Hermitian and, in either case, positive definite, and where X and B are rectangular matrices or vectors. A is stored in packed format. The Cholesky decomposition is used to factor A as where U is an upper triangular matrix and L is a lower triangular matrix (L = U H ) . The factored form of A is then used to solve the above system.

Arguments AP

(input/output) REAL or COMPLEX array, shape (:) with size(AP) = n(n + l)/2. where n is the order of A. On entry, the upper or lower triangle of matrix A in packed storage. The elements are stored columnwise as follows: UPLO 'U' 'L'

B

UPLO

INFO

On exit, the factor U or L from the Cholesky factorization A = UHU or A = LLH, in the same storage format as A. (input/output) REAL or COMPLEX array, shape (:.:) with size(B, 1) = n or shape (:) with size(B) = n. On entry, the matrix B. On exit, the solution matrix X. Optional (input) CHARACTER(LEN=1) = 'U': Upper triangle of A is stored; = 'L': Lower triangle of A is stored. Default value: 'U'. Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = —i, the ith argument had an illegal value. > 0: if INFO = i, the leading minor of order i of A is not positive definite, so the factorization could not be completed and the solution could not be computed. If INFO is not present and an error occurs, then the program is terminated with an error message.

78

Symmetric/Hermitian Positive Definite Linear Systems

References: [1] and [17, 9, 20].

Examples Example 1 The packed storage scheme is illustrated by the following example, where n — 4:

where a^ = conjg(a^) for i.j — 1, • • • ,4. Packed storage of the upper triangle of A:

Packed storage of the lower triangle of A:

Example 2 (from Program LA_PPSV_EXAMPLE) The results below are computed with

Arrays AP and B on entry:

AP 38 3 4 6 5 48 6 7 7 52 1 6 56 10 74

The call: CALL LAJPPSV( AP, B, 'L' )

B 56 71 69 80 102

79

LA_PPSV Arrays AP and B on exit:

B 1.00000 1.00000 1.00000 1.00000 l.QOQOO L and x, where A = LLT and x is the solution to the system Ax = b:

5.2.4

LAJPPSVX

SUBROUTINE LA_PPSVX( AP, B, X, UPLO=uplo, AFP=afp, & FACT=fact, EQUED=equed, S=s, FERR=ferr, & BERR=berr, RCOND=rcond, INFO=info ) type(wp), INTENT(INOUT) :: AP(:), rhs type(wp), INTENT(OUT) :: sol CHARACTER(LEN=a), INTENT(IN), OPTIONAL :: UPLO type(wp), INTENT(INOUT), OPTIONAL :: AFP(:) CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: FACT CHARACTER(LEN=1), INTENT(INOUT), OPTIONAL :: EQUED REAL(iup), INTENT(INOUT), OPTIONAL :: S(:) REAL(V), INTENT (OUT), OPTIONAL :: err REAL(wp), INTENT(OUT), OPTIONAL :: RCOND INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL j COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(:,:) | B(:) 5 0 / : : = X ( : , : ) | X(:) err- ::= FERR(:), BERR(:) | FERR, BERR

Purpose LA_PPSVX computes the solution to a linear system of equations AX — B., where A is real symmetric or complex Hermitian and, in either case, positive definite, and where X and B are rectangular matrices or vectors. A is stored in packed format. LA_PPSVX can also optionally equilibrate the system if A is poorly scaled, estimate the condition number of (the equilibrated) A, and compute error bounds.

Description 1. If FACT = 'E', then real scaling factors Si are computed to equilibrate the system:

80

Symmetric/Hermitian Positive Definite Linear Systems Depending on the value of EQUED determined during the equilibration, the matrix diag(S) may be implicitly the identity matrix: EQUED diag(S) Identity 'N' diag(S) 'Y'

2. If FACT = 'N', the Cholesky decomposition is used to factor the matrix A as

where U is an upper triangular matrix and L is a lower triangular matrix (L = UH). If FACT = 'E', the equilibrated matrix is factored as UHU or LLH. 3. If the leading minor of order i of (the equilibrated) A is not positive definite, then the routine returns with INFO = i. Otherwise, an estimate of the condition number of (the equilibrated) A is found using the above factorization. If the reciprocal of the condition number is less than machine precision, INFO = n 4- 1. where n is the order of A, is returned as a warning. However, the routine still goes on to solve for X. Iterative refinement is applied to improve the computed solution. 4. LAJPPSVX also optionally computes, for each solution vector X j , the estimated forward error bound and the componentwise relative backward error.

Arguments AP

(input/output) REAL or COMPLEX square array, shape (:) with size(AP) = n (n + l)/2, where n is a rank of the matrix A. On entry, the upper or lower triangle of matrix A, or its equilibration, in packed storage. The elements are stored columnwise as follows: UPLO 'U' 'L'

B

X

UPLO

AFP

On exit, if FACT = 'E', then the equilibrated version of A is stored in AP; otherwise, AP is unchanged. (input/output) REAL or COMPLEX array, shape (:,:) with size(B, 1) = n or shape (:) with size(B) = n. On entry, the matrix B. On exit, the scaled version of B if the system has been equilibrated; otherwise, B is unchanged. (output) REAL or COMPLEX array, shape (:,:) with size(X,l) = n and s»ze(X,2) = size(B,2), or shape (:) with size(X.) = n. The solution matrix X. Optional (input) CHARACTER(LEN=:1). = 'U': Upper triangle of A is stored; = 'L': Lower triangle of A is stored. Default value: 'U'. Optional (input or output) REAL or COMPLEX array, shape (:) with the same size as AP. If FACT = 'F' then AFP is an input argument that contains the factor U or L from the Cholesky factorization of (the equilibrated) A, in the same storage format as A, returned by a previous call to LA_PPSVX.

LA.PPSVX

81 If FACT ^ 'F' then AFP is an output argument that contains the factor U or L from the Cholesky factorization of (the equilibrated) A in the same storage format as A.

FACT

Optional (input) CHARACTER(LEN=1). Specifies whether the factored form of the matrix A is supplied on entry, and. if not. whether A should be equilibrated before it is factored. — 'N': The matrix A will be copied to AFP and factored (no equilibration). = 'E': The matrix A will be equilibrated, then copied to AFP and factored. = 'F': AFP contains the factored form of (the equilibrated) A. Default value: 'N'.

EQUED

Optional (input or output) CHARACTER(LEN^l). Specifies the form of equilibration that was done. EQUED is an input argument if FACT = 'F', otherwise it is an output argument: = 'N': No equilibration (always true if FACT = 'N'). = 'Y': Equilibration, i.e.. A has been premultiplied and postmultiplied by diag(S). Default value: 'N'.

S

Optional (input or output) REAL array, shape (:) with size(S) — size(A, I). The scaling factors for A. S is an input argument if FACT = 'F' arid EQUED = 'Y'. S is an output argument if FACT = 'E' and EQUED = 'Y'.

FERR

Optional (output) REAL array of shape (:), with size(FERR) = size(X,2), or REAL scalar. The estimated forward error bound for each solution vector Xj (the jth column of the solution matrix X). If XT RUE is the true solution corresponding to Xj, FERR^ is an estimated upper bound for the magnitude of the largest element in (Xj — XTRUE) divided by the magnitude of the largest element in Xj. The estimate is as reliable as the estimate for RCOND. and is almost always a slight overestimate of the true error.

BERR

Optional (output) REAL array of shape (:), with 6"<2:e(BERR) = size(X,2). or REAL scalar. The componentwise relative backward error of each solution vector Xj (i.e.. the smallest relative change in any element of A or B that makes Xj an exact solution).

RCOND

Optional (output) REAL The estimate of the reciprocal condition number of (the equilibrated) A. If RCOND is less than the machine precision, the matrix is singular to working precision. This condition is indicated by a return code of INFO > 0.

INFO

Optional (output) INTEGER successful exit. if INFO = —i. the ith argument had an illegal value. if INFO = i, andi is < n: the leading minor of order i of (the equilibrated) A is not positive definite, so the factorization could not be completed and the solution and error bounds could not be computed. RCOND = 0 is returned. = n+1: U or L is nonsingular, but RCOND is less than machine precision, so the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because the computed solution can be more accurate than the value of RCOND would suggest. If INFO is not present and an error occurs, then the program is terminated with an error message.

= 0: < 0: > 0:

References: [1] and [17, 9, 20, 21].

82

Symmetric/Hermitian Positive Definite Linear Systems

Example (from Program LA_PPSVX_EXAMPLE) The results below are computed with A and B are the same as in Example 2 for LA.PPSV. The call:

CALL LAJPPSVX( AP, B, X, 'L', FERR=FERR, BERR=BERR, & RCOND=RCOND ) FERR, BERR and RCOND on exit: FERR = 1.49613 x 1(T6 BERR = 4.32426 x 1(T8 RCOND = 2.91388 x KT1 The forward and backward errors are 1.49613 x 10~6 and 4.32426 x 10~8, respectively. The estimate of the reciprocal condition number is The solution of the system A x — b is:

5.2.5

LAJPBSV

SUBROUTINE LA_PBSV( AB, B, UPLO=uplo, INFO=info ) type(wp), INTENT (INOUT) :: AB(:,:), rhs CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: UPLO INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(:,:) | B(:)

Purpose LA_PBSV computes the solution to a linear system of equations AX = B, where A has band form and is real symmetric or complex Hermitian and, in either case, positive definite, and where X and B are rectangular matrices or vectors. The Cholesky decomposition is used to factor A as

where U is an upper triangular band matrix and L is a lower triangular band matrix, each with the same number of superdiagonals or subdiagonals as A. The factored form of A is then used to solve the above system.

LA_PBSV

83

Arguments AB

(input/output) REAL or COMPLEX array, shape (:.:) with size(AB, 1) = kd + 1 and yize(AB,2) = n, where kd is the number of superdiagonals or subdiagonals in the band and n is the order of A. On entry, the upper (if UPLO = 'U') or lower (if UPLO = 'L') triangle of matrix A in band storage. The (kd+ 1) diagonals of A are stored in the rows of AB so that the jih column of A is stored in the jih column of AB as follows: UPLO

'U' ;

L'

On exit, the factor U or L from the Cholesky factorization A = UHU = LLH in the same storage format as A. B

(input/output) REAL or COMPLEX array, shape (:,:) with size(B, 1) = n or shape (:) with 6-ize(B) = n. On entry, the matrix B. On exit, the solution matrix X.

UPLO

Optional (input) CHARACTER(LEN=1) = 'U': Upper triangle of A is stored; = 'L': Lower triangle of A is stored. Default value: 'U'.

INFO

Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = —z, the ith argument had an illegal value. > 0: if INFO = i, the leading minor of order i of A is not positive definite, so the factorization could not be completed and the solution could not be computed. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20].

Examples Example 1 The band storage scheme is illustrated by the following example, where n = 9 and kd = 2, making szze(AB, 1) = 3 and size(AB,2) - 9:

84

Symmetric/Hermitian Positive Definite Linear Systems

where a;j = conjg(ajj) for i,j = 1. • • • , 9. Banded storage of the upper triangle of A : AB *

*

an

*

Ci3

d-24

«35

«46

^57

^68

«79

ai2 a-23 034 045 ase «67 a?8 a?9 «22 033 Q44 QSS ^66 Q?7 QSS Q9&

Banded storage of the lower triangle of A : AB an

a

0-21 &31

032 «42

22

a

33

^44

^55

^66

^77

^88

^99

^43 «53

^54 ^64

#65 «75

^76 «86

«87 ^97

^98 *

* *

Elements marked * are not used by the routine. Example 2 (from Program LA_PBSV_EXAMPLE) The results below are computed with

AB and B on entry: AR

* * * 1 1 1 1 * * 2 2 2 2 2 * 3 3 3 3 3 3 16 22 26 28 26 22 16

The call: CALL LAJPBSV( AB, B, INFO=INFO ) AB, B and INFO on exit:

22 31 37 40 37 31 22

B

44 66 62 93 74 111 80 120 74 111 62 93 44 66

85

LA_PBSV

AB 1.90667 x KT1 3.76143 x Itr1 5.87680 x 10-1 3.93406

1.00000 1.00000 1.00000 1.00000 1.00000 1.00000 1.00000

B 2.00000 2.00000 2.00000 2.00000 2.00000 2.00000 2.00000

3.00000 3.00000 3.00000 3.00000 3.00000 3.00000 3.00000

INFO = 0

Matrices U and X, where A = UTU and X is the solution of the system AX — B:

U=

5.2.6

LA_PBSVX

SUBROUTINE LA_PBSVX( AB, B, X, UPLO=uplo, AFB=afb, FACT=fact, & EQUED=equed, S=s, FERR^ferr, BERR=berr, & RCOND=rcond, INFO=info ) type(wp), INTENT(INOUT) :: AB(:,:), rhs

type(wp), INTENT (OUT) :: sol CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: UPLO type(wp), INTENT(INOUT), OPTIONAL :: AFB(:,:) CHARACTER(LEN=1), INTENT (IN), OPTIONAL :: FACT CHARACTER(LEN=1), INTENT(INOUT), OPTIONAL :: EQUED REAL(wp), INTENT(INOUT), OPTIONAL :: S(:) REAL(wp)» INTENT(OUT), OPTIONAL :: err REAL(wp), INTENT(OUT), OPTIONAL :: RCOND INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(:,:) | B(:) sol ::= X(:,:) | X(:) err ::= FERR(:), BERR(:) | FERR, BERR

86

Symmetric/Hermitian Positive Definite Linear Systems

Purpose LA-PBSVX computes the solution to a linear system of equations AX = B, where A has band form and is real symmetric or complex Hermitian and. in either case, positive definite, and where X and B are rectangular matrices or vectors. LA.PBSVX can also optionally equilibrate the system if A is poorly scaled, estimate the condition number of (the equilibrated) A, and compute error bounds.

Description 1. If FACT = 'E', then real scaling factors Si are computed to equilibrate the system:

Depending on the value of EQUED determined during the equilibration, the matrix diag(S) may be implicitly the identity matrix: EQUED diag(S) 'N' Identity 'Y' diag(S) 2. If FACT = 'N', the Cholesky decomposition is used to factor the matrix A as

where U is an upper triangular matrix and L is a lower triangular matrix (L = UH). If FACT = 'E', the equilibrated matrix is factored as UHU or LLH'. 3. If the leading minor of order i of (the equilibrated) A is not positive definite, then the routine returns with INFO = i. Otherwise, an estimate of the condition number of (the equilibrated) A is found using the above factorization. If the reciprocal of the condition number is less than machine precision, INFO = n + 1, where n is the order of A, is returned as a warning. However, the routine still goes on to solve for X. Iterative refinement is applied to improve the computed solution. 4. LAJPBSVX also optionally computes, for each solution vector X j , the estimated forward error bound and the componentwise relative backward error.

Arguments AB

(input/output) REAL or COMPLEX array, shape (:.:) with size(AB, I) — kd + 1 and size(AB, 2) = n, where kd is the number of superdiagonals or subdiagonals and n is the order of A. On entry, the upper (if UPLO = 'U') or lower (if UPLO = 'L') triangle of matrix A, or its equilibration, in band storage. The (kd + 1) diagonals of A are stored in the rows of AB so that the jth column of A is stored in the jth column of AB as follows:

UPLO 'U' 'L' On exit, if FACT — 'E', then the equilibrated version of A is stored in AB; otherwise, AB is unchanged.

LA_PBSVX B

X UPLO

AFB

FACT

EQUED

S

FERR

BERR

RCOND

INFO

87 (input/output) REAL or COMPLEX array, shape (:,:) with size(B. 1) = n or shape (:) with s"Jze(B) = n. On entry, the matrix B. On exit, the scaled version of B if the system has been equilibrated; otherwise. B is unchanged. (output) REAL or COMPLEX array, shape (:,:) with size(X.,l) = n and size(X,2) = size(B,2), or shape (:) with size(K) — n. The solution matrix X. Optional (input) CHARACTER(LEN=1). = 'U': Upper triangle of A is stored; = 'L': Lower triangle of A is stored. Default value: 'U'. Optional (input or output) REAL or COMPLEX array, shape (:) with the same size as AB. If FACT — 'F' then AFB is an input argument that contains the factor U or L from the Cholesky factorization of (the equilibrated) A, in the same storage format as A, returned by a previous call to LAJPBSVX. If FACT ^ 'F' then AFB is an output argument that contains the factor U or L from the Cholesky factorization of (the equilibrated) A in the same storage format as A. Optional (input) CHARACTER(LEN=1). Specifies whether the factored form of the matrix A is supplied on entry, and if not. whether A should be equilibrated before it is factored. = 'N': The matrix A will be copied to AFB and factored (no equilibration). = 'E': The matrix A will be equilibrated, then copied to AFB and factored. = 'F': AFB contains the factored form of (the equilibrated) A. Default value: 'N'. Optional (input or output) CHARACTER(LEN=1). Specifies the form of equilibration that was done. EQUED is an input argument if FACT — 'F', otherwise it is an output argument = 'W: No equilibration (always true if FACT = 'N'). = 'Y:: Equilibration, i.e.. A has been premultiplied and postmultiplied by diag(S). Default value: 'N'. Optional (input or output) REAL array, shape (:) with size(S) — size(A, I). The scaling factors for A. S is an input argument if FACT = 'F' and EQUED = 'Y'. S is an output argument if FACT = 'E' and EQUED = 'Y'. Optional (output) REAL array of shape (:), with size(FERR) = s-ize(X,2), or REAL scalar. The estimated forward error bound for each solution vector Xj (the jth column of the solution matrix X). If XT RUE is the true solution corresponding to Xj, FERRj is an estimated upper bound for the magnitude of the largest element in (Xj — XT RUE) divided by the magnitude of the largest element in Xj. The estimate is as reliable as the estimate for RCOND, and is almost always a slight overestimate of the true error. Optional (output) REAL array of shape (:), with size(BERR) = size(X, 2), or REAL scalar. The componentwise relative backward error of each solution vector Xj (i.e., the smallest relative change in any element of A or B that makes Xj an exact solution). Optional (output) REAL The estimate of the reciprocal condition number of (the equilibrated) A. If RCOND is less than the machine precision, the matrix is singular to working precision. This condition is indicated by a return code of INFO > 0. Optional (output) INTEGER

88

Symmetric/Hermitian Positive Definite Linear Systems = 0: successful exit. < 0: if INFO = —i, the ith argument had an illegal value. > 0: if INFO = i, and i is < n: the leading minor of order i of (the equilibrated) A is not positive definite, so the factorization could not be completed and the solution and error bounds could not be computed. RCOND= 0 is returned. = n+1: U or L is nonsingular, but RCOND is less than machine precision, so the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because the computed solution can be more accurate than the value of RCOND would suggest. If INFO is not present and an error occurs, then the program is terminated with an error message. References: [1] and [17, 9. 20, 21].

Example (from Program LA_PBSVX_EXAMPLE) The results below are computed with e = 1.19209 x 10~7. A and B are the matrices from Example 2 for LA_PBSV. The call: CALL LA_PBSVX( A, B, X, FACT='E', EQUED=EQUED, S=S, & FERR=FERR, BERR=BERR, RCOND=RCOND ) EQUED, S, FERR, BERR and RCOND on exit:

FERR The forward and backward errors of the three solution vectors are:

The solution of the system A X = B is:

BERR

89

LA-PTSV

5.2.7

LA_PTSV

SUBROUTINE LA_PTSV( D, E, B, INFO=info ) REAL(wp), INTENT(INOUT) :: D(:) type(wp), INTENT(INOUT) :: E(:), rhs INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(:,:) | B(:)

Purpose LA.PTSV computes the solution to a linear system of equations AX — B, where A has tridiagonal form and is real symmetric or complex Hermitian and, in either case, positive definite, and where X and B are rectangular matrices or vectors. A is factored as A — LDLH, where L is a unit lower bidiagonal matrix and D is a diagonal matrix. The factored form of A is then used to solve the above system.

Arguments D

(input/output) REAL array, shape (:) with size(D) = n, where n is the order of A. On entry, the diagonal of A. On exit, the diagonal of D.

E

(input/output) REAL or COMPLEX array, shape (:), with size(E) = n — I. On entry, the subdiagonal of A. On exit, the subdiagonal of L.

B

(input/output) REAL or COMPLEX array, shape (:,:) with szze(B, 1) = n or shape (:) with size(B) = n. On entry, the matrix B. On exit, the solution matrix X.

INFO

Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = —i, the ith argument had an illegal value. > 0: if INFO = i, the leading minor of order i of A is not positive definite, and the solution has not been computed. The factorization has not been completed unless i = n. If INFO is not present and an error occurs, then the program is terminated with an error message.

References-. [1] and [17, 9, 20]. Example (from Program LAJPTSV_EXAMPLE) The results below are computed with

Symmetric/Hermitian Positive Definite Linear Systems

90 Arrays D, E and B on entry:

D 7 7 7 7 7

E 3 3 3 3

10 13 13 13 in

B 20 26 26 26 9n

30 39 39 39 sn

The call: CALL LA_PTSV( D, E, B, INFO ) D, E, B and INFO on exit:

D 7.00000 5.71429 5.42500 5.34101 5 WAQ3.

E 4.28571 x 10-1 5.25000 x 10-1 5.52995 x ID"1 5.61691 x 10-1

1.00000 1.00000 1.00000 1.00000 i nnnnn

B 2.00000 2.00000 2.00000 2.00000 9 nnnnn

3.00000 2.00000 3.00000 3.00000 3 nnnnn

INFO = 0

Matrices L and X, where A = LD LH and X is the solution of the system A X = B:

LA_PTSVX

5.2.8

91

LA_PTSVX

SUBROUTINE LA_PTSVX( D, E, B, X, DF=df, EF=ef, FACT^fact, & FERR=ferr, BERR=berr, RCOND=rcond, INFO=info ) REAL(wp), INTENT(IN) :: D(:) type(wp), INTENT(IN) :: E(:), rhs type(wp), INTENT(OUT) ::. sol REAL(wp), INTENT(INOUT), OPTIONAL :: DF(:) type(wp), INTENT(INOUT), OPTIONAL :: EF(:) CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: FACT REAL(wp), INTENT(OUT), OPTIONAL :: err, RCOND INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL j COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(:,:) | B(:) so/::=X(:,:) X(:) err ::= FERR(:), BERR(:) | FERR, BERR

Purpose LAJPTSVX computes the solution to a linear system of equations AX — B, where A has tridiagonal form and is real symmetric or complex Hermitian and, in either case, positive definite, and where X and B are rectangular matrices or vectors. LA_PTSVX can also optionally estimate the condition number of A and compute error bounds.

Description 1. If FACT = 'N', the matrix A is factored as A = LDLH, where L is a unit lower bidiagonal matrix and D is a diagonal matrix. The factorization can also be regarded as having the form A — UH DU, where U = LH. 2. If the leading minor of order i of A is not positive definite, then the routine returns with INFO = i. Otherwise, the factored form of A is used to estimate the condition number of A. If the reciprocal of the condition number is less than machine precision, INFO = n + 1, where n is the order of A. is returned as a warning. However, the routine still goes on to solve for X. Iterative refinement is applied to improve the computed solution. 3. LAJPTSVX also optionally computes, for each solution vector X j , the estimated forward error bound and the componentwise relative backward error.

Arguments D

(input) REAL array, shape (:) with size(D) — n, where n is the order of A. The diagonal of A.

E

(input) REAL or COMPLEX array, shape (:) with size(E) = n - I. The subdiagonal of A.

B

(input) REAL or COMPLEX array, shape (:,:) with size(B, 1) = n or shape (:) with size(B) = n. The matrix B.

92

Symmetric/Hermitian Positive Definite Linear Systems

X

(output) REAL or COMPLEX array, shape (:,:) with size(X, 1) = n and size(X,2) — size(B, 2), or shape (:) with size(X) — n. The solution matrix X.

DF

Optional (input or output) REAL array, shape (:) with the same size as D. If FACT = 'F', then DF is an input argument that contains the diagonal of D from the LDLH factorization of A. If FACT = 'N', then DF is an output argument that contains the diagonal of D from the LDLH factorization of A.

EF

Optional (input or output) REAL or COMPLEX array, shape (:) with the same size as E. If FACT = 'F', then EF is an input argument that contains the subdiagonal of L from the LDLH factorization of A. If FACT = 'N', then EF is an output argument that contains the subdiagonal of L from the LDLH factorization of A.

FACT

Optional (input) CHARACTER(LEN=1). Specifies whether the factored form of A has been supplied on entry. = 'N': The matrix A will be copied to DF and EF and factored. = 'F': DF and EF contain the factored form of A. Default value: 'N'.

FERR

Optional (output) REAL array of shape (:), with size(FERR) = size(X, 2), or REAL scalar. The estimated forward error bound for each solution vector Xj (the jth column of the solution matrix X). If XT RUE is the true solution corresponding to .Xj, FERRj is an estimated upper bound for the magnitude of the largest element in (Xj — XTRUE) divided by the magnitude of the largest element in X j .

BERR

Optional (output) REAL array of shape (:), with szze(BERR) = size(X, 2), or REAL scalar. The componentwise relative backward error of each solution vector Xj (i.e., the smallest relative change in any element of A or B that makes Xj an exact solution).

RCOND

Optional (output) REAL. The estimate of the reciprocal condition number of the matrix A. If RCOND is less than the machine precision, the matrix is singular to working precision. This condition is indicated by a return code of INFO > 0.

INFO

Optional (output) INTEGER — 0: successful exit. < 0: if INFO = —i, the ith argument had an illegal value. > 0: if INFO = j, and i is < n: the leading minor of order i of A is not positive definite, so the factorization could not be completed unless i = n, and the solution and error bounds could not be computed. RCOND = 0 is returned. = n+1: L is nonsingular, but RCOND is less than machine precision, so the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because the computed solution can be more accurate than the value of RCOND would suggest. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20, 21].

LA.PTSVX

93

Example (from Program LA_PTSVX_EXAMPLE) The results below are computed with e = 1.19209 x 10~7. Matrices A arid B are the same as in Example for LA_PTSV. The call: CALL LAJPTSVX( D, E, B, X, FERR=FERR, BERR=BERR, RCOND=RCOND ) FERR, BERR and RCOND on exit: FERR

BERR

RCOND

The forward and backward errors of the three solution vectors are: The estimate of the reciprocal condition number of matrix A is The solution of the system A X — B is:

5.3 5.3.1

Symmetric Indefinite Linear Systems LA_SYSV / LA_HESV

SUBROUTINE LA_SYSV / LA_HESV( A, B, UPLO=uplo, IPIV=ipiv, INFO^info ) type(wp), INTENT(INOUT) :: A(:,:), rhs CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: UPLO INTEGER, INTENT(OUT), OPTIONAL :: IPIV(:) INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(:,:) | B(:)

Purpose LA_SYSV computes the solution to a linear system of equations AX = B, where A is a real or complex symmetric matrix and X and B are rectangular matrices or vectors. A diagonal pivoting method is used to factor A as

94

Symmetric Indefinite Linear Systems

where U (or L) is a product of permutation and unit upper (or lower) triangular matrices, and D is a symmetric block diagonal matrix with 1 x 1 and 2 x 2 diagonal blocks. The factored form of A is then used to solve the above system. LA-HESV computes the solution to a linear system of equations AX = B, where A is a complex Hermitian matrix and X and B are rectangular matrices or vectors. A diagonal pivoting method is used to factor A as where U (or L) is a product of permutation and unit upper (or lower) triangular matrices, and D is a complex Hermitian block diagonal matrix with 1 x 1 and 2 x 2 diagonal blocks. The factored form of A is then used to solve the above system.

Arguments A

(input/output) REAL or COMPLEX square array, shape (:,:). On entry, the matrix A. If UPLO — 'U', the upper triangular part of A contains the upper triangular part of the matrix A, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the lower triangular part of A contains the lower triangular part of the matrix A, and the strictly upper triangular part of A is not referenced. On exit, the block diagonal matrix D and the multipliers used to obtain the factor U or L from the factorization of A.

B

(input/output) REAL or COMPLEX array, shape (:,:) with size(B, 1) — size(A, 1) or shape (:) with size(B) — size(A,l). On entry, the matrix J5. On exit, the solution matrix X.

UPLO

Optional (input) CHARACTER(LEN=1) = 'U': Upper triangle of A is stored; = 'L': Lower triangle of A is stored. Default value: 'U'.

IPIV

Optional (output) INTEGER array, shape (:) with size(IPIV) = size(A, I). Details of the row and column interchanges and the block structure of D. If IPIVfc > 0, then rows and columns k and IPIV^ were interchanged, and Dk,k is a 1 x 1 diagonal block. If IPIVjfc < 0, then there are two cases: 1. If UPLO = 'U' and IPIV* = IPPVV! < 0, then rows and columns (k - 1) and -IPIV* were interchanged and Dk-i-.k,k-i-.k is a 2 x 2 diagonal block. 2. If UPLO = 'L' and IPIV* = IPIVjt+i < 0, then rows and columns (k + 1) and -IPIVjt were interchanged and Dk:k+i,k:k+i is a 2 x 2 diagonal block.

INFO

Optional (output) INTEGER = 0: successful exit. • < 0: if INFO = —i, the ith argument had an illegal value. > 0: if INFO = i, D^i = 0. The factorization has been completed, but the block diagonal matrix D is singular, so the solution could not be computed. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20, 21].

95

LA.SYSV / LAJfESV

Examples The results below are computed with

Example 1 (from Program LA_SYSV_EXAMPLE)

Arrays A and B on entry: 0 * * * *

2 0 * * *

A 3 5 4 1 5 6 6 8 0 5 * 3 9 * * 8

i 14 19 21 23 32

B 28 38 42 46 64

42 57 63 69 96

Elements marked * are not used by the routine. The call: CALL LA_SYSV( A, B, IPIV=IPIV ) A, B and IPIV on exit:

1.00000 1.00000 1.00000 1.00000 1.00000 The solution of the system A X — B is:

B 2.00000 3.00000 2.00000 3.00000 2.00000 3.00000 2.00000 3.00000 2.00000 3.00000

IPIV

T 2 3 4 _5_

Symmetric Indefinite Linear Systems

96

Example 2 (from Program LA_SYSV_EXAMPLE) Matrix A as in Example 1 and the first column of matrix B in Example 1. Arrays A and B(:, 1) on entry: 0 2 3 5 4

* 0 5 6 6

A * * 8 0 5

* * * 3 9

B(:,l) 14 19 21 23 32

* * * * 8

Elements marked * are not used by the routine. The call: CALL LA_SYSV( A, B(:,l), 'L', IPIV, INFO ) A, B(:, 1), IPIV and INFO on exit:

B(:,l) 1.00000 1.00000 1.00000 1.00000 1.00000

IPIV -4 -4 3 4 5

INFO = 0

The solution of the system Ax = b is:

Example 3 (from Program LAJHESVJEXAMPLE)

97

LA_SYSV/LA_HESV Arrays A and B on entry:

Elements marked * are not used by the routine. The call:

CALL LA_HESV( A, B, IPIV=IPIV )

A. B and IPIV on exit:

A(continued)

B (1.00000,1.00000) (1.00000,1.00000) (1.00000,1.00000) (1.00000,1.00000) (1.00000,1.00000)

The solution of the system A x — b is:

IPIV

1

_2 -2 -2 -2

98

Symmetric Indefinite Linear Systems

5.3.2

LA.SYSVX / LA_HESVX

SUBROUTINE LA_SYSVX / LA_HESVX( A, B, X, UPLO=uplo, AF=af, & IPIV=ipiv, FACT=fact, FERR=ferr, BERR=berr, & RCOND=rcond, INFO=info ) type(wp), INTENT(IN) :: A(:,:), rhs type(wp), INTENT(OUT) :: sol CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: UPLO type(wp), INTENT(INOUT), OPTIONAL :: AF(:,:) INTEGER, INTENT(INOUT), OPTIONAL :: IPIV(:) CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: FACT REAL(iup), INTENT(OUT), OPTIONAL :: err, RCOND INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(:,:) | B(:) aoJ-::=X(:,:) | X(:) err ::= FERR(:), BERR(:) | FERR, BERR

Purpose LA_SYSVX computes the solution to a linear system of equations AX = B, where A is a real or complex symmetric matrix and X and B are rectangular matrices or vectors. LA JHESVX computes the solution to a linear system of equations A X = B, where A is a complex Hermitian matrix and X and B are rectangular matrices or vectors. LA_SYSVX and LAJHESVX can also optionally estimate the condition number of A and compute error bounds.

Description 1. If FACT — 'N', a diagonal pivoting method is used to factor the matrix A as

or where U (or L) is a product of permutation and unit upper (lower) triangular matrices, and D is symmetric (LA_SYSVX) or Hermitian (LAJHESVX) and block diagonal with 1 x 1 and 2 x 2 diagonal blocks. 2. If some Di^ — 0, so that D is singular, then the routine returns with INFO = i. Otherwise, the factored form of A is used to estimate the condition number of the matrix A. If the reciprocal of the condition number is less than machine precision, INFO = n +1, where n is the order of A: is returned as a warning. However, the routine still goes on to solve for X. Iterative refinement is applied to improve the computed solution. 3. LA.SYSVX and LA JHESVX also optionally compute, for each solution vector X j , the estimated forward error bound and the componentwise relative backward error.

Arguments A

(input) REAL or COMPLEX square array, shape (:,:). The symmetric or Hermitian matrix A.

LA.SYSVX / LAJfESVX

B

X

UPLO

AF

IPIV

FACT

FERR

BERR

RCOND

99

If UPLO = 'U', the upper triangular part of A contains the upper triangular part of the matrix A, arid the strictly lower triangular part of A is not referenced. If UPLO = 'L'. the lower triangular part of A contains the lower triangular part of the matrix A, and the strictly upper triangular part of A is not referenced. (input) REAL or COMPLEX array, shape (:,:) with size(B,l) — size(A.l) or shape (:) with size(B) = size(A, 1). The matrix B. (output) REAL or COMPLEX array, shape (:,:) with size(X, 1) = size(A, 1) and s'ize(X, 2) = size(B,2), or shape (:) with size(X) = size(A, I). The solution matrix X. Optional (input) CHARACTER(LEN=1). = 'U': Upper triangle of A is stored; = 'L': Lower triangle of A is stored. Default value: 'IT. Optional (input or output) REAL or COMPLEX array, shape (:,:) with the same size as A. If FACT — T'. then AF is an input argument that contains the block diagonal matrix D and the multipliers used to obtain the factor L or U from the factorization of A, returned by a previous call to LA.SYSVX or LA.HESVX. If FACT = : N'. then AF is an output argument that contains the block diagonal matrix D and the multipliers used to obtain the factor L or U from the factorization of A. Optional (input or output) INTEGER array, shape (:) with size(IPIV) = size(A, 1). If FACT = 'F'. then IPIV is an input argument that contains details of the row arid column interchanges and the block structure of D. If IPIVjt > 0 . then rows and columns k and IPIVjt were interchanged and Dk^ is a 1 x 1 diagonal block. If IPIVfc < 0 , then there are two cases: 1. If UPLO = ; U' and IPIVk - IPIV fc _i < 0, then rows and columns k - 1 arid —IPIVfc were interchanged and Dk-i-.k,k-i:k is a 2 x 2 diagonal block. 2. If UPLO = 'L' and IPIV* = IPIVfc+i < 0, then rows and columns k + 1 and -IPIV fc were interchanged and Dk:k+i,k-.k+\ is a 2 x 2 diagonal block. If FACT — 'N', then IPIV is an output argument that contains details of the row and column interchanges and the block structure of D] as described above. Optional (input) CHARACTER(LEN=1). Specifies whether the factored form of the matrix A has been supplied on entry. = 'N': The matrix A will be copied to AF and factored. = 'F': AF and IPIV contain the factored form of A. Default value: 'N'. Optional (output) REAL array of shape (:), with size(FERR) = size(X,2), or REAL scalar. The estimated forward error bound for each solution vector Xj (the jth column of the solution matrix X). If XT RUE is the true solution corresponding to Xj, FERRj is an estimated upper bound for the magnitude of the largest element in (Xj — XT RUE) divided by the magnitude of the largest element in Xj. The estimate is as reliable as the estimate for RCOND, and is almost always a slight overestimate of the true error. Optional (output) REAL array of shape (:), with size(BERR) = size(X, 2), or REAL scalar. The componentwise relative backward error of each solution vector Xj (i.e., the smallest relative change in any element of A or B that makes Xj an exact solution). Optional (output) REAL The estimate of the reciprocal condition number of A. If RCOND is less than the machine

100

Symmetric Indefinite Linear Systems precision, the matrix is singular to working precision. This condition is indicated by a return code of INFO > 0.

INFO

(output) INTEGER = 0: successful exit. < 0: if INFO = —z, the ith argument had an illegal value. > 0: if INFO = i, and i is < n: Dij = 0. The factorization has been completed, but the block diagonal matrix D is singular, so the solution could not be computed. = n+1: D is nonsingular, but RCOND is less than machine precision, so the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because the computed solution can be more accurate than the value of RCOND would suggest, n is the order of A. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20, 21]. Example (from Program LA_SYSVX_EXAMPLE) The results below are computed with e = 1.19209 x 10~7. Matrices A and B are the same as in Example 1 for LA_SYSV. The call: CALL LA_SYSVX( A, B, X, FERR= FERR, BERR= BERR, RCOND= RCOND )

FERR, BERR and RCOND on exit: FERR

BERR

= 3.07451 The forward and backward errors of the three solution vectors are:

The estimate of the reciprocal condition number of matrix A is The computed solution X is identical to that in Example 1 for LA_SYSV.

LA.SPSV / LAJIPSV

101

5.3.3 LAJ3PSV / LA_HPSV SUBROUTINE LA_SPSV / LA_HESV( AP, B, UPLO=uplo, & IPIV=ipiv, INFO=info ) type(wp), INTENT(INOUT) :: AP(:), rhs CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: UPLO INTEGER, INTENT(OUT), OPTIONAL :: IPIV(:) INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(:,:) | B(:)

Purpose LAJ3PSV computes the solution to a linear system of equations AX = B. where A is a real or complex symmetric matrix stored in packed format and X and B are rectangular matrices or vectors. A diagonal pivoting method is used to factor A as A = UDUT if UPLO = 'IT, or A = LDLT if UPLO = 'L' where U (or L) is a product of permutation and unit upper (or lower) triangular matrices, and D is a symmetric block diagonal matrix with 1 x 1 and 2 x 2 diagonal blocks. The factored form of A is then used to solve the above system. LAJHPSV computes the solution to a linear system of equations AX — B, where A is a complex Herinitiari matrix stored in packed format and X and B are rectangular matrices or vectors. A diagonal pivoting method is used to factor A as

where U (or L) is a product of permutation and unit upper (or lower) triangular matrices, and D is a complex Hermitian block diagonal matrix with 1 x 1 and 2 x 2 diagonal blocks. The factored form of A is then used to solve the above system.

Arguments AP

(input/output) REAL or COMPLEX array, shape (:) with size(AP) = n(n + l)/2, where n is the order of A. On entry, the upper or lower triangle of matrix A in packed storage. The elements are stored columnwise as follows: UPLO 'U' 'L'

B

On exit, the block diagonal matrix D and the multipliers used to obtain U or L from the factorization of A, stored as a packed triangular matrix in the same storage format as A. (input/output) REAL or COMPLEX array, shape (:,:) with size(B, 1) = n or shape (:) with size(B) = n. On entry, the matrix B. On exit, the solution matrix X.

102

Symmetric Indefinite Linear Systems

UPLO

Optional (input) CHARACTER(LEN=1) = !U': Upper triangle of A is stored; = 'L': Lower triangle of A is stored. Default value: 'U'.

IPIV

Optional (output) INTEGER array, shape (:) with sizeQPIV) = n. Details of the row and column interchanges and the block structure of D. If IPIVfc > 0, then rows and columns k and IPIV^ were interchanged, and Dk,k is a 1 x 1 diagonal block. If IPIVfc < 0, then there are two cases: 1. If UPLO = 'U' and IPIV* = IPIV^i were interchanged and Dk-i-.k,k-i:k is a 2. If UPLO = 'L' and IPIV*. = IPXY^ were interchanged and Dk-.k+i,k-.k+i is a

INFO

< 0, then rows and columns (Jfc - 1) and -IPIV* 2 x 2 diagonal block. < 0, then rows and columns (k + 1) and -IPIV* 2 x 2 diagonal block.

Optional (output) INTEGER. = 0: successful exit < 0: if INFO = —i, the ith argument had an illegal value. > 0: if INFO = i. Di^ = 0. The factorization has been completed, but the block diagonal matrix D is singular, so the solution could not be computed. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20, 21].

Examples The packed storage scheme is illustrated by the following example, where n = 4:

where a,j = a^ for i, j = 1, • • • , 4. Packed storage of the upper triangle of A:

AP

Packed storage of the lower triangle of A: AP

103

LA.SPSV / LAJIPSV Example 2 (from Program LA_SPSV_EXAMPLE) The results below are computed with

Arrays AP and B on entry:

0 2 3 5 4 0

AP 5 6 6 8 0 5 3 9 8

The call: CALL LA_SPSV( AP, B, 'L', IPIV AP, B and IPIV on exit:

B 1.00000 1 1.00000 1.00000 1.00000 1.00000 | The solution of the system Ax — b is:

IPIV I -4 -4 3 4 I 5_

B 14 19 63 69 96

104 5.3.4

Symmetric Indefinite Linear Systems LA_SPSVX / LAJHPSVX

SUBROUTINE LA_SPSVX / LA_HPSVX( AP, B, X, UPLO=uplo, AFP=afp, & IPIV=ipiv, FACT=fact, FERR=ferr, BERR=berr, & RCOND=rcond, INFO=info ) type(wp), INTENT(IN) :: AP(:), rhs type(wp), INTENT(OUT) :: sol CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: UPLO type(wp), INTENT(INOUT), OPTIONAL :: AFP(:) INTEGER, INTENT(INOUT), OPTIONAL :: IPIV(:) CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: FACT REAL(wp), INTENT(OUT), OPTIONAL :: err, RCOND INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(:,:) | B(:) sol:- X(:,:) | X(:) err ::= FERR(:), BERR(:) | FERR, BERR

Purpose LA.SPSVX computes the solution to a linear system of equations AX = B, where A is a real or complex symmetric matrix stored in packed format and X and B are rectangular matrices or vectors. LA_HPSVX computes the solution to a linear system of equations AX = B, where A is a complex Hermitian matrix stored in packed format and X and B are rectangular matrices or vectors. LA_SPSVX and LA_HPSVX can also optionally estimate the condition number of A and compute error bounds.

Description 1. If FACT = 'N', a diagonal pivoting method is used to factor the matrix A as or

where U (or L) is a product of permutation and unit upper (lower) triangular matrices, and D is symmetric (LA_SPSVX) or Hermitian (LA.HPSVX) and block diagonal with 1 x 1 and 2 x 2 diagonal blocks. 2. If some Di^ = 0, so that D is singular, then the routine returns with INFO = i. Otherwise, the factored form of A is used to estimate the condition number of the matrix A. If the reciprocal of the condition number is less than machine precision, INFO = n +1, where n is the order of A, is returned as a warning. However, the routine still goes on to solve for X. Iterative refinement is applied to improve the computed solution. 3. LAJSPSVX and LA_HPSVX also optionally compute, for each solution vector Xj, the estimated forward error bound and the componentwise relative backward error.

Arguments AP

(input) REAL or COMPLEX array, shape (:) with size(AP) = n(n + l)/2, where n is the order of A.

105

LA_SPSVX / LA JfPSVX

On entry, the upper or lower triangle of matrix A in packed storage. The elements are stored columnwise as follows: UPLO

TJ' 'L' B

X

UPLO

AFP

IPIV

FACT

FERR

with with size(B,l) = n or shape (input) REAL or COMPLEX array, shape size(B) = n. The matrix B. with size(K, 1) = n and size(X, 2) = (output) REAL or COMPLEX array, shape i s-ize(B,2), or shape (:) with size(X) = n. The solution matrix X. Optional (input) CHARACTER(LEN=1). = 'U': Upper triangle of A is stored: = 'L': Lower triangle of A is stored. Default value: 'U'. Optional (input or output) REAL or COMPLEX array, shape (:,:) with the same size as AP. If FACT = 'F', then AFP is an input argument that contains the block diagonal matrix D and the multipliers used to obtain the factor L or U from the factorization of A. returned by a previous call to LA_SPSVX or LAJHPSVX and stored as a packed triangular matrix in the same storage format as A. If FACT = 'N', then AFP is an output argument that contains the block diagonal matrix D and the multipliers used to obtain the factor L or U from the factorization of A, stored as a packed triangular matrix in the same storage format as A. Optional (input or output) INTEGER array, shape (:) with size(IPIV) = size(A. 1). If FACT = 'F', then IPIV is an input argument that contains details of the row and column interchanges and the block structure of D. If IPIVjt > 0 . then rows and columns k and IPIVjt were interchanged and Dk,k is a 1 x 1 diagonal block. If IPIVfc < 0 , then there are two cases: 1. If UPLO = 'U' and IPIV* = IPIV^ < 0, then rows and columns (k - I) and —IPIVA; were interchanged and Dk-i-.k,k-i-.k is a 2 x 2 diagonal block. 2. If UPLO = 'L' and IPIV* = IPIVfc+i < 0, then rows and columns (k + 1) and —IPIVfc were interchanged and Dk-.k+i,k-.k+\ is a 2 x 2 diagonal block. If FACT = 'N', then IPIV is an output argument and on exit contains details of the interchanges and the block structure of D (as described above). Optional (input) CHARACTER(LEN=1). Specifies whether the factored form of A has been supplied on entry. = 'N': The matrix A will be copied to AFP and factored. - 'F': AFP and IPIV contain the factored form of A. Default value: 'N'. Optional (output) REAL array of shape (:), with szze(FERR) = size(X,2), or REAL scalar. The estimated forward error bound for each solution vector Xj (the jih column of the solution matrix X). If XT RUE is the true solution corresponding to Xj, FERRj is an estimated upper bound for the magnitude of the largest element in (Xj — XTRUE) divided by the magnitude of the largest element in Xj. The estimate is as reliable as the estimate for RCOND, and is almost always a slight overestimate of the true error.

106 BERR

RCOND

INFO

Symmetric Indefinite Linear Systems Optional (output) REAL array of shape (:), with size(BERR) = szze(X, 2), or REAL scalar. The componentwise relative backward error of each solution vector Xj (i.e., the smallest relative change in any element of A or B that makes Xj an exact solution).

Optional (output) REAL

The estimate of the reciprocal condition number of A. If RCOND is less than the machine precision, the matrix is singular to working precision. This condition is indicated by a return code of INFO > 0.

(output] INTEGER = 0: successful exit. < 0: if INFO = -i, the ith argument had an illegal value. > 0: if INFO = «, and i is < n: Diti = 0. The factorization has been completed, but the block diagonal matrix D is singular, so the solution could not be computed. = n+1: D is nonsingular, but RCOND is less than machine precision, so the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because the computed solution can be more accurate than the value of RCOND would suggest. n is the order of A. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20, 21]. Example (from Program LA_SPSVXJEXAMPLE) The results below are computed with e = 1.19209 x 10~7. Matrices A and B are the same as in Example 2 for LA-SPSV. The call:

CALL LA_SPSVX( AP, B, X, 'L', AFP, IPIV)

AFP and IPIV on exit:

AFP

IPIV -4 -4 3 4 5

The solution vector x is identical to that in Example 2 for LA_SPSV.

Chapter 6

Driver Routines for Least Squares Problems 6.1 6.1.1

Linear Least Squares Problems LA_GELS

SUBROUTINE LA_GELS( A, B, TRANS=trans, INFO=info ) type(wp), INTENT( INOUT ) :: A( :, : ), rhs CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: TRANS INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(:,:) | B(:)

Purpose LA_GELS computes the minimum-norm least squares solution to one or more real or complex linear systems of the form Ax = b, ATx = b or AHx = b using a QR or LQ factorization of A. Matrix A is rectangular and assumed to be of full rank. The vectors b and corresponding solution vectors x are the columns of matrices denoted B and X, respectively.

Arguments A

(input/output) REAL or COMPLEX rectangular array, shape (:,:). On entry, the matrix A. On exit, if s'ize(A, 1) > szze(A,2), A is overwritten by details of its QR factorization. If s-ize(A, 1) < size(A, 2), A is overwritten by details of its LQ factorization.

B

(input/output) REAL or COMPLEX array, shape (:,:) with size(B,l) = max(size(A,l), size(A,2)) or shape (:) with size(B) = max(size(A, l),s2ze(A, 2)). On entry, the matrix B. On exit, the solution matrix X. There are four cases:

107

108

TRANS

INFO

Linear Least Squares Problems

1. If TRANS = 'N' and size(A,l) > size(A,2), then rows 1 to size(A,2) of B contain, columnwise, the least squares solution vector(s); the residual sum of squares for the solution vector in a column of B is given by the sum of squares of elements in rows size(A, 2) + 1 to size(A, 1) of that column. 2. If TRANS = 'N' and size(A, 1) < size(A,2), then rows 1 to size(A,2) of B contain, columnwise, the minimum norm solution vector (s). 3. If TRANS = T' or TRANS = 'C', and size(A, 1) > size(A, 2), then rows 1 to size(A, 1) of B contain, columnwise, the minimum norm solution vector(s). 4. If TRANS = 'T' or TRANS = 'C', and size(A, 1) < size(A, 2), then rows 1 to size(A, 1) of B contain, columnwise, the least squares solution vector(s); the residual sum of squares for the solution vector in a column of B is given by the sum of squares of elements in rows size(A, 1) + 1 to size(A, 2) of that column. Optional (input) CHARACTER(LEN=1). Specifies the form of the system of equations: = 'N': Ax — b (No transpose) = T': ATx = b (Transpose) = 'C': AHx = b (Conjugate transpose) Default value: 'N'. Optional (output) INTEGER = 0: successful exit. < 0: if INFO = —i, the ith argument had an illegal value. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20].

Examples The results below are computed with

Example 1 (from Program LA_GELS_EXAMPLE)

Arrays A and B on entry: A -3 -1 6 5 4 - 6 7 5 0 - 7 4 0 -7 7-8 3 4 2 -

-5 8 4 3 2 4

B -3 -6 1 2 8 - 6 - 2 0 6 -2 -5 10

9 3 2 7 -8 1

109

LA.GELS The call: CALL LA_GELS( A, B ) B on exit:

The solution matrix is:

The residual sums-of-squares are: 55.6579

165.295 23.1260 )

Example 2 (from Program LA_GELS_EXAMPLE) A on entry: As in Example 1. B(:, 1) on entry: B(:,l) _3

1 8 -2 o

Elements marked o need not be set on entry. This extra space is needed for the solution vector x. The call: CALL LA_GELS( A, B(:,l), T, INFO ) B(:, 1) and INFO on exit:

INFO = 0

110

Linear Least Squares Problems

The minimum-norm solution of the system ATx = b is:

6.1.2

LA_GELSY

SUBROUTINE LA_GELSY( A, B, RANK^rank, & JPVT= jpvt, RCOND= rcond, INFO= info ) type(wp), INTENT(INOUT) :: A(:,:), rhs INTEGER, INTENT(OUT), OPTIONAL :: RANK INTEGER, INTENT(INOUT), OPTIONAL :: JPVT(:) REAL(wp), INTENT(IN), OPTIONAL :: RCOND INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(:,:) | B(:)

Purpose LA_GELSY computes the minimum-norm least squares solution to one or more real or complex linear systems Ax = b using a complete orthogonal factorization of A. Matrix A is rectangular and may be rankdeficient. The vectors b and corresponding solution vectors x are the columns of matrices denoted B and X, respectively. The routine computes a QR factorization of A with column pivoting:

where R\\ is the largest leading submatrix whose estimated condition number is less than 1/RCOND. The order of RU , RANK, is the effective rank of A. R-22 is considered to be negligible, and RI% is annihilated by orthogonal (unitary) transformations from the right, yielding the complete orthogonal (unitary) factorization

The minimum-norm least squares solution is then

where Q\ consists of the first RANK columns of Q.

Arguments A

(input/output] REAL or COMPLEX array, shape (:,:). On entry, the matrix A. On exit, A has been overwritten by details of its complete orthogonal factorization.

111

LA.GELSY B

RANK JPVT

RCOND

INFO

(input/output) REAL or COMPLEX array, shape (:,:) with size(B,l) = max(szze(A,l), size(A,2)) or shape (:) with size(B) = max(s'ize(A,l), szze(A,2)). On entry, the matrix B. On exit, rows 1 to size(A, 2) contain the solution matrix X. If size(A,l) > size(A,2) and RANK = size(A,2), the residual sum-of-squares for the solution vector in a column of B is given by the sum of squares of elements in rows size(A, 2) + 1 : size(A, 1) of that column. Optional (output) INTEGER. The effective rank of A. i.e., the order of the submatrix RH. This is the same as the order of the submatrix Tn in the complete orthogonal factorization of A. Optional (input/output) INTEGER array, shape (:) with size(JPVT) = size(A,2). On entry, if JPVT^ ^ 0, the iih column of A is an initial column, otherwise it is a free column. Before the QR factorization of A. all initial columns are permuted to the leading positions; only the remaining free columns are moved as a result of column pivoting during the factorization. On exit, if JPVTj — k, then the ith column of the matrix product AP was the kth column of A. Optional (input) REAL. RCOND is used to determine the effective rank of A. This is defined as the order of the largest leading triangular submatrix RH in the QR factorization of A, with pivoting, whose estimated condition number < 1/RCOND. Default value: 10 x max(s'ize(A, I). size(A, 2)) x EPSILON(l.CLiup), where wp is the working precision. Optional (output) INTEGER. — 0: successful exit < 0: if INFO = —i, the ith argument had an illegal value If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20, 35]. Example (from Program LA.GELSYJEXAMPLE) The results below are computed with

A, B, JPVT and RCOND on entry: A 0 9 - 3 0 1 3 1 3 - 2 0 3 6 -

6 3 1 1 2 1

3 0 1 1 0 2

B -3 - 3 5 0 -2 0 2 -4 1 1 - 2 4

-6 0 -3 2 2 6

JPVT | 0 0 1 (T

112

Linear Least Squares Problems

The call:

CALL LA_GELSY( A, B, RANK, JPVT, 1.0E-5_u>p ) l

B, RANK and JPVT on exit:

RANK

m

JPVT 3 2 1 4

The rank of matrix A is 2. The solution matrix is:

6.1.3

LA_GELSS / LA_GELSD

SUBROUTINE LA_GELSS / LA_GELSD( A, B, RANK=rank, S=s, & RCOND=rcond, INFO=info ) type(wp), INTENT( INOUT ) :: A( :, : ), rhs INTEGER, INTENT(OUT), OPTIONAL :: RANK REAL(wp), INTENT(OUT), OPTIONAL :: S(:) REAL(twp), INTENT(IN), OPTIONAL :: RCOND INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(:,:) | B(:)

Purpose LA_GELSS and LA.GELSD compute the minimum-norm least squares solution to one or more real or complex linear systems Ax = b using the singular value decomposition of A. Matrix A is rectangular and may be rank-deficient. The vectors b and corresponding solution vectors x are the columns of matrices denoted B and X, respectively. The effective rank of A is determined by treating as zero those singular values which are less than RCOND times the largest singular value. In addition to X, the routines also return the right singular vectors and, optionally, the rank and singular values of A. l

wp ::= KIND(l.O) | KIND(l.ODO)

LA.GELSS / LA_GELSD

113

LA_GELSD combines the singular value decomposition with a divide and conquer technique. For large matrices it is often much faster than LA_GELSS but uses more workspace.

Arguments A

(input/output) REAL or COMPLEX array, shape (:.:). On entry, the matrix A. On exit, the first min(szze(A,l), size(A,2)) rows of A are overwritten with its right singular vectors, stored rowwise.

B

(input/output) REAL or COMPLEX array, shape (:.:) with size(B,l) = max(size(A.l), size(A,2)) or shape (:) with size(B) — max(size(A,l), size(A,2)). On entry, the matrix B. On exit, the solution matrix X. If size(A,l) > size(A,2) and RANK = size(A.I), the residual sum-of-squares for the solution in a column of B is given by the sum of squares of elements in rows size(A,2) + l : size(A.l) of that column.

RANK

Optional (output) INTEGER. The effective rank of A. i.e.. the number of singular values of A which are greater than the product RCOND x <TI, where o\ is the greatest singular value. Optional (output) REAL array, shape (:) with s-ize(S) = min(size(A,l), size(A,2)). The singular values of A in decreasing order. The condition number of A in the 2-norm is K%(A) = vi/&m\n(size(A,i),size(A,-2))-

RCOND

Optional (input) REAL. RCOND is used to determine the effective rank of A. Singular values Oi < RCOND x a\ are treated as zero. Default value: 10 x max(size(A, 1), size(A, 2)) x EPSILON(l.O-iyp), where wp is the working precision.

INFO

Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = —i, the ith argument had an illegal value. > 0: the algorithm for computing the SVD failed to converge; if INFO = i, i off-diagonal elements of an intermediate bidiagonal form did not converge to zero. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20].

Example (from Program LA_GELSS_EXAMPLE) The results below are computed with e = 1.19209 x 10~7. Matrices A and B are the same as in the example for LA.GELSY, The call: CALL LA_GELSS( A, B, RANK, S, RCOND=0.00001_w;p, INFO=INFO ) 2 A, B, S, RANK, and INFO on exit: l

wp ::= KIND(l.O) | KIND(l.ODO)

114

Generalized Least Squares Problems

RANK = 2

INFO = 0

The singular values of A are:

The right singular vectors are (columnwise):

The solution matrix is:

6.2

Generalized Linear Least Squares Problems

6.2.1 LA_GGLSE SUBROUTINE LA_GGLSE( A, B, C, D, X, INFO=info ) type(wp), INTENT( INOUT ) :: A( :, : ), B(:,:), C(:), D(:) type(wp), INTENT( OUT ) :: X(:) INTEGER, INTENT(OUT), OPTIONAL :: INFO

where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

115

LA.GGLSE

Purpose LA_GGLSE solves the linear equality-constrained least squares (LSE) problem:

where A and B are real or complex rectangular matrices and c and d are real or complex vectors. Further, A is m x n, B is p x n, c is m x 1 and d is p x 1. and it is assumed that

These conditions ensure that the LSE problem has a unique solution x. This is obtained using the generalized RQ factorization of the matrices B and A.

Arguments A

B

(input/output) REAL or COMPLEX array, shape (:,:) with s-ize(A, 1) = m and size(A, 2) =

n.

On entry, the matrix A. On exit, the contents of A are destroyed. (input/output) REAL or COMPLEX array, shape (:.:) with size(B, 1) = p and size(B,2) —

n.

C

D X INFO

On entry, the matrix B. On exit, the contents of B are destroyed. (input/output) REAL or COMPLEX array, shape (:) with size(C} = m. On entry, the vector c. On exit, the residual sum of squares for the solution is given by the sum of squares of elements n — p + 1 to m. (input/output) REAL or COMPLEX array, shape (:) with size(D) = p. On entry, The vectors d. On exit, the contents of D are destroyed. (output) REAL or COMPLEX array, shape (:) with size(X) = n. The solution vector x. Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = -i, the ith argument had an illegal value. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20]. Example (from Program LA_GGLSEJEXAMPLE) The results below are computed with e = 1.19209 x 10~7.

116

Generalized Least Squares Problems

Arrays A,B, C, and D on entry: - 6 7 4 4

7

^

9 - 7 4 •* *} 7 5 - 1 4

B 3 0 - 3 -2 0 1

2

q o

0 o

D 2 -1

1

The call: CALL LA_GGLSE( A, B, C, D, X, INFO ) C, X, and INFO on exit:

INFO = 0

The solution vector x and the residual sum-of-squares are:

6.2.2 LA_GGGLM SUBROUTINE LA_GGGLM( A, B, D, X, Y, INFO=info ) type(wp), INTENT( INOUT ) :: A( :, : ), B(:,:), D(:) type(wp), INTENT( OUT ) :: X(:), Y(:) INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

Purpose LA_GGGLM solves the general (Gauss-Markov) linear model (GLM) problem: where A and B are real or complex rectangular matrices and d is a real or complex vector. Further, A is n x m, B is n x p, and d is n x 1, and it is assumed that These conditions ensure that the GLM problem has unique solution vectors x and y. The problem is solved using the generalized QR factorization of A and B. If matrix B is square and nonsingular, then the GLM problem is equivalent to the weighted linear least squares problem

LA_GGGLM

117

Arguments A

(input/output) REAL or COMPLEX array, shape (:,:) with size(A, 1) — n and size(A, 2) — m. On entry, the matrix A. On exit, the contents of A are destroyed.

B

(input/output) REAL or COMPLEX array, shape (:.:) with size(B, 1) = n and size(B. 2) — POn entry, the matrix B. On exit, the contents of B are destroyed.

D

(input/output) REAL or COMPLEX array, shape (:) with size(D) = n. On entry, the vector d. On exit, the contents of D are destroyed.

X

(output] REAL or COMPLEX array, shape (:) with size(X) - m. The solution vector x.

Y

(output] REAL or COMPLEX array, shape (:) with size(Y) = p. The solution vector y.

INFO

Optional (output] INTEGER. = 0: successful exit < 0: if INFO = — i, the Ith argument had an illegal value. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20]. Example (from Program LA_GGGLM_EXAMPLE) The results below are computed with e = 1.19209 x 10~7.

Arrays A,B, and D on entry:

The call: CALL LA_GGGLM( A, B, D, X, Y, INFO )

118

Generalized Least Squares Problems

X, Y, and INFO on exit:

INFO = 0

The solution vectors x and y are:

Chapter 7

Driver Routines for Standard Eigenvalue Problems 7.1

Standard Symmetric Eigenvalue Problems

7.1.1

LA_SYEV / LA_HEEV / LA_SYEVD / LA_HEEVD

SUBROUTINE LA_SYEV / LA-HEEV / LA_SYEVD / LA_HEEVD( A, W, & JOBZ=jobz, UPLO=uplo, INFO^info ) type(wp), INTENT(INOUT) :: A(:,:) HEAL(wp), INTENT(OUT) :: W(:) CHARACTER(LEN=1), INTENT (IN), OPTIONAL :: JOBZ, UPLO INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

Purpose LA_SYEV and LA-SYEVD compute all eigenvalues and, optionally, all eigenvectors of a real symmetric matrix A. LA-HEEV and LA_HEEVD compute all eigenvalues and, optionally, all eigenvectors of a complex Hermitian matrix A. LA_SYEVD and LAJ3EEVD use a divide and conquer algorithm. If eigenvectors are desired, they can be much faster than LA_SYEV and LA-HEEV for large matrices but use more workspace.

Arguments A

(input/output) REAL or COMPLEX square array, shape (:,:). On entry, the matrix A. If UPLO = 'U', the upper triangular part of A contains the upper triangular part of the matrix A. If UPLO = 'L', the lower triangular part of A contains the lower triangular part of the matrix A. On exit: 119

120

Standard Symmetric Eigenvalue Problems If JOBZ = 'V, then the columns of A contain the orthonormal eigenvectors of the matrix A in the order of the eigenvalues. If JOBZ = 'N', then the upper triangle (if UPLO = 'U') or the lower triangle (if UPLO = 'L') of A, including the diagonal, is destroyed.

W

(output) REAL array, shape (:) with size(W) = size(A,l). The eigenvalues in ascending order.

JOBZ

Optional (input) CHARACTER(LEN=1). = 'N': Computes eigenvalues only; = 'V: Computes eigenvalues and eigenvectors. Default value: 'N'.

UPLO

Optional (input) CHARACTER(LEN=1). = 'U': Upper triangle of A is stored; = 'L': Lower triangle of A is stored. Default value: 'U'.

INFO

Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = —i, the ith argument had an illegal value > 0: if INFO = ?', then i off-diagonal elements of an intermediate tridiagonal form did not converge to zero. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20]. Examples The results below are computed with e = 1.19209 x 10~7.

Example 1 (from Program LA_SYEV_EXAMPLE) Array A on entry -5-3 1 5 3 * 2 - 1 4 - 1 * * 6 3 - 1 * * * 1 -1 *

Elements marked * are not used by the routine. The call: CALL LA_SYEV( A, W ) W on exit: -11.2462 -6.24975 1.18524 5.00130 8.30939

*

*

* —7

LA_SYEV / LAJIEEV / LA-SYEVD / LAJtEEVD Example 2 (from Program LA_SYEVD-EXAMPLE) Matrix A as in Example 1. Array A on entry:

* * * * -5 * * * 2 -3 * * 1 -1 6 4 1 * 5 3 3 -1 -1 -1 _7

Elements marked * are not used by the routine. The call: CALL LA_SYEVD( A, W, 'V, 'L', INFO ) A and INFO on exit:

INFO = 0

The eigenvectors of A are:

121

122

7.1.2

Standard Symmetric Eigenvalue Problems

LA_SYEVX / LA_HEEVX

SUBROUTINE LA.SYEVX / LAJHEEVX ( A, W, JOBZ=jobz, UPLO=uplo, & VL=vl, VU=vu, IL=il, IU=iu, M=m, IFAIL=ifail, &. ABSTOL=abstol, INFO=info ) type(wp), INTENT(INOUT) :: A(:,:) KEAL(wp), INTENT(OUT) :: W(:) CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: JOBZ, UPLO REAL(iyp), INTENT(IN), OPTIONAL :: VL, VU INTEGER, INTENT(IN), OPTIONAL :: IL, IU INTEGER, INTENT(OUT), OPTIONAL :: M INTEGER, INTENT(OUT), OPTIONAL :: IFAIL(:) REAL(iup), INTENT(IN), OPTIONAL :: ABSTOL INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

Purpose LA_SYEVX / LA_HEEVX compute selected eigenvalues and, optionally, the corresponding eigenvectors of a real symmetric/complex Hermitian matrix A. Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

Arguments A

(input/output) REAL or COMPLEX square array, shape (:,:). On entry, the matrix A. If UPLO = 'U', the upper triangular part of A contains the upper triangular part of the matrix A. If UPLO = 'L', the lower triangular part of A contains the lower triangular part of the matrix A. On exit: If JOBZ = 'V, then the first M columns of A contain the orthonormal eigenvectors of the matrix A corresponding to the selected eigenvalues, with the ith column of A containing the eigenvector associated with the eigenvalue in Wj. If an eigenvector fails to converge, then that column of A contains the latest approximation to the eigenvector and the index of the eigenvector is returned in IFAIL. If JOBZ = 'N', then the upper triangle (if UPLO = 'U') or the lower triangle (if UPLO = 'L') of A, including the diagonal, is destroyed.

W

(output) REAL array, shape (:) with size(W) = size(A,l). The first M elements contain the selected eigenvalues in ascending order.

JOBZ

Optional (input) CHARACTER(LEN=1). = 'N': Computes eigenvalues only; = 'V: Computes eigenvalues and eigenvectors. Default value: 'N'.

UPLO

Optional (input) CHARACTER(LEN=1). = 'U': Upper triangle of A is stored; = 'L': Lower triangle of A is stored. Default value: 'U'.

LA_SYEVX / LAJfEEVX

123

VL,VU

Optional (input) REAL. The lower and upper bounds of the interval to be searched for eigenvalues. VL < VU. Default values: VL = -HUGE(wp) and VU = HUGE(wp), where wp ::= KIND(l.O) | KIND(l.ODO). Note: Neither VL nor VU may be present if IL and/or IU is present. IL,IU Optional (input) INTEGER. The indices of the smallest and largest eigenvalues to be returned. The IL* through IU* eigenvalues will be found. 1 < IL < IU < size(A, 1). Default values: IL = 1 and IU = size(A,l). Note: Neither IL nor IU may be present if VL and/or VU is present. Note: All eigenvalues are calculated if none of the arguments VL. VU, IL and IU are present. M Optional (output) INTEGER. The total number of eigenvalues found. 0 < M < size(A. I). Note: If IL and IU are present then M = IU - IL + 1. IFAIL Optional (output) INTEGER array, shape (:) with size(lFAlL) = size(A,l). If INFO = 0, the first M elements of IFAIL are zero. If INFO > 0, then IFAIL contains the indices of the eigenvectors that failed to converge. Note: IFAIL must be absent if JOBZ = 'N'. ABSTOL Optional (input) REAL. The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval [a, b] of width less than or equal to

INFO

where wp is the working precision. If ABSTOL < 0, then EPSILON(1.0_u;p) x ||T||i will be used in its place, where ||T||i is the l\ norm of the tridiagonal matrix obtained by reducing A to tridiagonal form. Eigenvalues will be computed most accurately when ABSTOL is set to twice the underflow threshold 2 x LAJLAMCH(1.0_iup. 'Safe minimum'), not zero. Default value: 0.0_u>p. Note: If this routine returns with INFO > 0, then some eigenvectors did not converge. Try setting ABSTOL to 2 x LA_LAMCH(1.0_u/p,'Safe minimum'). Optional (output) INTEGER. — 0: successful exit. < 0: if INFO = —-i, the ith argument had an illegal value. > 0: if INFO = z, then i eigenvectors failed to converge. Their indices are stored in array IFAIL. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20, 21, 8]. Example (from Program LA_SYEVX_EXAMPLE) The results below are computed with e — 1.19209 x 10~7. Matrix A is the same as in Example 1 for LA_SYEV. The call: CALL LA_SYEVX( A, W, VL=-7.0-iyp, VU=7.0_u;p, M=M, ABSTOL=1.0E-4_u;p ) J l

wp is a work precision; wp ::= KIND(l.O) | KIND(l.ODO)

124

Standard Symmetric Eigenvalue Problems

W and M on exit:

W -6.2497292 1.1852608 5.0013161 0.0000000 0.0000000

M =3

There are three eigenvalues of matrix A in the interval [—7, 7]:

7.1.3 LA_SYEVR / LA.HEEVR SUBROUTINE LA_SYEVR / LA_HEEVR( A, W, JOBZ-jobz, & UPLO=uplo, VL=vl, VU=vu, IL=il, IU=iu, M=m, & ISUPPZ= isuppz, ABSTOL=abstol, INFO=info ) type(wp), INTENT(INOUT) :: A(:,:) REAL(wp), INTENT(OUT) :: W(:) CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: JOBZ, UPLO REAL(wp), INTENT(IN), OPTIONAL :: VL, VU INTEGER, INTENT(IN), OPTIONAL :: IL, IU INTEGER, INTENT(OUT), OPTIONAL :: M INTEGER, INTENT(OUT), OPTIONAL :: ISUPPZ(:) REAL(wp), INTENT (IN), OPTIONAL :: ABSTOL INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

Purpose LA_SYEVR / LAJHEEVR compute selected eigenvalues and, optionally, the corresponding eigenvectors of a real symmetric/complex Hermitian matrix A. Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues. LAJ3YEVR and LA_HEEVR use a relatively robust representation (RRR) algorithm. It is usually the fastest algorithm of all and uses the least workspace.

Arguments A

(input/output) REAL or COMPLEX square array, shape (:,:). On entry, the matrix A. If UPLO = 'U', the upper triangular part of A contains the upper triangular part of the matrix A. If UPLO = 'L', the lower triangular part of A contains the lower triangular part of the matrix A.

LA-SYEVR / LAJiEEVR

125

On exit: If JOBZ = 'V, then the first M columns of A contain the orthonormal eigenvectors of the matrix A corresponding to the selected eigenvalues, with the ith column of A containing the eigenvector associated with the eigenvalue in Wj. If JOBZ = 'N', the upper triangle (if UPLO = 'U') or the lower triangle (if UPLO = 'L') of A, including the diagonal, is destroyed. W (output) REAL array, shape (:) with size(W) — size(A.l). The first M elements contain the selected eigenvalues in ascending order. JOBZ Optional (input) CHARACTER(LEN=1). = 'N!: Computes eigenvalues only; = 'V: Computes eigenvalues and eigenvectors. Default value: 'N'. UPLO Optional (input) CHARACTER(LEN=1). = 'U': Upper triangle of A is stored; = 'L': Lower triangle of A is stored. Default value: 'U'. VL,VU Optional (input) REAL. The lower and upper bounds of the interval to be searched for eigenvalues. VL < VU. Default values: VL = -HUGE(wp) and VU = HUGE(™p) : where wp ::= KIND(l.O) | KIND(l.ODO). Note: Neither VL nor VU may be present if IL and/or IU is present. IL,IU Optional (input) INTEGER. The indices of the smallest and largest eigenvalues to be returned. The TLth through IU* eigenvalues will be found. 1 < IL < IU < size(A, 1). Default values: IL = 1 and IU = s'ize(A,l). Note: Neither IL nor IU may be present if VL and/or VU is present. Note: All eigenvalues are calculated if none of the arguments VL, VU, IL and IU are present. M Optional (output) INTEGER. The total number of eigenvalues found. 0 < M < size(A, I). Note: If IL and IU are present then M = IU - IL + 1. ISUPPZ Optional (output) INTEGER array, shape (:) with size(ISUPPZ) = 2 x max(l,M). The support of the eigenvectors in A, i.e., the indices indicating the nonzero elements. The ith eigenvector is nonzero only in elements ISUPPZ-2i-i through ISUPPZo;. Note: ISUPPZ must be absent if JOBZ = 'N'. ABSTOL Optional (input) REAL. The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval [a, b] of width less than or equal to ABSTOL + EPSILON(1.0_«;p) x max(| a \, \ b |),

INFO

where wp is the working precision. If ABSTOL < 0, then EPSILON(l.CLwp) x ||T||i will be used in its place, where ||T|ji is the l\ norm of the tridiagonal matrix obtained by reducing A to tridiagonal form. Default value: O.O.wp. Note: Eigenvalues are computed most accurately if ABSTOL is set to LA_LAMCH( 1.0_u;p. 'Safe minimum'), not zero. Optional (output) INTEGER = 0: successful exit. < 0: if INFO = —z, the ith argument had an illegal value.

126

Standard Symmetric Eigenvalue Problems If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20].

Example (from Program LAJSYEVRJEXAMPLE) The results below are computed with Matrix A is the same as in Example 1 for LAJSYEV. The call:

CALL LA_SYEVR( A, W, IL=1, IU=2, M=M )

W and M on exit: W

The first two eigenvalues of matrix A are:

7.1.4

LA_SPEV / LAJHPEV / LA_SPEVD / LA_HPEVD

SUBROUTINE LAJSPEV / LA_HPEV / LA_SPEVD / LA_HPEVD( AP, W, & UPLO=uplo, Z=z, INFO=info ) type(wp), INTENT(INOUT) :: AP(:) REAL(wp), INTENT(OUT) :: W(:) CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: UPLO type(wp), INTENT(OUT), OPTIONAL :: Z(:,:) INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

Purpose LA_SPEV and LA_SPEVD compute all eigenvalues and, optionally, all eigenvectors of a real symmetric matrix A in packed storage. LAJHPEV and LAJHPEVD compute all eigenvalues and, optionally, all eigenvectors of a complex Hermitian matrix A in packed storage. LAJ3PEVD and LAJHPEVD use a divide and conquer algorithm. If eigenvectors are desired, they can be much faster than LA_SPEV and LA_HPEV for large matrices but use more workspace.

Arguments AP

(input/output) REAL or COMPLEX array, shape (:) with size(AP) = n(n + l)/2, where n is the order of A.

127

LA_SPEV / LAJIPEV / LA.SPEVD / LAJ1PEVD

On entry, the upper or lower triangle of matrix A in packed storage. The elements are stored columnwise as follows: UPLO 'U' 'L'

W UPLO

Z INFO

On exit, AP is overwritten by values generated during the reduction of A to a tridiagonal matrix T. If UPLO = 'U', the diagonal and first superdiagonal of T overwrite the corresponding diagonals of A. If UPLO = 'L', the diagonal and first subdiagonal of T overwrite the corresponding diagonals of A. (output) REAL array, shape (:) with size(W) ~ n. The eigenvalues in ascending order. Optional (input) CHARACTER(LEN=1). = 'U': Upper triangle of A is stored: = 'L': Lower triangle of A is stored. Default value: 'U'. Optional (output) REAL or COMPLEX square array, shape (:,:) with size(7,, 1) = n. The columns of Z contain the orthonormal eigenvectors of A in the order of the eigenvalues. Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = —i. the it/l argument had an illegal value > 0: if INFO = i, then i off-diagonal elements of an intermediate tridiagonal form did not converge to zero. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20].

Examples Example 1 The packed storage scheme is illustrated below for the matrix

where If UPLO = 'U' then: AP on entry If UPLO = 'L' then:

Standard Symmetric Eigenvalue Problems

128 AP on entry

Example 2 (from Program LA_HPEV_EXAMPLE) The results below are computed with

Array AP on entry (UPLO = TJ' by default): AP

AP (continued)

The call:

CALL LA_HPEV( AP, W ) Array W on exit:

Example 3 (from Program LA_HPEVD..EXAMPLE) Matrix A as in Example 2. Array AP on entry:

AP AP continued

The call: CALL LA_HPEVD( A, W, 'L', Z, INFO )

LA_SPE V / LA JfPEV / LA.SPEVD / LAJ1PEVD

129

Z and INFO on exit:

Z

Z continued

Z continued INFO = 0

The eigenvectors of A are:

130

Standard Symmetric Eigenvalue Problems

7.1.5 LA_SPEVX / LA.HPEVX SUBROUTINE LA_SPEVX / LA_HPEVX( AP, W, UPLO=uplo, Z=z, & VL=vl, VU=vu, EL=il, IU=iu, M=m, IFAIL=ifail, & ABSTOL=abstol, INFO=info ) type(wp), INTENT(INOUT) :: AP(:) REAL(wp), INTENT(OUT) :: W(:) CHARACTER(LEN-l), INTENT(IN), OPTIONAL :: UPLO type(wp), INTENT(OUT), OPTIONAL :: Z(:,:) REAL(wp), INTENT(IN), OPTIONAL :: VL, VU INTEGER, INTENT (IN), OPTIONAL :: IL, IU INTEGER, INTENT(OUT), OPTIONAL :: M INTEGER, INTENT(OUT), OPTIONAL :: IFAIL(:) REAL(wp), INTENT(IN), OPTIONAL :: ABSTOL INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

Purpose LAJSPEVX / LAJHPEVX compute selected eigenvalues and, optionally, the corresponding eigenvectors of a real symmetric/complex hermitian matrix A in packed storage. Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

Arguments AP

(input/output) REAL or COMPLEX array, shape (:) with size(AP) = n(n + l)/2, where n is the order of A. On entry, the upper or lower triangle of matrix A in packed storage. The elements are stored columnwise as follows: UPLO

'IT 'L'

W UPLO

Z

On exit, AP is overwritten by values generated during the reduction of A to a tridiagonal matrix T. If UPLO = 'U', the diagonal and first superdiagonal of T overwrite the corresponding diagonals of A. If UPLO = 'L', the diagonal and first subdiagonal of T overwrite the corresponding diagonals of A. (output) REAL array, shape (:) with size(W) = n. The eigenvalues in ascending order. Optional (input) CHARACTER(LEN=1). ~ 'U': Upper triangle of A is stored. = 'L': Lower triangle of A is stored. Default value: 'U'. Optional (output) REAL or COMPLEX array, shape (:,:) with size(Z,l) = n and size(Z,2) = M. The first M columns of Z contain the orthonormal eigenvectors of the matrix A corresponding

LA_SPEVX / LAMPEVX

131

to the selected eigenvalues, with the iih column of Z containing the eigenvector associated with the eigenvalue in W 4 . If an eigenvector fails to converge, then that column of Z contains the latest approximation to the eigenvector, and the index of the eigenvector is returned in IFAIL. Note: The user must ensure that at least M columns are supplied in the array Z. When the exact value of M is not known in advance, an upper bound must be used. In all cases M < n. VL,VU Optional (input) REAL. The lower and upper bounds of the interval to be searched for eigenvalues. VL < VU. Default values: VL = -HUGE(wp) and VU = HUGE(wp), where wp ::= KIND(l.O) | KIND(l.ODO). Note: Neither VL nor VU may be present if IL and/or IU is present. IL,IU Optional (input) INTEGER. The indices of the smallest and largest eigenvalues to be returned. The ILth through IUt/l eigenvalues will be found. 1 < IL < IU < size(A, I). Default values: IL — 1 and IU = size(A,l). Note: Neither IL nor IU may be present if VL and/or VU is present. Note: All eigenvalues are calculated if none of the arguments VL, VU, IL and IU are present. M Optional (output) INTEGER. The total number of eigenvalues found. 0 < M < size(A. 1). Note: If IL and IU are present then M = IU - IL + 1. IFAIL Optional (output) INTEGER array, shape (:) with size(IFAIL) = n. If INFO = 0. the first M elements of IFAIL are zero. If INFO > 0, then IFAIL contains the indices of the eigenvectors that failed to converge. Note: If Z is present then IFAIL should also be present. ABSTOL Optional (input) REAL. The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval [a, b] of width less than or equal to

INFO

where wp is the working precision. If ABSTOL < 0, then EPSILON(1.0_w/p) x ||T||i will be used in its place, where ||T||i is the /i norm of the tridiagonal matrix obtained by reducing A to tridiagonal form. Eigenvalues will be computed most accurately when ABSTOL is set to twice the underflow threshold 2 x LA_LAMCH(1.0_wp, 'Safe minimum'), not zero. Default value: O.CLiyp. Note: If this routine returns with INFO > 0, then some eigenvectors did not converge. Try setting ABSTOL to 2 x LA_LAMCH(1.0_u;p, 'Safe minimum'). Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = —i. the ith argument had an illegal value. > 0: if INFO — i, then i eigenvectors failed to converge. Their indices are stored in array IFAIL. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20, 21].

Example (from Program LA_HPEVX_EXAMPLE) The results below are computed with e — 1.19209 x 10~7. Matrix A is the same as for LA_HPEV.

132

Standard Symmetric Eigenvalue Problems

The call: CALL LA_HPEVX( A, W, IL=2, IU=5, ABSTOL=1.0E-5_WP ) 2

Array W on exit: -5.54001 0.34077 4.40090 10.35344 0.00000

7.1.6

Eigenvalues A 2 , . . . , AS of matrix A:

LA.SBEV / LA_HBEV / LAJSBEVD / LA_HBEVD

SUBROUTINE LA.SBEV / LA_HBEV / LA_SBEVD / LA_HBEVD( AB, W, UPLO=uplo, Z=z, INFO=info ) type(wp), INTENT(INOUT) :: AB(:,:) REAL(wp), INTENT(OUT) :: W(:) CHARACTER(LEN=l), INTENT(IN), OPTIONAL :: UPLO type(wp), INTENT(OUT), OPTIONAL :: Z(:,:) INTEGER, INTENT (OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

Purpose LA-SBEV and LA_SBEVD compute all eigenvalues and, optionally, all eigenvectors of a real symmetric matrix A in band form. LAJHBEV and LAJHBEVD compute all eigenvalues and, optionally, all eigenvectors of a complex Hermitian matrix A in band form. LA.SBEVD and LAJHBEVD use a divide and conquer algorithm. They are much faster than LA.SBEV and LAJHBEV for large matrices but use more workspace.

Arguments AB

(input/output) REAL or COMPLEX array, shape (:,:) with size(AB,l) = kd + 1 and szze(AB,2) = n, where kd is the number of subdiagonals or superdiagonals in the band and n is the order of A. On entry, the upper (if UPLO = 'U') or lower (if UPLO = 'L') triangle of matrix A in band storage. The kd + 1 diagonals of A are stored in the rows of AB so that the jth column of A

'wp ::= KIND(l.O) | KIND(l.ODO)

133

LA.SBEV / LA_HBEV / LA_SBEVD / LAJJBEVD is stored in the jth column of AB as follows:

UPLO 'U' 'L'

On exit, AB is overwritten by values generated during the reduction of A to a tridiagonal matrix T. If UPLO = 'U', the first superdiagonal and the diagonal of T are returned in rows kd and kd + 1 of AB. If UPLO = 'L'. the diagonal and first subdiagonal of T are returned in the first two rows of AB. W

(output) REAL array, shape (:) with size(W) = n. The eigenvalues in ascending order.

UPLO

Optional (input) CHARACTER(LEN=1). = 'U': Upper triangle of A is stored: = 'L': Lower triangle of A is stored. Default value: 'U'.

Z

Optional (output) REAL or COMPLEX square array, shape (:.:) with size(Z,l) = n. The columns of Z contain the orthonormal eigenvectors of A in the order of the eigenvalues. Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = —i, the ith argument had an illegal value. > 0: if INFO = i, then i off-diagonal elements of an intermediate tridiagonal form did not converge to zero. If INFO is not present and an error occurs, then the program is terminated with an error message.

INFO

References: [1] and [17, 9, 20]. Examples Example 1 The band storage scheme is illustrated by the following example, where n = 9 and kd = 2, making s«ze(AB, 1) = 3 and size(AB,2) = 9:

where a^ = conjg(aji) for i, j = 1, • • • , 9.

134

Standard Symmetric Eigenvalue Problems

Banded storage of A when UPLO = 'U': AB on entry

Banded storage of A when UPLO = 'L': AB on entry

Array elements marked * are not used by the routine. Example 2 (from Program LA_SBEV_EXAMPLE) The results below are computed with

Array AB on entry (UPLO = 'U' by default): AB

The call: CALL LA_SBEV( AB, W ) Array W on exit and the eigenvalues of A:

W -13.6526 -6.98025 -3.71265 1.20058 16.1449 Example 3 (from Program LA_SBEVD_EXAMPLE) Matrix A as in Example 2.

135

LA_SBEVX / LAJIBEVX Array AB on entry:

AB - 6 2 - 1 3 -5 -2 6 10 6 0 - 5 4 - 1 0 0

The call: CALL LA_SBEVD( AB, W, 'L', Z, INFO ) Z and INFO on exit:

Z

INFO = 0 The eigenvectors of A are:

7.1.7

LA_SBEVX / LAJHBEVX

SUBROUTINE LA_SBEVX / LA_HBEVX( AB, W, UPLO=uplo, Z=z, & VL=vl, VU=vu, IL=il, IU=iu, M=m, IFAIL=ifail, & Q=q, ABSTOL=abstol, INFO=info ) type(wp), INTENT(INOUT) :: AB(:,:) REAL(iyp), INTENT (OUT) :: W(:) CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: UPLO type(wp), INTENT(OUT), OPTIONAL :: Z(:,:) HEAL(wp), INTENT (IN), OPTIONAL :: VL, VU INTEGER, INTENT(IN), OPTIONAL :: IL, IU INTEGER, INTENT(OUT), OPTIONAL :: M INTEGER, INTENT(OUT), OPTIONAL :: IFAIL(:) type(wp), INTENT(OUT), OPTIONAL :: Q(:,:) REAL(wp), INTENT (IN), OPTIONAL :: ABSTOL INTEGER, INTENT(OUT), OPTIONAL :: INFO where

type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

Purpose LA.SBEVX / LAJ3BEVX compute selected eigenvalues and, optionally, the corresponding eigenvectors

136

Standard Symmetric Eigenvalue Problems

of a real symmetric/complex Hermitian band matrix A. Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

Arguments AB

(input/output) REAL or COMPLEX array, shape (:,:) with size(AB,l) = kd + I and s'*2e(AB,2) = n, where kd is the number of subdiagonals or superdiagonals in the band and n is the order of A. On entry, the upper (if UPLO = 'U') or lower (if UPLO = 'L') triangle of matrix A in band storage. The kd + 1 diagonals of A are stored in the rows of AB so that the jth column of A is stored in the jth column of AB as follows: UPLO 'U' 'L'

W UPLO

Z

VL,VU

IL,IU

M

On exit, AB is overwritten by values generated during the reduction of A to a tridiagonal matrix T. If UPLO = 'U' the first superdiagonal and the diagonal of T are returned in rows kd and kd -f 1 of AB. If UPLO = 'L', the diagonal and first subdiagonal of T are returned in the first two rows of AB. (output) REAL array, shape (:) with size(W) = n. The first M elements contain the selected eigenvalues in ascending order. Optional (input) CHARACTER(LEN=1). = 'U' : Upper triangle of A is stored; = 'L' : Lower triangle of A is stored. Default value: 'U'. Optional (output) REAL or COMPLEX array, shape (:,:) with size(Z,l) — n and size(Z,2) = M. The first M columns of Z contain the orthonormal eigenvectors of the matrix A corresponding to the selected eigenvalues, with the ith column of Z containing the eigenvector associated with the eigenvalue in Wj. If an eigenvector fails to converge, then that column of Z contains the latest approximation to the eigenvector, and the index of the eigenvector is returned in IFAIL. Note: The user must ensure that at least M columns are supplied in the array Z. When the exact value of M is not known in advance, an upper bound must be used. In all cases M < n. Optional (input) REAL. The lower and upper bounds of the interval to be searched for eigenvalues. VL < VU. Default values: VL = -HUGE(wp) and VU = HUGE(wp), where wp ::= KIND(l.O) | KIND(l.ODO). Note: Neither VL nor VU may be present if IL and/or IU is present. Optional (input) INTEGER. The indices of the smallest and largest eigenvalues to be returned. The ILth through IUth eigenvalues will be found. 1 < IL < IU < size(A, I). Default values: IL = 1 and IU = size(A,I). Note: Neither IL nor IU may be present if VL and/or VU is present. Note: All eigenvalues are calculated if none of the arguments VL, VU, IL and IU are present. Optional (output) INTEGER. The total number of eigenvalues found. 0 < M < size(A, 1). Note: If IL and IU are present then M = IU - IL + 1.

137

LA_SBEVX / LAJ1BEVX IFAIL

Optional (output) INTEGER array, shape (:) with size(IFAIL) = n. If INFO = 0, the first M elements of IFAIL are zero. If INFO > 0, then IFAIL contains the indices of the eigenvectors that failed to converge. Note: If Z is present then IFAIL should also be present.

Q

Optional (output) REAL or COMPLEX square array. shape(:,:) with size(Q, 1) = n. The n x n unitary matrix used in the reduction to tridiagonal form. This is computed only if Z is present.

ABSTOL

Optional (input) REAL. The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval [a, b] of width less than or equal to

where wp is the working precision. If ABSTOL < 0, then EPSILON(1.0_wp) x ||T||i will be used in its place, where ||T||i is the l\ norm of the tridiagonal matrix obtained by reducing A to tridiagonal form. Eigenvalues will be computed most accurately when ABSTOL is set to twice the underflow threshold 2 x LA_LAMCH(1.0_t/;p. 'Safe minimum'), not zero. Default value: O.CLwp. Note: If this routine returns with INFO > 0. then some eigenvectors did not converge. Try setting ABSTOL to 2 x LAJLAMCH(1.0_u;p, 'Safe minimum'). INFO

Optional (output) INTEGER = 0: successful exit. < 0: if INFO = — i, the Ith argument had an illegal value. > 0: if INFO = i, then i eigenvectors failed to converge. Their indices are stored in array IFAIL. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20, 21]. Example 1 (from Program LAJ3BEVXJEXAMPLE) The results below are computed with The matrix A is the same as in Example 2 for LA_SBEV. The call: CALL LA_SBEVX( AB, W, Z=Z, VL=-4.0_wp, VU=100.0_iup, M=M, Q=Q )3 W, M and Q on exit:

W -3.71265 1.20058 1.61449 x 101 0.00000 0.00000 3

wp ::= KIND(l.O) I KIND(l.ODO)

M =3

138

Standard Symmetric Eigenvalue Problems

Q

The eigenvalues of A in the range [—4,100] are: -3.71265 1.20058 1.61449 x 101 The unitary matrix Q used in the reduction of A to tridiagonal form is:

7.1.8

LA_STEV / LA_STEVD

SUBROUTINE LA_STEV / LA_STEVD( D, E, Z=z, INFO=info ) REAL(wp), INTENT(INOUT) :: D(:), E(:) REAL(«;p), INTENT(OUT), OPTIONAL :: Z(:,:) INTEGER, INTENT(OUT), OPTIONAL :: INFO where wp ::= KIND(l.O) | KIND(l.ODO)

Purpose LA_STEV and LA_STEVD compute all eigenvalues and, optionally, all eigenvectors of a real symmetric tridiagonal matrix A. LA_STEVD uses a divide and conquer algorithm. If eigenvectors are desired, it can be much faster than LA.STEV for large matrices but uses more workspace.

Arguments D (input/output) E

Z

REAL array shape (:) with size(D) = n, where n is the order of A. On entry, the diagonal elements of the matrix A. On exit, the eigenvalues in ascending order. (input/output] REAL array, shape (::) with size(E) = n. On entry, the n — 1 subdiagonal elements of A in EI to E n _i. En need not be set but is used by the routine. On exit, the contents of E are destroyed. Optional (output) REAL square array, shape(:,:) with size(Z,l) = n. The columns of Z contain the orthonormal eigenvectors of A in the order of the eigenvalues.

139

LA.STEV / LA_STEVD INFO

Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = -i, the iih argument had an illegal value. > 0: if INFO = i. then i elements of E did not converge to zero. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20]. Examples The results below are computed with

Example 1 (from Program LA_STEV_EXAMPLE)

Arrays D and E on entry: D 0 5 4 7 9

E 9 2 3 -11

o

Element marked o need not be set on entry. The call: CALL LA_STEV( D, E )

D on exit:

The eigenvalues of matrix A are:

-6.99558 -3.67499 4.20213 12.1448 19.3236

Example 2 (from Program LA_STEVD.EXAMPLE) Matrix A as in Example 1. The call: CALL LA_STEVD( D, E, Z, INFO )

140

Standard Symmetric Eigenvalue Problems

Z, and INFO on exit (D as in Example 1): Z

INFO = 0 The eigenvectors of A are:

7.1.9 LA_STEVX SUBROUTINE LA_STEVX( D, E, W, Z=z, VL=vl, VU=vu, & IL=il, IU=iu, M=m, IFAIL=ifail, & ABSTOL=abstol, INFO=info ) REAL(wp), INTENT(INOUT) :: D(:), E(:) REAL (tip). INTENT(OUT) :: W(:) REAL(wp), INTENT(OUT), OPTIONAL :: Z(:,:) REAL(iup), INTENT(IN), OPTIONAL :: VL, VU INTEGER, INTENT(IN), OPTIONAL :: IL, IU INTEGER, INTENT(OUT), OPTIONAL :: M INTEGER, INTENT(OUT), OPTIONAL :: IFAIL(:) REAL(wp), INTENT(IN), OPTIONAL :: ABSTOL INTEGER, INTENT(OUT), OPTIONAL :: INFO where wp ::- KIND(l.O) | KIND(l.ODO)

Purpose LA_STEVX computes selected eigenvalues and, optionally, the corresponding eigenvectors of a real symmetric tridiagonal matrix A. Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

Arguments D (input/output]

REAL array, shape (:) with size(D) = n, where n is the order of A. On entry, the diagonal elements of the matrix A. On exit, the original contents of D possibly multiplied by a constant factor to avoid over/underflow in computing the eigenvalues.

LA_STEVX

141

(input/output) REAL array, shape (:) with size(E) = n. On entry, the n — 1 subdiagonal elements of A in EI to E n _i . En need not be set. On exit, the original contents of E possibly multiplied by a constant factor to avoid over/underflow in computing the eigenvalues. W (output) REAL array with size(W) — n. The first M elements contain the selected eigenvalues in ascending order. Optional (output) REAL or COMPLEX array, shape (:.:) with size(Z,l) = n and size(Z,2) Z = M. The first M columns of Z contain the orthonormal eigenvectors of A corresponding to the selected eigenvalues, with the ith column of Z containing the eigenvector associated with the eigenvalue in Wj. If an eigenvector fails to converge, then that column of Z contains the latest approximation to the eigenvector, and the index of the eigenvector is returned in IFAIL. Note: The user must ensure that at least M columns are supplied in the array Z. When the exact value of M is not known in advance, an upper bound must be used. In all cases M < n. VL,VU Optional (input) REAL. The lower arid upper bounds of the interval to be searched for eigenvalues. VL < VU. Default values: VL = -HUGE(wp) and VU = HUGE(wp), where wp ::= KIND(l.O) | KIND(l.ODO). Note: Neither VL nor VU may be present if IL and/or IU is present. Optional (input] INTEGER. IL,IU The indices of the smallest and largest eigenvalues to be returned. The ILth through IUt/l eigenvalues will be found. 1 < IL < IU < n. Default values: IL = 1 and IU = n. Note: Neither IL nor IU may be present if VL and/or VU is present. Note: All eigenvalues are calculated if none of the arguments VL, VU. IL and IU are present. M Optional (output) INTEGER. The total number of eigenvalues found. 0 < M < n. Note: If IL and IU are present then M = IU - IL + 1. IFAIL Optional (output) INTEGER array, shape (:) with size(IFAIL) = n. If INFO = 0, the first M elements of IFAIL are zero. If INFO > 0, then IFAIL contains the indices of the eigenvectors that failed to converge. Note: If Z is present then IFAIL should also be present. ABSTOL Optional (input) REAL. The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval [a, 6] of width less than or equal to

E

where wp is the working precision. If ABSTOL < 0, then EPSILON(l.O-twp) x ||A||i will be used in its place. Eigenvalues will be computed most accurately when ABSTOL is set to twice the underflow threshold 2 x LA_LAMCH(1.0_u;p, 'Safe minimum'), not zero. Default value: Q.Q.wp. Note: If this routine returns with INFO > 0, then some eigenvectors did not converge. Try setting ABSTOL to 2 x LAXAMCH(1.0.wp, 'Safe minimum'). INFO

Optional (output) INTEGER = 0: successful exit. < 0: if INFO = —i, the ith argument had an illegal value. > 0: if INFO = i, then i eigenvectors failed to converge. Their indices are stored in array IFAIL.

142

Standard Symmetric Eigenvalue Problems If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20, 21]. Example (from Program LAJSTEVXJEXAMPLE) The results below are computed with e = 1.19209 x 10~7. The matrix A is the same as Example 1 for LA.STEV. The call: CALL LA_STEVX( D, E, W, IL=1, IU=3, ABSTOL=1.0E-2_«;p ) 4 Array W on exit and the first three eigenvalues of matrix A: W -6.99685 -3.67165 4.20190 0.00000 0.00000

7.1.10

LA_STEVR

SUBROUTINE LAJ3TEVR ( D, E, W, Z= z, VL= vl, VU= vu, & IL= il, IU= iu, M= m, ISUPPZ= isuppz, & ABSTOL= abstol, INFO= info ) REAL(wp), INTENT(INOUT) :: D(:), E(:) REAL (top), INTENT(OUT) :: W(:) REAL(wp), INTENT(OUT), OPTIONAL :: Z(:,:) INTEGER, INTENT(OUT), OPTIONAL :: ISUPPZ(:) REAL(wp), INTENT(IN), OPTIONAL :: VL, VU INTEGER, INTENT(IN), OPTIONAL :: IL, IU INTEGER, INTENT(OUT), OPTIONAL :: M KEAL(wp), INTENT(IN), OPTIONAL :: ABSTOL INTEGER, INTENT(OUT), OPTIONAL :: INFO where wp ::= KIND(l.O) | KIND(l.ODO)

Purpose LA.STEVR computes selected eigenvalues and, optionally, the corresponding eigenvectors of a real sym metric tridiagonal matrix A. Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues. V ::= KIND(l.O) | KIND(l.ODO)

143

LA_STEVR

LA_STEVR uses a relatively robust representation (RRR) algorithm. It is usually the fastest algorithm of all and uses the least workspace.

Arguments (input/output) D

REAL array, shape (:) with size(D) = n, where n is the order of A. On entry, the diagonal elements of the matrix A. On exit, the original contents of D possibly multiplied by a constant factor to avoid over/underflow in computing the eigenvalues. E (•input/output) REAL array, shape (:) with size(E) — n. On entry, the n — I subdiagonal elements of A in E! to E n _i . En need not be set. On exit, the original contents of E possibly multiplied by a constant factor to avoid over/underflow in computing the eigenvalues. w (output) REAL array with size(W) = n. The first M elements contain the selected eigenvalues in ascending order. Optional (output] REAL or COMPLEX array, shape (:,:) with size(Z.l) = n and s'ize(Z,2) Z = M. The first M columns of Z contain the orthonormal eigenvectors of A corresponding to the selected eigenvalues, with the ith column of Z containing the eigenvector associated with the eigenvalue in Wj. Note: The user must ensure that at least M columns are supplied in the array Z. When the exact value of M is not known in advance, an upper bound must be used. In all cases M < n. VL,VU Optional (input) REAL. The lower and upper bounds of the interval to be searched for eigenvalues. VL < VU. Default values: VL = -HUGE(u;p) and VU = HUGE(wp), where wp ::= KIND(l.O) | KIND(l.ODO). Note: Neither VL nor VU may be present if IL and/or IU is present. IL,IU Optional (input) INTEGER. The indices of the smallest and largest eigenvalues to be returned. The ILt/l through IU* eigenvalues will be found. 1 < IL < IU < n. Default values: IL = 1 and IU = n. Note: Neither IL nor IU may be present if VL and/or VU is present. Note: All eigenvalues are calculated if none of the arguments VL, VU, IL and IU are present. Optional (output) INTEGER. M The total number of eigenvalues found. 0 < M < n. Note: If IL and IU are present then M = IU - IL + 1. Optional (output) INTEGER array, shape (:) with size(ISUPPZ) = 2max(l,M). ISUPPZ The support of the eigenvectors in A. i.e., the indices indicating the nonzero elements. The ith eigenvector is nonzero only in elements ISUPPZ-^-i through ISUPPZ?;. ABSTOL Optional (input) REAL. The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval [a, b] of width less than or equal to

where wp is the working precision. If ABSTOL < 0, then EPSILON(l.O-iup) x ||A||i will be used in its place. Eigenvalues will be computed most accurately if ABSTOL is set to LA_LAMCH( 1.0-wp, 'Safe minimum'), not zero. Default value: 0.0-iup.

144 INFO

Standard Symmetric Eigenvalue Problems Optional (output) INTEGER = 0: successful exit. < 0: if INFO = —x, the iih argument had an illegal value. > 0: an internal error occurred. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20].

Example (from Program LA_STEVR_EXAMPLE) The results below are computed with e = 1.19209 x 10~7. The matrix A is the same as in Example 1 for LAJSTEV. The call: CALL LA_STEVR( D, E, W, Z, -5.0_wp, 5.0_«/p, M=M )5 W, Z and M on exit:

W -3.67499 4.20213 0 0 0 M =2

The two eigenvalues of A in the range [—5, 5] and the corresponding eigenvectors are:

Eigenvectors J_JA^-V>iO. V V>\_/ UV/4. IJ

Eigenvalues ( -3.674993 4.20213 )

*wp is a work precision; wp ::= KIND(l.O) | KIND(l.ODO)

7.2. Standard Nonsymmetric Eigenvalue Problems

7.2

Standard Nonsymmetric Eigenvalue Problems

7.2.1

LA_GEES

145

SUBROUTINE LA_GEES( A, w, VS=vs, SELECT=select, & SDIM^sdim, INFO=info ) type(wp), INTENT(INOUT) :: A(:,:) type(wp), INTENT (OUT) :: w(:) type(wp), INTENT(OUT), OPTIONAL :: VS(:,:) INTERFACE LOGICAL FUNCTION SELECT^-) type(wp), INTENT (IN) :: Wj END FUNCTION SELECT END INTERFACE OPTIONAL :: SELECT INTEGER, INTENT(OUT), OPTIONAL :: SDIM, INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) w ::= WR, WI | W w(:) ::= WR(:), WI(:) | W(:) Wj ::= WRj, Wlj | Wj

Purpose LA_GEES computes for a real/complex square matrix A. the eigenvalues, the real-Schur/complex-Schur form T, and, optionally, the matrix of Schur vectors Z, where Z is orthogonal/unitary. This gives the Schur factorization Optionally, it also orders the eigenvalues on the diagonal of the Schur form so that selected eigenvalues are at the top left. The leading columns of Z then form an orthonormal basis for the invariant subspace corresponding to the selected eigenvalues. A real matrix is in real-Schur form if it is block upper triangular with 1 x 1 and 2 x 2 blocks along the main diagonal. 2 x 2 blocks are standardized in the form

where be < 0. The eigenvalues of such a block are a ± Vbc. A complex matrix is in complex-Schur form if it is upper triangular.

Arguments A

w

(input/output) REAL or COMPLEX square array, shape (:,:). On entry, the matrix A. On exit, the Schur form T. (output) REAL or COMPLEX array, shape (:) with size(w) = size(A, 1). The computed eigenvalues in the order in which they appear on the diagonal of the Schur form

T.

w(:) ::= WR(:), WI(:) | W(:),

146

VS SELECT

SDIM INFO

Standard Nonsymmetric Eigenvalue Problems where WR(:), WI(:) are of REAL type (for the real and imaginary parts) and W(:) is of COMPLEX type. Note: If A is real, then a complex-conjugate pair appear consecutively, with the eigenvalue having the positive imaginary part appearing first. Optional (output) REAL or COMPLEX square array, shape (:.:) with size(VS,l) = size(A,l). The matrix Z of Schur vectors. Optional (input) LOGICAL FUNCTION. LOGICAL FUNCTION SELECT( Wj ) type(wp), INTENT(IN) :: Wj where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) Wj ::= WR.,-, WI,- | Wj 1. SELECT must be declared as EXTERNAL or as an explicit interface in the calling (sub) program. 2. SELECT is called by LA_GEES for every computed eigenvalue wj (but only once for a complex conjugate pair when A is real). It is used to select the eigenvalues that will be ordered to the top left of the Schur form. The eigenvalue Wj is selected if SELECT(wj) has the value .TRUE. 3. A selected complex eigenvalue may no longer satisfy SELECT^) = .TRUE, after ordering, since ordering may change the value of complex eigenvalues (especially if the eigenvalue is ill-conditioned). In this case INFO is set to size(A, 1) -f- 2 (see INFO below). Note: Select must be present if SDIM is desired. Optional (output) INTEGER. The number of eigenvalues (after sorting) for which SELECT = .TRUE. (If A is real, complex conjugate pairs for which SELECT = .TRUE, for either eigenvalue count as 2). Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = —i, the ith argument had an illegal value. > 0: if INFO = i, and i is < n: the QR algorithm failed to compute all the eigenvalues; elements 1 : ilo— 1 and i + 1 : n of w contain those eigenvalues which have converged. VS contains the matrix which reduces A to its partially converged Schur form. — n+1: the eigenvalues could not be reordered because some eigenvalues were not sufficiently separated (the problem is very ill-conditioned). = n+2: after reordering, some leading complex eigenvalues in the Schur form no longer satisfy SELECT = .TRUE. This can be caused by ordinary roundoff or underflow due to scaling. n is the order of A. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [l] and [17, 9, 20]. Examples The results below are computed with e = 1.19209 x 10~7.

147

LA_GEES

Example 1 (from Program LA_GEES_EXAMPLE) Array A on entry: -2-8 1 2 6 6 0 2 0 4 -2 11 1 6 1 0 2-6 4 9 The call: CALL LA_GEES( A, WR, WI ) A, WR and WI on exit: A

WR -2.21691 -2.21691 4.45961 4.45961 -5.48541

WI 8.59661 -8.59661 3.80078 -3.80078 0.00000

The real-Schur form T of matrix A is:

The eigenvalues of A are:

Example 2 (from Program LA_GEES_EXAMPLE) Matrix A as in Example 1. Function SELECT is: LOGICAL FUNCTION SELECT(X,Y) USE LAJPRECISION, ONLY: WP => wp

5 1 0 4 3

148

! !

Standard Nonsymmetric Eigenvalue Problems INTRINSIC EPSILON REAL(WP), INTENT(IN) :: X,Y Select the real eigenvalues within the working precision IF (ABS(Y) <= EPSILON(1.0_WP)) THEN SELECT = .TRUE. ELSE SELECT = .FALSE.

END IF END FUNCTION SELECT

The call: CALL LA_GEES( A, WR, WI, VS, SELECT, SDIM, INFO ) A, WR, WI, VS, SDIM, and INFO on exit: A

WR

WI

VS

SDIM = 1,

INFO = 0

The real-Schur form T, the matrix of Schur vectors Z, and the eigenvalues of matrix A are:

LA_GEES

149

and

7.2.2

LA_GEESX

SUBROUTINE LA_GEESX( A, tu, VS=vs, SELECT=select, SDIM=sdim, & RCONDE=rconde, RCONDV=rcondv, INFO=info ) type(wp), INTENT(INOUT) :: A(:,:) type(wp), INTENT(OUT) :: w(:) type(wp), INTENT (OUT), OPTIONAL :: VS(:,:) INTERFACE LOGICAL FUNCTION SELECT^) type(wp), INTENT(IN) :: Wj END FUNCTION SELECT END INTERFACE OPTIONAL :: SELECT INTEGER, INTENT(OUT), OPTIONAL :: SDIM REAL(wp), INTENT(OUT), OPTIONAL :: RCONDE, RCONDV INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) w ::= WR, WI | W w(:) ::= WR(:), WI(:) | W(:) Wj Wj::= WR J 5 WIj

Purpose LA_GEESX computes for a real/complex square matrix A, the eigenvalues, the real-Schur/complex-Schur form T, and, optionally, the matrix of Schur vectors Z, where Z is orthogonal/unitary. This gives the Schur factorization Optionally, it also orders the eigenvalues on the diagonal of the Schur form so that selected eigenvalues are at the top left, computes a reciprocal condition number for the average of the selected eigenvalues, and computes a reciprocal condition number for the right invariant subspace corresponding to the selected eigenvalues. The leading columns of Z form an orthonormal basis for this invariant subspace. A real matrix is in real-Schur form if it is block upper triangular with 1 x 1 and 2 x 2 blocks along the main diagonal. 2 x 2 blocks are standardized in the form

where be < 0. The eigenvalues of such a block are a ± Vbc. A complex matrix is in complex-Schur form if it is upper triangular.

150

Standard Nonsymmetric Eigenvalue Problems

Arguments A

w

(input/output) REAL or COMPLEX square array, shape (:,:). On entry, the matrix A. On exit, the Schur form T. (output) REAL or COMPLEX array, shape (:) with size(w) = size(A, I). The computed eigenvalues in the order in which they appear on the diagonal of the Schur form T. w(:) ::= WR(:), WI(:) | W(:),

vs SELECT

where WR(:), WI(:) areofREAL type (for the real and imaginary parts) and W(:) is of COMPLEX type. Note: If A is real, then a complex-conjugate pair appear consecutively, with the eigenvalue having the positive imaginary part appearing first. Optional (output) REAL or COMPLEX square array, shape (:.:) with size(VS,l) = size(A,I). The matrix Z of Schur vectors. Optional (input) LOGICAL FUNCTION LOGICAL FUNCTION SELECT( type(wp), INTENT (IN) :: Wj

Wj

)

where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) Wj ::= WR j? WI, | Wj

1. SELECT must be declared as EXTERNAL or as an explicit interface in the calling (sub)program. 2. SELECT is called by LA_GEES for every computed eigenvalue wj (but only once for a complex conjugate pair when A is real). It is used to select the eigenvalues that will be ordered to the top left of the Schur form. The eigenvalue Wj is selected if SELECT(iyj) has the value .TRUE. 3. A selected complex eigenvalue may no longer satisfy SELECT(iUj) = .TRUE, after ordering, since ordering may change the value of complex eigenvalues (especially if the eigenvalue is ill-conditioned). In this case INFO is set to size(A, 1) + 2 (see INFO below). Note: Select must be present if SDIM, RCONDE and RCONDF are desired. SDIM Optional (output) INTEGER. The number of eigenvalues (after sorting) for which SELECT = .TRUE. (If A is real, complex conjugate pairs for which SELECT = .TRUE, for either eigenvalue count as 2). RCONDE Optional (output) REAL. The reciprocal condition number for the average of the selected eigenvalues. RCONDV Optional (output) REAL. The reciprocal condition number for the selected right invariant subspace. INFO Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = —i, the ith argument had an illegal value. > 0: if INFO = i, and i is < n: the QR algorithm failed to compute all the eigenvalues; elements 1 : z'/o—1 and i 4- 1 : n of w contain those eigenvalues which have converged. VS contains the matrix which reduces A to its partially converged Schur form.

LA_GEESX

151 = n+1: the eigenvalues could not be reordered because some eigenvalues were not sufficiently separated (the problem is very ill-conditioned). = n+2: after reordering, some leading complex eigenvalues in the Schur form no longer satisfy SELECT = .TRUE. This can be caused by ordinary roundoff or underflow due to scaling. n is the order of A. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20, 21].

Example (from Program LA_GEESXJEXAMPLE) The results below are computed with e = 1.19209 x 10~7. Matrix A is the same as in Example 1 for LA-GEES. Function SELECT is: LOGICAL FUNCTION SELECT( WR, WI ) USE LA_PRECISION, ONLY: WP => wp REAL(WP), INTENT (IN) :: WR, WI

INTRINSIC EPSILON, ABS

IF ( (ABS(WR) + ABS(WI) ) < 20.0_WP ) THEN SELECT = .TRUE.

ELSE SELECT = .FALSE. END IF END FUNCTION SELECT The call:

CALL LA_GEESX( A, WR, WI, SELECT=SELECT, SDIM=SDIM, & RCONDE=RCONDE, RCONDV-RCONDV ) WR, WI, SDIM, RCONDE arid RCONDV on exit: WR WI

SDIM = 5 RCONDE = 1.00000 RCONDV = The eigenvalues of matrix A are:

The reciprocal condition number for the average of the eigenvalues is 1. The reciprocal condition number for the right invariant subspace is 2.21900X101.

152

Standard Nonsymmetric Eigenvalue Problems

7.2.3 LA_GEEV SUBROUTINE LA_GEEV( A, tu, VL=vl, VR=vr, INFO=info ) type(wp), INTENT(INOUT) :: A(:,:) type(wp), INTENT(OUT) :: w(:) type(wp), INTENT(OUT), OPTIONAL :: VL(:,:), VR(:,:) INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) w ::= WR, WI | W w(:) ::= WR(:), WI(:) | W(:)

Purpose LA-GEEV computes for a real or complex square matrix A, the eigenvalues and, optionally, the left and/or right eigenvectors. A right eigenvector Vj of A satisfies

where Xj is its eigenvalue. A left eigenvector Uj of A satisfies

where u^ denotes the conjugate-transpose of Uj.

Arguments A

w

VL

VR

(input/output) REAL or COMPLEX square array, shape (:,:). On entry, the matrix A. On exit, the contents of A are destroyed. (output) REAL or COMPLEX array, shape (:) with size(w) — size(A,l). The computed eigenvalues. u;(:)::=WR(:),WI(:) | W(:), where WR(:), WI(:) are of REAL type (for the real and imaginary parts) and W(:) is of COMPLEX type. Note: If A is real, then a complex-conjugate pair appear consecutively, with the eigenvalue having the positive imaginary part appearing first. Optional (output) REAL or COMPLEX square array, shape (:,:) with size(VL,l) = size(A,l). The left eigenvectors Uj are stored in the columns of VL in the order of their eigenvalues. Each eigenvector is scaled so that the Euclidean norm is 1 and the largest component is real. Note: If A is real then complex eigenvectors, like their eigenvalues, occur in complex conjugate pairs. The real and imaginary parts of the first eigenvector of the pair are stored in VL:>J and VL:j+i, respectively. Thus a complex conjugate pair is given by

Optional (output) REAL or COMPLEX square array, shape (:,:) with size(VR,l) = size(A,l). The right eigenvectors Vj are stored in the columns of VR in the order of their eigenvalues. Each eigenvector is scaled so that the Euclidean norm is 1 and the largest component is real. Note: If A is real then complex eigenvectors, like their eigenvalues, occur in complex conjugate

153

LA_GEEV

pairs. The real and imaginary parts of the first eigenvector of the pair are stored in VR:)J and VR :) j+i, respectively. Thus a complex conjugate pair is given by

INFO

Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = — i, the ith argument had an illegal value. > 0: if INFO = ;, the QR algorithm failed to compute all the eigenvalues and no eigenvectors were computed. Elements i + I : n of w contain eigenvalues which have converged. n is the order of A If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [I] and [17, 9, 20]. Examples The results below are computed with e = 1.19209 x 10~7.

Example 1 (from Program LA_GEEV_EXAMPLE) Array A on entry:

The call: CALL LA_GEEV( A, WR, WI ) WR and WI on exit and the eigenvalues of matrix A: WR -3.74980 -3.74980 5.79150 -2.34478 2.05287

WI 5.88964 -5.88964 0.00000 0.00000 0.00000

Example 2 (from Program LA.GEEVJBXAMPLE)

Standard Nonsymmetric Eigenvalue Problems

154

The call: CALL LA_GEEV( A, W, VL, VR, INFO ) W, VL, VR, and INFO on exit: W

VL

VL (continued)

VL (continued)

VR

155

LA.GEEV VR (continued)

VR (continued) INFO = 0

The eigenvalues of matrix A are:

The left and right eigenvectors of matrix A are (columnwise):

and

156

Standard Nonsymmetric Eigenvalue Problems

7.2.4

LA_GEEVX

SUBROUTINE LA_GEEVX( A, w, VL=vl, VR=vr, BALANC=balanc, ILO=ilo, & IHI=ihi, SCALE=scale, ABNRM=abnrm, RCONDE=rconde, & RCONDV^rcondv, INFO=info ) type(wp), INTENT(INOUT) :: A(:,:) type(wp), INTENT(OUT) :: w(:)

type(wp), INTENT(OUT), OPTIONAL :: VL(:,:), VR(:,:)

CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: BALANC INTEGER, INTENT(OUT), OPTIONAL :: ILO, IHI REAL(wp), INTENT(OUT), OPTIONAL :: SCALE(:), ABNRM, & RCONDE(r), RCONDV(:) INTEGER, INTENT (OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) w ::= WR, WI | W w(:) ::= WR(:), WI(:) | W(:)

Purpose LA_GEEVX computes for a real or complex square matrix A, the eigenvalues and, optionally, the left and/or right eigenvectors. Optionally, it also balances A and computes reciprocal condition numbers for the eigenvalues and right eigenvectors. A right eigenvector Vj of A satisfies where A^ is its eigenvalue. A left eigenvector Uj of A satisfies

where u? denotes the conjugate transpose of Uj. The computed eigenvectors are normalized to have Euclidean norm equal to 1 and largest component real. Balancing A involves permuting its rows and columns to make it more nearly upper triangular and then scaling rows and columns by a diagonal similarity transformation to reduce the condition numbers of the eigenvalues and eigenvectors. Computed reciprocal condition numbers pertain to the matrix after balancing. Permuting does not change condition numbers (in exact arithmetic), but scaling does.

Arguments A

(input/output) REAL or COMPLEX square array, shape (:,:). On entry, the matrix A. On exit, the contents of A are destroyed.

LA.GEEVX w

157 (output) REAL or COMPLEX array, shape (:) with size(w) — size(A,l). The computed eigenvalues. u;(:) ::= WR(:), WI(:) | W(:),

VL

VR

where WR(:), WI(:) are of REAL type (for the real and imaginary parts) and W(:) is of COMPLEX type. Note: If A is real, then a complex-conjugate pair appear consecutively, with the eigenvalue having the positive imaginary part appearing first. Optional (output) REAL or COMPLEX square array, shape (:,:) with szze(VL,l) = size(A,l). The left eigenvectors uy are stored in the columns of VL in the order of their eigenvalues. Each eigenvector is scaled so that the Euclidean norm is 1 and the largest component is real. Note: If A is real then complex eigenvectors, like their eigenvalues, occur in complex conjugate pairs. The real and imaginary parts of the first eigenvector of the pair are stored in VL ;J and VL ;J+1 , respectively. Thus a complex conjugate pair is given by

Optional (output) REAL or COMPLEX square array, shape (:,:) with size(VR,l) = size(A,l). The right eigenvectors Vj are stored in the columns of VR in the order of their eigenvalues. Each eigenvector is scaled so that the Euclidean norm is 1 and the largest component is real. Note: If A is real then complex eigenvectors, like their eigenvalues, occur in complex conjugate pairs. The real and imaginary parts of the first eigenvector of the pair are stored in VR:J and VR :J -+i, respectively. Thus a complex conjugate pair is given by

BALANC Optional (input) CHARACTER(LEN=1). Indicates whether the input matrix should be permuted and/or diagonally scaled. = 'N': Do not permute or scale; — T': Permute but do not scale; = 'S': Scale but do not permute; = 'B': Both permute and scale. Default value: 'N'. ILO,IHI Optional (output) INTEGER. ILO and IHI are determined when A is balanced. The balanced Aij — 0 if i > j and j = 1, • • • , ILO - 1 or i = IHI + ! , - • • , size(A, I). SCALE Optional (output) REAL array, shape (:) with szze(SCALE) = size(A,l). Details of the permutations and scaling factors applied when balancing A. If Pj is the index of the row and column interchanged with row and column j, and Dj is the scaling factor applied to row and column ./', then

ABNRM

Optional (output) REAL. The /i norm of the balanced matrix (the maximum of the sum of absolute values of elements of any column). RCONDE Optional (output) REAL array, shape (:) with size(RCONDE) = size(A,l). RCONDEj is the reciprocal condition number of the jth eigenvalue. RCONDV Optional (output) REAL array, shape (:), size(RCONDV) = size(A,l). RCONDVj is the reciprocal condition number of the jth right eigenvector.

158 INFO

Standard Nonsymmetric Eigenvalue Problems Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = —i, the ith argument had an illegal value. > 0: if INFO — i, the QR algorithm failed to compute all the eigenvalues and no eigenvectors or condition numbers were computed; elements 1 : ILO — 1 and i + 1 : n of w contain eigenvalues which have converged. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20]. Example (from Program LA_GEEVXJEXAMPLE) The results below are computed with € = 1.19209 x 10~7. Matrix A is the same as in Example 1 for LA.GEEV. The call:

CALL LA_GEEVX( A, WR, WI, 'B', ILO, IHI, SCALE, & ABNRM, RCONDE, RCONDV ) ILO, IHI, SCALE, ABNRM, RCONDE and RCONDV on exit: SCALE ILO = 1 IHI = 5 ABNRM = 2.10000 x 101 RCONDE

RCONDV Matrix A did not need balancing. The /i norm of matrix A is 21. The reciprocal condition numbers of the eigenvalues are:

The reciprocal condition numbers of the right eigenvectors are: ( 5.02587 5.02587 2.33094

1.68955

1.10553 ) .

Chapter 8

Driver Routines for Generalized Eigenvalue Problems 8.1

Generalized Symmetric Eigenvalue Problems

8.1.1

LAJ3YGV /LA_SYGVD / LAJHEGV / LAJHEGVD

SUBROUTINE LA.SYGV / LA_SYGVD / LA_HEGV / LA_HEGVD( A, B, & W, ITYPE=itype, JOBZ-jobz, UPLO=uplo, INFO=info ) type(wp), INTENT(INOUT) :: A(:,:), B(:,:) REAL(wp), INTENT (OUT) :: W(:) INTEGER, INTENT(IN), OPTIONAL :: ITYPE CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: JOBZ, UPLO INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

Purpose LA_SYGV, LA_SYGVD, LA_HEGV and LA.HEGVD compute all eigenvalues and, optionally, all eigenvectors of generalized eigenvalue problems of the form

where A and B are real symmetric in the cases of LA_SYGV and LA.SYGVD and complex Hermitian in the cases of LAJHEGV and LA_HEGVD. In all four cases B is positive definite. LA_SYGVD and LA-HEGVD use a divide and conquer algorithm. If eigenvectors are desired, they can be much faster than LA_SYGV and LA_HEGV for large matrices but use more workspace.

Arguments A

(input/output) REAL or COMPLEX square array, shape (:,:). On entry, the matrix A. 159

160

Generalized Symmetric Eigenvalue Problems If UPLO = 'U', the upper triangular part of A contains the upper triangular part of matrix A. If UPLO = 'L', the lower triangular part of A contains the lower triangular part of matrix

A.

B

W ITYPE

JOBZ

UPLO

INFO

On exit, if JOBZ = 'V, then the columns of A contain the eigenvectors, normalized as follows: if ITYPE = 1 or 2: ZH B Z = I, if ITYPE = 3: ZH B~l Z = 7. If JOBZ = 'N', then the upper triangle (if UPLO = 'U') or the lower triangle (if UPLO = 'L') of A, including the diagonal, is destroyed. (input/output) REAL or COMPLEX square array, shape (:,:) with size(B, 1) = size(A, I). On entry, the matrix B. If UPLO = 'U', the upper triangular part of B contains the upper triangular part of matrix B. If UPLO = 'L', the lower triangular part of B contains the lower triangular part of matrix B. On exit, if the part of B containing the matrix is overwritten by the triangular factor U or L of the Cholesky factorization B = UH U or B = LLH', respectively. (output] REAL array, shape (:) with size(W) = size(A, 1). The eigenvalues in ascending order. Optional (input) INTEGER. Specifies the problem type to be solved: = 1: Az = XBz = 2: ABz = Xz = 3: BAz - Xz Default value: 1. Optional (input) CHARACTER(LEN=1). = 'N': Compute eigenvalues only; = 'V: Compute eigenvalues and eigenvectors. Default value: 'N'. Optional (input) CHARACTER(LEN=1). = 'U': Upper triangles of A and B are stored; = 'L': Lower triangles of A and B are stored. Default value: 'U'. Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = — a, the ith argument had an illegal value. > 0: the algorithm failed to converge or matrix B is not positive definite: < n: if INFO — i. i off-diagonal elements of an intermediate tridiagonal form did not converge to zero. > n: if INFO = n + i, for 1 < i < n, then the leading minor of order i of B is not positive definite. The factorization of B could not be completed and no eigenvalues or eigenvectors were computed. n is the order of A. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20]. Examples The results below are computed with

161

LA.SYGV / LA_SYG VD / LAJiEGV / LA.HEGVD Example 1 (from Program LA_SYGV_EXAMPLE)

Arrays A and B on entry: B 8 2 2 2 * 13 0 0 * * 13 0 * * * 14 * * * *

2 -5 4 -10 -3 * _2 -11 5 0 * * -6 -10 8 * * * -3 0 * * * * 7

1 1 2 3 3

Elements marked * are not used by the routine. The call: CALL LA_SYGV( A, B, W ) B and W on exit: B

W -1.72115 -1.18720 1.29015 x lO"1 1.58752 6.01579

The eigenvalues of the problem A z = X B z are: -1.72115 -1.18720 1.29015 x 10"1 1.58752 6.01579

The triangular factor U of the Cholesky factorization of B is:

Example 2 (from Program LA_SYGV_EXAMPLE) Matrices A and B as in Example 1.

162

Generalized Symmetric Eigenvalue Problems

Arrays A and B on entry:

Elements marked * are not used by the routine. The call: CALL LA_SYGV( A, B, W, 2, 'V, 'L', INFO ) A, B, INFO and W on exit:

B

INFO = 0 W

The eigenvalues of the problem A B z = A z are:

-284.343

-117.700 5.14901 78.7262

159.168 The eigenvectors are:

The triangular factor L of the Cholesky factorization of B is:

L=

LA_SYG VX / LAJJEG VX 8.1.2

163

LA_SYGVX / LAJHEGVX

SUBROUTINE LA_SYGVX / LA_HEGVX(A, B, W, ITYPE= itype, & JOBZ= jobz, UPLO= uplo, VL= vl, VU= vu, IL= il, & IU= iu, M= m, IFAIL= if ail, ABSTOL= abstol, INFO= info ) type(wp), INTENT(INOUT) :: A(:,:), B(:,:)

REAL(K;P), INTENT(OUT) :: w(:)

INTEGER, INTENT(IN), OPTIONAL :: ITYPE CHARACTER(LEN=1), INTENT (IN), OPTIONAL :: JOBZ, UPLO

REAL(wp), INTENT(IN), OPTIONAL :: VL, VU

INTEGER, INTENT(IN), OPTIONAL :: IL, IU INTEGER, INTENT(OUT), OPTIONAL :: M INTEGER, INTENT(OUT), OPTIONAL :: IFAIL(:)

REAL(wp), INTENT(IN), OPTIONAL :: ABSTOL INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

Purpose LAJ3YGVX and LAJHEGVX compute selected eigenvalues and, optionally, the corresponding eigenvectors of generalized eigenvalue problems of the form

where A and B are real symmetric in the case of LA_SYGVX and complex Hermitian in the case of LAJHEGVX. In both cases B is positive definite. Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

Arguments A

B

(input/output) REAL or COMPLEX square array, shape (:,:). On entry, the matrix A. If UPLO — 'U', the upper triangular part of A contains the upper triangular part of matrix A. If UPLO = 'L'. the lower triangular part of A contains the lower triangular part of matrix A. On exit, if JOBZ = 'V, the first M columns of A contain the orthonormal eigenvectors corresponding to the selected eigenvalues, with the ith column of A holding the eigenvector associated with the eigenvalue in W,. The eigenvectors are normalized as follows: if ITYPE = 1 or 2: ZH B Z = /, if ITYPE = 3: ZH B~l Z = I. If an eigenvector fails to converge, then that column of A contains the latest approximation to the eigenvector and the index of the eigenvector is returned in IFAIL. If JOBZ = 'N', then the upper triangle (if UPLO = 'U') or the lower triangle (if UPLO = 'L') of A, including the diagonal, is destroyed. (input/output) REAL or COMPLEX square array, shape (:,:) with size(B, 1) = size(A.. I). On entry, the matrix B. If UPLO = 'U', the upper triangular part of B contains the upper triangular part of matrix B. If UPLO = 'L', the lower triangular part of B contains the lower triangular part of matrix

164

Generalized Symmetric Eigenvalue Problems

B. On exit, the part of B containing the matrix is overwritten by the triangular factor U or L of the Cholesky factorization B = UH U or B = LLH. W (output) REAL array, shape (:) with size(W) — size(A, 1). The first M elements contain the selected eigenvalues in ascending order. ITYPE Optional (input) INTEGER. Specifies the problem type to be solved: = 1: Az = XBz = 2: ABz = Xz = 3: BAz = Xz Default value: 1. JOBZ Optional (input) CHARACTER(LEN=1). — 'N': Computes eigenvalues only; = 'V: Computes eigenvalues and eigenvectors. Default value: 'N'. UPLO Optional (input) CHARACTER(LEN=1). = 'U': Upper triangles of A and B are stored; = 'L': Lower triangles of A and B are stored. Default value: 'U'. VL,VU Optional (input) REAL. The lower and upper bounds of the interval to be searched for eigenvalues. VL < VU. Default values: VL = -HUGE(wp) and VU = HUGE(u/p), where wp ::= KIND(l.O) | KIND(l.ODO). Note: Neither VL nor VU may be present if IL and/or IU is present. IL,IU Optional (input) INTEGER. The indices of the smallest and largest eigenvalues to be returned. The ILth through IUth eigenvalues will be found. 1 < IL < IU < sz'ze(A, 1). Default values: IL = 1 and IU = size(A,l). Note: Neither IL nor IU may be present if VL and/or VU is present. Note: All eigenvalues are calculated if none of the arguments VL, VU, IL and IU are present. M Optional (output) INTEGER. The total number of eigenvalues found. 0 < M < size(A, 1). Note: If IL and IU are present then M = IU - IL + 1. IFAIL Optional (output) INTEGER array, shape (:) with size(IFAIL) = size(A,l). If INFO = 0, the first M elements of IFAIL are zero. If INFO > 0, then IFAIL contains the indices of the eigenvectors that failed to converge. Note: IFAIL should be present if JOBZ = 'V. ABSTOL Optional (input) REAL. The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval [a, b] of width less than or equal to ABSTOL + EPSILON(1.0_u;p) x max(| a |, | 6 |), where wp is the working precision. If ABSTOL < 0, then EPSILON(1.0_u;p) x ||T||i will be used in its place, where ||T||i is the /i norm of the tridiagonal matrix obtained by reducing the generalized eigenvalue problem to tridiagonal form. Eigenvalues will be computed most accurately when ABSTOL is set to twice the underflow threshold 2 x LA_LAMCH(1.0_u;j0, 'S'), not zero. Default value: 0.0_u>p.

165

A-SYGVX / LA_HEGVX

Note: If this routine returns with 0 < INFO < n, then some eigenvectors did not converge. Try setting ABSTOL to 2 x LA_LAMCH(1.0_u;p, 'S'). INFO

Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = —'i, the ith argument had an illegal value. > 0: the algorithm failed to converge or matrix B is not positive definite: < n: the algorithm failed to converge; if INFO = i, then i eigenvectors failed to converge. Their indices are stored in array IFAIL. > n: if INFO — n + i, for 1 < i < n, then the leading minor of order i of B is not positive definite. The factorization of B could not be completed and no eigenvalues or eigenvectors were computed. n is the order of A. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17. 9, 20, 21].

Example (from Program LA_SYGVX_EXAMPLE) The results below are computed with e = 1.19209 x 10~~7. Matrices A and B are the same as in Example 1 for LA_SYGV. The call: CALL LA_SYGVX( A, B, W, 3, 'V, VL=-10.0_wp, VU=10.0_wp, M=M, IFAIL=IFAIL )l W, M and IFAIL on exit:

W 5.14902 0.0000000 0.0000000 0.0000000 0.0000000

IFAIL 0

M =1

0

0 0

0

The only eigenvalue of the problem B Az = \z in the range [—10,10] is: 5.14902 The corresponding eigenvector converged successfully and is:

l

wp ::= KIND(l.O) | KIND(l.ODO)

166

Generalized Symmetric Eigenvalue Problems

8.1.3 LAJSPGV / LA_SPGVD / LA_HPGV / LAJHPGVD SUBROUTINE LAJSPGV / LA.SPGVD / LAJHPGV / LA_HPGVD( AP, BP, & W, ITYPE=itype, UPLO=uplo, Z=z, INFO=info ) type(wp), INTENT(INOUT) :: AP(:), BP(:) REAL(wp), INTENT(OUT) :: W(:) INTEGER, INTENT(IN), OPTIONAL :: ITYPE CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: UPLO type(wp), INTENT(OUT), OPTIONAL :: Z(:,:) INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

Purpose LA_SPGV, LA_SPGVD, LA_HPGV and LA.HPGVD compute all eigenvalues and, optionally, all eigenvectors of generalized eigenvalue problems of the form

where A and B are real symmetric in the cases of LAJSPGV and LA_SPGVD and complex Hermitian in the cases of LA_HPGV and LAJIPGVD. In cill four cases B is positive definite. Matrices A and B are stored in a packed format. LAJSPGVD and LA_HPGVD use a divide and conquer algorithm. If eigenvectors are desired, they can be much faster than LA-SPGV and LAJHPGV for large matrices but use more workspace.

Arguments

AP

(input/output) REAL or COMPLEX array, shape (:) with size(AP) = n(n + l)/2, where n is the order of A and B. On entry, the upper or lower triangle of matrix A in packed storage. The elements are stored columnwise as follows: UPLO 'U' 'L'

BP

On exit, the contents of AP are destroyed. (input/output) REAL or COMPLEX array, shape (:) and size(BP) = size(AP). On entry, the upper or lower triangle of matrix B in packed storage. The elements are stored columnwise as follows: UPLO 'U' 'L'

On exit, the triangular factor U or L of the Cholesky factorization B = UH U or B — L LH, in the same storage format as B.

LA.SPGV / LA.SPGVD / LAJIPGV / LAMPGVD

167

W

(output) REAL array, shape (:) with s-ize(W) = n. The eigenvalues in ascending order.

ITYPE

Optional (input) INTEGER. Specifies the problem type to be solved: = 1: Az = XBz = 2: ABz = \z = 3: BAz = Xz Default value: 1.

UPLO

Optional (input) CHARACTER(LEN-l). = 'U': Upper triangles of A and B are stored; = 'L': Lower triangles of A and B are stored. Default value: 'U'.

Z

Optional (output) REAL or COMPLEX square array, shape (:,:) with size(7i:l) = n. The matrix Z of eigenvectors, normalized as follows: if ITYPE = 1 or 2: ZH B Z = /, if ITYPE = 3: ZH B~l Z = I .

INFO

Optional (output) INTEGER. = 0: successful exit. th < 0: if INFO = — i, the i argument had an illegal value. > 0: the algorithm failed to converge or matrix B is not positive definite: < n: if INFO = i, i off-diagonal elements of an intermediate tridiagonal form did not converge to zero. > n: if INFO = n + ?', for 1 < '< < n, then the leading minor of order i of B is not positive definite. The factorization of B could not be completed and no eigenvalues or eigenvectors were computed. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20]. Examples The results below are computed with

Example 1 (from Program LAJHPGVJEXAMPLE)

168

Generalized Symmetric Eigenvalue Problems

Arrays AP and BP on entry:

AP AP continued

BP BP continued

The call:

CALL LA_HPGV( AP, BP, W )

BP and W on exit:

BP BP continued BP continued BP continued BP continued

W

The eigenvalues of the problem A z = X B z are:

The triangular factor U of the Cholesky factorization of B is:

LA_SPGV / LA-SPGVD / LAJ1PGV / LAJIPGVD

Example 2 (from Program LA_HPGV_EXAMPLE) Matrices A and B as in Example 1. Arrays AP and BP on entry: AP

AP continued BP

BP continued The call: CALL LA_HPGV( AP, BP, W, 3, 'L', Z, INFO ) BP, W, Z, and INFO on exit: BP

BP continued BP continued

BP continued BP continued

W

169

170

Generalized Symmetric Eigenvalue Problems Z

Z

Z continued

INFO = 0 The eigenvalues of the problem BAz — Xz are:

The eigenvectors are:

LA.SPGV / LA_SPG VD / LAJJPGV / LAMPGVD

171

The triangular factor L from the Cholesky factorization of B is:

8.1.4

LA_SPGVX / LAJHPGVX

SUBROUTINE LA_SPGVX / LA_HPGVX( AP, BP, W, ITYPE= itype, & UPLO= uplo, Z= z, VL= vl, VU= vu, IL= il, IU= i u , M= m, & IFAIL= ifail, ABSTOL= abstol, INFO= info ) type(wp), INTENT(INOUT) :: AP(:), BP(:) REAL(wp), INTENT(OUT) :: W(:) INTEGER, INTENT(IN), OPTIONAL :: ITYPE CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: UPLO type(wp), INTENT(OUT), OPTIONAL :: Z(:,:) HEAl(wp), INTENT(IN), OPTIONAL :: VL, VU INTEGER, INTENT(IN), OPTIONAL :: IL, IU INTEGER, INTENT(OUT), OPTIONAL :: M INTEGER, INTENT(OUT), OPTIONAL :: IFAIL(:) REAL(u;p), INTENT(IN), OPTIONAL :: ABSTOL INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

Purpose LA_SPGVX and LAJHPGVX compute selected eigenvalues and, optionally, the corresponding eigenvectors of generalized eigenvalue problems of the form

where A and B are real symmetric in the case of LA_SPGVX and complex Hermitian in the case of LAJHPGVX. In both cases B is positive definite. Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues. Matrices A and B are stored in a packed format.

Arguments AP

(input/output) REAL or COMPLEX array, shape (:) with size(AP) = n(n + l)/2, where n is the order of A and B.

172

Generalized Symmetric Eigenvalue Problems On entry, the upper or lower triangle of matrix A in packed storage. The elements are stored columnwise as follows: UPLO 5

U'

'L'

BP

On exit, the contents of AP are destroyed. (input/output) REAL or COMPLEX array, shape (:) with size(BP) = size(AP). On entry, the upper or lower triangle of matrix B in packed storage. The elements are stored columnwise as follows: UPLO 'U' 'L'

ITYPE

On exit, the triangular factor U or L of the Cholesky factorization B = UT U or B = LLT, in the same storage format as B. (output) REAL array, shape (:) with size(W) — n. The eigenvalues in ascending order. Optional (input) INTEGER. Specifies the problem type to be solved: = 1: Az = XBz = 2: ABz = \z = 3: BAz = Xz Default value: 1.

UPLO

Optional (input) CHARACTER(LEN=1).

W

Z

VL,VU

IL,IU

= 'U': Upper triangles of A and B are stored; — 'L': Lower triangles of A and B are stored. Default value: 'U'. Optional (output) REAL or COMPLEX rectangular array, shape (:.:) with size(Z,l) = n and size(Z,2) = M. The first M columns of Z contain the orthonormal eigenvectors corresponding to the selected eigenvalues, with the iih column of Z holding the eigenvector associated with the eigenvalue in Wj. The eigenvectors are normalized as follows: if ITYPE = 1 or 2: ZH B Z = /, if ITYPE = 3: ZH B~l Z = 7. If an eigenvector fails to converge, then that column of Z contains the latest approximation to the eigenvector and the index of the eigenvector is returned in IFAIL. Optional (input) REAL. The lower and upper bounds of the interval to be searched for eigenvalues. VL < VU. Default values: VL = -HUGE(u;p) and VU = HUGE(wp), where wp ::= KIND(l.O) | KIND(l.ODO). Note: Neither VL nor VU may be present if IL and/or IU is present. Optional (input) INTEGER. The indices of the smallest and largest eigenvalues to be returned. The ILth through IUth

LA-SPGVX / LA_HPGVX

173

eigenvalues will be found. 1 < IL < IU < size(A, 1). Default values: IL = 1 and IU = size(A,l). Note: Neither IL nor IU may be present if VL and/or VU is present. Note: All eigenvalues are calculated if none of the arguments VL, VU, IL and IU are present. M

IFAIL

ABSTOL

INFO

Optional (output) INTEGER. The total number of eigenvalues found. 0 < M < size(A, 1). Note: If IL and IU are present then M = IU - IL + 1. Optional (output) INTEGER array, shape (:) with size(lFAlL) = size(A,l). If INFO = 0, the first M elements of IFAIL are zero. If INFO > 0. then IFAIL contains the indices of the eigenvectors that failed to converge. Note: If Z is present then IFAIL should also be present. Optional (input) REAL. The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval [a, b] of width less than or equal to

where wp is the working precision. If ABSTOL < 0, then EPSILON(l.O-twp) x ||T||i will be used in its place, where ||T||i is the l\ norm of the tridiagonal matrix obtained by reducing the generalized eigenvalue problem to tridiagonal form. Eigenvalues will be computed most accurately when ABSTOL is set to twice the underflow threshold 2 x LA_LAMCH(1.0_wp. 'S'), not zero. Default value: Q.Q-wp. Note: If this routine returns with 0 < INFO < n, then some eigenvectors did not converge. Try setting ABSTOL to 2 x LA_LAMCH(1.0-tup, !S'). Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = --i, the ith argument had an illegal value > 0: the algorithm failed to converge or matrix B is not positive definite: < rr. the algorithm failed to converge; if INFO = i, then i eigenvectors failed to converge. Their indices are stored in array IFAIL. > n: if INFO = n + i, for 1 < i < n. then the leading minor of order i of B is not positive definite. The factorization of B could not be completed and no eigenvalues or eigenvectors were computed. If INFO is not present arid an error occurs, then the program is terminated with an error message.

References-. [I] and [17, 9, 20, 21]. Example (from Program LAJHPGVXJEXAMPLE) The results below are computed with e = 1.19209 x 10~7. Matrices A and B are the same as in Example 1 for LA.HPGV. The call:

CALL LA_HPGVX( AP, BP, W, 2, Z= Z, IL=4, IU=5, M= M, & IFAIL=IFAIL, ABSTOL=1.0E-3_u>p )

174

Generalized Symmetric Eigenvalue Problems

Note: wp is a work precision; wp ::= KIND(l.O) KIND(l.ODO) W, M, IFAIL and Z on exit:

W

IFAIL

The last two eigenvalues of the problem A B z — A z are:

The two eigenvectors converged successfully and are:

8.1.5

LA.SBGV / LAJSBGVD / LA_HBGV / LA_HBGVD

SUBROUTINE LA_SBGV / LAJSBGVD / LA_HBGV / LA_HBGVD( AB, BB, & W, UPLO=uplo, Z=z, INPO=info ) type(wp), INTENT(INOUT) :: AB(:,:), BB(:,:) REAL(wp), INTENT(OUT) :: W(:) CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: UPLO type(wp), INTENT(OUT), OPTIONAL :: Z(:,:) INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(1.0) | KIND(l.ODO)

Purpose LA.SBGV, LA.SBGVD, LA_HBGV and LA.HBGVD compute all eigenvalues and, optionally, all eigenvectors of the generalized eigenvalue problem

where A and B are real symmetric in the cases of LA.SBGV and LA.SBGVD and complex Hermitian in the cases of LA_HBGV and LAJHBGVD. Matrix B is positive definite. Matrices A and B are stored in a band format. LA-SBGVD and LAJHBGVD use a divide and conquer algorithm. If eigenvectors are desired, they can be much faster than LA_SBGV and LAJHBGV for large matrices but use more workspace.

LA.SBGV / LA-SBGVD / LAJIBGV / LAJIBGVD

175

Arguments AB

(input/output) REAL or COMPLEX array, shape (:,:) with size(AB,l) = ka + I and size(AB,2) = n, where ka is the number of subdiagonals or superdiagonals in the band and n is the order of A and B. On entry, the upper (if UPLO = 'U') or lower (if UPLO = 'L') triangle of matrix A in band storage. The ka + 1 diagonals of A are stored in the rows of AB so that the jth column of A is stored in the jth column of AB as follows:

UPLO 'U' 'L'

BB

On exit, the contents of AB are destroyed. (input/output) REAL or COMPLEX array, shape (:.:) with size(BB,l) = kb + 1 and s/ze(BB,2) = n, where kb is the number of subdiagonals or superdiagonals in the band of

B.

On entry, the upper (if UPLO = 'U') or lower (if UPLO = 'L') triangle of matrix B in band storage. The kb + 1 diagonals of B are stored in the rows of BB so that the jih column of B is stored in the jih column of BB as follows:

Bij

i-.j

UPLO

BBfc& + i + i_j ; j

'U'

BBi-H-jj

'L'

On exit, the factor S from the split Cholesky factorization B = SH S.

W UPLO

Z INFO

(output) REAL array, shape (:) with size(W) = n. The eigenvalues in ascending order. Optional (input) CHARACTER(LEN=1). — 'U': Upper triangles of A and B are stored; = 'L': Lower triangles of A and B are stored. Default value: 'U'. Optional (output) REAL or COMPLEX square array, shape (:,:) with size(Z,l) = n . The matrix Z of eigenvectors, normalized so that ZH B Z = I. Optional (output) INTEGER. = 0: successful exit. < 0: if INFO — — i, the ith argument had an illegal value. > 0: the algorithm failed to converge or matrix B is not positive definite: < n: if INFO = i. i off-diagonal elements of an intermediate tridiagonal form did not converge to zero. > n: if INFO = n + i, for 1 < i < n, then the leading minor of order i of B is not positive definite. The factorization of B could not be completed and no eigenvalues or eigenvectors were computed. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20].

Generalized Symmetric Eigenvalue Problems

176

Examples The results below are computed with e — 1.19209 x 10~7. Example 1 (from Program LA_SBGV_EXAMPLE)

Arrays AB and BB on entry: AB

BB

The call: CALL LA_SBGV( AB, BB, W ) BB and W on exit: W

BB

The eigenvalues of the problem A z — A B z are:

The split Cholesky factor S is:

Example 2 (from Program LA_SBGV_EXAMPLE) Matrices A and B as in Example 1.

LA.SBGV / LA.SBGVD / LA_HBGV / LAJiBGVD

177

Arrays AB and BB on entry:

BB 10 8 8 8 10

AB 6-5 0 0 9 5 4 4 4 0 -4 - 3 - 4 0 0

0

2

2

3

- 5 2 0 0

The call: CALL LA_SBGV( AB, BB, W, 'L', Z, INFO ) W, INFO and Z on exit:

W

-2.95028 -2.60316 x 1Q-1 3.37961 x HT1 8.63341 x 10"1 1.12617

INFO = 0

Z

The eigenvalues of the problem Az — XBz are:

The eigenvectors are:

0

0

178

8.1.6

Generalized Symmetric Eigenvalue Problems

LAJSBGVX / LA_HBGVX

SUBROUTINE LA_SBGVX / LA_HBGVX( AB, BB, W, UPLO=uplo, Z=z, & VL=vl, VU=vu, IL=U, IU=iu, M=m, IFAIL=ifail, Q=q, & ABSTOL=abstol, INFO=info ) type(wp), INTENT(INOUT) :: AB(:,:), BB(:,:) REAL(u;p), INTENT(OUT) :: W(:) CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: UPLO type(wp), INTENT(OUT), OPTIONAL :: Z(:,:) REAL(wp), INTENT(IN), OPTIONAL :: VL, VU INTEGER, INTENT(IN), OPTIONAL :: IL, IU INTEGER, INTENT(OUT), OPTIONAL :: M INTEGER, INTENT(OUT), OPTIONAL :: IFAIL(:) type(wp), INTENT(OUT), OPTIONAL :: Q(:,:) REAL(wp), INTENT (IN), OPTIONAL :: ABSTOL INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

Purpose LAJSBGVX and LA_HBGVX compute selected eigenvalues and, optionally, the corresponding eigenvectors of the generalized eigenvalue problem where A and B are real symmetric in the case of LA_SBGVX and complex Hermitian in the case of LA_HBGVX. In both cases B is positive definite. Matrices A and B are stored in a band format. Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

Arguments AB

(input/output] REAL or COMPLEX array, shape (:,:) with size(AB,l) = ka + 1 and s/ze(AB,2) = n, where ka is the number of subdiagonals or superdiagonals in the band of A and n is the order of A and B. On entry, the upper (if UPLO — 'U') or lower (if UPLO = 'L') triangle of A in band storage. The ka + I diagonals of A are stored in the rows of AB so that the jth column of A is stored in the jth column of AB as follows: Ai,j

BB

».J

UPLO

ABfca+1+i-jj

'U'

AB 1+ j_j 5 j

'L'

On exit, the contents of AB are destroyed. (input/output] REAL or COMPLEX array, shape (:,:) with size(BB,l) - kb + 1 and s«ze(BB,2) = n, where kb is the number of subdiagonals or superdiagonals in the band of B. On entry, the upper (if UPLO = 'U') or lower (if UPLO = 'L') triangle of matrix B in band

179

LA.SBGVX / LA_HBGVX

storage. The kb + I diagonals of B are stored in the rows of BB so that the jth column of B is stored in the jth column of BB as follows:

Bij

*,j

UPLO

BBfcfe+i+z-jj

'U'

BBi+i-jj

'L'

On exit, the factor S from the split Cholesky factorization B = SH S. W (output) REAL array, shape (:) with size(W) = n. The first M elements contain the selected eigenvalues in ascending order. UPLO Optional (input) CHARACTER(LEN=1). — 'U': Upper triangles of A and B are stored; = 'L': Lower triangles of A and B are stored. Default value: 'U'. Z Optional (output) REAL or COMPLEX square array, shape (:,:) with size(Z,l) = n. The first M columns of Z contain the orthonormal eigenvectors corresponding to the selected eigenvalues, with the ith column of Z containing the eigenvector associated with the eigenvalue in Wj. The eigenvectors are normalized so that ZH BZ = I. If an eigenvector fails to converge, then that column of Z contains the latest approximation to the eigenvector and the index of the eigenvector is returned in IFAIL. VL,VU Optional (input) REAL. The lower and upper bounds of the interval to be searched for eigenvalues. VL < VU. Default values: VL = -HUGE(tup) and VU = HUGE(wp), where wp ::= KIND(l.O) | KIND(l.ODO). Note: Neither VL nor VU may be present if IL and/or IU is present. IL,IU Optional (input) INTEGER. The indices of the smallest and largest eigenvalues to be returned. The ILth through IUt/l eigenvalues will be found. 1 < IL < IU < s'ize(A, 1). Default values: IL — 1 and IU = s'ize(A,l). Note: Neither IL nor IU may be present if VL and/or VU is present. Note: All eigenvalues are calculated if none of the arguments VL, VU, IL and IU are present. M Optional (output) INTEGER. The total number of eigenvalues found. 0 < M < size(A, 1). Note: If IL and IU are present then M = IU - IL + 1. IFAIL Optional (output) INTEGER array, shape (:) with szze(IFAIL) = n. If INFO - 0, the first M elements of IFAIL are zero. If INFO > 0, then IFAIL contains the indices of the eigenvectors that failed to converge. Note: If Z is present then IFAIL should also be present. Q Optional (output) REAL or COMPLEX square array, shape(:,:) with size(Q, 1) = n. If Z is present, the matrix used in the reduction of A z — A B z to tridiagonal form. ABSTOL Optional (input) REAL. The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval [a, b] of width less than or equal to ABSTOL + EPSILON(1.0_u;p) x max(| a |, | b |), where wp is the working precision. If ABSTOL < 0, then EPSILON(1.0_u;p) x ||T||i will be used in its place, where ||T"||i is the /i norm of the tridiagonal matrix obtained by reducing the

180

Generalized Symmetric Eigenvalue Problems generalized eigenvalue problem to tridiagonal form. Eigenvalues will be computed most accurately when ABSTOL is set to twice the underflow threshold 2 x LA_LAMCH(1.0_u;p, 'S'), not zero. Default value: Q.O.wp. Note: If this routine returns with 0 < INFO < n, then some eigenvectors did not converge. Try setting ABSTOL to 2 x LA_LAMCH(1.0_u;p, 'S').

INFO

Optional (output) INTEGER. = 0: successful exit. th <(): if INFO = —i. the i argument had an illegal value >0: the algorithm failed to converge or matrix B is not positive definite: n: if INFO = n 4- i, for 1 < i < n, then the leading minor of order i of B is not positive definite. The factorization of B could not be completed and no eigenvalues or eigenvectors were computed. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20, 21].

Example (from Program LAJ3BGVXJEX AMPLE) The results below are computed with e = 1.19209 x 10~7. Matrices A and B are the same as in Example 1 for LA_SBGV. The call: CALL LA_SBGVX( A, B, W, Z=Z, VL=O.O.u;p, VU=100.0_wj9, M=M, Q=Q )2 W, M and Q on exit: W

Q

The three eigenvalues in the range [0,100] are:

l

wp ::= KIND(l.O) | KIND(l.ODO)

LA_SBGVX / LA.HBGVX

181

The matrix Q used in the reduction of Az = \Bz to tridiagonal form is:

8.2

Generalized Nonsymmetric Eigenvalue Problems

8.2.1 LA_GGES SUBROUTINE LA_GGES( A, B, alpha, BETA, VSL=vsl, & VSR=vsr, SELECT=select, SDIM=sdim, INFO=info ) type(wp), INTENT(INOUT) :: A(:,:), B(:,:) type(wp), INTENT(OUT) :: alpha(:), BETA(:) type(wp), INTENT(OUT), OPTIONAL :: VSL(:,:), VSR(:,:) INTERFACE LOGICAL FUNCTION SELECT(a/p/»aj, BETA,) type(wp), INTENT(IN) :: alpha,, BETA,,END FUNCTION SELECT END INTERFACE OPTIONAL :: SELECT INTEGER, INTENT(OUT), OPTIONAL :: SDIM INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) alpha ::= ALPHAR, ALPHAI | ALPHA alpha(:) ::= ALPHAR(:), ALPHAI(:) | ALPHA(:) alpha3 ::= ALPHARj, ALPHAR | ALPHA^

Purpose LA_GGES computes for a pair of n x n real or complex matrices (A, B) the (generalized) real or complex Schur form, the generalized eigenvalues in the form of scalar pairs (a,/?), and, optionally, the left and/or right Schur vectors. If A and B are real then the real-Schur form is computed, otherwise the complex-Schur form is computed. The real-Schur form is a pair of real matrices (5, T) such that 1) S has block upper triangular form, with 1 x 1 and 2 x 2 blocks along the main diagonal, 2) T has upper triangular form with nonnegative elements on the main diagonal, and 3) 5 = QTAZ and T — QTBZ, where Q and Z are orthogonal matrices. The 2 x 2 blocks of 5 are "standardized" by making the corresponding elements of T have the form

The complex-Schur form is a pair of matrices (5, T) such that 1) 5 has upper triangular form, 2) T has upper triangular form with nonnegative elements on the main diagonal, and 3) S = QH AZ and T = QHBZ,

182

Generalized Nonsymmetric Eigenvalue Problems

where Q and Z are unitary matrices. In both cases the columns of Q and Z are called, respectively, the left and right (generalized) Schur vectors. A generalized eigenvalue of the pair (A, B) is, roughly speaking, a scalar of the form A = a/0 such that the matrix A — \B is singular. It is usually represented as the pair (a,/#), as there is a reasonable interpretation of the case ft = 0 (even if a = 0).

Arguments A

B

alpha

BETA

(input/output) REAL or COMPLEX square array, shape (:,:). On entry, the matrix A. On exit, the matrix 5. (input/output) REAL or COMPLEX square array, shape (:,:) with size(B,l) = size(A,l). On entry, the matrix B. On exit, the matrix T. (output) REAL or COMPLEX array, shape (:) with size(alpha) = size(A,l). The values of a. alpha(:) ::= ALPHAR(:), ALPHAI(r) | ALPHA(:), where ALPHAR(:), ALPHAI(r) are of REAL type (for the real and imaginary parts) and ALPHA(:) is of COMPLEX type. (output) REAL or COMPLEX array, shape (:) with size(BETA) = size(A,l). The values of 0. Note: The generalized eigenvalues of the pair (A, B) are the scalars Aj = ctj/fij- These quotients may easily over- or underflow, and 0j may even be zero. Thus, the user should avoid computing them naively. Note: If A and B are real then complex eigenvalues occur in complex conjugate pairs. Each pair is stored consecutively. Thus a complex conjugate pair is given by

where

VSL VSR

SELECT

Optional (output) REAL or COMPLEX square array, shape (:,:) with size(VSL,l) — size(A,l). The left Schur vectors. Optional (output) REAL or COMPLEX square array, shape (:,:) with size(VSR,l) = size(A,l). The right Schur vectors. Optional (input) LOGICAL FUNCTION LOGICAL FUNCTION SELECT( alpha,, BETAj) ) type(wp), INTENT(IN) :: alpha,, BETAj where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) alphaj ::= ALPHARj, ALPHAIj | ALPHA,, 1. SELECT must be declared as EXTERNAL or as an explicit interface in the calling (sub)program.

183

LA.GGES

2. SELECT is called by LA_GGES for every computed eigenvalue (alpha-j. BETA,,) (but only once for a complex conjugate pair when A and B are real). It is used to select the eigenvalues that will be ordered to the top left of the Schur form. The eigenvalue (alphaj, BETA.,) is selected if SELECT(alphaj, BETAj) has the value .TRUE. 3. A selected complex eigenvalue may no longer satisfy SELECT(alphaj, BETAj) = .TRUE. after ordering, since ordering may change the value of complex eigenvalues (especially if the eigenvalue is ill-conditioned); in this case INFO is set to size(A, 1) + 2 (see INFO below). Note: Select must be present if SDIM is desired. SDIM

INFO

Optional (output) INTEGER. The number of eigenvalues (after sorting) for which SELECT = .TRUE. (If A and B are real, then complex conjugate pairs for which SELECT = .TRUE, for either eigenvalue count as 2). Optional (output) INTEGER. = 0: successful exit. th < 0: if INFO = —i, the i argument had an illegal value. > 0: if INFO = i, and i is < n: the QZ iteration failed. The matrix pair (A, B) has not been reduced to Schur form, but (alphaj. BETA.,-) should be correct for j = INFO + 1,... , n. — n+1: another part of the algorithm failed. = n+2: after reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the Schur form no longer satisfy SELECT = .TRUE. This can be caused by ordinary roundoff or underflow due to scaling. = n+3: the reordering failed. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20]. Examples The results below are computed with

Example 1 (from Program LA_GGES_EXAMPLE)

Arrays A and B on entry:

184

Generalized Nonsymmetric Eigenvalue Problems

The call: CALL LA_GGES( A, B, ALPHAR, ALPHAI, BETA) A, B, ALPHAR, ALPHAI and BETA on exit:

A

B

ALPHAR ALPHAI BETA The block upper triangular matrix S is:

The upper triangular matrix T is:

The generalized eigenvalues are:

185

LA_GGES Example 2 (from Program LA_GGESJEXAMPLE) Matrices A and B as in Example 1. Function SELECT is: LOGICAL FUNCTION SELECT( ALPHAR, ALPHAI, BETA ) USE LA_PRECISION, ONLY: WP => wp REAL(WP), INTENT(IN) :: ALPHAR, ALPHAI, BETA INTRINSIC EPSILON, ABS IF ( ABS(BETA) > EPSILON(1.0_WP) ) THEN IF ( ABS(ALPHAI/BETA) < 3.0_WP) THEN SELECT = .TRUE. ELSE SELECT = .FALSE.

END IF

ELSE SELECT = .FALSE.

END IF

END FUNCTION SELECT The call:

CALL LA_GGES( A, B, ALPHAR, ALPHAI, BETA, VSL, VSR, & SELECT, SDIM, INFO ) A, B, ALPHAR, ALPHAI, BETA, VSL, VSR, SDIM and INFO on exit:

A

B

ALPHAR ALPHAI BETA

186

Generalized Nonsymmetric Eigenvalue Problems VSL

VSR

SDIM = 3 INFO = 0 The block upper triangular matrix S is:

The upper triangular matrix T is:

T—

The left Schur vectors are:

The right Schur vectors are:

The selected eigenvalues are:

LA_GGESX

187

8.2.2 LA_GGESX SUBROUTINE LA_GGESX( A, B, alpha, BETA, VSL=vsl, & VSR=vsr, SELECT=select, SDIM=sdim, & RCONDE=rconde, RCONDV=rcondv, INFO=info ) type(wp), INTENT(INOUT) :: A(:,:), B(:,:) type(wp), INTENT(OUT) :: alpha(:), BETA(:) type(wp), INTENT(OUT), OPTIONAL :: VSL(:,:), VSR(:,:) INTERFACE LOGICAL FUNCTION SELECT(alpha^ BETA^) type(wp), INTENT(IN) :: alphaj, BETAj END FUNCTION SELECT END INTERFACE OPTIONAL :: SELECT INTEGER, INTENT(OUT), OPTIONAL :: SDIM REAL(wp), INTENT(OUT), OPTIONAL :: RCONDE(2), RCONDV(2) INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) alpha ::= ALPHAR, ALPHAI | ALPHA alpha(:) ::= ALPHAR(:), ALPHAI(r) | ALPHA(:) alpha, ::= ALPHAR^, ALPHAR | ALPHA,

Purpose LA_GGESX computes for a pair of n x n real or complex matrices (A, B) the (generalized) real or complex Schur form, the generalized eigenvalues in the form of scalar pairs (a./3), and, optionally, the left and/or right Schur vectors. If A and B are real then the real-Schur form is computed, otherwise the complex-Schur form is computed. The real-Schur form is a pair of real matrices (S, T) such that 1) S has block upper triangular form, with 1 x 1 and 2 x 2 blocks along the main diagonal, 2) T has upper triangular form with nonnegative elements on the main diagonal, and 3) S — QTAZ and T = QTBZ, where Q and Z are orthogonal matrices. The 2 x 2 blocks of S are "standardized" by making the corresponding elements of T have the form

The complex-Schur form is a pair of matrices (5, T) such that 1) 5 has upper triangular form, 2) T has upper triangular form with nonnegative elements on the main diagonal, and 3) S = QHAZ and T = QHBZ, where Q and Z are unitary matrices. In both cases the columns of Q and Z are called, respectively, the left and right Schur vectors. A generalized eigenvalue of the pair (A, B) is, roughly speaking, a scalar of the form A = a//3 such that the matrix A — \B is singular. It is usually represented as the pair (a,/3), as there is a reasonable interpretation of the case fi = 0 (even if a = 0) LA-GGESX also computes two reciprocal condition numbers for the average of the selected eigenvalues and reciprocal condition numbers for the right and left deflating subspaces corresponding to the selected eigenvalues.

188

Generalized Nonsymmetric Eigenvalue Problems

Arguments A

B alpha

BETA

(input/output) REAL or COMPLEX square array, shape (:,:). On entry, the matrix A. On exit, the matrix 5. (input/output) REAL or COMPLEX square array, shape (:,:) with size(B, 1) = size(A, I). On entry, the matrix B. On exit, the matrix T. (output) REAL or COMPLEX array, shape (:) with size(alpha) = size(A, I). The values of a. alpha(:) ::= ALPHAR(:), ALPHAI(r) | ALPHA(:), where ALPHAR(r), ALPHAI(r) are of REAL type (for the real and imaginary parts) and ALPHA(:) is of COMPLEX type. (output) REAL or COMPLEX array, shape (:) with size(BETA) = size(A, I). The values of 0. Note: The generalized eigenvalues of the pair (A, B) are the scalars \j = otj/Pj. These quotients may easily over- or underflow, and fa may even be zero. Thus, the user should avoid computing them naively. Note: If A and B are real then complex eigenvalues occur in complex conjugate pairs. Each pair is stored consecutively. Thus a complex conjugate pair is given by

where VSL VSR

SELECT

Optional (output) REAL or COMPLEX square array, shape (:,:) with size(VSL,l) — size(A,l). The left Schur vectors. Optional (output) REAL or COMPLEX square array, shape (:,:) with szze(VSR,l) = size(A,l). The right Schur vectors. Optional (input) LOGICAL FUNCTION LOGICAL FUNCTION SELECT( alphaj, BETA,, ) type(wp), INTENT (IN) :: alpha,, BETA, where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) alphaj ::= ALPHAR,, ALPHAI, | ALPHA., 1. SELECT must be declared as EXTERNAL or as an explicit interface in the calling (sub) program. 2. S.ELECT is called by LA.GGES for every computed eigenvalue (alphaj, BETA.,-) (but only once for a complex conjugate pair when A and B are real). It is used to select the eigenvalues that will be ordered to the top left of the Schur form. The eigenvalue (alphaj, BETA,-) is selected if SELECT (alphaj, BETA.,-) has the value .TRUE. 3. A selected complex eigenvalue may no longer satisfy SELECT(alphaj, BETA,-) = .TRUE. after ordering, since ordering may change the value of complex eigenvalues (especially if the eigenvalue is ill-conditioned); in this case INFO is set to size(A, 1) + 2 (see INFO below).

LA_GGESX

189

Note: Select must be present if SDIM, RCONDE and RCONDF are desired. SDIM Optional (output] INTEGER. The number of eigenvalues (after sorting) for which SELECT = .TRUE. (If A and B are real, complex conjugate pairs for which SELECT = .TRUE, for either eigenvalue count as 2). RCONDE Optional (output) REAL array, shape (:) with size(RCONDE) = 2. The reciprocal condition numbers for the average of the selected eigenvalues. RCONDV Optional (output) REAL array, shape (:) with size(RCONDV) = 2. The reciprocal condition numbers for the left and right deflating subspaces corresponding to the selected eigenvalues. INFO Optional (output) INTEGER. — 0: successful exit. < 0: if INFO = — i, the ith argument had an illegal value. > 0: if INFO = i, and i is < n: The QZ iteration failed. (A,B) has not been reduced to Schur form, but (alpha^ BETAj) should be correct for j = INFO + 1 , . . . , n. — n+1: Another part of the algorithm failed. = n+2: after reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the Schur form no longer satisfy SELECT = .TRUE. This can be caused by ordinary roundoff or underflow due to scaling. = n+3: the reordering failed. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20, 21]. Example (from Program LA_GGESX_EXAMPLE) The results below are computed with e ~ 1.19209 x 10~7. Matrices A and B are the same as in Example 1 for LA_GGES. Logical function SELECT is the same as in Example 2 for LA_GGES. The call: CALL LA_GGESX( A, B, ALPHAR, ALPHAI, BETA, SELECT=SELECT, & RCONDE=RCONDE, RCONDV=RCONDV ) RCONDE and RCONDV on exit:

RCONDE The reciprocal condition numbers for the average of the eigenvalues are: The reciprocal condition numbers for the deflating subspace are:

RCONDV

190

Generalized Nonsymmetric Eigenvalue Problems

8.2.3 LA_GGEV SUBROUTINE LA_GGEV( A, B, alpha, BETA, VL=vl, &

VR=vr, INFO=info )

type(wp), INTENT(INOUT) :: A(:,:), B(:,:) type(wp), INTENT(OUT) :: alpha(:), BETA(:) type(wp), INTENT(OUT), OPTIONAL :: VL(:,:), VR(:,:) INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) alpha ::= ALPHAR, ALPHAI | ALPHA alpha(:) ::= ALPHAR(:), ALPHAI(:) | ALPHA(:)

Purpose LA_GGEV computes for a pair of n x n real or complex matrices (A, B) the generalized eigenvalues in the form of scalar pairs (a, /3) and, optionally, the left and/or right generalized eigenvectors. A generalized eigenvalue of the pair (A, B) is, roughly speaking, a scalar of the form A = a//? such that the matrix A — \B is singular. It is usually represented as the pair («,/?), as there is a reasonable interpretation of the case 0 = 0 (even if a = 0). A right generalized eigenvector corresponding to a generalized eigenvalue A is a vector v such that (A — A B} v = 0 . A left generalized eigenvector is a vector u such that UH (A — A B) = 0, where UH is the conjugate-transpose of u. The computation is based on the (generalized) real or complex Schur form of (A, B). (See LA_GGES for details of this form.)

Arguments A

(input/output) REAL or COMPLEX square array, shape (:,:). On entry, the matrix A. On exit, A has been destroyed.

B

(input/output) REAL or COMPLEX square array, shape (:,:) with size(B,l) = size(A,l). On entry, the matrix B. On exit, B has been destroyed.

alpha

(output) REAL or COMPLEX array, shape (:) with size(alpha) = size(A,l). The values of a. alpha(:) ::= ALPHAR(:), ALPHAI(:) | ALPHA(:), where ALPHAR(r), ALPHAI(:) are of REAL type (for the real and imaginary parts) and ALPHA (:) is of COMPLEX type.

BETA

(output) REAL or COMPLEX array, shape (:) with size(BETA) = size(A,l). The values of /?. Note: The generalized eigenvalues of the pair (A, B) are the scalars Xj = ctj//3j. These quotients may easily over- or underflow, and /3j may even be zero. Thus, the user should avoid computing them naively. Note: If A and B are real then complex eigenvalues occur in complex conjugate pairs. Each

191

LA.GGEV pair is stored consecutively. Thus a complex conjugate pair is given by

where VL

Optional (output) REAL or COMPLEX square array, shape (:,:) with size(VL,l) — size(A,l). The left generalized eigenvectors Uj are stored in the columns of VL in the order of their eigenvalues. Each eigenvector is scaled so the largest component has | realpart \ + \ imag.part |= 1. except that for eigenvalues with a — /3 = 0, a zero vector is returned as the corresponding eigenvector. Note: If A and B are real then complex eigenvectors, like their eigenvalues, occur in complex conjugate pairs. The real and imaginary parts of the first eigenvector of the pair are stored in VL : j and VL^j+i- Thus a complex conjugate pair is given by

VR

Optional (output) REAL or COMPLEX square array, shape (:,:) with size(VR,l) = size(A.l). The right generalized eigenvectors Vj are stored in the columns of VR in the order of their eigenvalues. Each eigenvector is scaled so the largest component has | realpart \ + \ imag.part 1=1, except that for eigenvalues with a = [3 — 0. a zero vector is returned as the corresponding eigenvector. Note: If A and B are real then complex eigenvectors, like their eigenvalues, occur in complex conjugate pairs. The real and imaginary parts of the first eigenvector of the pair are stored in VR:J and VR :j+ i. Thus a complex conjugate pair is given by

INFO

Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = —i, the ith argument had an illegal value. > 0: if INFO = i, and i is < n: The QZ iteration failed. No eigenvectors have been calculated, but (alphaj, BETAj) should be correct for j = INFO + 1 , . . . , n. = n+1: another part of the algorithm failed. = n+2: a failure occurred during the computation of the generalized eigenvectors. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20]. Examples The results below are computed with e = 1.1921 x 10~7.

Example 1 (from Program LA_GGEV_EXAMPLE) Matrices A and B as in Example 1 for LA_GGES

192

Generalized Nonsymmetric Eigenvalue Problems

The call:

CALL LA_GGEV( A, B, VL=VL, VR=VR )

VL and VR on exit:

VL

VR

The eigenvalues of Az = XBz are given in example 1 for LA_GGES. The corresponding (generalized) left eigenvectors are:

The corresponding (generalized) right eigenvectors are:

Example 2 (from Program LA_GGEV_EXAMPLE)

193

LA_GGEV Arrays Aand B on entry: A

B

The call: CALL LA_GGEV( A, B, ALPHA, BETA, VL, VR, INFO ) ALPHA, BETA, INFO, VL and VR on exit: BETA

ALPHA

INFO = 0

VL

VR

194 The eigenvalues of the problem Az = \Bz are:

The left generalized eigenvectors are:

The right generalized eigenvectors are:

Generalized Nonsymmetric Eigenvalue Problems

LA_GGEVX

8.2.4

195

LA_GGEVX

SUBROUTINE LA_GGEVX( A, B, alpha, BETA, VL=vl, & VR=vr, BALANC=balanc, ILO=ilo, IHI=ihi, & LSCALE=lscale, RSCALE=rscale, ABNRM=abnrm, & BBNRM=bbnrm, RCONDE=rconde, RCONDV=rcondv, & INFO=info ) type(wp), INTENT(INOUT) :: A(:,:), B(:,:) type(wp), INTENT(OUT) :: alpha(:), BETA(:) type(wp), INTENT(OUT), OPTIONAL :: VL(:,:), VR(:,:) CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: BALANC INTEGER, INTENT(OUT), OPTIONAL :: ILO, IHI REAL(u;p), INTENT(OUT), OPTIONAL :: LSCALE(:), RSCALE(:), RCONDE(:), RCONDV(:) REAL(u;p), INTENT(OUT), OPTIONAL :: ABNRM, BBNRM INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) alpha ::= ALPHAR, ALPHAI | ALPHA alpha(:) ::= ALPHAR(:), ALPHAI(:) | ALPHA(:)

Purpose LA-GGEVX computes for a pair of n x n real or complex matrices (A, B) the generalized eigenvalues in the form of scalar pairs (a, /3) and, optionally, the left and/or right generalized eigenvectors. A generalized eigenvalue of the pair (A, B) is, roughly speaking, a scalar of the form A = a//3 such that the matrix A — \B is singular. It is usually represented as the pair (a,/?), as there is a reasonable interpretation of the case /3 = 0 (even if a = 0). A right generalized eigenvector corresponding to a generalized eigenvalue A is a vector v such that (A — \B)v = 0. A left generalized eigenvector is a vector u such that UH (A — XB) — 0. where UH is the conjugate-transpose of u. The computation is based on the (generalized) real or complex Schur form of (A. B). (See LA-GGES for details of this form.) Optionally. LA_GGEVX also computes a balancing transformation (to improve the conditioning of the eigenvalues and eigenvectors), reciprocal condition numbers for the eigenvalues, and reciprocal condition numbers for the right eigenvectors. The balancing transformation consists of a permutation of rows and columns and/or a scaling of rows and columns.

Arguments A

B

(input/output) REAL or COMPLEX square array, shape (:,:). On entry, the matrix A. On exit, A has been overwritten. If the left, the right or both generalized eigenvectors are computed, then A contains the first part of the real/complex Schur form of the "balanced" versions of the matrix pair (A, B). (input/output) REAL or COMPLEX square array, shape (:,:) with size(B, 1) = size(A, I). On entry, the matrix B. On exit. B has been overwritten. If the left, the right or both generalized eigenvectors are computed, then B contains the second part of the real/complex Schur form of the "balanced" versions of the matrix pair (A, B).

196

Generalized Nonsymmetric Eigenvalue Problems

alpha

(output) REAL or COMPLEX array, shape (:) with size(alpha) = size(A, 1). The values of a. alpha(:) ::= ALPHAR(:), ALPHAI(r) | ALPHA(:), where ALPHAR(:), ALPHAI(:) are of REAL type (for the real and imaginary parts) and ALPHA^) is of COMPLEX type.

BETA

(output) REAL or COMPLEX array, shape (:) with size(BETA) = size(A,l). The values of fi. Note: The generalized eigenvalues of the pair (A, B) are the scalars \j — ctj//3j. These quotients may easily over- or underflow, and /3j may even be zero. Thus, the user should avoid computing them naively. Note: If A and B are real then complex eigenvalues occur in complex conjugate pairs. Each pair is stored consecutively. Thus a complex conjugate pair is given by

where

VL

Optional (output) REAL or COMPLEX square array, shape (:,:) with s«ze(VL, 1) = size(A, 1). The left generalized eigenvectors Uj are stored in the columns of VL in the order of their eigenvalues. Each eigenvector is scaled so the largest component has | realpart \ + \ imag.part \= 1, except that for eigenvalues with a = (3 = 0, a zero vector is returned as the corresponding eigenvector. Note: If A and B are real then complex eigenvectors, like their eigenvalues, occur in complex conjugate pairs. The real and imaginary parts of the first eigenvector of the pair are stored in VL:;j and VL :j j +1 . Thus a complex conjugate pair is given by

VR

Optional (output) REAL or COMPLEX square array, shape (:.:) with size(VR, 1) = size(A, 1). The right generalized eigenvectors Vj tire stored in the columns of VR in the order of their eigenvalues. Each eigenvector is scaled so the largest component has | realpart \ + \ imag.part \= 1, except that for eigenvalues with a = /3 = 0, a zero vector is returned as the corresponding eigenvector. Note: If A and B are real then complex eigenvectors, like their eigenvalues, occur in complex conjugate pairs. The real and imaginary parts of the first eigenvector of the pair are stored in VR:j and VR:)j+i. Thus a complex conjugate pair is given by

BALANC Optional (input) CHARACTER(LEN=1). Specifies the balance option to be performed. = 'N': do not permute or scale; = 'P': permute only; = 'S': scale only; == 'B': both permute and scale.

LA_GGEVX

197

Default value: 'N'. Note: Computed reciprocal condition numbers will be for the matrices after balancing. Permuting does not change condition numbers (in exact arithmetic), but scaling does. ILO,IHI

Optional (output) INTEGER. ILO and IHI are integer values such that on exit AM = 0 and BJJ = 0 if i > j and j — l , . . . , I L O - l o r i = IHI + l , . . . , n . If BALANC = 'N' or 'S', then ILO = 1 and IHI = n.

LSCALE

Optional (output) REAL array, shape (:) with size(LSCALE) = szze(A,l). Details of the permutations and scaling factors applied to the left side of A and B. If PLj is the index of the row interchanged with row j, arid DLj is the scaling factor applied to row j. then and

RSCALE

Optional (output) REAL array, shape (:). size(RSCALE) = size(A, 1). Details of the permutations and scaling factors applied to the right side of A and B. If PRj is the index of the column interchanged with column j, and DRj is the scaling factor applied to column j, then

and

ABNRM

Optional (output) REAL. The /x norm of A after balancing.

BBNRM

Optional (output) REAL. The /i norm of B after balancing.

RCONDE Optional (output) REAL array, shape (:) with size(RCONDE) = size(A, I). The reciprocal condition numbers of the eigenvalues. RCONDV Optional (output) REAL array, shape (:) with size(RCONDE) = size(A, 1). The estimated reciprocal condition numbers of the right eigenvectors. If the eigenvalues cannot be reordered to compute RCONDVj then RCONDVj is set to 0. This can only occur when the true value would be very small. INFO Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = —i, the ith argument had an illegal value. > 0: if INFO = i, and i is < n: The QZ iteration failed. No eigenvectors have been calculated, but (alphaj, BETAj) should be correct for j = INFO 4 - 1 , . . . , n. = n+1: another part of the algorithm failed. = n+2: a failure occurred during the computation of the generalized eigenvectors. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1] and [17, 9, 20, 21].

198

Generalized Nonsymmetric Eigenvalue Problems

Example (from Program LA.GGEVXJEXAMPLE) The results below are computed with e = 1.19209 x 10 -7

Arrays A and B on entry:

A

B

The call: CALL LA_GGEVX( A, B, ALPHA, BETA, BALANCE'S', LSCALE=LSCALE, & RSCALE^RSCALE, ABNRM=ABNRM, & BBNRM=BBNRM, RCONDE=RCONDE, & RCONDV=RCONDV )

LSCALE, RSC ALE, ABNRM, BBNRM, RCONDE, RCONDV, ALPHA, BETA and LAMBDA on exit:

LSCALE

RSCALE

RCONDE

RCONDV

ALPHA

LA_GGEVX

199 BETA LAMBDA

Balancing was not needed. The /! norm of A is 2.76734 x 101 and the /i norm of B is 3.61864 x 101. The reciprocal condition numbers of the eigenvalues are: ( 2.12830 1.84798 8.09452 5.56294 4.77657 ) The reciprocal condition numbers of the eigenvectors are: ( 2.29658 1.83061 2.67197 1.45866 1.61397 )

This page intentionally left blank

Chapter 9

Driver Routines for Singular Value Problems 9.1

Standard Singular Value Problems

9.1.1

LA.GESVD / LA_GESDD

SUBROUTINE LA_GESVD / LA_GESDD( A, S, U=u, VT=vt, & WW=ww, JOB=job, INFO=info ) type(wp), INTENT(INOUT) :: A(:,:) REAL(wp), INTENT(OUT) :: S(:) type(wp), INTENT(OUT), OPTIONAL :: U(:,:), VT(:,:) H'EAL(wp), INTENT(OUT), OPTIONAL :: WW(:) CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: JOB INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

Purpose LA_GESVD and LA_GESDD compute the singular values and, optionally, the left and/or right singular vectors from the singular value decomposition (SVD) of a real or complex m x n matrix A. The SVD of A is written where S is an m x n matrix which is zero except for its min(m, n) diagonal elements, U is an m x m orthogonal (unitary) matrix, and V is an n x n orthogonal (unitary) matrix. The diagonal elements of £, i.e., the values

are the singular values of A; they are real and non-negative, and are returned in descending order. The first min(m, n) columns of U and V are the left and right singular vectors of A, respectively. LA_GESDD solves the same problem as LA.GESVD but uses a divide and conquer method if singular 201

202

Standard Singular Value Problems

vectors are desired. For large matrices it is usually much faster than LA_GESVD when singular vectors are desired, but uses more workspace. Note: The routine returns VH, not V.

Arguments A

(input/output] REAL or COMPLEX array, shape (:,:) with size(A., 1) = m and size(A, 2) =

n.

On entry, the matrix A. On exit, if JOB = 'U' and U is not present, then A is overwritten with the first min(m,n) columns of U (the left singular vectors, stored columnwise). If JOB = 'V and VT is not present, then A is overwritten with the first min(m,n) rows of VH (the right singular vectors, stored rowwise). In all cases the original contents of A are destroyed. S

(output] REAL array, shape (:) with size(S) = min(m,n). The singular values of A, sorted so that Sj > Sj+i.

U

Optional (output) REAL or COMPLEX array, shape (:,:) with size(U, I) — m and size(U, 2) = m or min(m, n). If size(U, 2) = m, U contains the m x ra matrix U. If size(U, 2) = min(m, n), U contains the first min(m, n) columns of U (the left singular vectors, stored columnwise).

VT

Optional (output) REAL or COMPLEX array, shape (:,:) with size(VT, 1) = n or min(m, n) and size(VT, 2) = n. If size(VT, 1) — n , VT contains the n x n matrix VH. If size(VT, 1) = min(m,77), VT contains the first min(ra,n) rows of VH (the right singular vectors, stored rowwise).

WW

Optional (output) REAL array, shape (:) with size(WW) = min(m,n) — 1 If INFO > 0, WW contains the unconverged superdiagonal elements of an upper bidiagonal matrix B whose diagonal is in £ (not necessarily sorted). B has the same singular values as A. Note: WW is a dummy argument for LA_GESDD.

JOB

Optional (input) CHARACTER(LEN=1). - 'N': neither columns of U nor rows of VH are returned in array A. — 'U': if U is not present, the first min(ra,n) columns of U (the left singular vectors) are returned in array A; = 'V: if VT is not present, the first min(m, n) rows of VH (the right singular vectors) are returned in array A; Default value: 'N'.

INFO

Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = —z, the ith argument had an illegal value. > 0: The algorithm did not converge. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [1, pages 20, 46, 66, 67, 94, 111, 113, 147, 158, 159, 188, 236, 238,] and [17, 9, 20].

203

LA.GESVD / LA^GESDD

Examples The results below are computed with e — 1.19209 x 10~7. Example 1 (from Program LA_GESVD.EXAMPLE)

Array A on entry:

The call: CALL LA.GESVD ( A, S ) S on exit:

A

S

The singular values of matrix A are:

Example 2 (from Program LA_GESVD .EXAMPLE) Matrix A as in Example 1. The call: CALL LA_GESVD( A, S, VT=VT, WW=WW, JOB='U', INFO=INFO ) S on exit: as in Example 1. A, VT, WW, and INFO on exit: A

VT

Generalized Singular Value Problems

204

WW 0.00000 0.00000

INFO = 0

The singular values of A are the same as in Example 1. The left singular vectors of A are:

The right singular vectors of A are (columnwise):

9.2

Generalized Singular Value Problems

9.2.1 LA_GGSVD SUBROUTINE LA_GGSVD( A, B, ALPHA, BETA, K=k, L=l, & U=u, V=v, Q=q, IWORK=iwork, INFO=info ) type(wp), INTENT(INOUT) :: A(:,:), B(:,:) REAL(u;p), INTENT(OUT) :: ALPHA(:), BETA(:) INTEGER, INTENT(OUT), OPTIONAL :: K, L type(wp), INTENT(OUT), OPTIONAL :: U(:,:), V(:,:), Q(:,:) INTEGER, INTENT(IN), OPTIONAL :: IWORK(:) INTEGER, INTENT(OUT), OPTIONAL :: INFO where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

Purpose LA.GGSVD computes the generalized singular values and, optionally, the transformation matrices from the generalized singular value decomposition (GSVD) of a real or complex matrix pair (A, B}, where A is m x n and B is p x n. The GSVD of (A, B) is written

where U, V and Q are orthogonal (unitary) matrices of dimensions m x m, pxp and n x n, respectively. Let A I be the rank of B and r the rank of the (m+p) xn matrix , and let k = r — 1. Then EI and £2 are B m x (k + I) and p x (k + I) "diagonal" matrices, respectively, and R is a (k + I) x (k + /) nonsingular upper triangular matrix. The detailed structure of EI , E2 and R depends on the sign of (m — k — I) as follows:

LA_GGSVD

205

The case m - k - I > 0:

where C2 + S'2 — I. We define

The case m — k — I < 0:

where C'2 + S'2 = I. We define

In both cases the generalized singular values of the pair (A, B) are the ratios

The first k singular values are infinite. The finite singular values are real and nonnegative. LA-GGSVD computes the real (nonnegative) scalars a*,/^, i = 1 , 2 , . . . , k + /, the matrix R, and, optionally, the transformation matrices (7, V and Q. Note: Some important special cases of the GSVD are given in Section 2.2.5.3.

Generalized Singular Value Problems

206

Arguments A

(input/output) REAL or COMPLEX array, shape (:,:) with size(A, 1) = ra and size(A, 2) = n. On entry, the matrix A. On exit, A contains the triangular matrix J?, or part of R, as follows: If m — k — I > 0, then R is stored in Ai : fc + / 5n _fc_/ + i :n . If m — k — I < 0, then the matrix

is stored in B

(input/output] REAL or COMPLEX array, shape (:,:) with size(B, 1) = p and size(B, 2) = n. On entry, the matrix B. On exit, if m — k — / < 0, then #33 is stored in

ALPHA

(output) REAL array, shape (:) with size(ALPHA) = n The real scalars QJ, i = 1,2,..., k + I.

BETA

(output) REAL array, shape (:) with size(BETA) = n. The real scalars /?,, i = 1,2,..., k + I. Note: The generalized singular values of the pair (A, B) are

K, L

then ALPHAfc Optional (output) INTEGER. The dimension parameters k and /.

U

Optional (output) REAL or COMPLEX square array, shape (:,:) with size(U,l) = m. The matrix U.

V

Optional (output) REAL or COMPLEX square array, shape (:,:) with size(V,l) = p. The matrix V.

Q

Optional (output] REAL or COMPLEX square array, shape (:,:) with size(Q,I) — n. The matrix Q.

IWORK

Optional (output) INTEGER array, shape(:) with size(IWORK) = n. I WORK contains sorting information. More precisely, the loop for i = k + 1, min(m, k + /) swap ALPHAj and ALPHAiwoRK^ end will sort ALPHA so that ALPHAi > ALPHA2 > . . . > ALPHAn.

INFO

Optional (output) INTEGER. = 0: successful exit. < 0: if INFO = —i, the ith argument had an illegal value. > 0: if INFO = 1, the algorithm failed to converge. If INFO is not present and an error occurs, then the program is terminated with an error message.

References: [l] and [17, 9, 20].

207

LA_GGSVD

Examples The results below are computed with e = 1.19209 x 10~7. Example 1 (from Program LA.GGSVDJEXAMPLE)

Arrays A and B on entry: A B

The call: CALL LA_GGSVD( A, B, ALPHA, BETA, K, L ) A, ALPHA, BETA, K and L on exit: A

ALPHA

BETA

The generalized singular values of (A, B) and the matrix R:

Example 2 (from Program LA_GGSVD_EXAMPLE) Arrays A and B on entry: As in Example 1.

208

Generalized Singular Value Problems

The call: CALL LA_GGSVD( A, B, ALPHA, BETA, K, L, U, V, Q, INFO=INFO ) A, ALPHA, BETA, K and L on exit: As in Example 1. U, V, Q and INFO on exit:

U

U continued

U continued

V

Q

Q continued INFO = 0

The generalized singular values of (^4, B) are as in Example 1. Matrices C7, V and Q are:

LA_GGSVD

209

This page intentionally left blank

Part III

COMPUTATIONAL ROUTINES

This page intentionally left blank

Chapter 10

Computational Routines 10.1

Computational Routines for Linear Equations

using the LU factorization computed by LA_GETRF. References: See [1] and [9, 20].

LA_GECON

10.1.1 General Linear Systems

Real version.

LA_GETRF

SUBROUTINE LA_GECON( NORM, N, A, & LDA, ANORM, RCOND, WORK, & I WORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: & NORM INTEGER, INTENT(IN) :: LDA, N INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT (IN) :: ANORM REAL(wp), INTENT(OUT) :: RCOND INTEGER, INTENT(OUT) :: IWORK( * ) REAL(wp), INTENT(IN) :: A( LDA, * ) REAL(wp), INTENT (OUT) :: WORK( * ) where wp ::= KIND(l.O) | KIND(l.ODO) Complex version.

Real and complex versions. SUBROUTINE LA_GETRF( M, N, A, LDA, & IPIV, INFO ) INTEGER, INTENT(IN) :: LDA, M, N INTEGER, INTENT(OUT) :: INFO INTEGER, INTENT( OUT ) :: IPIV( * ) type(wp), INTENT( INOUT ) :: A( LDA, * ) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA_GETRF computes an LU factorization of a general mxn real / complex matrix A using partial pivoting with row interchanges. References: See [1] and [9, 20].

LA_GETRS

Real and complex versions. SUBROUTINE LA_GETRS( TRANS, N, NRHS, & A, LDA, IPIV, B, LDB, INFO ) CHARACTER(LEN=1), INTENT(IN) :: TRANS INTEGER, INTENT(IN) :: LDA, LDB, NRHS, N INTEGER, INTENT(OUT) :: INFO INTEGER, INTENT(IN) :: IPIV(*) type(wp), INTENT(IN) :: A(LDA,*) type(wp), INTENT (INOUT) :: rhs where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) LA_GETRS solves a system of linear equations AX = B or ATX — B with a general n x n real / complex matrix A

SUBROUTINE LA_GECON( NORM, N, A, & LDA, ANORM, RCOND, WORK, & RWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: & NORM INTEGER, INTENT(IN) :: LDA, N INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT (IN) :: ANORM REAL(wp), INTENT (OUT) :: RCOND, & RWORK (*) COMPLEX(wp), INTENT(IN) :: A( LDA, * ) COMPLEX(wp), INTENT(OUT) :: WORK( * ) where wp ::= KIND(l.O) | KIND(l.ODO) LA_GECON estimates the reciprocal of the condition number of a general real / complex matrix A, using the LU factorization computed by LA_GETRF. References: See [1] and [9, 20, 21].

213

Computational Routines

214

LA_GERFS

Real version.

SUBROUTINE LA_GERFS( TRANS, N, NRHS, & A, LDA, AF, LDAF, IPIV, B, LDB, X, LDX, & FERR, BERR, WORK, IWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: & TRANS INTEGER, INTENT(IN) :: LDA, LDAF, LDB, & LDX, NRHS, N INTEGER, INTENT(OUT) :: INFO INTEGER, INTENT(IN) :: IPIV(*) INTEGER, INTENT(OUT) :: IWORK(*) REAL(iup), INTENT(OUT) :: err REAL(wp), INTENT(OUT) :: WORK(*) REAL(wp), INTENT(IN) :: A(LDA,*), & AF(LDAF,*), rhs REAL(wp), INTENT (INOUT) :: sol where wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) sol ::= X(LDX,*) | X(*) err ::= FERR(*), BERR(*) | FERR, BERR Complex version. SUBROUTINE LA_GERFS( TRANS, N, NRHS, & A, LDA, AF, LDAF, IPIV, B, LDB, X, LDX, & FERR, BERR, WORK, RWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: & TRANS INTEGER, INTENT(IN) :: LDA, LDAF, LDB, & LDX, NRHS, N INTEGER, INTENT(OUT) :: INFO INTEGER, INTENT(IN) :: IPIV(*) REAL(wp), INTENT(OUT) :: err, RWORK(*) COMPLEX (w/p), INTENT (OUT) :: WORK(*) COMPLEX (wp), INTENT(IN) :: A(LDA,*), & AF(LDAF,*), rhs COMPLEX(w;p), INTENT(INOUT) :: sol where wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) sol ::= X(LDX,*) | X(*) err ::= FERR(*), BERR(*) | FERR, BERR LA_GERFS improves the computed solution to a system of linear equations and provides error bounds and backward error estimates for the solution. References: See [1] and [9, 21, 20].

LA_GETRI

Real and complex versions.

SUBROUTINE LA_GETRI( N, A, LDA, IPIV, & WORK, LWORK, INFO ) INTEGER, INTENT(IN) :: LDA, LWORK, N INTEGER, INTENT(OUT) :: INFO INTEGER, INTENT(IN) :: IPIV(*) type(wp), INTENT(OUT) :: WORK(LWORK) type(wp), INTENT(INOUT) :: A(LDA,*) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

LA_GETRI computes the inverse of a matrix using the LU factorization computed by LA.GETRF. References: See [1] and [9, 20].

LA.GEEQU

Real and complex versions. SUBROUTINE LA_GEEQU( M, N, A, LDA, R, C, & ROWCND, COLCND, AMAX, INFO ) INTEGER, INTENT(IN) :: LDA, M, N INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT(OUT) :: AMAX, COLCND, & ROWCND type(wp), INTENT(IN) :: A( LDA, * ) REAL(wp), INTENT(OUT) :: C( * ), R( * ) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA_GEEQU computes row and column scalings intended to equilibrate an m x n general real / complex matrix A and reduce its condition number. References: See [1] and [9, 21, 20].

LA_GBTRF

Real and complex versions. SUBROUTINE LA_GBTRF( M, N, KL, KU, AB, & LDAB, IPIV, INFO ) INTEGER, INTENT(IN) :: KL, KU, LDAB, M, N INTEGER, INTENT (OUT) :: INFO INTEGER, INTENT(INOUT) :: IPIV(*) type(wp), INTENT(INOUT) :: AB(LDAB,*) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA_GBTRF computes an LU factorization of a real / complex mxn band matrix A using partial pivoting with row interchanges. References: See [l] and [9, 20].

LA_GBTRS

Real and complex versions.

SUBROUTINE LA_GBTRS( TRANS, N, KL, KU, & NRHS, AB, LDAB, IPIV, B, LDB, INFO ) CHARACTER(LEN=1), INTENT(IN) :: TRANS INTEGER, INTENT(IN) :: KL, KU, LDAB, LDB, & N, NRHS INTEGER, INTENT(OUT) :: INFO INTEGER, INTENT(IN) :: IPIV(*) type(wp), INTENT(IN) :: AB( LDAB,*)

type(wp), INTENT(INOUT) :: rhs where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

rhs ::= B(LDB,*) | B(*)

LA_GBTRS solves a system of linear equations AX = B or ATX — B with a general real / complex band matrix A using the LU factorization computed by LA_GBTRF. References: See [1] and [9, 20].

215

Computational Routines for Linear Equations

LA_GBCON

Complex version.

Real version.

SUBROUTINE LA_GBCON( NORM, N, KL, & KU, AB, LDAB, IPIV, ANORM, & RCOND, WORK, IWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: & NORM INTEGER, INTENT(IN) :: KL, KU, LDAB, N INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT (IN) :: ANORM REAL(wp), INTENT(OUT) :: RCOND

INTEGER, INTENT(IN) :: IPIV( * ) INTEGER, INTENT(OUT) :: IWORK( * ) REAL(MP), INTENT(IN) - AB( LDAB, * )

REAL(wp), INTENT(OUT) :: WORK( * ) where wp ::= KIND(l.O) | KIND(l.ODO) Complex version.

SUBROUTINE LA_GBCON( NORM, N, KL, & KU, AB, LDAB, IPIV, ANORM, & RCOND, WORK, RWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: & NORM INTEGER, INTENT(IN) :: KL, KU, LDAB, N INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT (IN) :: ANORM REAL(wp), INTENT(OUT) :: RCOND INTEGER, INTENT(IN) :: IPIV( * ) REAL(wp), INTENT(OUT) :: RWORK( * ) COMPLEX(wp), INTENT(IN) :: AB( LDAB, * ) COMPLEX(wp), INTENT(OUT) :: WORK( * ) where wp ::= KIND(l.O) | KIND(l.ODO) LA_GBCON estimates the reciprocal of the condition number of a real / complex band matrix A, using the LU factorization computed by LA.GBTRF. References: See [1] and [9, 21, 20].

LA_GBRFS

Real version.

SUBROUTINE LA_GBCON( TRANS, N, KL, KU, & NRHS, AB, LDAB, AFB, LDAFB, IPIV, B, & LDB, X, LDX, FERR, BERR, WORK, & IWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: TRANS INTEGER, INTENT(IN) :: KL, KU, LDAB, & LDAFB, LDB, LDX, N, NRHS INTEGER, INTENT(OUT) :: INFO INTEGER, INTENT(IN) :: IPIV(*) INTEGER, INTENT(OUT) :: IWORK(*) REAL(wp), INTENT(OUT) :: err REAL(wp), INTENT(IN) :: AB( LDAB,*), & AFB( LDAFB,*), rhs REAL(iyp), INTENT(OUT) :: WORK(*) REAL(wp), INTENT (INOUT) :: sol where wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) sol ::= X(LDX,*) | X(*j err ::= FERR(*), BERR(*) | FERR, BERR

SUBROUTINE LA_GBRFS( TRANS, N, KL, KU, & NRHS, AB, LDAB, AFB, LDAFB, IPIV, B, & LDB, X, LDX, FERR, BERR, WORK, & RWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: TRANS INTEGER, INTENT(IN) :: KL, KU, LDAB, & LDAFB, LDB, LDX, N, NRHS INTEGER, INTENT(OUT) :: INFO INTEGER, INTENT(IN) :: IPIV(*) REAL(iwp), INTENT(OUT) :: err, RWORK(*) COMPLEX(iwp), INTENT(IN) :: AB( LDAB,*), & AFB( LDAFB,*), rhs COMPLEX(wp), INTENT(OUT) :: WORK(*) COMPLEX(wp), INTENT(INOUT) :: sol where wp ::= KIND(1.0) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) sol ::= X(LDX,*) | X(*) err ::= FERR(*), BERR(*) | FERR, BERR LA_GBRFS improves the computed solution to a system of linear equations when the coefficient matrix is banded, and provides error bounds and backward error estimates for the solution. References: See [1] and [9, 21, 20].

LA_GBEQU

Real and complex versions. SUBROUTINE LA_GBEQU( M, N, KL, KU, AB, & LDAB, R, C, ROWCND, COLCND, AMAX, & INFO ) INTEGER, INTENT(IN) :: KL, KU, LDAB, & M, N INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT(OUT) :: AMAX, & COLCND, ROWCND REAL(u;p), INTENT(OUT) :: C(*), R(*) type(wp), INTENT(IN) :: AB( LDAB,*) where type ::= REAL | COMPLEX wp ::= KIND(l.O) j KIND(l.ODO) LA_GBEQU computes row and column scalings intended

to equilibrate an m x n real / complex band matrix A and reduce its condition number. References: See [1] and [9, 21, 20].

LA.GTTRF

Real and complex versions. SUBROUTINE LA_GTTRF( N, DL, D, DU, DU2, IPIV, INFO ) INTEGER, INTENT(IN) :: N INTEGER, INTENT(OUT) :: INFO INTEGER, INTENT(OUT) :: IPIV(*) type(wp), INTENT(INOUT) :: D(*), DL(*), DU(*) type(wp), INTENT(OUT) :: DU2(*) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

216 LAJ5GTTRF computes an LU factorization of a real / complex tridiagonal matrix A using elimination with partial pivoting and row interchanges. References: See [1] and [9, 20].

LA_GTTRS

Computational Routines LA-GTCON estimates the reciprocal of the condition number of a real / complex tridiagonal matrix A using the LU factorization as computed by LA-GTTRF. References: See [1] and [9, 21, 20].

LA_GTRFS

Real and complex versions.

Real version.

SUBROUTINE LA_GTTRS( TRANS, N, NRHS, & DL, D, DU, DU2, IPIV, B, LDB, INFO ) CHARACTER(LEN=1), INTENT(IN) :: & TRANS INTEGER, INTENT(IN) :: LDB, N, NRHS INTEGER, INTENT(OUT) :: INFO INTEGER, INTENT(IN) :: IPIV(*) type(wp), INTENT(IN) :: D(*), DL(*), DU(*), & DU2(*) type(wp), INTENT(INOUT) :: rhs where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) LA_GTTRS solves one of the systems of equations AX — B or ATX = B, with a tridiagonal real / complex matrix A using the LU factorization computed by LA_GTTRF. References: See [1] and [9, 20].

SUBROUTINE LA_GTRFS( TRANS, N, NRHS, & DL, D, DU, DLF, DF, DUF, DU2, IPIV, B, & LDB, X, LDX, FERR, BERR, WORK, & IWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: TRANS INTEGER, INTENT(IN) :: LDB, LDX, N, & NRHS, IPIV(*) INTEGER, INTENT(OUT) :: INFO, IWORK(*) REAL(wp), INTENT (OUT) :: err REALJwp), INTENT(IN) :: rhs, D(*), DF(*), DL(*), & DLF(*), DU(*), DU2(*), DUF(*) REAL(u;p), INTENT (INOUT) :: sol REAL(wp), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) rhs ::- B(LDB,*) | B(*) sol ::= X(LDX,*) | X(*) err ::= FERR(*), BERR(*) | FERR, BERR

LA_GTCON

Real version.

SUBROUTINE LA_GTCON( NORM, N, DL, & D, DU, DU2, IPIV, ANORM, RCOND, & WORK, IWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: & NORM INTEGER, INTENT(IN) :: N INTEGER, INTENT(OUT) :: INFO, IWORK(*) REAL(w;p), INTENT (IN) :: ANORM REAL(wp), INTENT (OUT) :: RCOND INTEGER, INTENT(IN) :: IPIV(*) REAL(wp), INTENT(IN) :: D(*), DL(*), & DU(*), DU2(*) REAL(i/;p), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) Complex version. SUBROUTINE LA_GTCON( NORM, N, DL, & D, DU, DU2, IPIV, ANORM, RCOND, & WORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: & NORM INTEGER, INTENT(IN) :: N INTEGER, INTENT(OUT) :: INFO REAL(u;p), INTENT (IN) :: ANORM REALJwp), INTENT(OUT) :: RCOND INTEGER, INTENT(IN) :: IPIV(*) COMPLEX(w;p), INTENT(IN) :: D(*), DL(*), & DU(*), DU2(*) COMPLEX(u/p), INTENT(OUT) :: WORK(*) where wp ::= KIND(1.0) | KIND(l.ODO)

Complex version. SUBROUTINE LA_GTRFS( TRANS, N, NRHS, & DL, D, DU, DLF, DF, DUF, DU2, IPIV, B, &: LDB, X, LDX, FERR, BERR, WORK, & RWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: & TRANS INTEGER, INTENT(IN) :: LDB, LDX, N, &: NRHS, IPIV(*) INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT(OUT) :: err, RWORK(*) COMPLEX(u;p), INTENT(IN) :: rhs, D(*), DF(*), DL(*), & DLF(*), DU(*), DU2(*), DUF(*) COMPLEX(wp), INTENT(INOUT) :: sol COMPLEX(wp), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) sol ::= X(LDX,*) | X(*) err ::= FERR(*), BERR(*) | FERR, BERR LA_GTRFS improves the computed solution to a system of linear equations when the coefficient matrix is tridiagonal, and provides error bounds and backward error estimates for the solution. References: See [1] and [9, 21, 20].

10.1.2

Symmetric/Hermitian Positive Definite Linear Systems

LAJPOTRF

Real and complex Hermitian versions.

Computational Routines for Linear Equations SUBROUTINE LA_POTRF( UPLO, N, A, LDA, & INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: LDA, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(INOUT) :: A(LDA,*) where type ::= REAL | COMPLEX wp ::- KIND(l.O) | KIND(l.ODO) LA_POTRF computes the Cholesky factorization of a real symmetric / complex Hermitian positive definite matrix A. References: See [1] and [9, 20].

LAJPOTRS

Real and complex Hermitian versions. SUBROUTINE LA_POTRS( UPLO, N, NRHS, & A, LDA, B, LDB, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: LDA, LDB, N, & NRHS INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(IN) :: A( LDA,*) type(wp), INTENT(INOUT) :: rhs where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) LA_POTRS solves a system of linear equations AX — B with a a real symmetric / complex Hermitian positive definite matrix A using the Cholesky factorization computed by LA_POTRF. References: See [1] and [9, 20].

LAJPOCON

Real version.

SUBROUTINE LA_POCON( UPLO, N, A, LDA, & ANORM, RCOND, WORK, IWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: & UPLO INTEGER, INTENT(IN) :: LDA, N INTEGER, INTENT(OUT) :: INFO REAL(iyp), INTENT (IN) :: ANORM REAL(wp), INTENT (OUT) :: RCOND INTEGER, INTENT(OUT) :: IWORK( * ) REAL(wp), INTENT (IN) :: A( LDA, * ) REAL(iop), INTENT(OUT) :: WORK( * ) where wp ::= KIND(l.O) | KIND(l.ODO) Complex Hermitian version. SUBROUTINE LAJPOCON( UPLO, N, A, LDA, & ANORM, RCOND, WORK, RWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: & UPLO INTEGER, INTENT(IN) :: LDA, N INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT (IN) :: ANORM REAL(wp), INTENT(OUT) :: RCOND, & RWORK (*)

217 COMPLEX(iup), INTENT(IN) :: A( LDA, * ) COMPLEX(iyp), INTENT(OUT) :: WORK( * ) where wp ::= KIND(l.O) | KIND(l.ODO) LA_POCON estimates the reciprocal of the condition number of a real symmetric / complex Hermitian positive definite matrix using the Cholesky factorization computed by POTRF. References: See [1] and [9, 21, 20].

LA_PORFS

Real version.

SUBROUTINE LA_PORFS( UPLO, N, NRHS, & A, LDA, AF, LDAF, B, LDB, X, LDX, & FERR, BERR, WORK, IWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: & UPLO INTEGER, INTENT(IN) :: LDA, LDAF, & LDB, LDX, N, NRHS INTEGER, INTENT(OUT) :: INFO, &: IWORK (*) REAL(iop), INTENT(OUT) :: err REAL(iwp), INTENT(IN) :: A( LDA,*), & AF( LDAF,*), rhs REAL(wp), INTENT(INOUT) :: sol REAL(wp), INTENT (OUT) :: WORK(*) where wp ::= KIND(LO) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) sol ::- X(LDX,*) | X(*) err ::= FERR(*), BERR(*) | FERR, BERR Complex Hermitian version. SUBROUTINE LA_PORFS( UPLO, N, NRHS, & A, LDA, AF, LDAF, B, LDB, X, LDX, & FERR, BERR, WORK, RWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: & UPLO INTEGER, INTENT(IN) :: LDA, LDAF, & LDB, LDX, N, NRHS INTEGER, INTENT(OUT) :: INFO REAL(u;p), INTENT(OUT) :: err, RWORK(*) COMPLEX(wp), INTENT(IN) :: A( LDA,*), & AF( LDAF,*), rhs COMPLEX(u;p), INTENT(INOUT) :: sol COMPLEX(u;p), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) sol ::= X(LDX,*) | X(*) err ::= FERR(*), BERR(*) | FERR, BERR LA_PORFS improves the computed solution to a system of linear equations when the coefficient matrix is a real symmetric / complex Hermitian positive definite, and provides error bounds and backward error estimates for the solution. References: See [1] and [9, 21, 20].

LA_POTRI

Real and complex Hermitian versions.

Computational Routines

218 SUBROUTINE LA_POTRI( UPLO, N, A, LDA, & INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: LDA, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(INOUT) :: A( LDA,*) where type ::= REAL | COMPLEX

wp ::= KIND(l.O) | KIND(l.ODO) LAJPOTRI computes the inverse of a real symmetric / complex Hermitian positive definite matrix A using the Cholesky factorization computed by LAJPOTRF. References: See [1] and [9, 20].

LAJPOEQU

Real and complex Hermitian versions.

SUBROUTINE LA_POEQU( N, A, LDA, S, & SCOND, AMAX, INFO ) INTEGER, INTENT(IN) :: LDA, N INTEGER, INTENT(OUT) :: INFO REAL(u;p), INTENT (OUT) :: AMAX, & SCOND, S(*) type(wp), INTENT(IN) :: A( LDA,*) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA-POEQU computes row and column scalings intended to equilibrate a real symmetric / complex Hermitian positive definite matrix A and reduce its condition number. References: See [1] and [9, 21, 20].

LAJPPTRF

Real and complex Hermitian versions.

SUBROUTINE LAJPPTRF( UPLO, N, AP, &: INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(INOUT) :: AP(*)

where type ::= REAL | COMPLEX wp ::= KIND(1.0) | KIND(l.ODO) LA_PPTRF computes the Cholesky factorization of a real symmetric / complex Hermitian positive definite matrix A stored in packed format. References: See [1] and [9, 20].

LAJPPTRS

Real and complex Hermitian versions.

SUBROUTINE LA_PPTRS( UPLO, N, NRHS, & AP, B, LDB, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: LDB, N, NRHS INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(IN) :: AP(*) type(wp), INTENT(INOUT) :: rhs where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*)

LA-PPTRS solves a system of linear equations AX = B with a real symmetric / complex Hermitian positive definite .matrix A in packed storage using the Cholesky factorization computed by LA-PPTRF. References: See [1] and [9, 20].

LAJPPCON

Real version.

SUBROUTINE LAJPPCON( UPLO, N, AP, & ANORM, RCOND, WORK, IWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: N INTEGER, INTENT(OUT) :: INFO, IWORK(*) REAL(u/p), INTENT(IN) :: ANORM REAL(wp), INTENT(OUT) :: RCOND REAL(wp), INTENT(IN) :: AP(*) REAL(wp), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) Complex Hermitian version. SUBROUTINE LA_PPCON( UPLO, N, AP, & ANORM, RCOND, WORK, RWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT (IN) :: N INTEGER, INTENT(OUT) :: INFO REAL(iyp), INTENT (IN) :: ANORM REAL(iyp), INTENT (OUT) :: RCOND, & RWORK(*) COMPLEX(iyp), INTENT(IN) :: AP(*) COMPLEX(wp), INTENT(OUT) :: WORK(*) where

wp ::= KIND(l.O) | KIND(l.ODO) LA.PPCON estimates the reciprocal of the condition number of a real symmetric / complex Hermitian positive definite packed matrix using the Cholesky factorization computed by LAJPPTRF. References: See [1] and [9, 21, 2.0].

LAJPPRFS

Real version.

SUBROUTINE LA_PPRFS( UPLO, N, NRHS, & AP, AFP, B, LDB, X, LDX, FERR, BERR, & WORK, IWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: LDB, LDX, N, NRHS INTEGER, INTENT(OUT) :: INFO, IWORK(*) REAL(wp), INTENT (OUT) :: err REAL(wp), INTENT(IN) :: AFP(*), AP(*), rhs REAL(w;p), INTENT(INOUT) :: sol REAL(iwp), INTENT(OUT) :: WORK(*) where wp ::= KIND(1.0) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) sol ::= X(LDX,*) | X(*) err ::= FERR(*), BERR(*) | FERR, BERR Complex Hermitian version.

219

Computational Routines for Linear Equations SUBROUTINE LA_PPRFS( UPLO, N, NRHS, & AP, AFP, B, LDB, X, LDX, FERR, BERR, & WORK, RWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: LDB, LDX, N, NRHS INTEGER, INTENT(OUT) :: INFO REAL(u;p), INTENT(OUT) :: err, RWORK(*) COMPLEX (top), INTENT(IN) :: AFP(*), AP(*), & rhs COMPLEX(«;p), INTENT(INOUT) :: sol COMPLEX(u/p), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) sol ::= X(LDX,*) | X(*) err ::= FERR(*), BERR(*) | FERR, BERR LAJPPRFS improves the computed solution to a system of linear equations when the coefficient matrix is a real symmetric / complex Hermitian positive definite and packed, and provides error bounds and backward error estimates for the solution. References: See [1] and [9, 21, 20].

LAJPPTRI

Real and complex Hermitian versions. SUBROUTINE LA_PPTRI( UPLO, N, AP, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(INOUT) :: AP(*) where type ::= REAL 1 COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA_PPTRI computes the inverse of real symmetric / complex Hermitian positive definite matrix A in packed storage format using the Cholesky factorization computed by LAJPPTRF. References: See [1] and [9, 20].

LA_PPEQU

Real and complex Hermitian versions. SUBROUTINE LAJPPEQU( UPLO, N, AP, S, & SCOND, AMAX, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: N INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT(OUT) :: AMAX, SCOND, & S(*) type(wp), INTENT(IN) :: AP(*) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) L A JPPEQU computes row and column scalings intended to equilibrate a real symmetric / complex Hermitian positive definite matrix A in packed storage and reduce its condition number. References: See [1] and [9, 21, 20].

LAJPBTRF

Real and complex Hermitian versions.

SUBROUTINE LA_PBTRF( UPLO, N, KD, AB, & LDAB, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: KD, LDAB, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(INOUT) :: AB( LDAB,*) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA-PBTRF computes the Cholesky factorization of a real symmetric / complex Hermitian positive definite band matrix A. References: See [1] and [9, 20].

LAJPBTRS

Real and complex Hermitian versions. SUBROUTINE LA_PBTRS( UPLO, N, KD, & NRHS, AB, LDAB, B, LDB, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: KD, LDAB, LDB, &: N, NRHS INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(IN) :: AB( LDAB,*) type(wp), INTENT(INOUT) :: rhs where type :: = REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) L A_PBTRS solves a system of linear equations AX = B with a real symmetric / complex Hermitian positive definite band matrix A using the Cholesky factorization computed by LA_PBTRF. References: See [1] and [9, 20].

LA_PBCON

Real version.

SUBROUTINE LA_PBCON( UPLO, N, KD, AB, & LDAB, ANORM, RCOND, WORK, IWORK, & INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: KD, LDAB, N INTEGER, INTENT(OUT) :: INFO, IWORK(*) REAL(wp), INTENT(IN) :: ANORM REAL(u;p), INTENT(OUT) :: RCOND REAL(wp), INTENT(IN) :: AB( LDAB,*) REAL(y;p), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) Complex Hermitian version. SUBROUTINE LA_PBCON( UPLO, N, KD, AB, & LDAB, ANORM, RCOND, WORK, RWORK, & INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: KD, LDAB, N INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT (IN) :: ANORM REAL(u;p), INTENT(OUT) :: RCOND, &

Computational Routines

220 RWORK(*) COMPLEX(«;p), INTENT(IN) :: AB( LDAB,*) COMPLEXJwp), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) LAJPBCON estimates the reciprocal of the condition number of a real symmetric / complex Hermitian positive definite band matrix using the Cholesky factorization computed by LA.PBTRF. References: See [1] and [9, 21, 20].

LAJPBRFS

Real version.

SUBROUTINE LA_PBRFS( UPLO, N, KD, & NRHS, AB, LDAB, AFB, LDAFB, B, LDB, & X, LDX, FERR, BERR, WORK, IWORK, & INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: KD, LDAB, LDAFB, & LDB, LDX, N, NRHS INTEGER, INTENT(OUT) :: INFO, IWORK(*) REAL(wp), INTENT(OUT) :: err REAL(wp), INTENT(IN) :: AB( LDAB,*), & AFB( LDAFB,*), rhs REAL(wp), INTENT(INOUT) :: sol REAL(w;p), INTENT (OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) sol ::= X(LDX,*) | X(*) err ::= FERR(*), BERR(*) | FERR, BERR Complex Hermitian version. SUBROUTINE LA_PBRFS( UPLO, N, KD, & NRHS, AB, LDAB, AFB, LDAFB, B, LDB, & X, LDX, FERR, BERR, WORK, RWORK, & INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: KD, LDAB, LDAFB, &: LDB, LDX, N, NRHS INTEGER, INTENT(OUT) :: INFO REAL(u;p), INTENT(OUT) :: err, RWORK(*), COMPLEX (wp), INTENT(IN) :: AB( LDAB,*), & AFB( LDAFB,*), rhs COMPLEX (wp), INTENT (INOUT) :: sol COMPLEX(u/p), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) sol ::= X(LDX,*) | X(*) err ::= FERR(*), BERR(*) | FERR, BERR LA.PBRFS improves the computed solution to a system of linear equations when the coefficient matrix is a real symmetric / complex Hermitian positive definite banded, and provides error bounds and backward error estimates for the solution. References: See [1] and [9, 21, 20].

LA_PBEQU

Real and complex Hermitian versions.

SUBROUTINE LA_PBEQU( UPLO, N, KD, AB, & LDAB, S, SCOND, AMAX, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: KD, LDAB, N INTEGER, INTENT(OUT) :: INFO REAL(u;p), INTENT(OUT) :: AMAX, SCOND, & S(*) type(wp), INTENT(IN) :: AB( LDAB,*) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LAJPBEQU computes row and column scalings intended to equilibrate a real symmetric / complex Hermitian positive definite band matrix A and reduce its condition number. References: See [1] and [9, 21, 20].

LA_PTTRF

Real and complex Hermitian versions. SUBROUTINE LA_PTTRF( N, D, E, INFO ) INTEGER, INTENT(IN) :: N INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT (INOUT) :: D( * ) type(wp), INTENT(INOUT) :: E( * ) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LAJPTTRF computes the LDLT factorization of a real symmetric / complex Hermitian positive definite tridiagonal matrix A. The factorization may also be regarded as having the form A = UTDU. References: See [1] and [9, 20].

LA_PTTRS

Real version.

SUBROUTINE LA_PTTRS( N, NRHS, D, E, B, & LDB, INFO ) INTEGER, INTENT(IN) :: LDB, N, NRHS INTEGER, INTENT (OUT) :: INFO REAL(wp), INTENT(IN) :: D(*) REAL (top), INTENT (IN) :: E(*) REAL(wp), INTENT(INOUT) :: rhs where wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) Complex Hermitian version. SUBROUTINE LA_PTTRS( UPLO, N, NRHS, D, & E, B, LDB, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT (IN) :: LDB, N, NRHS INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT(IN) :: D(*) COMPLEX(u;p), INTENT(IN) :: E(*) COMPLEX(wp), INTENT(INOUT) :: rhs where wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*)

Computational Routines for Linear Equations LAJPTTRS solves a real symmetric / complex Hermitian positive definite tridiagonal system of the form AX — B, using the factorization computed by LA_PTTRF. References: See [1] and [9, 20].

LAJPTCON

221 LAJPTRFS improves the computed solution to a system of linear equations when the coefficient matrix is a real symmetric / complex Hermitian positive definite and tridiagonal, and provides error bounds and backward error estimates for the solution. References: See [1] and [9, 21, 20].

Real and complex Hermitian versions.

10.1.3 Symmetric Indefinite Linear Systems

SUBROUTINE LA_PTCON( N, D, E, ANORM, & RCOND, RWORK, INFO ) INTEGER, INTENT(IN) :: N INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT(IN) :: ANORM, D(*) REAL(u;p), INTENT(OUT) :: RCOND, & Real, complex, and complex Hermitian versions. RWORK (*) type(wp), INTENT(IN) :: E(*) SUBROUTINE LA_SYTRF( UPLO, N, A, LDA, & where IPIV, WORK, LWORK, INFO ) type ::= REAL | COMPLEX CHARACTER(LEN=1), INTENT(IN) :: UPLO wp ::= KIND(l.O) | KIND(l.ODO) INTEGER, INTENT(IN) :: LDA, LWORK, N LAJPTCON computes the reciprocal of the condition INTEGER, INTENT(OUT) :: INFO, IPIV(*) number of a real symmetric / complex Hermitian positive detype(wp), INTENT(INOUT) :: A( LDA,*) finite tridiagonal matrix using the factorization computed by type(wp), INTENT(OUT) :: WORK( LWORK ) LAJPTTRF. where References: See [1] and [9, 21, 20]. type ::= REAL | COMPLEX wp ::= KIND(l.O) KIND(l.ODO) LA_SYTRF / LA_HETRF compute the factorization of a real symmetric / complex symmetric / complex HermiReal version. tian matrix A using the Bunch-Kaufman diagonal pivoting method. SUBROUTINE LA_PTRFS( N, NRHS, D, E, DF, & References: See [1] and [9, 21, 20]. EF, B, LDB, X, LDX, FERR, BERR, WORK, & INFO ) INTEGER, INTENT(IN) :: LDB, LDX, N, NRHS INTEGER, INTENT(OUT) :: INFO Real, complex, and complex Hermitian versions. REAL(u;p), INTENT(IN) :: D(*), DF(*) REAL(iop), INTENT(OUT) :: err SUBROUTINE LA_SYTRS( UPLO, N, NRHS, A, & REAL(wp), INTENT(IN) :: rhs, E(*), EP(*) LDA, IPIV, B, LDB, INFO ) REAL(wp), INTENT(INOUT) :: sol CHARACTER(LEN=1), INTENT (IN) :: UPLO REAL(iop), INTENT(OUT) :: WORK(*) INTEGER, INTENT(IN) :: LDA, LDB, N, NRHS where INTEGER, INTENT (OUT) :: INFO wp ::= KIND(l.O) KIND(l.ODO) INTEGER , INTENT(IN) :: IPIV(*) rhs ::= B(LDB,*) | B(*) type(wp), INTENT(IN) :: A( LDA,*) sol ::= X(LDX,*) | X(*) type(wp), INTENT(INOUT) :: rhs err ::= FERR(*), BERR(*) | FERR, BERR where Complex Hermitian version. type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) SUBROUTINE LA_PTRFS( UPLO, N, NRHS, D, & rhs ::= B(LDB,*) | B(*) E, DF, EF, B, LDB, X, LDX, FERR, BERR, & LA.SYTRS / LA-HETRS solve a system of linear WORK, RWORK, INFO ) equations AX = B with a real symmetric / complex symCHARACTER(LEN=1), INTENT(IN) :: UPLO metric / complex Hermitian matrix A using the factorization INTEGER, INTENT(IN) :: LDB, LDX, N, NRHS computed by LA_SYTRF / LA-HETRF, respectively. INTEGER, INTENT(OUT) :: INFO References: See [1] and [9, 20]. REAL(wp), INTENT(IN) :: D(*), DF(*) REAL(wp), INTENT (OUT) :: err, & RWORK (*) Real version. COMPLEX(wp), INTENT(IN) :: rhs, E(*), EF(*) COMPLEX(wp), INTENT(INOUT) :: sol SUBROUTINE LA_SYCON( UPLO, N, A, LDA, & COMPLEX(iyp), INTENT(OUT) :: WORK(*) where IPIV, ANORM, RCOND, WORK, IWORK, & wp ::= KIND(l.O) | KIND(l.ODO) INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO rhs ::= B(LDB,*) | B(*) sol ::= X(LDX,*) | X(*) INTEGER, INTENT(IN) :: LDA, N err ::= FERR(*), BERR(*) | FERR, BERR INTEGER, INTENT(OUT) :: INFO, IWORK(*)

LA_SYTRF / LA_HETRF

LA_PTRFS

LA.SYTRS / LA_HETRS

LA_SYCON / LA_HECON

222 REAL(wp), INTENT(IN) :: ANORM REAL(wp), INTENT(OUT) :: RCOND INTEGER, INTENT(IN) :: IPIV(*) REAL(wp), INTENT(IN) :: A( LDA,*) REAL(u;p), INTENT(OUT) :: WORK(*) where wp ::= KIND(1.0) | KIND(l.ODO) Complex and complex Hermitian versions.

Computational Routines COMPLEX(t//p), INTENT(INOUT) :: sol COMPLEX(wp), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*)

sol ::= X(LDX,*) | X(*) err ::= FERR(*), BERR(*) | FERR, BERR LA.SYRFS / LAJHERFS improve the computed solution to a system of linear equations when the coefficient matrix SUBROUTINE LA-SYCON / LA_HECON( UPLO, & is real symmetric / complex symmetric / complex Hermitian N, A, LDA, IPIV, ANORM, RCOND, WORK, & indefinite, and provides error bounds and backward error estimates for the solution. INFO ) References: See [1] and [9, 21, 20]. CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: LDA, N INTEGER, INTENT(OUT) :: INFO LA_SYTRI / LA_HETRI REAL(wp), INTENT (IN) :: ANORM Real, complex, and complex Hermitian versions. REAL(wp), INTENT(OUT) :: RCOND INTEGER, INTENT(IN) :: IPIV(*) SUBROUTINE LA.SYTRI /LA_HETRI( UPLO, & COMPLEX(u;p), INTENT(IN) :: A( LDA,*) N, A, LDA, IPIV, WORK, INFO ) COMPLEX(wp), INTENT(OUT) :: WORK(*) CHARACTER(LEN=1), INTENT(IN) :: UPLO where INTEGER, INTENT(IN) :: LDA, N wp ::= KIND(l.O) | KIND(l.ODO) INTEGER, INTENT(OUT) :: INFO LA-SYCON / LAJHECON estimates the reciprocal of INTEGER, INTENT(IN) :: IPIV(*) the condition number of a real symmetric / complex symtype(wp), INTENT(INOUT) :: A( LDA,*) metric / complex Hermitian matrix A using the factorization type(wp), INTENT(OUT) :: WORK(*) computed by LAJSYTRF / LAJHETRF, respectively. where References: See [1] and [9, 21, 20]. type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA_SYRFS / LA_HERFS LA.SYTRI / LA.HETRI compute the inverse of Real version. real symmetric, complex symmetric / complex Hermitian indefinite matrix A using the factorization computed by SUBROUTINE LA_SYRFS( UPLO, N, NRHS, A, & LA.SYTRF / LA.HETRF respectively. LDA, AF, LDAF, IPIV, B, LDB, X, LDX, & References: See [1] and [9, 20]. FERR, BERR, WORK, IWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO LA.SPTRF / LA_HPTRF INTEGER, INTENT(IN) :: LDA, LDAF, LDB, & Real, complex, and complex Hermitian versions. LDX, N, NRHS INTEGER, INTENT(OUT) :: INFO, IWORK(*)

INTEGER, INTENT(IN) :: IPIV(*) REAL(wp), INTENT (OUT) :: err REAL(u;p), INTENT(IN) :: A( LDA,*), & AF( LDAF,*), rhs REAL(wp), INTENT(INOUT) :: sol REAL(wp), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*)

sol ::= X(LDX,*) | X(*) err ::= FERR(*), BERR(*) | FERR, BERR Complex and complex Hermitian versions. SUBROUTINE LA_SYRFS / LA_HERFS( UPLO, & N, NRHS, A, LDA, AF, LDAF, IPIV, B, & LDB, X, LDX, FERR, BERR, WORK, & RWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: LDA, LDAF, LDB, & LDX, N, NRHS INTEGER, INTENT(OUT) :: INFO INTEGER, INTENT(IN) :: IPIV(*) REAL(w;p), INTENT(OUT) :: err, RWORK(*) COMPLEX(w;p), INTENT(IN) :: A( LDA,*), & AF( LDAF,*), rhs

SUBROUTINE LA-SPTRF /LA_HPTRF( UPLO, &: N, AP, IPIV, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT (IN) :: N INTEGER, INTENT(OUT) :: INFO, IPIV(*) type(wp), INTENT(INOUT) :: AP(*) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA.SPTRF and LA.HPTRF compute the factorization of a real symmetric / complex symmetric / complex Hermitian indefinite matrix A stored in packed format using the Bunch-Kaufman diagonal pivoting method. References: See [1] and [9, 21, 20].

LA_SPTRS / LA.HPTRS

Real, complex, and complex Hermitian versions. SUBROUTINE LAJSPTRS /LA_HPTRS( UPLO, & N, NRHS, AP, IPIV, B, LDB, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: LDB, N, NRHS INTEGER, INTENT (OUT) :: INFO INTEGER, INTENT(IN) :: IPIV(*)

Computational Routines for Linear Equations type(wp), INTENT (IN) :: AP(*) type(wp), INTENT(INOUT) :: B(LDB,*) where type ::= REAL COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) LA_SPTRS / LA_HPTRS solve a system of linear equations AX — B with a real symmetric / complex symmetric / complex Hermitian matrix A stored in packed format using the factorization computed by LA.SPTRF / LAJHPTRF respectively. References: See [1] and [9, 20].

LA_SPCON / LA_HPCON

Real version.

SUBROUTINE LA_SPCON( UPLO, N, AP, IPIV, & ANORM, RCOND, WORK, IWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: N INTEGER, INTENT(OUT) :: INFO, IWORK(*) REAL(top), INTENT(IN) :: ANORM REAL (top), INTENT (OUT) :: RCOND INTEGER, INTENT(IN) :: IPIV( * ) REAL(wp), INTENT(IN) :: AP(*) REAL(wp), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) Complex and complex Hermitian versions. SUBROUTINE LA_SPCON /LAJHPCON( UPLO, & N, AP, IPIV, ANORM, RCOND, WORK, & INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: N INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT(IN) :: ANORM REAL(wp), INTENT(OUT) :: RCOND INTEGER, INTENT(IN) :: IPIV( * ) COMPLEX(u;p), INTENT(IN) :: AP(*) COMPLEX(wp), INTENT(OUT) :: WORK(*) where

wp ::= KIND(l.O) | KIND(l.ODO) LA_SPCON / LA_HPCON estimates the reciprocal of the condition number of real symmetric / complex symmetric / complex Hermitian indefinite packed matrix A using the factorization computed by LA_SPTRF / LAJHPTRF respectively. References: See [1] and [9, 20, 21].

LA_SPRFS / LA_HPRFS

Real version.

SUBROUTINE LA_SPRFS( UPLO, N, NRHS, & AP, AFP, IPIV, B, LDB, X, LDX, FERR, & BERR, WORK, IWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: LDB, LDX, N, NRHS INTEGER, INTENT(OUT) :: INFO, IWORK(*) INTEGER, INTENT(IN) :: IPIV(*) REAL(wp), INTENT(OUT) :: err REAL(wp), INTENT(IN) :: AFP(*), AP(*), rhs

223 REAL(wp), INTENT(INOUT) :: sol REALJwp), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) sol ::= X(LDX,*) | X(*) err ::= FERR(*), BERR(*) | FERR, BERR Complex and complex Hermitian versions. SUBROUTINE LA_SPRFS /LA_HPRFS( UPLO, & N, NRHS, AP, AFP, IPIV, B, LDB, X, LDX, & FERR, BERR, WORK, RWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: LDB, LDX, N, NRHS INTEGER, INTENT(OUT) :: INFO INTEGER, INTENT(IN) :: IPIV(*) REAL(wp), INTENT (OUT) :: err, RWORK (*) COMPLEX(wp), INTENT(IN) :: AFP(*), AP(*), & rhs COMPLEX(iup), INTENT(INOUT) :: sol COMPLEX(wp), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) sol ::= X(LDX,*) | X(*) err ::= FERR(*), BERR(*) | FERR, BERR LA_SPRFS / LA_HPRFS improve the computed solution to a system of linear equations when the coefficient matrix is a real symmetric / complex symmetric / complex Hermitian, indefinite and packed, and provides error bounds and backward error estimates for the solution. References: See [1] and [9, 21, 20].

LA_SPTRI / LA_HPTRI

Real, complex, and complex Hermitian versions. SUBROUTINE LA_SYTRI /LA_HETRI( UPLO, & N, AP, IPIV, WORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: N INTEGER, INTENT(OUT) :: INFO INTEGER, INTENT(IN) :: IPIV(*) type(wp), INTENT(INOUT) :: AP(*) type(wp), INTENT(OUT) :: WORK(*) where type ::— REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA_SPTRI / LAJHPTRI compute the inverse of a real symmetric / complex symmetric / complex Hermitian, indefinite matrix A in packed storage using the factorization computed by LA.SPTRF / LAJHPTRF respectively. References: See [1] and [9, 20].

10.1.4

Triangular Linear Systems

LA_TRTRS

Real and complex versions.

224

Computational Routines

SUBROUTINE LA_TRTRS( UPLO, TRANS, & DIAG, N, NRHS, A, LDA, B, LDB, INFO ) CHARACTER(LEN=1), INTENT(IN) :: DIAG, & TRANS, UPLO INTEGER, INTENT (IN) :: LDA, LDB, N, NRHS INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(IN) :: A(LDA,*)

type(wp), INTENT(INOUT) :: rhs where type ::= REAL | COMPLEX wp ::= KIND(1.0) | KIND(l.ODO)

rhs ::= B(LDB,*) | B(*)

LA.TRTRS solves a triangular system of the form AX = B, ATX = B, or AH X = B, where A is a real /complex triangular matrix of order n, and B is a rectangular matrix. References: See [1] and [9, 20].

LA_TRCON

Real version.

SUBROUTINE LA_TRCON( NORM, UPLO, & DIAG, N, A, LDA, RCOND, WORK, & I WORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: DIAG, & NORM, UPLO INTEGER, INTENT (IN) :: LDA, N INTEGER, INTENT(OUT) :: INFO, IWORK(*) REAL(wp), INTENT(OUT) :: RCOND REAL(wp), INTENT(IN) :: A(LDA,*) REAL(wp), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) Complex version.

REAL(«;p), INTENT(IN) :: A(LDA,*), rhs REAL(wp), INTENT(IN) :: sol REAL(«;p), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) sol ::= X(LDX,*) | X(*) err ::= FERR(*), BERR(*) | FERR, BERR Complex version. SUBROUTINE LA_TRRFS( UPLO, TRANS, & DIAG, N, NRHS, A, LDA, B, LDB, X, LDX, &: FERR, BERR, WORK, RWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: DIAG, & TRANS, UPLO INTEGER, INTENT(IN) :: LDA, LDB, LDX, N, & NRHS INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT(OUT) :: err, RWORK(*) COMPLEX(u;p), INTENT(IN) :: A(LDA,*), rhs COMPLEXJu/p), INTENT(INOUT) :: sol COMPLEX(wp), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) sol ::= X(LDX,*) | X(*) err ::= FERR(*), BERR(*) | FERR, BERR LA.TRRFS provides error bounds and backward error estimates for the solution to a system of linear equations with a real / complex triangular coefficient matrix. References: See [1] and [9, 21, 20].

LA_TRTRI

Real and complex versions. SUBROUTINE LA_TRCON( NORM, UPLO, & DIAG, N, A, LDA, RCOND, WORK, fc RWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: DIAG, & NORM, UPLO INTEGER, INTENT(IN) :: LDA, N INTEGER, INTENT(OUT) :: INFO REAL(ttfp), INTENT(OUT) :: RCOND, RWORK(*) COMPLEX(top), INTENT(IN) :: A(LDA,*) COMPLEX (tup), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) LAJTRCON estimates the reciprocal of the condition number of a real / complex triangular matrix A. References: See [I] and [9, 20, 21].

LA.TRRFS

Real version.

SUBROUTINE LA_TRRFS( UPLO, TRANS, & DIAG, N, NRHS, A, LDA, B, LDB, X, LDX, & FERR, BERR, WORK, I WORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: DIAG, & TRANS, UPLO INTEGER, INTENT (IN) :: LDA, LDB, LDX, N, & NRHS INTEGER, INTENT(OUT) :: INFO, IWORK(*) REAL(w;p), INTENT (OUT) :: err

SUBROUTINE LA_TRTRI( UPLO, DIAG, N, A, & LDA, INFO ) CHARACTER(LEN=1), INTENT(IN) :: DIAG, & UPLO INTEGER, INTENT(IN) :: LDA, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(INOUT) :: A( LDA, * ) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA_TRTRI computes the inverse of a real / complex upper or lower triangular matrix A. References: See [1] and [9, 20].

LA_TPTRS

Real and complex versions. SUBROUTINE LA_TPTRS( UPLO, TRANS, & DIAG, N, NRHS, AP, B, LDB, INFO ) CHARACTER(LEN=1), INTENT(IN) :: DIAG, & TRANS, UPLO INTEGER, INTENT(IN) :: LDB, N, NRHS INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(IN) :: AP(*) type(wp), INTENT(INOUT) :: rhs where type ::= REAL | COMPLEX

Computational Routines for Linear Equations wp ::= KIND(l.O) | KIND(l.ODO) rks ::= B(LDB,*) | B(*) L AJTPTRS solves a triangular system of the form AX — B, ATX — B, or AHX = B, where A is a real / complex triangular matrix of order n stored in packed format, and B is an N x nrhs matrix. References: See [1] and [9, 20].

LA_TPCON

Real version.

SUBROUTINE LA_TPCON( NORM, UPLO, & DIAG, N, AP, RCOND, WORK, IWORK, & INFO ) CHARACTER(LEN=1), INTENT(IN) :: DIAG, & NORM, UPLO INTEGER, INTENT(IN) :: N INTEGER, INTENT(OUT) :: INFO, IWORK(*) REAL(u;p), INTENT(OUT) :: RCOND REAL(iyp), INTENT(IN) :: AP(*) REAL(wp), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) Complex version. SUBROUTINE LA_TPCON( NORM, UPLO, & DIAG, N, AP, RCOND, WORK, RWORK, & INFO ) CHARACTER(LEN=1), INTENT(IN) :: DIAG, & NORM, UPLO INTEGER, INTENT(IN) :: N INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT (OUT) :: RCOND, RWORK (*) COMPLEX(u;p), INTENT(IN) :: AP(*) COMPLEX(wp), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) LA_TPCON estimates the reciprocal of the condition number of a packed real / complex triangular matrix A. References: See [1] and [9, 21, 20].

LA_TPRFS

Real version.

SUBROUTINE LA_TPRFS( UPLO, TRANS, & DIAG, N, NRHS, AP, B, LDB, X, LDX, & FERR, BERR, WORK, IWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: DIAG, & TRANS, UPLO INTEGER, INTENT(IN) :: LDB, LDX, N, NRHS INTEGER, INTENT(OUT) :: INFO, IWORK(*) REAL(ryp), INTENT(OUT) :: err REALJwp), INTENT(IN) :: AP(*), rhs, sol REAL(u;p), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) sol ::= X(LDX,*) | X(*) err ::= FERR(*), BERR(*) | FERR, BERR Complex version.

225 SUBROUTINE LA_TPRFS( UPLO, TRANS, & DIAG, N, NRHS, AP, B, LDB, X, LDX, & FERR, BERR, WORK, RWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: DIAG, & TRANS, UPLO INTEGER, INTENT(IN) :: LDB, LDX, N, NRHS INTEGER, INTENT (OUT) :: INFO REAL(wp), INTENT(OUT) :: err, RWORK(*) COMPLEX(wp), INTENT(IN) :: AP(*), rhs, sol COMPLEX(wp), INTENT(OUT) :: WORK(*) where wp ::- KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) sol ::= X(LDX,*) | X(*) err ::= FERR(*), BERR(*) | FERR, BERR LA-TPRFS provides error bounds and backward error estimates for the solution to a system of linear equations with a real / complex triangular packed coefficient matrix. References: See [1] and [9, 21, 20].

LA_TPTRI

Real and complex versions. SUBROUTINE LA_TPTRI( UPLO, DIAG, N, AP, & INFO ) CHARACTER(LEN=l), INTENT(IN) :: DIAG, & UPLO INTEGER, INTENT(IN) :: N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(INOUT) :: AP( * ) where type ::= REAL COMPLEX wp ::= KIND(1.0) | KIND(l.ODO) LA.TPTRI computes the inverse of a real / complex upper / lower triangular matrix A stored in packed format. References: See [1] and [9, 20].

LA_TBTRS

Real and complex versions. SUBROUTINE LA_TBTRS( UPLO, TRANS, & DIAG, N, KD, NRHS, AB, LDAB, B, LDB, & INFO ) CHARACTER(LEN=1), INTENT(IN) :: DIAG, & TRANS, UPLO INTEGER, INTENT(IN) :: KD, LDAB, LDB, N, & NRHS INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(IN) :: AB(LDAB,*) type(wp), INTENT (INOUT) :: rhs where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) L A_TBTRS solves a triangular system of the form AX = B, ATX = B, or AHX = B, where A is a real / complex triangular band matrix of order n, and B is an n x nrhs matrix. References: See [1] and [9, 20].

LA_TBCON

Real version.

Computational Routines

226 SUBROUTINE LA_TBCON( NORM, UPLO, & DIAG, N, KD, AB, LDAB, RCOND, WORK, & I WORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: DIAG, & NORM, UPLO INTEGER, INTENT(IN) :: KD, LDAB, N INTEGER, INTENT(OUT) :: INFO, IWORK(*) REAL(wp), INTENT(OUT) :: RCOND REAL(wp), INTENT(IN) :: AB(LDAB,*) REAL(u;jj), INTENT(OUT) :: WORK(*) where wp ::= KIND(1.0) | KIND(l.ODO) Complex version. SUBROUTINE LA_TBCON( NORM, UPLO, & DIAG, N, KD, AB, LDAB, RCOND, WORK, & RWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: DIAG, & NORM, UPLO INTEGER, INTENT(IN) :: KD, LDAB, N INTEGER, INTENT(OUT) :: INFO REAL(u;p), INTENT(OUT) :: RCOND, RWORK(*) COMPLEX(u/p), INTENT(IN) :: AB(LDAB,*) COMPLEX(wp), INTENT(OUT) :: WORK(I(t) where wp ::= KIND(l.O) | KIND(l.ODO) LA.TBCON estimates the reciprocal of the condition number of a real / complex triangular band matrix A. References: See [1] and [9, 21, 20].

LAJTBRFS

Real version.

SUBROUTINE LA_TBRFS( UPLO, TRANS, & DIAG, N, KD, NRHS, AB, LDAB, B, LDB, & X, LDX, FERR, BERR, WORK, IWORK, & INFO ) CHARACTER(LEN=1), INTENT (IN) :: DIAG, &: TRANS, UPLO INTEGER, INTENT(IN) :: KD, LDAB, LDB, & LDX, N, NRHS INTEGER, INTENT(OUT) :: INFO, IWORK(*) REAL(wp), INTENT(OUT) :: err REALJwp), INTENT(IN) :: AB(LDAB,*), rhs, sol REAL(u;p), INTENT(OUT) :: WORK(*) where wp ::= KIND(1.0) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) sol ::= X(LDX,*) | X(*) err ::= FERR(*), BERR(*) | FERR, BERR Complex version. SUBROUTINE LA_TBRFS( UPLO, TRANS, & DIAG, N, KD, NRHS, AB, LDAB, B, LDB, & X, LDX, FERR, BERR, WORK, RWORK, & INFO ) CHARACTER(LEN=1), INTENT(IN) :: DIAG, & TRANS, UPLO INTEGER, INTENT(IN) :: KD, LDAB, LDB, & LDX, N, NRHS INTEGER, INTENT(OUT) :: INFO REAL(u7>), INTENT(OUT) :: err, RWORK(*) COMPLEX(u;p), INTENT(IN) :: AB(LDAB,*), &

rhs, sol

COMPLEX(itfp), INTENT(OUT) :: WORK(*) where wp ::= KIND(1.0) | KIND(l.ODO) rhs ::= B(LDB,*) | B(*) sol ::= X(LDX,*) | X(*) err ::= BERR(*), FERR(*) | BERR, FERR LA_TBRFS provides error bounds and backward error estimates for the solution to a system of linear equations with a real / complex triangular band coefficient matrix. References: See [1] and [9, 21, 20].

10.2

Computational Routines for Orthogonal Factorizations

LA_GEQP3 Real version.

SUBROUTINE LA_GEQP3( M, N, A, LDA, & JPVT, TAU, WORK, LWORK, INFO ) INTEGER, INTENT(IN) :: LDA, LWORK, M, N INTEGER, INTENT (OUT) :: INFO INTEGER, INTENT(INOUT) :: JPVT( * ) REAL(u;p), INTENT (INOUT) :: A( LDA, * ) REAL(wp), INTENT (OUT) :: TAU( * ), & WORK (LWORK) where wp ::= KIND(l.O) | KIND(l.ODO) Complex version. SUBROUTINE LA_GEQP3( M, N, A, LDA, & JPVT, TAU, WORK, LWORK, RWORK, INFO ) INTEGER, INTENT(IN) :: LDA, LWORK, M, N INTEGER, INTENT(OUT) :: INFO INTEGER, INTENT(INOUT) :: JPVT( * ) COMPLEX(u;p), INTENT(INOUT) :: A( LDA, * ) COMPLEX(u;p), INTENT(OUT) :: TAU( * ), & WORK (LWORK) REAL(wp), INTENT(OUT) :: RWORK( * ) where wp ::= KIND(l.O) | KIND(l.ODO) LA-GEQP3 computes a QR factorization with column pivoting of a matrix A: AP = QR using Level 3 BLAS. References: See [1] and [9, 20, 36].

LA_GEQRF

Real and complex versions. SUBROUTINE LA_GEQRF( M, N, A, LDA, TAU, & WORK, LWORK, INFO ) INTEGER, INTENT(IN) :: LDA, LWORK, M, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(INOUT) :: A(LDA,*) type(wp), INTENT(OUT) :: TAU(*), & WORK (LWORK) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

Computational Routines for Orthogonal Factorizations LA_GEQRF computes a QR factorization of a real / complex TTi x n matrix A. References: See [1, pages 31, 33, 35, 45, 63, 147, 158, 160, 161, 188, 234] and [9, 20].

LA_ORGQR / LAJJNGQR

Real and complex versions.

227

LA_GELQF computes an LQ factorization of a real / complex m x n A: A — LQ. References: See [1] and [9, 20].

LA_ORGLQ / LAJJNGLQ

Real and complex versions.

SUBROUTINE LA.ORGLQ / LAJJNGLQ( M, & N, K, A, LDA, TAU, WORK, LWORK, INFO ) SUBROUTINE LA_ORGQR / LA.UNGQR( M, N, & INTEGER, INTENT(IN) :: K, LDA, LWORK, & K, A, LDA, TAU, WORK, LWORK, INFO ) M, N INTEGER, INTENT(IN) :: K, LDA, LWORK, M, N INTEGER, INTENT(OUT) :: INFO INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(IN) :: TAU(*) type(wp), INTENT(INOUT) :: A(LDA,*) type(wp), INTENT(INOUT) :: A(LDA,*) type(wp), INTENT(IN) :: TAU(*) type(wp), INTENT(OUT) :: & type(wp), INTENT(OUT) :: WORK(LWORK) WORK(LWORK) where where type ::= REAL | COMPLEX type ::= REAL | COMPLEX wp ::= KIND(l.O) KIND(l.ODO) wp ::= KIND(l.O) | KIND(l.ODO) LA_ORGQR / LAJLJNGQR generate an m x n real / LA_ORGLQ / LA_UNGLQ generates an m x n a real complex matrix Q with orthonormal columns, which is defined / complex matrix Q with orthonormal rows, which is defined as the first n columns of a product of k elementary reflectors as the first m rows of a product of k elementary reflectors of of order m as returned by LA_GEQRF. order n as returned by LA_GELQF. References: See [1] and [9, 20]. References: See [1] and [9, 20].

LAJ3RMQR / LAJJNMQR

Real and complex versions.

SUBROUTINE LA_ORMQR / LA_UNMQR( & SIDE, TRANS, M, N, K, A, LDA, TAU, C, & LDC, WORK, LWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: SIDE, & TRANS INTEGER, INTENT(IN) :: K, LDA, LDC, & LWORK, M, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(IN) :: A(LDA,*), TAU(*) type(wp), INTENT(INOUT) :: C(LDC,*) type(wp), INTENT(OUT) :: WORK(LWORK) where type ::= REAL COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA.ORMQR / LA_UNMQR overwrite the general real / complex m x n matrix C with QC, CQ, QHC or CQH (respectively) where Q is real orthogonal / complex unitary matrix defined as the product of k elementary reflectors as returned by LA_GEQRF. References: See [1] and [9, 20].

LA_GELQF

LA_ORMLQ / LAJUNMLQ

Real and complex versions.

SUBROUTINE LA-ORMLQ / LA_UNMLQ( SIDE, & TRANS, M, N, K, A, LDA, TAU, C, LDC, & WORK, LWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: SIDE, & TRANS INTEGER, INTENT(IN) :: K, LDA, LDC, fc LWORK, M, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(IN) :: A(LDA,*), TAU(*) type(wp), INTENT(INOUT) :: C(LDC,*) type(wp), INTENT(OUT) :: WORK(LWORK) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA-ORMLQ / LA_UNMLQ overwrite the general real / complex mxn matrix C with QC, CQ, QHC or CQH (respectively) where Q is a real orthogonal / complex unitary matrix defined as the product of k elementary reflectors as returned by LA.GELQF. References: See [1] and [9, 20].

LA_GEQLF

Real and complex versions.

Real and complex versions.

SUBROUTINE LA_GELQF( M, N, A, LDA, TAU, & WORK, LWORK, INFO ) INTEGER, INTENT(IN) :: LDA, LWORK, M, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(INOUT) :: A(LDA,*) type(wp), INTENT(OUT) :: TAU(*), & WORK (LWORK) •where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

SUBROUTINE LA_GEQLF( M, N, A, LDA, TAU, & WORK, LWORK, INFO ) INTEGER, INTENT(IN) :: LDA, LWORK, M, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(INOUT) :: A(LDA,*) type(wp), INTENT(OUT) :: TAU(*), & WORK (LWORK) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

Computational Routines

228 LA-GEQLF computes a QL factorization of a real / complex m x n matrix A: A = QL. References: See [1] and [9, 20].

LA.ORGQL / LA.UNGQL

LA-GERQF computes an RQ factorization of a real / complex m X n matrix A: A = RQ. References: See [1] and [9, 20].

LAJDRGRQ / LAJLJNGRQ

Real and complex versions.

Real and complex versions.

SUBROUTINE LA.ORGQL / LA_UNGQL( M, N, &: K, A, LDA, TAU, WORK, LWORK, INFO ) INTEGER, INTENT(IN) :: K, LDA, LWORK, & M, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(IN) :: TAU(*) type(wp), INTENT(INOUT) :: A(LDA,*) type(wp), INTENT (OUT) :: WORK (LWORK) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA.ORGQL / LAJLJNGQL generate an m x n real / complex matrix Q with orthonormal columns, which is defined as the last n columns of a product of k elementary reflectors of order m as returned by LA_GEQLF. References: See [1] and [9, 20].

SUBROUTINE LA.ORGRQ / LA_UNGRQ( M, & N, K, A, LDA, TAU, WORK, LWORK, INFO ) INTEGER, INTENT(IN) :: K, LDA, LWORK, & M, N INTEGER, INTENT (OUT) :: INFO type(wp), INTENT(IN) :: TAU(*) type(wp), INTENT(INOUT) :: A(LDA,*) type(wp), INTENT(OUT) :: & WORK (LWORK) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA_ORGRQ / LA.UNGRQ generates an m x n real / complex matrix Q with orthonormal rows, which is defined as the last m rows of a product of k elementary reflectors of order n as returned by LA-GERQF. References: See [1] and [9, 20].

LAJ3RMQL / LAJLJNMQL

Real and complex versions.

LAJ3RMRQ / LAJJNMRQ

Real and complex versions.

SUBROUTINE LA-ORMQL / LA_UNMQL( SIDE, & SUBROUTINE LA_ORMRQ / LA_UNMRQ( SIDE, & TRANS, M, N, K, A, LDA, TAU, C, LDC, & TRANS, M, N, K, A, LDA, TAU, C, LDC, & WORK, LWORK, INFO ) WORK, LWORK, INFO ) CHARACTER(LEN=1), INTENT (IN) :: SIDE, & CHARACTER(LEN=1), INTENT(IN) :: SIDE, & TRANS TRANS INTEGER, INTENT(IN) :: K, LDA, LDC, & INTEGER, INTENT (IN) :: K, LDA, LDC, & LWORK, M, N LWORK, M, N INTEGER, INTENT (OUT) :: INFO INTEGER, INTENT (OUT) :: INFO type(wp), INTENT(IN) :: A(LDA,*), TAU(*) type(wp), INTENT(IN) :: A(LDA,*), TAU(*) type(wp), INTENT(INOUT) :: C(LDC,*) type(wp), INTENT(INOUT) :: C(LDC,*) type(wp), INTENT (OUT) :: & type(wp), INTENT(OUT) :: & WORK (LWORK) WORK (LWORK) where where type ::= REAL | COMPLEX type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) wp ::= KIND(l.O) | KIND(l.ODO) LA-ORMQL / LA-UNMQL overwrites the general LA.ORMRQ / LAJUNMRQ overwrites the general real / complex xn matrix C with QC, CQ, QTC and CQT real / complex m x n matrix C with QC, CQ, QHC and H (respectively) where Q is a real orthogonal / complex uniCQ (respectively), where Q is a real orthogonal / complex tary matrix defined as the product of A; as returned by unitary matrix defined as the product of k elementary reflecLA-GEQLF. tors as returned by LA-GERQF. References: See [1] and [9, 20]. References: See [1] and [9, 20].

LA_GERQF

LA.TZRZF

Real and complex versions.

Real and complex versions.

SUBROUTINE LA_GERQF( M, N, A, LDA, TAU, & WORK, LWORK, INFO ) INTEGER, INTENT(IN) :: LDA, LWORK, M, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT (INOUT) :: A (LDA,*) type(wp), INTENT(OUT) :: TAU(*), & WORK (LWORK) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

SUBROUTINE LA_TZRZF( M, N, A, LDA, & TAU, WORK, LWORK, INFO ) INTEGER, INTENT(IN) :: LDA, LWORK, M, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(INOUT) :: A( LDA, * ) type(wp), INTENT(OUT) :: TAU( * ), & WORK (LWORK) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

Computational Routines for Orthogonal Factorizations

229

SUBROUTINE LA_SPTRD / LAJHPTRD( UPLO, & N, AP, D, E, TAU, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: N INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT(OUT) :: D(*), E(*) LA_ORMRZ / LAJJNMRZ type(wp), INTENT(INOUT) :: AP(*) Real and complex versions. type(wp), INTENT(OUT) :: TAU(*) where SUBROUTINE LA-ORMRZ / LA_UNMRZ( SIDE, & type ::= REAL | COMPLEX TRANS, M, N, K, L, A, LDA, TAU, C, LDC, & wp ::= KIND(l.O) | KIND(l.ODO) WORK, LWORK, INFO ) LA.SPTRD / LAJHPTRD reduces a real symmetric / CHARACTER(LEN=1), INTENT(IN) :: SIDE, & complex Hermitian matrix A stored in packed storage to real TRANS symmetric tridiagonal form T by an orthogonal / unitary simINTEGER, INTENT(IN) :: K, L, LDA, LDC, & ilarity transformation: QH AQ — T. LWORK, M, N References: See [1] and [9, 20]. INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(IN) :: A( LDA, * ), TAU( * ) LA.SBTRD / LA_HBTRD type(wp), INTENT(INOUT) :: C( LDC, * ) Real and complex versions. type(wp), INTENT(OUT) :: WORK(LWORK) where type ::= REAL | COMPLEX SUBROUTINE LA.SBTRD / LA_HBTRD( VECT, & wp ::~ KIND(l.O) | KIND(l.ODO) UPLO, N, KD, AB, LDAB, D, E, Q, LDQ, & WORK, INFO ) LA_ORMRZ / LAJUNMRZ overwrites the general CHARACTER(LEN=1), INTENT(IN) :: UPLO, & real / complex m x n C with QC, CQ, QHC or CQH (reVECT spectively) where Q is a real orthogonal / complex unitary INTEGER, INTENT(IN) :: KD, LDAB, LDQ, N matrix defined as the product of k elementary reflectors as INTEGER, INTENT (OUT) :: INFO returned by LA_TZRZF. REAL(u;p), INTENT(OUT) :: D(*), E(*) References: See [1] and [9, 20].

LA_TZRZF reduces the m x n ( m < n ) real / complex upper trapezoidal matrix A to upper triangular form by means of real orthogonal / unitary transformations. References: See [1] and [9, 20].

type(tflp), INTENT(INOUT) :: AB(LDAB,*), & Q(LDQ,*)

10.3

Computational Routines for the Symmetric Eigenproblem

LA_SYTRD / LA_HETRD Real and complex versions.

SUBROUTINE LA-SYTRD / LA_HETRD( UPLO, & N, A, LDA, D, E, TAU, WORK, LWORK, & INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: LDA, LWORK, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(INOUT) :: A(LDA,*) REAL(wp), INTENT(OUT) :: D(*), E(*) type(wp), INTENT (OUT) :: TAU(*), & WORK (LWORK) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA_SYTRD / LA-HETRD reduces a real symmetric / complex Hermitian matrix A to real symmetric tridiagonal form T by an orthogonal / unitary similarity transformation: QHAQ = T. References: See [1] and [9, 20].

LA_SPTRD / LAJHPTRD

Real and complex versions.

type(wp), INTENT (OUT) :: WORK(*) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA_SBTRD / LAJHBTRD reduces a real symmetric / complex Hermitian band matrix A to real symmetric tridiagonal form T by an orthogonal / unitary similarity transformation: QHAQ = T. References: See [1] and [9, 20].

LA_ORGTR / LAJJNGTR

Real and complex versions.

SUBROUTINE LA.ORGTR / LA_UNGTR( UPLO, & N, A, LDA, TAU, WORK, LWORK, INFO ) CHARACTER(LEN=:1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: LDA, LWORK, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(IN) :: TAU(*) type(wp), INTENT(INOUT) :: A(LDA,*) type(wp), INTENT(OUT) :: WORK(LWORK) where type ::= REAL | COMPLEX wp ::= KIND(1.0) | KIND(l.ODO) LA_ORGTR / LA.UNGTR generates a real orthogonal / complex unitary matrix Q which is defined as the product of n - 1 elementary reflectors of order n, as returned by LA.SYTRD / LA-HETRD. References: See [1] and [9, 20].

LA_ORMTR / LAJJNMTR

Real and complex versions.

230 SUBROUTINE LA_ORMTR / LA_UNMTR( SIDE, & UPLO, TRANS, M, N, A, LDA, TAU, C, LDC, & WORK, LWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: SIDE, & TRANS, UPLO INTEGER, INTENT(IN) :: LDA, LDC, & LWORK, M, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(IN) :: A(LDA,*), TAU(*) type(wp), INTENT(OUT) :: WORK(LWORK) type(wp), INTENT(INOUT) :: C(LDC,*) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA.ORMTR / LA_UNMTR overwrite the general real / complex m x n matrix C with a real orthogonal / complex unitary matrix Q of order nq. References: See [1] and [9, 20].

LAJ3PGTR / LAJJPGTR

Computational Routines

LA_STEQR

Real and complex versions. SUBROUTINE LA_STEQR( COMPZ, N, D, E, Z, & LDZ, WORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: COMPZ INTEGER, INTENT(IN) :: LDZ, N INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT(INOUT) :: D(*), E(*) REAL(wp), INTENT(OUT) :: WORK(*) type(wp), INTENT(INOUT) :: Z(LDZ,*) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA_STEQR computes all eigenvalues and, optionally, eigenvectors of a symmetric tridiagonal matrix using the implicit QL or QR method. References: See [1] and [9, 20].

LA_STERF

Real and complex versions.

Real version.

SUBROUTINE LA.OPGTR / LA_UPGTR( UPLO, & N, AP, TAU, Q, LDQ, WORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: LDQ, N INTEGER, INTENT (OUT) :: INFO type(wp), INTENT(IN) :: AP(*), TAU(*) type(wp), INTENT(OUT) :: Q(LDQ,*), WORK(*) where type ::= REAL | COMPLEX wp ::= KIND(1.0) | KIND(l.ODO) LA-OPGTR / LA.UPGTR generate a real orthogonal / complex unitary matrix Q which is denned as the product of n — 1 elementary reflectors Hi of order n, as returned by LAJSPTRD / LA-HPTRD using packed storage. References: See [1] and [9, 20].

SUBROUTINE LA_STERF( N, D, E, INFO ) INTEGER, INTENT (IN) :: N INTEGER, INTENT(OUT) :: INFO KEAL(wp), INTENT(INOUT) :: D(*), E(*) where wp ::= KIND(l.O) | KIND(l.ODO) LA_STERF computes all eigenvalues of a symmetric tridiagonal matrix using the Pal-Walker-Kahan variant of the QL or QR algorithm. References: See [1] and [9, 20].

LA_STEDC

Real version.

SUBROUTINE LA_STEDC( COMPZ, N, D, E, Z, &: LDZ, WORK, LWORK, IWORK, LIWORK, & INFO ) LA_OPMTR / LA.UPMTR CHARACTER(LEN=1), INTENT(IN) :: COMPZ Real and complex versions. INTEGER, INTENT(IN) :: LDZ, LIWORK, & LWORK, N SUBROUTINE LA.OPMTR / LA_UPMTR( SIDE, & INTEGER, INTENT(OUT) :: INFO, & UPLO, TRANS, M, N, AP, TAU, C, LDC, & IWORK (LI WORK) WORK, INFO ) REAL(u;p), INTENT(INOUT) :: D(*), E(*) CHARACTER(LEN=1), INTENT(IN) :: SIDE, & REAL(wp), INTENT(INOUT) :: Z(LDZ,*) TRANS, UPLO REAL(wp), INTENT(OUT) :: WORK(LWORK) INTEGER, INTENT(IN) :: LDC, M, N where INTEGER, INTENT(OUT) :: INFO wp ::= KIND(l.O) | KIND(l.ODO) type(wp), INTENT(IN) :: AP(*), TAU(*) Complex version. type(wp), INTENT(INOUT) :: C(LDC,*) type(wp), INTENT(OUT) :: WORK(*) SUBROUTINE LA_STEDC( COMPZ, N, D, E, Z, & where LDZ, WORK, LWORK, RWORK, LRWORK, & type ::= REAL | COMPLEX IWORK, LIWORK, INFO ) wp ::= KIND(1.0) | KIND(l.ODO) CHARACTER(LEN=1), INTENT (IN) :: COMPZ LA_OPMTR / LAJQPMTR overwrite the general INTEGER, INTENT(IN) :: LDZ, LIWORK, & real / complex m x n matrix C with a real orthogonal / LRWORK, LWORK, N complex unitary matrix Q of order nq, denned as the product INTEGER, INTENT(OUT) :: INFO, & of nq — I elementary reflectors, as returned by LA_SPTRD IWORK (LIWORK) / LA_HPTRD. REAL (top), INTENT (INOUT) :: D(*), E(*) References: See [1] and [9, 20]. REAL(wp), INTENT(OUT) :: RWORK(LRWORK) COMPLEX(iwp), INTENT(INOUT) :: Z(LDZ,*)

231

Computational Routines for the Symmetric eigenproblem COMPLEX (top), INTENT(OUT) :: & WORK(LWORK) where wp ::= KIND(l.O) | KIND(l.ODO) LAJ5TEDC computes all eigenvalues and, optionally, eigenvectors of a symmetric tridiagonal matrix using the divide and conquer method. References: See [1] and [9, 20].

LA_STEGR

Real and complex versions. SUBROUTINE LA_STEGR( JOBZ, RANGE, N, & D, E, VL, VU, IL, IU, ABSTOL, M, W, Z, & LDZ, ISUPPZ, WORK, LWORK, & IWORK, LIWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: JOBZ, & RANGE INTEGER, INTENT(IN) :: IL, IU, LDZ, & LIWORK, LWORK, N INTEGER, INTENT(OUT) :: INFO, M INTEGER, INTENT(OUT) :: ISUPPZ( * ), & IWORK (LIWORK) REAL(typ), INTENT(IN) :: ABSTOL, VL, VU REAL(wp), INTENT(INOUT) :: D( * ), E( * ) REAL (tup), INTENT (IN) :: W( * ) REAL(wp), INTENT(OUT) :: WORK(LWORK) type(wp), INTENT(OUT) :: Z( LDZ, * ) where wp ::= KIND(l.O) KIND(l.ODO) LA_STEGR computes selected eigenvalues and, optionally, eigenvectors of a real symmetric / complex Hermitian tridiagonal matrix T. References: See [1] and [9, 20, 11].

LA_STEBZ

Real version.

SUBROUTINE LA_STEBZ( RANGE, ORDER, & N, VL, VU, IL, IU, ABSTOL, D, E, M, & NSPLIT, W, IBLOCK, ISPLIT, WORK, & IWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: & ORDER, RANGE INTEGER, INTENT(IN) :: IL, IU, M, N INTEGER, INTENT(OUT) :: INFO, NSPLIT, & IBLOCK(*), ISPLIT(*), IWORK(*) REAL(wp), INTENT(IN) :: ABSTOL, VL, VU, & D(*), E(*) REAL(u;p), INTENT(OUT) :: W(*), WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) LAJ5TEBZ computes the eigenvalues of a symmetric tridiagonal matrix T. The user may ask for all eigenvalues in the half-open interval (VL,VU], or the ILth through IVth eigenvalues. References: See [1] and [9, 20, 29].

LA_STEIN

Real and complex versions.

SUBROUTINE LA_STEIN( N, D, E, M, W, & IBLOCK, ISPLIT, Z, LDZ, WORK, IWORK, & IFAIL, INFO ) INTEGER, INTENT(IN) :: LDZ, M, N, & IBLOCK(*), ISPLIT(*) INTEGER, INTENT(OUT) :: INFO, IFAIL(*), & IWORK(*) REAL(top), INTENT(IN) :: D(*), E(*), W(*) REAL(wp), INTENT(OUT) :: WORK(*) type(wp), INTENT(OUT) :: Z( LDZ, * ) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA_STEIN computes the eigenvectors of a real symmetric tridiagonal matrix T corresponding to specified eigenvalues, using inverse iteration. References: See [1] and [9, 20].

LAJPTEQR

Real and complex versions. SUBROUTINE LA_PTEQR( COMPZ, N, D, E, Z, & LDZ, WORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: COMPZ INTEGER, INTENT(IN) :: INFO, LDZ, N REAL(wp), INTENT(INOUT) :: D(*), E(*) REAL(wp), INTENT(OUT) :: WORK(*) type(wp), INTENT(INOUT) :: Z(LDZ,*) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA_PTEQR computes all eigenvalues and, optionally, eigenvectors of a symmetric positive definite tridiagonal matrix by first factoring the matrix using LA_PTTRF and then calling LA-BDSQR to compute the singular values of the bidiagonal factor. References: See [1] and [9, 20].

10.4

Computational Routines for the Nonsymmetric eigenproblem

LA_GEHRD

Real and complex versions. SUBROUTINE LA_GEHRD( N, ILO, IHI, A, & LDA, TAU, WORK, LWORK, INFO ) INTEGER, INTENT(IN) :: IHI, ILO, LDA, & LWORK, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(INOUT) :: A(LDA,*) type(wp), INTENT(OUT) :: TAU(*), WORK (LWORK) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

232

Computational Routines

LA.GEHRD reduces a real / complex general matrix A to upper Hessenberg form H by an orthogonal / unitary similarity transformation: QH AQ = H . References: See [1] and [9, 20].

LA_GEBAL

Real and complex versions. SUBROUTINE LA_GEBAL( JOB, N, A, LDA, & ILO, IHI, SCALE, INFO ) CHARACTER(LEN=1), INTENT(IN) :: JOB INTEGER, INTENT (IN) :: LDA, N INTEGER, INTENT(OUT) :: IHI, ILO, INFO REAL(wp), INTENT(OUT) :: SCALE(*) type(wp), INTENT(INOUT) :: A(LDA,*) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA_GEBAL balances a general real / complex matrix A. References: See [1] and [9, 20, 37].

LA.GEBAK

Real and complex versions.

LA_ORMHR / LA.UNMHR

Real and complex versions.

SUBROUTINE LA.ORMHR / LA_UNMHR( SIDE, & TRANS, M, N, ILO, IHI, A, LDA, TAU, C, & LDC, WORK, LWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: SIDE, & TRANS INTEGER, INTENT(IN) :: IHI, ILO, LDA, LDC, & LWORK, M, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(IN) :: A(LDA,*), TAU(*) type(wp), INTENT(INOUT) :: C(LDA,*) type(wp), INTENT(OUT) :: WORK(LWORK) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA.ORMHR / LA_UNMHR overwrites the general real / complex m x n C with a real orthogonal / complex unitary matrix Q of order nq where Q is denned as the product of elementary reflectors, as returned by LA_GEHRD. References: See [1] and [9, 20].

LA_HSEQR

Real version.

SUBROUTINE LA_GEBAK( JOB, SIDE, N, ILO, & IHI, SCALE, M, V, LDV, INFO ) SUBROUTINE LA_HSEQR( JOB, COMPZ, N, & CHARACTER(LEN=1), INTENT(IN) :: JOB, & ILO, IHI, H, LDH, WR, WI, Z, LDZ, WORK, & SIDE LWORK, INFO ) INTEGER, INTENT(IN) :: IHI, ILO, LDV, M, N CHARACTER(LEN=1), INTENT(IN) :: COMPZ, & INTEGER, INTENT(OUT) :: INFO JOB REAL(wp), INTENT(IN) :: SCALE(*) INTEGER, INTENT(IN) :: IHI, ILO, LDH, LDZ, type(wp), INTENT(INOUT) :: V(LDV,*) LWORK, N where INTEGER, INTENT(OUT) :: INFO type ::= REAL | COMPLEX REAL(wp), INTENT(OUT) :: WR(*), WI(*) wp ::= KIND(l.O) | KIND(l.ODO) REAL(wp), INTENT(INOUT) :: H(LDH,*), Z(LDZ,*) LA_GEBAK forms the right or left eigenvectors of a REAL(wp), INTENT (OUT) :: WORK (LWORK) real / complex general matrix by backward transformation on where the computed eigenvectors of the balanced matrix output by wp ::= KIND(l.O) | KIND(l.ODO) LA.GEBAL. Complex version. References: See [1] and [9, 20].

LAJDRGHR / LA.UNGHR

Real and complex versions.

SUBROUTINE LA.ORGHR / LA_UNGHR( N, & ILO, IHI, A, LDA, TAU, WORK, LWORK, & INFO ) INTEGER, INTENT(IN) :: IHI, ILO, LDA, & LWORK, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(IN) :: TAU(*) type(wp), INTENT(INOUT) :: A(LDA,*) type(wp), INTENT(OUT) :: WORK(LWORK) where type ::= REAL | COMPLEX wp ::= KIND(1.0) | KIND(l.ODO) LA.ORGHR / LA.UNGHR generate a real orthogonal / complex unitary matrix Q which is defined as the product of elementary reflectors of order n, as returned by LA.GEHRD. References: See [1] and [9, 20].

SUBROUTINE LA_HSEQR( JOB, COMPZ, N, & ILO, IHI, H, LDH, W, Z, LDZ, WORK, & LWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: COMPZ, & JOB INTEGER, INTENT(IN) :: IHI, ILO, LDH, LDZ, & LWORK, N INTEGER, INTENT(OUT) :: INFO COMPLEX(wp), INTENT(INOUT) :: H(LDH,*), & Z(LDZ,*) COMPLEX(wp), INTENT(OUT) :: W(*), & WORK (LWORK) where wp ::= KIND(l.O) | KIND(l.ODO) LA.HSEQR computes the eigenvalues of a real / complex upper Hessenberg matrix H, and, optionally, the matrices T and Z from the Schur decomposition H = ZTZH, where T is an upper triangular matrix (the Schur form), and Z is the unitary matrix of Schur vectors. References: See [1] and [9, 20].

Computational Routines for the Symmetric eigenproblem

LA_HSEIN

Real version.

SUBROUTINE LA_HSEIN( VR, LDVR, MM, M, & WORK, IFAILL, IFAILR, INFO ) CHARACTER(LEN=1), INTENT(IN) :: & EIGSRC, INITV, SIDE INTEGER, INTENT(IN) :: LDH, LDVL, LDVR, & MM, N INTEGER, INTENT(OUT) :: INFO, M, & IFAILL(*), IFAILR(*) LOGICAL, INTENT(IN) :: SELECT(*) REAL(wp), INTENT(INOUT) :: WR(*), WI(*) REAL(wp), INTENT(IN) :: H(LDH,*) REAL(wp), INTENT(INOUT) :: VL(LDVL,*), VR(LDVR,*) REAL(wp), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) Complex version.

233

SELECT, N, T, LDT, VL, LDVL, VR, LDVR, & MM, M, WORK, RWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: & HOWMNY, SIDE INTEGER, INTENT(IN) :: LDT, LDVL, LDVR, & MM, N INTEGER, INTENT(OUT) :: INFO, M LOGICAL, INTENT(INOUT) :: SELECT(*) REAL(tup), INTENT(OUT) :: RWORK(*) COMPLEX(wp), INTENT(INOUT) :: T(LDT,*), & VL(LDVL,*), VR(LDVR,*) COMPLEX(iyp), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) LA_TREVC computes some or all of the right and/or left eigenvectors of a real / complex upper quasi-triangular / triangular matrix T. References: See [1] and [9, 20].

LA_TREXC

Real version.

SUBROUTINE LA_HSEIN( VR, LDVR, MM, M, & WORK, RWORK, IFAILL, IFAILR, INFO ) SUBROUTINE LA_TREXC( COMPQ, N, T, LDT, & CHARACTER(LEN=1), INTENT(IN) :: & Q, LDQ, IFST, ILST, WORK, INFO ) EIGSRC, INITV, SIDE CHARACTER(LEN=1), INTENT(IN) :: COMPQ INTEGER, INTENT(IN) :: LDH, LDVL, LDVR, & INTEGER, INTENT(IN) :: IFST, ILST, LDQ, & MM, N LDT, N INTEGER, INTENT(OUT) :: INFO, M, &: INTEGER, INTENT(OUT) :: INFO IFAILL(*), IFAILR(*) REAL(wp), INTENT(INOUT) :: Q(LDQ,*), &: LOGICAL, INTENT(IN) :: SELECT(*) T(LDT,*), WORK(*) REAL(wp), INTENT(OUT) :: RWORK( * ) where COMPLEX(u;p), INTENT(IN) :: H(LDH,*) COMPLEX(wp), INTENT(INOUT) :: VL(LDVL,*), & wp ::= KIND(l.O) | KIND(l.ODO) Complex version. VR(LDVR,*), W(*) COMPLEX(wp), INTENT(OUT) :: WORK(*) where SUBROUTINE LA_TREXC( COMPQ, N, T, LDT, & wp ::= KIND(l.O) | KIND(l.ODO) Q, LDQ, IFST, ILST, INFO ) CHARACTER(LEN=1), INTENT(IN) :: COMPQ LA-HSEIN uses inverse iteration to find specified right INTEGER, INTENT(IN) :: IFST, ILST, LDQ, & and/or left eigenvectors of a real / complex upper Hessenberg LDT, N matrix H. INTEGER, INTENT(OUT) :: INFO References: See [1] and [9, 20]. COMPLEX(u;p), INTENT(INOUT) :: Q(LDQ,*), & T(LDT,*) LA_TREVC where Real version. wp ::= KIND(1.0) | KIND(l.ODO) LA_TREXC reorders the Schur factorization of a real / SUBROUTINE LA_TREVC( SIDE, HOWMNY, & complex matrix A = QTQH, so that the diagonal block of T SELECT, N, T, LOT, VL, LDVL, VR, LDVR, & with row index IFST is moved to row ILST. MM, M, WORK, INFO ) References: See [1] and [9, 20]. CHARACTER(LEN=1), INTENT(IN) :: & HOWMNY, SIDE INTEGER, INTENT(IN) :: LDT, LDVL, LDVR, & MM, N Real and complex versions. INTEGER, INTENT(OUT) :: INFO, M LOGICAL, INTENT(INOUT) :: SELECT(*) SUBROUTINE LA_TRSYL( TRANA, TRANB, & REAL(wp), INTENT(IN) :: T(LDT,*) ISGN, M, N, A, LDA, B, LDB, C, LDC, & REAL(wp), INTENT(INOUT) :: VL(LDVL,*), & SCALE, INFO ) VR(LDVR,*) CHARACTER(LEN=1), INTENT(IN) :: & REAL(wp), INTENT(OUT) :: WORK(*) TRANA, TRANB where INTEGER, INTENT(IN) :: ISGN, LDA, LDB, & wp ::= KIND(l.O) | KIND(l.ODO) LDC, M, N Complex version. INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT (OUT) :: SCALE type(wp), INTENT(IN) :: A(LDA,*), B(LDB,*) SUBROUTINE LA_TREVC( SIDE, HOWMNY, &

LA.TRSYL

234 type(wp), INTENT(INOUT) :: C(LDC,*) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA_TRSYL solves the real / complex Sylvester matrix equation. References: See [1] and [9, 20].

LA.TRSNA

Real version.

Computational Routines INTEGER, INTENT(IN) :: LDQ, LDT, LWORK, & N, LIWORK INTEGER, INTENT(OUT) :: INFO, M, & IWORK(LIWORK) REAL(«/p), INTENT(OUT) :: S, SEP LOGICAL, INTENT(IN) :: SELECT(*) REAL(t0p), INTENT(INOUT) :: Q(LDQ,*), T(LDT,*) REAL(«;p), INTENT(IN) :: WR(*), WI(*) REAL(wp), INTENT(OUT) :: WORK(LWORK) where wp ::= KIND(l.O) | KIND(l.ODO) Complex version.

SUBROUTINE LA_TRSNA( JOB, HOWMNY, & SELECT, N, T, LDT, VL, LDVL, VR, LDVR, & SUBROUTINE LA_TRSEN( JOB, COMPQ, fc SELECT, N, T, LDT, Q, LDQ, W, M, S, & S, SEP, MM, M, WORK, LDWORK, IWORK, fc SEP, WORK, LWORK, INFO ) INFO ) CHARACTER(LEN=1), INTENT(IN) :: COMPQ, & CHARACTER(LEN=1), INTENT(IN) :: & JOB HOWMNY, JOB INTEGER, INTENT(IN) :: LDQ, LDT, LWORK, N INTEGER, INTENT(IN) :: LDT, LDVL, LDVR, & INTEGER, INTENT(OUT) :: INFO, M LDWORK, MM, N REAL(u;p), INTENT(OUT) :: S, SEP INTEGER, INTENT(OUT) :: INFO, M, IWORK(*) LOGICAL, INTENT(IN) :: SELECT(*) LOGICAL, INTENT(IN) :: SELECT(*) COMPLEX(iwp), INTENT(INOUT) :: Q(LDQ,*), & REAL(wp), INTENT(OUT) :: S(*), SEP(*) T(LDT,*) REAL(u;p), INTENT(IN) :: T(LDT,*), & COMPLEX(wp), INTENT(IN) :: W(*), & VL(LDVL,*), VRJLDVR,*) WORK (LWORK) REAL(u;p), INTENT(OUT) :: WORK(LDWORK,*) where where wp ::= KIND(l.O) | KIND(l.ODO) wp ::= KIND(l.O) | KIND(l.ODO) LA.TRSEN reorders the Schur factorization of a real Complex version. / complex matrix A = QTQH, so that a selected cluster of eigenvalues appears in the leading positions on the diagonal of SUBROUTINE LA_TRSNA( JOB, HOWMNY, & SELECT, N, T, LDT, VL, LDVL, VR, LDVR, & the upper triangular matrix T, and the leading columns of Q S, SEP, MM, M, WORK, LDWORK, RWORK, & form an orthonormal basis of the corresponding right invariant subspace. INFO ) References: See [1] and [9, 20]. CHARACTER(LEN=1), INTENT(IN) :: & HOWMNY, JOB INTEGER, INTENT(IN) :: LDT, LDVL, LDVR, & LDWORK, MM, N INTEGER, INTENT(OUT) :: INFO, M 10.5 Computational Routines LOGICAL, INTENT(IN) :: SELECT(*) REAL(wp), INTENT(OUT) :: RWORK(*), S(*), & for the Singular Value DeSEP(*) COMPLEX (wp), INTENT(IN) :: T(LDT,*), & composition VL(LDVL,*), VR(LDVR,*) COMPLEX(wp), INTENT(OUT) :: &: WORK(LDWORK,*) LA_GEBRD where Real and complex versions. wp ::= KIND(l.O) | KIND(l.ODO) LA_TRSNA estimates reciprocal condition numbers SUBROUTINE LA_GEBRD( M, N, A, LDA, D, E, & TAUQ, TAUP, WORK, LWORK, INFO ) for specified eigenvalues and/or right eigenvectors of a real / INTEGER, INTENT(IN) :: LDA, LWORK, M, N complex upper quasi-triangular / triangular matrix T (or of H INTEGER, INTENT(OUT) :: INFO any matrix QTQ with Q orthogonal / unitary). REAL(wp), INTENT(OUT) :: D(*), E(*> References: See [1] and [9, 20]. type(wp), INTENT(INOUT) :: A(LDA,*) typc(wp), INTENT(OUT) :: TAUP(*), TAUQ(*), & LA.TRSEN WORK (LWORK) Real version. where type ::= REAL | COMPLEX SUBROUTINE LA_TRSEN( JOB, COMPQ, & wp ::= KIND(l.O) | KIND(l.ODO) SELECT, N, T, LDT, Q, LDQ, WR, WI, M, S, & LA-GEBRD reduces a general real / complex m x n SEP, WORK, LWORK, IWORK, LIWORK, & matrix A to upper or lower bidiagonal form B by an orthogoINFO ) nal / unitary transformation: QHAP = B. CHARACTER(LEN=1), INTENT(IN) :: COMPQ, & References: See [1] and [9, 20]. JOB

Computational Routines for the Singular Value Decomposition

LA.GBBRD

235

LA_ORMBR / LAJJNMBR

Real version.

Real and complex versions.

SUBROUTINE LA_GBBRD( VECT, M, N, NCC, & KL, KU, AB, LDAB, D, E, Q, LDQ, PT, & LDPT, C, LDC, WORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: VECT INTEGER, INTENT(IN) :: KL, KU, LDAB, & LDC, LDPT, LDQ, M, N, NCC INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT(OUT) :: D(*), E(*) REAL(iup), INTENT(INOUT) :: AB(LDAB,*), & C(LDC,*) REAL(wp), INTENT(OUT) :: PT(LDPT,*), & Q(LDQ,*), WORK(*) where wp ::= KIND(1.0) | KIND(l.ODO)

SUBROUTINE LA.ORMBR / LA_UNMBR( & VECT, SIDE, TRANS, M, N, K, A, LDA, & TAU, C, LDC, WORK, LWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: SIDE, & TRANS, VECT INTEGER, INTENT(IN) :: K, LDA, LDC, & LWORK, M, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(IN) :: A(LDA,*), TAU(*) type(wp), INTENT(INOUT) :: C(LDA,*) type(wp), INTENT(OUT) :: WORK(LWORK) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA_ORMBR / LA_UNMBR overwrites the general real / complex m x n matrix C with the products QC, CQ, QHC, CQH', PC, CP, QHC or CQH, respectively, where Q and PH are the orthogonal / unitary matrices determined by LA_GEBRD when reducing a real / complex matrix A to bidiagonal form: A = QBPH. References: See [1] and [9, 20].

Complex version. SUBROUTINE LA_GBBRD( VECT, M. N, NCC, & KL, KU, AB, LDAB, D, E, Q, LDQ, PT, & LDPT, C, LDC, WORK, RWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: VECT INTEGER, INTENT(IN) :: KL, KU, LDAB, & LDC, LDPT, LDQ, M, N, NCC INTEGER, INTENT(OUT) :: INFO REAL(tup), INTENT(OUT) :: D(*), E(*),& RWORK (*) COMPLEX(iyp), INTENT(INOUT) :: & AB(LDAB,*), C(LDC,*) COMPLEX(wp), INTENT(OUT) :: PT(LDPT,*), & Q(LDQ,*), WORK(*) where wp ::= KIND(l.O) KIND(l.ODO) LA-GBBRD reduces a real / complex general m X n band matrix A to real upper bidiagonal form B by an orthogonal / unitary transformation: QH AP — B. References: See [1] and [9, 20].

LA_BDSQR

Real and complex versions.

SUBROUTINE LA_BDSQR( UPLO, N, NCVT, & NRU, NCC, D, E, VT, LDVT, U, LDU, C, & LDC, RWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: LDC, LDU, LDVT, & N, NCC, NCVT, NRU INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT(INOUT) :: D(*), E(*) REAL(wp), INTENT(OUT) :: RWORK(*) type(wp), INTENT(INOUT) :: C(LDC,1(e), & U(LDU,*), VT(LDVT,*) where LA.ORGBR / LA.UNGBR type ::= REAL | COMPLEX Real and complex versions. wp ::= KIND(l.O) | KIND(l.ODO) LA_BDSQR computes the singular value decomposiSUBROUTINE LA_ORGBR / LA_UNGBR( & tion (SVD) of a real n x n (upper or lower) bidiagonal maVECT, M, N, K, A, LDA, TAU, WORK, & trix B: B — QSPH where 5 is a diagonal matrix with nonLWORK, INFO ) negative diagonal elements (the singular values of B), and Q CHARACTER(LEN=1), INTENT(IN) :: VECT and P are orthogonal matrices. INTEGER, INTENT(IN) :: K, LDA, LWORK, M, & References: See [1] and [9, 20, 8, 34]. N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(IN) :: TAU(*) LA_BDSDC type(wp), INTENT(INOUT) :: A(LDA,*) Real version. type(wp), INTENT(OUT) :: WORK(LWORK) where SUBROUTINE LA_BDSDC( UPLO, COMPQ, N, & type ::= REAL | COMPLEX D, E, U, LDU, VT, LDVT, Q, IQ, WORK, & wp ::= KIND(1.0) | KIND(l.ODO) IWORK, INFO ) L A.ORGBR / LA_UNGBR generates one of the real CHARACTER(LEN=1), INTENT(IN) :: & COMPQ, UPLO / complex orthogonal / unitary matrices Q or PH determined INTEGER, INTENT(IN) :: LDU, LDVT, N by LA_GEBRD when reducing a complex matrix A to bidiH H INTEGER, INTENT(OUT) :: INFO, IQ( * ), & agonal form: A — QBP . Q and P are defined as products I WORK ( * ) of elementary reflectors Hi or d respectively. REAL(wp), INTENT(INOUT) :: D( * ), E( * ) References: See [1] and [9, 20]. REAL(wp), INTENT(OUT) :: Q(*), U(LDU,*), &

Computational Routines

236 VT(LDVT,*), WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) LAJBDSDC computes the singular value decomposition (SVD) of a real n x n (upper or lower) bidiagonal matrix B: B = USVT, using a divide and conquer method, where 5 is a diagonal matrix with non-negative diagonal elements (the singular values of B), and U and VT are orthogonal matrices of left and right singular vectors, respectively. LA.BDSDC can be used to compute all singular values, and optionally, singular vectors or singular vectors in compact form. References: See [1] and [9, 20].

10.6

Computational Routines for the Generalized Symmetric Definite Eigenproblem

LA_SYGST / LA.HEGST Real and complex versions.

SUBROUTINE LA_SYGST / LA_HEGST( ITYPE, & UPLO, N, A, LDA, B, LDB, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: ITYPE, LDA, LDB, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(IN) :: B(LDB,*) type(wp), INTENT(INOUT) :: A(LDA,*) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LAJ5YGST / LA_HEGST reduces a real symmetric / complex Hermitian definite generalized eigenproblem to standard form. References: See [1] and [9, 20].

LA_SPGST / LA_HPGST

Real and complex versions.

SUBROUTINE LA_SPGST / LA_HPGST( ITYPE, & UPLO, N, AP, BP, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT(IN) :: ITYPE, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(IN) :: BP(*) type(wp), INTENT(INOUT) :: AP(*) where type ::= REAL | COMPLEX wp ::= KIND(1.0) | KIND(l.ODO) LAJSPGST / LAJHPGST reduces a real symmetric / complex Hermitian definite generalized eigenproblem to standard form, using packed storage. References: See [1] and [9, 20].

LA_PBSTF

Real and complex versions. SUBROUTINE LA_PBSTF( UPLO, N, KD, AB, & LDAB, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO INTEGER, INTENT (IN) :: KD, LDAB, N INTEGER, INTENT (OUT) :: INFO type(wp), INTENT(INOUT) :: AB(LDAB,*) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA_PBSTF computes a split Cholesky factorization of a real symmetric / complex Hermitian positive definite band matrix A. References: See [1] and [9, 20].

LAJ3BGST / LA_HBGST

Real version.

SUBROUTINE LA_SBGST( VECT, UPLO, N, & KA, KB, AB, LDAB, BB, LDBB, X, LDX, & WORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO, & VECT INTEGER, INTENT(IN) :: KA, KB, LDAB, & LDBB, LDX, N INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT(IN) :: BB(LDBB,*) REAL(wp), INTENT(INOUT) :: AB(LDAB,*) REAL(wp), INTENT(OUT) :: WORK(*), X(LDX,*) where wp ::= KIND(l.O) | KIND(l.ODO) Complex version. SUBROUTINE LA_HBGST( VECT, UPLO, N, & KA, KB, AB, LDAB, BB, LDBB, X, LDX, & WORK, RWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: UPLO, & VECT INTEGER, INTENT(IN) :: KA, KB, LDAB, & LDBB, LDX, N INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT(OUT) :: RWORK(*) COMPLEX(wp), INTENT(IN) :: BB(LDBB,*) COMPLEX(u;p), INTENT(INOUT) :: AB(LDAB,*) COMPLEX(wp), INTENT(OUT) :: WORK(*), & X(LDX,*) where wp ::= KIND(l.O) | KIND(l.ODO) LA-SBGST / LA_HBGST reduces a real symmetric / complex Hermitian definite banded generalized eigenproblem Ax = XBx to standard form Cy = Xy, such that C has the same bandwidth as A. References: See [1] and [9, 20].

10.7. Computational Routines for the Generalized Nonsymmetric Eigenproblem

10.7

Computational Routines for the Generalized Nonsymmetric Eigenproblem

LA_GGHRD

237

LA_GGBAK forms the right or left eigenvectors of a real / complex generalized eigenvalue problem Ax = A£?x, by backward transformation on the computed eigenvectors of the balanced pair of matrices output by LA_GGBAL. References: See [1] and [9, 20, 42].

LA_HGEQZ

Real and complex versions.

Real version.

SUBROUTINE LA_GGHRD( COMPQ, COMPZ, & N, ILO, IHI, A, LDA, B, LDB, Q, LDQ, Z, & LDZ, INFO ) CHARACTER(LEN=1), INTENT(IN) :: & COMPQ, COMPZ INTEGER, INTENT(IN) :: IHI, ILO, LDA, & LDB, LDQ, LDZ, N INTEGER, INTENT(OUT) :: INFO type(wp), INTENT(INOUT) :: A(LDA,*), & B(LDB,*), Q(LDQ,*), Z(LDZ,*) where type ::= REAL COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA_GGHRD reduces a pair of real / complex matrices (A, J5) to generalized upper Hessenberg form using orthogonal / unitary transformations. References: See [1] and [9, 20].

SUBROUTINE LA.HGEQZ( JOB, COMPQ, & COMPZ, N, ILO, IHI, A, LDA, B, LDB, & ALPHAR, ALPHAI, BETA, Q, LDQ, Z, LDZ, & WORK, LWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: COMPQ, & COMPZ, JOB INTEGER, INTENT(IN) :: IHI, ILO, LDA, LDB, & LDQ, LDZ, LWORK, N INTEGER, INTENT (OUT) :: INFO REAL(wp), INTENT(INOUT) :: A(LDA,*), & B(LDB,*), Q(LDQ,*), Z(LDZ,*) REAL(iyp), INTENT(OUT) :: ALPHAR(*), & ALPHAI(*), BETA(*), WORK(LWORK) where wp ::= KIND(l.O) | KIND(l.ODO) Complex version.

LA_GGBAL

Real and complex versions. SUBROUTINE LA_GGBAL( JOB, N, A, LDA, B, & LDB, ILO, IHI, LSCALE, RSCALE, WORK, & INFO ) CHARACTER(LEN=1), INTENT(IN) :: JOB INTEGER, INTENT(IN) :: LDA, LDB, N INTEGER, INTENT(OUT) :: IHI, ILO, INFO REAL(u;p), INTENT(OUT) :: LSCALE(*), & RSCALE(*), WORK(*) type(wp), INTENT(INOUT) :: A(LDA,*), B(LDB,*) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA-GGBAL balances a pair of general real / complex matrices (A,B}. References: See [1] and [9, 20, 42].

LA_GGBAK

SUBROUTINE LA_HGEQZ( JOB, COMPQ, & COMPZ, N, ILO, IHI, A, LDA, B, LDB, & ALPHA, BETA, Q, LDQ, Z, LDZ, WORK, & LWORK, RWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: COMPQ, & COMPZ, JOB INTEGER, INTENT(IN) :: IHI, ILO, LDA, LDB, & LDQ, LDZ, LWORK, N INTEGER, INTENT(OUT) :: INFO REAL(iyp), INTENT (OUT) :: RWORK ( * ) COMPLEX(iyp), INTENT(INOUT) :: A(LDA,*), & B(LDB,*), Q(LDQ,*), Z(LDZ,*) COMPLEX(iyp), INTENT(OUT) :: ALPHA(*), & BETA(*), WORK(LWORK) where wp ::= KIND(l.O) | KIND(l.ODO) L A_HGEQZ implements a single-shift version of the QZ method for finding the generalized eigenvalues wl = a,//3 t of the equation det(A — WiB] — 0 References: See [1] and [9, 20, 32].

LA_TGEVC

Real and complex versions.

Real version.

SUBROUTINE LA_GGBAK( JOB, SIDE, N, ILO, & IHI, LSCALE, RSCALE, M, V, LDV, INFO ) CHARACTER(LEN=1), INTENT(IN) :: JOB, & SIDE INTEGER, INTENT(IN) :: IHI, ILO, LDV, M, N INTEGER, INTENT(OUT) :: INFO REAL(wp), INTENT(IN) :: LSCALE(*), & RSCALE(*) type(wp), INTENT(INOUT) :: V(LDV,*) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO)

SUBROUTINE LA_TGEVC( SIDE, HOWMNY, & SELECT, N, A, LDA, B, LDB, VL, LDVL, & VR, LDVR, MM, M, WORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: HOWMNY, SIDE INTEGER, INTENT(IN) :: LDA, LDB, LDVL, LDVR, MM, N INTEGER, INTENT(OUT) :: INFO, M LOGICAL, INTENT(IN) :: SELECT(*) REAL(iop), INTENT(IN) :: A(LDA,*), B(LDB,*) REAL(wp), INTENT(INOUT) :: VL(LDVL,*), & VR(LDVR,*)

Computational Routines

238 REAL(wp), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) Complex version.

References: See [1] and [9, 20, 28].

SUBROUTINE LA_TGEVC( SIDE, HOWMNY, & SELECT, N, A, LDA, B, LDB, VL, LDVL, & VR, LDVR, MM, M, WORK, RWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: & HOWMNY, SIDE INTEGER, INTENT(IN) :: LDA, LDB, LDVL, & LDVR, MM, N INTEGER, INTENT(OUT) :: INFO, M LOGICAL, INTENT(IN) :: SELECT(*) REAL(«;p), INTENT(OUT) :: RWORK(*) COMPLEX(w;p), INTENT(IN) :: A(LDA,*), & B(LDB,*) COMPLEX(iop), INTENT(INOUT) :: & VL(LDVL,*), VR(LDVR,*) COMPLEX(wp), INTENT(OUT) :: WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) LAJTGEVC computes some or all of the right and/or left generalized eigenvectors of a pair of real / complex upp>er triangular matrices (A,B). References: See [1] and [9, 20].

SUBROUTINE LA_TGSYL( TRANS, IJOB, M, N, & A, LDA, B, LDB, C, LDC, D, LDD, E, LDE, & F, LDF, SCALE, DIF, WORK, LWORK, & IWORK, INFO ) CHARACTER, INTENT (IN) :: TRANS INTEGER, INTENT(IN) :: IJOB, LDA, LDB, & LDC, LDD, LDE, LDF, LWORK, M, N INTEGER, INTENT (OUT) :: INFO, IWORK (*) REAL(wp), INTENT(OUT) :: DIF, SCALE type(wp), INTENT(IN) :: A(LDA,*), B(LDB,*), & D(LDD,*), E(LDF,*) type(wp), INTENT(INOUT) :: C(LDC,*), & F(LDF,*) type(wp), INTENT(OUT) :: WORK(LWORK) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA_TGSYL solves the generalized Sylvester equation. References: See [1] and (9, 20, 26, 24, 27].

LAJTGEXC

Real version.

SUBROUTINE LA_TGEXC( WANTQ, WANTZ, & N, A, LDA, B, LDB, Q, LDQ, Z, LDZ, IFST, & ILST, WORK, LWORK, INFO ) LOGICAL, INTENT(IN) :: WANTQ, WANTZ INTEGER, INTENT (IN) :: LDA, LDB, LDQ, & LDZ, LWORK, N INTEGER, INTENT(INOUT) :: IFST, ILST INTEGER, INTENT(OUT) :: INFO REAL(«/p), INTENT(INOUT) :: A(LDA,*), & B(LDB,*), Q(LDQ,*), Z(LDZ,*) REAL(wp), INTENT(OUT) :: WORK(LWORK) where wp ::= KIND(l.O) | KIND(l.ODO) Complex version. SUBROUTINE LA_TGEXC( WANTQ, WANTZ, & N, A, LDA, B, LDB, Q, LDQ, Z, LDZ, IFST, & ILST, INFO ) LOGICAL, INTENT(IN) :: WANTQ, WANTZ INTEGER, INTENT(IN) :: LDA, LDB, LDQ, & LDZ, N INTEGER, INTENT(INOUT) :: IFST, ILST INTEGER, INTENT(OUT) :: INFO COMPLEX(u/p), INTENT(INOUT) :: A(LDA,*), & B(LDB,*), Q(LDQ,*), Z(LDZ,*) where wp ::= KIND(l.O) | KIND(l.ODO) LA_TGEXC reorders the generalized Schur decomposition of a complex matrix pair (A,B), using an orthogonal / unitary equivalence transformation (A,B) := Q(A,B)ZH, so that the diagonal block of (A, B) with row index IFST is moved to row ILST.

LA.TGSYL

Real and complex versions.

LA.TGSNA

Real and complex versions. SUBROUTINE LA_TGSNA( JOB, HOWMNY, & SELECT, N, A, LDA, B, LDB, VL, LDVL, & VR, LDVR, S, DIF, MM, M, WORK, & LWORK, IWORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: & HOWMNY, JOB INTEGER, INTENT(IN) :: LDA, LDB, LDVL, &: LDVR, LWORK, MM, N INTEGER, INTENT(OUT) :: INFO, M, IWORK(*) LOGICAL, INTENT(IN) :: SELECT(*) REAL(wp), INTENT(OUT) :: DIF(*), S(*) type(wp), INTENT(IN) :: A(LDA,*), & B(LDB,*), VL(LDVL,*), VR(LDVR,*) type(wp), INTENT(OUT) :: WORK(LWORK) where type ::= REAL | COMPLEX wp ::= KIND(l.O) | KIND(l.ODO) LA-TGSNA estimates reciprocal condition numbers for specified eigenvalues and/or eigenvectors of a matrix pair (A,B}. References: See [1] and [9, 20, 25, 28, 26].

LA_TGSEN

Real version.

SUBROUTINE LA_TGSEN( IJOB, WANTQ, & WANTZ, SELECT, N, A, LDA, B, LDB, & ALPHAR, ALPHAI, BETA, Q, LDQ, Z, LDZ, & M, PL, PR, DIF, WORK, LWORK, IWORK, & LIWORK, INFO ) LOGICAL, INTENT(IN) :: WANTQ, WANTZ INTEGER, INTENT(IN) :: IJOB, LDA, LDB, & LDQ, LDZ, LIWORK, LWORK, N INTEGER, INTENT(OUT) :: INFO, M,&

Computational Routines for the Generalized Nonsymmetric Eigenproblem IWORK (LIWORK) REAL(wp), INTENT(OUT) :: PL, PR LOGICAL, INTENT(IN) :: SELECT(*) REAL(wp), INTENT(INOUT) :: A(LDA,*), & B(LDB,*), Q(LDQ,*), Z(LDZ,*) REAL(top), INTENT(OUT) :: ALPHAI(*), & ALPHAR(*), BETA(*), DIF(2), & WORK(LWORK) where wp ::= KIND(l.O) KIND(l.ODO) Complex version. SUBROUTINE LA_TGSEN( IJOB, WANTQ, & WANTZ, SELECT, N, A, LDA, B, LDB, & ALPHA, BETA, Q, LDQ, Z, LDZ, & M, PL, PR, DIF, WORK, LWORK, IWORK, & LIWORK, INFO ) LOGICAL, INTENT(IN) :: WANTQ, WANTZ INTEGER, INTENT(IN) :: IJOB, LDA, LDB, & LDQ, LDZ, LIWORK, LWORK, N INTEGER, INTENT(OUT) :: INFO, M, & I WORK (LI WORK) REAL(wp), INTENT (OUT) :: PL, PR LOGICAL, INTENT(IN) :: SELECT(*) REAL(wp), INTENT(OUT) :: DIF(2) COMPLEX(itfp), INTENT(INOUT) :: A(LDA,*), & B(LDB,*), Q(LDQ,*), Z(LDZ,*) COMPLEX(wp), INTENT(OUT) :: ALPHA(*), &: BETA(*), WORK(LWORK) where wp ::= KIND(l.O) | KIND(l.ODO) LA_TGSEN reorders the generalized Schur decomposition of a real / complex matrix pair (A, B) (in terms of an orthogonal / unitary equivalence transformation QH (A, B)Z), so that a selected cluster of eigenvalues appears in the leading diagonal blocks of the pair (A,B). References: See [1] and [9, 20, 28, 25, 26].

239

IWORK(*) REAL(wp), INTENT(IN) :: TOLA, TOLB REAL(wp), INTENT(INOUT) :: A(LDA,*), & B(LDB,*) REAL(iup), INTENT(OUT) :: Q(LDQ,*), TAU(*), & U(LDU,*), V(LDV,*), WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) Complex version.

SUBROUTINE LA_GGSVP( JOBU, JOBV, JOBQ, & M, P, N, A, LDA, B, LDB, TOLA, TOLB, L, U, LDU, V, LDV, Q, LDQ, IWO RWORK, TAU, WORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: JOBQ, JOBU, JOBV INTEGER, INTENT(IN) :: LDA, LDB, LD LDU, LDV, M, N, P INTEGER, INTENT(OUT) :: INFO, K, L IWORK(*) REAL(wp), INTENT(IN) :: TOLA, TOLB REAL(wp), INTENT(IN) :: RWORK(*) COMPLEX(wp), INTENT(INOUT) :: A(LDA,*), & B(LDB,*) COMPLEX(u;p), INTENT(OUT) :: Q(LDQ,*), & TAU(*), U(LDU,*), V(LDV,*), WORK(*) where wp ::= KIND(l.O) | KIND(l.ODO) LA_GGSVP computes orthogonal / unitary matrices U, V and Q. References: See [l] and [9, 20].

LA_TGSJA

Real and complex versions.

SUBROUTINE LA_TGSJA( JOBU, JOBV, JOBQ, & M, P, N, K, L, A, LDA, B, LDB, TOLA, & TOLB, ALPHA, BETA, U, LDU, V, LDV, Q, & LDQ, WORK, NCYCLE, INFO ) CHARACTER(LEN=1), INTENT(IN) :: JOBQ, & JOBU, JOBV INTEGER, INTENT(IN) :: K, L, LDA, LDB, & LDQ, LDU, LDV, M, N, NCYCLE, P INTEGER, INTENT(OUT) :: INFO REAL(iyp), INTENT(IN) :: TOLA, TOLB REAL(iop), INTENT(OUT) :: ALPHA(*), & BETA(*) type(wp), INTENT(INOUT) :: A(LDA,*), &: Real version. B(LDB,*), Q(LDQ,*), U(LDU,*), V(LDV,*) type(wp), INTENT(OUT) :: WORK(*) SUBROUTINE LA.GGSVP( JOBU, JOBV, JOBQ, & where M, P, N, A, LDA, B, LDB, TOLA, TOLB, K, & type ::= REAL | COMPLEX L, U, LDU, V, LDV, Q, LDQ, IWORK, TAU, & wp ::= KIND(l.O) | KIND(l.ODO) WORK, INFO ) CHARACTER(LEN=1), INTENT(IN) :: JOBQ, & LA_TGSJA computes the generalized singular value deJOBU, JOBV composition (GSVD) of two real / complex upper triangular INTEGER, INTENT(IN) :: LDA, LDB, LDQ, & (or trapezoidal) matrices A and B. LDU, LDV, M, N, P References: See [1] and [9, 20]. INTEGER, INTENT(OUT) :: INFO, K, L, &

10.8

Computational Routines for the Generalized Singular Value Decomposition

LA_GGSVP

This page intentionally left blank

Bibliography [1] E. ANDERSON, Z. BAI, C. BISCHOF, L. S. BLACKFORD, J. DEMMEL, J. DONGARRA, J. Du CROZ, A. GREENBAUM, S. HAMMARLING, A. MCKENNEY, AND D. SORENSEN, LAPACK Users' Guide, Society for Industrial and Applied Mathematics, Philadelphia, PA, third ed., 1999. [2] Z. BAI AND J. W. DEMMEL, Computing the generalized singular value decomposition, SI AM J. Sci. Comp., 14 (1993), pp. 1464-1486. (Also LAPACK Working Note #46). [3] Z. BAI AND H. ZHA, A new preprocessing algorithm for the computation of the generalized singular value decomposition, SIAM J. Sci. Comp., 14 (1993), pp. 1007-1012. [4] L. S. BLACKFORD AND J. DONGARRA, Installation guide for LAPACK, Computer Science Dept. Technical Report CS-92-151, University of Tennessee, Knoxville, TN, March 1992. (Also LAPACK Working Note #41). [5]

, Quick installation guide for LAPACK on Unix systems, Computer Science Dept. Technical Report CS-94-249, University of Tennessee, Knoxville, TN, September 1994. (LAPACK Working Note #81).

[6] L. S. BLACKFORD, J. DONGARRA, J. Du CROZ, S. HAMMARLING, AND J. WASNIEWSKI, A Fortran 90 Interface for LAPACK, Computer Science Dept. Technical Report CS-96-341, University of Tennessee, Knoxville, TN, 1996. (Also LAPACK Working Note #117). [7] COMPAQ CORPORATION, Compaq http://www.compaq.com/hpc/software/dxml.html.

Extended

Math

Library.

[8] J. DEMMEL AND W. KAHAN, Computing Small Singular Values of Bidiagonal Matrices with Guaranteed High Relative Accuracy, SIAM J. Sci. Statist. Comput., 11 (1990), pp. 873912. Also (LAPACK Working Note # 3: http://www.netlib.org/lapack/lawns/lawn03.ps or http://www.netlib.org/lapack/lawnspdf/lawn03.pdf). [9] J. W. DEMMEL, Applied Numerical Linear Algebra, Society for Industrial and Applied Mathematics, Philadelphia, PA, USA, first ed., 1997. [10] J. W. DEMMEL AND B. KAGSTROM, Computing stable eigendecompositions of matrix pencils, Lin. Alg. Appl., 88/89 (1987), pp. 139-186. [11] I. DHILLON, A New 0(n2) Algorithm for the Symmetric Tridiagonal Eigenvalue / Eigenvector Problem, Tech. Rep. UCB/CSD-97-971, UC Berkeley, Computer Science Division, May 1997. 241

242

Bibliography

[12] J. DONGARRA, J. DU CROZ, S. HAMMARLING, J. WASNIEWSKI, AND A. ZEMLA, A Proposal

for a Fortran 90 Interface for LAPACK, Computer Science Dept. Technical Report CS-95-295, University of Tennessee, Knoxville, TN, 1995. (Also LAPACK Working Note #101). [13] J. DONGARRA, W. OWCZARZ, J. WASNIEWSKI, AND P. YALAMOV, Testing Software for LAPACK90, Computer Science Dept. Technical Report CS-98-401, University of Tennessee, Knoxville, TN, 1998. (Also LAPACK Working Note #138). [14] J. DONGARRA AND J. WASNIEWSKI, High Performance Linear Algebra Package - LAPACK90, Computer Science Dept. Technical Report CS-98-384, University of Tennessee, Knoxville, TN, 1998. (Also LAPACK Working Note #134). [15] J. J. DONGARRA, J. Du CROZ, I. S. DUFF, AND S. HAMMARLING, A set of Level 3 Basic Linear Algebra Subprograms, ACM Trans. Math. Soft., 16 (1990), pp. 1-17. [16] J. J. DONGARRA, J. Du CROZ, S. HAMMARLING, AND R. J. HANSON, An extended set of FORTRAN basic linear algebra subroutines, ACM Trans. Math. Soft., 14 (1988), pp. 1-17. [17] J. J. DONGARRA, I. S. DUFF, D. SORENSEN, AND H. A. VAN DER VORST, Numerical Linear Algebra for High-Performance Computers, SIAM, Second ed., 1998. [18] J. J. DONGARRA AND E. GROSSE, Distribution of mathematical software via electronic mail, Communications of the ACM, 30 (1987), pp. 403-407. [19] F. GANTMACHER, The Theory of Matrices, vol. II (transl), Chelsea, New York, 1959. [20] G. GOLUB AND C. F. VAN LOAN, Matrix Computations, Johns Hopkins University Press, Baltimore, MD, third ed., 1996. [21] N. J. HlGHAM, Accuracy and Stability of Numerical Algorithms, SIAM, 1996. [22] IBM, IBM Engineering and Scientific Subroutine Library for AIX, Version 3, Volume 1 ed., December 1997. Pub. number SA22-7272-0. [23]

, Engineering and Scientific Subroutine Library for AIX Guide and Reference. http://www.rs6000.ibm.com/resource/aix_resource/sp_books/essl/index.html, 2000.

[24] B. KAGSTROM, A Perturbation Analysis of the Generalized Sylvester Equation (AR - LB,DR - LE) = (C,F], SIAM J. Matrix Anal. Appl., 15 (1994), pp. 1045-1060. [25] B. KAGSTROM AND P. POROMAA, Computing Eigenspaces with Specified Eigenvalues of a Regular Matrix Pair (A,B) and Condition Estimation: Theory, Algorithms and Software, Numerical Algorithms, 12 (1996), pp. 369-407. Also Report # UMINF - 94.04 at Umea University and LAPACK Working Note # 87. [26]

, LAPACK-Style Algorithms and Software for Solving the Generalized Sylvester Equation and Estimating the Separation between Regular Matrix Pairs, ACM Trans, on Math. Software, 22 (1996), pp. 78-103. Also Report # UMINF - 93.23 at Umea University (Sweden) and LAPACK Working Note # 75.

Bibliography

243

[27] B. KAGSTROM AND L. WESTIN, Generalized Schur Methods with Condition Estimators for Solving the Generalized Sylvester Equation, IEEE Transactions on Automatic Control, 34 (1989), pp. 745-751. [28] B. KAGSTROM, A Direct Method for Reordering Eigenvalues in the Generalized Real Schur Form of a Regular Matrix Pair (A, B), in Linear Algebra for Large Scale and Real-Time Applications, M. S. Moonen et al., eds., Kluwer Academic Publ, 1993, pp. 195-218. [29] W. KAHAN, Accurate Eigenvalues of a Symmetric Tridiagonal Matrix, Tech. Rep. CS41, Stanford University, Computer Science Dept., July 1966. [30] C. L. LAWSON, R. J. HANSON, D. KINCAID, AND F. T. KROGH, Basic linear algebra subprograms for Fortran usage, ACM Trans. Math. Soft., 5 (1979), pp. 308-323. [31] M. METCALF AND J. REID, FORTRAN 90/95 Explained, Oxford University Press, Oxford, UK, second ed., 1996. [32] C. B. MOLER AND G. W. STEWART, An Algorithm for Generalized Matrix Eigenvalue Problems, SIAM J. Numer. Anal., 10 (1973), pp. 241-256. [33] C. PAIGE, Computing the generalized singular value decomposition, SIAM J. Sci. Stat., 7 (1986), pp. 1126-1146. [34] B. PARLETT AND F. V., Accurate Singular Values and Differential QD Algorithms, Tech. Rep. CPAM-554, University of California at Berkeley, Mathematics Department, July 1992. [35] G. QuiNTANA-ORTi, E. QuiNTANA-ORTi, AND A. PETITET, Efficient Solution of the Rank-Deficient Linear Least Squares Problem, SIAM Journal on Scientific and Statistical Computing, 20 (1999), pp. 1155-1163. Also LAPACK Working Note # 113: http://www.netlib.org/lapack/lawns/lawnll3.ps or http://www.netlib.org/lapack/lawns/lawnll3.pdf. [36] G. QUINTANA-ORTI, X. SUN, AND C. H. BISCHOF, BLAS-3 Version of the QR Factorization with Column Pivoting. http://www.netlib.org/lapack/lawns/lawnll4.ps or http://www.netlib.org/lapack/lawnspdf/lawnll4.pdf, 1996. PRISM Working Note # 26 and LAPACK Working Note # 114. [37] B. T. SMITH, J. M. BOYLE, J. J. DONGARRA, B. S. GARBOW, Y. IKEBE, V. C. KLEMA, AND C. B. MOLER, Matrix Eigensystem Routines - EISPACK Guide, vol. 6 of Lecture Notes in Computer Science, Springer-Verlag, Berlin, 1976. [38] G. W. STEWART, On the sensitivity of the eigenvalue problem Ax — \Bx, Anal., 9 (1972), pp. 669-686. [39]

SIAM J. Num.

, Error and perturbation bounds for subspaces associated with certain eigenvalue problems, SIAM Review, 15 (1973), pp. 727-764.

[40] G. W. STEWART AND J.-G. SUN, Matrix Perturbation Theory, Academic Press, New York, 1990.

244

Bibliography

[41] SUN

MICROSYSTEMS

INC.,

Sun

Performance

Library

User's

Guide.

http://docs.sun.com/htmlcoll/coll.H8.3/iso-8859-l/PERFLIBUG/plug_bookTOC.html. [42] R. C. WARD, Balancing the Generalized Eigenvalue Problem, SIAM J. Sci. Stat. Comp., 2 (1981), pp. 141-152. [43] R. C. WHALEY, A. PETITET, AND J. J. DONGARRA, Automated empirical optimization of software and the ATLAS project, To appear in Parallel Computing, (2001). Also available as University of Tennessee LAPACK Working Note #147, UT-CS-00-448, 2000 (www.netlib.org/lapack/lawns/lawnl47.ps). [44] J. H. WILKINSON, Kronecker's canonical form and the QZ algorithm, Lin. Alg. AppL, 28 (1979), pp. 285-303.

Index by Keyword packed storage, 101, 104 ALLOCATABLE attribute, 25, 32 ALLOCATE statement, 25, 32 arguments assumed-shape arrays, 28 description, 27 descriptions, 27 illegal value, 28 optional, 26, 28 order of, 27 rank, 26 arrays allocatable, 25, 32 assumed-shape, 3, 25, 28 empty, 25 passing subsections, 25 ATLAS, 4, 7, 41 automatic allocation, 25 auxiliary enquiry function ILAENV, 5 routines, 11, 31

absolute error, 123, 125, 131, 137, 141, 143, 164, 173, 179 accuracy and stability, 47 algorithms Bunch-Kaufman full storage, 93, 98, 221 packed storage, 101, 104, 222 Cholesky decomposition, 74, 220 band storage, 82, 86, 219 full storage, 70, 74, 217 packed storage, 77, 79, 218 tridiagonal, 89, 91 divide and conquer, 231 generalized symmetric, band storage, 174 generalized symmetric, full storage, 159 generalized symmetric, packed storage, 166 least squares, 113 singular value problems, 201 symmetric tridiagonal, 138 symmetric, band storage, 132 symmetric, full storage, 119 symmetric, packed storage, 126 Gaussian elimination with row interchanges band storage, 58, 61 dense storage, 51, 54 tridiagonal, 65, 67 inverse iteration, 231 LDLr decomposition full storage, 93, 98 packed storage, 101, 104 Pal-Walker-Kahan, 230 QR, 146, 151 RRR, 124, 143 Schur decomposition, see Schur UDUT decomposition full storage, 93, 98

backward error, 57, 65, 82, 93, 214-217, 219226 bounds, 13 backward transformation, 232, 237 balanced pair of matrices, 237 balancing, 156, 237 transformation, 195 band form, see band storage storage, 14 scheme, 59, 83, 133 Basic Linear Algebra Subprograms, see BLAS bidiagonal factor, 231 form, 235 245

246 matrices, 30 BLAS, xvii, 41 library, 7 model implementation, 7 optimized, 7 vendor implementation, 7 block algorithms, xvii, 5 size, 5, 41 bug reports, 9 Bunch-Kaufman, see algorithms call LAPACK95 routines, 31, 32 CD-ROM, 8 Cholesky, see algorithms, decomposition and factorization column equilibration, 65 commercial use, 9 complex conjugate pairs, 17, 20 Hermitian, 14 Schur factorization, 17 symmetric, 14 computation failure, 29 computational routines, 3, 11, 30 condition number, 13, 110 eigenvalues generalized nonsymmetric, 187, 195 nonsymmetric, 157 eigenvectors generalized nonsymmetric, 187, 195 nonsymmetric, 157 right, 234 invariant subspace nonsymmetric, 149 selected eigenvalues nonsymmetric, 149 specified eigenvalues, 234 condition number of the system complex general band, 61 dense, 54, 213 triangular band, 226 triangular matrix, 224

Index by Keyword triangular packed, 225 tridiagonal, 67 complex Hermitian band storage, 220 dense, 217 indefinite, full storage, 98, 222 indefinite, packed storage, 104, 223 packed storage, 218 positive definite, band storage, 86 positive definite, full storage, 74 positive definite, packed storage, 79 positive definite, tridiagonal, 91 tridiagonal, 221 complex symmetric indefinite, full storage, 98, 222 indefinite, packed storage, 104, 223 general band, 215 real general band, 61 dense, 54, 213 triangular band, 226 triangular matrix, 224 triangular packed, 225 tridiagonal, 67 real symmetric dense, 217 dense, band storage, 220 indefinite, full storage, 98, 222 indefinite, packed storage, 104, 223 packed storage, 218 positive definite, band storage, 86 positive definite, full storage, 74 positive definite, packed storage, 79 positive definite, tridiagonal, 91 tridiagonal, 221 tridiagonal, 216 constructing LAPACK routines, 4 conventional storage, 30 Cosine-Sine decomposition, 22 CPU-TIME, 42 CXML, 41 data types, 11 DEALLOCATE statement, 33 debugging

Index by Keyword hints, installation, 8 release-notes, 8 decomposition Cholesky, 217 band storage, 219 packed storage, 218 tridiagonal, 220 singular values, 201 deflating subspace, 20, 189 derived types, 26 diagonal block, 233, 238 blocks, 17, 20. 239 elements. 16, 27 entries, 23 matrices, 16, 18, 22 divide and conquer, 19 driver, 16 least squares, 14 method, 231 SVD, 18 documentation, structure, 26 driver routines, 3, 11, 13, 42 divide and conquer, 14, 18, 19 expert, 13, 19 generalized least squares, 15 nonsymmetric eigenvalue problem, 20, 21 SVD, 21 symmetric definite eigenvalue problem, 18 linear equations, 13 least squares, 13 nonsymmetric eigenvalue problem, 17 simple, 13, 19 effective rank of matrix, 112 eigenvalue problem, 3 ill-conditioned, 20 regular, 20 singular, 20 eigenvalues, 16 all

247

generalized nonsymmetric, 190 generalized symmetric, band storage, 174 generalized symmetric, full storage, 159 generalized symmetric, packed storage, 166 nonsymmetric, 152, 156 symmetric tridiagonal, 138 symmetric, band storage, 132 symmetric, full storage, 119 symmetric, packed storage, 126 approximate generalized symmetric, band storage, 180 generalized symmetric, full storage, 165, 173 symmetric tridiagonal, 141, 143 symmetric, band storage, 137 symmetric, full storage, 123, 125 symmetric, packed storage, 131 condition number nonsymmetric, 156, 157 divide and conquer method, 231 generalized, 237 ordering of, 21 nontrivial, 23 ordering of, 17 Pal-Walker-Kahan algorithm, 230 reciprocal condition numbers, 238 selected complex Hermitian, 231 generalized nonsymmetric, 181, 187, 195 generalized symmetric, band storage, 178 generalized symmetric, full storage, 163 generalized symmetric, packed storage, 171 nonsymmetric, 145, 149 real symmetric, 231 symmetric tridiagonal, 140, 143 symmetric, band storage, 136 symmetric, full storage, 122, 124 symmetric, packed storage, 130 selected cluster, 234, 239 symmetric positive definite tridiagonal matrix, 231 tridiagonal matrix, 230 trivial, 23

248

eigenvectors, 16 all generalized nonsymmetric, 190 generalized symmetric, band storage, 174 generalized symmetric, full storage, 159 generalized symmetric, packed storage, 166 nonsymmetric, 152, 156 symmetric tridiagonal, 138 symmetric, band storage, 132 symmetric, full storage, 119 symmetric, packed storage, 126 complex conjugate pairs nonsymmetric, 152, 157 condition number nonsymmetric, 156, 157 left, 17, 20, 232, 233, 237 generalized, 238 nonsymmetric, 152, 156 NEP, 17 normalized nonsymmetric, 156 orthogonal generalized symmetric, band storage, 179 generalized symmetric, full storage, 163 generalized symmetric, packed storage, 172 reciprocal condition numbers, 238 right, 17, 20, 232, 233, 237 generalized, 238 nonsymmetric, 152, 156 scaled nonsymmetric, 152, 156 selected complex Hermitian, 231 generalized nonsymmetric, 181, 187, 195 generalized symmetric, band storage, 178 generalized symmetric, full storage, 163 generalized symmetric, packed storage, 171 nonsymmetric, 145, 149 real symmetric, 231 symmetric tridiagonal, 140, 143 symmetric, band storage, 136 symmetric, full storage, 122, 124

Index by Keyword symmetric, packed storage, 130 usually the fastest algorithm, 124, 143 symmetric positive definite tridiagonal matrix, 231 tridiagonal matrix, 230, 231 EISPACK, xvii elementary reflectors, 235 elimination, see also factorization or decomposition in algorithms equality-constrained least squares, 15 equilibration, 13, 214, 215, 218-220 by column, 65 complex general band, 61 dense, 54 complex Hermitian positive definite, band storage, 86 positive definite, full storage, 74 positive definite, packed storage, 79 real general band, 61 dense, 54 real symmetric positive definite, band storage, 86 positive definite, full storage, 74 positive definite, packed storage, 79 ERINFO, 28, 29 errata, see release_notes error bounds, 214-217, 219-226 handling, 26, 28 routine, 28 error bounds for linear systems complex general band, 61 dense, 54 tridiagonal, 67 complex Hermitian indefinite, full storage, 98 indefinite, packed storage, 104 positive definite, band storage, 86 positive definite, full storage, 74 positive definite, packed storage, 79 positive definite, tridiagonal, 91 complex symmetric

Index by Keyword indefinite, full storage, 98 indefinite, packed storage, 104 real general band, 61 dense, 54 tridiagonal, 67 real symmetric indefinite, full storage, 98 indefinite, packed storage, 104 positive definite, band storage, 86 positive definite, full storage, 74 positive definite, packed storage, 79 positive definite, tridiagonal, 91 ESSL,41 Euclidean norm. 152, 156 example program, 32, 33 EXAMPLESl (directory), 5 EXAMPLES2 (directory), 5 expert driver, 16 description, 27 f77_lapack.mod, 31 f95_lapack.mod, 31 factorization, see also decomposition or elimination in algorithms Cholesky, 160, 162, 166, 168, 171, 175, 217 band storage, 219 packed storage, 218 tridiagonal, 220 complex Hermitian indefinite matrix, 221 indefinite matrix, packed storage, 222 complex symmetric indefinite matrix, 221 indefinite matrix, packed storage, 222 Gauss, 51 generalized QR, 116 generalized RQ, 115 LQ, 107, 227 LU, 51, 54, 58, 61, 65, 67, 213, 214, 216 QL, 228 QR, 107, 110, 146, 151, 227 with column pivoting, 226 real symmetric

249

indefinite matrix, 221 indefinite matrix, packed storage, 222 RQ, 228 Schur, 145, 149, 181, 187, 190, 195 split Cholesky, 236 FAQ, 3 Fortran standard, xvii Fortran 77, xvii, 41 Fortran 95, xvii, 3, 41 wrappers, 3 forward error, 57, 65, 82, 93 bounds, 13 Frequently Asked Questions, see FAQ Gauss, see algorithms and factorization Gauss-Markov, see GLM General Gauss-Markov Linear Model Problem, see GLM Generalized QR Factorization, see GQR Generalized RQ Factorization, see GRQ generalized eigenproblem, 236, 237 banded, reduction, 236 nonsymmetric, 20 packed form, 236 generalized least squares, 15 Generalized Nonsymmetric Eigenvalue Problem, see GNEP generalized Schur decomposition, 21 vectors, 20 generalized singular value, 21, 207 Generalized Singular Value Decomposition, see GSVD generalized singular value decomposition special cases, 22 generalized Sylvester equation, 238 Generalized Symmetric Eigenvalue Problem, see GSEP generalized upper Hessenberg form, 237 generic interface blocks, 35 interfaces, 3, 26 GLM, 15 problem, 116 GNEP, 20

250

GQR, 15, 16 GRQ, 15, 16 GSEP, 18 GSVD, 21, see Generalized Singular Value Decomposition, 239 Hermitian, 13 eigenvalue problem, 16 matrices, 30 Hessenberg upper, 232 generalized form, 237 ILAENV, 5 illegal argument, 28 inconsistent shapes, 29 indefinite symmetric, 14 Independent Software Vendor, see ISV INFO, 28 installation, 4 debugging hints, 8 insufficient memory, 29 INTENT attribute IN, 34 INOUT, 34 OUT, 34 INTERFACE statement, 36, 37, 39, 40 interfaces generic, 26 invalid argument, 28 shape, 29 invariant subspace, 17, 20, 145, 149, 234 inverse of a matrix, 214, 218, 219, 222-225 ISV, 7 iterative refinement of the system complex general band, 61 dense, 54 tridiagonal, 67 complex Hermitian indefinite, full storage, 98 indefinite, packed storage, 104 positive definite, band storage, 86 positive definite, full storage, 74 positive definite, packed storage, 79

Index by Keyword positive definite, tridiagonal, 91 complex symmetric indefinite, full storage, 98 indefinite, packed storage, 104 real general band, 61 dense, 54 tridiagonal, 67 real symmetric indefinite, full storage, 98 indefinite, packed storage, 104 positive definite, band storage, 86 positive definite, full storage, 74 positive definite, packed storage, 79 positive definite, tridiagonal, 91 KIND type parameter, 12 la_auxmod.mod, 31 la_precision.mod, 12, 31, 32 LAPACK, xvii, 3, 6, 41 home page, 6 Installation Guide, 6 library, 3 package, 6 test suites, 6 Users' Guide, 16, 18, 20 LAPACK95, xvii, 3, 41 commercial use of, 9 documentation, 26 driver routines, 13 FAQ, 3 home page, 3 naming, 26 source code, 4 test suites, 5 leading diagonal blocks, 239 least squares solution, 107, 110, 112, 115 libblas.a, 31 liblapack.a, 31 Iiblapack95.a, 31 linear equations, 13 linear least squares problem, 3, 13 equality-constrained, 115 generalized, 15 equality-constrained (LSE), 15

Index by Keyword regression model (GLM), 15 weighted, 15 LINPACK, xvii LLS (Linear Least Squares), 13, 14 LOGICAL FUNCTION SELECT, 147 lower bidiagonal form, 234 matrix, 235 LQ factorization, 227 LSE, 15 problem, 115 LU factorization, 11, 213, 214, 216 machine constants returned by LA_LAMCH, 6 dependencies (ILAENV), 5 make.inc, 5 matrices balancing, 232 bidiagonal lower, 235 upper, 235 complex unitary, 145, 149, 181, 187, 195, 204 complex general band, 58, 61 dense, 51, 54 tridiagonal, 65, 67 complex Hermitian, 229 band storage, 229 block diagonal 1 x 1 and 2 x 2, 93, 98, 101, 104 indefinite, 222 indefinite, full storage, 93, 98 indefinite, packed storage, 101, 104, 223 inverse, 218, 222 inverse, packed storage, 219, 223 packed storage, 229 positive definite, 217, 218, 222, 236 positive definite, band storage, 82, 86, 219, 220, 236 positive definite, full storage, 70, 74 positive definite, packed storage, 77, 79, 218, 219, 223, 236

251

positive definite, tridiagonal, 89, 91, 220, 221 complex symmetric block diagonal 1 x 1 and 2 x 2, 93, 98, 101, 104 indefinite, 222 indefinite, full storage, 93, 98 indefinite, packed storage, 101, 104, 223 inverse, 222 inverse, packed storage, 223 effective rank, 112 full rank, 107 general inverse, 214 orthogonal, 227-230, 232, 234-236, 239 packed storage, 230 product, 228 pencil, 20 permutation, 51, 54, 58, 61, 65, 67, 93, 98, 101, 104 quasi-triangular upper, 233, 234 rank deficient, 112 real general band, 58, 61 dense, 51, 54 tridiagonal, 65, 67 real orthogonal, 145, 149, 181, 187, 195, 204 real symmetric, 229 band storage, 229 block diagonal 1 x 1 and 2 x 2 , 93, 98, 101, 104 indefinite, 222 indefinite, full storage, 93, 98 indefinite, packed storage, 101, 104, 223 inverse, 218, 222 inverse, packed storage, 219, 223 packed storage, 229 positive definite, 217, 218, 236 positive definite, band storage, 82, 86, 219, 220, 236 positive definite, full storage, 70, 74 positive definite, packed storage, 77, 79, 218, 219, 236

252 positive definite, tridiagonal, 89, 91, 220, 221 singular value problems complex unitary, 201 real orthogonal, 201 Sylvester equation, 234 transformation generalized singular value, 204 trapezoidal, 239 triangular inverse, 224 packed, inverse, 225 upper, 238 unit lower triangular(L), 51, 54, 58, 61, 65, 67, 70, 74, 77, 79, 82, 86, 89, 91, 93, 98, 101, 104 unitary, 227-230, 232, 234, 235, 239 packed storage, 230 product, 228 upper Hessenberg, 232, 233 trapezoidal, 229 triangular (U), 51, 54, 58, 61, 65, 67, 70, 74, 77, 79, 82, 86, 89, 91, 93, 98, 101, 104 matrix pairs eigenvalues generalized nonsymmetric, 187, 190 singular value generalized, 204 megaflops, 41, 42 memory allocation, 28 minimum norm least squares solution, 14, 107, 110, 112 solution, 13, 110 mirror repositories of netlib, 8 MODULE F77_LAPACK, 31 F95_LAPACK, 31 LA_AUXMOD, 31 LA_PRECISION, 12, 31 MODULE statement, 12 naming scheme, 12 computational routine, 12

Index by Keyword driver routine, 12 LAPACK95, 26 near-singularity, 13 NEP, 17 netlib, 3 mirror repositories, 8 non-negative diagonal elements, 235, 236 nonsymmetric eigenproblem generalized, 20 Nonsymmetric Eigenvalue Problem, see NEP ONLY option, 32-34 operation counts for LAPACK, 43 optimal block size, 41 optional arguments, 3 OPTIONAL attribute, 26, 34 orthogonal matrix, 16 orthonormal basis, 17, 145, 149, 234 columns, 227, 228 rows, 227, 228 over determined system, 13, 14 packed form, see packed storage storage, 14, 30 scheme, 78 partial pivoting with row interchanges, 213, 214, 216 pencil, see matrices performance, 4, 5, 7-9, 41 pivot growth factor, 13, 57 complex general band matrix, 61 dense matrix, 54 real general band matrix, 61 dense matrix, 54 poor performance, 47 positive definite, 14 precision, 11 QL factorization, 228 QR factorization, 32, 227 generalized (GQR), 15

Index by Keyword with column pivoting, 226 quasi-triangular matrix, 233, 234 quotient singular value decomposition, 21 RANDOM_NUMBER, 32, 33 rank deficient of matrix, 112 of argument, 26 README, 5 reciprocal condition number, 57, 82, 93, 189, 199 condition numbers, 189 pivot growth factor, 57 reduction to bidiagonal form, 234 to tridiagonal form, 138, 229 reflectors, see elementary reflectors regression, generalized linear, 15 Relatively Robust Representation, see RRR release-notes, 6 reliability, see test suites residual sum-of-squares, 116 right eigenvectors, 17 singular vectors, 204 row index, 233 interchanges, 59 partial pivoting, 213, 214, 216 RQ factorization, 228 generalized (GRQ), 15 RRR driver, 16 scaling, 156 Schur complex form, 145, 149 decomposition, see factorization factorization, 17, 145, 149, 181, 187, 190, 195, 233, 234 complex, 17 generalized, 20, 238, 239 form, 232 generalized complex form, 181, 187, 190, 195 left vectors, 181, 187, 190, 195

253

real form, 181, 187, 190, 195 right vectors, 181, 187, 190, 195 vectors, 20, 181, 187, 190, 195 real form, 145, 149 vectors, 17, 145, 148, 149, 232 selected cluster of eigenvalues, 234 SEP, 16 simple driver, 13, 16, 18 single shift, 237 singular, 20 vectors, 18, 112, 201, 236 compact form, 236 left, 18, 201 right, 18, 112, 201, 204 singular value, 18, 112, 201 bidiagonal factor, 231 decomposition, 18, 113, 201 generalized, 21, 204 greatest, 113 problems, 3 singular value decomposition, 14 generalized, 21-23 generalized, special cases, 22 quotient, 21 spectral factorization, 16 split Cholesky factorization, 236 SRC (directory), 5 stability, 47 standard form, 236 packed form, 236 storage scheme, 30 band, 133 packed, 78 subspaces deflating, 20 invariant, 20 SUNPERF, 41 support, 9 SVD, see singular value decomposition, 235, 236 Sylvester equation, 238

254 matrix equation, 234 symmetric, 13 eigenproblems (SEP), 16 matrices, 30 Symmetric Eigenvalue Problem, see SEP system of linear equations, 3 backward error, 214-217, 222 band storage, 220 packed storage, 219, 223 triangular band, 226 triangular matrix, 224 triangular packed, 225 tridiagorial, 221 condition number, 215 equilibration, 214, 215, 218 band storage, 220 packed storage, 219 error bounds, 214-217, 222 band storage, 220 packed storage, 219, 223 triangular band, 226 triangular matrix, 224 triangular packed, 225 tridiagonal, 221 scaling, 214, 215, 218 band storage, 220 packed storage, 219 solution, 213, 214, 216, 217 band storage, 219 packed storage, 218 symmetric indefinite, 221 symmetric indefinite, packed storage, 223 triangular band, 225 triangular matrix, 224 triangular packed, 225 tridiagonal, 221 test suites, 5, 6, 47 TESTING (directory), 5 TIMING (directory), 5 transformation backward, 232, 237 equivalence orthogonal, 238, 239 unitary, 238, 239

Index by Keyword orthogonal, 110, 229, 232, 234, 235, 237 similarity orthogonal, 229 orthogonal, band storage, 229 orthogonal, packed storage, 229 unitary, 229 unitary, band storage, 229 unitary, packed storage, 229 unitary, 110, 229, 232, 234, 235, 237 trapezoidal matrices, 239 triangular factor Cholesky, 162, 168, 171 matrices, 30 tridiagonal form, 11 matrices, 30 troubleshooting, 41 underdetermined system, 13, 14 unitary matrix, 16, 138 upper bidiagonal form, 234, 235 matrix, 235 Hessenberg matrix, 232, 233 trapezoidal matrix, 229 triangular form, 229 matrices, 238 USE F77_LAPACK, 31, 33, 34 F95.LAPACK, 31, 32 LA.AUXMOD, 31, 34 LA.PRECISION, 31-34 DP, 12 SP, 12 USE statement, 12, 32 vendor supplied BLAS, 7 weighted linear least squares, 116 working precision (WP), 32 zero-sized array, 25

This page intentionally left blank

Index by Routine Name DLAMCH, 40

LA.GESVD, 18, 19, 42, 43, 45, 201 LA_GESVX, 14, 54 LAJ3ETRF, 213 LA_GETRI, 214 LA_GETRS, 213 LA_GGBAK, 237 LA_GGBAL, 237 LA_GGES, 21, 23, 181 LA_GGESX, 21, 23, 187 LA_GGEV, 21, 23, 190 LA.GGEVX, 21, 23, 195 LA_GGGLM, 15, 16, 116 LAJ3GHRD, 237 LA_GGLSE, 16, 114 LA.GGSVD, 23, 204 LA_GGSVP, 239 LA.GTCON, 216 LA_GTRFS, 216 LA_GTSV, 14, 65 LA_GTSVX, 14, 67 LA_GTTRF, 215 LAJ3TTRS, 216 LA.HBEV, 19, 132 LA_HBEVD, 19, 132 LA_HBEVX, 19, 135 LA.HBGST, 236 LA_HBGV, 23, 174 LA_HBGVD, 23, 174 LA.HBGVX, 23, 178 LA_HBTRD, 229 LA_HECON, 221 LA_HEEV, 19, 119 LA_HEEVD, 19, 119 LA_HEEVR, 19, 124 LA_HEEVX, 19, 122 LA.HEGST, 236 LA.HEGV, 23, 159

ERINFO, 28, 29 ILAENV, 5, 34 LA_BDSDC, 235 LA_BDSQR, 235 LA_GBBRD, 235 LA_GBCON, 215 LA_GBEQU, 215 LA_GBRFS, 215 LA_GBSV, 14, 57 LA.GBSVX, 14, 61 LA_GBTRF, 214 LA_GBTRS, 214 LA_GEBAK, 232 LA_GEBAL, 232 LA_GEBRD, 234 LA_GECON, 213 LA_GEEQU, 214 LA_GEES, 17, 19, 145 LA.GEESX, 17, 19, 149 LA_GEEV, 17, 19, 42-44, 152 LA.GEEVX, 17, 19, 156 LA_GEHRD, 231 LA.GELQF, 227 LA_GELS, 14, 15, 107 LA_GELSD, 14, 15, 112 LA_GELSS, 14, 15, 112 LA.GELSY, 14, 15, 110 LA_GEQLF, 227 LA_GEQP3, 226 LA.GEQRF, 32, 33, 226 LA_GERFS, 214 LA.GERQF, 228 LA_GESDD, 18, 19, 43, 45, 46, 201 LA.GESV, 14, 28, 31, 32, 42, 43, 51

256

Index by Routine Name LA_PBCON, 219 LA.HEGVD, 23, 159 LA_PBEQU, 220 LA.HEGVX, 23, 163 LA_PBRFS, 220 LA_HERFS, 222 LA_PBSTF, 236 LAJHESV, 14, 93 LA_PBSV, 14, 82 LA_HESVX, 14, 98 LA_PBSVX, 14, 85 LA_HETRD, 229 LA_PBTRF, 219 LA_HETRF, 221 LA_PBTRS, 219 LA_HETRI, 222 LA_POCON, 217 LA_HETRS, 221 LA_POEQU, 218 LA_HGEQZ, 237 LAJPORFS, 217 LA-HPCON, 223 LA_POSV, 14, 28, 70 LA_HPEV, 19, 126 LA_POSVX, 14, 73 LA_HPEVD. 19, 126 LA_POTRF, 216 LA_HPEVX, 19, 130 LA_POTRI, 217 LA_HPGST, 236 LA_POTRS, 217 LA_HPGV, 23, 166 LA_PPCON, 218 LA_HPGVD, 23, 166 LA_PPEQU, 219 LA_HPGVX, 23, 171 LA_PPRFS, 218 LA_HPRFS, 223 LA_PPSV, 14, 77 LA_HPSV, 14, 101 LA_PPSVX, 14, 79 LA_HPSVX, 14, 104 LAJPPTRF, 218 LA_HPTRD, 229 LA_PPTRI, 219 LA_HPTRF, 222 LA.PPTRS, 218 LA.HPTRI, 223 LA_PTCON, 221 LA_HPTRS, 222 LA_PTEQR, 231 LA_HSEIN, 233 LAJPTRFS, 221 LA_HSEQR, 232 LA_LAMCH, 5, 40, 123, 125, 131, 137, 141,LA_PTSV, 14, 89 LA_PTSVX, 14, 91 143, 165, 173, 180 LA_PTTRF, 220 LA_OPGTR, 230 LA_PTTRS, 220 LA_OPMTR, 230 LA_SBEV, 19, 132 LA_ORGBR, 235 LA_SBEVD, 19, 132 LA_ORGLQ, 227 LA_SBEVX, 19, 135 LA_ORGQL, 228 LA_SBGST, 236 LA_ORGQR, 227 LA_SBGV, 23, 174 LA_ORGRQ, 228 LA_SBGVD, 23, 174 LA_ORGTR, 229 LA_SBGVX, 23, 178 LA_ORMBR, 235 LA_SBTRD, 229 LA_ORMHR, 232 LA_SPCON, 223 LA_ORMLQ, 227 LA-SPEV, 19, 126 LA_ORMQL, 228 LA_SPEVD, 19, 126 LA.ORMQR, 227 LA_SPEVX, 19, 130 LA_ORMRQ, 228 LA_SPGST, 236 LA_ORMRZ, 229 LA.SPGV, 23, 166 LA_ORMTR, 229

257

Index by Routine Name

258

LA_SPGVD, 23, 166 LA.SPGVX, 23, 171 LA_SPRFS, 223 LA_SPSV, 14, 101 LAJSPSVX, 14, 104 LA.SPTRD, 229 LA.SPTRF, 222 LA.SPTRI, 223 LA_SPTRS, 222 LA.STEBZ, 231 LA.STEDC, 230 LA.STEGR, 231 LA-STEIN, 231 LAJ3TEQR, 230 LA_STERF, 230 LA.STEV, 19, 138 LA_STEVD, 19, 138 LA.STEVR, 19, 142 LA.STEVX, 19, 140 LA_SYCON, 221 LA_SYEV, 19, 33, 119 LA_SYEVD, 19, 119 LA_SYEVR, 19, 124 LA.SYEVX, 19, 122 LA.SYGST, 236 LA.SYGV, 23, 159 LA.SYGVD, 23, 159 LA_SYGVX, 23, 163 LA.SYRFS, 222 LA.SYSV, 14, 93 LA.SYSVX, 14, 98 LA_SYTRD, 229 LA_SYTRF, 221 LAJ3YTRI, 222 LAJ3YTRS, 221 LA.TBCON, 225 LA.TBRFS, 226 LA_TBTRS, 225 LA_TGEVC, 237 LA.TGEXC, 238 LA.TGSEN, 238 LA.TGSJA, 239 LA.TGSNA, 238 LA.TGSYL, 238 LA.TPCON, 225

LA.TPRFS, 225 LA.TPTRI, 225 LA_TPTRS, 224 LA.TRCON, 224 LA.TREVC, 233 LA.TREXC, 233 LA.TRRFS, 224 LA.TRSEN, 234 LA.TRSNA, 234 LA_TRSYL, 233 LA_TRTRI, 224 LA_TRTRS, 223 LA.TZRZF, 228 LA.UNGBR, 235 LA_UNGHR, 232 LA.UNGLQ, 227 LA.UNGQL, 228 LA.UNGQR, 227 LA.UNGRQ, 228 LAJJNGTR, 229 LA_UNMBR, 235 LA.UNMHR, 232 LA.UNMLQ, 227 LA.UNMQL, 228 LAJJNMQR, 227 LA_UNMRQ, 228 LA.UNMRZ, 229 LA.UNMTR, 229 LA_UPGTR, 230 LAJJPMTR, 230 SLAMCH, 40