Engineering and Scientific Subroutine Library for AIX, Version 4 Release 1, and Linux on pSeries, Version 4 Release 1: Guide and Reference

About This Book . . . . . . . . . . . xi
How to Use This Book . . . . . . . . . . . xi
How to Find a Subroutine Description . . . . . xii
Where to Find Related Publications . . . . . . xii
How to Look Up a Bibliography Reference . . . xiii
Special Terms . . . . . . . . . . . . . xiii
Short and Long Precision . . . . . . . . xiii
Subroutines and Subprograms . . . . . . . xiii
How to Interpret the Subroutine Names with a
Prefix Underscore . . . . . . . . . . . . xiii
Abbreviated Names . . . . . . . . . . . xiii
Fonts . . . . . . . . . . . . . . . . xiv
Special Notations and Conventions . . . . . . xiv
Scalar Data . . . . . . . . . . . . . xiv
Vectors . . . . . . . . . . . . . . . xv
Matrices . . . . . . . . . . . . . . xv
Sequences . . . . . . . . . . . . . . xv
Arrays . . . . . . . . . . . . . . . xvi
Special Characters, Symbols, Expressions, and
Abbreviations . . . . . . . . . . . . . xvii
How to Interpret the Subroutine Descriptions . . . xix
Description . . . . . . . . . . . . . xix
Syntax . . . . . . . . . . . . . . . xix
On Entry . . . . . . . . . . . . . . xix
On Return . . . . . . . . . . . . . . xx
Notes . . . . . . . . . . . . . . . xx
Function . . . . . . . . . . . . . . xx
Special Usage. . . . . . . . . . . . . xx
Error Conditions . . . . . . . . . . . xx
Examples . . . . . . . . . . . . . . xx
Summary of Changes . . . . . . . . xxi
What’s New for ESSL Version 4 Release 1 .
 .
 .
 . xxi
Future Migration . . . . . . . . .
 .
 .
 . xxi
Part 1. Guide Information . . . . . . 1
Chapter 1. Introduction and
Requirements . . . . . . . . . . . . 3
Overview of ESSL . . . . . . . . . . . . 3
Performance and Functional Capability . . . . 3
Usability . . . . . . . . . . . . . . . 3
The Variety of Mathematical Functions . . . . 4
ESSL—Processing Capabilities . . . . . . . 5
Accuracy of the Computations . . . . . . . 6
High Performance of ESSL . . . . . . . . . 6
The Fortran Language Interface to the Subroutines 7
Software and Hardware Products That Can Be Used
with ESSL . . . . . . . . . . . . . . . 7
ESSL for AIX—Hardware and Software . . . . 7
ESSL for Linux—Hardware and Software . . . . 8
Software Products for Displaying ESSL
Documentation . . . . . . . . . . . . . 9
ESSL Internet Resources . . . . . . . . . . 10
© Copyright IBM Corp. 1991, 2003
Getting on the ESSL Mailing List . . . .
 .
 .
 .
 10
List of ESSL Subroutines . . . . . . .
 .
 .
 .
 11
Linear Algebra Subprograms . . . .
 .
 .
 .
 11
Matrix Operations . . . . . . . .
 .
 .
 .
 14
Linear Algebraic Equations . . . . .
 .
 .
 .
 15
Eigensystem Analysis . . . . . . .
 .
 .
 .
 19
Fourier Transforms, Convolutions and
Correlations, and Related Computations .
 .
 .
 .
 19
Sorting and Searching . . . . . . .
 .
 .
 .
 21
Interpolation . . . . . . . . . .
 .
 .
 .
 21
Numerical Quadrature. . . . . . .
 .
 .
 .
 21
Random Number Generation . . . .
 .
 .
 .
 22
Utilities . . . . . . . . . . . .
 .
 .
 .
 22
Chapter 2. Planning Your Program . . . 25
Selecting an ESSL Subroutine . . . . . . . .
 25
Which ESSL Library Do You Want to Use? . . .
 25
What Type of Data Are You Processing in Your
Program? . . . . . . . . . . . . . .
 28
How Is Your Data Structured? And What Storage
Technique Are You Using? . . . . . . . .
 28
What about Performance and Accuracy? . . . .
 29
Avoiding Conflicts with Internal ESSL Routine
Names That are Exported. . . . . . . . . .
 29
Setting Up Your Data . . . . . . . . . . .
 29
How Do You Set Up Your Scalar Data? . . . .
 29
How Do You Set Up Your Arrays? . . . . . .
 29
How Should Your Array Data Be Aligned? . . .
 30
What Storage Mode Should You Use for Your
Data? . . . . . . . . . . . . . . .
 30
How Do You Convert from One Storage Mode to
Another? . . . . . . . . . . . . . .
 30
Setting Up Your ESSL Calling Sequences . . . .
 31
What Is an Input-Output Argument? . . . . .
 31
What Are the General Rules to Follow when
Specifying Data for the Arguments? . . . . .
 31
What Happens When a Value of 0 Is Specified
for N? . . . . . . . . . . . . . . .
 31
How Do You Specify the Beginning of the Data
Structure in the ESSL Calling Sequence? . . . .
 32
Using Auxiliary Storage in ESSL . . . . . . .
 32
Dynamic Allocation of Auxiliary Storage . . .
 33
Setting Up Auxiliary Storage When Dynamic
Allocation Is Not Used . . . . . . . . .
 33
Who Do You Want to Calculate the Size? You or
ESSL? . . . . . . . . . . . . . . .
 33
How Do You Calculate the Size Using the
Formulas? . . . . . . . . . . . . . .
 33
How Do You Get ESSL to Calculate the Size
Using ESSL Error Handling?. . . . . . . .
 34
Providing a Correct Transform Length to ESSL . .
 38
What ESSL Subroutines Require Transform
Lengths? . . . . . . . . . . . . . .
 38
Who Do You Want to Calculate the Length? You
or ESSL? . . . . . . . . . . . . . .
 38
