diff --git a/source/elements/oneMKL/source/domains/spblas/gemm.rst b/source/elements/oneMKL/source/domains/spblas/gemm.rst index 908600e46f..43dd0b0c48 100644 --- a/source/elements/oneMKL/source/domains/spblas/gemm.rst +++ b/source/elements/oneMKL/source/domains/spblas/gemm.rst @@ -191,7 +191,7 @@ gemm (USM version) const std::int64_t columns, const std::int64_t ldb, const fp beta, - const fp *C, + fp *C, const std::int64_t ldc, const std::vector &dependencies = {}); diff --git a/source/elements/oneMKL/source/domains/spblas/gemv.rst b/source/elements/oneMKL/source/domains/spblas/gemv.rst index 7284ff19ba..3bf93089ce 100644 --- a/source/elements/oneMKL/source/domains/spblas/gemv.rst +++ b/source/elements/oneMKL/source/domains/spblas/gemv.rst @@ -126,7 +126,7 @@ gemv (USM version) oneapi::mkl::sparse::matrix_handle_t A_handle, const fp *x, const fp beta, - const fp *y, + fp *y, const std::vector &dependencies = {}); } diff --git a/source/elements/oneMKL/source/domains/spblas/gemvoptimize.rst b/source/elements/oneMKL/source/domains/spblas/gemvoptimize.rst index 9c3a9570d6..a9b2b64a79 100644 --- a/source/elements/oneMKL/source/domains/spblas/gemvoptimize.rst +++ b/source/elements/oneMKL/source/domains/spblas/gemvoptimize.rst @@ -17,65 +17,6 @@ and performs optimizations. Optimized data is then stored in the handle. -.. _onemkl_sparse_optimize_gemv_buffer: - -optimize_gemv (Buffer version) ------------------------------- - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - void optimize_gemv (sycl::queue &queue, - oneapi::mkl::transpose transpose_val, - oneapi::mkl::sparse::matrix_handle_t handle); - - } - -.. container:: section - - .. rubric:: Input Parameters - - queue - Specifies the SYCL command queue which will be used for SYCL - kernels execution. - - - transpose_val - Specifies operation ``op()`` on input matrix. The possible options - are described in :ref:`onemkl_enum_transpose` enum class. - - - handle - Handle to object containing sparse matrix and other internal - data. Created using the - oneapi::mkl::sparse::set_csr_data 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` - -.. _onemkl_sparse_optimize_gemv_usm: - -optimize_gemv (USM version) ---------------------------- - .. rubric:: Syntax .. code-block:: cpp @@ -85,7 +26,7 @@ optimize_gemv (USM version) sycl::event optimize_gemv (sycl::queue &queue, oneapi::mkl::transpose transpose_val, oneapi::mkl::sparse::matrix_handle_t handle, - std::vector &dependencies); + const std::vector &dependencies = {}); } @@ -113,6 +54,14 @@ optimize_gemv (USM version) List of events that oneapi::mkl::sparse::optimize_gemv 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 diff --git a/source/elements/oneMKL/source/domains/spblas/matrixinit.rst b/source/elements/oneMKL/source/domains/spblas/matrixinit.rst index ca6493d216..5c8d134099 100644 --- a/source/elements/oneMKL/source/domains/spblas/matrixinit.rst +++ b/source/elements/oneMKL/source/domains/spblas/matrixinit.rst @@ -24,10 +24,29 @@ The oneapi::mkl::sparse::init_matrix_handle function initializes the namespace oneapi::mkl::sparse { - void init_matrix_handle (oneapi::mkl::sparse::matrix_handle_t *handle); + void init_matrix_handle (oneapi::mkl::sparse::matrix_handle_t *p_handle); } + +.. container:: section + + .. rubric:: Input parameters + + p_handle + The address of the sparse::matrix_handle_t ``p_handle`` object to be initialized. + This initialization routine must only be called on an uninitialized matrix_handle_t object. + + +.. container:: section + + .. rubric:: Output parameters + + p_handle + On return, the address is updated to point to a newly allocated and initialized matrix_handle_t object + that can be filled and used to perform sparse BLAS operations. + + .. container:: section .. rubric:: Throws @@ -50,4 +69,4 @@ The oneapi::mkl::sparse::init_matrix_handle function initializes the .. container:: parentlink - **Parent topic:** :ref:`onemkl_spblas` \ No newline at end of file + **Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/releasematrixhandle.rst b/source/elements/oneMKL/source/domains/spblas/releasematrixhandle.rst index 9026ae1565..fe7bd05921 100644 --- a/source/elements/oneMKL/source/domains/spblas/releasematrixhandle.rst +++ b/source/elements/oneMKL/source/domains/spblas/releasematrixhandle.rst @@ -26,26 +26,43 @@ before releasing any data in case of USM. namespace oneapi::mkl::sparse { - void release_matrix_handle (oneapi::mkl::sparse::matrix_handle_t handle, - const std::vector &dependencies = {}); + sycl::event release_matrix_handle (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t *p_handle, + const std::vector &dependencies = {}); } .. container:: section - .. rubric:: Input parameter + .. rubric:: Input parameters + queue + The SYCL command queue which will be used for SYCL kernels execution. - handle - Handle to object containing sparse matrix and other internal - data. Created using one of the + p_handle + The address of the sparse::matrix_handle_t ``p_handle`` object to be released, containing sparse matrix and other internal + data. Initialized with oneapi::mkl::sparse::init_matrix_handle routine, and filled with user data using one of the oneapi::mkl::sparse::set__structure routines. dependencies - List of events that ``handle`` depends on. - The call waits on the events(if any) before resetting the ``handle`` to default values. + List of events that ``p_handle`` depends on. + The call waits on the events(if any) before resetting the ``p_handle`` to default values. +.. container:: section + + .. rubric:: Output parameters + + p_handle + The address of the sparse::matrix_handle_t ``p_handle`` that will be scheduled to be updated to point to a null object + and the passed in handle will be scheduled for deallocation and cleanup. + +.. container:: section + + .. rubric:: Return Values + + sycl::event + SYCL event which can be waited upon or added as a dependency for the completion of the deallocation and cleanup routines. .. container:: section diff --git a/source/elements/oneMKL/source/domains/spblas/setcsrstructure.rst b/source/elements/oneMKL/source/domains/spblas/setcsrstructure.rst index c845dcccaf..d9f4827189 100644 --- a/source/elements/oneMKL/source/domains/spblas/setcsrstructure.rst +++ b/source/elements/oneMKL/source/domains/spblas/setcsrstructure.rst @@ -31,7 +31,8 @@ set_csr_data (Buffer version) namespace oneapi::mkl::sparse { - void set_csr_data (oneapi::mkl::sparse::matrix_handle_t handle, + void set_csr_data (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t handle, intType num_rows, intType num_cols, oneapi::mkl::index_base index, @@ -45,6 +46,9 @@ set_csr_data (Buffer version) .. rubric:: Input Parameters + queue + The SYCL command queue which will be used for SYCL kernel execution. + handle Handle to object containing sparse matrix and other internal data for subsequent DPC++ Sparse BLAS operations. @@ -122,13 +126,15 @@ set_csr_data (USM version) namespace oneapi::mkl::sparse { - void set_csr_data (oneapi::mkl::sparse::matrix_handle_t handle, - intType num_rows, - intType num_cols, - oneapi::mkl::index_base index, - intType *row_ptr, - intType *col_ind, - fp *val); + sycl::event set_csr_data (sycl::queue &queue, + oneapi::mkl::sparse::matrix_handle_t handle, + intType num_rows, + intType num_cols, + oneapi::mkl::index_base index, + intType *row_ptr, + intType *col_ind, + fp *val, + const std::vector &dependencies = {}); } @@ -136,6 +142,9 @@ set_csr_data (USM version) .. rubric:: Input Parameters + queue + The SYCL command queue which will be used for SYCL kernel execution. + handle Handle to object containing sparse matrix and other internal data for subsequent DPC++ Sparse BLAS operations. @@ -173,6 +182,9 @@ set_csr_data (USM version) non-zero elements of the input matrix. Refer to :ref:`onemkl_sparse_csr` format for detailed description of ``val`` + dependencies + A vector of type const std::vector & containing the list of events + that the oneapi::mkl::sparse::set_csr_data routine depends on. .. container:: section @@ -180,10 +192,18 @@ set_csr_data (USM version) :class: sectiontitle -handle - Handle to object containing sparse matrix and other internal - data for subsequent SYCL Sparse BLAS operations. + handle + Handle to object containing sparse matrix and other internal + data for subsequent SYCL Sparse BLAS operations. + +.. container:: section + + .. rubric:: Return Values + :class: sectiontitle + sycl::event + A sycl::event that can be used to track the completion of asynchronous events + that were enqueued during the API call that continue the chain of events from the input dependencies. .. container:: section @@ -208,4 +228,4 @@ handle .. container:: parentlink - **Parent topic:** :ref:`onemkl_spblas` \ No newline at end of file + **Parent topic:** :ref:`onemkl_spblas` diff --git a/source/elements/oneMKL/source/domains/spblas/trmvoptimize.rst b/source/elements/oneMKL/source/domains/spblas/trmvoptimize.rst index b5b6452487..ba152a4957 100644 --- a/source/elements/oneMKL/source/domains/spblas/trmvoptimize.rst +++ b/source/elements/oneMKL/source/domains/spblas/trmvoptimize.rst @@ -17,79 +17,6 @@ and performs optimizations. Optimized data is then stored in the handle. -.. _onemkl_sparse_optimize_trmv_buffer: - -optimize_trmv (Buffer version) ------------------------------- - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - void optimize_trmv (sycl::queue &queue, - oneapi::mkl::uplo uplo_val, - oneapi::mkl::transpose transpose_val, - oneapi::mkl::diag diag_val, - oneapi::mkl::sparse::matrix_handle_t handle); - } - -.. 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. - - - transpose_val - Specifies operation ``op()`` on input matrix. The possible options - are described in :ref:`onemkl_enum_transpose` enum class. - - - diag_val - Specifies if the diagonal is unit or not. The possible options - are described in :ref:`onemkl_enum_diag` enum class. - - - handle - Handle to object containing sparse matrix and other internal - data. Created using the - oneapi::mkl::sparse::set_csr_data 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` - - -.. _onemkl_sparse_optimize_trmv_usm: - -optimize_trmv (USM version) ---------------------------- - .. rubric:: Syntax .. code-block:: cpp @@ -101,7 +28,7 @@ optimize_trmv (USM version) oneapi::mkl::transpose transpose_val, oneapi::mkl::diag diag_val, oneapi::mkl::sparse::matrix_handle_t handle, - std::vector &dependencies); + const std::vector &dependencies = {}); } .. container:: section @@ -140,6 +67,14 @@ optimize_trmv (USM version) List of events that oneapi::mkl::sparse::optimize_trmv 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 diff --git a/source/elements/oneMKL/source/domains/spblas/trsvoptimize.rst b/source/elements/oneMKL/source/domains/spblas/trsvoptimize.rst index 66990cbbbf..2caa41bc7f 100644 --- a/source/elements/oneMKL/source/domains/spblas/trsvoptimize.rst +++ b/source/elements/oneMKL/source/domains/spblas/trsvoptimize.rst @@ -17,78 +17,6 @@ and performs optimizations. Optimized data is then stored in the handle. -.. _onemkl_sparse_optimize_trsv_buffer: - -optimize_trsv (Buffer version) ------------------------------- - -.. rubric:: Syntax - -.. code-block:: cpp - - namespace oneapi::mkl::sparse { - - void optimize_trsv (sycl::queue &queue, - oneapi::mkl::uplo uplo_val, - oneapi::mkl::transpose transpose_val, - oneapi::mkl::diag diag_val, - oneapi::mkl::sparse::matrix_handle_t handle); - } - -.. 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. - - - transpose_val - Specifies operation ``op()`` on input matrix. The possible options - are described in :ref:`onemkl_enum_transpose` enum class. - - - diag_val - Specifies if the diagonal is unit or not. The possible options - are described in :ref:`onemkl_enum_diag` enum class. - - - handle - Handle to object containing sparse matrix and other internal - data. Created using the - oneapi::mkl::sparse::set_csr_data 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` - -.. _onemkl_sparse_optimize_trsv_usm: - -optimize_trmv (USM version) ------------------------------- - .. rubric:: Syntax @@ -101,7 +29,7 @@ optimize_trmv (USM version) oneapi::mkl::transpose transpose_val, oneapi::mkl::diag diag_val, oneapi::mkl::sparse::matrix_handle_t handle, - std::vector &dependencies); + const std::vector &dependencies = {}); } .. container:: section @@ -140,6 +68,14 @@ optimize_trmv (USM version) List of events that oneapi::mkl::sparse::optimize_trsv 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