INTRO_BLAS1 - Introduction to vector-vector linear algebra (matrix) (LICENSE:PD) subprograms
Description
FORTRAN storage of arrays
FORTRAN array argument association
BLAS Indexing Conventions
Forward Storage
Backward Storage
Further Stride
BLAS Data Types
BLAS Naming Conventions
FORTRAN type declaration for functions
Summary Table of Level 1 BLAS Routines
To Do
See Also
References
Implementation
Author
The Level 1 BLAS perform basic vector-vector operations. The following three types of vector-vector operations are available: Routines for scaling, copying, swapping, and computing linear combination of vectors. Routines for computing dot products between vectors and various vector norms. Routines for generating or applying plane or modified plane rotations. The Basic Linear Algebra Subprograms (BLAS) were developed to enhance the portability of published linear algebra codes. Because these subprograms are portable, modular, self-documenting, and efficient, you can incorporate them into your programs. To realize the full power of the BLAS you must understand the following three subjects: - FORTRAN storage of arrays - FORTRAN array argument association - BLAS indexing conventions
Arrays in FORTRAN are stored in column major order. This means that the eariler indexes in an array declaration toggle first. Consider the following specifications: DIMENSION A(N1,N2),B(N3)EQUIVALENCE (A,B) where N3 = N1 * N2. Then A(I,J) is associated with the same memory location as B(K) where K = I + (J-1) * N1 This means that successive elements of a column of A are adjacent in memory, while successive elements of a row of A are stored with a difference of N1 storage units between them. Remember that the size of a storage unit depends on the data type.
When a FORTRAN subprogram is called with an array element as argument, the value is not passed. Instead, the subprogram receives the address in memory of the element. Consider the following code segment:M=11 N=13 REAL A(M,N) COL = 3 CALL SUBR (A(1,COL),M) . . . SUBROUTINE SUBR (X,N) REAL X(N) . . .In this example, the subroutine SUBR is given the address of the first element of the third column of A. Because it treats that argument as a one-dimensional array, successive elements X(1), X(2), ..., occupy the same memory locations as successive elements of the third column of A: that is, A(1,3), A(2,3), .... Hence, the entire third column of A is available to the subprogram.
The rest of this section describes the topics of manipulating array sections, dealing with stride arguments, and handling backward storage.A vector description in BLAS is defined by three quantities: - array or starting element within an array, for instance the variable X or X(I,J) - vector length or number of elements, for instance the variable N - the increment, sometimes called the stride, that defines the number of storage units between successive vector elements, for instance the variable INCX. The notation for describing a BLAS vector in calling a BLAS subroutine is the triad (N,X,INCX). A few very brief examples follow. If X is a one dimensional array of length N, then (N,X,1) represents forward storage of X i.e. X(1), X(2), ..., X(N) and (N,X,-1) represents backward storage of X i.e. X(N), X(N-1), ..., X(1). If A is an M by N array, then (M,A(1,J),1) represents column J and (N,A(I,1),M) represents row I. Finally, if an M by N matrix is embedded in the upper left-hand corner of an array B of size LDB by NMAX, then column J is (M,B(1,J),1) and row I is (N,B(I,1),LDB). More specific details follow.
As an example of the BLAS vector declaration using the above, suppose that X represents a declared real array. Let N be the vector length and let INCX be the increment. Suppose that a logical vector x with components x(i), i = 1, 2,..., N, is to be stored in X. If INCX >= 0, then x(i) is stored in X(1 + (I-1) * INCX). This is known as forward array storage starting at X(1) with stride equal to INCX, ending with X(1 - (N-1) * INCX). Thus, if N = 4 and INCX = 2, the logical vector x with components x(1), x(2), x(3), and x(4) are stored in memory in the array elements X(1), X(3), X(5), and X(7), respectively. This method of indexing, using a starting element, a number of elements, and a stride, is especially useful for accessing one-dimensional vectors in multidimensional arrays. For instance, if A is defined as REAL A(M,N) Then to access the 2nd row of A, one uses forward storage with an stride of M. Thus a BLAS routine call with X=A(2,1) and increment/stride of INCX=M will access A(2,i) for i = 1,2,...,N. To access the third column of A in a BLAS routine call with X=A(1,3) and increment/stride of INCX=1 This approach also works with multidimensional arrays. As an example, if A is defined as REAL A(M,N,P) to access the P elements of A at row 3 and column 4 one could call a BLAS routine with starting address X of X=A(3,4,1) and increment/stride of INCX=M*N
Some BLAS routines permit backward storage of vectors, which is specified by using a negative increment INCX. If INCX < 0, then x(i) is stored "backwards" in X. Specifically x(i) is stored in X(1 + (N-I) * |INCX|) or equivalently in X(1 - (N-I) * INCX). This is called backward storage starting from X(1 - (N-1) * INCX) with stride equal to INCX, ending with X(1). Thus, if N = 4 and INCX = -2, the logical vector components x(1), x(2), x(3), and x(4) are stored in the array elements X(7), X(5), X(3), and X(1), respectively. Note: INCX = 0 is permitted by some BLAS routines and is not permitted by others. When it is allowed, it means that logical vector x is a vector of length N, all whose components are equal the value of X(1).
EXAMPLES
The following examples illustrate how to use increment arguments to perform different operations with the same subprogram. These
EXAMPLES
use the BLAS function SDOT, with the following declarations:
INTEGER*4 N,INCX,INCY REAL*4 SDOT,S,X(1+(N-1)*|INCX|),Y(1+(N-1)*|INCY|) S = SDOT (N, X,INCX, Y,INCY)This sets S to the dot product of the vectors (N,X,INCX) and (N,Y,INCY). Example 1: Compute the dot product T = X(1)*Y(1) + X(2)*Y(2) + X(3)*Y(3) + X(4)*Y(4):REAL*4 SDOT,T,X(4),Y(4) T = SDOT (4, X,1, Y,1)Example 2: Compute the convolution T = X(1)*Y(4) + X(2)*Y(3) + X(3)*Y(2) + X(4)*Y(1):REAL*4 SDOT,T,X(4),Y(4) T = SDOT (4, X,1, Y,-1)Example 3: Compute the dot product Y(2) = A(2,1)*X(1) + A(2,2)*X(2) + A(2,3)*X(3), which is the dot product of the second row of an M by 3 matrix A, stored in a 10 by 3 array, with a 3-element vector X:INTEGER*4 N,LDA PARAMETER (LDA = 10) REAL*4 SDOT,A(LDA,3),X(3),Y(LDA) N = 3 Y(2) = SDOT (N, A(2,1),LDA, X,1)
The following data types are used in the BLAS routines: - REAL: Fortran "real" data type, 32-bit floating point; these routine names begin with S. - COMPLEX: Fortran "complex" data type, two 32-bit floating point reals; these routine names begin with C. - DOUBLE PRECISION: Fortran "double precision" data type, 64-bit floating point; these routine names begin with D. - DOUBLE COMPLEX: Fortran "double complex" data type, two 64-bit floating point doubles; these routine names begin with Z.
The following table describes the naming conventions for these
routines:
-------------------------------------------------------------
64-bit
complex
64-bit real (double
(double 32-bit complex
32-bit real precision) complex precision)
-------------------------------------------------------------
form: Sname Dname Cname Zname
example:SAXPY DAXPY CAXPY ZAXPY
-------------------------------------------------------------
Always declare the data type of external functions. Declaring the
data type of the complex Level 1 BLAS functions is particularly
important because, based on the first letter of their names and the
Fortran data typing rules, the default implied data type would be
REAL.
Fortran type declarations for function names follow:
Type Function Name
REAL SASUM, SCASUM, SCNRM2, SDOT, SNRM2, SSUM
COMPLEX CDOTC, CDOTU, CSUM
DOUBLE PRECISION DASUM, DZASUM, DDOT, DNRM2, DZNRM2, DSUM
DOUBLE COMPLEX ZDOTC, ZDOTU, ZSUM
INTEGER ISAMAX, IDAMAX, ICAMAX, IZAMAX, ISAMIN, IDAMIN,
ISMAX, IDMAX, ISMIN, IDMIN
The following table contains the purpose, operation, and name of each Level 1 BLAS routine. The first routine name listed in each table block is the name of the manual page that contains documentation for any routines listed in that block. The routines marked with an asterisk (*) are extensions to the standard set of Level 1 BLAS routines. For the complete details about each operation, see the individual man pages. Note: functions marked with an asterisk [*] are extensions to the standard set of Level 1 BLAS routines that may not be present on all systems. The man(1) command can find a man page online by either the real, complex, double precision, or double complex name.-------------------------------------------------------------- Purpose Operation -------------------------------------------------------------- Sums the absolute n SASUM values of the elements sasum <- ||x|| = Sum |x | DASUM of a real vector (also 1 i=1 i called the l1 norm) Sums the absolute scasum <- ||Real[x]|| + SCASUM values of the real and 1 DZASUM imaginary parts of the ||Imag[x]|| = elements of a complex 1 vector n Sum |Real[x ]| + i=1 i n Sum |Imag[x ]| i=1 i Adds a scalar multiple y <- alpha*x + beta*y SAXPBY* of a real or complex DAXPBY* vector to a scalar CAXPBY* multiple of another ZAXPBY* vector Adds a scalar multiple y <- alpha*x + y SAXPY of a real or complex DAXPY vector to another CAXPY vector ZAXPY Copies a real or y <- x SCOPY complex vector into DCOPY another vector CCOPY ZCOPY Computes a dot product T n SDOT of two real or complex sdot <- x y = Sum x y DDOT vectors i=1 i i H n _ CDOTC cdotc <- x y = Sum x y ZDOTC i=1 i i T n CDOTU cdotu <- x y = Sum x y ZDOTU i=1 i i Computes the Hadamard z(i):=alpha x(i) y(i) + beta SHAD* product of two vectors z(i) DHAD* CHAD* ZHAD* Computes the Euclidean snrm2 <- ||x|| = SNRM2 norm (also called l2 2 DNRM2 norm) of a real or n 2 complex vector sqrt(Sum (x ) i=1 i scnrm2 <- ||x|| = SCNRM2 2 DZNRM2 n _ sqrt(Sum (x x ) i=1 i iIn addition to the mathematical functions defined above, several search functions are a part of Level 1 BLAS; these functions are listed below:Applies a real plane CSROT* rotation to a pair of ZDROT* complex vectors Applies an orthogonal SROT plane rotation DROT Constructs a Givens SROTG plane rotation DROTG CROTG* ZROTG* Applies a modified SROTM Givens plane rotation DROTM Constructs a modified SROTMG Givens plane rotation DROTMG Scales a real or x <- alpha x SSCAL complex vector DSCAL CSCAL ZSCAL CSSCAL ZDSCAL Sums the elements of a n SSUM* real or complex vector sum <- Sum x DSUM* i=1 i CSUM* ZSUM* Swaps two real or two x <-> y SSWAP complex vectors DSWAP CSWAP ZSWAP Searches a vector for isamax <- MAX |x | ISAMAX the first occurrence of j IDAMAX the maximum absolute ICAMAX value IZAMAX Searches a vector for isamin <- MIN |x | ISAMIN* the first occurrence of j IDAMIN* the minimum absolute value Searches a vector for ismax <- MAX x ISMAX* the first occurrence of j IDMAX* the minimum absolute value Searches a vector for ismin <- MIN x ISMIN* the first occurrence of j IDMIN* the minimum absolute value --------------------------------------------------------------
ISAMAX, ICAMAX, ISAMIN*, ISMAX*, ISMIN* IDAMAX IZAMAX, IDAMIN*, IDMAX*, IDMIN*
Many of the stared functions have not been implemented yet in a free software.
intro_blas2(1), intro_blas3(1)
Lawson, C., Hanson, R., Kincaid, D., and Krogh, F., "Basic Linear Algebra Subprograms for Fortran Usage," ACM Transactions on Mathematical Software, 5 (1979), pp. 308 - 325.
See the individual man pages for implementation details and full argument listings
John L. Weatherwax
| INTRO_BLAS1 (l) | 12 August 05 |