iii
How Do You Calculate the Length Using the
Table or Formula? . . . . . . . . . .
 . 39
How Do You Get ESSL to Calculate the Length
Using ESSL Error Handling?. . . . . . .
 . 39
Getting the Best Accuracy . . . . . . . .
 . 43
What Precisions Do ESSL Subroutines Operate
On? . . . . . . . . . . . . . . .
 . 43
How does the Nature of the ESSL Computation
Affect Accuracy?. . . . . . . . . . .
 . 44
What Data Type Standards Are Used by ESSL,
and What Exceptions Should You Know About?
 . 44
How is Underflow Handled? . . . . . .
 . 44
Where Can You Find More Information on
Accuracy? . . . . . . . . . . . . .
 . 45
Getting the Best Performance . . . . . . .
 . 45
What General Coding Techniques Can You Use
to Improve Performance? . . . . . . . .
 . 45
Where Can You Find More Information on
Performance? . . . . . . . . . . . .
 . 46
Dealing with Errors when Using ESSL . . . .
 . 46
What Can You Do about Program Exceptions? .
 . 46
What Can You Do about ESSL Input-Argument
Errors? . . . . . . . . . . . . . .
 . 46
What Can You Do about ESSL Computational
Errors? . . . . . . . . . . . . . .
 . 47
What Can You Do about ESSL Resource Errors?
 49
What Can You Do about ESSL Attention
Messages? . . . . . . . . . . . . .
 . 49
How Do You Control Error Handling by Setting
Values in the ESSL Error Option Table? . . .
 . 50
How does Error Handling Work in a Threaded
Environment? . . . . . . . . . . .
 . 52
Where Can You Find More Information on
Errors? . . . . . . . . . . . . . .
 . 52
Chapter 3. Setting Up Your Data
Structures . . . . . . . . . . . . . 55
Concepts . . . . . . . . . . . . . . .
 55
Vectors . . . . . . . . . . . . . . . .
 55
Transpose of a Vector . . . . . . . . . .
 56
Conjugate Transpose of a Vector . . . . . .
 56
In Storage . . . . . . . . . . . . . .
 57
How Stride Is Used for Vectors . . . . . . .
 58
Sparse Vector . . . . . . . . . . . . .
 60
Matrices . . . . . . . . . . . . . . .
 61
Transpose of a Matrix . . . . . . . . . .
 62
Conjugate Transpose of a Matrix . . . . . .
 62
In Storage . . . . . . . . . . . . . .
 62
How Leading Dimension Is Used for Matrices . .
 63
Symmetric Matrix . . . . . . . . . . .
 64
Positive Definite or Negative Definite Symmetric
Matrix . . . . . . . . . . . . . . .
 69
Symmetric Indefinite Matrix . . . . . . . .
 69
Complex Hermitian Matrix . . . . . . . .
 69
Positive Definite or Negative Definite Complex
Hermitian Matrix . . . . . . . . . . .
 70
Positive Definite or Negative Definite Symmetric
Toeplitz Matrix . . . . . . . . . . . .
 70
Positive Definite or Negative Definite Complex
Hermitian Toeplitz Matrix . . . . . . . .
 71
Triangular Matrix . . . . . . . . . . .
 72
iv
 ESSL for AIX, Version 4 Release 1, and Linux on pSeries, VersionGeneral Band Matrix . . . . . . . . .
 .
 75
Symmetric Band Matrix . . . . . . . .
 .
 81
Positive Definite Symmetric Band Matrix . .
 .
 83
Complex Hermitian Band Matrix . . . . .
 .
 83
Triangular Band Matrix . . . . . . . .
 .
 84
General Tridiagonal Matrix . . . . . . .
 .
 88
Symmetric Tridiagonal Matrix . . . . . .
 .
 89
Positive Definite Symmetric Tridiagonal Matrix
 89
Sparse Matrix. . . . . . . . . . . .
 . 90
Sequences . . . . . . . . . . . . .
 . 101
Real and Complex Elements in Storage . . .
 . 101
One-Dimensional Sequences . . . . . .
 . 101
Two-Dimensional Sequences . . . . . .
 . 101
Three-Dimensional Sequences . . . . . .
 . 102
How Stride Is Used for Three-Dimensional
Sequences . . . . . . . . . . . .
 . 104
Chapter 4. Coding Your Program . . . 107
Fortran Programs . . . . . . . . . . . .
 107
Calling ESSL Subroutines and Functions in
Fortran . . . . . . . . . . . . . .
 107
Setting Up a User-Supplied Subroutine for ESSL
in Fortran . . . . . . . . . . . . .
 107
Setting Up Scalar Data in Fortran. . . . . .
 108
Setting Up Arrays in Fortran . . . . . . .
 108
Creating Multiple Threads and Calling ESSL
from Your Fortran Program . . . . . . . .
 113
Handling Errors in Your Fortran Program . . .
 114
Example of Handling Errors in a Multithreaded
Application Program . . . . . . . . . .
 122
C Programs . . . . . . . . . . . . . .
 124
Calling ESSL Subroutines and Functions in C
 124
Passing Arguments in C . . . . . . . . .
 125
Setting Up a User-Supplied Subroutine for ESSL
in C . . . . . . . . . . . . . . .
 126
Setting Up Scalar Data in C . . . . . . .
 126
Setting Up Complex Data Types in C . . . .
 127
Using Logical Data in C . . . . . . . . .
 128
Setting Up Arrays in C . . . . . . . . .
 128
Creating Multiple Threads and Calling ESSL
from Your C Program . . . . . . . . .
 129
Handling Errors in Your C Program . . . . .
 131
C++ Programs . . . . . . . . . . . . .
 140
Calling ESSL Subroutines and Functions in C++
 140
Passing Arguments in C++ . . . . . . . .
 140
Setting Up a User-Supplied Subroutine for ESSL
in C++ . . . . . . . . . . . . . .
 142
