[oneMKL][Sparse BLAS] Add a new oneapi::mkl::sparse::set_coo_data()…

… API for COO matrices (#515)

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

Also adds a description of COO matrix format.

* [oneMKL][Sparse BLAS] Add clarification about `set_xxx_data` needing to allow multiple calls

* [oneMKL][Sparse BLAS] Reorder CSR matrix arrays in CSR format example

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

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
+.. SPDX-FileCopyrightText: 2019-2024 Intel Corporation
 ..
 .. SPDX-License-Identifier: CC-BY-4.0
 
@@ -7,16 +7,87 @@
 Sparse storage formats
 ======================
 
+There are a variety of matrix storage formats available for
+representing sparse matrices. Two popular formats are the
+coordinate (COO) format, and the compressed sparse row (CSR)
+format.
+
+.. container:: section
+
+    .. _onemkl_sparse_coo:
+
+    .. rubric:: COO
+
+    The COO format is the simplest sparse matrix format,
+    represented by three arrays, *row_ind*, *col_ind*
+    and *val*, and an *index* parameter. Each non-zero
+    element, *i* in the sparse matrix is represented by its
+    row index, column index, and value, that is,
+    *(row_ind[i], col_ind[i], val[i])*. The entries need not
+    be in a sorted order.
+
+    .. container:: tablenoborder
+
+         .. list-table::
+
+            * - nrows
+              - Number of rows in the sparse matrix.
+            * - 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 *row_ind*, *col_ind* and *val* arrays.
+            * - index
+              - Parameter that is used to specify whether the matrix has zero or one-based indexing.
+            * - val
+              - An array of length ``nnz`` that contains the non-zero elements of the sparse matrix
+                not necessarily in any sorted order.
+            * - row_ind
+              - An integer array of length ``nnz``. Contains row indices for non-zero elements
+                stored in the *val* array such that *row_ind[i]* is the row number (using zero-
+                or one-based indexing) of the element of the sparse matrix stored in *val[i]*.
+            * - col_ind
+              - 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]*.
+
+
+A sparse matrix can be represented in a COO format in a following way (assuming one-based indexing):
+
+.. math::
+   A = \left(\begin{matrix}
+             1 &  0 & 2\\
+             0 & -1 & 4\\
+             3 &  0 & 0\\
+             \end{matrix}\right)
+
+
++------------+------------------------------------------------------------+
+| nrows      | 3                                                          |
++------------+------------------------------------------------------------+
+| ncols      | 3                                                          |
++------------+------------------------------------------------------------+
+| nnz        | 5                                                          |
++------------+------------------------------------------------------------+
+| index      | 1                                                          |
++------------+------------+-----------+-----------+-----------+-----------+
+| row_ind    | 1          | 1         | 2         | 2         | 3         |
++------------+------------+-----------+-----------+-----------+-----------+
+| col_ind    | 1          | 3         | 2         | 3         | 1         |
++------------+------------+-----------+-----------+-----------+-----------+
+| val        | 1          | 2         | -1        | 4         | 3         |
++------------+------------+-----------+-----------+-----------+-----------+
+
+
 .. container:: section
 
     .. _onemkl_sparse_csr:
 
     .. rubric:: CSR
 
-    There are a variety of matrix storage formats available for
-    representing the sparse matrix. One of the most popular is
-    compressed sparse row (CSR) format, that is represented by
-    three arrays: *row_ptr*, *col_ind* and *val*, and *index*
+    The CSR format is one of the most popular sparse matrix
+    storage formats, represented by three arrays,
+    *row_ptr*, *col_ind* and *val*, and an *index*
     parameter.
 
     .. container:: tablenoborder
