[oneMKL][spblas] Add sorted_by_rows property (#583)

* [oneMKL][spblas] Add sorted_by_rows property

* Avoid new lines in table

* an -> a

* Reword description

Author: Rbiessy

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<onemkl_exception_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
 -------------------

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<onemkl_exception_uninitialized>`
      exception. Calling ``spmm`` with arguments not matching ``spmm_optimize``
-     will throw an
+     will throw a
      :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

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<onemkl_exception_uninitialized>`
      exception. Calling ``spmv`` with arguments not matching ``spmv_optimize``
-     will throw an
+     will throw a
      :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

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<onemkl_exception_uninitialized>`
      exception. Calling ``spsv`` with arguments not matching ``spsv_optimize``
-     will throw an
+     will throw a
      :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