Setting Up Scalar Data in C++ . . . . . . .
 142
Using Complex Data in C++ . . . . . . .
 143
Using Logical Data in C++ . . . . . . . .
 145
Setting Up Arrays in C++ . . . . . . . .
 145
Creating Multiple Threads and Calling ESSL
from Your C++ Program . . . . . . . . .
 145
Handling Errors in Your C++ Program . . . .
 147
Chapter 5. Processing Your Program
 157
Processing Your Program on AIX . . . .
 .
 .
 .
 157
Dynamic Linking Versus Static Linking .
 .
 .
 .
 157
Fortran Program Procedures . . . .
 .
 .
 .
 157
C Program Procedures . . . . . .
 .
 .
 .
 158
4 Release 1 Guide and Reference
C++ Program Procedures . . . . .
 .
 .
 .
 159
Processing Your Program on Linux . . .
 .
 .
 .
 160
Dynamic Linking Versus Static Linking .
 .
 .
 .
 161
Fortran Program Procedures . . . .
 .
 .
 .
 161
C Program Procedures . . . . . .
 .
 .
 .
 162
C++ Program Procedures . . . . .
 .
 .
 .
 162
Chapter 6. Migrating Your Programs
 165
Migrating ESSL Version 3 Release 3 Programs to
Version 4 Release 1 . . . . . . . . . . .
 165
ESSL Subroutines . . . . . . . . . . .
 165
Planning for Future Migration . . . . . . . .
 165
Migrating between IBM Eserver pSeries and
RS/6000 Processors . . . . . . . . . . .
 166
Auxiliary Storage . . . . . . . . . . .
 166
Bitwise-Identical Results . . . . . . . . .
 166
Migrating from Other Libraries to ESSL . . . .
 166
Migrating from ESSL/370 . . . . . . . .
 166
Migrating from Another IBM Subroutine Library
 166
Migrating from LAPACK . . . . . . . .
 166
Migrating from a Non-IBM Subroutine Library
 167
Chapter 7. Handling Problems . . . . 169
Where to Find More Information About Errors
 .
 .
 169
Getting Help from IBM Support . . . . .
 .
 .
 169
National Language Support . . . . . .
 .
 .
 170
Dealing with Errors . . . . . . . . .
 .
 .
 171
Program Exceptions . . . . . . . .
 .
 .
 171
ESSL Input-Argument Error Messages . .
 .
 .
 171
ESSL Computational Error Messages . .
 .
 .
 172
ESSL Resource Error Messages . . . .
 .
 .
 172
ESSL Informational and Attention Messages
 .
 .
 173
Miscellaneous Error Messages . . . . .
 .
 .
 175
Messages . . . . . . . . . . . . .
 .
 .
 176
Message Conventions . . . . . . .
 .
 .
 176
Input-Argument Error Messages(2001-2099)
 .
 .
 176
Computational Error Messages(2100-2199) .
 .
 .
 182
Input-Argument Error Messages(2200-2299)
 .
 .
 184
Resource Error Messages(2400-2499) . . .
 .
 .
 184
Informational and Attention Error
Messages(2600-2699) . . . . . . . .
 .
 . 184
Miscellaneous Error Messages(2700-2799) .
 .
 . 184
Part 2. Reference Information . . . 187
Chapter 8. Linear Algebra
Subprograms . . . . . . . . . . . 189
Overview of the Linear Algebra Subprograms
 .
 . 189
Vector-Scalar Linear Algebra Subprograms
 .
 . 189
Sparse Vector-Scalar Linear Algebra
Subprograms . . . . . . . . . .
 .
 . 190
Matrix-Vector Linear Algebra Subprograms
 .
 . 191
Sparse Matrix-Vector Linear Algebra
Subprograms . . . . . . . . . .
 .
 .
 192
Use Considerations . . . . . . . . .
 .
 .
 192
Performance and Accuracy Considerations .
 .
 .
 192
Vector-Scalar Subprograms . . . . . .
 .
 .
 194
ISAMAX, IDAMAX, ICAMAX, and
IZAMAX—Position of the First or Last Occurrence
of the Vector Element Having the Largest
Magnitude . . . . . . . . . . . . . .
 195
ISAMIN and IDAMIN—Position of the First or
Last Occurrence of the Vector Element Having
Minimum Absolute Value . . . . . . . . .
 198
ISMAX and IDMAX—Position of the First or Last
Occurrence of the Vector Element Having the
Maximum Value . . . . . . . . . . . .
 201
ISMIN and IDMIN—Position of the First or Last
Occurrence of the Vector Element Having
Minimum Value . . . . . . . . . . . .
 204
SASUM, DASUM, SCASUM, and DZASUM—Sum
of the Magnitudes of the Elements in a Vector . .
 207
SAXPY, DAXPY, CAXPY, and ZAXPY—Multiply a
Vector X by a Scalar, Add to a Vector Y, and Store
in the Vector Y . . . . . . . . . . . . .
 210
SCOPY, DCOPY, CCOPY, and ZCOPY—Copy a
Vector . . . . . . . . . . . . . . . .
 213
SDOT, DDOT, CDOTU, ZDOTU, CDOTC, and
ZDOTC—Dot Product of Two Vectors . . . . .
 216
SNAXPY and DNAXPY—Compute SAXPY or
DAXPY N Times . . . . . . . . . . . .
 220
SNDOT and DNDOT—Compute Special Dot
Products N Times . . . . . . . . . . . .
 225
SNRM2, DNRM2, SCNRM2, and
DZNRM2—Euclidean Length of a Vector with
Scaling of Input to Avoid Destructive Underflow
and Overflow . . . . . . . . . . . . .
 230
SNORM2, DNORM2, CNORM2, and
ZNORM2—Euclidean Length of a Vector with No
Scaling of Input . . . . . . . . . . . .
 233
SROTG, DROTG, CROTG, and ZROTG—Construct
a Givens Plane Rotation . . . . . . . . . .
 236
