intro_blas1(3S)
INTRO_BLAS1 - Introduction to vector-vector linear algebra subprograms
As shipped in IRIX 6.5.19. Last changed in IRIX 6.5.19.
NAME INTRO_BLAS1 - Introduction to vector-vector linear algebra subprograms IMPLEMENTATION See individual man pages for operating system and hardware availability. DESCRIPTION The Level 1 Basic Linear Algebra Subprograms (BLAS) consist of routines that perform vector-vector operations. These routines are written to run optimally on all SGI systems. The following data types are used in these routines: * Single precision: Fortran "real" data type, C/C++ "float" data type, 32-bit floating point; these routine names begin with S. * Single precision complex: Fortran "complex" data type, C/C++ "scsl_complex" data type (defined in <scsl_blas.h>), C++ STL "complex<float>" data type (defined in <complex.h>), two 32-bit floating point reals; these routine names begin with C. * Double precision: Fortran "double precision" data type, C/C++ "double" data type, 64-bit floating point; these routine names begin with D. * Double precision complex: Fortran "double complex" data type, C/C++ "scsl_zomplex" data type (defined in <scsl_blas.h>), C++ STL "complex<double>" data type (defined in <complex.h>), two 64-bit floating point doubles; these routine names begin with Z. Often little or no difference exists between these versions, other than the data types of some inputs and outputs. In this case, the routines are described on the same man page, and that man page is named after the single precision or single precision complex routine. NOTE: SCSL supports two different C interfaces to the BLAS: * The C interface described in this man page and in individual BLAS man pages follows the same conventions used for the C interface to the SCSL signal processing library. * SCSL also supports the C interface to the legacy BLAS set forth by the BLAS Technical Forum. This interface supports row-major storage of multidimensional arrays; see INTRO_CBLAS(3S) for details. By default, the integer arguments are 4 bytes (32 bits) in size; this is the size obtained when one links to the SCSL library with -lscs or -lscs_mp. Another version of SCSL is available, however, in which integers are 8 bytes (64 bits). This version allows the user access to larger memory sizes and helps when porting legacy Cray codes. It can be loaded by using either the -lscs_i8 or -lscs_i8_mp link option. Note that any program may use only one of the two versions; 4-byte integer and 8-byte integer library calls cannot be mixed. C/C++ function prototypes for Level 1 BLAS routines are provided in <scsl_blas.h>, when using the default 4-byte integers, and <scsl_blas_i8.h>, when using 8-byte integers. These header files define the complex types scsl_complex and scsl_zomplex, which are used in the prototypes. Alternatively, C++ programs may declare arguments using the types complex<float> and complex<double> from the standard template library. But if these types are used, <complex.h> must be included before <scsl_blas.h> (or <scsl_blas_i8.h>). Note, though, that both complex types are equivalent: they simply represent (real, imaginary) pairs of floating point numbers stored contiguously in memory. With the proper casts, you can simply pass arrays of floating point data to the routines where complex arguments are expected. Casts, however, can be avoided. The header files <scsl_blas.h> and <scsl_blas_i8.h> directly support the use of user-defined complex types or disabling prototype checking for complex arguments completely. By defining the symbol SCSL_VOID_ARGS before including <scsl_blas.h> or <scsl_blas_i8.h> all complex arguments will be prototyped as void *. To define the symbol SCSL_VOID_ARGS at compile time use the -D compiler option (i.e., -DSCSL_VOID_ARGS) or use an explicit #define SCSL_VOID_ARGS in the source code. This allows the use of any complex data structure without warnings from the compiler, provided the structure is as described above; that is: 1. The real and imaginary components must be contiguous in memory. 2. Sequential array elements must also be contiguous in memory. While this allows the use of non-standard complex types without generating compiler warnings, it has the disadvantage that the compiler will not catch type mismatches. Strong type checking can be enabled employing user-defined complex types instead of SCSL's standard complex types. To do this, define SCSL_USER_COMPLEX_T=my_complex and SCSL_USER_ZOMPLEX_T=my_zomplex, where my_complex and my_zomplex are the names of user-defined complex types. These complex types must be defined before including the <scsl_blas.h> (or <scsl_blas_i8.h>) header file. Fortran 90 users on IRIX systems can perform compile-time checking of SCSL BLAS subroutine and function calls by adding USE SCSL_BLAS (for 4- byte integer arguments) or USE SCSL_BLAS_I8 (for 8-byte integer arguments) to the source code from which the BLAS calls are made. Alternatively, the compile-time checking can be invoked without any source code modifications by using the -auto_use compiler option, e.g., f90 -auto_use SCSL_BLAS test.f -lscs f90 -auto_use SCSL_BLAS_I8 -i8 test.f -lscs_i8 Level 1 Basic Linear Algebra Subprograms The Level 1 BLAS perform basic vector-vector operations. The following three types of vector-vector operations are available: * Dot products and various vector norms * Scaling, copying, swapping, and computing linear combination of vectors * Generating or applying plane or modified plane rotations. Increment arguments A vector's description consists of the name of the array (x or y) followed by the storage spacing (increment) in the array of vector elements (incx or incy). The increment can be positive or negative. When a vector x consists of n elements, the corresponding actual array arguments must be of a length at least 1+(n-1)*|incx|. For a negative increment, the first element of x is assumed to be x(1+(n-1)*|incx|) for Fortran arrays, x[(n-1)*|incx|] for C/C++ arrays. The standard specification of _SCAL, _NRM2, _ASUM, and I_AMAX does not define their behavior for negative increments, so this functionality is an extension to the standard BLAS. Setting an increment argument to 0 can cause unpredictable results. Man page naming The man(1) command can find a man page online by either the single precision, single precision complex, double precision, or double precision complex name. The following table describes the naming conventions for these routines: ------------------------------------------------------------- Single Double Single Double Precision Precision Precision Precision Complex Complex ------------------------------------------------------------- form: Sname Dname Cname Zname example: SGEMM DGEMM CGEMM ZGEMM ------------------------------------------------------------- Fortran type declaration for functions Always declare the data type of external functions. Declaring the data type of the complex Level 1 BLAS functions is particularily 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 Level 1 BLAS search functions Several search functions are a part of Level 1 BLAS; these functions are listed below (functions marked with an asterisk [*] are extensions to the standard set of Level 1 BLAS routines): ISAMAX, ICAMAX, ISAMIN*, ISMAX*, ISMIN* IDAMAX IZAMAX, IDAMIN*, IDMAX*, IDMIN* List of Level 1 BLAS routines The following list contains the purpose, operation, and name of each Level 1 BLAS routine. The routines marked with an asterisk (*) are extensions to the standard set of Level 1 BLAS routines. For complete details about each operation, see the individual man pages. * SASUM, DASUM: Sums the absolute values of the elements of a real vector (also called the l1 norm). n sasum <- ||x|| = Sum |x | 1 i=1 i * SCASUM, DZASUM: Sums the absolute values of the real and imaginary parts of the elements of a complex vector, as follows: scasum <- ||Real[x]|| + ||Imag[x]|| = 1 1 n n Sum |Real[x ]| + Sum |Imag[x ]| i=1 i i=1 i * SAXPBY*, DAXPBY*, CAXPBY*, ZAXPBY*: Adds a scalar multiple of a real or complex vector to a scalar multiple of another vector. y <- alpha x + beta y * SAXPY, DAXPY, CAXPY, ZAXPY: Adds a scalar multiple of a real or complex vector to another vector. y <- alpha x + y * SCOPY, DCOPY, CCOPY, ZCOPY: Copies a real or complex vector into another vector. y <- x * SDOT, DDOT, CDOTU, ZDOTU: Computes a dot product of two real or complex vectors. T n sdot <- x y = Sum x y i=1 i i * CDOTC, ZDOTC: Computes a dot product of the conjugate of a complex vector and another complex vector. H n _ cdotc <- x y = Sum x y i=1 i i * SHAD*, DHAD*, CHAD*, ZHAD*: Computes the Hadamard product of two vectors. z <- alpha x y + beta z i i i i * SNRM2, DNRM2: Computes the Euclidean norm (also called l2 norm) of a real vector. n 2 snrm2 <- ||x|| = sqrt(Sum x ) 2 i=1 i * SCNRM2, DZNRM2: Computes the Euclidean norm (12 norm) of a complex vector. n _ scnrm2 <- ||x|| = sqrt(Sum (x x ) 2 i=1 1 1 * CSROT*, ZDROT*, CROT*, ZROT*: Applies a real plane rotation to a pair of complex vectors. * SROT, DROT: Applies an orthogonal plane rotation. * SROTG, DROTG, CROTG*, ZROTG*: Constructs a Givens plane rotation. * SROTM, DROTM: Applies a modified Givens plane rotation. * SROTMG ,DROTMG: Constructs a modified Givens plane rotation. * SSCAL, DSCAL, CSCAL, ZSCAL, CSSCAL, ZDSCAL: Scales a real or complex vector. x <- alpha x * SSUM*, DSUM*, CSUM*, ZSUM*: Sums the elements of a real or complex vector. n sum <- Sum x i=1 i * SSWAP, DSWAP, CSWAP, ZSWAP: Swaps two real or two complex vectors. x <-> y * ISAMAX, IDAMAX, ICAMAX, IZAMAX: Searches a vector for the first occurrence of the maximum absolute value. isamax <- MAX |x | j * ISAMIN*, IDAMIN*: Searches a vector for the first occurrence of the minimum absolute value. isamin <- MIN |x | j * ISMAX*, IDMAX*: Searches a vector for the first occurrence of the maximum value. ismax <- MAX x j * ISMIN*, IDMIN*: Searches a vector for the first occurrence of the minimum value. ismin <- MIN x j NOTES SCSL does not currently support reshaped arrays. SEE ALSO 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. INTRO_SCSL(3S), INTRO_BLAS2(3S), INTRO_BLAS3(3S), INTRO_CBLAS(3S)