[oneMKL][Sparse BLAS] Add a new `oneapi::mkl::sparse::set_coo_data()` API for COO matrices

[gajanan-choudhary]

Coordinate (COO) matrix format: oneapi::mkl::sparse::set_coo_data() API

• We propose adding a new oneapi::mkl::sparse::set_coo_data() API to the oneMKL Specification in the Sparse BLAS domain for creation of matrices in the coordinate (COO) format.
• The API looks very similar to the existing oneapi::mkl::sparse::set_csr_data() API in the Spec for the compressed sparse row (CSR) matrix format.
• Proposed oneapi::mkl::sparse::set_coo_data() API

  namespace oneapi::mkl::sparse {
      /* sycl::buffer API */
      void set_coo_data(sycl::queue                           &queue,
                        oneapi::mkl::sparse::matrix_handle_t  handle,
                        const intType                         nrows,
                        const intType                         ncols,
                        const intType                         nnz,
                        oneapi::mkl::index_base               index,
                        sycl::buffer<intType, 1>              &row_ind,
                        sycl::buffer<intType, 1>              &col_ind,
                        sycl::buffer<fp, 1>                   &val);
      /* USM API */
      sycl::event set_coo_data(sycl::queue                           &queue,
                               oneapi::mkl::sparse::matrix_handle_t  handle,
                               const intType                         nrows,
                               const intType                         ncols,
                               const intType                         nnz,
                               oneapi::mkl::index_base               index,
                               intType                               *row_ind,
                               intType                               *col_ind,
                               fp                                    *val,
                               const std::vector<sycl::event>        &dependencies = {});
  }

• Existingoneapi::mkl::sparse::set_csr_data() API

  namespace oneapi::mkl::sparse {
      /* sycl::buffer API */
      void set_csr_data(sycl::queue                           &queue,
                        oneapi::mkl::sparse::matrix_handle_t  handle,
                        const intType                         nrows,
                        const intType                         ncols,
                        const intType                         nnz,
                        oneapi::mkl::index_base               index,
                        sycl::buffer<intType, 1>              &row_ptr,
                        sycl::buffer<intType, 1>              &col_ind,
                        sycl::buffer<fp, 1>                   &val);
      /* USM API */
      sycl::event set_csr_data(sycl::queue                           &queue,
                               oneapi::mkl::sparse::matrix_handle_t  handle,
                               const intType                         nrows,
                               const intType                         ncols,
                               const intType                         nnz,
                               oneapi::mkl::index_base               index,
                               intType                               *row_ptr,
                               intType                               *col_ind,
                               fp                                    *val,
                               const std::vector<sycl::event>        &dependencies = {});
  }

Changes

• A new file, setcoostructure.rst is being added containing details of the new oneapi::mkl::sparse::set_coo_data() API.
• In almost all the existing sparse BLAS APIs, the description of the sparse matrix handle mentioned the CSR format; that is now being changed to reflect both CSR and COO formats.
• format-descriptions.rst is modified to also contain a description and example of the COO format. The COO format description is kept at the top since it is the simplest one to understand.
• [Update:] After a PR review, I've added in text for clarifying that set_csr_data and set_coo_data APIs need to allow multiple calls and 0/nullptr args in some cases and that it is implementation-defined for now.
• Remaining changes, if any, are very minor.

Tests

• Built the HTML pages locally and checked each Sparse BLAS page for rendering quality, which looks normal.
• Tested COO format related links in all webpages.
• As a sanity check, there are currently exactly 46 lines each with (case-insensitive) occurrences of the words, "CSR" and "COO", in the sparse BLAS domain files.