SROT, DROT, CROT, ZROT, CSROT, and
ZDROT—Apply a Plane Rotation. . . . . . .
 242
SSCAL, DSCAL, CSCAL, ZSCAL, CSSCAL, and
ZDSCAL—Multiply a Vector X by a Scalar and
Store in the Vector X . . . . . . . . . . .
 246
SSWAP, DSWAP, CSWAP, and
ZSWAP—Interchange the Elements of Two Vectors .
 249
SVEA, DVEA, CVEA, and ZVEA—Add a Vector X
to a Vector Y and Store in a Vector Z . . . . .
 252
SVES, DVES, CVES, and ZVES—Subtract a Vector
Y from a Vector X and Store in a Vector Z . . . .
 256
SVEM, DVEM, CVEM, and ZVEM—Multiply a
Vector X by a Vector Y and Store in a Vector Z . .
 260
SYAX, DYAX, CYAX, ZYAX, CSYAX, and
ZDYAX—Multiply a Vector X by a Scalar and Store
in a Vector Y . . . . . . . . . . . . .
 264
SZAXPY, DZAXPY, CZAXPY, and
ZZAXPY—Multiply a Vector X by a Scalar, Add to
a Vector Y, and Store in a Vector Z . . . . . .
 267
Sparse Vector-Scalar Subprograms . . . . . .
 270
SSCTR, DSCTR, CSCTR, ZSCTR—Scatter the
Elements of a Sparse Vector X in
Compressed-Vector Storage Mode into Specified
Elements of a Sparse Vector Y in Full-Vector
Storage Mode . . . . . . . . . . . . .
 271
Contents
 v
SGTHR, DGTHR, CGTHR, and ZGTHR—Gather
Specified Elements of a Sparse Vector Y in
Full-Vector Storage Mode into a Sparse Vector X in
Compressed-Vector Storage Mode . . . . . .
 274
SGTHRZ, DGTHRZ, CGTHRZ, and
ZGTHRZ—Gather Specified Elements of a Sparse
Vector Y in Full-Vector Mode into a Sparse Vector
X in Compressed-Vector Mode, and Zero the Same
Specified Elements of Y . . . . . . . . . .
 277
SAXPYI, DAXPYI, CAXPYI, and
ZAXPYI—Multiply a Sparse Vector X in
Compressed-Vector Storage Mode by a Scalar, Add
to a Sparse Vector Y in Full-Vector Storage Mode,
and Store in the Vector Y . . . . . . . . .
 280
SDOTI, DDOTI, CDOTUI, ZDOTUI, CDOTCI, and
ZDOTCI—Dot Product of a Sparse Vector X in
Compressed-Vector Storage Mode and a Sparse
Vector Y in Full-Vector Storage Mode . . . . .
 283
Matrix-Vector Subprograms . . . . . . . .
 286
SGEMV, DGEMV, CGEMV, ZGEMV, SGEMX,
DGEMX, SGEMTX, and DGEMTX—Matrix-Vector
Product for a General Matrix, Its Transpose, or Its
Conjugate Transpose . . . . . . . . . . .
 287
SGER, DGER, CGERU, ZGERU, CGERC, and
ZGERC—Rank-One Update of a General Matrix. .
 297
SSPMV, DSPMV, CHPMV, ZHPMV, SSYMV,
DSYMV, CHEMV, ZHEMV, SSLMX, and
DSLMX—Matrix-Vector Product for a Real
Symmetric or Complex Hermitian Matrix . . . .
 304
SSPR, DSPR, CHPR, ZHPR, SSYR, DSYR, CHER,
ZHER, SSLR1, and DSLR1 —Rank-One Update of
a Real Symmetric or Complex Hermitian Matrix. .
 312
SSPR2, DSPR2, CHPR2, ZHPR2, SSYR2, DSYR2,
CHER2, ZHER2, SSLR2, and DSLR2—Rank-Two
Update of a Real Symmetric or Complex Hermitian
Matrix . . . . . . . . . . . . . . . .
 319
SGBMV, DGBMV, CGBMV, and
ZGBMV—Matrix-Vector Product for a General
Band Matrix, Its Transpose, or Its Conjugate
Transpose . . . . . . . . . . . . . .
 327
SSBMV, DSBMV, CHBMV, and
ZHBMV—Matrix-Vector Product for a Real
Symmetric or Complex Hermitian Band Matrix . .
 333
STRMV, DTRMV, CTRMV, ZTRMV, STPMV,
DTPMV, CTPMV, and ZTPMV—Matrix-Vector
Product for a Triangular Matrix, Its Transpose, or
Its Conjugate Transpose . . . . . . . . . .
 338
STBMV, DTBMV, CTBMV, and
ZTBMV—Matrix-Vector Product for a Triangular
Band Matrix, Its Transpose, or Its Conjugate
Transpose . . . . . . . . . . . . . .
 344
Sparse Matrix-Vector Subprograms . . . . . .
 349
DSMMX—Matrix-Vector Product for a Sparse
Matrix in Compressed-Matrix Storage Mode . . .
 350
DSMTM—Transpose a Sparse Matrix in
Compressed-Matrix Storage Mode . . . . . .
 353
DSDMX—Matrix-Vector Product for a Sparse
Matrix or Its Transpose in Compressed-Diagonal
Storage Mode . . . . . . . . . . . . .
 357
Chapter 9. Matrix Operations . . . . . 361
vi
 ESSL for AIX, Version 4 Release 1, and Linux on pSeries, VersionOverview of the Matrix Operation Subroutines . .
 361
Use Considerations . . . . . . . . . . .
 362
Specifying Normal, Transposed, or Conjugate
Transposed Input Matrices . . . . . . . .
 362
Transposing or Conjugate Transposing: . . . .
 362
Performance and Accuracy Considerations . . .
 363
In General . . . . . . . . . . . . .
 363
For Large Matrices . . . . . . . . . .
 363
