About This Information . . . . . . . . xi
How to Use This Information . . . . . . . . xi
How to Find a Subroutine Description . . . . . xii
Where to Find Related Publications . . . . . . xii
How to Look Up a Bibliography Reference . . . . xii
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
Conventions and terminology used . . . . . . xiv
Fonts . . . . . . . . . . . . . . . xiv
Special Notations and Conventions . . . . . xv
Special Characters, Symbols, Expressions, and
Abbreviations . . . . . . . . . . . . xvii
How to Interpret the Subroutine Descriptions . . . xix
Description . . . . . . . . . . . . . xix
Syntax . . . . . . . . . . . . . . . xix
On Entry . . . . . . . . . . . . . . xx
On Return . . . . . . . . . . . . . . xx
Notes . . . . . . . . . . . . . . . xx
Function . . . . . . . . . . . . . . xx
Special Usage. . . . . . . . . . . . . xx
Error Conditions . . . . . . . . . . . xx
Examples . . . . . . . . . . . . . . xx
Summary of Changes
. . . . . . . xxiii
Future Migration
.
.
.
.
.
.
.
.
.
.
. xxviii
Part 1. Guide Information . . . . . . 1
Chapter 1. Introduction and
Requirements . . . . . . . . . . . . 3
Overview of ESSL . . . . . . . . . . . . 3
Performance and Functional Capability . . . . 3
Usability. . . . . . . . . . . . . . . 4
The Variety of Mathematical Functions . . . . 4
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 . . . . . . . . . . . . . . . 8
Hardware Products Supported by ESSL . . . . 8
Operating Systems Supported by ESSL . . . . 8
Software Products Required by ESSL . . . . . 8
Software Products for Installing and Customizing
ESSL . . . . . . . . . . . . . . . 10
Software Products for Displaying ESSL
Documentation . . . . . . . . . . . . 10
ESSL Internet Resources . . . . . . . . . . 11
Blue Gene documentation . . . . . . . . . 11
Getting on the ESSL Mailing List . . . . . . . 11
List of ESSL Subroutines . . . . . . . . . . 11
© Copyright IBM Corp. 1986, 2012
Linear Algebra Subprograms . . . .
.
.
.
12
Matrix Operations . . . . . . . .
.
.
.
15
Linear Algebraic Equations . . . . .
.
.
.
16
Eigensystem Analysis . . . . . . .
.
.
.
20
Fourier Transforms, Convolutions and
Correlations, and Related Computations .
.
.
.
21
Sorting and Searching . . . . . . .
.
.
.
23
Interpolation . . . . . . . . . .
.
.
.
24
Numerical Quadrature. . . . . . .
.
.
.
24
Random Number Generation . . . .
.
.
.
24
Utilities. . . . . . . . . . . .
.
.
.
25
Chapter 2. Planning Your Program . . . 27
Selecting an ESSL Subroutine . . . . . . . .
27
What ESSL Library Do You Want to Use? . . .
27
Use of SIMD Algorithms by Some Subroutines in
the Libraries Provided by ESSL . . . . . . .
28
Multithreaded Subroutines in the SMP Libraries
Provided by ESSL . . . . . . . . . . .
37
What Type of Data Are You Processing in Your
Program? . . . . . . . . . . . . . .
43
How Is Your Data Structured? And What Storage
Technique Are You Using? . . . . . . . .
43
What about Performance and Accuracy?. . . .
43
Avoiding Conflicts with Internal ESSL Routine
Names That are Exported. . . . . . . . . .
44
Setting Up Your Data . . . . . . . . . . .
44
How Do You Set Up Your Scalar Data? . . . .
44
How Do You Set Up Your Arrays?. . . . . .
44
How Should Your Array Data Be Aligned? . . .
45
What Storage Mode Should You Use for Your
Data? . . . . . . . . . . . . . . .
45
How Do You Convert from One Storage Mode to
Another? . . . . . . . . . . . . . .
45
Setting Up Your ESSL Calling Sequences . . . .
46
What Is an Input-Output Argument? . . . . .
46
What Are the General Rules to Follow when
Specifying Data for the Arguments? . . . . .
46
What Happens When a Value of 0 Is Specified
for N? . . . . . . . . . . . . . . .
47
How Do You Specify the Beginning of the Data
Structure in the ESSL Calling Sequence? . . . .
47
Using Auxiliary Storage in ESSL . . . . . . .
47
Dynamic Allocation of Auxiliary Storage . . .
48
Setting Up Auxiliary Storage When Dynamic
Allocation Is Not Used . . . . . . . . .
49
Providing a Correct Transform Length to ESSL . .
54
Who Do You Want to Calculate the Transform
Length? You or ESSL? . . . . . . . . . .
54
How Do You Calculate the Transform Length
Using the Table or Formula?. . . . . . . .
55
How Do You Get ESSL to Calculate the
Transform Length Using ESSL Error Handling? .
55
Getting the Best Accuracy . . . . . . . . .
59
iii
What Precisions Do ESSL Subroutines Operate
On? . . . . . . . . . . . . . . .
. 59
How does the Nature of the ESSL Computation
Affect Accuracy?. . . . . . . . . . .
. 60
What Data Type Standards Are Used by ESSL,
and What Exceptions Should You Know About?
. 60
How is Underflow Handled? . . . . . .
. 61
Where Can You Find More Information on
Accuracy? . . . . . . . . . . . . .
. 61
|
What about Bitwise-Identical Results? . . .
. 61
Getting the Best Performance . . . . . . .
. 61
What General Coding Techniques Can You Use
to Improve Performance? . . . . . . . .
. 61
Where Can You Find More Information on
Performance? . . . . . . . . . . . .
. 63
Dealing with Errors when Using ESSL . . . .
. 63
What Can You Do about Program Exceptions?.
. 63
What Can You Do about ESSL Input-Argument
Errors? . . . . . . . . . . . . . .
. 63
What Can You Do about ESSL Computational
Errors? . . . . . . . . . . . . . .
. 64
What Can You Do about ESSL Resource Errors?
66
What Can You Do about ESSL Attention
Messages? . . . . . . . . . . . . .
. 66
How Do You Control Error Handling by Setting
Values in the ESSL Error Option Table? . . .
. 67
How does Error Handling Work in a Threaded
Environment? . . . . . . . . . . .
. 69
Where Can You Find More Information on
Errors? . . . . . . . . . . . . . .
. 69
Chapter 3. Setting Up Your Data
Structures . . . . . . . . . . . . . 71
Concepts . . . . . . . . . . . . . . . 71
Vectors . . . . . . . . . . . . . . . . 71
Transpose of a Vector . . . . . . . . . . 72
Conjugate Transpose of a Vector . . . . . . 72
Vector Storage Representation . . . . . . . 73
How Stride Is Used for Vectors . . . . . . . 74
Sparse Vector . . . . . . . . . . . . . 76
Matrices . . . . . . . . . . . . . . . 77
Transpose of a Matrix . . . . . . . . . . 78
Conjugate Transpose of a Matrix . . . . . . 78
Matrix Storage Representation . . . . . . . 78
How Leading Dimension Is Used for Matrices . . 79
Symmetric Matrix . . . . . . . . . . . 81
Positive Definite or Negative Definite Symmetric
Matrix . . . . . . . . . . . . . . . 85
Symmetric Indefinite Matrix . . . . . . . . 85
Complex Hermitian Matrix . . . . . . . . 86
Positive Definite or Negative Definite Complex
Hermitian Matrix . . . . . . . . . . . 87
Positive Definite or Negative Definite Symmetric
Toeplitz Matrix . . . . . . . . . . . . 87
Positive Definite or Negative Definite Complex
Hermitian Toeplitz Matrix . . . . . . . . 88
Triangular Matrix . . . . . . . . . . . 89
General Band Matrix . . . . . . . . . . 92
Symmetric Band Matrix . . . . . . . . . 98
Positive Definite Symmetric Band Matrix . . . 100
Complex Hermitian Band Matrix . . . . . . 100
iv
ESSL for AIX, 5.1, and ESSL for Linux on POWER, 5.1.1: GuideTriangular Band Matrix . . . . . . . .
. 101
General Tridiagonal Matrix . . . . . . .
. 105
Symmetric Tridiagonal Matrix . . . . . .
. 106
Positive Definite Symmetric Tridiagonal Matrix
107
Sparse Matrix . . . . . . . . . . .
. 107
Sequences . . . . . . . . . . . . .
. 118
Real and Complex Elements in Storage . . .
. 118
One-Dimensional Sequences . . . . . .
. 119
Two-Dimensional Sequences . . . . . .
. 119
Three-Dimensional Sequences . . . . . .
. 119
How Stride Is Used for Three-Dimensional
Sequences . . . . . . . . . . . .
. 121
Chapter 4. Coding Your Program . . . 123
Fortran Programs . . . . . . . . . . . .
123
Calling ESSL Subroutines and Functions in
Fortran . . . . . . . . . . . . . .
123
Setting Up a User-Supplied Subroutine for ESSL
in Fortran . . . . . . . . . . . . .
123
Setting Up Scalar Data in Fortran. . . . . .
124
Setting Up Arrays in Fortran . . . . . . .
124
Creating Multiple Threads and Calling ESSL
from Your Fortran Program. . . . . . . .
129
Handling Errors in Your Fortran Program . . .
130
Example of Handling Errors in a Multithreaded
Application Program . . . . . . . . . .
139
C Programs . . . . . . . . . . . . . .
141
Calling ESSL Subroutines and Functions in C
141
Passing Arguments in C . . . . . . . . .
142
Setting Up a User-Supplied Subroutine for ESSL
in C . . . . . . . . . . . . . . .
143
Setting Up Scalar Data in C . . . . . . .
143
Setting Up Complex Data Types in C . . . .
144
Using Logical Data in C . . . . . . . . .
145
Setting Up Arrays in C . . . . . . . . .
145
Creating Multiple Threads and Calling ESSL
from Your C Program . . . . . . . . .
146
Handling Errors in Your C Program . . . . .
148
C++ Programs . . . . . . . . . . . . .
157
Calling ESSL Subroutines and Functions in C++
157
Passing Arguments in C++ . . . . . . . .
157
Setting Up a User-Supplied Subroutine for ESSL
in C++ . . . . . . . . . . . . . .
158
Setting Up Scalar Data in C++. . . . . . .
159
Using Complex Data in C++ . . . . . . .
160
Using Logical Data in C++ . . . . . . . .
162
Setting Up Arrays in C++ . . . . . . . .
162
Creating Multiple Threads and Calling ESSL
from Your C++ Program. . . . . . . . .
162
Handling Errors in Your C++ Program . . . .
164
Chapter 5. Processing Your Program
175
Processing Your Program on AIX . . .
.
.
.
.
175
Fortran Program Procedures on AIX .
.
.
.
.
175
C Program Procedures on AIX. . .
.
.
.
.
177
C++ Program Procedures on AIX . .
.
.
.
.
178
Processing Your Program on Linux . .
.
.
.
.
181
Fortran Program Procedures on Linux
.
.
.
.
182
C Program Procedures on Linux . .
.
.
.
.
184
C++ Program Procedures on Linux .
.
.
.
.
187
and Reference
Chapter 6. Migrating Your Programs
191
|
Migrating Programs from ESSL for Linux on Power
|
Version 5 Release 1 to Version 5 Release 1.1 . . .
191
Migrating Programs from ESSL Version 4 Release 4
to Version 5 Release 1 . . . . . . . . . .
191
Migrating Programs from ESSL Version 4 Release 3
to Version 4 Release 4 . . . . . . . . . .
191
Migrating Programs from ESSL Version 4 Release
2.2 or Later to ESSL Version 4 Release 3 . . . .
191
Migrating Programs from ESSL Version 4 Release
2.1 to Version 4 Release 2.2 . . . . . . . . .
192
Migrating Programs from ESSL Version 4 Release 2
to Version 4 Release 2.1 . . . . . . . . . .
192
Migrating Programs from ESSL Version 4 Release 1
to Version 4 Release 2 . . . . . . . . . .
192
Migrating Programs from ESSL Version 3 Release 3
to Version 4 Release 1 . . . . . . . . . .
192
ESSL Subroutines . . . . . . . . . . .
193
Planning for Future Migration . . . . . . . .
193
Migrating From One Hardware Platform to
Another . . . . . . . . . . . . . . .
193
Auxiliary Storage . . . . . . . . . . .
193
Bitwise-Identical Results. . . . . . . . .
193
Migrating from Other Libraries to ESSL . . . .
194
Migrating from ESSL/370 . . . . . . . .
194
Migrating from Another IBM Subroutine Library
194
Migrating from LAPACK . . . . . . . .
194
Migrating from FFTW Version 3.1.2 . . . . .
194
Migrating from a Non-IBM Subroutine Library
194
Chapter 7. Handling Problems . . . . 195
Where to Find More Information About Errors
.
.
195
Getting Help from IBM Support . . . . .
.
.
195
National Language Support . . . . . .
.
.
196
Dealing with Errors . . . . . . . . .
.
.
197
Program Exceptions . . . . . . . .
.
.
197
ESSL Input-Argument Error Messages . .
.
.
197
ESSL Computational Error Messages . .
.
.
198
ESSL Resource Error Messages . . . .
.
.
198
ESSL Informational and Attention Messages
.
.
199
Miscellaneous Error Messages . . . . .
.
.
199
Messages . . . . . . . . . . . . .
.
.
199
Message Conventions . . . . . . .
.
.
200
Input-Argument Error Messages(2001-2099)
.
.
200
Computational Error Messages(2100-2199) .
.
.
205
Input-Argument Error Messages(2200-2299)
.
.
207
Resource Error Messages(2400-2499) . . .
.
.
208
Informational and Attention Error
Messages(2600-2699) . . . . . . . .
.
. 208
Miscellaneous Error Messages(2700-2799) .
.
. 208
Part 2. Reference Information . . . 209
Chapter 8. Linear Algebra
Subprograms . . . . . . . . . . . 211
Overview of the Linear Algebra Subprograms .
. 211
Vector-Scalar Linear Algebra Subprograms. .
. 211
Sparse Vector-Scalar Linear Algebra
Subprograms . . . . . . . . . . .
. 212
Matrix-Vector Linear Algebra Subprograms .
. 213
Sparse Matrix-Vector Linear Algebra
Subprograms . . . . . . . . . . . .
214
Use Considerations . . . . . . . . . . .
214
Performance and Accuracy Considerations . . .
214
Vector-Scalar Subprograms . . . . . . . .
215
ISAMAX, IDAMAX, ICAMAX, and IZAMAX
(Position of the First or Last Occurrence of the
Vector Element Having the Largest Magnitude) . .
215
ISAMIN and IDAMIN (Position of the First or Last
Occurrence of the Vector Element Having
Minimum Absolute Value) . . . . . . . . .
218
ISMAX and IDMAX (Position of the First or Last
Occurrence of the Vector Element Having the
Maximum Value) . . . . . . . . . . . .
220
ISMIN and IDMIN (Position of the First or Last
Occurrence of the Vector Element Having
Minimum Value) . . . . . . . . . . . .
223
SASUM, DASUM, SCASUM, and DZASUM (Sum
of the Magnitudes of the Elements in a Vector) . .
225
SAXPY, DAXPY, CAXPY, and ZAXPY (Multiply a
Vector X by a Scalar, Add to a Vector Y, and Store
in the Vector Y). . . . . . . . . . . . .
228
SCOPY, DCOPY, CCOPY, and ZCOPY (Copy a
Vector) . . . . . . . . . . . . . . .
231
SDOT, DDOT, CDOTU, ZDOTU, CDOTC, and
ZDOTC (Dot Product of Two Vectors) . . . . .
233
SNAXPY and DNAXPY (Compute SAXPY or
DAXPY N Times) . . . . . . . . . . . .
236
SNDOT and DNDOT (Compute Special Dot
Products N Times). . . . . . . . . . . .
241
SNRM2, DNRM2, SCNRM2, and DZNRM2
(Euclidean Length of a Vector with Scaling of Input
to Avoid Destructive Underflow and Overflow) . .
246
SNORM2, DNORM2, CNORM2, and ZNORM2
(Euclidean Length of a Vector with No Scaling of
Input) . . . . . . . . . . . . . . . .
249
SROTG, DROTG, CROTG, and ZROTG (Construct
a Given Plane Rotation) . . . . . . . . . .
251
SROT, DROT, CROT, ZROT, CSROT, and ZDROT
(Apply a Plane Rotation) . . . . . . . . .
257
SSCAL, DSCAL, CSCAL, ZSCAL, CSSCAL, and
ZDSCAL (Multiply a Vector X by a Scalar and
Store in the Vector X) . . . . . . . . . . .
261
SSWAP, DSWAP, CSWAP, and ZSWAP (Interchange
the Elements of Two Vectors) . . . . . . . .
264
SVEA, DVEA, CVEA, and ZVEA (Add a Vector X
to a Vector Y and Store in a Vector Z) . . . . .
266
SVES, DVES, CVES, and ZVES (Subtract a Vector Y
from a Vector X and Store in a Vector Z) . . . .
270
SVEM, DVEM, CVEM, and ZVEM (Multiply a
Vector X by a Vector Y and Store in a Vector Z) . .
274
SYAX, DYAX, CYAX, ZYAX, CSYAX, and ZDYAX
(Multiply a Vector X by a Scalar and Store in a
Vector Y) . . . . . . . . . . . . . . .
277
SZAXPY, DZAXPY, CZAXPY, and ZZAXPY
(Multiply a Vector X by a Scalar, Add to a Vector Y,
and Store in a Vector Z) . . . . . . . . . .
280
Sparse Vector-Scalar Subprograms . . . . . .
283
Contents
v
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) . . . . . . . . . . . . .
283
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) . . . . . .
286
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). . . . . . . . . .
288
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) . . . . . . . . . . . . . . . . .
291
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) . . . . .
293
Matrix-Vector Subprograms . . . . . . . .
296
SGEMV, DGEMV, CGEMV, ZGEMV, SGEMX,
DGEMX, SGEMTX, and DGEMTX (Matrix-Vector
Product for a General Matrix, Its Transpose, or Its
Conjugate Transpose). . . . . . . . . . .
296
SGER, DGER, CGERU, ZGERU, CGERC, and
ZGERC (Rank-One Update of a General Matrix). .
306
SSPMV, DSPMV, CHPMV, ZHPMV, SSYMV,
DSYMV, CHEMV, ZHEMV, SSLMX, and DSLMX
(Matrix-Vector Product for a Real Symmetric or
Complex Hermitian Matrix) . . . . . . . .
313
SSPR, DSPR, CHPR, ZHPR, SSYR, DSYR, CHER,
ZHER, SSLR1, and DSLR1 (Rank-One Update of a
Real Symmetric or Complex Hermitian Matrix) . .
320
SSPR2, DSPR2, CHPR2, ZHPR2, SSYR2, DSYR2,
CHER2, ZHER2, SSLR2, and DSLR2 (Rank-Two
Update of a Real Symmetric or Complex Hermitian
Matrix) . . . . . . . . . . . . . . .
327
SGBMV, DGBMV, CGBMV, and ZGBMV
(Matrix-Vector Product for a General Band Matrix,
Its Transpose, or Its Conjugate Transpose) . . . .
335
SSBMV, DSBMV, CHBMV, and ZHBMV
(Matrix-Vector Product for a Real Symmetric or
Complex Hermitian Band Matrix) . . . . . .
341
STRMV, DTRMV, CTRMV, ZTRMV, STPMV,
DTPMV, CTPMV, and ZTPMV (Matrix-Vector
Product for a Triangular Matrix, Its Transpose, or
Its Conjugate Transpose) . . . . . . . . .
346
STBMV, DTBMV, CTBMV, and ZTBMV
(Matrix-Vector Product for a Triangular Band
Matrix, Its Transpose, or Its Conjugate Transpose) .
351
Sparse Matrix-Vector Subprograms . . . . . .
356
DSMMX (Matrix-Vector Product for a Sparse
Matrix in Compressed-Matrix Storage Mode) . . .
356
DSMTM (Transpose a Sparse Matrix in
Compressed-Matrix Storage Mode) . . . . . .
359
vi
ESSL for AIX, 5.1, and ESSL for Linux on POWER, 5.1.1: GuideDSDMX (Matrix-Vector Product for a Sparse Matrix
or Its Transpose in Compressed-Diagonal Storage
Mode) . . . . . . . . . . . . . . . . 362
Chapter 9. Matrix Operations. . . . . 367
Overview of the Matrix Operation Subroutines . .
367
Use Considerations . . . . . . . . . . .
368
Specifying Normal, Transposed, or Conjugate
Transposed Input Matrices . . . . . . . .
368
Transposing or Conjugate Transposing: . . . .
369
Performance and Accuracy Considerations . . .
369
In General . . . . . . . . . . . . .
369
For Large Matrices . . . . . . . . . .
369
For Combined Operations . . . . . . . .
369
Matrix Operation Subroutines . . . . . . .
370
SGEADD, DGEADD, CGEADD, and ZGEADD
(Matrix Addition for General Matrices or Their
Transposes) . . . . . . . . . . . . . .
370
SGESUB, DGESUB, CGESUB, and ZGESUB (Matrix
Subtraction for General Matrices or Their
Transposes) . . . . . . . . . . . . . .
375
SGEMUL, DGEMUL, CGEMUL, and ZGEMUL
(Matrix Multiplication for General Matrices, Their
Transposes, or Conjugate Transposes) . . . . .
381
SGEMMS, DGEMMS, CGEMMS, and ZGEMMS
(Matrix Multiplication for General Matrices, Their
Transposes, or Conjugate Transposes Using
Winograd's Variation of Strassen's Algorithm) . .
390
SGEMM, DGEMM, CGEMM, and ZGEMM
(Combined Matrix Multiplication and Addition for
General Matrices, Their Transposes, or Conjugate
Transposes) . . . . . . . . . . . . . .
395
SSYMM, DSYMM, CSYMM, ZSYMM, CHEMM,
and ZHEMM (Matrix-Matrix Product Where One
Matrix is Real or Complex Symmetric or Complex
Hermitian) . . . . . . . . . . . . . .
402
STRMM, DTRMM, CTRMM, and ZTRMM
(Triangular Matrix-Matrix Product) . . . . . .
409
SSYRK, DSYRK, CSYRK, ZSYRK, CHERK, and
ZHERK (Rank-K Update of a Real or Complex
Symmetric or a Complex Hermitian Matrix) . . .
416
SSYR2K, DSYR2K, CSYR2K, ZSYR2K, CHER2K,
and ZHER2K (Rank-2K Update of a Real or
Complex Symmetric or a Complex Hermitian
Matrix) . . . . . . . . . . . . . . .
422
SGETMI, DGETMI, CGETMI, and ZGETMI
(General Matrix Transpose [In-Place]) . . . . .
429
SGETMO, DGETMO, CGETMO, and ZGETMO
(General Matrix Transpose [Out-of-Place]) . . . .
431
Chapter 10. Linear Algebraic
Equations . . . . . . . . . . . . . 435
Overview of the Linear Algebraic Equation
Subroutines . . . . . . . . . . . . . . 435
Dense Linear Algebraic Equation Subroutines
435
Banded Linear Algebraic Equation Subroutines 437
Sparse Linear Algebraic Equation Subroutines
438
Linear Least Squares Subroutines . . . . . . 438
Dense and Banded Linear Algebraic Equation
Considerations . . . . . . . . . . . . . 439
and Reference
Use Considerations . . . . . . . . . .
439
Performance and Accuracy Considerations . .
439
Sparse Matrix Direct Solver Considerations . . .
440
Use Considerations . . . . . . . . . .
440
Performance and Accuracy Considerations . .
440
Sparse Matrix Skyline Solver Considerations . . .
441
Use Considerations . . . . . . . . . .
441
Performance and Accuracy Considerations . .
441
Sparse Matrix Iterative Solver Considerations . .
442
Use Considerations . . . . . . . . . .
442
Performance and Accuracy Considerations . .
442
Linear Least Squares Considerations. . . . . .
443
Use Considerations . . . . . . . . . .
443
Performance and Accuracy Considerations . .
443
Dense Linear Algebraic Equation Subroutines
443
SGESV, DGESV, CGESV, ZGESV (General Matrix
Factorization and Multiple Right-Hand Side Solve) .
443
SGETRF, DGETRF, CGETRF and ZGETRF (General
Matrix Factorization) . . . . . . . . . . .
447
SGETRS, DGETRS, CGETRS, and ZGETRS (General
Matrix Multiple Right-Hand Side Solve) . . . .
451
SGEF, DGEF, CGEF, and ZGEF (General Matrix
Factorization) . . . . . . . . . . . . .
455
SGES, DGES, CGES, and ZGES (General Matrix, Its
Transpose, or Its Conjugate Transpose Solve) . . .
458
SGESM, DGESM, CGESM, and ZGESM (General
Matrix, Its Transpose, or Its Conjugate Transpose
Multiple Right-Hand Side Solve) . . . . . . .
461
SGECON, DGECON, CGECON, and ZGECON
(Estimate the Reciprocal of the Condition Number
of a General Matrix) . . . . . . . . . . .
466
SGEFCD and DGEFCD (General Matrix
Factorization, Condition Number Reciprocal, and
Determinant) . . . . . . . . . . . . .
470
SGETRI, DGETRI, CGETRI, ZGETRI, SGEICD, and
DGEICD (General Matrix Inverse, Condition
Number Reciprocal, and Determinant) . . . . .
474
SLANGE, DLANGE, CLANGE, and ZLANGE
(General Matrix Norm) . . . . . . . . . .
481
SPPSV, DPPSV, CPPSV, and ZPPSV (Positive
Definite Real Symmetric and Complex Hermitian
Matrix Factorization and Multiple Right-Hand Side
Solve) . . . . . . . . . . . . . . . .
483
SPOSV, DPOSV, CPOSV, and ZPOSV (Positive
Definite Real Symmetric or Complex Hermitian
Matrix Factorization and Multiple Right-Hand Side
Solve) . . . . . . . . . . . . . . . .
489
SPOTRF, DPOTRF, CPOTRF, ZPOTRF, SPOF,
DPOF, CPOF, ZPOF, SPPTRF, DPPTRF, CPPTRF,
ZPPTRF, SPPF, and DPPF (Positive Definite Real
Symmetric or Complex Hermitian Matrix
Factorization) . . . . . . . . . . . . .
494
SPOTRS, DPOTRS, CPOTRS, ZPOTRS, SPOSM,
DPOSM, CPOSM, ZPOSM, SPPTRS, DPPTRS,
CPPTRS, and ZPPTRS (Positive Definite Real
Symmetric or Complex Hermitian Matrix Multiple
Right-Hand Side Solve) . . . . . . . . . .
506
SPPS and DPPS (Positive Definite Real Symmetric
Matrix Solve) . . . . . . . . . . . . .
513
SPOCON, DPOCON, CPOCON, ZPOCON,
SPPCON, DPPCON, CPPCON, and ZPPCON
(Estimate the Reciprocal of the Condition Number
of a Positive Definite Real Symmetric or Complex
Hermitian Matrix) . . . . . . . . . . . .
516
SPPFCD, DPPFCD, SPOFCD, and DPOFCD
(Positive Definite Real Symmetric Matrix
Factorization, Condition Number Reciprocal, and
Determinant) . . . . . . . . . . . . .
523
SPOTRI, DPOTRI, CPOTRI, ZPOTRI, SPOICD,
DPOICD, SPPTRI, DPPTRI, CPPTRI, ZPPTRI,
SPPICD, and DPPICD (Positive Definite Real
Symmetric or Complex Hermitian Matrix Inverse,
Condition Number Reciprocal, and Determinant) .
529
SLANSY, DLANSY, CLANHE, ZLANHE, SLANSP,
DLANSP, CLANHP, and ZLANHP (Real
Symmetric or Complex Hermitian Matrix Norm) .
540
DBSSV (Symmetric Indefinite Matrix Factorization
and Multiple Right-Hand Side Solve) . . . . .
544
DBSTRF (Symmetric Indefinite Matrix
Factorization) . . . . . . . . . . . . .
550
DBSTRS (Symmetric Indefinite Matrix Multiple
Right-Hand Side Solve) . . . . . . . . . .
554
STRSV, DTRSV, CTRSV, ZTRSV, STPSV, DTPSV,
CTPSV, and ZTPSV (Solution of a Triangular
System of Equations with a Single Right-Hand
Side) . . . . . . . . . . . . . . . .
558
STRSM, DTRSM, CTRSM, and ZTRSM (Solution of
Triangular Systems of Equations with Multiple
Right-Hand Sides) . . . . . . . . . . . .
563
STRTRI, DTRTRI, CTRTRI, ZTRTRI, STPTRI,
DTPTRI, CTPTRI, and ZTPTRI (Triangular Matrix
Inverse) . . . . . . . . . . . . . . .
570
Banded Linear Algebraic Equation Subroutines
577
SGBF and DGBF (General Band Matrix
Factorization) . . . . . . . . . . . . .
578
SGBS and DGBS (General Band Matrix Solve) . .
581
SPBF, DPBF, SPBCHF, and DPBCHF (Positive
Definite Symmetric Band Matrix Factorization) . .
583
SPBS, DPBS, SPBCHS, and DPBCHS (Positive
Definite Symmetric Band Matrix Solve). . . . .
586
SGTF and DGTF (General Tridiagonal Matrix
Factorization) . . . . . . . . . . . . .
588
SGTS and DGTS (General Tridiagonal Matrix
Solve) . . . . . . . . . . . . . . . .
591
SGTNP, DGTNP, CGTNP, and ZGTNP (General
Tridiagonal Matrix Combined Factorization and
Solve with No Pivoting) . . . . . . . . . .
593
SGTNPF, DGTNPF, CGTNPF, and ZGTNPF
(General Tridiagonal Matrix Factorization with No
Pivoting) . . . . . . . . . . . . . . .
595
SGTNPS, DGTNPS, CGTNPS, and ZGTNPS
(General Tridiagonal Matrix Solve with No
Pivoting) . . . . . . . . . . . . . . .
598
SPTF and DPTF (Positive Definite Symmetric
Tridiagonal Matrix Factorization) . . . . . . .
600
SPTS and DPTS (Positive Definite Symmetric
Tridiagonal Matrix Solve) . . . . . . . . .
602
STBSV, DTBSV, CTBSV, and ZTBSV (Triangular
Band Equation Solve). . . . . . . . . . .
604
Sparse Linear Algebraic Equation Subroutines
609
Contents
vii
DGSF (General Sparse Matrix Factorization Using
Storage by Indices, Rows, or Columns) . . . . .
609
DGSS (General Sparse Matrix or Its Transpose
Solve Using Storage by Indices, Rows, or Columns)
615
DGKFS (General Sparse Matrix or Its Transpose
Factorization, Determinant, and Solve Using
Skyline Storage Mode) . . . . . . . . . .
619
DSKFS (Symmetric Sparse Matrix Factorization,
Determinant, and Solve Using Skyline Storage
Mode) . . . . . . . . . . . . . . . .
636
DSRIS (Iterative Linear System Solver for a General
or Symmetric Sparse Matrix Stored by Rows). . .
653
DSMCG (Sparse Positive Definite or Negative
Definite Symmetric Matrix Iterative Solve Using
Compressed-Matrix Storage Mode) . . . . . .
663
DSDCG (Sparse Positive Definite or Negative
Definite Symmetric Matrix Iterative Solve Using
Compressed-Diagonal Storage Mode) . . . . .
671
DSMGCG (General Sparse Matrix Iterative Solve
Using Compressed-Matrix Storage Mode) . . . .
678
DSDGCG (General Sparse Matrix Iterative Solve
Using Compressed-Diagonal Storage Mode) . . .
685
Linear Least Squares Subroutines . . . . . .
691
SGEQRF, DGEQRF, CGEQRF, and ZGEQRF
(General Matrix QR Factorization) . . . . . .
691
SGELS, DGELS, CGELS, and ZGELS (Linear Least
Squares Solution for a General Matrix) . . . . .
696
SGESVF and DGESVF (Singular Value
Decomposition for a General Matrix) . . . . .
706
SGESVS and DGESVS (Linear Least Squares
Solution for a General Matrix Using the Singular
Value Decomposition) . . . . . . . . . .
713
SGELLS and DGELLS (Linear Least Squares
Solution for a General Matrix with Column
Pivoting) . . . . . . . . . . . . . . .
717
Chapter 11. Eigensystem Analysis
725
Overview of the Eigensystem Analysis Subroutines
725
Performance and Accuracy Considerations . . .
726
Eigensystem Analysis Subroutines . . . . . .
726
SGEEVX, DGEEVX, CGEEVX, and ZGEEVX
(Eigenvalues and, Optionally, Right Eigenvectors,
Left Eigenvectors, Reciprocal Condition Numbers
for Eigenvalues, and Reciprocal Condition
Numbers for Right Eigenvectors of a General
Matrix) . . . . . . . . . . . . . . .
726
SSPEVX, DSPEVX, CHPEVX, ZHPEVX, SSYEVX,
DSYEVX, CHEEVX, and ZHEEVX (Eigenvalues
and, Optionally, the Eigenvectors of a Real
Symmetric or Complex Hermitian Matrix) . . . .
740
DSYGVX (Selected Eigenvalues and, Optionally,
the Eigenvectors of a Positive Definite Real
Symmetric Generalized Eigenproblem) . . . . .
755
SGEEV, DGEEV, CGEEV, and ZGEEV (Eigenvalues
and, Optionally, All or Selected Eigenvectors of a
General Matrix) . . . . . . . . . . . .
764
SSPEV, DSPEV, CHPEV, and ZHPEV (Eigenvalues
and, Optionally, the Eigenvectors of a Real
Symmetric Matrix or a Complex Hermitian Matrix)
774
viii
ESSL for AIX, 5.1, and ESSL for Linux on POWER, 5.1.1: GuideSSPSV, DSPSV, CHPSV, and ZHPSV (Extreme
Eigenvalues and, Optionally, the Eigenvectors of a
Real Symmetric Matrix or a Complex Hermitian
Matrix) . . . . . . . . . . . . . . . 782
SGEGV and DGEGV (Eigenvalues and, Optionally,
the Eigenvectors of a Generalized Real
Eigensystem, Az=wBz, where A and B Are Real
General Matrices) . . . . . . . . . . . . 789
SSYGV and DSYGV (Eigenvalues and, Optionally,
the Eigenvectors of a Real Symmetric Generalized
Eigenproblem) . . . . . . . . . . . . . 795
Chapter 12. Fourier Transforms,
Convolutions and Correlations, and
Related Computations . . . . . . . 801
Overview of the Signal Processing Subroutines . .
801
Fourier Transforms Subroutines . . . . . .
801
Convolution and Correlation Subroutines . . .
802
Related-Computation Subroutines . . . . .
802
Fourier Transforms, Convolutions, and Correlations
Considerations . . . . . . . . . . . . .
803
Use Considerations . . . . . . . . . .
803
Initializing Auxiliary Working Storage . . . .
806
Determining the Amount of Auxiliary Working
Storage That You Need . . . . . . . . .
806
Performance and Accuracy Considerations . . .
806
When Running on the Workstation Processors
807
Defining Arrays . . . . . . . . . . .
807
Fourier Transform Considerations . . . . .
807
How the Fourier Transform Subroutines Achieve
High Performance . . . . . . . . . . .
808
Convolution and Correlation Considerations
808
Related Computation Considerations . . . . .
810
Accuracy Considerations . . . . . . . .
810
Fourier Transform Subroutines . . . . . . .
810
SCFTD and DCFTD (Multidimensional Complex
Fourier Transform) . . . . . . . . . . .
810
SRCFTD and DRCFTD (Multidimensional
Real-to-Complex Fourier Transform). . . . . .
818
SCRFTD and DCRFTD (Multidimensional
Complex-to-Real Fourier Transform). . . . . .
826
SCFT and DCFT (Complex Fourier Transform) . .
834
SRCFT and DRCFT (Real-to-Complex Fourier
Transform) . . . . . . . . . . . . . .
842
SCRFT and DCRFT (Complex-to-Real Fourier
Transform) . . . . . . . . . . . . . .
849
SCOSF and DCOSF (Cosine Transform). . . . .
857
SSINF and DSINF (Sine Transform) . . . . . .
865
SCFT2 and DCFT2 (Complex Fourier Transform in
Two Dimensions) . . . . . . . . . . . .
872
SRCFT2 and DRCFT2 (Real-to-Complex Fourier
Transform in Two Dimensions) . . . . . . .
879
SCRFT2 and DCRFT2 (Complex-to-Real Fourier
Transform in Two Dimensions) . . . . . . .
886
SCFT3 and DCFT3 (Complex Fourier Transform in
Three Dimensions) . . . . . . . . . . .
893
SRCFT3 and DRCFT3 (Real-to-Complex Fourier
Transform in Three Dimensions) . . . . . . .
899
SCRFT3 and DCRFT3 (Complex-to-Real Fourier
Transform in Three Dimensions) . . . . . . .
906
and Reference
Convolution and Correlation Subroutines . . .
912
SCON and SCOR (Convolution or Correlation of
One Sequence with One or More Sequences) . . .
912
SCOND and SCORD (Convolution or Correlation
of One Sequence with Another Sequence Using a
Direct Method) . . . . . . . . . . . . .
918
SCONF and SCORF (Convolution or Correlation of
One Sequence with One or More Sequences Using
the Mixed-Radix Fourier Method) . . . . . .
924
SDCON, DDCON, SDCOR, and DDCOR
(Convolution or Correlation with Decimated
Output Using a Direct Method) . . . . . . .
933
SACOR (Autocorrelation of One or More
Sequences) . . . . . . . . . . . . . .
937
SACORF (Autocorrelation of One or More
Sequences Using the Mixed-Radix Fourier Method)
940
Related-Computation Subroutines . . . . . .
946
SPOLY and DPOLY (Polynomial Evaluation) . . .
946
SIZC and DIZC (I-th Zero Crossing) . . . . . .
948
STREC and DTREC (Time-Varying Recursive Filter)
951
SQINT and DQINT (Quadratic Interpolation). . .
953
SWLEV, DWLEV, CWLEV, and ZWLEV
(Wiener-Levinson Filter Coefficients) . . . . .
957
Chapter 13. Sorting and Searching
963
Overview of the Sorting and Searching Subroutines
963
Use Considerations . . . . . . . . . . .
963
Performance and Accuracy Considerations . . .
963
Sorting and Searching Subroutines . . . . . .
964
ISORT, SSORT, and DSORT (Sort the Elements of a
Sequence) . . . . . . . . . . . . . .
964
ISORTX, SSORTX, and DSORTX (Sort the Elements
of a Sequence and Note the Original Element
Positions). . . . . . . . . . . . . . .
965
ISORTS, SSORTS, and DSORTS (Sort the Elements
of a Sequence Using a Stable Sort and Note the
Original Element Positions). . . . . . . . .
968
IBSRCH, SBSRCH, and DBSRCH (Binary Search for
Elements of a Sequence X in a Sorted Sequence Y) .
971
ISSRCH, SSSRCH, and DSSRCH (Sequential Search
for Elements of a Sequence X in the Sequence Y) .
975
Chapter 14. Interpolation . . . . . . 979
Overview of the Interpolation Subroutines . .
.
979
Use Considerations . . . . . . . . . .
.
979
Performance and Accuracy Considerations . .
.
979
Interpolation Subroutines . . . . . . . .
.
979
SPINT and DPINT (Polynomial Interpolation) .
.
980
STPINT and DTPINT (Local Polynomial
Interpolation) . . . . . . . . . . . .
. 984
SCSINT and DCSINT (Cubic Spline Interpolation)
987
SCSIN2 and DCSIN2 (Two-Dimensional Cubic
Spline Interpolation) . . . . . . . . . .
. 992
Chapter 15. Numerical Quadrature
997
Overview of the Numerical Quadrature
Subroutines . . . . . . . . . . .
.
.
.
997
Use Considerations . . . . . . . .
.
.
.
997
Choosing the Method . . . . . .
.
.
.
997
Performance and Accuracy Considerations
.
.
.
997
Programming Considerations for the SUBF
Subroutine . . . . . . . . . . . . . . 998
Designing SUBF . . . . . . . . . . . 998
Coding and Setting Up SUBF in Your Program 998
Numerical Quadrature Subroutines. . . . . . 999
SPTNQ and DPTNQ (Numerical Quadrature
Performed on a Set of Points) . . . . . . . . 999
SGLNQ and DGLNQ (Numerical Quadrature
Performed on a Function Using Gauss-Legendre
Quadrature) . . . . . . . . . . . . . 1001
SGLNQ2 and DGLNQ2 (Numerical Quadrature
Performed on a Function Over a Rectangle Using
Two-Dimensional Gauss-Legendre Quadrature) . 1003
SGLGQ and DGLGQ (Numerical Quadrature
Performed on a Function Using Gauss-Laguerre
Quadrature) . . . . . . . . . . . . . 1009
SGRAQ and DGRAQ (Numerical Quadrature
Performed on a Function Using Gauss-Rational
Quadrature) . . . . . . . . . . . . . 1012
SGHMQ and DGHMQ (Numerical Quadrature
Performed on a Function Using Gauss-Hermite
Quadrature) . . . . . . . . . . . . . 1015
Chapter 16. Random Number
Generation . . . . . . . . . . . . 1019
Overview of the Random Number Generation
Subroutines . . . . . . . . . . . .
. 1019
Use Considerations . . . . . . . . . .
. 1019
Random Number Generation Subroutines . .
. 1019
SURAND and DURAND (Generate a Vector of
Uniformly Distributed Random Numbers) . .
. 1019
SNRAND and DNRAND (Generate a Vector of
Normally Distributed Random Numbers) . .
. 1022
SURXOR and DURXOR (Generate a Vector of
Long Period Uniformly Distributed Random
Numbers) . . . . . . . . . . . . .
. 1025
Chapter 17. Utilities . . . . . . . . 1029
Overview of the Utility Subroutines . . . .
. 1029
Use Considerations . . . . . . . . . .
. 1029
Determining the Level of ESSL Installed . .
. 1029
Finding the Optimal Stride(s) for Your Fourier
Transforms . . . . . . . . . . . .
. 1029
Converting Sparse Matrix Storage . . . .
. 1030
Utility Subroutines . . . . . . . . . .
. 1030
EINFO (ESSL Error Information-Handler
Subroutine). . . . . . . . . . . . .
.
1030
ERRSAV (ESSL ERRSAV Subroutine) . . . .
.
1032
ERRSET (ESSL ERRSET Subroutine) . . . .
.
1033
ERRSTR (ESSL ERRSTR Subroutine) . . . .
.
1035
IESSL (Determine the Level of ESSL Installed)
1035
STRIDE (Determine the Stride Value for Optimal
Performance in Specified Fourier Transform
Subroutines) . . . . . . . . . . . .
. 1036
DSRSM (Convert a Sparse Matrix from
Storage-by-Rows to Compressed-Matrix Storage
Mode) . . . . . . . . . . . . . .
. 1052
DGKTRN (For a General Sparse Matrix, Convert
Between Diagonal-Out and Profile-In Skyline
Storage Mode). . . . . . . . . . . .
. 1055
Contents
ix
DSKTRN (For a Symmetric Sparse Matrix,
Convert Between Diagonal-Out and Profile-In
Skyline Storage Mode) . . . . . . . . .
. 1060
Part 3. Appendixes . . . . . . . 1065
Appendix A. Basic Linear Algebra
Subprograms (BLAS) . . . . . . . 1067
Appendix B. LAPACK . . . . . . . 1071
Appendix C. FFTW Version 3.1.2 to
ESSL Wrapper Libraries . . . . . . 1073
Appendix D. Accessibility
. . . . . 1077
Notices . . . . . . . . . . . . . 1079
Trademarks . . . . .
.
.
.
.
.
.
.
. 1080
Software update protocol .
.
.
.
.
.
.
.
. 1081
Programming Interfaces .
.
.
.
.
.
.
.
. 1081
Bibiography . . . . . . . . . . . 1083
Glossary . . . . . . . . . . . . . 1091
Index . . . . . . . . . . . . . . 1099
