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
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:
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
andY
dense matrices.- opA
Specifies operation
op()
on input matrixA
.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 matrixX
.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 ofopX == 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 leastcolumns
iflayout_val=oneapi::mkl::layout::row-major
or at least number of columns inA
iflayout_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 leastcolumns
iflayout_val=oneapi::mkl::layout::row-major
or at least number of rows inA
iflayout_val=oneapi::mkl::layout::col-major
.- dependencies
A vector of type
std::vector<sycl::event>
containing the list of events that theoneapi::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