oneapi::mkl::sparse::optimize_gemm

oneapi::mkl::sparse::optimize_gemm#

Performs internal optimizations for oneapi::mkl::sparse::gemm by analyzing the provided matrix structure and operation parameters.

Description#

The oneapi::mkl::sparse::optimize_gemm routine analyzes matrix structure and performs optimizations. Optimized data is then stored in the matrix handle. We have two versions of oneapi::mkl::sparse::optimize_gemm; one analyzes the sparse matrix pattern only, and the other version could take information about the layout and dimenstions of the dense matrices and may allow further optimizations based on the given input.

Note

Refer to Error Handling for a detailed description of the possible exceptions thrown.

API#

Syntax#

Using USM and SYCL buffers:

 namespace oneapi::mkl::sparse {
     sycl::event optimize_gemm (
         sycl::queue &queue,
         oneapi::mkl::transpose  opA,
         oneapi::mkl::sparse::matrix_handle_t A,
         const std::vector<sycl::event> &dependencies = {});

     sycl::event optimize_gemm (
         sycl::queue &queue,
         oneapi::mkl::layout layout_val,
         oneapi::mkl::transpose  opA,
         oneapi::mkl::transpose  opX,
         oneapi::mkl::sparse::matrix_handle_t A,
         const std::int64_t columns,
         const std::vector<sycl::event> &dependencies = {});
}

Include Files#

  • oneapi/mkl/spblas.hpp

Input Parameters#

queue

Specifies the SYCL command queue that 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 the input sparse matrix.

oneapi::mkl::transpose::nontrans

Non-transpose, op(A) = A.

oneapi::mkl::transpose::trans

Transpose, op(A) = AT.

oneapi::mkl::transpose::conjtrans

Conjugate transpose, op(A) = AH.

opX

Specifies operation op() on the input dense matrix.

oneapi::mkl::transpose::nontrans

Non-transpose, op(X) = X.

oneapi::mkl::transpose::trans

Transpose, op(X) = XT.

oneapi::mkl::transpose::conjtrans

Conjugate transpose, op(X) = XH.

Note

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

A

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

Note

The supported cases for <sparse_matrix_type> are csr and coo on CPU and GPU devices for the sparse::gemm() routine. Currently, the sparse::optimize_gemm() routine would be mainly beneficial to the coo sparse matrix on GPU device.

columns

Number of columns of matrix op(X) and Y of the following sparse::gemm() routine.

dependencies

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

Return Values#

sycl::event

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

sycl::event ev_opt = sparse::optimize_gemm(queue, opA, A);               // Allowed use in case of USM
sycl::event ev_opt = sparse::optimize_gemm(queue, opA, A, {});           // Allowed use in case of USM
sycl::event ev_opt = sparse::optimize_gemm(queue, opA, A, dependencies); // Allowed use in case of USM
sparse::optimize_gemm(queue, opA, A);                                    // OK Recommended use in case of sycl::buffer
static_cast<void>(sparse::optimize_gemm(queue, opA, A));                 // OK Recommended use in case of sycl::buffer (explicitly say we aren't using the event)(will be used in sycl::buffer examples)
sparse::optimize_gemm(queue, opA, A, {});                                // Not recommended in case of sycl::buffer, but supported;
sparse::optimize_gemm(queue, opA, A, dependencies);                      // Not recommended in case of sycl::buffer, but supported;
sycl::event ev_opt = sparse::optimize_gemm(queue, opA, A);               // Allowed use in case of sycl::buffer, but most sycl::buffer oneMKL APIs do not have ability to pass in dependencies

sycl::event ev_opt = sparse::optimize_gemm(queue, layout_val, opA, opX, A, columns);               // Allowed use in case of USM
sycl::event ev_opt = sparse::optimize_gemm(queue, layout_val, opA, opX, A, columns, {});           // Allowed use in case of USM
sycl::event ev_opt = sparse::optimize_gemm(queue, layout_val, opA, opX, A, columns, dependencies); // Allowed use in case of USM
sparse::optimize_gemm(queue, layout_val, opA, opX, A, columns);                                    // OK Recommended use in case of sycl::buffer
static_cast<void>(sparse::optimize_gemm(queue, layout_val, opA, opX, A, columns));                 // OK Recommended use in case of sycl::buffer (explicitly say we aren't using the event)(will be used in sycl::buffer examples)
sparse::optimize_gemm(queue, layout_val, opA, opX, A, columns, {});                                // Not recommended in case of sycl::buffer, but supported;
sparse::optimize_gemm(queue, layout_val, opA, opX, A, columns, dependencies);                      // Not recommended in case of sycl::buffer, but supported;
sycl::event ev_opt = sparse::optimize_gemm(queue, layout_val, opA, opX, A, columns);               // Allowed use in case of sycl::buffer, but most sycl::buffer oneMKL APIs do not have ability to pass in dependencies