[oneMKL][spblas] Update Sparse BLAS APIs to v2.0 (#522)

Sparse BLAS version 2.0. This commit completely breaks compatibility with previous Sparse BLAS 1.x APIs and so will trigger a major version increment for oneMKL Sparse BLAS to version 2.0.

Most notable changes:
* Introduce handle opaque types that store the USM pointer or SYCL buffer for dense matrix/vectors in Sparse BLAS APIs.
* Introduce matrix properties and views.
* Merge gemv, symv and trmv to spmv operation; gemm is renamed to spmm; trsv is renamed to spsv.
* Drop support for gemvdot as there didn't seem to be enough use-cases nor support in other backends (may be added back in future)
* Add support for external workspace provided by the user which size is queried by *_buffer_size functions.

source/elements/oneMKL/source/domains/sparse_linear_algebra.inc.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation
+.. SPDX-FileCopyrightText: 2024 Intel Corporation
 ..
 .. SPDX-License-Identifier: CC-BY-4.0
 
@@ -9,29 +9,24 @@ Sparse Linear Algebra
 
 .. container::
 
-
-   The oneAPI Math Kernel Library provides a Data Parallel C++ interface
-   to some of the Sparse Linear Algebra routines.
-
-   :ref:`onemkl_spblas` provides basic operations on sparse vectors and matrices, and
-   separates them into two stages: analysis
-   (also called inspector stage or optimize stage) and execution. For a given matrix,
-   the analysis would typically be called one time and the execution may be called
-   multiple times. During the analysis stage, the API inspects the matrix properties
-   including size, sparsity pattern and available parallelism and can apply matrix
-   format or structure changes to enable a more optimized algorithm.
-   In the execution stage, multiple routine calls can take advantage of the analysis
-   stage data in order to improve performance.
-
-
-   In order to save information in between calls to Sparse BLAS computation routines,
-   the :ref:`onemkl_sparse_matrix_handle_t` type is introduced, that is essentially
-   an opaque pointer, used to store data related to initial sparse matrix
-   and data obtained during analysis stage.
-
+   The oneAPI Math Kernel Library provides a C++ interface to a set of Sparse
+   Linear Algebra routines using SYCL.
+
+   :ref:`onemkl_spblas` provides basic operations on sparse vectors and
+   matrices. Most operations are split into three stages: query of the external
+   workspace size, optimization stage and execution. For a given configuration,
+   the first two stages would typically be called once for a set of input
+   arguments and the execution stage may be called multiple times. During the
+   optimization stage, the API may inspect the matrix properties including size,
+   sparsity pattern and available parallelism, and may apply matrix format or
+   structure changes to enable a more optimized algorithm. User-provided matrix
+   data remain unmodified if such optimizations are made. In the execution
+   stage, multiple routine calls can take advantage of the optimization stage
+   data in order to improve performance. Each operation has a descriptor type
+   that is used to carry information across the different stages.
 
 .. toctree::
-    :hidden:
+   :hidden:
 
-    spblas/spblas.rst
+   spblas/spblas.rst
 

source/elements/oneMKL/source/domains/spblas/data_types/data_handles.rst

@@ -0,0 +1,122 @@
+.. SPDX-FileCopyrightText: 2024 Intel Corporation
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+.. _onemkl_sparse_data_handles:
+
+Data handles
+============
+
+.. _onemkl_sparse_dense_vector_handle:
+
+Dense vector handle
+-------------------
+
+.. rubric:: Definition
+
+.. code-block:: cpp
+
+   namespace oneapi::mkl::sparse {
+
+       struct dense_vector_handle;
+       using dense_vector_handle_t = dense_vector_handle*;
+
+   }
+
+.. container:: section
+
+   .. rubric:: Description
+
+   Defines ``dense_vector_handle_t`` as an opaque pointer to the incomplete type
+   ``dense_vector_handle``. Each backend may provide a different
+   implementation of the type ``dense_vector_handle``.
+
+   See related functions:
+
+   - :ref:`onemkl_sparse_init_dense_vector`
+   - :ref:`onemkl_sparse_set_dense_vector_data`
+   - :ref:`onemkl_sparse_release_dense_vector`
+
+.. _onemkl_sparse_dense_matrix_handle:
+
+Dense matrix handle
+-------------------
+
+.. rubric:: Definition
+
+.. code-block:: cpp
+
+   namespace oneapi::mkl::sparse {
+
+       struct dense_matrix_handle;
+       using dense_matrix_handle_t = dense_matrix_handle*;
+
+   }
+
+.. container:: section
+
+   .. rubric:: Description
+
+   Defines ``dense_matrix_handle_t`` as an opaque pointer to the incomplete type
+   ``dense_matrix_handle``. Each backend may provide a different
+   implementation of the type ``dense_matrix_handle``.
+
+   See related functions:
+
+   - :ref:`onemkl_sparse_init_dense_matrix`
+   - :ref:`onemkl_sparse_set_dense_matrix_data`
+   - :ref:`onemkl_sparse_release_dense_matrix`
+
+.. _onemkl_sparse_matrix_handle:
+
+Sparse matrix handle
+--------------------
+
+.. rubric:: Definition
+
+.. code-block:: cpp
+
+   namespace oneapi::mkl::sparse {
+
+       struct matrix_handle;
+       using matrix_handle_t = matrix_handle*;
+
+   }
+
+.. container:: section
+
+   .. rubric:: Description
+
+   Defines ``matrix_handle_t`` as an opaque pointer to the incomplete type
+   ``matrix_handle``. Each backend may provide a different
+   implementation of the type ``matrix_handle``.
+
+   See related functions:
+
+   - :ref:`onemkl_sparse_init_coo_matrix`
+   - :ref:`onemkl_sparse_init_csr_matrix`
+   - :ref:`onemkl_sparse_set_coo_matrix_data`
+   - :ref:`onemkl_sparse_set_csr_matrix_data`
+   - :ref:`onemkl_sparse_set_matrix_property`
+   - :ref:`onemkl_sparse_release_sparse_matrix`
+
+   See a description of the supported :ref:`sparse formats<onemkl_sparse_format_descriptions>`.
+
+.. toctree::
+   :hidden:
+
+   init_dense_vector
+   init_dense_matrix
+   init_coo_matrix
+   init_csr_matrix
+   release_dense_vector
+   release_dense_matrix
+   release_sparse_matrix
+   set_dense_vector_data
+   set_dense_matrix_data
+   set_coo_matrix_data
+   set_csr_matrix_data
+   set_matrix_property
+   format-descriptions
+
+**Parent topic:** :ref:`onemkl_spblas`

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

@@ -0,0 +1,155 @@
+.. SPDX-FileCopyrightText: 2024 Intel Corporation
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+.. _onemkl_sparse_format_descriptions:
+
+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.
+
+In this specification, "non-zero" elements or "non-zero" entries refer to
+explicitly defined elements or entries which may take any value supported by the
+the `:ref:data type<onemkl_sparse_supported_types>`. Undefined elements or
+entries are implicitly zeros.
+
+.. 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. The
+   ``i``-th defined element 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, though performance of
+   Sparse BLAS operations may be improved if they are sorted in some logical
+   way, for instance by row index and then column index subordinate to each row
+   set.
+
+   .. container:: tablenoborder
+
+      .. list-table::
+
+         * - num_rows
+           - Number of rows in the sparse matrix.
+         * - num_cols
+           - Number of columns in the sparse matrix.
+         * - nnz
+           - Number of non-zero entries in the sparse matrix. 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)
+
++------------+------------------------------------------------------------+
+| num_rows   | 3                                                          |
++------------+------------------------------------------------------------+
+| num_cols   | 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
+
+   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
+
+      .. list-table::
+
+         * - num_rows
+           - Number of rows in the sparse matrix.
+         * - num_cols
+           - Number of columns in the sparse matrix.
+         * - nnz
+           - Number of non-zero entries in the sparse matrix. 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 of length ``nnz`` that contains the non-zero elements of
+             the sparse matrix stored row by row.
+         * - 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]``.
+         * - row_ptr
+           - An integer array of size equal to ``num_rows + 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 non-zero elements and ``index``
+             (``nnz + index``).
+
+A sparse matrix can be represented in a CSR format in a following way (assuming
+zero-based indexing):
+
+.. math::
+   A = \left(\begin{matrix}
+             1 &  0 & 2\\
+             0 & -1 & 4\\
+             3 &  0 & 0\\
+             \end{matrix}\right)
+
++------------+------------------------------------------------------------+
+| num_rows   | 3                                                          |
++------------+------------------------------------------------------------+
+| num_cols   | 3                                                          |
++------------+------------------------------------------------------------+
+| nnz        | 5                                                          |
++------------+------------------------------------------------------------+
+| index      | 0                                                          |
++------------+------------+-----------+-----------+-----------+-----------+
+| row_ptr    | 0          | 2         | 4         | 5         |           |
++------------+------------+-----------+-----------+-----------+-----------+
+| col_ind    | 0          | 2         | 1         | 2         | 0         |
++------------+------------+-----------+-----------+-----------+-----------+
+| val        | 1          | 2         | -1        | 4         | 3         |
++------------+------------+-----------+-----------+-----------+-----------+
+
+**Parent topic:** :ref:`onemkl_sparse_data_handles`