For Combined Operations . . . . . . . .
 363
Matrix Operation Subroutines . . . . . . .
 364
SGEADD, DGEADD, CGEADD, and
ZGEADD—Matrix Addition for General Matrices
or Their Transposes . . . . . . . . . . .
 365
SGESUB, DGESUB, CGESUB, and
ZGESUB—Matrix Subtraction for General Matrices
or Their Transposes . . . . . . . . . . .
 371
SGEMUL, DGEMUL, CGEMUL, and
ZGEMUL—Matrix Multiplication for General
Matrices, Their Transposes, or Conjugate
Transposes . . . . . . . . . . . . . .
 377
SGEMMS, DGEMMS, CGEMMS, and
ZGEMMS—Matrix Multiplication for General
Matrices, Their Transposes, or Conjugate
Transposes Using Winograd’s Variation of
Strassen’s Algorithm . . . . . . . . . . .
 386
SGEMM, DGEMM, CGEMM, and
ZGEMM—Combined Matrix Multiplication and
Addition for General Matrices, Their Transposes, or
Conjugate Transposes . . . . . . . . . .
 391
SSYMM, DSYMM, CSYMM, ZSYMM, CHEMM,
and ZHEMM—Matrix-Matrix Product Where One
Matrix is Real or Complex Symmetric or Complex
Hermitian . . . . . . . . . . . . . .
 399
STRMM, DTRMM, CTRMM, and
ZTRMM—Triangular Matrix-Matrix Product . . .
 406
SSYRK, DSYRK, CSYRK, ZSYRK, CHERK, and
ZHERK—Rank-K Update of a Real or Complex
Symmetric or a Complex Hermitian Matrix . . .
 412
SSYR2K, DSYR2K, CSYR2K, ZSYR2K, CHER2K,
and ZHER2K—Rank-2K Update of a Real or
Complex Symmetric or a Complex Hermitian
Matrix . . . . . . . . . . . . . . . .
 418
SGETMI, DGETMI, CGETMI, and
ZGETMI—General Matrix Transpose (In-Place) . .
 425
SGETMO, DGETMO, CGETMO, and
ZGETMO—General Matrix Transpose
(Out-of-Place) . . . . . . . . . . . . .
 428
Chapter 10. Linear Algebraic
Equations . . . . . . . . . . . . . 431
Overview of the Linear Algebraic Equation
Subroutines . . . . . . . . . . . . .
 . 431
Dense Linear Algebraic Equation Subroutines
 431
Banded Linear Algebraic Equation Subroutines
 433
Sparse Linear Algebraic Equation Subroutines
 433
Linear Least Squares Subroutines . . . . .
 . 434
Dense and Banded Linear Algebraic Equation
Considerations . . . . . . . . . . . .
 .
 434
Use Considerations . . . . . . . . .
 .
 434
Performance and Accuracy Considerations .
 .
 435
Sparse Matrix Direct Solver Considerations . .
 .
 435
4 Release 1 Guide and Reference
Use Considerations . . . . . . . . . .
 435
Performance and Accuracy Considerations . .
 435
Sparse Matrix Skyline Solver Considerations . . .
 436
Use Considerations . . . . . . . . . .
 436
Performance and Accuracy Considerations . .
 436
Sparse Matrix Iterative Solver Considerations . .
 437
Use Considerations . . . . . . . . . .
 437
Performance and Accuracy Considerations . .
 437
Linear Least Squares Considerations. . . . . .
 438
Use Considerations . . . . . . . . . .
 438
Performance and Accuracy Considerations . .
 438
Dense Linear Algebraic Equation Subroutines
 439
SGESV, DGESV, CGESV, ZGESV—General Matrix
Factorization and Multiple Right-Hand Side Solve .
 440
SGETRF, DGETRF, CGETRF and
ZGETRF—General Matrix Factorization . . . .
 444
SGETRS, DGETRS, CGETRS, and
ZGETRS—General Matrix Multiple Right-Hand
Side Solve . . . . . . . . . . . . . .
 448
SGEF, DGEF, CGEF, and ZGEF—General Matrix
Factorization . . . . . . . . . . . . .
 452
SGES, DGES, CGES, and ZGES—General Matrix,
Its Transpose, or Its Conjugate Transpose Solve . .
 455
SGESM, DGESM, CGESM, and ZGESM—General
Matrix, Its Transpose, or Its Conjugate Transpose
Multiple Right-Hand Side Solve . . . . . . .
 459
SGEFCD and DGEFCD—General Matrix
Factorization, Condition Number Reciprocal, and
Determinant . . . . . . . . . . . . . .
 464
SPPSV and DPPSV—Positive Definite Real
Symmetric Matrix Factorization and Multiple
Right-Hand Side Solve . . . . . . . . . .
 468
SPOSV, DPOSV, CPOSV, and ZPOSV—Positive
Definite Real Symmetric or Complex Hermitian
Matrix Factorization and Multiple Right-Hand Side
Solve . . . . . . . . . . . . . . . .
 472
SPOTRF, DPOTRF, CPOTRF, ZPOTRF, SPOF,
DPOF, CPOF, ZPOF, SPPTRF, DPPTRF, SPPF, and
DPPF—Positive Definite Real Symmetric or
Complex Hermitian Matrix Factorization . . . .
 477
SPOTRS, DPOTRS, CPOTRS, ZPOTRS, SPOSM,
DPOSM, CPOSM, ZPOSM, SPPTRS, and DPPTRS
—Positive Definite Real Symmetric or Complex
Hermitian Matrix Multiple Right-Hand Side Solve .
 488
SPPS and DPPS—Positive Definite Real Symmetric
Matrix Solve . . . . . . . . . . . . . .
 495
SPPFCD, DPPFCD, SPOFCD, and
DPOFCD—Positive Definite Real Symmetric Matrix
Factorization, Condition Number Reciprocal, and
Determinant . . . . . . . . . . . . . .
 498
