[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

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`.