[oneMKL][spblas] Restrict features not supported by any backends (#542)

* Require same types for all handles
* Clarify when should the data be available on device
* Clarify the behavior of calling functions in the wrong order
* Clarify when exceptions are thrown

Author: Rbiessy

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

@@ -52,12 +52,12 @@ set_coo_matrix_data (Buffer version)
    .. rubric:: Template parameters
 
    dataType
-      See :ref:`supported template types<onemkl_sparse_supported_types>`. Can be
-      a different type than what was used when creating the ``matrix_handle_t``.
+      See :ref:`supported template types<onemkl_sparse_supported_types>`. Must
+      be the same type as was used when creating the ``matrix_handle_t``.
 
    indexType
-      See :ref:`supported template types<onemkl_sparse_supported_types>`. Can be
-      a different type than what was used when creating the ``matrix_handle_t``.
+      See :ref:`supported template types<onemkl_sparse_supported_types>`. Must
+      be the same type as was used when creating the ``matrix_handle_t``.
 
 .. container:: section
 
@@ -150,12 +150,12 @@ set_coo_matrix_data (USM version)
    .. rubric:: Template parameters
 
    dataType
-      See :ref:`supported template types<onemkl_sparse_supported_types>`. Can be
-      a different type than what was used when creating the ``matrix_handle_t``.
+      See :ref:`supported template types<onemkl_sparse_supported_types>`. Must
+      be the same type as was used when creating the ``matrix_handle_t``.
 
    indexType
-      See :ref:`supported template types<onemkl_sparse_supported_types>`. Can be
-      a different type than what was used when creating the ``matrix_handle_t``.
+      See :ref:`supported template types<onemkl_sparse_supported_types>`. Must
+      be the same type as was used when creating the ``matrix_handle_t``.
 
 .. container:: section
 

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

@@ -52,12 +52,12 @@ set_csr_matrix_data (Buffer version)
    .. rubric:: Template parameters
 
    dataType
-      See :ref:`supported template types<onemkl_sparse_supported_types>`. Can be
-      a different type than what was used when creating the ``matrix_handle_t``.
+      See :ref:`supported template types<onemkl_sparse_supported_types>`. Must
+      be the same type as was used when creating the ``matrix_handle_t``.
 
    indexType
-      See :ref:`supported template types<onemkl_sparse_supported_types>`. Can be
-      a different type than what was used when creating the ``matrix_handle_t``.
+      See :ref:`supported template types<onemkl_sparse_supported_types>`. Must
+      be the same type as was used when creating the ``matrix_handle_t``.
 
 .. container:: section
 
@@ -149,12 +149,12 @@ set_csr_matrix_data (USM version)
    .. rubric:: Template parameters
 
    dataType
-      See :ref:`supported template types<onemkl_sparse_supported_types>`. Can be
-      a different type than what was used when creating the ``matrix_handle_t``.
+      See :ref:`supported template types<onemkl_sparse_supported_types>`. Must
+      be the same type as was used when creating the ``matrix_handle_t``.
 
    indexType
-      See :ref:`supported template types<onemkl_sparse_supported_types>`. Can be
-      a different type than what was used when creating the ``matrix_handle_t``.
+      See :ref:`supported template types<onemkl_sparse_supported_types>`. Must
+      be the same type as was used when creating the ``matrix_handle_t``.
 
 .. container:: section
 

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

@@ -50,9 +50,8 @@ set_dense_matrix_data (Buffer version)
    .. rubric:: Template parameters
 
    dataType
-      See :ref:`supported template types<onemkl_sparse_supported_types>`. Can be
-      a different type than what was used when creating the
-      ``dense_matrix_handle_t``.
+      See :ref:`supported template types<onemkl_sparse_supported_types>`. Must
+      be the same type as was used when creating the ``dense_matrix_handle_t``.
 
 .. container:: section
 
@@ -123,9 +122,8 @@ set_dense_matrix_data (USM version)
    .. rubric:: Template parameters
 
    dataType
-      See :ref:`supported template types<onemkl_sparse_supported_types>`. Can be
-      a different type than what was used when creating the
-      ``dense_matrix_handle_t``.
+      See :ref:`supported template types<onemkl_sparse_supported_types>`. Must
+      be the same type as was used when creating the ``dense_matrix_handle_t``.
 
 .. container:: section
 

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

@@ -47,9 +47,8 @@ set_dense_vector_data (Buffer version)
    .. rubric:: Template parameters
 
    dataType
-      See :ref:`supported template types<onemkl_sparse_supported_types>`. Can be
-      a different type than what was used when creating the
-      ``dense_vector_handle_t``.
+      See :ref:`supported template types<onemkl_sparse_supported_types>`. Must
+      be the same type as was used when creating the ``dense_vector_handle_t``.
 
 .. container:: section
 
@@ -105,9 +104,8 @@ set_dense_vector_data (USM version)
    .. rubric:: Template parameters
 
    dataType
-      See :ref:`supported template types<onemkl_sparse_supported_types>`. Can be
-      a different type than what was used when creating the
-      ``dense_vector_handle_t``.
+      See :ref:`supported template types<onemkl_sparse_supported_types>`. Must
+      be the same type as was used when creating the ``dense_vector_handle_t``.
 
 .. container:: section
 

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

@@ -84,10 +84,8 @@ matrix_view
    See :ref:`onemkl_sparse_matrix_descriptor`, :ref:`onemkl_enum_uplo` and
    :ref:`onemkl_enum_diag` for a description of the members.
 
-   The ``uplo_view`` member is ignored if ``type_view`` is ``general`` or
-   ``diagonal``.
-
-   The ``diag_view`` member is ignored if ``type_view`` is ``general``.
+   Each operation documents which combination of ``type_view``, ``uplo_view``
+   and ``diag_view`` are valid.
 
    .. rubric:: Syntax
 
@@ -124,7 +122,4 @@ matrix_view
       the other members are initialized to the same value as the default
       constructor.
 
-      If the ``matrix_desc`` is ``diagonal``, ``diag_view`` is initialized to
-      ``diag::unit``.
-
 **Parent topic:** :ref:`onemkl_spblas`

source/elements/oneMKL/source/domains/spblas/operations/spmm.rst

@@ -273,9 +273,19 @@ spmm
      before ``spmm`` with the same arguments. ``spmm`` can then be called
      multiple times. Calling ``spmm_optimize`` on the same descriptor can reset
      some of the descriptor's data such as the ``workspace``.
+   - In the general case, not calling the functions in the order specified above
+     is undefined behavior. Not calling ``spmm_buffer_size`` or
+     ``spmm_optimize`` at least once with a given descriptor will throw an
+     :ref:`oneapi::mkl::uninitialized<onemkl_exception_uninitialized>`
+     exception. Calling ``spmm`` with arguments not matching ``spmm_optimize``
+     will throw an
+     :ref:`oneapi::mkl::invalid_argument<onemkl_exception_invalid_argument>`
+     exception, unless stated otherwise.
    - The data of the dense handles ``B_handle`` and ``C_handle`` and the scalars
      ``alpha`` and ``beta`` can be reset before each call to ``spmm``. Changing
      the data of the sparse handle ``A_handle`` is undefined behavior.
+   - The data must be available on the device when calling ``spmm_optimize`` by
+     using event dependencies if needed.
    - ``spmm_optimize`` and ``spmm`` are asynchronous.
    - The algorithm defaults to ``spmm_alg::default_alg`` if a backend does not
      support the provided algorithm.
@@ -305,7 +315,9 @@ spmm
 
    A_view
       Specifies which part of the handle should be read as described by
-      :ref:`onemkl_sparse_matrix_view`.
+      :ref:`onemkl_sparse_matrix_view`. The ``type_view`` field must be
+      ``matrix_descr::general`` and the ``uplo_view`` and ``diag_view`` fields
+      are ignored.
 
    A_handle
       Sparse matrix handle object representing :math:`A`.

source/elements/oneMKL/source/domains/spblas/operations/spmv.rst

@@ -267,9 +267,19 @@ spmv
      before ``spmv`` with the same arguments. ``spmv`` can then be called
      multiple times. Calling ``spmv_optimize`` on the same descriptor can reset
      some of the descriptor's data such as the ``workspace``.
+   - In the general case, not calling the functions in the order specified above
+     is undefined behavior. Not calling ``spmv_buffer_size`` or
+     ``spmv_optimize`` at least once with a given descriptor will throw an
+     :ref:`oneapi::mkl::uninitialized<onemkl_exception_uninitialized>`
+     exception. Calling ``spmv`` with arguments not matching ``spmv_optimize``
+     will throw an
+     :ref:`oneapi::mkl::invalid_argument<onemkl_exception_invalid_argument>`
+     exception, unless stated otherwise.
    - The data of the dense handles ``x_handle`` and ``y_handle`` and the scalars
      ``alpha`` and ``beta`` can be reset before each call to ``spmv``. Changing
      the data of the sparse handle ``A_handle`` is undefined behavior.
+   - The data must be available on the device when calling ``spmv_optimize`` by
+     using event dependencies if needed.
    - ``spmv_optimize`` and ``spmv`` are asynchronous.
    - The algorithm defaults to ``spmv_alg::default_alg`` if a backend does not
      support the provided algorithm.
@@ -295,7 +305,9 @@ spmv
 
    A_view
       Specifies which part of the handle should be read as described by
-      :ref:`onemkl_sparse_matrix_view`.
+      :ref:`onemkl_sparse_matrix_view`. The ``type_view`` field cannot be
+      ``matrix_descr::diagonal``. The ``diag_view`` field can be ``diag::unit``
+      if and only if ``type_view`` is ``matrix_descr::triangular``.
 
    A_handle
       Sparse matrix handle object representing :math:`A`.

source/elements/oneMKL/source/domains/spblas/operations/spsv.rst

@@ -258,9 +258,19 @@ spsv
      before ``spsv`` with the same arguments. ``spsv`` can then be called
      multiple times. Calling ``spsv_optimize`` on the same descriptor can reset
      some of the descriptor's data such as the ``workspace``.
+   - In the general case, not calling the functions in the order specified above
+     is undefined behavior. Not calling ``spsv_buffer_size`` or
+     ``spsv_optimize`` at least once with a given descriptor will throw an
+     :ref:`oneapi::mkl::uninitialized<onemkl_exception_uninitialized>`
+     exception. Calling ``spsv`` with arguments not matching ``spsv_optimize``
+     will throw an
+     :ref:`oneapi::mkl::invalid_argument<onemkl_exception_invalid_argument>`
+     exception, unless stated otherwise.
    - The data of the dense handle ``x_handle`` and scalar ``alpha`` can be reset
      before each call to ``spsv``. Changing the data of the sparse handle
      ``A_handle`` is undefined behavior.
+   - The data must be available on the device when calling ``spsv_optimize`` by
+     using event dependencies if needed.
    - ``spsv_optimize`` and ``spsv`` are asynchronous.
    - The algorithm defaults to ``spsv_alg::default_alg`` if a backend does not
      support the provided algorithm.
@@ -283,8 +293,9 @@ spsv
 
    A_view
       Specifies which part of the handle should be read as described by
-      :ref:`onemkl_sparse_matrix_view`. ``A_view.type_view`` must be
-      ``matrix_descr::triangular`` or ``matrix_descr::diagonal``.
+      :ref:`onemkl_sparse_matrix_view`. The ``type_view`` field must be
+      ``matrix_descr::triangular``. The ``diag_view`` field can be
+      ``diag::nonunit`` or ``diag::unit``.
 
    A_handle
       Sparse matrix handle object representing :math:`A`.