@@ -66,11 +137,11 @@ A sparse matrix can be represented in a CSR format in a following way (assuming
 +------------+------------------------------------------------------------+
 | index      | 0                                                          |
 +------------+------------+-----------+-----------+-----------+-----------+
-| val        | 1          | 2         | -1        | 4         | 3         |
+| row_ptr    | 0          | 2         | 4         | 5         |           |
 +------------+------------+-----------+-----------+-----------+-----------+
 | col_ind    | 0          | 2         | 1         | 2         | 0         |
 +------------+------------+-----------+-----------+-----------+-----------+
-| row_ptr    | 0          | 2         | 4         | 5         |           |
+| val        | 1          | 2         | -1        | 4         | 3         |
 +------------+------------+-----------+-----------+-----------+-----------+
 
 

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

@@ -27,7 +27,7 @@ where :math:`\alpha` and :math:`\beta` are scalars, :math:`A` is a sparse matrix
 
 and :math:`\text{op}(A)` is an ``m``-by-``k`` matrix , :math:`\text{op}(B)` is an ``k``-by-``columns`` matrix, and :math:`C` is an ``m``-by-``columns`` matrix.
 
-Dense matrix storage is in either row-major or column-major format. Sparse matrix formats are compressed sparse row (CSR) formats. 
+Dense matrix storage is in either row-major or column-major format. Sparse matrix formats are compressed sparse row (CSR) or coordinate (COO) formats.
 
 
 .. _onemkl_sparse_gemm_buffer:
@@ -87,7 +87,9 @@ gemm (Buffer version)
 
 
     A_handle
-         Handle to object containing sparse matrix, :math:`A`. Created using the oneapi::mkl::sparse::set_csr_data routine.
+         Handle to object containing sparse matrix, :math:`A`. Created using
+         one of ``oneapi::mkl::sparse::set_csr_data`` or
+         ``oneapi::mkl::sparse::set_coo_data`` routines.
 
 
     B
@@ -227,11 +229,13 @@ gemm (USM version)
 
 
     A_handle
-         Handle to object containing sparse matrix, :math:`A`. Created using the oneapi::mkl::sparse::set_csr_data routine.
+         Handle to object containing sparse matrix, :math:`A`. Created using
+         one of ``oneapi::mkl::sparse::set_csr_data`` or
+         ``oneapi::mkl::sparse::set_coo_data`` routines.
 
 
     B 
-         The dense matrix in the sparse-dense matrix product. A device accessible USM object containing an array of size:
+         The input dense matrix :math:`B` in the sparse matrix-dense matrix product. :math:`B` is a device accessible one-dimensional USM object containing an array of size:
 
       .. list-table::
          :header-rows: 1

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

@@ -64,8 +64,8 @@ optimize_gemm (based on Sparse Matrix)
 
     A_handle
        Handle to object containing sparse matrix and other internal
-       data. Created using the
-       oneapi::mkl::sparse::set_csr_data routine.
+       data. Created using one of ``oneapi::mkl::sparse::set_csr_data`` or
+       ``oneapi::mkl::sparse::set_coo_data`` routines.
 
 
     dependencies
@@ -157,8 +157,8 @@ optimize_gemm (based on Both Input Matrices)
 
     handle
        Handle to object containing sparse matrix and other internal
-       data. Created using the
-       oneapi::mkl::sparse::set_csr_data routine.
+       data. Created using one of ``oneapi::mkl::sparse::set_csr_data`` or
+       ``oneapi::mkl::sparse::set_coo_data`` routines.
 
 
     dependencies

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

@@ -65,8 +65,9 @@ gemv (Buffer version)
 
 
     A_handle
-       Handle to object containing sparse matrix, :math:`A`. Created using the
-       oneapi::mkl::sparse::set_csr_data routine.
+       Handle to object containing sparse matrix, :math:`A`. Created using
+       one of ``oneapi::mkl::sparse::set_csr_data`` or
+       ``oneapi::mkl::sparse::set_coo_data`` routines.
 
 
     x
@@ -151,8 +152,9 @@ gemv (USM version)
 
 
     A_handle
-       Handle to object containing sparse matrix, :math:`A`. Created using the
-       oneapi::mkl::sparse::set_csr_data routine.
+       Handle to object containing sparse matrix, :math:`A`. Created using
+       one of ``oneapi::mkl::sparse::set_csr_data`` or
+       ``oneapi::mkl::sparse::set_coo_data`` routines.
 
 
     x

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

@@ -74,8 +74,9 @@ gemvdot (Buffer version)
 
 
     A_handle
-       Handle to object containing sparse matrix :math:`A`. Created using the
-       oneapi::mkl::sparse::set_csr_data routine.
+       Handle to object containing sparse matrix, :math:`A`. Created using
+       one of ``oneapi::mkl::sparse::set_csr_data`` or
+       ``oneapi::mkl::sparse::set_coo_data`` routines.
 
 
     x
@@ -164,8 +165,9 @@ gemvdot (USM version)
 
 
     A_handle
-       Handle to object containing sparse matrix :math:`A`. Created using the
-       oneapi::mkl::sparse::set_csr_data routine.
+       Handle to object containing sparse matrix, :math:`A`. Created using
+       one of ``oneapi::mkl::sparse::set_csr_data`` or
+       ``oneapi::mkl::sparse::set_coo_data`` routines.
 
 
     x

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

@@ -46,8 +46,8 @@ the handle.
 
     handle
        Handle to object containing sparse matrix and other internal
-       data. Created using the
-       oneapi::mkl::sparse::set_csr_data routine.
+       data. Created using one of ``oneapi::mkl::sparse::set_csr_data`` or
+       ``oneapi::mkl::sparse::set_coo_data`` routines.
 
 
     dependencies