| @cindex linear algebra, BLAS |
| @cindex matrix, operations |
| @cindex vector, operations |
| @cindex BLAS |
| @cindex CBLAS |
| @cindex Basic Linear Algebra Subroutines (BLAS) |
| |
| The Basic Linear Algebra Subprograms (@sc{blas}) define a set of fundamental |
| operations on vectors and matrices which can be used to create optimized |
| higher-level linear algebra functionality. |
| |
| The library provides a low-level layer which corresponds directly to the |
| C-language @sc{blas} standard, referred to here as ``@sc{cblas}'', and a |
| higher-level interface for operations on GSL vectors and matrices. |
| Users who are interested in simple operations on GSL vector and matrix |
| objects should use the high-level layer, which is declared in the file |
| @code{gsl_blas.h}. This should satisfy the needs of most users. Note |
| that GSL matrices are implemented using dense-storage so the interface |
| only includes the corresponding dense-storage @sc{blas} functions. The full |
| @sc{blas} functionality for band-format and packed-format matrices is |
| available through the low-level @sc{cblas} interface. |
| |
| The interface for the @code{gsl_cblas} layer is specified in the file |
| @code{gsl_cblas.h}. This interface corresponds to the @sc{blas} Technical |
| Forum's draft standard for the C interface to legacy @sc{blas} |
| implementations. Users who have access to other conforming @sc{cblas} |
| implementations can use these in place of the version provided by the |
| library. Note that users who have only a Fortran @sc{blas} library can |
| use a @sc{cblas} conformant wrapper to convert it into a @sc{cblas} |
| library. A reference @sc{cblas} wrapper for legacy Fortran |
| implementations exists as part of the draft @sc{cblas} standard and can |
| be obtained from Netlib. The complete set of @sc{cblas} functions is |
| listed in an appendix (@pxref{GSL CBLAS Library}). |
| |
| There are three levels of @sc{blas} operations, |
| |
| @table @b |
| @item Level 1 |
| Vector operations, e.g. @math{y = \alpha x + y} |
| @item Level 2 |
| Matrix-vector operations, e.g. @math{y = \alpha A x + \beta y} |
| @item Level 3 |
| Matrix-matrix operations, e.g. @math{C = \alpha A B + C} |
| @end table |
| |
| @noindent |
| Each routine has a name which specifies the operation, the type of |
| matrices involved and their precisions. Some of the most common |
| operations and their names are given below, |
| |
| @table @b |
| @item DOT |
| scalar product, @math{x^T y} |
| @item AXPY |
| vector sum, @math{\alpha x + y} |
| @item MV |
| matrix-vector product, @math{A x} |
| @item SV |
| matrix-vector solve, @math{inv(A) x} |
| @item MM |
| matrix-matrix product, @math{A B} |
| @item SM |
| matrix-matrix solve, @math{inv(A) B} |
| @end table |
| |
| @noindent |
| The types of matrices are, |
| |
| @table @b |
| @item GE |
| general |
| @item GB |
| general band |
| @item SY |
| symmetric |
| @item SB |
| symmetric band |
| @item SP |
| symmetric packed |
| @item HE |
| hermitian |
| @item HB |
| hermitian band |
| @item HP |
| hermitian packed |
| @item TR |
| triangular |
| @item TB |
| triangular band |
| @item TP |
| triangular packed |
| @end table |
| |
| @noindent |
| Each operation is defined for four precisions, |
| |
| @table @b |
| @item S |
| single real |
| @item D |
| double real |
| @item C |
| single complex |
| @item Z |
| double complex |
| @end table |
| |
| @noindent |
| Thus, for example, the name @sc{sgemm} stands for ``single-precision |
| general matrix-matrix multiply'' and @sc{zgemm} stands for |
| ``double-precision complex matrix-matrix multiply''. |
| |
| @menu |
| * GSL BLAS Interface:: |
| * BLAS Examples:: |
| * BLAS References and Further Reading:: |
| @end menu |
| |
| @node GSL BLAS Interface |
| @section GSL BLAS Interface |
| |
| GSL provides dense vector and matrix objects, based on the relevant |
| built-in types. The library provides an interface to the @sc{blas} |
| operations which apply to these objects. The interface to this |
| functionality is given in the file @code{gsl_blas.h}. |
| |
| @comment CblasNoTrans, CblasTrans, CblasConjTrans |
| @comment CblasUpper, CblasLower |
| @comment CblasNonUnit, CblasUnit |
| @comment CblasLeft, CblasRight |
| |
| @menu |
| * Level 1 GSL BLAS Interface:: |
| * Level 2 GSL BLAS Interface:: |
| * Level 3 GSL BLAS Interface:: |
| @end menu |
| |
| @node Level 1 GSL BLAS Interface |
| @subsection Level 1 |
| |
| @deftypefun int gsl_blas_sdsdot (float @var{alpha}, const gsl_vector_float * @var{x}, const gsl_vector_float * @var{y}, float * @var{result}) |
| @cindex DOT, Level-1 BLAS |
| This function computes the sum @math{\alpha + x^T y} for the vectors |
| @var{x} and @var{y}, returning the result in @var{result}. |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_sdot (const gsl_vector_float * @var{x}, const gsl_vector_float * @var{y}, float * @var{result}) |
| @deftypefunx int gsl_blas_dsdot (const gsl_vector_float * @var{x}, const gsl_vector_float * @var{y}, double * @var{result}) |
| @deftypefunx int gsl_blas_ddot (const gsl_vector * @var{x}, const gsl_vector * @var{y}, double * @var{result}) |
| These functions compute the scalar product @math{x^T y} for the vectors |
| @var{x} and @var{y}, returning the result in @var{result}. |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_cdotu (const gsl_vector_complex_float * @var{x}, const gsl_vector_complex_float * @var{y}, gsl_complex_float * @var{dotu}) |
| @deftypefunx int gsl_blas_zdotu (const gsl_vector_complex * @var{x}, const gsl_vector_complex * @var{y}, gsl_complex * @var{dotu}) |
| These functions compute the complex scalar product @math{x^T y} for the |
| vectors @var{x} and @var{y}, returning the result in @var{result} |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_cdotc (const gsl_vector_complex_float * @var{x}, const gsl_vector_complex_float * @var{y}, gsl_complex_float * @var{dotc}) |
| @deftypefunx int gsl_blas_zdotc (const gsl_vector_complex * @var{x}, const gsl_vector_complex * @var{y}, gsl_complex * @var{dotc}) |
| These functions compute the complex conjugate scalar product @math{x^H |
| y} for the vectors @var{x} and @var{y}, returning the result in |
| @var{result} |
| @end deftypefun |
| |
| @deftypefun float gsl_blas_snrm2 (const gsl_vector_float * @var{x}) |
| @deftypefunx double gsl_blas_dnrm2 (const gsl_vector * @var{x}) |
| @cindex NRM2, Level-1 BLAS |
| These functions compute the Euclidean norm |
| @c{$||x||_2 = \sqrt{\sum x_i^2}$} |
| @math{||x||_2 = \sqrt @{\sum x_i^2@}} of the vector @var{x}. |
| @end deftypefun |
| |
| @deftypefun float gsl_blas_scnrm2 (const gsl_vector_complex_float * @var{x}) |
| @deftypefunx double gsl_blas_dznrm2 (const gsl_vector_complex * @var{x}) |
| These functions compute the Euclidean norm of the complex vector @var{x}, |
| @tex |
| \beforedisplay |
| $$ |
| ||x||_2 = \sqrt{\sum (\Re(x_i)^2 + \Im(x_i)^2)}. |
| $$ |
| \afterdisplay |
| @end tex |
| @ifinfo |
| |
| @example |
| ||x||_2 = \sqrt @{\sum (\Re(x_i)^2 + \Im(x_i)^2)@}. |
| @end example |
| @end ifinfo |
| @end deftypefun |
| |
| @deftypefun float gsl_blas_sasum (const gsl_vector_float * @var{x}) |
| @deftypefunx double gsl_blas_dasum (const gsl_vector * @var{x}) |
| @cindex ASUM, Level-1 BLAS |
| These functions compute the absolute sum @math{\sum |x_i|} of the |
| elements of the vector @var{x}. |
| @end deftypefun |
| |
| @deftypefun float gsl_blas_scasum (const gsl_vector_complex_float * @var{x}) |
| @deftypefunx double gsl_blas_dzasum (const gsl_vector_complex * @var{x}) |
| These functions compute the sum of the magnitudes of the real and |
| imaginary parts of the complex vector @var{x}, |
| @c{$\sum \left( |\Re(x_i)| + |\Im(x_i)| \right)$} |
| @math{\sum |\Re(x_i)| + |\Im(x_i)|}. |
| @end deftypefun |
| |
| @deftypefun CBLAS_INDEX_t gsl_blas_isamax (const gsl_vector_float * @var{x}) |
| @deftypefunx CBLAS_INDEX_t gsl_blas_idamax (const gsl_vector * @var{x}) |
| @deftypefunx CBLAS_INDEX_t gsl_blas_icamax (const gsl_vector_complex_float * @var{x}) |
| @deftypefunx CBLAS_INDEX_t gsl_blas_izamax (const gsl_vector_complex * @var{x}) |
| @cindex AMAX, Level-1 BLAS |
| These functions return the index of the largest element of the vector |
| @var{x}. The largest element is determined by its absolute magnitude for |
| real vectors and by the sum of the magnitudes of the real and imaginary |
| parts @math{|\Re(x_i)| + |\Im(x_i)|} for complex vectors. If the |
| largest value occurs several times then the index of the first |
| occurrence is returned. |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_sswap (gsl_vector_float * @var{x}, gsl_vector_float * @var{y}) |
| @deftypefunx int gsl_blas_dswap (gsl_vector * @var{x}, gsl_vector * @var{y}) |
| @deftypefunx int gsl_blas_cswap (gsl_vector_complex_float * @var{x}, gsl_vector_complex_float * @var{y}) |
| @deftypefunx int gsl_blas_zswap (gsl_vector_complex * @var{x}, gsl_vector_complex * @var{y}) |
| @cindex SWAP, Level-1 BLAS |
| These functions exchange the elements of the vectors @var{x} and @var{y}. |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_scopy (const gsl_vector_float * @var{x}, gsl_vector_float * @var{y}) |
| @deftypefunx int gsl_blas_dcopy (const gsl_vector * @var{x}, gsl_vector * @var{y}) |
| @deftypefunx int gsl_blas_ccopy (const gsl_vector_complex_float * @var{x}, gsl_vector_complex_float * @var{y}) |
| @deftypefunx int gsl_blas_zcopy (const gsl_vector_complex * @var{x}, gsl_vector_complex * @var{y}) |
| @cindex COPY, Level-1 BLAS |
| These functions copy the elements of the vector @var{x} into the vector |
| @var{y}. |
| @end deftypefun |
| |
| |
| @deftypefun int gsl_blas_saxpy (float @var{alpha}, const gsl_vector_float * @var{x}, gsl_vector_float * @var{y}) |
| @deftypefunx int gsl_blas_daxpy (double @var{alpha}, const gsl_vector * @var{x}, gsl_vector * @var{y}) |
| @deftypefunx int gsl_blas_caxpy (const gsl_complex_float @var{alpha}, const gsl_vector_complex_float * @var{x}, gsl_vector_complex_float * @var{y}) |
| @deftypefunx int gsl_blas_zaxpy (const gsl_complex @var{alpha}, const gsl_vector_complex * @var{x}, gsl_vector_complex * @var{y}) |
| @cindex AXPY, Level-1 BLAS |
| @cindex DAXPY, Level-1 BLAS |
| @cindex SAXPY, Level-1 BLAS |
| These functions compute the sum @math{y = \alpha x + y} for the vectors |
| @var{x} and @var{y}. |
| @end deftypefun |
| |
| @deftypefun void gsl_blas_sscal (float @var{alpha}, gsl_vector_float * @var{x}) |
| @deftypefunx void gsl_blas_dscal (double @var{alpha}, gsl_vector * @var{x}) |
| @deftypefunx void gsl_blas_cscal (const gsl_complex_float @var{alpha}, gsl_vector_complex_float * @var{x}) |
| @deftypefunx void gsl_blas_zscal (const gsl_complex @var{alpha}, gsl_vector_complex * @var{x}) |
| @deftypefunx void gsl_blas_csscal (float @var{alpha}, gsl_vector_complex_float * @var{x}) |
| @deftypefunx void gsl_blas_zdscal (double @var{alpha}, gsl_vector_complex * @var{x}) |
| @cindex SCAL, Level-1 BLAS |
| These functions rescale the vector @var{x} by the multiplicative factor |
| @var{alpha}. |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_srotg (float @var{a}[], float @var{b}[], float @var{c}[], float @var{s}[]) |
| @deftypefunx int gsl_blas_drotg (double @var{a}[], double @var{b}[], double @var{c}[], double @var{s}[]) |
| @cindex ROTG, Level-1 BLAS |
| @cindex Givens Rotation, BLAS |
| These functions compute a Givens rotation @math{(c,s)} which zeroes the |
| vector @math{(a,b)}, |
| @tex |
| \beforedisplay |
| $$ |
| \left( |
| \matrix{c&s\cr |
| -s&c\cr} |
| \right) |
| \left( |
| \matrix{a\cr |
| b\cr} |
| \right) |
| = |
| \left( |
| \matrix{r'\cr |
| 0\cr} |
| \right) |
| $$ |
| \afterdisplay |
| @end tex |
| @ifinfo |
| |
| @example |
| [ c s ] [ a ] = [ r ] |
| [ -s c ] [ b ] [ 0 ] |
| @end example |
| |
| @end ifinfo |
| @noindent |
| The variables @var{a} and @var{b} are overwritten by the routine. |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_srot (gsl_vector_float * @var{x}, gsl_vector_float * @var{y}, float @var{c}, float @var{s}) |
| @deftypefunx int gsl_blas_drot (gsl_vector * @var{x}, gsl_vector * @var{y}, const double @var{c}, const double @var{s}) |
| These functions apply a Givens rotation @math{(x', y') = (c x + s y, -s |
| x + c y)} to the vectors @var{x}, @var{y}. |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_srotmg (float @var{d1}[], float @var{d2}[], float @var{b1}[], float @var{b2}, float @var{P}[]) |
| @deftypefunx int gsl_blas_drotmg (double @var{d1}[], double @var{d2}[], double @var{b1}[], double @var{b2}, double @var{P}[]) |
| @cindex Modified Givens Rotation, BLAS |
| @cindex Givens Rotation, Modified, BLAS |
| These functions compute a modified Givens transformation. The modified |
| Givens transformation is defined in the original Level-1 @sc{blas} |
| specification, given in the references. |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_srotm (gsl_vector_float * @var{x}, gsl_vector_float * @var{y}, const float @var{P}[]) |
| @deftypefunx int gsl_blas_drotm (gsl_vector * @var{x}, gsl_vector * @var{y}, const double @var{P}[]) |
| These functions apply a modified Givens transformation. |
| @end deftypefun |
| |
| @node Level 2 GSL BLAS Interface |
| @subsection Level 2 |
| |
| @deftypefun int gsl_blas_sgemv (CBLAS_TRANSPOSE_t @var{TransA}, float @var{alpha}, const gsl_matrix_float * @var{A}, const gsl_vector_float * @var{x}, float @var{beta}, gsl_vector_float * @var{y}) |
| @deftypefunx int gsl_blas_dgemv (CBLAS_TRANSPOSE_t @var{TransA}, double @var{alpha}, const gsl_matrix * @var{A}, const gsl_vector * @var{x}, double @var{beta}, gsl_vector * @var{y}) |
| @deftypefunx int gsl_blas_cgemv (CBLAS_TRANSPOSE_t @var{TransA}, const gsl_complex_float @var{alpha}, const gsl_matrix_complex_float * @var{A}, const gsl_vector_complex_float * @var{x}, const gsl_complex_float @var{beta}, gsl_vector_complex_float * @var{y}) |
| @deftypefunx int gsl_blas_zgemv (CBLAS_TRANSPOSE_t @var{TransA}, const gsl_complex @var{alpha}, const gsl_matrix_complex * @var{A}, const gsl_vector_complex * @var{x}, const gsl_complex @var{beta}, gsl_vector_complex * @var{y}) |
| @cindex GEMV, Level-2 BLAS |
| These functions compute the matrix-vector product and sum @math{y = |
| \alpha op(A) x + \beta y}, where @math{op(A) = A}, |
| @math{A^T}, @math{A^H} for @var{TransA} = @code{CblasNoTrans}, |
| @code{CblasTrans}, @code{CblasConjTrans}. |
| @end deftypefun |
| |
| |
| @deftypefun int gsl_blas_strmv (CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{TransA}, CBLAS_DIAG_t @var{Diag}, const gsl_matrix_float * @var{A}, gsl_vector_float * @var{x}) |
| @deftypefunx int gsl_blas_dtrmv (CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{TransA}, CBLAS_DIAG_t @var{Diag}, const gsl_matrix * @var{A}, gsl_vector * @var{x}) |
| @deftypefunx int gsl_blas_ctrmv (CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{TransA}, CBLAS_DIAG_t @var{Diag}, const gsl_matrix_complex_float * @var{A}, gsl_vector_complex_float * @var{x}) |
| @deftypefunx int gsl_blas_ztrmv (CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{TransA}, CBLAS_DIAG_t @var{Diag}, const gsl_matrix_complex * @var{A}, gsl_vector_complex * @var{x}) |
| @cindex TRMV, Level-2 BLAS |
| These functions compute the matrix-vector product |
| @math{x = op(A) x} for the triangular matrix @var{A}, where |
| @math{op(A) = A}, @math{A^T}, @math{A^H} for @var{TransA} = |
| @code{CblasNoTrans}, @code{CblasTrans}, @code{CblasConjTrans}. When |
| @var{Uplo} is @code{CblasUpper} then the upper triangle of @var{A} is |
| used, and when @var{Uplo} is @code{CblasLower} then the lower triangle |
| of @var{A} is used. If @var{Diag} is @code{CblasNonUnit} then the |
| diagonal of the matrix is used, but if @var{Diag} is @code{CblasUnit} |
| then the diagonal elements of the matrix @var{A} are taken as unity and |
| are not referenced. |
| @end deftypefun |
| |
| |
| @deftypefun int gsl_blas_strsv (CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{TransA}, CBLAS_DIAG_t @var{Diag}, const gsl_matrix_float * @var{A}, gsl_vector_float * @var{x}) |
| @deftypefunx int gsl_blas_dtrsv (CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{TransA}, CBLAS_DIAG_t @var{Diag}, const gsl_matrix * @var{A}, gsl_vector * @var{x}) |
| @deftypefunx int gsl_blas_ctrsv (CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{TransA}, CBLAS_DIAG_t @var{Diag}, const gsl_matrix_complex_float * @var{A}, gsl_vector_complex_float * @var{x}) |
| @deftypefunx int gsl_blas_ztrsv (CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{TransA}, CBLAS_DIAG_t @var{Diag}, const gsl_matrix_complex * @var{A}, gsl_vector_complex * @var{x}) |
| @cindex TRSV, Level-2 BLAS |
| These functions compute @math{inv(op(A)) x} for @var{x}, where |
| @math{op(A) = A}, @math{A^T}, @math{A^H} for @var{TransA} = |
| @code{CblasNoTrans}, @code{CblasTrans}, @code{CblasConjTrans}. When |
| @var{Uplo} is @code{CblasUpper} then the upper triangle of @var{A} is |
| used, and when @var{Uplo} is @code{CblasLower} then the lower triangle |
| of @var{A} is used. If @var{Diag} is @code{CblasNonUnit} then the |
| diagonal of the matrix is used, but if @var{Diag} is @code{CblasUnit} |
| then the diagonal elements of the matrix @var{A} are taken as unity and |
| are not referenced. |
| @end deftypefun |
| |
| |
| @deftypefun int gsl_blas_ssymv (CBLAS_UPLO_t @var{Uplo}, float @var{alpha}, const gsl_matrix_float * @var{A}, const gsl_vector_float * @var{x}, float @var{beta}, gsl_vector_float * @var{y}) |
| @deftypefunx int gsl_blas_dsymv (CBLAS_UPLO_t @var{Uplo}, double @var{alpha}, const gsl_matrix * @var{A}, const gsl_vector * @var{x}, double @var{beta}, gsl_vector * @var{y}) |
| @cindex SYMV, Level-2 BLAS |
| These functions compute the matrix-vector product and sum @math{y = |
| \alpha A x + \beta y} for the symmetric matrix @var{A}. Since the |
| matrix @var{A} is symmetric only its upper half or lower half need to be |
| stored. When @var{Uplo} is @code{CblasUpper} then the upper triangle |
| and diagonal of @var{A} are used, and when @var{Uplo} is |
| @code{CblasLower} then the lower triangle and diagonal of @var{A} are |
| used. |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_chemv (CBLAS_UPLO_t @var{Uplo}, const gsl_complex_float @var{alpha}, const gsl_matrix_complex_float * @var{A}, const gsl_vector_complex_float * @var{x}, const gsl_complex_float @var{beta}, gsl_vector_complex_float * @var{y}) |
| @deftypefunx int gsl_blas_zhemv (CBLAS_UPLO_t @var{Uplo}, const gsl_complex @var{alpha}, const gsl_matrix_complex * @var{A}, const gsl_vector_complex * @var{x}, const gsl_complex @var{beta}, gsl_vector_complex * @var{y}) |
| @cindex HEMV, Level-2 BLAS |
| These functions compute the matrix-vector product and sum @math{y = |
| \alpha A x + \beta y} for the hermitian matrix @var{A}. Since the |
| matrix @var{A} is hermitian only its upper half or lower half need to be |
| stored. When @var{Uplo} is @code{CblasUpper} then the upper triangle |
| and diagonal of @var{A} are used, and when @var{Uplo} is |
| @code{CblasLower} then the lower triangle and diagonal of @var{A} are |
| used. The imaginary elements of the diagonal are automatically assumed |
| to be zero and are not referenced. |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_sger (float @var{alpha}, const gsl_vector_float * @var{x}, const gsl_vector_float * @var{y}, gsl_matrix_float * @var{A}) |
| @deftypefunx int gsl_blas_dger (double @var{alpha}, const gsl_vector * @var{x}, const gsl_vector * @var{y}, gsl_matrix * @var{A}) |
| @deftypefunx int gsl_blas_cgeru (const gsl_complex_float @var{alpha}, const gsl_vector_complex_float * @var{x}, const gsl_vector_complex_float * @var{y}, gsl_matrix_complex_float * @var{A}) |
| @deftypefunx int gsl_blas_zgeru (const gsl_complex @var{alpha}, const gsl_vector_complex * @var{x}, const gsl_vector_complex * @var{y}, gsl_matrix_complex * @var{A}) |
| @cindex GER, Level-2 BLAS |
| @cindex GERU, Level-2 BLAS |
| These functions compute the rank-1 update @math{A = \alpha x y^T + A} of |
| the matrix @var{A}. |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_cgerc (const gsl_complex_float @var{alpha}, const gsl_vector_complex_float * @var{x}, const gsl_vector_complex_float * @var{y}, gsl_matrix_complex_float * @var{A}) |
| @deftypefunx int gsl_blas_zgerc (const gsl_complex @var{alpha}, const gsl_vector_complex * @var{x}, const gsl_vector_complex * @var{y}, gsl_matrix_complex * @var{A}) |
| @cindex GERC, Level-2 BLAS |
| These functions compute the conjugate rank-1 update @math{A = \alpha x |
| y^H + A} of the matrix @var{A}. |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_ssyr (CBLAS_UPLO_t @var{Uplo}, float @var{alpha}, const gsl_vector_float * @var{x}, gsl_matrix_float * @var{A}) |
| @deftypefunx int gsl_blas_dsyr (CBLAS_UPLO_t @var{Uplo}, double @var{alpha}, const gsl_vector * @var{x}, gsl_matrix * @var{A}) |
| @cindex SYR, Level-2 BLAS |
| These functions compute the symmetric rank-1 update @math{A = \alpha x |
| x^T + A} of the symmetric matrix @var{A}. Since the matrix @var{A} is |
| symmetric only its upper half or lower half need to be stored. When |
| @var{Uplo} is @code{CblasUpper} then the upper triangle and diagonal of |
| @var{A} are used, and when @var{Uplo} is @code{CblasLower} then the |
| lower triangle and diagonal of @var{A} are used. |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_cher (CBLAS_UPLO_t @var{Uplo}, float @var{alpha}, const gsl_vector_complex_float * @var{x}, gsl_matrix_complex_float * @var{A}) |
| @deftypefunx int gsl_blas_zher (CBLAS_UPLO_t @var{Uplo}, double @var{alpha}, const gsl_vector_complex * @var{x}, gsl_matrix_complex * @var{A}) |
| @cindex HER, Level-2 BLAS |
| These functions compute the hermitian rank-1 update @math{A = \alpha x |
| x^H + A} of the hermitian matrix @var{A}. Since the matrix @var{A} is |
| hermitian only its upper half or lower half need to be stored. When |
| @var{Uplo} is @code{CblasUpper} then the upper triangle and diagonal of |
| @var{A} are used, and when @var{Uplo} is @code{CblasLower} then the |
| lower triangle and diagonal of @var{A} are used. The imaginary elements |
| of the diagonal are automatically set to zero. |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_ssyr2 (CBLAS_UPLO_t @var{Uplo}, float @var{alpha}, const gsl_vector_float * @var{x}, const gsl_vector_float * @var{y}, gsl_matrix_float * @var{A}) |
| @deftypefunx int gsl_blas_dsyr2 (CBLAS_UPLO_t @var{Uplo}, double @var{alpha}, const gsl_vector * @var{x}, const gsl_vector * @var{y}, gsl_matrix * @var{A}) |
| @cindex SYR2, Level-2 BLAS |
| These functions compute the symmetric rank-2 update @math{A = \alpha x |
| y^T + \alpha y x^T + A} of the symmetric matrix @var{A}. Since the |
| matrix @var{A} is symmetric only its upper half or lower half need to be |
| stored. When @var{Uplo} is @code{CblasUpper} then the upper triangle |
| and diagonal of @var{A} are used, and when @var{Uplo} is |
| @code{CblasLower} then the lower triangle and diagonal of @var{A} are |
| used. |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_cher2 (CBLAS_UPLO_t @var{Uplo}, const gsl_complex_float @var{alpha}, const gsl_vector_complex_float * @var{x}, const gsl_vector_complex_float * @var{y}, gsl_matrix_complex_float * @var{A}) |
| @deftypefunx int gsl_blas_zher2 (CBLAS_UPLO_t @var{Uplo}, const gsl_complex @var{alpha}, const gsl_vector_complex * @var{x}, const gsl_vector_complex * @var{y}, gsl_matrix_complex * @var{A}) |
| @cindex HER2, Level-2 BLAS |
| These functions compute the hermitian rank-2 update @math{A = \alpha x |
| y^H + \alpha^* y x^H A} of the hermitian matrix @var{A}. Since the |
| matrix @var{A} is hermitian only its upper half or lower half need to be |
| stored. When @var{Uplo} is @code{CblasUpper} then the upper triangle |
| and diagonal of @var{A} are used, and when @var{Uplo} is |
| @code{CblasLower} then the lower triangle and diagonal of @var{A} are |
| used. The imaginary elements of the diagonal are automatically set to zero. |
| @end deftypefun |
| |
| @node Level 3 GSL BLAS Interface |
| @subsection Level 3 |
| |
| |
| @deftypefun int gsl_blas_sgemm (CBLAS_TRANSPOSE_t @var{TransA}, CBLAS_TRANSPOSE_t @var{TransB}, float @var{alpha}, const gsl_matrix_float * @var{A}, const gsl_matrix_float * @var{B}, float @var{beta}, gsl_matrix_float * @var{C}) |
| @deftypefunx int gsl_blas_dgemm (CBLAS_TRANSPOSE_t @var{TransA}, CBLAS_TRANSPOSE_t @var{TransB}, double @var{alpha}, const gsl_matrix * @var{A}, const gsl_matrix * @var{B}, double @var{beta}, gsl_matrix * @var{C}) |
| @deftypefunx int gsl_blas_cgemm (CBLAS_TRANSPOSE_t @var{TransA}, CBLAS_TRANSPOSE_t @var{TransB}, const gsl_complex_float @var{alpha}, const gsl_matrix_complex_float * @var{A}, const gsl_matrix_complex_float * @var{B}, const gsl_complex_float @var{beta}, gsl_matrix_complex_float * @var{C}) |
| @deftypefunx int gsl_blas_zgemm (CBLAS_TRANSPOSE_t @var{TransA}, CBLAS_TRANSPOSE_t @var{TransB}, const gsl_complex @var{alpha}, const gsl_matrix_complex * @var{A}, const gsl_matrix_complex * @var{B}, const gsl_complex @var{beta}, gsl_matrix_complex * @var{C}) |
| @cindex GEMM, Level-3 BLAS |
| These functions compute the matrix-matrix product and sum @math{C = |
| \alpha op(A) op(B) + \beta C} where @math{op(A) = A}, @math{A^T}, |
| @math{A^H} for @var{TransA} = @code{CblasNoTrans}, @code{CblasTrans}, |
| @code{CblasConjTrans} and similarly for the parameter @var{TransB}. |
| @end deftypefun |
| |
| |
| @deftypefun int gsl_blas_ssymm (CBLAS_SIDE_t @var{Side}, CBLAS_UPLO_t @var{Uplo}, float @var{alpha}, const gsl_matrix_float * @var{A}, const gsl_matrix_float * @var{B}, float @var{beta}, gsl_matrix_float * @var{C}) |
| @deftypefunx int gsl_blas_dsymm (CBLAS_SIDE_t @var{Side}, CBLAS_UPLO_t @var{Uplo}, double @var{alpha}, const gsl_matrix * @var{A}, const gsl_matrix * @var{B}, double @var{beta}, gsl_matrix * @var{C}) |
| @deftypefunx int gsl_blas_csymm (CBLAS_SIDE_t @var{Side}, CBLAS_UPLO_t @var{Uplo}, const gsl_complex_float @var{alpha}, const gsl_matrix_complex_float * @var{A}, const gsl_matrix_complex_float * @var{B}, const gsl_complex_float @var{beta}, gsl_matrix_complex_float * @var{C}) |
| @deftypefunx int gsl_blas_zsymm (CBLAS_SIDE_t @var{Side}, CBLAS_UPLO_t @var{Uplo}, const gsl_complex @var{alpha}, const gsl_matrix_complex * @var{A}, const gsl_matrix_complex * @var{B}, const gsl_complex @var{beta}, gsl_matrix_complex * @var{C}) |
| @cindex SYMM, Level-3 BLAS |
| These functions compute the matrix-matrix product and sum @math{C = |
| \alpha A B + \beta C} for @var{Side} is @code{CblasLeft} and @math{C = |
| \alpha B A + \beta C} for @var{Side} is @code{CblasRight}, where the |
| matrix @var{A} is symmetric. When @var{Uplo} is @code{CblasUpper} then |
| the upper triangle and diagonal of @var{A} are used, and when @var{Uplo} |
| is @code{CblasLower} then the lower triangle and diagonal of @var{A} are |
| used. |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_chemm (CBLAS_SIDE_t @var{Side}, CBLAS_UPLO_t @var{Uplo}, const gsl_complex_float @var{alpha}, const gsl_matrix_complex_float * @var{A}, const gsl_matrix_complex_float * @var{B}, const gsl_complex_float @var{beta}, gsl_matrix_complex_float * @var{C}) |
| @deftypefunx int gsl_blas_zhemm (CBLAS_SIDE_t @var{Side}, CBLAS_UPLO_t @var{Uplo}, const gsl_complex @var{alpha}, const gsl_matrix_complex * @var{A}, const gsl_matrix_complex * @var{B}, const gsl_complex @var{beta}, gsl_matrix_complex * @var{C}) |
| @cindex HEMM, Level-3 BLAS |
| These functions compute the matrix-matrix product and sum @math{C = |
| \alpha A B + \beta C} for @var{Side} is @code{CblasLeft} and @math{C = |
| \alpha B A + \beta C} for @var{Side} is @code{CblasRight}, where the |
| matrix @var{A} is hermitian. When @var{Uplo} is @code{CblasUpper} then |
| the upper triangle and diagonal of @var{A} are used, and when @var{Uplo} |
| is @code{CblasLower} then the lower triangle and diagonal of @var{A} are |
| used. The imaginary elements of the diagonal are automatically set to |
| zero. |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_strmm (CBLAS_SIDE_t @var{Side}, CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{TransA}, CBLAS_DIAG_t @var{Diag}, float @var{alpha}, const gsl_matrix_float * @var{A}, gsl_matrix_float * @var{B}) |
| @deftypefunx int gsl_blas_dtrmm (CBLAS_SIDE_t @var{Side}, CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{TransA}, CBLAS_DIAG_t @var{Diag}, double @var{alpha}, const gsl_matrix * @var{A}, gsl_matrix * @var{B}) |
| @deftypefunx int gsl_blas_ctrmm (CBLAS_SIDE_t @var{Side}, CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{TransA}, CBLAS_DIAG_t @var{Diag}, const gsl_complex_float @var{alpha}, const gsl_matrix_complex_float * @var{A}, gsl_matrix_complex_float * @var{B}) |
| @deftypefunx int gsl_blas_ztrmm (CBLAS_SIDE_t @var{Side}, CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{TransA}, CBLAS_DIAG_t @var{Diag}, const gsl_complex @var{alpha}, const gsl_matrix_complex * @var{A}, gsl_matrix_complex * @var{B}) |
| @cindex TRMM, Level-3 BLAS |
| These functions compute the matrix-matrix product @math{B = \alpha op(A) |
| B} for @var{Side} is @code{CblasLeft} and @math{B = \alpha B op(A)} for |
| @var{Side} is @code{CblasRight}. The matrix @var{A} is triangular and |
| @math{op(A) = A}, @math{A^T}, @math{A^H} for @var{TransA} = |
| @code{CblasNoTrans}, @code{CblasTrans}, @code{CblasConjTrans}. When |
| @var{Uplo} is @code{CblasUpper} then the upper triangle of @var{A} is |
| used, and when @var{Uplo} is @code{CblasLower} then the lower triangle |
| of @var{A} is used. If @var{Diag} is @code{CblasNonUnit} then the |
| diagonal of @var{A} is used, but if @var{Diag} is @code{CblasUnit} then |
| the diagonal elements of the matrix @var{A} are taken as unity and are |
| not referenced. |
| @end deftypefun |
| |
| |
| @deftypefun int gsl_blas_strsm (CBLAS_SIDE_t @var{Side}, CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{TransA}, CBLAS_DIAG_t @var{Diag}, float @var{alpha}, const gsl_matrix_float * @var{A}, gsl_matrix_float * @var{B}) |
| @deftypefunx int gsl_blas_dtrsm (CBLAS_SIDE_t @var{Side}, CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{TransA}, CBLAS_DIAG_t @var{Diag}, double @var{alpha}, const gsl_matrix * @var{A}, gsl_matrix * @var{B}) |
| @deftypefunx int gsl_blas_ctrsm (CBLAS_SIDE_t @var{Side}, CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{TransA}, CBLAS_DIAG_t @var{Diag}, const gsl_complex_float @var{alpha}, const gsl_matrix_complex_float * @var{A}, gsl_matrix_complex_float * @var{B}) |
| @deftypefunx int gsl_blas_ztrsm (CBLAS_SIDE_t @var{Side}, CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{TransA}, CBLAS_DIAG_t @var{Diag}, const gsl_complex @var{alpha}, const gsl_matrix_complex * @var{A}, gsl_matrix_complex * @var{B}) |
| @cindex TRSM, Level-3 BLAS |
| These functions compute the inverse-matrix matrix product |
| @math{B = \alpha op(inv(A))B} for @var{Side} is |
| @code{CblasLeft} and @math{B = \alpha B op(inv(A))} for |
| @var{Side} is @code{CblasRight}. The matrix @var{A} is triangular and |
| @math{op(A) = A}, @math{A^T}, @math{A^H} for @var{TransA} = |
| @code{CblasNoTrans}, @code{CblasTrans}, @code{CblasConjTrans}. When |
| @var{Uplo} is @code{CblasUpper} then the upper triangle of @var{A} is |
| used, and when @var{Uplo} is @code{CblasLower} then the lower triangle |
| of @var{A} is used. If @var{Diag} is @code{CblasNonUnit} then the |
| diagonal of @var{A} is used, but if @var{Diag} is @code{CblasUnit} then |
| the diagonal elements of the matrix @var{A} are taken as unity and are |
| not referenced. |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_ssyrk (CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{Trans}, float @var{alpha}, const gsl_matrix_float * @var{A}, float @var{beta}, gsl_matrix_float * @var{C}) |
| @deftypefunx int gsl_blas_dsyrk (CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{Trans}, double @var{alpha}, const gsl_matrix * @var{A}, double @var{beta}, gsl_matrix * @var{C}) |
| @deftypefunx int gsl_blas_csyrk (CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{Trans}, const gsl_complex_float @var{alpha}, const gsl_matrix_complex_float * @var{A}, const gsl_complex_float @var{beta}, gsl_matrix_complex_float * @var{C}) |
| @deftypefunx int gsl_blas_zsyrk (CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{Trans}, const gsl_complex @var{alpha}, const gsl_matrix_complex * @var{A}, const gsl_complex @var{beta}, gsl_matrix_complex * @var{C}) |
| @cindex SYRK, Level-3 BLAS |
| These functions compute a rank-k update of the symmetric matrix @var{C}, |
| @math{C = \alpha A A^T + \beta C} when @var{Trans} is |
| @code{CblasNoTrans} and @math{C = \alpha A^T A + \beta C} when |
| @var{Trans} is @code{CblasTrans}. Since the matrix @var{C} is symmetric |
| only its upper half or lower half need to be stored. When @var{Uplo} is |
| @code{CblasUpper} then the upper triangle and diagonal of @var{C} are |
| used, and when @var{Uplo} is @code{CblasLower} then the lower triangle |
| and diagonal of @var{C} are used. |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_cherk (CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{Trans}, float @var{alpha}, const gsl_matrix_complex_float * @var{A}, float @var{beta}, gsl_matrix_complex_float * @var{C}) |
| @deftypefunx int gsl_blas_zherk (CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{Trans}, double @var{alpha}, const gsl_matrix_complex * @var{A}, double @var{beta}, gsl_matrix_complex * @var{C}) |
| @cindex HERK, Level-3 BLAS |
| These functions compute a rank-k update of the hermitian matrix @var{C}, |
| @math{C = \alpha A A^H + \beta C} when @var{Trans} is |
| @code{CblasNoTrans} and @math{C = \alpha A^H A + \beta C} when |
| @var{Trans} is @code{CblasTrans}. Since the matrix @var{C} is hermitian |
| only its upper half or lower half need to be stored. When @var{Uplo} is |
| @code{CblasUpper} then the upper triangle and diagonal of @var{C} are |
| used, and when @var{Uplo} is @code{CblasLower} then the lower triangle |
| and diagonal of @var{C} are used. The imaginary elements of the |
| diagonal are automatically set to zero. |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_ssyr2k (CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{Trans}, float @var{alpha}, const gsl_matrix_float * @var{A}, const gsl_matrix_float * @var{B}, float @var{beta}, gsl_matrix_float * @var{C}) |
| @deftypefunx int gsl_blas_dsyr2k (CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{Trans}, double @var{alpha}, const gsl_matrix * @var{A}, const gsl_matrix * @var{B}, double @var{beta}, gsl_matrix * @var{C}) |
| @deftypefunx int gsl_blas_csyr2k (CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{Trans}, const gsl_complex_float @var{alpha}, const gsl_matrix_complex_float * @var{A}, const gsl_matrix_complex_float * @var{B}, const gsl_complex_float @var{beta}, gsl_matrix_complex_float * @var{C}) |
| @deftypefunx int gsl_blas_zsyr2k (CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{Trans}, const gsl_complex @var{alpha}, const gsl_matrix_complex * @var{A}, const gsl_matrix_complex * @var{B}, const gsl_complex @var{beta}, gsl_matrix_complex * @var{C}) |
| @cindex SYR2K, Level-3 BLAS |
| These functions compute a rank-2k update of the symmetric matrix @var{C}, |
| @math{C = \alpha A B^T + \alpha B A^T + \beta C} when @var{Trans} is |
| @code{CblasNoTrans} and @math{C = \alpha A^T B + \alpha B^T A + \beta C} when |
| @var{Trans} is @code{CblasTrans}. Since the matrix @var{C} is symmetric |
| only its upper half or lower half need to be stored. When @var{Uplo} is |
| @code{CblasUpper} then the upper triangle and diagonal of @var{C} are |
| used, and when @var{Uplo} is @code{CblasLower} then the lower triangle |
| and diagonal of @var{C} are used. |
| @end deftypefun |
| |
| @deftypefun int gsl_blas_cher2k (CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{Trans}, const gsl_complex_float @var{alpha}, const gsl_matrix_complex_float * @var{A}, const gsl_matrix_complex_float * @var{B}, float @var{beta}, gsl_matrix_complex_float * @var{C}) |
| @deftypefunx int gsl_blas_zher2k (CBLAS_UPLO_t @var{Uplo}, CBLAS_TRANSPOSE_t @var{Trans}, const gsl_complex @var{alpha}, const gsl_matrix_complex * @var{A}, const gsl_matrix_complex * @var{B}, double @var{beta}, gsl_matrix_complex * @var{C}) |
| @cindex HER2K, Level-3 BLAS |
| These functions compute a rank-2k update of the hermitian matrix @var{C}, |
| @math{C = \alpha A B^H + \alpha^* B A^H + \beta C} when @var{Trans} is |
| @code{CblasNoTrans} and @math{C = \alpha A^H B + \alpha^* B^H A + \beta C} when |
| @var{Trans} is @code{CblasConjTrans}. Since the matrix @var{C} is hermitian |
| only its upper half or lower half need to be stored. When @var{Uplo} is |
| @code{CblasUpper} then the upper triangle and diagonal of @var{C} are |
| used, and when @var{Uplo} is @code{CblasLower} then the lower triangle |
| and diagonal of @var{C} are used. The imaginary elements of the |
| diagonal are automatically set to zero. |
| @end deftypefun |
| |
| @node BLAS Examples |
| @section Examples |
| |
| The following program computes the product of two matrices using the |
| Level-3 @sc{blas} function @sc{dgemm}, |
| @tex |
| \beforedisplay |
| $$ |
| \left( |
| \matrix{0.11&0.12&0.13\cr |
| 0.21&0.22&0.23\cr} |
| \right) |
| \left( |
| \matrix{1011&1012\cr |
| 1021&1022\cr |
| 1031&1031\cr} |
| \right) |
| = |
| \left( |
| \matrix{367.76&368.12\cr |
| 674.06&674.72\cr} |
| \right) |
| $$ |
| \afterdisplay |
| @end tex |
| @ifinfo |
| |
| @example |
| [ 0.11 0.12 0.13 ] [ 1011 1012 ] [ 367.76 368.12 ] |
| [ 0.21 0.22 0.23 ] [ 1021 1022 ] = [ 674.06 674.72 ] |
| [ 1031 1032 ] |
| @end example |
| |
| @end ifinfo |
| @noindent |
| The matrices are stored in row major order, according to the C convention |
| for arrays. |
| |
| @example |
| @verbatiminclude examples/blas.c |
| @end example |
| |
| @noindent |
| Here is the output from the program, |
| |
| @example |
| $ ./a.out |
| @verbatiminclude examples/blas.out |
| @end example |
| |
| @node BLAS References and Further Reading |
| @section References and Further Reading |
| |
| Information on the @sc{blas} standards, including both the legacy and |
| draft interface standards, is available online from the @sc{blas} |
| Homepage and @sc{blas} Technical Forum web-site. |
| |
| @itemize @asis |
| @item |
| @cite{BLAS Homepage} @* |
| @uref{http://www.netlib.org/blas/} |
| @item |
| @cite{BLAS Technical Forum} @* |
| @uref{http://www.netlib.org/cgi-bin/checkout/blast/blast.pl} |
| @end itemize |
| |
| @noindent |
| The following papers contain the specifications for Level 1, Level 2 and |
| Level 3 @sc{blas}. |
| |
| @itemize @asis |
| @item |
| C. Lawson, R. Hanson, D. Kincaid, F. Krogh, ``Basic Linear Algebra |
| Subprograms for Fortran Usage'', @cite{ACM Transactions on Mathematical |
| Software}, Vol.@: 5 (1979), Pages 308--325. |
| |
| @item |
| J.J. Dongarra, J. DuCroz, S. Hammarling, R. Hanson, ``An Extended Set of |
| Fortran Basic Linear Algebra Subprograms'', @cite{ACM Transactions on |
| Mathematical Software}, Vol.@: 14, No.@: 1 (1988), Pages 1--32. |
| |
| @item |
| J.J. Dongarra, I. Duff, J. DuCroz, S. Hammarling, ``A Set of |
| Level 3 Basic Linear Algebra Subprograms'', @cite{ACM Transactions on |
| Mathematical Software}, Vol.@: 16 (1990), Pages 1--28. |
| @end itemize |
| |
| @noindent |
| Postscript versions of the latter two papers are available from |
| @uref{http://www.netlib.org/blas/}. A @sc{cblas} wrapper for Fortran @sc{blas} |
| libraries is available from the same location. |
