INTRO_BLAS2(3S)INTRO_BLAS2(3S)NAME
INTRO_BLAS2 - Introduction to matrix-vector linear algebra subprograms
IMPLEMENTATION
See individual man pages for operating system and hardware availability.
DESCRIPTION
The Level 2 Basic Linear Algebra Subprograms (Level 2 BLAS) consist of
routines that perform matrix-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
Page 1
INTRO_BLAS2(3S)INTRO_BLAS2(3S)
8-byte integer library calls cannot be mixed.
C/C++ function prototypes for Level 2 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
Page 2
INTRO_BLAS2(3S)INTRO_BLAS2(3S)
Array Storage
Multidimensional arrays passed as arguments to BLAS routines must be
stored in column-major order, the storage convention used in Fortran
programs. C and C++ users must explicitly store multidimensional arrays
column-by-column. One way to do this is to reverse the order of array
dimensions with respect to the Fortran declaration (e.g., x(ldx,n) in
Fortran versus x[n][ldx] in C/C++). Because of the prototypes used in
<scsl_blas.h>, the array should be cast as a pointer to the appropriate
type when passed as an argument to a BLAS routine in order to avoid
potential compiler type mismatch errors or warning messages.
C and C++ users who want to employ row-major storage for multidimensional
arrays when calling the BLAS routines should consult the INTRO_CBLAS(3S)
man page.
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.
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
-------------------------------------------------------------
List of Level 2 BLAS routines
The following list describes these routines. The list is in alphabetic
order, except that each Hermitian matrix routine (any routine whose name
begins with CH) is grouped next to equivalent symmetric matrix routines
(whose names begin with SS or CS). This is because the Hermitian
property is a type of symmetry.
Each routine marked with an asterisk (*) is an extension to the standard
set of Level 2 BLAS routines.
Page 3
INTRO_BLAS2(3S)INTRO_BLAS2(3S)
* CHBMV, ZHBMV: Multiplies a complex vector by a complex Hermitian
band matrix.
y <- alpha Ax + beta y
* CHEMV, ZHEMV: Multiplies a complex vector by a complex Hermitian
matrix.
y <- alpha Ax + beta y
* CHER, ZHER: Performs Hermitian rank 1 update of a complex Hermitian
matrix.
H
A <- alpha xx + A
* CHER2, ZHER2: Performs Hermitian rank 2 update of a complex Hermitian
matrix.
H _____ H
A <- alpha xy + alpha yx + A
* CHPMV, ZHPMV: Multiplies a complex vector by a packed complex
Hermitian matrix.
y <- alpha Ax + beta y
* CHPR, ZHPR: Performs Hermitian rank 1 update of a packed complex
Hermitian matrix.
H
A <- alpha xx + A
* CHPR2, ZHPR2: Performs Hermitian rank 2 update of a packed complex
Hermitian matrix.
H _____ H
A <- alpha xy + alpha yx + A
* SGBMV, DGBMV, CGBMV, ZGBMV: Multiplies a real or complex vector by a
real or complex general band matrix.
y <- alpha op(A) x + beta y
where
Page 4
INTRO_BLAS2(3S)INTRO_BLAS2(3S)op(A) = A
or
T
op(A) = A
or
H
op(A) = A (CGBMV, ZGBMV only)
* SGEMV, DGEMV, CGEMV, ZGEMV: Multiplies a real or complex vector by a
real or complex general matrix.
y <- alpha op(A) x + beta y
where
op(A) = A
or
T
op(A) = A
or
H
op(A) = A (CGEMV, ZGEMV only)
* SGER, DGER: Performs rank 1 update of a real general matrix.
T
A <- alpha xy + A
* CGERC, ZGERC: Performs conjugated rank 1 update of a complex general
matrix.
H
A <- alpha xy + A
* CGERU, ZGERU: Performs unconjugated rank 1 update of a complex
general matrix.
T
A <- alpha xy + A
Page 5
INTRO_BLAS2(3S)INTRO_BLAS2(3S)
* SGESUM*, DGESUM*, CGESUM*, ZGESUM*: Adds a scalar multiple of a real
or complex matrix to a scalar multiple of another real or complex
matrix.
B <- alpha op(A) + beta B
where
op(A) = A
or
T
op(A) = A
or
H
op(A) = A (CGESUM, ZGESUM only)
* SSBMV, DSBMV: Multiplies a real vector by a real symmetric band
matrix.
y <- alpha Ax + beta y
* SSPMV, DSPMV, CSPMV*, ZSPMV*: Multiplies a real or complex vector by
a real or complex symmetric packed matrix.
y <- alpha Ax + beta y
* SSPR, DSPR, CSPR*, ZSPR*: Performs symmetric rank 1 update of a real
or complex symmetric packed matrix.
T
A <- alpha xx + A
* SSPR2, DSPR2: Performs symmetric rank 2 update of a real symmetric
packed matrix.
T T
A <- alpha xy + alpha yx + A
* SSYMV, DSYMV, CSYMV*, ZSYMV*: Multiplies a real or complex vector by
a real or complex symmetric matrix.
y <- alpha Ax + beta y
Page 6
INTRO_BLAS2(3S)INTRO_BLAS2(3S)
* SSYR, DSYR, CSYR*, ZSYR*: Performs symmetric rank 1 update of a real
or complex symmetric matrix.
T
A <- alpha xx + A
* SSYR2, DSYR2: Performs symmetric rank 2 update of a real symmetric
matrix.
T T
A <- alpha xy + alpha yx + A
* STBMV, DTBMV, CTBMV, ZTBMV: Multiplies a real or complex vector by a
real or complex triangular band matrix.
x <- op(A)
where
op(A) = A
or
T
op(A) = A
or
H
op(A) = A (CTBMV, ZTBMV only)
* STBSV, DTBSV, CTBSV, ZTBSV: Solves a real or complex triangular band
system of equations.
-1
x <- op(A)x
where
op(A) = A
or
T
op(A) = A
or
Page 7
INTRO_BLAS2(3S)INTRO_BLAS2(3S)
H
op(A) = A (CTBSV, ZTBSV only)
* STPMV, DTPMV, CTPMV, ZTPMV: Multiplies a real or complex vector by a
real or complex triangular packed matrix.
x <- op(A)
where
op(A) = A
or
T
op(A) = A
or
H
op(A) = A (CTPMV, ZTPMV only)
* STPSV, DTPSV, CTPSV, ZTPSV: Solves a real or complex triangular
packed system of equations.
-1
x <- op(A)
where
op(A) = A
or
T
op(A) = A
or
H
op(A) = A (CTPSV. ZTPSV only)
* STRMV, DTRMV, CTRMV, ZTRMV: Multiplies a real or complex vector by a
real or complex triangular matrix.
x <- op(A)
where
Page 8
INTRO_BLAS2(3S)INTRO_BLAS2(3S)op(A) = A
or
T
op(A) = A
or
H
op(A) = A (CTRMV, ZTRMV only)
* STRSV, DTRSV, CTRSV, ZTRSV: Solves a real or complex triangular
system of equations.
-1
x <- op(A)
where
op(A) = A
or
T
op(A) = A
or
H
op(A) = A (CTRSV, ZTRSV only)
NOTES
SCSL does not currently support reshaped arrays.
SEE ALSO
Dongarra, J., J. Du Croz, S. Hammarling, and R. Hanson, "An Extended Set
of FORTRAN Basic Linear Algebra Subprograms," ACM Transactions on
Mathematical Software, Vol. 14, No. 1, March 1988, pp. 1 - 17.
INTRO_SCSL(3S), INTRO_BLAS1(3S), INTRO_BLAS3(3S), INTRO_CBLAS(3S)
Page 9