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

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