gemm

Computes a sparse matrix times dense matrix product.

Description and Assumptions

Refer to Supported Types for a list of supported <fp> and <intType> types. The oneapi::mkl::sparse::gemm routine computes a sparse matrix-dense matrix product defined as

\[C \leftarrow \alpha \cdot \text{op}(A) \cdot \text{op}(B) + \beta \cdot C\]

where \(\alpha\) and \(\beta\) are scalars, \(A\) is a sparse matrix, \(B\) and \(C\) are dense matrices, \(\text{op}()\) is a matrix modifier for \(A\) and \(B\) 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}\]

and \(\text{op}(A)\) is an m-by-k matrix , \(\text{op}(B)\) is an k-by-columns matrix, and \(C\) is an m-by-columns matrix.

Dense matrix storage is in either row-major or column-major format. Sparse matrix formats are compressed sparse row (CSR) formats.

gemm (Buffer version)

Syntax

namespace oneapi::mkl::sparse {

   void gemm (sycl::queue                          &queue,
              oneapi::mkl::layout                  dense_matrix_layout,
              oneapi::mkl::transpose               transpose_A,
              oneapi::mkl::transpose               transpose_B,
              const fp                             alpha,
              oneapi::mkl::sparse::matrix_handle_t A_handle,
              sycl::buffer<fp, 1>                  &B,
              const std::int64_t                   columns,
              const std::int64_t                   ldb,
              const fp                             beta,
              sycl::buffer<fp, 1>                  &C,
              const std::int64_t                   ldc);

}

Input parameters

queue

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

dense_matrix_layout

Specifies the storage scheme in memory for the dense matrices. Note that this layout applies to both \(B\) and \(C\) dense matrices. The possible options are described in layout enum class.

transpose_A

Specifies operation op() on input matrix \(A\). The possible options are described in transpose enum class.

transpose_B

Specifies operation op() on input matrix \(B\). The possible options are described in transpose enum class.

alpha

Specifies the scalar \(\alpha\).

A_handle

Handle to object containing sparse matrix, \(A\). Created using the oneapi::mkl::sparse::set_csr_data routine.

B

The input dense matrix \(B\) in the sparse matrix-dense matrix product. \(B\) is a one dimensional SYCL memory object containing an array of size:

	B not transposed	B transposed
Row major	B is an k-by-columns matrix so must have size at least k*ldb.	B is an columns-by-k matrix so must have size at least columns*ldb
Column major	B is an k-by-columns matrix so must have size at least ldb*columns.	B is an columns-by-k matrix so must have size at least ldb*k

See Matrix Storage for more details.

columns

Number of columns of matrix \(C\).

ldb

Specifies the leading dimension of matrix \(B\). It must be positive.

	B not transposed	B transposed
Row major	ldb must be at least columns.	ldb must be at least k.
Column major	ldb must be at least k.	ldb must be at least columns.

beta

Specifies the scalar beta.

C

The dense matrix input/output array. A one-dimensional SYCL memory object containing an array of size at least m*ldc if row_major layout is used to store dense matrices or at least ldc*columns if column_major layout is used to store dense matrices.

ldc

Specifies the leading dimension of matrix \(C\). Must be positive and at least columns if row major layout is used to store dense matrices or at least m if column major layout is used to store dense matrices.

Output Parameters

C

Dense matrix output is overwritten by the updated matrix, \(C\).

Throws

This routine shall throw the following exceptions if the associated condition is detected. An implementation may throw additional implementation-specific exception(s) in case of error conditions not covered here.

oneapi::mkl::computation_error

oneapi::mkl::device_bad_alloc

oneapi::mkl::host_bad_alloc

oneapi::mkl::invalid_argument

oneapi::mkl::unimplemented

oneapi::mkl::uninitialized

oneapi::mkl::unsupported_device

gemm (USM version)

Syntax

namespace oneapi::mkl::sparse {

   sycl::event gemm (sycl::queue                           &queue,
                     oneapi::mkl::layout                   dense_matrix_layout,
                     oneapi::mkl::transpose                transpose_A,
                     oneapi::mkl::transpose                transpose_B,
                     const fp                              alpha,
                     oneapi::mkl::sparse::matrix_handle_t  A_handle,
                     const fp                              *B,
                     const std::int64_t                    columns,
                     const std::int64_t                    ldb,
                     const fp                              beta,
                     fp                                    *C,
                     const std::int64_t                    ldc,
                     const std::vector<sycl::event>        &dependencies = {});

}

Input parameters

queue

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

dense_matrix_layout

Specifies the storage scheme in memory for the dense matrices. Note that this layout applies to both \(B\) and \(C\) dense matrices. The possible options are described in layout enum class.

transpose_A

Specifies operation op() on input matrix \(A\). The possible options are described in transpose enum class.

transpose_B

Specifies operation op() on input matrix \(B\). The possible options are described in transpose enum class.

alpha

Specifies the scalar \(\alpha\).

A_handle

Handle to object containing sparse matrix, \(A\). Created using the oneapi::mkl::sparse::set_csr_data routine.

B

The dense matrix in the sparse-dense matrix product. A device accessible USM object containing an array of size:

	B not transposed	B transposed
Row major	B is an k-by-columns matrix so must have size at least k*ldb.	B is an columns-by-k matrix so must have size at least columns*ldb
Column major	B is an k-by-columns matrix so must have size at least ldb*columns.	B is an columns-by-k matrix so must have size at least ldb*k

See Matrix Storage for more details.

columns

Number of columns of matrix \(C\).

ldb

Specifies the leading dimension of matrix \(B\). It must be positive.

	B not transposed	B transposed
Row major	ldb must be at least columns.	ldb must be at least k.
Column major	ldb must be at least k.	ldb must be at least columns.

beta

Specifies the scalar beta.

C

The dense matrix input/output array. A device accessible USM object containing an array of size at least m*ldc if row_major layout is used to store dense matrices or at least ldc*columns if column_major layout is used to store dense matrices.

ldc

Specifies the leading dimension of matrix \(C\). Must be positive and at least columns if row major layout is used to store dense matrices or at least m if column major layout is used to store dense matrices.

dependencies

List of events that oneapi::mkl::sparse::gemm routine depends on. If omitted, defaults to no dependencies.

Output Parameters

C

Dense matrix output is overwritten by the updated matrix \(C\).

Throws

This routine shall throw the following exceptions if the associated condition is detected. An implementation may throw additional implementation-specific exception(s) in case of error conditions not covered here.

oneapi::mkl::computation_error

oneapi::mkl::device_bad_alloc

oneapi::mkl::host_bad_alloc

oneapi::mkl::invalid_argument

oneapi::mkl::unimplemented

oneapi::mkl::uninitialized

oneapi::mkl::unsupported_device

Return Values

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

Parent topic: Sparse BLAS