diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst index a6dba2712d..a12311d319 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_coo_matrix_data.rst +++ b/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`. Can be - a different type than what was used when creating the ``matrix_handle_t``. + See :ref:`supported template types`. Must + be the same type as was used when creating the ``matrix_handle_t``. indexType - See :ref:`supported template types`. Can be - a different type than what was used when creating the ``matrix_handle_t``. + See :ref:`supported template 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`. Can be - a different type than what was used when creating the ``matrix_handle_t``. + See :ref:`supported template types`. Must + be the same type as was used when creating the ``matrix_handle_t``. indexType - See :ref:`supported template types`. Can be - a different type than what was used when creating the ``matrix_handle_t``. + See :ref:`supported template types`. Must + be the same type as was used when creating the ``matrix_handle_t``. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst index 3a28785d0f..8b95277559 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_csr_matrix_data.rst +++ b/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`. Can be - a different type than what was used when creating the ``matrix_handle_t``. + See :ref:`supported template types`. Must + be the same type as was used when creating the ``matrix_handle_t``. indexType - See :ref:`supported template types`. Can be - a different type than what was used when creating the ``matrix_handle_t``. + See :ref:`supported template 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`. Can be - a different type than what was used when creating the ``matrix_handle_t``. + See :ref:`supported template types`. Must + be the same type as was used when creating the ``matrix_handle_t``. indexType - See :ref:`supported template types`. Can be - a different type than what was used when creating the ``matrix_handle_t``. + See :ref:`supported template types`. Must + be the same type as was used when creating the ``matrix_handle_t``. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst index c75a80e742..0eab72f6b8 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_matrix_data.rst +++ b/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`. Can be - a different type than what was used when creating the - ``dense_matrix_handle_t``. + See :ref:`supported template 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`. Can be - a different type than what was used when creating the - ``dense_matrix_handle_t``. + See :ref:`supported template types`. Must + be the same type as was used when creating the ``dense_matrix_handle_t``. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst index 844e73bf70..c882f07079 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_dense_vector_data.rst +++ b/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`. Can be - a different type than what was used when creating the - ``dense_vector_handle_t``. + See :ref:`supported template 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`. Can be - a different type than what was used when creating the - ``dense_vector_handle_t``. + See :ref:`supported template types`. Must + be the same type as was used when creating the ``dense_vector_handle_t``. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/matrix_view.rst b/source/elements/oneMKL/source/domains/spblas/matrix_view.rst index c69069c58e..0c0bb6535e 100644 --- a/source/elements/oneMKL/source/domains/spblas/matrix_view.rst +++ b/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` diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index 5bfb5d5151..fc9d6bfa85 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/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` + exception. Calling ``spmm`` with arguments not matching ``spmm_optimize`` + will throw an + :ref:`oneapi::mkl::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. @@ -302,7 +312,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`. diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index 5287b3a852..991f363e80 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/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` + exception. Calling ``spmv`` with arguments not matching ``spmv_optimize`` + will throw an + :ref:`oneapi::mkl::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. @@ -292,7 +302,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`. diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index 1ddb9bf110..61201c3301 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/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` + exception. Calling ``spsv`` with arguments not matching ``spsv_optimize`` + will throw an + :ref:`oneapi::mkl::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`.