[SPARSE] Update oneMKL backends to match new sparse API

docs/domains/sparse_linear_algebra.rst

@@ -0,0 +1,36 @@
+.. _onemkl_sparse_linear_algebra:
+
+Sparse Linear Algebra
+=====================
+
+See the latest specification for the sparse domain `here
+<https://oneapi-spec.uxlfoundation.org/specifications/oneapi/latest/elements/onemkl/source/domains/spblas/spblas>`_.
+
+This page documents implementation specific or backend specific details of the
+sparse domain.
+
+OneMKL Intel CPU and GPU backends
+---------------------------------
+
+Currently known limitations:
+
+- All operations' algorithms except ``no_optimize_alg`` map to the default
+  algorithm.
+- The required external workspace size is always 0 bytes.
+- ``oneapi::mkl::sparse::set_csr_data`` and
+  ``oneapi::mkl::sparse::set_coo_data`` functions cannot be used on a handle
+  that has already been used for an operation or its optimize function. Doing so
+  will throw an ``oneapi::mkl::unimplemented`` exception.
+- Using ``spsv`` with the ``oneapi::mkl::sparse::spsv_alg::no_optimize_alg`` and
+  a sparse matrix that does not have the
+  ``oneapi::mkl::sparse::matrix_property::sorted`` property will throw an
+  ``oneapi::mkl::unimplemented`` exception.
+- Using ``spmm`` on Intel GPU with a sparse matrix that is
+  ``oneapi::mkl::transpose::conjtrans`` and has the
+  ``oneapi::mkl::sparse::matrix_property::symmetric`` property will throw an
+  ``oneapi::mkl::unimplemented`` exception.
+- Using ``spsv`` on Intel GPU with a sparse matrix that is
+  ``oneapi::mkl::transpose::conjtrans`` and will throw an
+  ``oneapi::mkl::unimplemented`` exception.
+- Scalar parameters ``alpha`` and ``beta`` should be host pointers to prevent
+  synchronizations and copies to the host.

docs/index.rst

@@ -33,4 +33,5 @@ Contents
 
    onemkl-datatypes.rst
    domains/dense_linear_algebra.rst
+   domains/sparse_linear_algebra.rst
    create_new_backend.rst

examples/sparse_blas/compile_time_dispatching/CMakeLists.txt

@@ -27,8 +27,8 @@ endif()
 include(WarningsUtils)
 
 foreach(backend ${SPARSE_BLAS_BACKENDS})
-  set(EXAMPLE_NAME example_sparse_blas_gemv_usm_${backend})
-  add_executable(${EXAMPLE_NAME} sparse_blas_gemv_usm_${backend}.cpp)
+  set(EXAMPLE_NAME example_sparse_blas_spmv_usm_${backend})
+  add_executable(${EXAMPLE_NAME} sparse_blas_spmv_usm_${backend}.cpp)
   target_include_directories(${EXAMPLE_NAME}
       PUBLIC ${PROJECT_SOURCE_DIR}/examples/include
       PUBLIC ${PROJECT_SOURCE_DIR}/include
@@ -39,6 +39,6 @@ foreach(backend ${SPARSE_BLAS_BACKENDS})
   target_link_libraries(${EXAMPLE_NAME} PRIVATE ONEMKL::SYCL::SYCL onemkl_sparse_blas_${backend})
 
   # Register example as ctest
-  add_test(NAME sparse_blas/EXAMPLE/CT/sparse_blas_gemv_usm_${backend} COMMAND ${EXAMPLE_NAME})
+  add_test(NAME sparse_blas/EXAMPLE/CT/sparse_blas_spmv_usm_${backend} COMMAND ${EXAMPLE_NAME})
 endforeach(backend)
 

examples/sparse_blas/compile_time_dispatching/sparse_blas_gemv_usm_mklcpu.cpp → examples/sparse_blas/compile_time_dispatching/sparse_blas_spmv_usm_mklcpu.cpp

@@ -20,7 +20,7 @@
 /*
 *
 *  Content:
-*       This example demonstrates use of DPCPP API oneapi::mkl::sparse::gemv
+*       This example demonstrates use of DPCPP API oneapi::mkl::sparse::spmv
 *       using unified shared memory to perform general sparse matrix-vector
 *       multiplication on a INTEL CPU SYCL device.
 *
@@ -32,7 +32,7 @@
 *
 *
 *       This example demonstrates only single precision (float) data type for
-*       gemv matrix data
+*       spmv matrix data
 *
 *
 *******************************************************************************/
@@ -77,7 +77,7 @@ int run_sparse_matrix_vector_multiply_example(const sycl::device &cpu_dev) {
             }
             catch (sycl::exception const &e) {
                 std::cout << "Caught asynchronous SYCL "
-                             "exception during sparse::gemv:\n"
+                             "exception during sparse::spmv:\n"
                           << e.what() << std::endl;
             }
         }