DBSSV—Symmetric Indefinite Matrix Factorization
and Multiple Right-Hand Side Solve . . . . .
 504
DBSTRF—Symmetric Indefinite Matrix
Factorization . . . . . . . . . . . . .
 510
DBSTRS—Symmetric Indefinite Matrix Multiple
Right-Hand Side Solve . . . . . . . . . .
 515
SGETRI, DGETRI, CGETRI, ZGETRI, SGEICD, and
DGEICD—General Matrix Inverse, Condition
Number Reciprocal, and Determinant . . . . .
 519
SPOTRI, DPOTRI, CPOTRI, ZPOTRI, SPOICD,
DPOICD, SPPICD, and DPPICD—Positive Definite
Real Symmetric or Complex Hermitian Matrix
Inverse, Condition Number Reciprocal, and
Determinant . . . . . . . . . . . . . .
 526
STRSV, DTRSV, CTRSV, ZTRSV, STPSV, DTPSV,
CTPSV, and ZTPSV—Solution of a Triangular
System of Equations with a Single Right-Hand Side
 535
STRSM, DTRSM, CTRSM, and ZTRSM—Solution
of Triangular Systems of Equations with Multiple
Right-Hand Sides . . . . . . . . . . . .
 541
STRTRI, DTRTRI, CTRTRI, ZTRTRI, STPTRI,
DTPTRI, CTPTRI, and ZTPTRI—Triangular Matrix
Inverse . . . . . . . . . . . . . . .
 548
Banded Linear Algebraic Equation Subroutines
 556
SGBF and DGBF—General Band Matrix
Factorization . . . . . . . . . . . . .
 557
SGBS and DGBS—General Band Matrix Solve . .
 561
SPBF, DPBF, SPBCHF, and DPBCHF—Positive
Definite Symmetric Band Matrix Factorization . .
 563
SPBS, DPBS, SPBCHS, and DPBCHS—Positive
Definite Symmetric Band Matrix Solve . . . . .
 566
SGTF and DGTF—General Tridiagonal Matrix
Factorization . . . . . . . . . . . . .
 569
SGTS and DGTS—General Tridiagonal Matrix
Solve . . . . . . . . . . . . . . . .
 572
SGTNP, DGTNP, CGTNP, and ZGTNP—General
Tridiagonal Matrix Combined Factorization and
Solve with No Pivoting . . . . . . . . . .
 574
SGTNPF, DGTNPF, CGTNPF, and
ZGTNPF—General Tridiagonal Matrix
Factorization with No Pivoting . . . . . . .
 577
SGTNPS, DGTNPS, CGTNPS, and
ZGTNPS—General Tridiagonal Matrix Solve with
No Pivoting . . . . . . . . . . . . . .
 580
SPTF and DPTF—Positive Definite Symmetric
Tridiagonal Matrix Factorization . . . . . . .
 583
SPTS and DPTS—Positive Definite Symmetric
Tridiagonal Matrix Solve . . . . . . . . .
 585
STBSV, DTBSV, CTBSV, and ZTBSV—Triangular
Band Equation Solve . . . . . . . . . . .
 587
Sparse Linear Algebraic Equation Subroutines
 592
DGSF—General Sparse Matrix Factorization Using
Storage by Indices, Rows, or Columns . . . . .
 593
DGSS—General Sparse Matrix or Its Transpose
Solve Using Storage by Indices, Rows, or Columns .
 599
DGKFS—General Sparse Matrix or Its Transpose
Factorization, Determinant, and Solve Using
Skyline Storage Mode . . . . . . . . . .
 603
DSKFS—Symmetric Sparse Matrix Factorization,
Determinant, and Solve Using Skyline Storage
Mode . . . . . . . . . . . . . . . .
 620
DSRIS—Iterative Linear System Solver for a
General or Symmetric Sparse Matrix Stored by
Rows . . . . . . . . . . . . . . . .
 637
DSMCG—Sparse Positive Definite or Negative
Definite Symmetric Matrix Iterative Solve Using
Compressed-Matrix Storage Mode . . . . . .
 647
DSDCG—Sparse Positive Definite or Negative
Definite Symmetric Matrix Iterative Solve Using
Compressed-Diagonal Storage Mode . . . . .
 654
Contents
 vii
DSMGCG—General Sparse Matrix Iterative Solve
Using Compressed-Matrix Storage Mode . . .
 . 661
DSDGCG—General Sparse Matrix Iterative Solve
Using Compressed-Diagonal Storage Mode . .
 . 668
Linear Least Squares Subroutines . . . . .
 . 674
SGESVF and DGESVF—Singular Value
Decomposition for a General Matrix . . . . .
 . 675
SGESVS and DGESVS—Linear Least Squares
Solution for a General Matrix Using the Singular
Value Decomposition . . . . . . . . . .
 . 682
DGEQRF—General Matrix QR Factorization . .
 . 686
DGELS—Linear Least Squares Solution for a
General Matrix . . . . . . . . . . . .
 . 690
SGELLS and DGELLS—Linear Least Squares
Solution for a General Matrix with Column
Pivoting . . . . . . . . . . . . . .
 . 697
Chapter 11. Eigensystem Analysis
 703
Overview of the Eigensystem Analysis Subroutines
 703
Performance and Accuracy Considerations . . .
 703
Eigensystem Analysis Subroutines . . . . . .
 704
SGEEV, DGEEV, CGEEV, and ZGEEV—Eigenvalues
and, Optionally, All or Selected Eigenvectors of a
General Matrix . . . . . . . . . . . . .
 705
SSPEV, DSPEV, CHPEV, and ZHPEV—Eigenvalues
and, Optionally, the Eigenvectors of a Real
Symmetric Matrix or a Complex Hermitian Matrix .
 716
SSPSV, DSPSV, CHPSV, and ZHPSV—Extreme
Eigenvalues and, Optionally, the Eigenvectors of a
Real Symmetric Matrix or a Complex Hermitian
Matrix . . . . . . . . . . . . . . . .
 724
