Skip to content

Commit

Permalink
[oneMKL][spblas] update the spec for several spblas routines (uxlfoun…
Browse files Browse the repository at this point in the history 
…dation#491)

* update spec for oneapi::mkl::sparse::release_matrix_handle() routine.

* update spec for oneapi::mkl::sparse::set_csr_data() routine.

* fix minor typo in the spec of the oneapi::mkl::sparse::gemm routine.

* fix minor typo in the spec of the oneapi::mkl::sparse::gemv routine.

* update spec for oneapi::mkl::sparse::optimize_gemv() routine.

* update spec for oneapi::mkl::sparse::optimize_trmv() routine.

* update spec for oneapi::mkl::sparse::optimize_trsv() routine.

* rename 'handle' as 'p_handle' for init_matrix_handle and release_matrix_handle routines.

* add missing 'const' keyword for dependencies list.
  • Loading branch information
@baeseung-intel @aepanchi
baeseung-intel authored and aepanchi committed Oct 31, 2023
1 parent 5ee4d46 commit e733fd3
Show file tree
Hide file tree
Showing 8 changed files with 107 additions and 231 deletions.
2 changes: 1 addition & 1 deletion source/elements/oneMKL/source/domains/spblas/gemm.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<sycl::event> &dependencies = {});
Expand Down
2 changes: 1 addition & 1 deletion source/elements/oneMKL/source/domains/spblas/gemv.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<sycl::event> &dependencies = {});
}
Expand Down
69 changes: 9 additions & 60 deletions source/elements/oneMKL/source/domains/spblas/gemvoptimize.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<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>`
.. _onemkl_sparse_optimize_gemv_usm:

optimize_gemv (USM version)
---------------------------

.. rubric:: Syntax

.. code-block:: cpp
Expand All @@ -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<sycl::event> &dependencies);
const std::vector<sycl::event> &dependencies = {});
}
Expand Down Expand Up @@ -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
Expand Down
23 changes: 21 additions & 2 deletions source/elements/oneMKL/source/domains/spblas/matrixinit.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -50,4 +69,4 @@ The oneapi::mkl::sparse::init_matrix_handle function initializes the
.. container:: parentlink


**Parent topic:** :ref:`onemkl_spblas`
**Parent topic:** :ref:`onemkl_spblas`
33 changes: 25 additions & 8 deletions source/elements/oneMKL/source/domains/spblas/releasematrixhandle.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<sycl::event> &dependencies = {});
sycl::event release_matrix_handle (sycl::queue &queue,
oneapi::mkl::sparse::matrix_handle_t *p_handle,
const std::vector<sycl::event> &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_<sparse_matrix_type>_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

Expand Down
44 changes: 32 additions & 12 deletions source/elements/oneMKL/source/domains/spblas/setcsrstructure.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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.
Expand Down Expand Up @@ -122,20 +126,25 @@ 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<sycl::event> &dependencies = {});
}
.. container:: section

.. 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.
Expand Down Expand Up @@ -173,17 +182,28 @@ 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<sycl::event> & containing the list of events
that the oneapi::mkl::sparse::set_csr_data routine depends on.

.. container:: section

.. rubric:: Output Parameters
: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

Expand All @@ -208,4 +228,4 @@ handle
.. container:: parentlink


**Parent topic:** :ref:`onemkl_spblas`
**Parent topic:** :ref:`onemkl_spblas`
83 changes: 9 additions & 74 deletions source/elements/oneMKL/source/domains/spblas/trmvoptimize.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<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>`

.. _onemkl_sparse_optimize_trmv_usm:

optimize_trmv (USM version)
---------------------------

.. rubric:: Syntax

.. code-block:: cpp
Expand All @@ -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<sycl::event> &dependencies);
const std::vector<sycl::event> &dependencies = {});
}
.. container:: section
Expand Down Expand Up @@ -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
Expand Down
Loading

0 comments on commit e733fd3

Please sign in to comment.