From 45ef35474b5928ce96d82b35e22a6d53c8497baa Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Mon, 23 Sep 2024 15:10:53 +0200 Subject: [PATCH 1/4] [oneMKL][spblas] Add sorted_by_rows property --- .../spblas/data_types/set_matrix_property.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) 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..ad7288e6eb 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, }; } @@ -39,12 +40,20 @@ Matrix properties 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. + - | Guarantees that the user-provided matrix data is fully sorted. | 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. + * - ``sorted_by_rows`` + - | Guarantees that the user-provided matrix data is partially sorted. + Has no effect if the property ``sorted`` is set. + | For COO this guarantees that the indices are sorted by row in + ascending order. The column indices within a row do not need to be + sorted. + | Setting this property for a matrix using the CSR format will throw an + :ref:`oneapi::mkl::invalid_argument` + exception. set_matrix_property ------------------- From 8ed9c907ceada0efbfae097919885cd0774bec95 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Thu, 26 Sep 2024 17:48:04 +0200 Subject: [PATCH 2/4] Avoid new lines in table --- .../spblas/data_types/set_matrix_property.rst | 60 ++++++++++++------- 1 file changed, 40 insertions(+), 20 deletions(-) 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 ad7288e6eb..54cdf9a1de 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 @@ -29,31 +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 row then by column 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 is fully sorted. - | 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. - * - ``sorted_by_rows`` - - | Guarantees that the user-provided matrix data is partially sorted. - Has no effect if the property ``sorted`` is set. - | For COO this guarantees that the indices are sorted by row in - ascending order. The column indices within a row do not need to be - sorted. - | Setting this property for a matrix using the CSR format will throw an - :ref:`oneapi::mkl::invalid_argument` - exception. + * - CSR + - Setting this property for a matrix using the CSR format will throw an + :ref:`oneapi::mkl::invalid_argument` + exception. + * - COO + - Guarantees that the indices are sorted by row in ascending order. + The column indices within a row do not need to be sorted. set_matrix_property ------------------- From c7da10f055aa7a338ab1c4f1ccb3d2e853235003 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Mon, 30 Sep 2024 17:39:26 +0200 Subject: [PATCH 3/4] an -> a --- .../source/domains/spblas/data_types/set_matrix_property.rst | 2 +- .../elements/oneMKL/source/domains/spblas/operations/spmm.rst | 4 ++-- .../elements/oneMKL/source/domains/spblas/operations/spmv.rst | 4 ++-- .../elements/oneMKL/source/domains/spblas/operations/spsv.rst | 4 ++-- 4 files changed, 7 insertions(+), 7 deletions(-) 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 54cdf9a1de..5d6bcecebd 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 @@ -68,7 +68,7 @@ details the property for each matrix format: * - Matrix format - Description * - CSR - - Setting this property for a matrix using the CSR format will throw an + - Setting this property for a matrix using the CSR format will throw a :ref:`oneapi::mkl::invalid_argument` exception. * - COO 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 From eef74a30ab15edbfed9e1d470913aec66ec23903 Mon Sep 17 00:00:00 2001 From: "romain.biessy" Date: Tue, 8 Oct 2024 16:33:51 +0200 Subject: [PATCH 4/4] Reword description --- .../domains/spblas/data_types/set_matrix_property.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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 5d6bcecebd..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 @@ -52,8 +52,8 @@ details the property for each matrix format: - Guarantees that the column indices are sorted in ascending order for a given row. * - COO - - Guarantees that the indices are sorted by row then by column in - ascending order. + - Guarantees that the indices are sorted by rows then by columns within + rows in ascending order. sorted_by_rows ^^^^^^^^^^^^^^ @@ -72,7 +72,7 @@ details the property for each matrix format: :ref:`oneapi::mkl::invalid_argument` exception. * - COO - - Guarantees that the indices are sorted by row in ascending order. + - 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