SGEGV and DGEGV—Eigenvalues and, Optionally,
the Eigenvectors of a Generalized Real
Eigensystem, Az=wBz, where A and B Are Real
General Matrices . . . . . . . . . . . .
 731
SSYGV and DSYGV—Eigenvalues and, Optionally,
the Eigenvectors of a Generalized Real Symmetric
Eigensystem, Az=wBz, where A Is Real Symmetric
and B Is Real Symmetric Positive Definite . . . .
 736
Chapter 12. Fourier Transforms,
Convolutions and Correlations, and
Related Computations . . . . . . . 741
Overview of the Signal Processing Subroutines . .
 741
Fourier Transforms Subroutines . . . . . .
 741
Convolution and Correlation Subroutines . . .
 741
Related-Computation Subroutines . . . . .
 742
Fourier Transforms, Convolutions, and Correlations
Considerations . . . . . . . . . . . . .
 742
Use Considerations . . . . . . . . . .
 742
Initializing Auxiliary Working Storage . . . .
 745
Determining the Amount of Auxiliary Working
Storage That You Need . . . . . . . . .
 745
Performance and Accuracy Considerations . . .
 745
When Running on the Workstation Processors
 746
Defining Arrays . . . . . . . . . . .
 746
Fourier Transform Considerations . . . . .
 746
How the Fourier Transform Subroutines Achieve
High Performance . . . . . . . . . . .
 747
Convolution and Correlation Considerations
 747
viii
 ESSL for AIX, Version 4 Release 1, and Linux on pSeries, VersionRelated Computation Considerations . . . . .
 749
Accuracy Considerations . . . . . . . .
 749
Fourier Transform Subroutines . . . . . . .
 750
SCFT and DCFT—Complex Fourier Transform . .
 751
SRCFT and DRCFT—Real-to-Complex Fourier
Transform . . . . . . . . . . . . . .
 759
SCRFT and DCRFT—Complex-to-Real Fourier
Transform . . . . . . . . . . . . . .
 766
SCOSF and DCOSF—Cosine Transform. . . . .
 773
SSINF and DSINF—Sine Transform . . . . . .
 780
SCFT2 and DCFT2—Complex Fourier Transform in
Two Dimensions . . . . . . . . . . . .
 787
SRCFT2 and DRCFT2—Real-to-Complex Fourier
Transform in Two Dimensions . . . . . . . .
 793
SCRFT2 and DCRFT2—Complex-to-Real Fourier
Transform in Two Dimensions . . . . . . . .
 800
SCFT3 and DCFT3—Complex Fourier Transform in
Three Dimensions . . . . . . . . . . . .
 807
SRCFT3 and DRCFT3—Real-to-Complex Fourier
Transform in Three Dimensions . . . . . . .
 812
SCRFT3 and DCRFT3—Complex-to-Real Fourier
Transform in Three Dimensions . . . . . . .
 817
Convolution and Correlation Subroutines . . .
 823
SCON and SCOR—Convolution or Correlation of
One Sequence with One or More Sequences . . .
 824
SCOND and SCORD—Convolution or Correlation
of One Sequence with Another Sequence Using a
Direct Method . . . . . . . . . . . . .
 830
SCONF and SCORF—Convolution or Correlation
of One Sequence with One or More Sequences
Using the Mixed-Radix Fourier Method . . . .
 835
SDCON, DDCON, SDCOR, and
DDCOR—Convolution or Correlation with
Decimated Output Using a Direct Method . . . .
 844
SACOR—Autocorrelation of One or More
Sequences . . . . . . . . . . . . . .
 848
SACORF—Autocorrelation of One or More
Sequences Using the Mixed-Radix Fourier Method .
 852
Related-Computation Subroutines . . . . . .
 857
SPOLY and DPOLY—Polynomial Evaluation . . .
 858
SIZC and DIZC—I-th Zero Crossing . . . . . .
 861
STREC and DTREC—Time-Varying Recursive Filter
 864
SQINT and DQINT—Quadratic Interpolation. . .
 867
SWLEV, DWLEV, CWLEV, and
ZWLEV—Wiener-Levinson Filter Coefficients. . .
 871
Chapter 13. Sorting and Searching
 877
Overview of the Sorting and Searching Subroutines
 877
Use Considerations . . . . . . . . . . .
 877
Performance and Accuracy Considerations . . .
 877
Sorting and Searching Subroutines . . . . . .
 878
ISORT, SSORT, and DSORT—Sort the Elements of a
Sequence . . . . . . . . . . . . . . .
 879
ISORTX, SSORTX, and DSORTX—Sort the
Elements of a Sequence and Note the Original
Element Positions . . . . . . . . . . . .
 881
ISORTS, SSORTS, and DSORTS—Sort the Elements
of a Sequence Using a Stable Sort and Note the
Original Element Positions . . . . . . . . .
 884
4 Release 1 Guide and Reference
IBSRCH, SBSRCH, and DBSRCH—Binary Search
for Elements of a Sequence X in a Sorted Sequence
Y . . . . . . . . . . . . . . . . . 887
ISSRCH, SSSRCH, and DSSRCH—Sequential
Search for Elements of a Sequence X in the
Sequence Y . . . . . . . . . . . . . . 891
Chapter 14. Interpolation . . . . . . 895
Overview of the Interpolation Subroutines . .
 .
 895
Use Considerations . . . . . . . . . .
 .
 895
Performance and Accuracy Considerations . .
 .
 895
Interpolation Subroutines . . . . . . . .
 .
 896
SPINT and DPINT—Polynomial Interpolation .
 .
 897
STPINT and DTPINT—Local Polynomial
Interpolation . . . . . . . . . . . .
 . 901
SCSINT and DCSINT—Cubic Spline Interpolation
 904
SCSIN2 and DCSIN2—Two-Dimensional Cubic
Spline Interpolation . . . . . . . . . .
 . 909
