[oneMKL][spblas] Add optimize_symv() and optimize_gemm() routines…

… in oneMKL specification. (#499)

* [oneMKL][spblas] add spec for oneapi::mkl::sparse::optimize_gemm() routine.

* [oneMKL][spblas] add spec for oneapi::mkl::sparse::optimize_symv() routine.

* minor fix.

* [oneMKL][spblas] add explanation of why we propose two versions of optimize_gemm().

* Update source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst

* Apply suggestions from code review

* fix whitespace issues

---------

Co-authored-by: Spencer Patty <spencer.patty@intel.com>

source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst

@@ -0,0 +1,208 @@
+.. SPDX-FileCopyrightText: 2023 Intel Corporation
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+.. _onemkl_sparse_optimize_gemm:
+
+optimize_gemm
+=============
+
+Performs internal optimizations for oneapi::mkl::sparse::gemm by analyzing
+the matrix structure.
+
+.. rubric:: Description and Assumptions
+
+The oneapi::mkl::sparse::optimize_gemm routine analyzes matrix structure
+and performs optimizations. Optimized data is then stored in
+the handle.
+
+In contrast to other optimization routines in Sparse BLAS domain
+which are done solely based on the sparse matrix pattern, 
+two versions of the ``sparse::optimize_gemm`` routine are provided for preparing different
+optimizations for ``sparse::gemm`` routine.  In particular, if the shape
+of the dense matrix right hand side, :math:`B`, is unknown or widely varying in 
+subsequent calls to ``sparse::gemm`` then a user might reasonably
+only wish to perform optimizations for ``:sparse::gemm`` with respect 
+to the sparse matrix structure.  However, if one or more particular shapes of :math:`B` 
+is available, then each :math:`B` shape can be provided as an additional hint 
+along with the sparse matrix pattern in the call to ``sparse::optimize_gemm``.  This 
+second version of the API with :math:`B` shape should be callable one or 
+more times and may allow libraries to provide more targeted performance 
+optimizations.
+
+.. _onemkl_sparse_optimize_gemm_A:
+
+optimize_gemm (based on Sparse Matrix)
+--------------------------------------
+
+.. rubric:: Syntax
+
+.. code-block:: cpp
+
+   namespace oneapi::mkl::sparse {
+
+      sycl::event optimize_gemm (sycl::queue                          &queue,
+                                 oneapi::mkl::transpose               transpose_A,
+                                 oneapi::mkl::sparse::matrix_handle_t A_handle,
+                                 const std::vector<sycl::event>       &dependencies = {});
+
+   }
+
+.. container:: section
+
+    .. rubric:: Input Parameters
+
+    queue
+         Specifies the SYCL command queue which will be used for SYCL
+         kernels execution.
+
+
+    transpose_A
+         Specifies operation ``op()`` on input matrix :math:`A`. The possible options
+         are described in :ref:`onemkl_enum_transpose` enum class.
+
+
+    A_handle
+       Handle to object containing sparse matrix and other internal
+       data. Created using the
+       oneapi::mkl::sparse::set_csr_data routine.
+
+
+    dependencies
+       List of events that oneapi::mkl::sparse::optimize_gemm routine depends on.
+
+
+.. container:: section
+
+    .. rubric:: Output Parameters
+         :class: sectiontitle
+
+    handle
+        Handle might be updated with some internal optimized data by this routine.
+
+.. container:: section
+
+    .. rubric:: Throws
+         :class: sectiontitle
+
+    This routine shall throw the following exceptions if the associated condition is detected.
+    An implementation may throw additional implementation-specific exception(s)
+    in case of error conditions not covered here.
+
+    | :ref:`oneapi::mkl::computation_error<onemkl_exception_computation_error>`
+    | :ref:`oneapi::mkl::device_bad_alloc<onemkl_exception_device_bad_alloc>`
+    | :ref:`oneapi::mkl::host_bad_alloc<onemkl_exception_host_bad_alloc>`
+    | :ref:`oneapi::mkl::invalid_argument<onemkl_exception_invalid_argument>`
+    | :ref:`oneapi::mkl::unimplemented<onemkl_exception_unimplemented>`
+    | :ref:`oneapi::mkl::uninitialized<onemkl_exception_uninitialized>`
+    | :ref:`oneapi::mkl::unsupported_device<onemkl_exception_unsupported_device>`
+
+.. container:: section
+
+    .. rubric:: Return Values
+       :class: sectiontitle
+
+    Output event that can be waited upon or added as a
+    dependency for the completion of optimize_gemm routine.
+
+
+.. _onemkl_sparse_optimize_gemm_AB:
+
+optimize_gemm (based on Both Input Matrices)
+--------------------------------------------
+
+.. rubric:: Syntax
+
+.. code-block:: cpp
+
+   namespace oneapi::mkl::sparse {
+
+      sycl::event optimize_gemm (sycl::queue                          &queue,
+                                 oneapi::mkl::transpose               transpose_A,
+                                 oneapi::mkl::transpose               transpose_B,
+                                 oneapi::mkl::layout                  dense_matrix_layout,
+                                 const std::int64_t                   columns,
+                                 oneapi::mkl::sparse::matrix_handle_t A_handle,
+                                 const std::vector<sycl::event>       &dependencies = {});
+
+   }
+
+.. container:: section
+
+    .. rubric:: Input Parameters
+
+    queue
+         Specifies the SYCL command queue which will be used for SYCL
+         kernels execution.
+
+
+    transpose_A
+         Specifies operation ``op()`` on input matrix :math:`A`. The possible options
+         are described in :ref:`onemkl_enum_transpose` enum class.
+
+
+    transpose_B
+         Specifies operation ``op()`` on input matrix :math:`B`. The possible options
+         are described in :ref:`onemkl_enum_transpose` enum class.
+
+
+    dense_matrix_layout
+         Specifies the storage scheme in memory for the dense matrices. Note that this layout applies to both :math:`B` and :math:`C` dense matrices.
+         The possible options are described in :ref:`onemkl_enum_layout` enum class.
+
+
+    columns
+         Number of columns of matrix :math:`C`.
+
+
+    handle
+       Handle to object containing sparse matrix and other internal
+       data. Created using the
+       oneapi::mkl::sparse::set_csr_data routine.
+
+
+    dependencies
+       List of events that oneapi::mkl::sparse::optimize_gemm routine depends on.
+
+
+.. container:: section
+
+    .. rubric:: Output Parameters
+         :class: sectiontitle
+
+    handle
+        Handle might be updated with some internal optimized data by this routine.
+
+.. container:: section
+
+    .. rubric:: Throws
+         :class: sectiontitle
+
+    This routine shall throw the following exceptions if the associated condition is detected.
+    An implementation may throw additional implementation-specific exception(s)
+    in case of error conditions not covered here.
+
+    | :ref:`oneapi::mkl::computation_error<onemkl_exception_computation_error>`
+    | :ref:`oneapi::mkl::device_bad_alloc<onemkl_exception_device_bad_alloc>`
+    | :ref:`oneapi::mkl::host_bad_alloc<onemkl_exception_host_bad_alloc>`
+    | :ref:`oneapi::mkl::invalid_argument<onemkl_exception_invalid_argument>`
+    | :ref:`oneapi::mkl::unimplemented<onemkl_exception_unimplemented>`
+    | :ref:`oneapi::mkl::uninitialized<onemkl_exception_uninitialized>`
+    | :ref:`oneapi::mkl::unsupported_device<onemkl_exception_unsupported_device>`
+
+.. container:: section
+
+    .. rubric:: Return Values
+       :class: sectiontitle
+
+    Output event that can be waited upon or added as a
+    dependency for the completion of optimize_gemm routine.
+
+
+.. container:: familylinks
+
+
+   .. container:: parentlink
+
+
+      **Parent topic:** :ref:`onemkl_spblas`

source/elements/oneMKL/source/domains/spblas/spblas.rst

@@ -27,10 +27,14 @@ Sparse BLAS
            -     Fills the internal CSR data structure
          * -     :ref:`onemkl_sparse_optimize_gemv`
            -     Optimize routine for gemv
+         * -     :ref:`onemkl_sparse_optimize_symv`
+           -     Optimize routine for symv
          * -     :ref:`onemkl_sparse_optimize_trmv`
            -     Optimize routine for trmv
          * -     :ref:`onemkl_sparse_optimize_trsv`
            -     Optimize routine for trsv
+         * -     :ref:`onemkl_sparse_optimize_gemm`
+           -     Optimize routine for gemm
          * -     :ref:`onemkl_sparse_gemv`
            -     Sparse matrix-dense vector product using a general sparse matrix
          * -     :ref:`onemkl_sparse_gemvdot`
@@ -56,10 +60,12 @@ Sparse BLAS
     releasematrixhandle
     setcsrstructure
     gemm
+    gemmoptimize
     gemv
     gemvdot
     gemvoptimize
     symv
+    symvoptimize
     trmv
     trmvoptimize
     trsv

source/elements/oneMKL/source/domains/spblas/symvoptimize.rst

@@ -0,0 +1,98 @@
+.. SPDX-FileCopyrightText: 2023 Intel Corporation
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+.. _onemkl_sparse_optimize_symv:
+
+optimize_symv
+=============
+
+Performs internal optimizations for oneapi::mkl::sparse::symv by analyzing
+the matrix structure.
+
+.. rubric:: Description and Assumptions
+
+The oneapi::mkl::sparse::optimize_symv routine analyzes matrix structure
+and performs optimizations. Optimized data is then stored in
+the handle.
+
+
+.. rubric:: Syntax
+
+.. code-block:: cpp
+
+   namespace oneapi::mkl::sparse {
+
+      sycl::event optimize_symv (sycl::queue                          &queue,
+                                 oneapi::mkl::uplo                    uplo_val,
+                                 oneapi::mkl::sparse::matrix_handle_t handle,
+                                 const std::vector<sycl::event>       &dependencies = {});
+   }
+
+.. container:: section
+
+
+   .. rubric:: Input Parameters
+
+
+   queue
+        Specifies the SYCL command queue which will be used for SYCL
+        kernels execution.
+
+
+   uplo_val
+        Specifies which part is to be processed. The possible options are
+        described in :ref:`onemkl_enum_uplo` enum class.
+
+
+   handle
+      Handle to object containing sparse matrix and other internal
+      data. Created using the
+      oneapi::mkl::sparse::set_csr_data routine.
+
+
+   dependencies
+       List of events that oneapi::mkl::sparse::optimize_symv routine depends on.
+
+
+.. container:: section
+
+    .. rubric:: Output Parameters
+         :class: sectiontitle
+
+    handle
+        Handle might be updated with some internal optimized data by this routine.
+
+.. container:: section
+
+    .. rubric:: Throws
+       :class: sectiontitle
+
+    This routine shall throw the following exceptions if the associated condition is detected.
+    An implementation may throw additional implementation-specific exception(s)
+    in case of error conditions not covered here.
+
+    | :ref:`oneapi::mkl::computation_error<onemkl_exception_computation_error>`
+    | :ref:`oneapi::mkl::device_bad_alloc<onemkl_exception_device_bad_alloc>`
+    | :ref:`oneapi::mkl::host_bad_alloc<onemkl_exception_host_bad_alloc>`
+    | :ref:`oneapi::mkl::invalid_argument<onemkl_exception_invalid_argument>`
+    | :ref:`oneapi::mkl::unimplemented<onemkl_exception_unimplemented>`
+    | :ref:`oneapi::mkl::uninitialized<onemkl_exception_uninitialized>`
+    | :ref:`oneapi::mkl::unsupported_device<onemkl_exception_unsupported_device>`
+
+.. container:: section
+
+    .. rubric:: Return Values
+       :class: sectiontitle
+
+    Output event that can be waited upon or added as a
+    dependency for the completion of optimize_symv routine.
+
+
+.. container:: familylinks
+
+
+   .. container:: parentlink
+
+
+      **Parent topic:** :ref:`onemkl_spblas`