[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