Chapter 15. Numerical Quadrature
 913
Overview of the Numerical Quadrature
Subroutines . . . . . . . . . . . . .
 .
 913
Use Considerations . . . . . . . . . .
 .
 913
Choosing the Method . . . . . . . .
 .
 913
Performance and Accuracy Considerations . .
 .
 913
Programming Considerations for the SUBF
Subroutine . . . . . . . . . . . . .
 . 914
Designing SUBF . . . . . . . . . .
 . 914
Coding and Setting Up SUBF in Your Program
 914
Numerical Quadrature Subroutines. . . . .
 . 916
SPTNQ and DPTNQ—Numerical Quadrature
Performed on a Set of Points . . . . . . .
 . 917
SGLNQ and DGLNQ—Numerical Quadrature
Performed on a Function Using Gauss-Legendre
Quadrature . . . . . . . . . . . . .
 . 920
SGLNQ2 and DGLNQ2—Numerical Quadrature
Performed on a Function Over a Rectangle Using
Two-Dimensional Gauss-Legendre Quadrature .
 . 922
SGLGQ and DGLGQ—Numerical Quadrature
Performed on a Function Using Gauss-Laguerre
Quadrature . . . . . . . . . . . . .
 . 928
SGRAQ and DGRAQ—Numerical Quadrature
Performed on a Function Using Gauss-Rational
Quadrature . . . . . . . . . . . . .
 . 931
SGHMQ and DGHMQ—Numerical Quadrature
Performed on a Function Using Gauss-Hermite
Quadrature . . . . . . . . . . . . .
 . 935
Chapter 16. Random Number
Generation . . . . . . . . . . . . 939
Overview of the Random Number Generation
Subroutines . . . . . . . . . . . . .
 . 939
Use Considerations . . . . . . . . . .
 . 939
Random Number Generation Subroutines . .
 . 940
SURAND and DURAND—Generate a Vector of
Uniformly Distributed Random Numbers . . .
 . 941
SNRAND and DNRAND—Generate a Vector of
Normally Distributed Random Numbers . . .
 . 944
SURXOR and DURXOR—Generate a Vector of
Long Period Uniformly Distributed Random
Numbers . . . . . . . . . . . . . .
 . 947
Chapter 17. Utilities . . . . . . . . . 951
Overview of the Utility Subroutines . . . . . .
 951
Use Considerations . . . . . . . . . . .
 951
Determining the Level of ESSL Installed . . .
 951
Finding the Optimal Stride(s) for Your Fourier
Transforms . . . . . . . . . . . . .
 951
Converting Sparse Matrix Storage . . . . .
 952
Utility Subroutines . . . . . . . . . . .
 953
EINFO—ESSL Error Information-Handler
Subroutine . . . . . . . . . . . . . .
 954
ERRSAV—ESSL ERRSAV Subroutine for ESSL . .
 957
ERRSET—ESSL ERRSET Subroutine for ESSL. . .
 958
ERRSTR—ESSL ERRSTR Subroutine for ESSL . .
 960
IESSL—Determine the Level of ESSL Installed . .
 961
STRIDE—Determine the Stride Value for Optimal
Performance in Specified Fourier Transform
Subroutines . . . . . . . . . . . . . .
 963
DSRSM—Convert a Sparse Matrix from
Storage-by-Rows to Compressed-Matrix Storage
Mode . . . . . . . . . . . . . . . .
 972
DGKTRN—For a General Sparse Matrix, Convert
Between Diagonal-Out and Profile-In Skyline
Storage Mode . . . . . . . . . . . . .
 976
DSKTRN—For a Symmetric Sparse Matrix, Convert
Between Diagonal-Out and Profile-In Skyline
Storage Mode . . . . . . . . . . . . .
 981
Part 3. Appendixes . . . . . . . . 985
Appendix A. Basic Linear Algebra
Subprograms (BLAS) . . . . . . . . 987
Level 1 BLAS .
 .
 .
 .
 .
 .
 .
 .
 .
 .
 .
 .
 . 987
Level 2 BLAS .
 .
 .
 .
 .
 .
 .
 .
 .
 .
 .
 .
 . 987
Level 3 BLAS .
 .
 .
 .
 .
 .
 .
 .
 .
 .
 .
 .
 . 988
Appendix B. LAPACK . . . . . . . . 989
LAPACK Subroutines . . . . . .
 .
 .
 .
 . 989
Non–LAPACK-Conforming Subroutines
 .
 .
 .
 . 989
Notices . . . . . . . . . . . . . . 991
Trademarks . . . . . .
 .
 .
 .
 .
 .
 .
 .
 . 992
Software Update Protocol .
 .
 .
 .
 .
 .
 .
 .
 . 993
Programming Interfaces . .
 .
 .
 .
 .
 .
 .
 .
 . 993
Glossary . . . . . . . . . . . . . 995
Bibliography . . . . . . . . . . . . 999
References . . . . . . .
 .
 .
 .
 .
 .
 .
 . 999
ESSL Publications . . . .
 .
 .
 .
 .
 .
 .
 .
 1004
Evaluation and Planning .
 .
 .
 .
 .
 .
 .
 .
 1004
Installation . . . . . .
 .
 .
 .
 .
 .
 .
 .
 1004
Application Programming .
 .
 .
 .
 .
 .
 .
 .
 1004
Related Publications . . . .
 .
 .
 .
 .
 .
 .
 .
 1004
AIX . . . . . . . .
 .
 .
 .
 .
 .
 .
 .
 1004
Linux . . . . . . .
 .
 .
 .
 .
 .
 .
 .
 1004
Contents
 ix
C++ . . . . . . . .
 .
 .
 .
 .
 .
 .
 . 1005
XL Fortran . . . . . .
 .
 .
 .
 .
 .
 .
 . 1005
IBM 3838 Array Processor .
 .
 .
 .
 .
 .
 .
 . 1005
Index . . . . . . . . . . . . . . 1007