oneapi::mkl::sparse::gemm#

Computes a sparse matrix-dense matrix product.

Description#

Note

Refer to Sparse BLAS Supported Data and Integer Types for a list of supported <DATA_TYPE> and <INT_TYPE> data and integer types and refer to Error Handling for a detailed description of the possible exceptions thrown.

The oneapi::mkl::sparse::gemm routine computes a sparse matrix-dense matrix product defined as

\[Y \leftarrow \alpha\cdot\text{op}(A)\cdot\text{op}(X) + \beta\cdot Y\]

where: \(\alpha\) and \(\beta\) are scalars, \(A\) is a sparse matrix of size num_rows rows by num_cols columns, and \(\text{op()}\) is a matrix modifier for A and X using the following description:

\[\begin{split}\text{op}(A) = \begin{cases} A,& \text{ oneapi::mkl::transpose::nontrans}\\ A^{T},& \text{ oneapi::mkl::transpose::trans}\\A^{H},& \text{ oneapi::mkl::transpose::conjtrans.} \end{cases}\end{split}\]

The dense matrix objects X and Y are stored with row-major or column-major layout and have an appropriate number of rows for the matrix product and columns number of columns.

API#

Syntax#

Using SYCL buffers:

namespace oneapi::mkl::sparse {
    void gemm(sycl::queue &queue,
      oneapi::mkl::layout layout_val,
      oneapi::mkl::transpose opA,
      oneapi::mkl::transpose opX,
      const DATA_TYPE alpha,
      matrix_handle_t A,
      sycl::buffer<DATA_TYPE, 1> &X,
      const std::int64_t columns,
      const std::int64_t ldx,
      const DATA_TYPE beta,
      sycl::buffer<DATA_TYPE, 1> &Y,
      const std::int64_t ldy);
}

Using USM pointers:

namespace oneapi::mkl::sparse {
    sycl::event gemm(
        sycl::queue &queue,
        oneapi::mkl::layout layout_val,
        oneapi::mkl::transpose opA,
        oneapi::mkl::transpose opX,
        const DATA_TYPE alpha,
        matrix_handle_t A,
        const DATA_TYPE *X,
        const std::int64_t columns,
        const std::int64_t ldx,
        const DATA_TYPE beta,
        DATA_TYPE *Y,
        const std::int64_t ldy,
        const std::vector<sycl::event> &dependencies = {});
}

Note

In the oneMKL 2024.0 release, we removed the deprecated oneapi::mkl::sparse::gemm APIs that didn’t support the dense matrix layout or opX flag for matrix X. If you have been using the removed old oneapi::mkl::sparse::gemm API, you must update the API call by passing oneapi::mkl::layout::row-major for the layout_val parameter and oneapi::mkl::transpose::nontrans for the opX parameter, as in the following example:

int main() {
    ...
    // For using SYCL buffers
    oneapi::mkl::sparse::gemm(queue, oneapi::mkl::layout::row_major, opA, oneapi::mkl::transpose:nontrans, alpha, A, X, ... );

    or

    // For using USM pointers
    auto ev_gemm = oneapi::mkl::sparse::gemm(queue, oneapi::mkl::layout::row_major, opA, oneapi::mkl::transpose:nontrans, alpha, A, X, ... );
    ...
}

Include Files#

  • oneapi/mkl/spblas.hpp

Input Parameters#

queue

Specifies the SYCL command queue which will be used for SYCL kernels execution.

layout_val

Specifies the storage scheme in memory for the dense matrices. Note that this layout applies to both X and Y dense matrices.

opA

Specifies operation op() on input matrix A.

oneapi::mkl::transpose::nontrans

Non-transpose, \(\text{op}(A) = A\).

oneapi::mkl::transpose::trans

Transpose, \(\text{op}(A) = A^{T}\).

oneapi::mkl::transpose::conjtrans

Conjugate transpose, \(\text{op}(A) = A^{H}\).

opX

Specifies operation op() on input matrix X.

oneapi::mkl::transpose::nontrans

Non-transpose, \(\text{op}(X) = X\).

oneapi::mkl::transpose::trans

Transpose, \(\text{op}(X) = X^{T}\).

oneapi::mkl::transpose::conjtrans

Conjugate transpose, \(\text{op}(X) = X^{H}\).

Note

Currently, the only supported case for operation is oneapi::mkl::transpose::nontrans.

alpha

Specifies the scalar, \(\alpha\).

A

Handle to object containing sparse matrix and other internal data. Created using one of the oneapi::mkl::sparse::set_<sparse_matrix_type>_data routines.

X

SYCL buffer or device-accessible USM pointer of size at least rows*cols, where (with the assumption of opX == oneapi::mkl::transpose::nontrans).

layout=oneapi::mkl::layout::col-major

layout=oneapi::mkl::layout::row-major

rows (number of rows in X)

ldx

if \(\text{op}(A) = A\), number of columns in A

if \(\text{op}(A) = A^{T}\), number of rows in A

cols (number of columns in X)

columns

ldx

columns

Number of columns of matrix Y.

ldx

Specifies the leading dimension of matrix X. Must be positive, and at least columns if layout_val=oneapi::mkl::layout::row-major or at least number of columns in A if layout_val=oneapi::mkl::layout::col-major.

beta

Specifies the scalar, \(\beta\).

Y

SYCL buffer or device-accessible USM pointer of size at least rows*cols, where:

layout=oneapi::mkl::layout::col-major

layout=oneapi::mkl::layout::row-major

rows (number of rows in Y)

ldy

if \(\text{op}(A) = A\), number of rows in A

if \(\text{op}(A) = A^{T}\), number of columns in A

cols (number of columns in Y)

columns

ldy

ldy

Specifies the leading dimension of matrix Y. Must be positive, and at least columns if layout_val=oneapi::mkl::layout::row-major or at least number of rows in A if layout_val=oneapi::mkl::layout::col-major.

dependencies

A vector of type std::vector<sycl::event> containing the list of events that the oneapi::mkl::sparse::gemm routine depends on.

Output Parameters#

Y

Overwritten by the updated matrix Y.

Return Values (USM Only)#

sycl::event

SYCL event which can be waited upon or added as a dependency for the completion of the gemm routine.

Examples#

An example of how to use oneapi::mkl::sparse::gemm with SYCL buffers or USM can be found in the oneMKL installation directory, under:

share/doc/mkl/examples/sycl/sparse_blas/source/csr_gemm_row_major.cpp
share/doc/mkl/examples/sycl/sparse_blas/source/csr_gemm_row_major_usm.cpp
share/doc/mkl/examples/sycl/sparse_blas/source/csr_gemm_col_major.cpp
share/doc/mkl/examples/sycl/sparse_blas/source/csr_gemm_col_major_usm.cpp