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

✍ Scribed by coll.

• Publisher: IBM
• Year: 2003
• Tongue: English
• Leaves: 1048
• Series: SA22-7904-01
• Edition: 2nd
• Category: Library

✦ Synopsis

Retrieved from http://web.archive.org/web/20170114012551/http://www.hpcx.ac.uk/support/documentation/IBMdocuments/am501401.pdf on 2017 January 13.

This edition applies to:
v
Version 4 Release 1 of the IBM Engineering and Scientific Subroutine Library (ESSL) for Advanced Interactive
Executive (AIX) licensed program, program number 5765-F82
v
Version 4 Release 1 of the IBM Engineering and Scientific Subroutine Library (ESSL) for Linux on pSeries licensed
program, program number 5765-G17
and to all subsequent releases and modifications until otherwise indicated by new editions.

✦ Table of Contents

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