.. _oneapi-mkl-sparse-gemm: oneapi::mkl::sparse::gemm ========================= Computes a sparse matrix-dense matrix product. .. contents:: :local: :depth: 1 Description *********** .. note:: Refer to :ref:`supported-types` for a list of supported ```` and ```` and refer to :ref:`exceptions` for a detailed description of the exceptions thrown. The ``oneapi::mkl::sparse::gemm`` routine computes a sparse matrix-dense matrix product defined as .. math:: C \leftarrow \alpha\cdot\text{op}(A)\cdot\text{op}(B) + \beta\cdot C where: :math:`\alpha` and :math:`\beta`` are scalars, :math:`A` is a sparse matrix of size ``num_rows`` rows by ``num_cols`` columns, :math:`\text{op()}` is a matrix modifier for ``A`` and ``B`` using the following description: .. math:: \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} The dense matrix objects ``B`` and ``C`` are stored with row-major or column-major layout and have appropriately sized number of rows for the matrix product and ``columns`` number of columns. API *** Syntax ------ .. note:: Currently, complex types are not supported. **Using SYCL buffers:** .. code-block:: cpp namespace oneapi::mkl::sparse { void gemm(cl::sycl::queue &queue, oneapi::mkl::layout dense_matrix_layout, oneapi::mkl::transpose transpose_A, oneapi::mkl::transpose transpose_B, const fp alpha, matrix_handle_t handle, cl::sycl::buffer &b, const std::int64_t columns, const std::int64_t ldb, const fp beta, cl::sycl::buffer &c, const std::int64_t ldc); } .. code-block:: cpp namespace oneapi::mkl::sparse { [[deprecated("Use oneapi::mkl::sparse::gemm(queue, oneapi::mkl::layout::row_major, transpose_A, oneapi::mkl::transpose:nontrans, alpha, ... ) instead.")]] void gemm ( cl::sycl::queue &queue, oneapi::mkl::transpose transpose_flag, const fp alpha, oneapi::mkl::sparse::matrix_handle_t handle, cl::sycl::buffer &b, const std::int64_t columns, const std::int64_t ldb, const fp beta, cl::sycl::buffer &c, const std::int64_t ldc) } **Using USM pointers:** .. code-block:: cpp namespace oneapi::mkl::sparse { cl::sycl::event gemm( cl::sycl::queue &queue, oneapi::mkl::layout dense_matrix_layout, oneapi::mkl::transpose transpose_A, oneapi::mkl::transpose transpose_B, const fp alpha, matrix_handle_t handle, 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 &dependencies = {}); } .. code-block:: cpp namespace oneapi::mkl::sparse { [[deprecated("Use oneapi::mkl::sparse::gemm(queue, oneapi::mkl::layout::row_major, transpose_A, oneapi::mkl::transpose:nontrans, alpha, ... ) instead.")]] cl::sycl::event gemm ( cl::sycl::queue &queue, oneapi::mkl::transpose transpose_flag, const fp alpha, oneapi::mkl::sparse::matrix_handle_t 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 &dependencies = {}) } Include Files ------------- - oneapi/mkl/spblas.hpp 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. transpose_A (in old API, transpose_flag) Specifies operation ``op()`` on input matrix ``A``. .. list-table:: :header-rows: 0 * - ``oneapi::mkl::transpose::nontrans`` - Non-transpose, :math:`\text{op}(A) = A`. * - ``oneapi::mkl::transpose::trans`` - Transpose, :math:`\text{op}(A) = A^{T}`. * - ``oneapi::mkl::transpose::conjtrans`` - Conjugate transpose, :math:`\text{op}(A) = A^{H}`. .. note:: Currently, the only supported case for operation is ``oneapi::mkl::transpose::nontrans``. transpose_B Specifies operation ``op()`` on input matrix ``B``. .. list-table:: :header-rows: 0 * - ``oneapi::mkl::transpose::nontrans`` - Non-transpose, :math:`\text{op}(B) = B`. * - ``oneapi::mkl::transpose::trans`` - Transpose, :math:`\text{op}(B) = B^{T}`. * - ``oneapi::mkl::transpose::conjtrans`` - Conjugate transpose, :math:`\text{op}(B) = B^{H}`. .. note:: Currently, the only supported case for operation is ``oneapi::mkl::transpose::nontrans``. alpha Specifies the scalar, :math:`\alpha`. handle Handle to object containing sparse matrix and other internal data. Created using one of the ``oneapi::mkl::sparse::set__data`` routines. .. note:: Currently, the only supported case for is csr. b SYCL buffer or device-accessible USM pointer of size at least ``rows*cols``, where (with the assumption of ``transpose_B == oneapi::mkl::transpose::nontrans``). .. list-table:: :header-rows: 0 * - - ``layout=oneapi::mkl::layout::col-major`` - ``layout=oneapi::mkl::layout::row-major`` * - rows (number of rows in ``B``) - ldb - if :math:`\text{op}(A) = A`, number of columns in ``A`` if :math:`\text{op}(A) = A^{T}`, number of rows in ``A`` * - cols (number of columns in ``B``) - columns - ldb columns Number of columns of matrix ``C``. ldb Specifies the leading dimension of matrix ``B``. Must be positive, and at least ``columns`` if ``dense_matrix_layout=oneapi::mkl::layout::row-major`` or at least number of columns in ``A`` if ``dense_matrix_layout=oneapi::mkl::layout::col-major``. beta Specifies the scalar, :math:`\beta`. c SYCL buffer or device-accessible USM pointer of size at least ``rows*cols``, where: .. list-table:: :header-rows: 0 * - - ``layout=oneapi::mkl::layout::col-major`` - ``layout=oneapi::mkl::layout::row-major`` * - rows (number of rows in ``C``) - ldc - if :math:`\text{op}(A) = A`, number of rows in ``A`` if :math:`\text{op}(A) = A^{T}`, number of columns in ``A`` * - cols (number of columns in ``C``) - columns - ldc ldc Specifies the leading dimension of matrix ``C``. Must be positive, and at least ``columns`` if ``dense_matrix_layout=oneapi::mkl::layout::row-major`` or at least number of rows in ``A`` if ``dense_matrix_layout=oneapi::mkl::layout::col-major``. dependencies A vector of type ``std::vector`` containing the list of events that the ``oneapi::mkl::sparse::gemm`` routine depends on. Output Parameters ----------------- c Overwritten by the updated matrix ``C``. Return Values (USM Only) ------------------------ cl::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 |O-MKL| installation directory, under: .. code-block:: examples/dpcpp/sparse_blas/source/sparse_gemm_row_major.cpp .. code-block:: examples/dpcpp/sparse_blas/source/sparse_gemm_row_major_usm.cpp .. code-block:: examples/dpcpp/sparse_blas/source/sparse_gemm_col_major.cpp .. code-block:: examples/dpcpp/sparse_blas/source/sparse_gemm_col_major_usm.cpp