@@ -128,7 +128,10 @@ int run_sparse_matrix_vector_multiply_example(const sycl::device &cpu_dev) {
     //
 
     oneapi::mkl::transpose transA = oneapi::mkl::transpose::nontrans;
-    std::cout << "\n\t\tsparse::gemv parameters:\n";
+    oneapi::mkl::sparse::spmv_alg alg = oneapi::mkl::sparse::spmv_alg::default_alg;
+    oneapi::mkl::sparse::matrix_view A_view;
+
+    std::cout << "\n\t\tsparse::spmv parameters:\n";
     std::cout << "\t\t\ttransA = "
               << (transA == oneapi::mkl::transpose::nontrans
                       ? "nontrans"
@@ -137,23 +140,49 @@ int run_sparse_matrix_vector_multiply_example(const sycl::device &cpu_dev) {
     std::cout << "\t\t\tnrows = " << nrows << std::endl;
     std::cout << "\t\t\talpha = " << alpha << ", beta = " << beta << std::endl;
 
-    // create and initialize handle for a Sparse Matrix in CSR format
-    oneapi::mkl::sparse::matrix_handle_t handle = nullptr;
-
-    oneapi::mkl::sparse::init_matrix_handle(cpu_selector, &handle);
-
-    auto ev_set = oneapi::mkl::sparse::set_csr_data(cpu_selector, handle, nrows, nrows, nnz,
-                                                    oneapi::mkl::index_base::zero, ia, ja, a);
-
-    auto ev_opt = oneapi::mkl::sparse::optimize_gemv(cpu_selector, transA, handle, { ev_set });
-
-    auto ev_gemv =
-        oneapi::mkl::sparse::gemv(cpu_selector, transA, alpha, handle, x, beta, y, { ev_opt });
-
-    auto ev_release =
-        oneapi::mkl::sparse::release_matrix_handle(cpu_selector, &handle, { ev_gemv });
-
-    ev_release.wait_and_throw();
+    // Create and initialize handle for a Sparse Matrix in CSR format
+    oneapi::mkl::sparse::matrix_handle_t A_handle = nullptr;
+    oneapi::mkl::sparse::init_csr_matrix(cpu_selector, &A_handle, nrows, nrows, nnz,
+                                         oneapi::mkl::index_base::zero, ia, ja, a);
+
+    // Create and initialize dense vector handles
+    oneapi::mkl::sparse::dense_vector_handle_t x_handle = nullptr;
+    oneapi::mkl::sparse::dense_vector_handle_t y_handle = nullptr;
+    oneapi::mkl::sparse::init_dense_vector(cpu_selector, &x_handle, sizevec, x);
+    oneapi::mkl::sparse::init_dense_vector(cpu_selector, &y_handle, sizevec, y);
+
+    // Create operation descriptor
+    oneapi::mkl::sparse::spmv_descr_t descr = nullptr;
+    oneapi::mkl::sparse::init_spmv_descr(cpu_selector, &descr);
+
+    // Allocate external workspace
+    std::size_t workspace_size = 0;
+    oneapi::mkl::sparse::spmv_buffer_size(cpu_selector, transA, &alpha, A_view, A_handle, x_handle,
+                                          &beta, y_handle, alg, descr, workspace_size);
+    void *workspace = sycl::malloc_device(workspace_size, cpu_queue);
+
+    // Optimize spmv
+    auto ev_opt =
+        oneapi::mkl::sparse::spmv_optimize(cpu_selector, transA, &alpha, A_view, A_handle, x_handle,
+                                           &beta, y_handle, alg, descr, workspace);
+
+    // Run spmv
+    auto ev_spmv = oneapi::mkl::sparse::spmv(cpu_selector, transA, &alpha, A_view, A_handle,
+                                             x_handle, &beta, y_handle, alg, descr, { ev_opt });
+
+    // Release handles and descriptor
+    std::vector<sycl::event> release_events;
+    release_events.push_back(
+        oneapi::mkl::sparse::release_dense_vector(cpu_selector, x_handle, { ev_spmv }));
+    release_events.push_back(
+        oneapi::mkl::sparse::release_dense_vector(cpu_selector, y_handle, { ev_spmv }));
+    release_events.push_back(
+        oneapi::mkl::sparse::release_sparse_matrix(cpu_selector, A_handle, { ev_spmv }));
+    release_events.push_back(
+        oneapi::mkl::sparse::release_spmv_descr(cpu_selector, descr, { ev_spmv }));
+    for (auto event : release_events) {
+        event.wait_and_throw();
+    }
 
     //
     // Post Processing
@@ -181,7 +210,7 @@ int run_sparse_matrix_vector_multiply_example(const sycl::device &cpu_dev) {
         good &= check_result(res[row], z[row], nrows, row);
     }
 
-    std::cout << "\n\t\t sparse::gemv example " << (good ? "passed" : "failed") << "\n\tFinished"
+    std::cout << "\n\t\t sparse::spmv example " << (good ? "passed" : "failed") << "\n\tFinished"
               << std::endl;
 
     free_vec(fp_ptr_vec, cpu_queue);
@@ -211,7 +240,7 @@ void print_example_banner() {
     std::cout << "# and alpha, beta are floating point type precision scalars." << std::endl;
     std::cout << "# " << std::endl;
     std::cout << "# Using apis:" << std::endl;
-    std::cout << "#   sparse::gemv" << std::endl;
+    std::cout << "#   sparse::spmv" << std::endl;
     std::cout << "# " << std::endl;
     std::cout << "# Using single precision (float) data type" << std::endl;
     std::cout << "# " << std::endl;
@@ -232,22 +261,22 @@ int main(int /*argc*/, char ** /*argv*/) {
         // TODO: Add cuSPARSE compile-time dispatcher in this example once it is supported.
         sycl::device cpu_dev(sycl::cpu_selector_v);
 
-        std::cout << "Running Sparse BLAS GEMV USM example on CPU device." << std::endl;
+        std::cout << "Running Sparse BLAS SPMV USM example on CPU device." << std::endl;
         std::cout << "Device name is: " << cpu_dev.get_info<sycl::info::device::name>()
                   << std::endl;
         std::cout << "Running with single precision real data type:" << std::endl;
 
         run_sparse_matrix_vector_multiply_example<float, std::int32_t>(cpu_dev);
-        std::cout << "Sparse BLAS GEMV USM example ran OK." << std::endl;
+        std::cout << "Sparse BLAS SPMV USM example ran OK." << std::endl;
     }
     catch (sycl::exception const &e) {
-        std::cerr << "Caught synchronous SYCL exception during Sparse GEMV:" << std::endl;
+        std::cerr << "Caught synchronous SYCL exception during Sparse SPMV:" << std::endl;
         std::cerr << "\t" << e.what() << std::endl;
         std::cerr << "\tSYCL error code: " << e.code().value() << std::endl;
         return 1;
     }
     catch (std::exception const &e) {
-        std::cerr << "Caught std::exception during Sparse GEMV:" << std::endl;
+        std::cerr << "Caught std::exception during Sparse SPMV:" << std::endl;
         std::cerr << "\t" << e.what() << std::endl;
         return 1;
     }

examples/sparse_blas/run_time_dispatching/CMakeLists.txt

@@ -22,7 +22,7 @@
 include(WarningsUtils)
 
 # Build object from all example sources
-set(SPARSE_BLAS_RT_SOURCES "sparse_blas_gemv_usm")
+set(SPARSE_BLAS_RT_SOURCES "sparse_blas_spmv_usm")
 # Set up for the right backend for run-time dispatching examples
 # If users build more than one backend (i.e. mklcpu and mklgpu, or mklcpu and CUDA), they may need to
 # overwrite ONEAPI_DEVICE_SELECTOR in their environment to run on the desired backend

examples/sparse_blas/run_time_dispatching/sparse_blas_gemv_usm.cpp → examples/sparse_blas/run_time_dispatching/sparse_blas_spmv_usm.cpp

@@ -20,7 +20,7 @@
 /*
 *
 *  Content:
-*       This example demonstrates use of DPCPP API oneapi::mkl::sparse::gemv
+*       This example demonstrates use of DPCPP API oneapi::mkl::sparse::spmv
 *       using unified shared memory to perform general sparse matrix-vector
 *       multiplication on a SYCL device (HOST, CPU, GPU) that is selected
 *       during runtime.
@@ -33,7 +33,7 @@
 *
 *
 *       This example demonstrates only single precision (float) data type for
-*       gemv matrix data
+*       spmv matrix data
 *
 *
 *******************************************************************************/
@@ -78,7 +78,7 @@ int run_sparse_matrix_vector_multiply_example(const sycl::device &dev) {
             }
             catch (sycl::exception const &e) {
                 std::cout << "Caught asynchronous SYCL "
-                             "exception during sparse::gemv:\n"
+                             "exception during sparse::spmv:\n"
                           << e.what() << std::endl;
             }
         }
@@ -93,6 +93,7 @@ int run_sparse_matrix_vector_multiply_example(const sycl::device &dev) {
     std::size_t sizeja = static_cast<std::size_t>(27 * nrows);
     std::size_t sizeia = static_cast<std::size_t>(nrows + 1);
     std::size_t sizevec = static_cast<std::size_t>(nrows);
+    auto sizevec_i64 = static_cast<std::int64_t>(sizevec);
 
     ia = (intType *)sycl::malloc_shared(sizeia * sizeof(intType), main_queue);
     ja = (intType *)sycl::malloc_shared(sizeja * sizeof(intType), main_queue);
@@ -128,7 +129,10 @@ int run_sparse_matrix_vector_multiply_example(const sycl::device &dev) {
     //
 
     oneapi::mkl::transpose transA = oneapi::mkl::transpose::nontrans;
-    std::cout << "\n\t\tsparse::gemv parameters:\n";
+    oneapi::mkl::sparse::spmv_alg alg = oneapi::mkl::sparse::spmv_alg::default_alg;
+    oneapi::mkl::sparse::matrix_view A_view;
+
+    std::cout << "\n\t\tsparse::spmv parameters:\n";
     std::cout << "\t\t\ttransA = "
               << (transA == oneapi::mkl::transpose::nontrans
                       ? "nontrans"
@@ -137,22 +141,49 @@ int run_sparse_matrix_vector_multiply_example(const sycl::device &dev) {
     std::cout << "\t\t\tnrows = " << nrows << std::endl;
     std::cout << "\t\t\talpha = " << alpha << ", beta = " << beta << std::endl;
 
-    // create and initialize handle for a Sparse Matrix in CSR format
-    oneapi::mkl::sparse::matrix_handle_t handle = nullptr;
-
-    oneapi::mkl::sparse::init_matrix_handle(main_queue, &handle);
-
-    auto ev_set = oneapi::mkl::sparse::set_csr_data(main_queue, handle, nrows, nrows, nnz,
-                                                    oneapi::mkl::index_base::zero, ia, ja, a);
-
-    auto ev_opt = oneapi::mkl::sparse::optimize_gemv(main_queue, transA, handle, { ev_set });
-
-    auto ev_gemv =
-        oneapi::mkl::sparse::gemv(main_queue, transA, alpha, handle, x, beta, y, { ev_opt });
-
-    auto ev_release = oneapi::mkl::sparse::release_matrix_handle(main_queue, &handle, { ev_gemv });
-
-    ev_release.wait_and_throw();
+    // Create and initialize handle for a Sparse Matrix in CSR format
+    oneapi::mkl::sparse::matrix_handle_t A_handle = nullptr;
+    oneapi::mkl::sparse::init_csr_matrix(main_queue, &A_handle, nrows, nrows, nnz,
+                                         oneapi::mkl::index_base::zero, ia, ja, a);
+
+    // Create and initialize dense vector handles
+    oneapi::mkl::sparse::dense_vector_handle_t x_handle = nullptr;
+    oneapi::mkl::sparse::dense_vector_handle_t y_handle = nullptr;
+    oneapi::mkl::sparse::init_dense_vector(main_queue, &x_handle, sizevec_i64, x);
+    oneapi::mkl::sparse::init_dense_vector(main_queue, &y_handle, sizevec_i64, y);
+
+    // Create operation descriptor
+    oneapi::mkl::sparse::spmv_descr_t descr = nullptr;
+    oneapi::mkl::sparse::init_spmv_descr(main_queue, &descr);
+
+    // Allocate external workspace
+    std::size_t workspace_size = 0;
+    oneapi::mkl::sparse::spmv_buffer_size(main_queue, transA, &alpha, A_view, A_handle, x_handle,
+                                          &beta, y_handle, alg, descr, workspace_size);
+    void *workspace = sycl::malloc_device(workspace_size, main_queue);
+
+    // Optimize spmv
+    auto ev_opt =
+        oneapi::mkl::sparse::spmv_optimize(main_queue, transA, &alpha, A_view, A_handle, x_handle,
+                                           &beta, y_handle, alg, descr, workspace);
+
+    // Run spmv
+    auto ev_spmv = oneapi::mkl::sparse::spmv(main_queue, transA, &alpha, A_view, A_handle, x_handle,
+                                             &beta, y_handle, alg, descr, { ev_opt });
+
+    // Release handles and descriptor
+    std::vector<sycl::event> release_events;
+    release_events.push_back(
+        oneapi::mkl::sparse::release_dense_vector(main_queue, x_handle, { ev_spmv }));
+    release_events.push_back(
+        oneapi::mkl::sparse::release_dense_vector(main_queue, y_handle, { ev_spmv }));
+    release_events.push_back(
+        oneapi::mkl::sparse::release_sparse_matrix(main_queue, A_handle, { ev_spmv }));
+    release_events.push_back(
+        oneapi::mkl::sparse::release_spmv_descr(main_queue, descr, { ev_spmv }));
+    for (auto event : release_events) {
+        event.wait_and_throw();
+    }
 
     //
     // Post Processing
@@ -180,7 +211,7 @@ int run_sparse_matrix_vector_multiply_example(const sycl::device &dev) {
         good &= check_result(res[row], z[row], nrows, row);
     }
 
-    std::cout << "\n\t\t sparse::gemv example " << (good ? "passed" : "failed") << "\n\tFinished"
+    std::cout << "\n\t\t sparse::spmv example " << (good ? "passed" : "failed") << "\n\tFinished"
               << std::endl;
 
     free_vec(fp_ptr_vec, main_queue);
@@ -210,7 +241,7 @@ void print_example_banner() {
     std::cout << "# and alpha, beta are floating point type precision scalars." << std::endl;
     std::cout << "# " << std::endl;
     std::cout << "# Using apis:" << std::endl;
-    std::cout << "#   sparse::gemv" << std::endl;
+    std::cout << "#   sparse::spmv" << std::endl;
     std::cout << "# " << std::endl;
     std::cout << "# Using single precision (float) data type" << std::endl;
     std::cout << "# " << std::endl;
@@ -234,28 +265,28 @@ int main(int /*argc*/, char ** /*argv*/) {
         sycl::device dev = sycl::device();
 
         if (dev.is_gpu()) {
-            std::cout << "Running Sparse BLAS GEMV USM example on GPU device." << std::endl;
+            std::cout << "Running Sparse BLAS SPMV USM example on GPU device." << std::endl;
             std::cout << "Device name is: " << dev.get_info<sycl::info::device::name>()
                       << std::endl;
         }
         else {
-            std::cout << "Running Sparse BLAS GEMV USM example on CPU device." << std::endl;
+            std::cout << "Running Sparse BLAS SPMV USM example on CPU device." << std::endl;
             std::cout << "Device name is: " << dev.get_info<sycl::info::device::name>()
                       << std::endl;
         }
         std::cout << "Running with single precision real data type:" << std::endl;
 
         run_sparse_matrix_vector_multiply_example<float, std::int32_t>(dev);
-        std::cout << "Sparse BLAS GEMV USM example ran OK." << std::endl;
+        std::cout << "Sparse BLAS SPMV USM example ran OK." << std::endl;
     }
     catch (sycl::exception const &e) {
-        std::cerr << "Caught synchronous SYCL exception during Sparse GEMV:" << std::endl;
+        std::cerr << "Caught synchronous SYCL exception during Sparse SPMV:" << std::endl;
         std::cerr << "\t" << e.what() << std::endl;
         std::cerr << "\tSYCL error code: " << e.code().value() << std::endl;
         return 1;
     }
     catch (std::exception const &e) {
-        std::cerr << "Caught std::exception during Sparse GEMV:" << std::endl;
+        std::cerr << "Caught std::exception during Sparse SPMV:" << std::endl;
         std::cerr << "\t" << e.what() << std::endl;
         return 1;
     }