From de72619c5502a81b74071ac9a732b59a5b3189e5 Mon Sep 17 00:00:00 2001 From: "Bae, Seung-Hee" Date: Fri, 8 Sep 2023 11:58:23 -0700 Subject: [PATCH 1/7] [oneMKL][spblas] add spec for oneapi::mkl::sparse::optimize_gemm() routine. --- .../source/domains/spblas/gemmoptimize.rst | 195 ++++++++++++++++++ .../oneMKL/source/domains/spblas/spblas.rst | 3 + 2 files changed, 198 insertions(+) create mode 100644 source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst diff --git a/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst b/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst new file mode 100644 index 0000000000..82cb316a85 --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst @@ -0,0 +1,195 @@ +.. 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. + + +.. _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 &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` + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::host_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::uninitialized` + | :ref:`oneapi::mkl::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 &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` + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::host_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::uninitialized` + | :ref:`oneapi::mkl::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` diff --git a/source/elements/oneMKL/source/domains/spblas/spblas.rst b/source/elements/oneMKL/source/domains/spblas/spblas.rst index a1e57d7be4..ae88499161 100644 --- a/source/elements/oneMKL/source/domains/spblas/spblas.rst +++ b/source/elements/oneMKL/source/domains/spblas/spblas.rst @@ -31,6 +31,8 @@ Sparse BLAS - 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,6 +58,7 @@ Sparse BLAS releasematrixhandle setcsrstructure gemm + gemmoptimize gemv gemvdot gemvoptimize From 065dec587ed91a67db31726434375cc810b967d5 Mon Sep 17 00:00:00 2001 From: "Bae, Seung-Hee" Date: Fri, 8 Sep 2023 13:45:41 -0700 Subject: [PATCH 2/7] [oneMKL][spblas] add spec for oneapi::mkl::sparse::optimize_symv() routine. --- .../oneMKL/source/domains/spblas/spblas.rst | 3 + .../source/domains/spblas/symvoptimize.rst | 98 +++++++++++++++++++ 2 files changed, 101 insertions(+) create mode 100644 source/elements/oneMKL/source/domains/spblas/symvoptimize.rst diff --git a/source/elements/oneMKL/source/domains/spblas/spblas.rst b/source/elements/oneMKL/source/domains/spblas/spblas.rst index ae88499161..2599cc2bb2 100644 --- a/source/elements/oneMKL/source/domains/spblas/spblas.rst +++ b/source/elements/oneMKL/source/domains/spblas/spblas.rst @@ -27,6 +27,8 @@ 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` @@ -63,6 +65,7 @@ Sparse BLAS gemvdot gemvoptimize symv + symvoptimize trmv trmvoptimize trsv diff --git a/source/elements/oneMKL/source/domains/spblas/symvoptimize.rst b/source/elements/oneMKL/source/domains/spblas/symvoptimize.rst new file mode 100644 index 0000000000..2cbaa6e225 --- /dev/null +++ b/source/elements/oneMKL/source/domains/spblas/symvoptimize.rst @@ -0,0 +1,98 @@ +.. SPDX-FileCopyrightText: 2019-2020 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 &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` + | :ref:`oneapi::mkl::device_bad_alloc` + | :ref:`oneapi::mkl::host_bad_alloc` + | :ref:`oneapi::mkl::invalid_argument` + | :ref:`oneapi::mkl::unimplemented` + | :ref:`oneapi::mkl::uninitialized` + | :ref:`oneapi::mkl::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` From aa2513ef000ddd104fc0afe6a4dc32d95e67aa94 Mon Sep 17 00:00:00 2001 From: "Bae, Seung-Hee" Date: Fri, 8 Sep 2023 13:59:26 -0700 Subject: [PATCH 3/7] minor fix. --- source/elements/oneMKL/source/domains/spblas/symvoptimize.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/elements/oneMKL/source/domains/spblas/symvoptimize.rst b/source/elements/oneMKL/source/domains/spblas/symvoptimize.rst index 2cbaa6e225..13a8f555e5 100644 --- a/source/elements/oneMKL/source/domains/spblas/symvoptimize.rst +++ b/source/elements/oneMKL/source/domains/spblas/symvoptimize.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation +.. SPDX-FileCopyrightText: 2023 Intel Corporation .. .. SPDX-License-Identifier: CC-BY-4.0 From a6dee94f9b393b213d3b60b82f20e0797be522b6 Mon Sep 17 00:00:00 2001 From: "Bae, Seung-Hee" Date: Fri, 8 Sep 2023 15:54:37 -0700 Subject: [PATCH 4/7] [oneMKL][spblas] add explanation of why we propose two versions of optimize_gemm(). --- .../oneMKL/source/domains/spblas/gemmoptimize.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst b/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst index 82cb316a85..ae0211d410 100644 --- a/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst +++ b/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst @@ -16,6 +16,17 @@ 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 only based on Sparse matrix structure, +two version of ``optimize_gemm`` routines are listed here for preparing optimizations +for oneapi::mkl::sparse::gemm routine, +since we might perform optimizations for oneapi::mkl::sparse::gemm +with respect to the shape and layout of the given dense matrix +as well as based on sparse matrix structure only. +If user wants to run multiple times oneapi::mkl::sparse::gemm with the same shape and layout +of input dense matrix :math:`B`, then the latter version of ``optimize_gemm`` routine might +give further performance optimization specific to the input dense matrix as well as +the given sparse matrix. .. _onemkl_sparse_optimize_gemm_A: From fb53d7f7a51f8f29b58a12ba6b1aa55f787a418e Mon Sep 17 00:00:00 2001 From: Spencer Patty Date: Mon, 11 Sep 2023 14:34:56 -0700 Subject: [PATCH 5/7] Update source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst --- .../source/domains/spblas/gemmoptimize.rst | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst b/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst index ae0211d410..1c65523b9b 100644 --- a/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst +++ b/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst @@ -17,16 +17,18 @@ and performs optimizations. Optimized data is then stored in the handle. In contrast to other optimization routines in Sparse BLAS domain, -which are done only based on Sparse matrix structure, -two version of ``optimize_gemm`` routines are listed here for preparing optimizations -for oneapi::mkl::sparse::gemm routine, -since we might perform optimizations for oneapi::mkl::sparse::gemm -with respect to the shape and layout of the given dense matrix -as well as based on sparse matrix structure only. -If user wants to run multiple times oneapi::mkl::sparse::gemm with the same shape and layout -of input dense matrix :math:`B`, then the latter version of ``optimize_gemm`` routine might -give further performance optimization specific to the input dense matrix as well as -the given sparse matrix. +which are done solely based on the sparse matrix pattern, +two versions of ``sparse::optimize_gemm`` routines 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, but 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: From e01599ed95456798c2da0e69f59910635a43de33 Mon Sep 17 00:00:00 2001 From: Spencer Patty Date: Mon, 11 Sep 2023 14:40:43 -0700 Subject: [PATCH 6/7] Apply suggestions from code review --- .../elements/oneMKL/source/domains/spblas/gemmoptimize.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst b/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst index 1c65523b9b..30b4fb2d78 100644 --- a/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst +++ b/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst @@ -16,14 +16,14 @@ 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, +In contrast to other optimization routines in Sparse BLAS domain which are done solely based on the sparse matrix pattern, -two versions of ``sparse::optimize_gemm`` routines are provided for preparing different +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, but if one or more particular shapes of :math:`B` +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 From 64d4b12b18a9bb270093f16603038be265386bfd Mon Sep 17 00:00:00 2001 From: Spencer Patty Date: Mon, 11 Sep 2023 16:46:40 -0700 Subject: [PATCH 7/7] fix whitespace issues --- .../elements/oneMKL/source/domains/spblas/gemmoptimize.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst b/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst index 30b4fb2d78..83a4f3ef6c 100644 --- a/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst +++ b/source/elements/oneMKL/source/domains/spblas/gemmoptimize.rst @@ -19,9 +19,9 @@ 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 +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