diff --git a/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst index 0bbd44854f..4e2014b7f3 100644 --- a/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst +++ b/source/elements/oneMKL/source/domains/spblas/data_types/set_matrix_property.rst @@ -19,6 +19,7 @@ Matrix properties enum class matrix_property { symmetric, sorted, + sorted_by_rows, }; } @@ -28,23 +29,51 @@ Matrix properties holds all the given properties. A property can be set as a hint for backends to optimize some operations. Multiple properties can be set to the same handle. +symmetric +^^^^^^^^^ + +Guarantees that the user-provided matrix data are symmetric, meaning the matrix +is square, the user data contain both lower and upper triangular regions, and +that its transpose is equal to itself. + +sorted +^^^^^^ + +Guarantees that the user-provided matrix data is fully sorted. The table below +details the property for each matrix format: + + .. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Matrix format + - Description + * - CSR + - Guarantees that the column indices are sorted in ascending order for + a given row. + * - COO + - Guarantees that the indices are sorted by rows then by columns within + rows in ascending order. + +sorted_by_rows +^^^^^^^^^^^^^^ + +Guarantees that the user-provided matrix data is partially sorted. The table below +details the property for each matrix format: + .. list-table:: :header-rows: 1 :widths: 20 80 - * - Value + * - Matrix format - Description - * - ``symmetric`` - - Guarantees that the user-provided matrix data are symmetric, meaning - the matrix is square, the user data contain both lower and upper - triangular regions, and that its transpose is equal to itself. - * - ``sorted`` - - | Guarantees that the user-provided matrix data has some sorting - property. - | For CSR this guarantees that the column indices are sorted in - ascending order for a given row. - | For COO this guarantees that the indices are sorted by row then by - column in ascending order. + * - CSR + - Setting this property for a matrix using the CSR format will throw a + :ref:`oneapi::mkl::invalid_argument` + exception. + * - COO + - Guarantees that the indices are sorted by rows in ascending order. + The column indices within a row do not need to be sorted. set_matrix_property ------------------- diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst index 93c967547a..08b64595ee 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmm.rst @@ -275,10 +275,10 @@ spmm 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 + ``spmm_optimize`` at least once with a given descriptor will throw a :ref:`oneapi::mkl::uninitialized` exception. Calling ``spmm`` with arguments not matching ``spmm_optimize`` - will throw an + will throw a :ref:`oneapi::mkl::invalid_argument` exception, unless stated otherwise. - The data of the dense handles ``B_handle`` and ``C_handle`` and the scalars diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst index e1fecbfacd..cbcc0a0269 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spmv.rst @@ -269,10 +269,10 @@ spmv 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 + ``spmv_optimize`` at least once with a given descriptor will throw a :ref:`oneapi::mkl::uninitialized` exception. Calling ``spmv`` with arguments not matching ``spmv_optimize`` - will throw an + will throw a :ref:`oneapi::mkl::invalid_argument` exception, unless stated otherwise. - The data of the dense handles ``x_handle`` and ``y_handle`` and the scalars diff --git a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst index 0751647ace..146088b633 100644 --- a/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst +++ b/source/elements/oneMKL/source/domains/spblas/operations/spsv.rst @@ -260,10 +260,10 @@ spsv 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 + ``spsv_optimize`` at least once with a given descriptor will throw a :ref:`oneapi::mkl::uninitialized` exception. Calling ``spsv`` with arguments not matching ``spsv_optimize`` - will throw an + will throw a :ref:`oneapi::mkl::invalid_argument` exception, unless stated otherwise. - The data of the dense handle ``x_handle`` and scalar ``alpha`` can be reset