[oneMKL][SpBLAS] Add nnz arg to oneapi::mkl::sparse::set_csr_data() API (#512)

* [oneMKL][SpBLAS] Add `nnz` arg to `oneapi::mkl::sparse::set_csr_data()` API

* [oneMKL][SpBLAS] Add `const`-ness to `nrows`, `ncols`, `nnz` args in `set_csr_data`

Author: gajanan-choudhary

source/elements/oneMKL/source/domains/spblas/format-descriptions.rst

@@ -23,24 +23,28 @@ Sparse storage formats
 
          .. list-table::
 
-            * - num_rows
+            * - nrows
               - Number of rows in the sparse matrix.
-            * - num_cols
+            * - ncols
               - Number of columns in the sparse matrix.
+            * - nnz
+              - Number of non-zero entries in the sparse matrix (which may include explicit zeros).
+                This is also the length of the *col_ind* and *val* arrays.
             * - index
               - Parameter that is used to specify whether the matrix has zero or one-based indexing.
             * - val
-              - An array that contains the non-zero elements of the sparse matrix stored row by row.
+              - An array of length ``nnz`` that contains the non-zero elements of the sparse matrix
+                stored row by row.
             * - col_ind
-              - An integer array of column indices for non-zero elements stored in the *val* array,
-                such that *col_ind[i]* is the column number (using zero- or one-based indexing) of the
-                element of the sparse matrix stored in *val[i]*.
+              - An integer array of length ``nnz``. Contains column indices for non-zero elements
+                stored in the *val* array such that *col_ind[i]* is the column number (using zero-
+                or one-based indexing) of the element of the sparse matrix stored in *val[i]*.
             * - row_ptr
-              - An integer array of size equal to ``num_rows + 1``.  Element j of this integer array
+              - An integer array of size equal to ``nrows + 1``.  Element j of this integer array
                 gives the position of the element in the *val* array that is first non-zero element in a
                 row j of A. Note that this position is equal to *row_ptr[j] - index*. Last element of
-                the *row_ptr* array (*row_ptr[num_rows]*) stores the sum of,
-                number of nonzero elements and *index*(number of nonzero elements + *index*).
+                the *row_ptr* array (*row_ptr[nrows]*) stores the sum of,
+                number of nonzero elements and *index* (*nnz* + *index*).
 
 
 A sparse matrix can be represented in a CSR format in a following way (assuming zero-based indexing):
@@ -54,9 +58,11 @@ A sparse matrix can be represented in a CSR format in a following way (assuming
 
 
 +------------+------------------------------------------------------------+
-| num_rows   | 3                                                          |
+| nrows      | 3                                                          |
 +------------+------------------------------------------------------------+
-| num_cols   | 3                                                          |
+| ncols      | 3                                                          |
++------------+------------------------------------------------------------+
+| nnz        | 5                                                          |
 +------------+------------------------------------------------------------+
 | index      | 0                                                          |
 +------------+------------+-----------+-----------+-----------+-----------+
@@ -74,4 +80,4 @@ A sparse matrix can be represented in a CSR format in a following way (assuming
    .. container:: parentlink
 
 
-      **Parent topic:** :ref:`onemkl_spblas`
+      **Parent topic:** :ref:`onemkl_spblas`

source/elements/oneMKL/source/domains/spblas/setcsrstructure.rst

@@ -15,7 +15,7 @@ Takes a matrix handle and the input CSR matrix arrays and fills the internal CSR
 Refer to :ref:`onemkl_sparse_supported_types` for a
 list of supported ``<fp>`` and ``<intType>``.
 The mkl::sparse::set_csr_data routine takes a matrix handle
-for a sparse matrix of dimensions *num_rows* -by- *num_cols*
+for a sparse matrix of dimensions *nrows* -by- *ncols*
 represented in the CSR format, and fills the internal
 CSR data structure.
 
@@ -33,8 +33,9 @@ set_csr_data (Buffer version)
 
       void set_csr_data (sycl::queue                           &queue,
                          oneapi::mkl::sparse::matrix_handle_t  handle,
-                         intType                               num_rows,
-                         intType                               num_cols,
+                         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,
@@ -54,14 +55,19 @@ set_csr_data (Buffer version)
          data for subsequent DPC++ Sparse BLAS operations.
 
 
-    num_rows
+    nrows
          Number of rows of the input matrix .
 
 
-    num_cols
+    ncols
          Number of columns of the input matrix .
 
 
+    nnz
+         Number of non-zero entries in the matrix (which may include explicit
+         zeros).
+
+
     index
          Indicates how input arrays are indexed.
          The possible options are
@@ -70,21 +76,22 @@ set_csr_data (Buffer version)
 
     row_ptr
          SYCL memory object containing an array of length
-         ``num_rows+1``. Refer to :ref:`onemkl_sparse_csr` format
+         ``nrows+1``. Refer to :ref:`onemkl_sparse_csr` format
          for detailed description of ``row_ptr``.
 
 
     col_ind
-         SYCL memory object which stores an array containing the
-         column indices in ``index``-based numbering.
+         SYCL memory object which stores an array of length ``nnz``
+         containing the column indices in ``index``-based numbering.
          Refer to :ref:`onemkl_sparse_csr` format for detailed
          description of ``col_ind``.
 
 
     val
-         SYCL memory object which stores an array containing
-         non-zero elements of the input matrix. Refer to
-         :ref:`onemkl_sparse_csr` format for detailed description of ``val``.
+         SYCL memory object which stores an array of length ``nnz``
+         containing non-zero elements (and possibly explicit zeros) of the
+         input matrix. Refer to :ref:`onemkl_sparse_csr` format for detailed
+         description of ``val``.
 
 
 .. container:: section
@@ -128,8 +135,9 @@ set_csr_data (USM version)
 
       sycl::event set_csr_data (sycl::queue                           &queue,
                                 oneapi::mkl::sparse::matrix_handle_t  handle,
-                                intType                               num_rows,
-                                intType                               num_cols,
+                                const intType                         nrows,
+                                const intType                         ncols,
+                                const intType                         nnz,
                                 oneapi::mkl::index_base               index,
                                 intType                               *row_ptr,
                                 intType                               *col_ind,
@@ -150,12 +158,17 @@ set_csr_data (USM version)
          data for subsequent DPC++ Sparse BLAS operations.
 
 
-    num_rows
-         Number of rows of the input matrix .
+    nrows
+         Number of rows of the input matrix.
 
 
-    num_cols
-         Number of columns of the input matrix .
+    ncols
+         Number of columns of the input matrix.
+
+
+    nnz
+         Number of non-zero entries in the matrix (which may include explicit
+         zeros).
 
 
     index
@@ -166,21 +179,22 @@ set_csr_data (USM version)
 
     row_ptr
          USM object containing an array of length
-         ``num_rows+1``. Refer to :ref:`onemkl_sparse_csr` format for
+         ``nrows+1``. Refer to :ref:`onemkl_sparse_csr` format for
          detailed description of ``row_ptr``
 
 
     col_ind
-         USM object which stores an array containing the
-         column indices in ``index``-based numbering.
+         USM object which stores an array of length ``nnz``
+         containing the column indices in ``index``-based numbering.
          Refer to :ref:`onemkl_sparse_csr` format for detailed
          description of ``col_ind``
 
 
     val
-         USM object which stores an array containing
-         non-zero elements of the input matrix. Refer to
-         :ref:`onemkl_sparse_csr` format for detailed description of ``val``
+         USM object which stores an array of length ``nnz``
+         containing non-zero elements (and possibly explicit zeros) of the
+         input matrix. Refer to :ref:`onemkl_sparse_csr` format for
+         detailed description of ``val``
 
     dependencies
          A vector of type const std::vector<sycl::event> & containing the list of events